mandrel 2.4.0 → 2.6.0

package/.agents/scripts/lib/findings/route-finding.js

@@ -32,7 +32,12 @@ import crypto from 'node:crypto';
 
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
+const SEMANTIC_MARKER = 'audit-semantic-keys:';
 const SHA1_RE = /^[0-9a-f]{40}$/;
+// A semantic key round-trips through a comma-joined footer, so it must not
+// carry a comma or a `>` (which would truncate the HTML comment). Both are
+// stripped when the key is built, so this guard is defence-in-depth.
+const SEMANTIC_KEY_RE = /^[^,>]+$/;
 
 /**
  * Normalise a single scalar identity field to a stable string.
@@ -92,6 +97,67 @@ export function fingerprintFinding(finding) {
   return { short: full.slice(0, 12), full, components };
 }
 
+/**
+ * Compute the **location-based semantic key** for a finding. Unlike the
+ * fingerprint (which folds in the title, so any prose rewording mints a fresh
+ * sha), the semantic key is stable across a reworded title and a re-severitied
+ * finding: it is derived solely from the finding's identity *location* —
+ * `area` (the audit dimension) plus `primaryFile`. Two scans that describe the
+ * same problem at the same location produce the same semantic key even when
+ * their titles diverge, so a reworded finding still confirms against the Issue
+ * that already tracks that location.
+ *
+ * Returns the empty string when the location is unknown (no `area` and no
+ * `primaryFile`) — an empty key never confirms a match, exactly as an absent
+ * fingerprint footer never does.
+ *
+ * @param {object} finding — canonical finding ({ area, primaryFile, ... }).
+ * @returns {string}
+ */
+export function semanticKeyFor(finding) {
+  const area = normaliseField(finding?.area);
+  const primaryFile = normaliseField(finding?.primaryFile);
+  if (!area && !primaryFile) return '';
+  const key = `${area}${SEP}${primaryFile}`;
+  return SEMANTIC_KEY_RE.test(key) ? key : key.replace(/[,>]/g, ' ').trim();
+}
+
+/**
+ * Render the machine-readable semantic-key footer for one or more keys
+ * (`<!-- audit-semantic-keys: key,key,... -->`). Stamped alongside the
+ * fingerprint footer by the audit filers so a later reworded finding can
+ * confirm identity by location when its fingerprint has drifted. Round-trips
+ * through {@link parseSemanticKeyFooter}. Empty keys are dropped.
+ *
+ * @param {string | string[]} keys — one semantic key or an array of them.
+ * @returns {string}
+ */
+export function semanticKeyFooter(keys) {
+  const list = (Array.isArray(keys) ? keys : [keys])
+    .filter((k) => typeof k === 'string' && k.length > 0)
+    .map((k) => k.replace(/[,>]/g, ' ').trim())
+    .filter((k) => k.length > 0);
+  return `<!-- ${SEMANTIC_MARKER} ${list.join(',')} -->`;
+}
+
+/**
+ * Extract semantic keys from an Issue body carrying the semantic-key footer.
+ * Internal — the audit filers stamp the footer via {@link semanticKeyFooter};
+ * only the confirmation path here reads it back.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+function parseSemanticKeyFooter(body) {
+  if (typeof body !== 'string') return [];
+  const match = body.match(/<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 /**
  * Render the machine-readable fingerprint footer for one or more shas.
  *
@@ -147,6 +213,21 @@ function issueCarriesFingerprint(issue, sha) {
   return parseFingerprintFooter(issue.body).includes(sha);
 }
 
+/**
+ * Confirm an issue body's footer carries the target semantic key. Unlike
+ * {@link issueCarriesFingerprint}, this is strict on a missing body — a
+ * location match is only meaningful when the issue actually carries a
+ * semantic-key footer to compare against.
+ *
+ * @param {{ body?: string }} issue
+ * @param {string} key
+ * @returns {boolean}
+ */
+function issueCarriesSemanticKey(issue, key) {
+  if (!key || typeof issue?.body !== 'string') return false;
+  return parseSemanticKeyFooter(issue.body).includes(key);
+}
+
 /**
  * Decide the route decision from a confirmed matched issue's state.
  * @param {{ state?: string }} issue
@@ -194,23 +275,29 @@ function decideFromConfirmed(confirmed, sha) {
 }
 
 /**
- * Keep only the issue records that have the right wire shape AND carry the
- * target fingerprint in their footer. A semantic candidate that merely *looks*
- * similar but does not carry the sha is dropped here — semantic similarity
- * widens the net; the fingerprint footer is what confirms identity.
+ * Keep only the issue records that have the right wire shape AND carry a
+ * confirming footer. Confirmation is by the exact **fingerprint** footer and,
+ * when a `semanticKey` is supplied (audit dedup opts in via
+ * `options.semanticKeyConfirm`), ALSO by the location-based **semantic-key**
+ * footer. A semantic candidate that merely *looks* similar but carries neither
+ * footer is dropped here — semantic similarity widens the net; a deterministic
+ * footer (fingerprint or semantic key) is what confirms identity. The semantic
+ * key catches a reworded finding whose fingerprint has drifted but whose
+ * location is unchanged.
  *
  * @param {Array<unknown>} hits
- * @param {string} sha
+ * @param {{ sha: string, semanticKey?: string }} identity
  * @returns {Array<{ number: number, state: string }>}
  */
