mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-runner/story-run-progress-writer.js

@@ -0,0 +1,400 @@
+/**
+ * story-run-progress-writer — render the per-story progress snapshot.
+ *
+ * Story #3909 — this module no longer **posts** a `story-run-progress`
+ * structured comment. That per-Story comment was the redundant mid-flight
+ * progress surface: an Epic run already keeps the operator-facing
+ * `epic-run-progress` rollup (one comment on the Epic) plus the
+ * `epic-run-state` checkpoint and the lifecycle ledger, and the rollup is
+ * rendered from the checkpoint `waves[]` — it never read the per-Story
+ * comment. The per-Story comment fired at five phase transitions each and
+ * duplicated state already on the labels + ledger, so the comment write was
+ * removed.
+ *
+ * The renderer survives because its `{ body, payload }` output still feeds
+ * two non-comment contracts: the `renderedBody` markdown the `/story-deliver`
+ * and `single-story-deliver` CLIs (`story-phase.js`, `story-deliver-prepare.js`)
+ * relay to chat so the operator sees the phase table inline, and the snapshot
+ * payload returned in those CLIs' JSON envelopes. `upsertStoryRunProgress`
+ * therefore renders-only: it computes the body/payload and (optionally) mirrors
+ * a low-severity webhook event, but writes no GitHub comment.
+ *
+ * Payload shape — per tech spec #902 (kept stable; the CLI envelopes carry it
+ * verbatim):
+ *
+ *   {
+ *     "kind": "story-run-progress",
+ *     "storyId": <number>,
+ *     "branch": "story-<id>",
+ *     "phase": "init|implementing|closing|blocked|done",
+ *     "tasks": [
+ *       { "id": <n>, "title": "...", "state": "done", "commitSha": "abc1234" },
+ *       { "id": <n>, "title": "...", "state": "executing" },
+ *       { "id": <n>, "title": "...", "state": "pending" }
+ *     ],
+ *     "updatedAt": "<iso8601>"
+ *   }
+ */
+
+export const STORY_RUN_PROGRESS_TYPE = 'story-run-progress';
+
+const VALID_TASK_STATES = new Set([
+  'pending',
+  'executing',
+  'done',
+  'blocked',
+  'failed',
+]);
+
+const VALID_PHASES = new Set([
+  'init',
+  'implementing',
+  'closing',
+  'blocked',
+  'done',
+]);
+
+const TASK_STATE_EMOJI = {
+  pending: '⏳',
+  executing: '🔧',
+  done: '✅',
+  blocked: '🚧',
+  failed: '❌',
+};
+
+const PHASE_EMOJI = {
+  init: '🌱',
+  implementing: '🔧',
+  closing: '🔒',
+  blocked: '🚧',
+  done: '✅',
+};
+
+/**
+ * Canonical 3-tier Story-phase order. The Story-phase snapshot replaces the
+ * 4-tier per-Task list when the Story carries inline acceptance (no child
+ * Tasks). Each entry tracks `status` + `startedAt` / `endedAt` so the parent
+ * `/epic-deliver` aggregator can render a coarse progress bar without
+ * walking Task tickets.
+ */
+export const STORY_PHASE_ORDER = ['init', 'implement', 'validate', 'close'];
+
+const VALID_STORY_PHASE_STATUS = new Set(['pending', 'in-progress', 'done']);
+
+const STORY_PHASE_STATUS_EMOJI = {
+  pending: '⏳',
+  'in-progress': '🔧',
+  done: '✅',
+};
+
+/**
+ * Build the canonical default `phases[]` array for a freshly-initialized
+ * 3-tier Story snapshot. All entries are `pending`; timestamps are null.
+ * Exported so call sites (story-deliver-prepare, story-phase) and
+ * tests can build the same shape without re-implementing it.
+ *
+ * @returns {Array<{ name: string, status: 'pending', startedAt: null, endedAt: null }>}
+ */
+export function defaultStoryPhases() {
+  return STORY_PHASE_ORDER.map((name) => ({
+    name,
+    status: 'pending',
+    startedAt: null,
+    endedAt: null,
+  }));
+}
+
+/**
+ * Normalize one Story-phase row into the canonical schema. Timestamps may be
+ * `null` (phase not yet started) or ISO-8601 strings; status is one of
+ * pending | in-progress | done.
+ *
+ * @param {object} phase
+ * @returns {object}
+ */
+function normalizeStoryPhase(phase) {
+  if (!phase || typeof phase !== 'object') {
+    throw new TypeError('story-run-progress phase rows must be objects');
+  }
+  const name = String(phase.name ?? '');
+  if (!STORY_PHASE_ORDER.includes(name)) {
+    throw new RangeError(
+      `story-run-progress invalid phase name "${name}"; ` +
+        `expected one of: ${STORY_PHASE_ORDER.join(', ')}`,
+    );
+  }
+  const status = String(phase.status ?? 'pending');
+  if (!VALID_STORY_PHASE_STATUS.has(status)) {
+    throw new RangeError(
+      `story-run-progress invalid phase status "${status}" for "${name}"; ` +
+        `expected one of: ${[...VALID_STORY_PHASE_STATUS].join(', ')}`,
+    );
+  }
+  return {
+    name,
+    status,
+    startedAt: phase.startedAt == null ? null : String(phase.startedAt),
+    endedAt: phase.endedAt == null ? null : String(phase.endedAt),
+  };
+}
+
+/**
+ * Normalize one Task row into the canonical schema. `commitSha` is only
+ * carried on `done` rows (it has no meaning before the commit lands and is
+ * cleared on rollback).
+ *
+ * @param {object} task
+ * @returns {object}
+ */
+function normalizeTask(task) {
+  if (!task || typeof task !== 'object') {
+    throw new TypeError('story-run-progress task rows must be objects');
+  }
+  const id = Number(task.id ?? task.taskId);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new TypeError(
+      `story-run-progress task row missing valid id: ${JSON.stringify(task)}`,
+    );
+  }
+  const state = String(task.state ?? 'pending');
+  if (!VALID_TASK_STATES.has(state)) {
+    throw new RangeError(
+      `story-run-progress invalid task state "${state}" for task #${id}; ` +
+        `expected one of: ${[...VALID_TASK_STATES].join(', ')}`,
+    );
+  }
+  const row = { id, title: String(task.title ?? ''), state };
+  if (state === 'done' && task.commitSha != null) {
+    row.commitSha = String(task.commitSha);
+  }
+  return row;
+}
+
+/**
+ * Build the markdown body the writer upserts. Pure: no IO, no provider call.
+ * Exported so tests can pin the rendered shape without going through the
+ * upsert path.
+ *
+ * Two shapes are supported, selected by whether `input.phases` (3-tier
+ * Story-phase snapshot) or `input.tasks` (legacy 4-tier per-Task list) is
+ * provided. Callers MUST pass exactly one of the two — passing both is
+ * rejected as a contract violation so a mistake at the call site fails
+ * loudly rather than silently dropping one shape.
+ *
+ * @param {{
+ *   storyId: number,
+ *   branch: string,
+ *   phase: string,
+ *   tasks?: object[],
+ *   phases?: object[],
+ *   updatedAt?: string,
+ * }} input
+ * @returns {{ body: string, payload: object }}
+ */
+export function renderStoryRunProgressBody(input) {
+  const storyId = Number(input?.storyId);
+  if (!Number.isInteger(storyId) || storyId <= 0) {
+    throw new TypeError(
+      'renderStoryRunProgressBody requires a numeric storyId',
+    );
+  }
+  const branch = String(input?.branch ?? '');
+  if (!branch) {
+    throw new TypeError(
+      'renderStoryRunProgressBody requires a non-empty branch',
+    );
+  }
+  const phase = String(input?.phase ?? '');
+  if (!VALID_PHASES.has(phase)) {
+    throw new RangeError(
+      `renderStoryRunProgressBody invalid phase "${phase}"; ` +
+        `expected one of: ${[...VALID_PHASES].join(', ')}`,
+    );
+  }
+
+  const hasPhases = Array.isArray(input.phases);
+  const hasTasks = Array.isArray(input.tasks);
+  if (hasPhases && hasTasks) {
+    throw new TypeError(
+      'renderStoryRunProgressBody: pass either `phases` (3-tier) or `tasks` ' +
+        '(4-tier), not both — the snapshot shape is mutually exclusive.',
+    );
+  }
+
+  const updatedAt = input.updatedAt ?? new Date().toISOString();
+
+  if (hasPhases) {
+    return renderPhasesBody({
+      storyId,
+      branch,
+      phase,
+      phases: input.phases,
+      updatedAt,
+    });
+  }
+  return renderTasksBody({
+    storyId,
+    branch,
+    phase,
+    tasks: input.tasks ?? [],
+    updatedAt,
+  });
+}
+
+/**
+ * Render the 4-tier per-Task body. Pure helper for `renderStoryRunProgressBody`.
+ */
+function renderTasksBody({
+  storyId,
+  branch,
+  phase,
+  tasks: rawTasks,
+  updatedAt,
+}) {
+  const tasks = rawTasks.map(normalizeTask);
+  const payload = {
+    kind: STORY_RUN_PROGRESS_TYPE,
+    storyId,
+    branch,
+    phase,
+    tasks,
+    updatedAt,
+  };
+
+  const done = tasks.filter((t) => t.state === 'done').length;
+  const total = tasks.length;
+  const phaseEmoji = PHASE_EMOJI[phase] ?? '';
+  const header = `### 📖 Story #${storyId} — ${phaseEmoji} ${phase} · ${done}/${total} tasks done`;
+  const tableRows = tasks.length
+    ? [
+        '| ID | State | Title | Commit |',
+        '| --- | --- | --- | --- |',
+        ...tasks.map((t) => {
+          const emoji = TASK_STATE_EMOJI[t.state] ?? '';
+          const commit = t.commitSha
+            ? `\`${String(t.commitSha).slice(0, 7)}\``
+            : '—';
+          const title = String(t.title).replace(/\|/g, '\\|');
+          return `| #${t.id} | ${emoji} ${t.state} | ${title} | ${commit} |`;
+        }),
+      ].join('\n')
+    : '_(no tasks recorded for this story)_';
+
+  const body = [
+    header,
+    '',
+    `Branch: \`${branch}\``,
+    '',
+    tableRows,
+    '',
+    '```json',
+    JSON.stringify(payload, null, 2),
+    '```',
+  ].join('\n');
+
+  return { body, payload };
+}
+
+/**
+ * Render the 3-tier Story-phase body. Pure helper for
+ * `renderStoryRunProgressBody`. Emits a `phases[]` payload whose entries
+ * carry `{ name, status, startedAt, endedAt }` for init/implement/validate/close.
+ */
+function renderPhasesBody({ storyId, branch, phase, phases: raw, updatedAt }) {
+  const phases = raw.map(normalizeStoryPhase);
+  const payload = {
+    kind: STORY_RUN_PROGRESS_TYPE,
+    storyId,
+    branch,
+    phase,
+    phases,
+    updatedAt,
+  };
+
+  const done = phases.filter((p) => p.status === 'done').length;
+  const total = phases.length;
+  const phaseEmoji = PHASE_EMOJI[phase] ?? '';
+  const header = `### 📖 Story #${storyId} — ${phaseEmoji} ${phase} · ${done}/${total} phases done`;
+  const tableRows = phases.length
+    ? [
+        '| Phase | Status | Started | Ended |',
+        '| --- | --- | --- | --- |',
+        ...phases.map((p) => {
+          const emoji = STORY_PHASE_STATUS_EMOJI[p.status] ?? '';
+          const started = p.startedAt ?? '—';
+          const ended = p.endedAt ?? '—';
+          return `| ${p.name} | ${emoji} ${p.status} | ${started} | ${ended} |`;
+        }),
+      ].join('\n')
+    : '_(no phases recorded for this story)_';
+
+  const body = [
+    header,
+    '',
+    `Branch: \`${branch}\``,
+    '',
+    tableRows,
+    '',
+    '```json',
+    JSON.stringify(payload, null, 2),
+    '```',
+  ].join('\n');
+
+  return { body, payload };
+}
+
+/**
+ * Render the story-run-progress snapshot for one phase transition and return
+ * `{ body, payload }` so callers can surface the markdown body to chat and
+ * carry the payload in their JSON envelope. Story #3909 — this no longer posts
+ * a GitHub comment (the redundant mid-flight progress surface was deleted); it
+ * renders only and, when `notify` is supplied, mirrors a low-severity webhook
+ * event for operators who wire one up.
+ *
+ * Two shapes are supported, selected by whether `args.phases` (3-tier
+ * Story-phase snapshot) or `args.tasks` (legacy 4-tier per-Task list) is
+ * provided. The webhook mirror's `done/total` count is computed from whichever
+ * shape is active.
+ *
+ * @param {{
+ *   provider?: import('../../ITicketingProvider.js').ITicketingProvider,
+ *   storyId: number,
+ *   branch: string,
+ *   phase: string,
+ *   tasks?: object[],
+ *   phases?: object[],
+ *   epicId?: number,
+ *   updatedAt?: string,
+ *   notify?: Function,
+ * }} args
+ * @returns {Promise<{ body: string, payload: object }>}
+ */
+export async function upsertStoryRunProgress(args) {
+  const { notify, epicId, provider: _provider, ...rest } = args ?? {};
+  const { body, payload } = renderStoryRunProgressBody(rest);
+  if (typeof notify === 'function') {
+    const isPhases = Array.isArray(payload.phases);
+    const items = isPhases ? payload.phases : payload.tasks;
+    const done = isPhases
+      ? items.filter((p) => p.status === 'done').length
+      : items.filter((t) => t.state === 'done').length;
+    const total = items.length;
+    const unit = isPhases ? 'phases' : 'tasks';
+    const message = `Story #${payload.storyId} · ${payload.phase} · ${done}/${total} ${unit} done`;
+    await Promise.resolve(
+      notify(
+        payload.storyId,
+        {
+          severity: 'low',
+          message,
+          event: STORY_RUN_PROGRESS_TYPE,
+          level: 'story',
+          epicId,
+          phase: payload.phase,
+        },
+        { skipComment: true },
+      ),
+    ).catch(() => {});
+  }
+  return { body, payload };
+}

