mandrel 2.9.0 → 2.10.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -36,6 +36,24 @@
  * Backgrounding is not a workaround here and does not need to be: an
  * interrupted poll is stateless and re-entrant by construction.
  *
+ * ## Async mode (Story #4698 — a designed short probe window, not an accident)
+ *
+ * `maxWaitSeconds` (default 300s) still routinely EXPIRES on a slow-CI
+ * consumer: the median PR-create→merge time can be minutes, so nearly every
+ * close burns its whole foreground slot polling and then returns `pending`
+ * anyway. `delivery.mergeWatch.mode: "async"` makes that async confirm a
+ * designed mode rather than an expiry accident. It caps the per-invocation
+ * wait to a short probe window (`ASYNC_PROBE_WINDOW_SECONDS`, ~60s) — long
+ * enough for the loop's existing checks to catch an instant merge and, via the
+ * imported {@link decideMergeWaitFailFast} decision (Story #4695/#4710), an
+ * instantly-red required check — then returns the SAME resumable `pending`
+ * terminal, whose `nextCommand` the worker launches in the background. Nothing
+ * else changes: the cumulative `maxBudgetSeconds` anchor is untouched, and
+ * `sync` mode (the default) is byte-compatible. An explicit `--max-wait-seconds`
+ * override wins over the async cap so a headless caller can still land in one
+ * block. The clamp lives entirely in `resolveMergeWaitConfig`; the poll loop is
+ * mode-agnostic.
+ *
  * ## The wait is not weaker than the watch it displaced
  *
  * The pre-#4543 poll read only `state` / `mergedAt`. A check that went red
@@ -72,7 +90,7 @@
  *     confirm.
  */
 
-import { gh as defaultGh } from '../../../gh-exec.js';
+import { createGh } from '../../../gh-exec.js';
 import {
   confirmStoryMerged as defaultConfirmStoryMerged,
   readPrMergeState as defaultReadPrMergeState,
@@ -86,8 +104,10 @@ import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-blo
 import {
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
+  decideMergeWaitFailFast,
   deriveChecksStatus,
-  failingChecksBlockMerge,
+  deriveRequiredRunEvidence,
+  MERGE_WAIT_GH_TIMEOUT_MS,
 } from '../../merge-poll.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
@@ -105,6 +125,17 @@ import { runPostLandTail as defaultRunPostLandTail } from './post-land.js';
  */
 export const DEFAULT_MAX_WAIT_SECONDS = 300;
 
+/**
+ * Async-mode per-invocation probe window (Story #4698). When
+ * `delivery.mergeWatch.mode` is `"async"`, `resolveMergeWaitConfig` caps the
+ * per-invocation wait to this many seconds so close returns the resumable
+ * `pending` terminal fast instead of burning the foreground host slot. Sized
+ * to catch an instant merge and — via the head-anchored required-check
+ * predicate — an instantly-red required check, while staying far inside the
+ * cumulative `maxBudgetSeconds` give-up bound.
+ */
+export const ASYNC_PROBE_WINDOW_SECONDS = 60;
+
 /** Bounded `gh pr update-branch` attempts for a BEHIND PR. */
 export const DEFAULT_UPDATE_ATTEMPTS = 3;
 
@@ -129,6 +160,49 @@ function defaultSleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * The wait's default `gh` facade, bound to a spawn-level timeout (Story
+ * #4710): every subprocess the wait launches through it carries
+ * `MERGE_WAIT_GH_TIMEOUT_MS`, so a wedged `gh` child is killed rather than
+ * stranding an unattended async-mode wait forever. Callers that inject their
+ * own `gh` (tests, the resume CLI) are bounded by {@link withGhTimeout} at
+ * the call sites instead.
+ */
+const defaultGh = createGh(undefined, { timeoutMs: MERGE_WAIT_GH_TIMEOUT_MS });
+
+/**
+ * Bound an arbitrary `gh` call with a wall-clock timeout (Story #4710). The
+ * spawn-level `timeoutMs` on {@link defaultGh} already kills a wedged real
+ * subprocess, but an injected `gh` implementation (a test stub, a facade
+ * built without defaults) can still return a promise that never settles —
+ * and the merge wait must never hang on any of them. Rejection maps to the
+ * caller's existing error handling: the probe degrades to its conservative
+ * pending shape, the update-branch attempt logs and continues.
+ *
+ * A late settlement of the losing promise is explicitly absorbed so a
+ * post-timeout rejection cannot surface as an unhandled rejection.
+ *
+ * The timeout timer is deliberately NOT `unref`'d: when the awaited call is a
+ * promise that never settles (a hung stub, or a real gh child whose I/O has
+ * gone quiet), the timer is the ONLY handle keeping the event loop alive, so
+ * unref'ing it would let the process/test exit before the timeout ever fires —
+ * exactly the hang this guard exists to prevent. It is short-lived and always
+ * cleared in `finally`, so keeping it referenced costs nothing.
+ */
+function withGhTimeout(promise, timeoutMs, label) {
+  let timer;
+  const bounded = new Promise((resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new Error(`${label} did not return within ${timeoutMs}ms (timeout)`),
+      );
+    }, timeoutMs);
+    promise.then(resolve, reject);
+  }).finally(() => clearTimeout(timer));
+  promise.catch(() => {});
+  return bounded;
+}
+
 /**
  * One probe per poll iteration, carrying every field the loop and the
  * terminal classifier need: merge state, the checks rollup, the merge-state
@@ -137,20 +211,31 @@ function defaultSleep(ms) {
  *
  * Returns a degraded `{ checksStatus: 'pending', error }` probe when the read
  * itself fails, preserving the conservative classification on probe errors —
- * a flaky API read must not be mistaken for a definitive verdict.
+ * a flaky API read must not be mistaken for a definitive verdict. A probe
+ * that exceeds `ghTimeoutMs` (Story #4710) takes the SAME degraded path: a
+ * hung subprocess must surface as a probe error within the bound, never
+ * strand the wait.
  *
  * @returns {Promise<object>}
  */
