mandrel 1.57.0

package/.agents/scripts/lib/orchestration/story-close/phases/locked-pipeline.js

@@ -0,0 +1,234 @@
+/**
+ * phases/locked-pipeline.js — the per-Epic-merge-lock-protected body of
+ * `runStoryClose` (Story #2460, Epic #2453 — CLI thinning pilot).
+ *
+ * Sits behind `withEpicMergeLock` in story-close.js. Owns:
+ *
+ *   1. dispatchRecovery     — prior-state detection + --resume / --restart
+ *      dispatch
+ *   2. fetchChildTickets      — hydrate the cascade target set
+ *   3. phase-timer restore  — pick up the snapshot story-init wrote
+ *   4. gates                — pre-merge validation (skipped on resume)
+ *   5. refresh              — bounded baseline auto-refresh (gates ok path)
+ *   6. close                — merge + post-merge close pipeline
+ *
+ * The split out of story-close.js keeps the CLI shell at ≤ 300 LOC and
+ * means a future test can drive the locked pipeline with the lock
+ * mocked out — without re-acquiring the per-Epic lock or re-entering
+ * the preflight gate.
+ */
+
+import { Logger } from '../../../Logger.js';
+import { fetchChildTickets } from '../../../story-lifecycle.js';
+import { createPhaseTimer } from '../../../util/phase-timer.js';
+import {
+  clearPhaseTimerState,
+  loadPhaseTimerState,
+} from '../../../util/phase-timer-state.js';
+import { read as readPlanState } from '../../epic-plan-state-store.js';
+import { dispatchRecovery } from '../../story-close-recovery.js';
+import { runClosePhase } from './close.js';
+import { runStoryCodeReview } from './code-review.js';
+import {
+  emitBaselineBlockedResult,
+  runPreMergeValidation,
+  shouldSkipValidation,
+} from './gates.js';
+import { runAutoRefreshSafely } from './refresh.js';
+import { emitSpawnTimeoutBlockedResult } from './timeout-blocked-emitter.js';
+
+/**
+ * Run pre-merge gates and, on a clean outcome, the bounded baseline
+ * auto-refresh. Returns `{ blocked }` so the locked pipeline can
+ * short-circuit on a `blocked` / `blocked-timeout` gate outcome.
+ */
+async function runGatesAndRefresh(ctx) {
+  const gateOutcome = await runPreMergeValidation({
+    cwd: ctx.cwd,
+    worktreePath: ctx.worktreePath,
+    epicBranch: ctx.epicBranch,
+    storyBranch: ctx.storyBranch,
+    config: ctx.config,
+    storyId: ctx.storyId,
+    epicId: ctx.epicId,
+    noEvidenceFlag: ctx.noEvidenceFlag,
+    phaseTimer: ctx.phaseTimer,
+    provider: ctx.provider,
+    bus: ctx.bus,
+  });
+  if (gateOutcome?.status === 'blocked') {
+    return {
+      blocked: await emitBaselineBlockedResult({
+        storyId: ctx.storyId,
+        gateOutcome,
+        progress: ctx.progress,
+        bus: ctx.bus,
+      }),
+    };
+  }
+  if (gateOutcome?.status === 'blocked-timeout') {
+    return {
+      blocked: await emitSpawnTimeoutBlockedResult({
+        storyId: ctx.storyId,
+        epicId: ctx.epicId,
+        spawnName: gateOutcome.gateName ?? 'coverage-capture',
+        spawnCmd: gateOutcome.spawnCmd ?? null,
+        timeoutMs: gateOutcome.timeoutMs ?? null,
+        exitCode: gateOutcome.exitCode ?? 124,
+        config: ctx.config,
+        provider: ctx.provider,
+        progress: ctx.progress,
+        bus: ctx.bus,
+      }),
+    };
+  }
+  await runAutoRefreshSafely(
+    {
+      storyId: ctx.storyId,
+      epicId: ctx.epicId,
+      cwd: ctx.worktreePath || ctx.cwd,
+      epicBranch: ctx.epicBranch,
+      storyBranch: ctx.storyBranch,
+      config: ctx.config,
+    },
+    { progress: ctx.progress },
+  );
+  return { blocked: null };
+}
+
+/**
+ * Read the parent Epic's judged `planningRisk` envelope off its
+ * `epic-plan-state` checkpoint so the Story-scope review can inherit the
+ * Epic's review depth (Story #3940). Best-effort and total — it reuses the
+ * shared `read` from `epic-plan-state-store.js` (the same reader `/epic-plan
+ * --resume` and `epic-audit-prepare.js`'s `resolveRiskRoutedLenses` use, no
+ * third bespoke reader) and never fails the close:
+ *
+ *   - absent/non-integer `epicId` (a Story that is not Epic-attached) → `null`
+ *   - missing/unparseable checkpoint, no `planningRisk` field → `null`
+ *   - any read throw (provider error, malformed comment) → `null`
+ *
+ * A `null` result threads through `runStoryCodeReview` → `runCodeReview`
+ * unchanged, so depth resolves from diff width alone (`standard`), preserving
+ * today's behaviour for an Epic that skipped `/epic-plan`.
+ *
+ * @param {{ provider: object, epicId: number|null|undefined, readPlanStateFn?: typeof readPlanState }} args
+ * @returns {Promise<{ overallLevel?: string, axes?: Array<object> }|null>}
+ */
+export async function resolveParentEpicPlanningRisk({
+  provider,
+  epicId,
+  readPlanStateFn = readPlanState,
+}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) return null;
+  try {
+    const state = await readPlanStateFn({ provider, epicId });
+    return state?.planningRisk ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Body of `withEpicMergeLock(epicId, ..., () => …)` from story-close.js.
+ *
+ * @param {object} args - resolved-close-input bundle from
+ *   `resolveCloseInputs` plus the orchestrator-injected `progress` /
+ *   `progressLog` callbacks and the lifecycle bus.
+ * @returns {Promise<{ success: boolean, result?: object } | object>}
+ */
+export async function runStoryCloseLocked(args) {
+  const {
+    cwd,
+    storyId,
+    epicId,
+    epicBranch,
+    storyBranch,
+    config,
+    skipValidationParam,
+    resumeFlag,
+    restartFlag,
+    provider,
+    story,
+    progress,
+  } = args;
+
+  // Prior-state detection + --resume / --restart dispatch.
+  // `dispatchRecovery` only reads `orchestration.worktreeIsolation`; surface
+  // it from the canonical `delivery.worktreeIsolation` view directly.
+  const { resumeFromConflict, resumeFromMerge, resumeFromPostMerge } =
+    dispatchRecovery({
+      cwd,
+      storyId,
+      epicId,
+      epicBranch,
+      storyBranch,
+      orchestration: { worktreeIsolation: config.delivery?.worktreeIsolation },
+      resume: resumeFlag,
+      restart: restartFlag,
+      progress,
+      logger: Logger,
+    });
+
+  const tasks = await fetchChildTickets(provider, storyId);
+  provider.primeTicketCache([story, ...tasks]);
+  progress('TICKETS', `Found ${tasks.length} child ticket(s)`);
+
+  const prior = loadPhaseTimerState({ mainCwd: cwd, storyId });
+  const phaseTimer = createPhaseTimer(storyId, prior ? { restore: prior } : {});
+
+  const skipValidation = shouldSkipValidation({
+    skipValidationParam,
+    resumeFromConflict,
+    resumeFromMerge,
+    resumeFromPostMerge,
+  });
+
+  const ctx = {
+    ...args,
+    tasks,
+    phaseTimer,
+    resumeFromConflict,
+    resumeFromMerge,
+    resumeFromPostMerge,
+    clearPhaseTimerState,
+  };
+
+  if (!skipValidation) {
+    const { blocked } = await runGatesAndRefresh(ctx);
+    if (blocked) return blocked;
+
+    // Story #2840 — Story-scope code review runs after the gate chain
+    // passes (so we know the diff is build-clean) but before the merge
+    // into `epic/<id>`. Critical findings short-circuit the close and
+    // exit non-zero; non-critical findings post a structured comment
+    // and let close proceed.
+    //
+    // Story #3940 — the review inherits the parent Epic's judged review
+    // depth: read the Epic's `planningRisk` envelope best-effort off its
+    // `epic-plan-state` checkpoint and forward it so `runCodeReview`
+    // resolves depth from BOTH that risk and the Story-scope
+    // (`epic/<id>...story-<id>`) changed-file count. A missing/unreadable
+    // checkpoint degrades to `null` (→ `standard`) without failing close.
+    const planningRisk = await resolveParentEpicPlanningRisk({
+      provider: ctx.provider,
+      epicId: ctx.epicId,
+    });
+    const review = await runStoryCodeReview({
+      storyId: ctx.storyId,
+      epicBranch: ctx.epicBranch,
+      storyBranch: ctx.storyBranch,
+      provider: ctx.provider,
+      bus: ctx.bus,
+      progress: ctx.progress,
+      planningRisk,
+    });
+    if (review.blocked) return review.blocked;
+  }
+
+  // Everything past validation is the `close` phase; the post-merge
+  // pipeline marks `api-sync` once the merge lands.
+  phaseTimer.mark('close');
+
+  return runClosePhase(ctx);
+}

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

@@ -0,0 +1,110 @@
+/**
+ * phases/preflight.js — story-close preflight phase (Story #2460, Epic
+ * #2453 — CLI thinning pilot).
+ *
+ * Wraps the registry-driven preflight scan + the canonical "preflight
+ * refused" close-result envelope. Runs BEFORE `withEpicMergeLock` so the
+ * per-Epic lock is not acquired just to release it on a refused
+ * preflight (the project-wide exit-code 2 reservation).
+ *
+ * Public surface:
+ *   - runStoryClosePreflight(opts)         ← exported (story-close.js re-export)
+ *   - emitPreflightBlockedResult(opts)
+ *   - runPreflightPhase(ctx)               ← pipeline entry
+ */
+
+import { Logger } from '../../../Logger.js';
+import {
+  PREFLIGHT_REFUSED_EXIT_CODE,
+  runPreflight,
+} from '../../../preflight-runner.js';
+import { emitBlockedCloseResult } from '../merge-runner.js';
+
+/**
+ * Run the story-close preflight gate. Exported so tests can drive it
+ * with an inline registry / probe spies without re-entering the full
+ * close orchestrator.
+ *
+ * @param {object} opts
+ * @param {string|number} opts.storyId
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {object} [opts.probes]
+ * @param {object} [opts.registry]
+ * @param {string} [opts.dir]
+ * @param {object} [opts.logger]
+ * @returns {Promise<{ ok: boolean, findings: Array, fixed: Array }>}
+ */
+export async function runStoryClosePreflight({
+  storyId,
+  cwd = process.cwd(),
+  probes,
+  registry,
+  dir,
+  logger,
+} = {}) {
+  Logger.info(
+    `[story-close] Running preflight checks (scope=story-close) for Story #${storyId ?? '?'}...`,
+  );
+  const preflight = await runPreflight({
+    scope: 'story-close',
+    autoFix: true,
+    cwd,
+    probes,
+    registry,
+    dir,
+    logger,
+  });
+  return {
+    ok: !preflight.blocked,
+    findings: preflight.findings,
+    fixed: preflight.fixed,
+  };
+}
+
+/**
+ * Emit the canonical close-result envelope for the "preflight refused"
+ * exit. Shape mirrors `emitBaselineBlockedResult` so the wave aggregator's
+ * label-derivation fallback sees a consistent envelope.
+ */
+export async function emitPreflightBlockedResult({
+  storyId,
+  preflight,
+  progress,
+}) {
+  return emitBlockedCloseResult({
+    storyId,
+    phase: 'preflight',
+    reason: 'preflight-refused',
+    extra: { findings: preflight.findings },
+    progress,
+    blockedMessage: `Story #${storyId} blocked: preflight refused — ${preflight.findings.length} blocker finding(s).`,
+    logger: Logger,
+  });
+}
+
+/**
+ * Phase pipeline entry. Returns one of:
+ *   - { ok: true } when preflight passed (caller continues)
+ *   - { ok: false, exitEnvelope } when preflight refused (caller short-circuits
+ *     with `{ success: false, result: exitEnvelope, exitCode: PREFLIGHT_REFUSED_EXIT_CODE }`)
+ */
+export async function runPreflightPhase({ ctx }) {
+  const outcome = await runStoryClosePreflight({
+    storyId: ctx.storyId,
+    cwd: ctx.cwd,
+  });
+  if (outcome.ok) return { ok: true };
+  const exitEnvelope = await emitPreflightBlockedResult({
+    storyId: ctx.storyId,
+    preflight: outcome,
+    progress: ctx.progress,
+  });
+  return {
+    ok: false,
+    exitEnvelope: {
+      success: false,
+      result: exitEnvelope,
+      exitCode: PREFLIGHT_REFUSED_EXIT_CODE,
+    },
+  };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * phases/refresh.js — bounded baseline auto-refresh phase (Story #2460,
+ * Epic #2453 — CLI thinning pilot).
+ *
+ * Pre-merge gates have passed; this phase regenerates baseline rows
+ * scoped to the Story diff and folds them into HEAD via one canonical
+ * `chore(baselines): refresh <kind> for story-<id>` commit per kind that
+ * actually drifted. Failure modes are advisory: a regen / amend /
+ * signal-write failure is logged but does not block the close.
+ *
+ * Public surface:
+ *   - describeAutoRefreshOutcome(refreshResult)   ← exported (story-close.js re-export)
+ *   - reportAutoRefreshOutcome(refreshResult, deps?)
+ *   - runAutoRefreshSafely(args, deps?)
+ */
+
+import { Logger } from '../../../Logger.js';
+import { runAutoRefresh } from '../auto-refresh-runner.js';
+
+/**
+ * Pure: render the AUTO-REFRESH status into a `{channel, message}` log
+ * envelope, or `null` for statuses we don't surface. Extracted so the
+ * branching lives behind a tested boundary.
+ */
+export function describeAutoRefreshOutcome(refreshResult) {
+  if (
+    refreshResult?.status === 'committed' ||
+    refreshResult?.status === 'amended'
+  ) {
+    return {
+      channel: 'progress',
+      label: 'AUTO-REFRESH',
+      message: `Committed bounded baseline drift on Story branch (${refreshResult.sha}).`,
+    };
+  }
+  if (refreshResult?.status === 'refused') {
+    const sig = refreshResult.dedup
+      ? 'already present'
+      : refreshResult.signalAppended
+        ? 'appended'
+        : 'not written';
+    return {
+      channel: 'progress',
+      label: 'AUTO-REFRESH',
+      message: `Refused — ${refreshResult.refusalReasons.length} cap breach(es); friction signal ${sig}.`,
+    };
+  }
+  if (refreshResult?.status === 'failed') {
+    return {
+      channel: 'warn',
+      message: `[auto-refresh] ${refreshResult.reason}: ${refreshResult.detail ?? ''}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Translate the structured outcome into a single log line via the
+ * provided `progress` callback (so production wires `progressLog` and
+ * tests can pin the channel + label).
+ */
+export function reportAutoRefreshOutcome(refreshResult, deps = {}) {
+  const envelope = describeAutoRefreshOutcome(refreshResult);
+  if (!envelope) return;
+  const progress = deps.progress;
+  const logger = deps.logger ?? Logger;
+  if (envelope.channel === 'warn') logger.warn(envelope.message);
+  else if (progress) progress(envelope.label, envelope.message);
+}
+
+/**
+ * Story #1398 (Epic #1386) — bounded baseline auto-refresh. Pre-merge
+ * gates have passed; regenerate baseline rows scoped to the Story diff
+ * and amend them into HEAD if every row's delta is at or below the
+ * configured caps. Failure modes are advisory.
+ */
+export async function runAutoRefreshSafely(args, deps = {}) {
+  try {
+    const refreshResult = await runAutoRefresh(args);
+    reportAutoRefreshOutcome(refreshResult, deps);
+  } catch (err) {
+    Logger.warn(
+      `[auto-refresh] runner threw: ${err?.stack || err?.message || err}`,
+    );
+  }
+}

package/.agents/scripts/lib/orchestration/story-close/phases/timeout-blocked-emitter.js

@@ -0,0 +1,112 @@
+/**
+ * phases/timeout-blocked-emitter.js — side-effecting half of the timeout
+ * dispatch phase (Story #2460, Epic #2453 — CLI thinning pilot).
+ *
+ * Applies the `agent::blocked` transition + the friction comment + the
+ * lifecycle-bus emit when one of the close-time bounded-timeout spawns
+ * exits 124. All three side-effects are best-effort: a failure here
+ * logs and falls through so the close-result envelope reaches the
+ * operator regardless.
+ *
+ * Sibling: `timeout-blocked.js` (pure helpers — the descriptor table,
+ * reason-token map, and body renderer). Split out so the side-effects
+ * stay isolated and the pure half is trivially testable.
+ */
+
+import { Logger } from '../../../Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from '../../ticketing.js';
+import { emitBlockedCloseResult } from '../merge-runner.js';
+import {
+  renderSpawnTimeoutFrictionBody,
+  resolveSpawnTimeoutDescriptor,
+  resolveSpawnTimeoutMs,
+} from './timeout-blocked.js';
+
+/**
+ * Apply the `agent::blocked` transition + friction comment when one of
+ * the close-time spawns exits 124.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   epicId?: number|string|null,
+ *   spawnName: string,
+ *   spawnCmd?: string|null,
+ *   timeoutMs?: number|null,
+ *   exitCode?: number|null,
+ *   config?: object,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   reason?: string,
+ *   bus?: object|null,
+ * }} input
+ */
+export async function emitSpawnTimeoutBlockedResult({
+  storyId,
+  epicId,
+  spawnName,
+  spawnCmd = null,
+  timeoutMs: providedTimeoutMs = null,
+  exitCode = 124,
+  config,
+  provider,
+  progress: log,
+  reason,
+  bus = null,
+}) {
+  const timeoutMs =
+    providedTimeoutMs ?? resolveSpawnTimeoutMs(spawnName, config);
+
+  const body = renderSpawnTimeoutFrictionBody({
+    storyId,
+    epicId,
+    timeoutMs,
+    spawnName,
+    spawnCmd,
+  });
+
+  let commentId = null;
+  try {
+    const res = await upsertStructuredComment(
+      provider,
+      storyId,
+      'friction',
+      body,
+    );
+    commentId = res?.commentId ?? null;
+  } catch (err) {
+    Logger.warn?.(
+      `[story-close] failed to upsert ${spawnName}-timeout friction comment on #${storyId}: ${err?.message ?? err}`,
+    );
+  }
+
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {
+      cascade: false,
+    });
+  } catch (err) {
+    Logger.warn?.(
+      `[story-close] failed to transition Story #${storyId} → ${STATE_LABELS.BLOCKED}: ${err?.message ?? err}`,
+    );
+  }
+
+  const descriptor = resolveSpawnTimeoutDescriptor(spawnName);
+  return emitBlockedCloseResult({
+    storyId,
+    phase: 'closing',
+    reason: reason ?? `${spawnName}-timeout`,
+    extra: {
+      gateName: spawnName,
+      exitCode: exitCode ?? 124,
+      timeoutMs,
+      commentId,
+    },
+    bus,
+    progress: log,
+    blockedMessage: `Story #${storyId} blocked: \`${spawnCmd || descriptor.defaultCmd}\` exceeded ${timeoutMs ?? 'configured'}ms — flipped to ${STATE_LABELS.BLOCKED}.`,
+    logger: Logger,
+  });
+}

package/.agents/scripts/lib/orchestration/story-close/phases/timeout-blocked.js

@@ -0,0 +1,157 @@
+/**
+ * phases/timeout-blocked.js — pure timeout-classification helpers for
+ * the story-close phase pipeline (Story #2460, Epic #2453).
+ *
+ * Holds the spawn-timeout descriptor table, the reason-token map, the
+ * config → timeout-ms resolver, and the friction-comment body renderers.
+ * The side-effecting emit (label transition + comment upsert + bus emit)
+ * lives in the sibling `timeout-blocked-emitter.js` so this file stays
+ * pure and easy to test.
+ *
+ * Public surface (all exported; re-exported by story-close.js for
+ * historical test imports):
+ *   - SPAWN_TIMEOUT_DESCRIPTORS
+ *   - resolveSpawnTimeoutDescriptor(name)
+ *   - resolveSpawnTimeoutReason(name)
+ *   - resolveSpawnTimeoutMs(name, config)
+ *   - renderSpawnTimeoutFrictionBody(input)
+ *   - renderCoverageTimeoutFrictionBody(input)
+ */
+
+import { getQuality } from '../../../config-resolver.js';
+
+/**
+ * Story #2165 — known spawn-timeout dispatch table. Each entry names the
+ * spawn whose bounded-timeout watchdog tripped and the `.agentrc.json`
+ * config key the operator tunes to raise the budget.
+ */
+export const SPAWN_TIMEOUT_DESCRIPTORS = Object.freeze({
+  'coverage-capture': Object.freeze({
+    displayName: 'Coverage capture',
+    defaultCmd: 'npm run test:coverage',
+    configKey: 'delivery.quality.gates.coverage.timeoutMs',
+    summary: 'The `coverage-capture` pre-merge gate',
+  }),
+  'check-maintainability': Object.freeze({
+    displayName: 'Maintainability baseline refresh',
+    defaultCmd: 'npm run maintainability:update',
+    configKey: 'delivery.quality.gates.maintainability.refreshTimeoutMs',
+    summary: 'The `check-maintainability` baseline-refresh path',
+  }),
+  'check-crap': Object.freeze({
+    displayName: 'CRAP baseline refresh',
+    defaultCmd: 'npm run crap:update',
+    configKey: 'delivery.quality.gates.crap.refreshTimeoutMs',
+    summary: 'The `check-crap` baseline-refresh path',
+  }),
+  'format-autofix': Object.freeze({
+    displayName: 'Format autofix',
+    defaultCmd: 'npx biome format --write .',
+    configKey: 'delivery.quality.formatAutofix.timeoutMs',
+    summary: 'The pre-gate `format-autofix` step',
+  }),
+});
+
+const DEFAULT_TIMEOUT_DESCRIPTOR = Object.freeze({
+  displayName: 'Close-time spawn',
+  defaultCmd: '<unknown>',
+  configKey: 'delivery.quality.<gate>.timeoutMs',
+  summary: 'A close-time spawn',
+});
+
+export function resolveSpawnTimeoutDescriptor(spawnName) {
+  return SPAWN_TIMEOUT_DESCRIPTORS[spawnName] ?? DEFAULT_TIMEOUT_DESCRIPTOR;
+}
+
+/**
+ * Story #2241 / Task #2247 — map a spawn-timeout name to the canonical
+ * `story.blocked.reason` token the lifecycle bus emits.
+ */
+const SPAWN_TIMEOUT_REASONS = Object.freeze({
+  'coverage-capture': 'timeout:coverage-capture',
+  'check-maintainability': 'timeout:baseline-refresh',
+  'check-crap': 'timeout:baseline-refresh',
+  'format-autofix': 'timeout:biome-format',
+});
+
+export function resolveSpawnTimeoutReason(spawnName) {
+  return (
+    SPAWN_TIMEOUT_REASONS[spawnName] ?? `timeout:${spawnName ?? 'unknown'}`
+  );
+}
+
+/**
+ * Story #2165 — resolve the timeout (ms) the upstream watchdog enforced
+ * for the named spawn. Best-effort: a missing/invalid resolver returns
+ * `null`.
+ */
+export function resolveSpawnTimeoutMs(spawnName, config) {
+  try {
+    const quality = getQuality(config);
+    switch (spawnName) {
+      case 'coverage-capture':
+        return quality?.coverage?.timeoutMs ?? null;
+      case 'check-maintainability':
+        return quality?.maintainability?.refreshTimeoutMs ?? null;
+      case 'check-crap':
+        return quality?.crap?.refreshTimeoutMs ?? null;
+      case 'format-autofix':
+        return quality?.formatAutofix?.timeoutMs ?? null;
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render the friction-comment body posted on the Story ticket when one of
+ * the close-time spawns trips the bounded-timeout watchdog (exit 124).
+ */
+export function renderSpawnTimeoutFrictionBody({
+  storyId,
+  epicId,
+  timeoutMs,
+  spawnName = 'coverage-capture',
+  spawnCmd,
+}) {
+  const descriptor = resolveSpawnTimeoutDescriptor(spawnName);
+  const cmd = spawnCmd || descriptor.defaultCmd;
+  const seconds = Math.round((timeoutMs ?? 0) / 1000);
+  const minutes = Math.round((seconds / 60) * 10) / 10;
+  const budget = timeoutMs
+    ? `${timeoutMs}ms (~${minutes} min)`
+    : 'configured budget';
+  return [
+    `### ${descriptor.displayName} timed out`,
+    '',
+    `${descriptor.summary} spawned \`${cmd}\` for Story #${storyId} (Epic #${epicId ?? 'unknown'}) and the bounded watchdog killed the child after ${budget}.`,
+    '',
+    `**Exit code:** 124 (GNU \`timeout(1)\` convention — surfaced when \`spawnSync\` returns with \`signal: 'SIGKILL'\`).`,
+    '',
+    `**Next actions:**`,
+    `- Re-run \`${cmd}\` locally inside the Story worktree to confirm the hang.`,
+    `- If the command is honestly slow, raise \`${descriptor.configKey}\` in \`.agentrc.json\` and re-close.`,
+    `- If a deadlock or runaway loop is the cause, isolate the offending input and fix the underlying hang.`,
+    '',
+    `Story label has been flipped to \`agent::blocked\`. Resume by transitioning back to \`agent::executing\` after the underlying issue is fixed.`,
+  ].join('\n');
+}
+
+/**
+ * Backwards-compatible wrapper for the coverage-capture timeout body
+ * (Story #2136 / Task #2143).
+ */
+export function renderCoverageTimeoutFrictionBody({
+  storyId,
+  epicId,
+  timeoutMs,
+}) {
+  return renderSpawnTimeoutFrictionBody({
+    storyId,
+    epicId,
+    timeoutMs,
+    spawnName: 'coverage-capture',
+  });
+}