-function confirmFingerprint(hits, sha) {
+function confirmCandidates(hits, { sha, semanticKey = '' }) {
   if (!Array.isArray(hits)) return [];
   return hits.filter(
     (h) =>
       h &&
       typeof h.number === 'number' &&
       typeof h.state === 'string' &&
-      issueCarriesFingerprint(h, sha),
+      (issueCarriesFingerprint(h, sha) ||
+        issueCarriesSemanticKey(h, semanticKey)),
   );
 }
 
@@ -245,11 +332,18 @@ function confirmFingerprint(hits, sha) {
  *   Meaning-first candidate search over open+closed issues (and Epic
  *   sub-issues). When supplied, runs FIRST; its candidates are then
  *   fingerprint-confirmed.
+ * @param {object} [options]
+ * @param {boolean} [options.semanticKeyConfirm=false] — also confirm a
+ *   candidate by the location-based semantic-key footer, not the fingerprint
+ *   alone. Opt-in so the audit dedup path catches a reworded finding at an
+ *   unchanged location while the qa-explore path (which does not stamp
+ *   semantic-key footers) stays fingerprint-exact and byte-identical.
  * @returns {Promise<{ decision: 'new'|'update-existing'|'duplicate'|'regression-of-closed', matchedIssue: object|null, fingerprint: string }>}
  */
 export async function routeFinding(
   finding,
   { searchIssues, searchCandidates } = {},
+  options = {},
 ) {
   if (
     typeof searchCandidates !== 'function' &&
@@ -261,6 +355,7 @@ export async function routeFinding(
   }
 
   const { full: sha } = fingerprintFinding(finding);
+  const semanticKey = options.semanticKeyConfirm ? semanticKeyFor(finding) : '';
 
   // Stage 1: semantic candidate pass first (when wired); else fingerprint
   // lookup. Both yield a candidate pool drawn from open AND closed issues.
@@ -269,15 +364,18 @@ export async function routeFinding(
       ? await searchCandidates(finding)
       : await searchIssues(sha);
 
-  // Stage 2: confirm identity by fingerprint footer over the candidate pool.
-  const confirmed = confirmFingerprint(hits, sha);
+  // Stage 2: confirm identity by fingerprint footer (and, when opted in, the
+  // location-based semantic-key footer) over the candidate pool.
+  const confirmed = confirmCandidates(hits, { sha, semanticKey });
 
   return decideFromConfirmed(confirmed, sha);
 }
 
 export const __testing = {
   MARKER,
+  SEMANTIC_MARKER,
   SEP,
-  confirmFingerprint,
+  confirmCandidates,
   decideFromConfirmed,
+  issueCarriesSemanticKey,
 };

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,150 @@ export async function emitBlockRecoveredFriction({
 }
 
 /**
- * Pure predicate: is this signal a recovery-marked `story-blocked` record?
+ * 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).
+ *
+ * **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.
+ *
+ * **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.
+ *
+ * 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
+ * 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
+ * stays counted) rather than a speculative write.
+ *
+ * @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 } = {}) {
+  const sid = positiveIntOrNull(storyId);
+  if (sid === null) return false;
+
+  let failed = false;
+  let recovered = false;
+  try {
+    await forEachLine(
+      null,
+      sid,
+      (parsed) => {
+        if (!parsed || typeof parsed !== 'object') return;
+        if (parsed.category !== RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED) {
+          return;
+        }
+        if (isRecoveredSignal(parsed)) recovered = true;
+        else failed = true;
+      },
+      config,
+    );
+  } catch (err) {
+    Logger.warn(
+      `[runtime-friction] close-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;
+
+  return emitRuntimeFriction({
+    storyId: sid,
+    category: RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED,
+    tool: 'runPostLandTail',
+    details: { recovered: true },
+    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

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,7 @@ 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 { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import {
   executeFastForward as defaultExecuteFastForward,
@@ -250,6 +251,7 @@ 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.reassertStatusColumnFn]  Test seam.
  * @param {Function} [args.gitSpawnFn]              Test seam.
  * @param {Function} [args.planFastForwardFn]       Test seam.
@@ -266,6 +268,7 @@ export async function runPostLandTail({
   config,
   progress,
   captureStoryFollowUpsFn = defaultCaptureStoryFollowUps,
+  emitCloseRecoveredFrictionFn = defaultEmitCloseRecoveredFriction,
   reassertStatusColumnFn = defaultReassertStatusColumn,
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
@@ -274,6 +277,14 @@ 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
+  // 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.
+  await emitCloseRecoveredFrictionFn({ storyId, config });
+
   const followUps = await step(
     () =>
       stepFollowUps({

package/.agents/scripts/lib/orchestration/story-close/phases/local-lens-review.js

@@ -30,6 +30,58 @@ import { computeChangeSet } from '../../change-set.js';
  */
 const STORY_SCOPE_LENS_DEPTH = 'light';
 
+/**
+ * Render the host-MUST-walk roster of materialized lens-prompt artifacts
+ * (Story #4627). The Story-scope lens pass materializes each matched lens's
+ * substituted prompt body to a scoped artifact file; the default review
+ * provider is a mechanical sweep that never reads them, so the artifacts are
+ * inert unless the close's stdout tells the host to walk them. This mirrors
+ * the plan-run audit-roster comment's "host MUST walk each" contract
+ * (`run-epilogue.js`): the close names each artifact path and the host reads
+ * each one against the diff.
+ *
+ * Pure: derives the block from the `runAuditSuite` envelope's `workflows[]`,
+ * keeping only entries that actually wrote an artifact. Returns `null` when no
+ * artifact was written (nothing to walk), so the caller emits nothing.
+ *
+ * Module-local: an implementation detail of {@link runLocalLensReview}, whose
+ * host-MUST-walk output rides out on the `progress` stream. Exercised through
+ * that public entry point (assert the progress lines name each artifact path)
+ * rather than imported directly, so it adds no production-dead public export.
+ *
+ * @param {object|null} materialized the `runAuditSuite` result envelope.
+ * @returns {string|null} the roster block, or `null` when there is nothing to walk.
+ */
+function renderLensArtifactRoster(materialized) {
+  const paths = (materialized?.workflows ?? [])
+    .map((w) => w?.artifactPath)
+    .filter((p) => typeof p === 'string' && p.length > 0);
+  if (paths.length === 0) return null;
+  return [
+    `Lens prompts materialized (host MUST read/walk each against the Story diff):`,
+    ...paths.map((p) => `  - ${p}`),
+  ].join('\n');
+}
+
+/**
+ * Build the `runAuditSuite` substitutions for the Story-scope lens pass
+ * (Story #4627). Resolves the `{{changedFiles}}` token from the actual Story
+ * diff (newline-joined, the shape the lens templates' `## Scope` block reads)
+ * and the `{{ticketId}}` token from the Story id when known. Both are built-in
+ * substitution keys (`substitutions.js#BUILT_IN_SUBSTITUTION_KEYS`), so the
+ * runner accepts them without a per-lens `substitutionKeys` declaration.
+ *
+ * @param {{ changedFiles: string[], storyId?: number|string|null }} args
+ * @returns {Record<string, string>}
+ */
+function buildLensSubstitutions({ changedFiles, storyId }) {
+  const substitutions = { changedFiles: changedFiles.join('\n') };
+  if (storyId != null && `${storyId}`.length > 0) {
+    substitutions.ticketId = String(storyId);
+  }
+  return substitutions;
+}
+
 /**
  * Enumerate the files changed in the `baseRef...headRef` diff. Thin adapter over
  * the shared {@link computeChangeSet} enumerator (Story #4593) that flattens its
@@ -120,10 +172,20 @@ function resolveLensChangeSet({
  * for standalone callers that supply no list; see {@link resolveLensChangeSet}
  * for the three-state contract.
  *
+ * Story #4627 — the pass now delivers lens **content** to a reader. It threads
+ * `{{changedFiles}}` / `{{ticketId}}` substitutions and an `artifactPrefix`
+ * into `runAuditSuite` so each matched lens's substituted prompt body is
+ * written to a scoped artifact under the run's audit output dir, then emits a
+ * host-MUST-walk roster of those artifact paths to the close's stdout. Before
+ * this the default review provider dropped the materialized envelope, so the
+ * pass was a progress log line with no reader.
+ *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   changedFiles?: string[]|null,
+ *   storyId?: number|string|null,
+ *   artifactPrefix?: string,
  *   progress: (tag: string, msg: string) => void,
  *   progressTag?: string,
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
@@ -135,12 +197,15 @@ function resolveLensChangeSet({
  *   lenses: string[],
  *   skipped: boolean,
  *   materialized: object|null,
+ *   artifactPaths: string[],
  * }>}
  */
 export async function runLocalLensReview({
   baseRef,
   headRef,
   changedFiles: injectedChangedFiles,
+  storyId,
+  artifactPrefix,
   progress,
   progressTag = 'CODE-REVIEW',
   gitSpawnFn = gitSpawn,
@@ -152,6 +217,7 @@ export async function runLocalLensReview({
     lenses: [],
     skipped: true,
     materialized: null,
+    artifactPaths: [],
   };
   try {
     const changedFiles = resolveLensChangeSet({
@@ -168,16 +234,30 @@ export async function runLocalLensReview({
       );
       return empty;
     }
-    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
+    // Scope the artifact filenames to this Story so concurrent closes on a
+    // shared audit output dir cannot clobber each other's prompts.
+    const effectivePrefix =
+      artifactPrefix ?? (storyId != null ? `story-${storyId}` : 'story-scope');
+    const materialized = await runAuditSuiteFn({
+      auditWorkflows: lenses,
+      substitutions: buildLensSubstitutions({ changedFiles, storyId }),
+      artifactPrefix: effectivePrefix,
+    });
     progress(
       progressTag,
       `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
     );
+    const roster = renderLensArtifactRoster(materialized);
+    if (roster) progress(progressTag, roster);
+    const artifactPaths = (materialized?.workflows ?? [])
+      .map((w) => w?.artifactPath)
+      .filter((p) => typeof p === 'string' && p.length > 0);
     return {
       depth: STORY_SCOPE_LENS_DEPTH,
       lenses,
       skipped: false,
       materialized,
+      artifactPaths,
     };
   } catch (err) {
     // The lens pass is advisory: a git or materialization failure must not

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -110,6 +110,7 @@ export async function runStoryReviewCore({
     baseRef,
     headRef,
     changedFiles: changeSet.files,
+    storyId: storyIdNum,
     progress,
     progressTag,
     gitSpawnFn,

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,