-export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
+export async function readPrWaitProbe({
+  prNumber,
+  gh = defaultGh,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+}) {
   try {
-    const view = await gh.pr.view(prNumber, [
-      'state',
-      'mergedAt',
-      'createdAt',
-      'mergeStateStatus',
-      'reviewDecision',
-      'statusCheckRollup',
-    ]);
+    const view = await withGhTimeout(
+      gh.pr.view(prNumber, [
+        'state',
+        'mergedAt',
+        'createdAt',
+        'mergeStateStatus',
+        'reviewDecision',
+        'statusCheckRollup',
+      ]),
+      ghTimeoutMs,
+      `gh pr view ${prNumber}`,
+    );
     return {
       state: typeof view?.state === 'string' ? view.state : null,
       mergedAt: typeof view?.mergedAt === 'string' ? view.mergedAt : null,
@@ -164,6 +249,11 @@ export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
           ? view.reviewDecision
           : undefined,
       checksStatus: deriveChecksStatus(view?.statusCheckRollup),
+      // Head-anchored per-run evidence (Story #4695): distinguishes a
+      // genuinely red required run from the superseded / still-pending noise
+      // the aggregate `checksStatus` folds together. `null` when the rollup is
+      // absent/empty — the loop's consecutive-probe fallback owns that path.
+      requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
     };
   } catch (err) {
     return {
@@ -185,18 +275,36 @@ export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
  * raises the per-invocation bound to keep single-block semantics without
  * editing the consumer's config.
  *
+ * `mode` (Story #4698) selects the close-time merge posture. `async` caps the
+ * per-invocation wait to `ASYNC_PROBE_WINDOW_SECONDS` so close returns the
+ * resumable `pending` terminal fast; `sync` (the default) is unchanged. An
+ * explicit `maxWaitSecondsOverride` still wins over the async cap — a headless
+ * caller with no host ceiling opts back into single-block waiting.
+ *
  * @param {object} [config]
  * @param {number} [maxWaitSecondsOverride]
- * @returns {{ intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
+ * @returns {{ mode: 'sync'|'async', intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
  */
 export function resolveMergeWaitConfig(config, maxWaitSecondsOverride) {
   const mergeWatch = config?.delivery?.mergeWatch ?? {};
   const int = (value, fallback, min = 1) =>
     Number.isInteger(value) && value >= min ? value : fallback;
-  const maxWaitSeconds = int(
+  const mode = mergeWatch.mode === 'async' ? 'async' : 'sync';
+  const configuredMaxWait = int(
     maxWaitSecondsOverride,
     int(mergeWatch.maxWaitSeconds, DEFAULT_MAX_WAIT_SECONDS),
   );
+  // Async mode caps the per-invocation wait to a short probe window so close
+  // returns `pending` fast instead of burning the foreground host slot on a
+  // merge that lands after the wait would have expired anyway. The window is
+  // long enough for the loop's existing checks to catch an instant merge and —
+  // via the imported `decideMergeWaitFailFast` decision — an instantly
+  // red required check. An explicit `--max-wait-seconds` override still wins so
+  // a headless caller with no host ceiling opts back into single-block waiting.
+  const maxWaitSeconds =
+    mode === 'async' && maxWaitSecondsOverride == null
+      ? Math.min(configuredMaxWait, ASYNC_PROBE_WINDOW_SECONDS)
+      : configuredMaxWait;
   // A poll interval longer than the wait bound is incoherent, and silently
   // harmful: the pending check would fire on poll 1 every time, so the wait
   // could never sleep, `polls` could never reach
@@ -210,6 +318,7 @@ export function resolveMergeWaitConfig(config, maxWaitSecondsOverride) {
     maxWaitSeconds,
   );
   return {
+    mode,
     intervalSeconds,
     maxWaitSeconds,
     maxBudgetSeconds: int(
@@ -429,6 +538,12 @@ async function blockOnUnlanded({
     budget,
   });
   const elapsedSeconds = budget?.elapsedSeconds ?? 0;
+  // Which evidence path produced a `checks-failed` verdict (Story #4695):
+  // `per-run` (head-anchored required-run evidence) or `consecutive-probe`
+  // (the evidence-unavailable fallback). Named on the emitted record so the
+  // `merge.unlanded` telemetry attributes the fail-fast to the path that
+  // fired it. Absent for every other block class.
+  const evidencePath = prProbe?.evidencePath;
 
   if (Number.isInteger(prNumber) && prNumber > 0) {
     try {
@@ -439,6 +554,7 @@ async function blockOnUnlanded({
         blockClass,
         reason,
         elapsedSeconds,
+        ...(evidencePath ? { evidencePath } : {}),
       });
     } catch (err) {
       progress?.(
@@ -509,6 +625,7 @@ async function maybeUpdateBehindPr({
   updatesUsed,
   updateAttempts,
   gh,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
   progress,
 }) {
   if (probe.mergeStateStatus !== 'BEHIND') return false;
@@ -520,7 +637,11 @@ async function maybeUpdateBehindPr({
     return false;
   }
   try {
-    await (gh ?? defaultGh).pr.updateBranch(prNumber);
+    await withGhTimeout(
+      (gh ?? defaultGh).pr.updateBranch(prNumber),
+      ghTimeoutMs,
+      `gh pr update-branch ${prNumber}`,
+    );
     progress?.(
       'CONFIRM',
       `⏫ PR #${prNumber} was BEHIND its base — updated (attempt ${updatesUsed + 1}/${updateAttempts}).`,
@@ -650,6 +771,10 @@ async function onMergeObserved({
  * @param {(ms: number) => Promise<void>} [args.sleepFn] Test seam so the
  *   suite does not actually wait.
  * @param {() => number} [args.nowMsFn] Test seam; returns epoch ms.
+ * @param {number} [args.ghTimeoutMs] Wall-clock bound for each `gh` call the
+ *   wait makes (Story #4710). A framework constant
+ *   (`MERGE_WAIT_GH_TIMEOUT_MS`), overridable only as a test seam — not
+ *   config.
  * @returns {Promise<object>}
  */
 export async function runConfirmMergePhase({
@@ -676,6 +801,7 @@ export async function runConfirmMergePhase({
   runPostLandTailFn = defaultRunPostLandTail,
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
 }) {
   // The arm itself never succeeded (gh failure, unparseable PR number, or a
   // deliberate disablement) — there is no "armed but unconfirmed" PR to
@@ -699,22 +825,38 @@ export async function runConfirmMergePhase({
     });
   }
 
-  const { intervalSeconds, maxWaitSeconds, maxBudgetSeconds, updateAttempts } =
-    resolveMergeWaitConfig(config, maxWaitSecondsOverride);
+  const {
+    mode,
+    intervalSeconds,
+    maxWaitSeconds,
+    maxBudgetSeconds,
+    updateAttempts,
+  } = resolveMergeWaitConfig(config, maxWaitSecondsOverride);
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
   let updatesUsed = 0;
   let polls = 0;
+  // Consecutive failing check probes observed WITHOUT per-run evidence
+  // (Story #4695). The evidence-unavailable fallback: a single failing rollup
+  // snapshot never fail-fasts — two consecutive failing probes at least one
+  // poll interval apart are required. Reset on any non-failing (or genuinely
+  // evidenced) probe.
+  let consecutiveRequiredFailSnapshots = 0;
 
   progress?.(
     'CONFIRM',
     `⏳ Close-and-land: polling PR #${prNumber} for merge confirmation ` +
-      `(wait=${maxWaitSeconds}s this invocation, cumulative budget=${maxBudgetSeconds}s)...`,
+      `(mode=${mode}, wait=${maxWaitSeconds}s this invocation, ` +
+      `cumulative budget=${maxBudgetSeconds}s)...`,
   );
 
   while (true) {
-    const probe = await readPrWaitProbeFn({ prNumber, gh: injectedGh });
+    const probe = await readPrWaitProbeFn({
+      prNumber,
+      gh: injectedGh,
+      ghTimeoutMs,
+    });
     polls += 1;
 
     // Anchor the cumulative budget at the PR's creation the first time we
@@ -755,6 +897,12 @@ export async function runConfirmMergePhase({
       });
     }
 
+    // Everything below funnels into ONE terminal exit (Story #4710): each
+    // definitive condition fills `unlanded` and the single call site at the
+    // bottom classifies, emits, and blocks — the fail-fast tree used to
+    // duplicate that block twice inline.
+    let unlanded = null;
+
     if (probe.state === 'CLOSED') {
       // Closed without merging — a definitive terminal, not a "still
       // pending" condition the budget should keep waiting on. checksStatus
@@ -763,10 +911,7 @@ export async function runConfirmMergePhase({
       // pending", which would misclassify this definitive case as
       // checks-pending-timeout instead of reaching the api-race-other
       // reason built from prProbe.error.
-      return blockOnUnlanded({
-        storyId,
-        prNumber,
-        prUrl,
+      unlanded = {
         prProbe: {
           checksStatus: 'closed',
           error: 'PR closed without merging (state=CLOSED)',
@@ -775,72 +920,78 @@ export async function runConfirmMergePhase({
           exhausted: true,
           elapsedSeconds: Math.round(waitedMs / 1000),
         },
-        provider,
-        progress,
-        classifyMergeBlockFn,
-        emitMergeUnlandedFn,
+      };
+    } else {
+      // Fail fast on a GENUINELY red REQUIRED check — head-anchored (Story
+      // #4695), decided by the extracted `decideMergeWaitFailFast` (Story
+      // #4710): per-run evidence decides on a single probe; without evidence
+      // two consecutive failing probes are required. No remaining budget
+      // turns a failed check green, and waiting it out is what made the
+      // pre-#4543 wait report the operator's red test run as a
+      // branch-protection block.
+      const decision = decideMergeWaitFailFast({
+        probe,
+        consecutiveRequiredFailSnapshots,
       });
+      consecutiveRequiredFailSnapshots =
+        decision.consecutiveRequiredFailSnapshots;
+      if (decision.failFast) {
+        progress?.(
+          'CONFIRM',
+          decision.evidencePath === 'per-run'
+            ? `🛑 PR #${prNumber}: a required check concluded failure with none in flight — failing fast (evidence=per-run).`
+            : `🛑 PR #${prNumber}: two consecutive failing check probes without per-run evidence — failing fast (evidence=consecutive-probe).`,
+        );
+        unlanded = {
+          prProbe: decision.prProbe,
+          budget: {
+            exhausted: false,
+            elapsedSeconds: Math.round(waitedMs / 1000),
+          },
+        };
+      }
     }
 
-    // Fail fast on a red REQUIRED check. No remaining budget turns a failed
-    // check green, and waiting it out is what made the pre-#4543 wait report
-    // the operator's red test run as a branch-protection block.
-    //
-    // Gated on `failingChecksBlockMerge`, not on the raw rollup: a red
-    // OPTIONAL check does not stop native auto-merge, so failing fast on it
-    // would block the Story while the PR lands anyway.
-    if (failingChecksBlockMerge(probe)) {
-      progress?.(
-        'CONFIRM',
-        `🛑 PR #${prNumber}: a required check went red — failing fast rather than burning the budget.`,
-      );
-      return blockOnUnlanded({
-        storyId,
-        prNumber,
-        prUrl,
-        prProbe: probe,
-        budget: {
-          exhausted: false,
-          elapsedSeconds: Math.round(waitedMs / 1000),
-        },
-        provider,
-        progress,
-        classifyMergeBlockFn,
-        emitMergeUnlandedFn,
-      });
-    }
+    if (!unlanded) {
+      if (
+        await maybeUpdateBehindPr({
+          probe,
+          prNumber,
+          updatesUsed,
+          updateAttempts,
+          gh: injectedGh,
+          ghTimeoutMs,
+          progress,
+        })
+      ) {
+        updatesUsed += 1;
+      }
 
-    if (
-      await maybeUpdateBehindPr({
-        probe,
-        prNumber,
-        updatesUsed,
-        updateAttempts,
-        gh: injectedGh,
-        progress,
-      })
-    ) {
-      updatesUsed += 1;
+      // Cumulative budget exhausted → the genuine give-up. Classify from the
+      // probe we already hold. Gated behind the poll floor so an
+      // already-over-budget PR (anchored at a createdAt older than the budget
+      // — a resume the next day, or a long-open PR) still gets a real poll
+      // cycle instead of being blocked before this invocation waited at all.
+      if (
+        polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
+        cumulativeMs + intervalMs > maxBudgetSeconds * 1000
+      ) {
+        unlanded = {
+          prProbe: probe,
+          budget: {
+            exhausted: true,
+            elapsedSeconds: Math.round(cumulativeMs / 1000),
+          },
+        };
+      }
     }
 
-    // Cumulative budget exhausted → the genuine give-up. Classify from the
-    // probe we already hold. Gated behind the poll floor so an
-    // already-over-budget PR (anchored at a createdAt older than the budget —
-    // a resume the next day, or a long-open PR) still gets a real poll cycle
-    // instead of being blocked before this invocation waited at all.
-    if (
-      polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
-      cumulativeMs + intervalMs > maxBudgetSeconds * 1000
-    ) {
+    if (unlanded) {
       return blockOnUnlanded({
         storyId,
         prNumber,
         prUrl,
-        prProbe: probe,
-        budget: {
-          exhausted: true,
-          elapsedSeconds: Math.round(cumulativeMs / 1000),
-        },
+        ...unlanded,
         provider,
         progress,
         classifyMergeBlockFn,

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

@@ -13,10 +13,17 @@
  */
 
 import {
+  evaluateLensDiffFloor,
+  resolveLensDiffFloor,
   runAuditSuite,
   selectLocalLenses,
 } from '../../../audit-suite/index.js';
+import { resolveConfig } from '../../../config-resolver.js';
 import { gitSpawn } from '../../../git-utils.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
 import { computeChangeSet } from '../../change-set.js';
 
 /**
@@ -180,10 +187,21 @@ function resolveLensChangeSet({
  * this the default review provider dropped the materialized envelope, so the
  * pass was a progress log line with no reader.
  *
+ * Story #4699 — the **lens diff-floor**. When the caller supplies a known
+ * `changedLineCount` and the diff sits strictly below the configured floor
+ * (`delivery.review.lensDiffFloor`, default 40) with zero sensitive-path
+ * hits, the pass records the matched roster but skips materialization
+ * entirely (`skipped: true` with the lenses retained and a `floorSkip`
+ * verdict) — the maker-blind code-review pillar and every hard gate are
+ * untouched. An unknown line count, a disabled floor, or a sensitive-path
+ * hit all fail open to the full materialization.
+ *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   changedFiles?: string[]|null,
+ *   changedLineCount?: number|null,
+ *   lensDiffFloor?: number,
  *   storyId?: number|string|null,
  *   artifactPrefix?: string,
  *   progress: (tag: string, msg: string) => void,
@@ -191,11 +209,15 @@ function resolveLensChangeSet({
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   selectLocalLensesFn?: typeof selectLocalLenses,
  *   runAuditSuiteFn?: typeof runAuditSuite,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   evaluateLensDiffFloorFn?: typeof evaluateLensDiffFloor,
+ *   emitToolDegradationFn?: typeof emitRuntimeFriction,
  * }} args
  * @returns {Promise<{
  *   depth: 'light',
  *   lenses: string[],
  *   skipped: boolean,
+ *   floorSkip: object|null,
  *   materialized: object|null,
  *   artifactPaths: string[],
  * }>}
@@ -204,6 +226,8 @@ export async function runLocalLensReview({
   baseRef,
   headRef,
   changedFiles: injectedChangedFiles,
+  changedLineCount = null,
+  lensDiffFloor,
   storyId,
   artifactPrefix,
   progress,
@@ -211,11 +235,15 @@ export async function runLocalLensReview({
   gitSpawnFn = gitSpawn,
   selectLocalLensesFn = selectLocalLenses,
   runAuditSuiteFn = runAuditSuite,
+  resolveConfigFn = resolveConfig,
+  evaluateLensDiffFloorFn = evaluateLensDiffFloor,
+  emitToolDegradationFn = emitRuntimeFriction,
 }) {
   const empty = {
     depth: STORY_SCOPE_LENS_DEPTH,
     lenses: [],
     skipped: true,
+    floorSkip: null,
     materialized: null,
     artifactPaths: [],
   };
@@ -234,6 +262,34 @@ export async function runLocalLensReview({
       );
       return empty;
     }
+
+    // Lens diff-floor (Story #4699). Deliberately evaluated AFTER lens
+    // selection so a floor-skip still records WHICH lenses it skipped —
+    // the findings-yield ledger needs the roster either way.
+    const floorVerdict = evaluateLensDiffFloorFn({
+      changedFiles,
+      changedLineCount,
+      floor:
+        typeof lensDiffFloor === 'number'
+          ? lensDiffFloor
+          : resolveLensDiffFloor(safeResolveConfig(resolveConfigFn)),
+    });
+    if (floorVerdict.skip) {
+      progress(
+        progressTag,
+        `Lens diff-floor: ${floorVerdict.changedLineCount} changed line(s) < ` +
+          `floor ${floorVerdict.floor} with zero sensitive-path hits — ` +
+          `skipping materialization of ${lenses.join(', ')}.`,
+      );
+      return {
+        depth: STORY_SCOPE_LENS_DEPTH,
+        lenses,
+        skipped: true,
+        floorSkip: floorVerdict,
+        materialized: null,
+        artifactPaths: [],
+      };
+    }
     // Scope the artifact filenames to this Story so concurrent closes on a
     // shared audit output dir cannot clobber each other's prompts.
     const effectivePrefix =
@@ -256,16 +312,48 @@ export async function runLocalLensReview({
       depth: STORY_SCOPE_LENS_DEPTH,
       lenses,
       skipped: false,
+      floorSkip: floorVerdict,
       materialized,
       artifactPaths,
     };
   } catch (err) {
     // The lens pass is advisory: a git or materialization failure must not
-    // fail the close. Log and degrade to a skipped envelope.
+    // fail the close. Log, route the tool-execution degradation to friction
+    // telemetry (Story #4699 — degradations are operational signals, not
+    // findings), and degrade to a skipped envelope.
     progress(
       progressTag,
       `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
     );
+    try {
+      await emitToolDegradationFn({
+        storyId,
+        category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
+        tool: 'local-lens-review',
+        details: {
+          surface: 'lens-materialization',
+          reason: String(err?.message ?? err).slice(0, 500),
+        },
+      });
+    } catch {
+      // Observability must never fail the close (best-effort contract).
+    }
     return empty;
   }
 }
+
+/**
+ * Resolve config for the floor read without letting a resolver failure
+ * fail the (advisory) lens pass. Module-local: a degraded config simply
+ * yields the framework-default floor.
+ *
+ * @param {typeof resolveConfig} resolveConfigFn
+ * @returns {object|undefined}
+ */
+function safeResolveConfig(resolveConfigFn) {
+  try {
+    return resolveConfigFn();
+  } catch {
+    return undefined;
+  }
+}