package/.agents/scripts/lib/orchestration/epic-runner/sub-agent-return.js

@@ -0,0 +1,285 @@
+/**
+ * sub-agent-return.js — parse and reconcile per-Story sub-agent return text.
+ *
+ * `/epic-deliver` Step 2 dispatches one `Agent` tool call per Story per
+ * wave. Each sub-agent owes its parent the JSON return contract documented
+ * in `.agents/workflows/epic-deliver.md`:
+ *
+ *   {
+ *     "storyId": <number>,
+ *     "status": "done" | "blocked" | "failed",
+ *     "phase": "init|implementing|closing|blocked|done",
+ *     "tasksDone": <number>,
+ *     "tasksTotal": <number>,
+ *     "branchDeleted": <boolean>,
+ *     "blockerCommentId": <string|null>,
+ *     "detail": <string|undefined>,
+ *     "renderedBody": <string|undefined>
+ *   }
+ *
+ * On the current model tier a sub-agent that does real work returns the
+ * envelope verbatim; a return that fails to parse is a rare protocol error,
+ * not a normal recovery path. Parsing is therefore strict — an already-parsed
+ * object or a return string that is pure JSON — with **no free-form
+ * extraction heuristics**: the prose-wrapped extraction candidates
+ * (fenced ```json``` blocks, balanced-`{...}`-substring scans, chat-prelude
+ * tolerance) were measured to never fire in practice (Story #3864:
+ * zero malformed terminal returns across the sampled delivered Epics) and
+ * were deleted in a hard cutover. A return that does not parse routes
+ * directly to GitHub-state reconciliation plus a friction record — the
+ * stronger backstop that already caught everything the heuristics caught.
+ *
+ * This module provides the two helpers `/epic-deliver`'s wave dispatcher
+ * now uses:
+ *
+ *   - `parseStoryAgentReturn(raw)` — accept an already-parsed object or a
+ *     return string that is pure JSON, then schema-validate it. Returns
+ *     `{ ok: true, value }` on success, `{ ok: false, error }` otherwise.
+ *
+ *   - `reconcileStoryFromGitHub({ provider, storyId })` — reads the Story
+ *     ticket's labels and `story-run-progress` structured comment to derive
+ *     an authoritative result row. Used as a fallback whenever the
+ *     sub-agent's return text fails to parse. Status is downgraded to
+ *     `failed` unless the live ticket actually carries `agent::done`
+ *     (in which case the operator may have manually closed the Story).
+ */
+
+import { parseFencedJsonComment } from '../structured-comment-parser.js';
+import { findStructuredComment } from '../ticketing.js';
+import { STORY_RUN_PROGRESS_TYPE } from './story-run-progress-writer.js';
+
+const VALID_STATUS = new Set(['done', 'blocked', 'failed']);
+
+/**
+ * Strict parse of a per-Story sub-agent return. Accepts:
+ *   1. an object that already looks parsed, or
+ *   2. a return string that is pure JSON.
+ *
+ * There is no free-form extraction: a string that is not pure JSON (prose,
+ * a fenced block, a chat-prelude + envelope) yields `ok: false` and the
+ * caller MUST reconcile from GitHub. Parsing is strict on both sides —
+ * callers always get a fully-validated object or `ok: false`.
+ *
+ * @param {unknown} raw
+ * @returns {{ ok: true, value: object } | { ok: false, error: string }}
+ */
+export function parseStoryAgentReturn(raw) {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    return validateStoryReturnShape(raw);
+  }
+  if (typeof raw !== 'string') {
+    return {
+      ok: false,
+      error: `expected string or object, got ${raw === null ? 'null' : typeof raw}`,
+    };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: 'empty return text' };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return {
+      ok: false,
+      error: `return text is not a JSON envelope (${quote(trimmed)})`,
+    };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      ok: false,
+      error: `return text parsed to a non-object (${quote(trimmed)})`,
+    };
+  }
+  return validateStoryReturnShape(parsed);
+}
+
+/**
+ * Validate the per-Story return contract. Pure helper — no IO.
+ *
+ * @param {object} obj
+ * @returns {{ ok: true, value: object } | { ok: false, error: string }}
+ */
+function validateStoryReturnShape(obj) {
+  const storyId = Number(obj.storyId ?? obj.id);
+  if (!Number.isInteger(storyId) || storyId <= 0) {
+    return {
+      ok: false,
+      error: `storyId must be a positive integer; got ${JSON.stringify(obj.storyId ?? obj.id)}`,
+    };
+  }
+  const status = String(obj.status ?? '');
+  if (!VALID_STATUS.has(status)) {
+    return {
+      ok: false,
+      error: `status "${status}" must be one of: ${[...VALID_STATUS].join(', ')}`,
+    };
+  }
+  const value = { storyId, status };
+  if (typeof obj.phase === 'string') value.phase = obj.phase;
+  if (Number.isInteger(obj.tasksDone)) value.tasksDone = obj.tasksDone;
+  if (Number.isInteger(obj.tasksTotal)) value.tasksTotal = obj.tasksTotal;
+  if (typeof obj.branchDeleted === 'boolean') {
+    value.branchDeleted = obj.branchDeleted;
+  }
+  if (obj.blockerCommentId != null) {
+    value.blockerCommentId = String(obj.blockerCommentId);
+  }
+  if (typeof obj.detail === 'string') value.detail = obj.detail;
+  if (typeof obj.renderedBody === 'string')
+    value.renderedBody = obj.renderedBody;
+  return { ok: true, value };
+}
+
+function quote(text) {
+  const oneline = text.replace(/\s+/g, ' ').trim();
+  return oneline.length > 120 ? `${oneline.slice(0, 117)}...` : oneline;
+}
+
+/**
+ * Authoritative reconciliation: rebuild a per-Story result row from the
+ * Story ticket's live state when the sub-agent return cannot be trusted.
+ *
+ * The result is always conservative — `status: 'failed'` unless the live
+ * ticket carries `agent::done` (or `state: 'closed'`). The phase / counters
+ * are best-effort, sourced from the Story's `story-run-progress` comment;
+ * absence of the comment is non-fatal.
+ *
+ * Story #3907 — a Story carrying `agent::blocked` reconciles to
+ * `status: 'blocked'`, not `failed`. A garbled / unparseable return from a
+ * genuinely blocked child previously collapsed to `failed`, which erased the
+ * `blockerCommentId` and steered the operator toward the wrong remediation
+ * (re-run vs. resolve-the-blocker). The blocked arm recovers the blocker
+ * comment id from the Story's latest `friction` structured comment so the
+ * wave row carries it through to `epic-run-progress`.
+ *
+ * @param {{
+ *   provider: { getTicket: Function, getTicketComments: Function },
+ *   storyId: number,
+ * }} args
+ * @returns {Promise<{
+ *   storyId: number,
+ *   status: 'done' | 'blocked' | 'failed',
+ *   phase?: string,
+ *   tasksDone?: number,
+ *   tasksTotal?: number,
+ *   blockerCommentId?: string,
+ *   reconciledFromGitHub: true,
+ *   reconcileError?: string,
+ * }>}
+ */
+export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
+  if (!Number.isInteger(storyId) || storyId <= 0) {
+    throw new TypeError(
+      'reconcileStoryFromGitHub: storyId must be a positive integer',
+    );
+  }
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new TypeError(
+      'reconcileStoryFromGitHub: provider.getTicket is required',
+    );
+  }
+
+  let ticket;
+  try {
+    ticket = await provider.getTicket(storyId, { fresh: true });
+  } catch (err) {
+    return {
+      storyId,
+      status: 'failed',
+      reconciledFromGitHub: true,
+      reconcileError: err?.message ?? String(err),
+    };
+  }
+
+  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+  const isDone = labels.includes('agent::done') || ticket?.state === 'closed';
+  const isBlocked = !isDone && labels.includes('agent::blocked');
+  let status = 'failed';
+  if (isDone) status = 'done';
+  else if (isBlocked) status = 'blocked';
+
+  const out = { storyId, status, reconciledFromGitHub: true };
+
+  // Story #3907 — for a blocked Story, recover the blocker comment id from
+  // the latest `friction` structured comment so the operator is routed to the
+  // blocker (and its evidence), not a blind re-run. Best-effort: a missing
+  // friction comment leaves `status: 'blocked'` with no id, which is still
+  // strictly more accurate than the old `failed` downgrade.
+  if (isBlocked) {
+    try {
+      const friction = await findStructuredComment(
+        provider,
+        storyId,
+        'friction',
+      );
+      if (friction && friction.id != null) {
+        out.blockerCommentId = String(friction.id);
+      }
+    } catch (err) {
+      out.reconcileError = err?.message ?? String(err);
+    }
+  }
+
+  // Cross-look the story-run-progress comment for phase / task counters when
+  // present. Story #3909 retired the per-Story story-run-progress *comment*
+  // (the redundant mid-flight surface), so this read now usually finds nothing
+  // and the reconciled row degrades to label-only — which is fine: the labels
+  // are the authoritative state. Failure here is non-fatal.
+  try {
+    const comment = await findStructuredComment(
+      provider,
+      storyId,
+      STORY_RUN_PROGRESS_TYPE,
+    );
+    const payload = comment ? parseFencedJsonComment(comment) : null;
+    if (payload && typeof payload === 'object') {
+      if (typeof payload.phase === 'string') out.phase = payload.phase;
+      if (Array.isArray(payload.tasks)) {
+        out.tasksTotal = payload.tasks.length;
+        out.tasksDone = payload.tasks.filter(
+          (t) => t && t.state === 'done',
+        ).length;
+      }
+    }
+  } catch (err) {
+    out.reconcileError = err?.message ?? String(err);
+  }
+
+  return out;
+}
+
+/**
+ * Render a single friction-comment body listing every malformed sub-agent
+ * return for a given wave. Pure helper — no provider call. Exposed so tests
+ * can pin the body shape.
+ *
+ * @param {{
+ *   epicId: number,
+ *   wave: number,
+ *   failures: Array<{ storyId: number, error: string, returnText: string }>,
+ * }} args
+ * @returns {string}
+ */
+export function renderMalformedReturnsFriction({ epicId, wave, failures }) {
+  const lines = [
+    `### 🚧 epic-execute friction — Epic #${epicId}, wave ${wave}`,
+    '',
+    `**Reason:** \`malformed-subagent-return\``,
+    '',
+    `${failures.length} sub-agent return(s) did not match the /story-deliver return contract.`,
+    'Each Story below was reconciled from GitHub (labels + `story-run-progress`)',
+    'and its wave-row downgraded to `failed` unless the live ticket already carried',
+    '`agent::done`.',
+    '',
+  ];
+  for (const f of failures) {
+    lines.push(`- **Story #${f.storyId}** — ${f.error}`);
+    if (f.returnText) {
+      lines.push(`  Original return: \`${quote(f.returnText)}\``);
+    }
+  }
+  return lines.join('\n');
+}