mandrel 1.57.0 → 1.59.0

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -25,8 +25,9 @@
  * therefore validates each Story against the **simulated post-predecessor
  * tree** — base-branch existence overlaid with the create/delete delta of
  * the Story's transitive `depends_on` predecessors (the same reachability
- * walk the conflict gate uses, imported from `ticket-validator-conflicts.js`
- * rather than re-derived). Two extra wave-aware rules layer on top of the
+ * walk the conflict gate uses, imported from the shared
+ * `story-reachability.js` leaf rather than re-derived). Two extra
+ * wave-aware rules layer on top of the
  * base-branch rules:
  *   - `creates`            + path created by a **predecessor** → mismatch
  *     (`expected: 'refactors-existing'`) telling the planner to declare
@@ -48,8 +49,8 @@
 import { gitSpawn } from '../git-utils.js';
 import { parse as parseStoryBody } from '../story-body/story-body.js';
 import { FILE_ASSUMPTION_VALUES } from './file-assumption-enum.js';
+import { computeStoryReachability } from './story-reachability.js';
 import { isObjectPathEntry } from './task-body-validator.js';
-import { computeStoryReachability } from './ticket-validator-conflicts.js';
 
 /**
  * Default git probe — returns `true` when `path` exists at

package/.agents/scripts/lib/orchestration/lease-guard-shared.js

@@ -0,0 +1,144 @@
+/**
+ * lease-guard-shared.js — Story #3992: single-source the lease-acquisition
+ * kernel shared by the three per-surface lease guards.
+ *
+ * `epic-deliver-lease-guard.js`, `epic-plan-lease-guard.js`, and
+ * `single-story-lease-guard.js` historically each carried their own copy of
+ * the operator-handle resolution and the fail-closed acquire wrapper around
+ * `ticket-lease.acquireLease` (anchor `heartbeatAt` to `now` so a foreign
+ * assignee always reads as a live claim, then throw an operator-facing
+ * refusal naming the current owner unless `--steal`). The three copies had
+ * already diverged — different `resolveOperator` signatures and different
+ * missing-handle behaviour (`null` vs `throw`) — and were synchronised only
+ * by docstring promise ("This mirrors the sibling lease guards…").
+ *
+ * This module is the single home for the kernel, modelled on the
+ * shared plumbing inside `story-close/format-autofix.js` (Story #3332,
+ * consolidated by Story #4017). The
+ * per-surface guards now differ only in injected **policy**:
+ *
+ *   - **Operator candidates** — each surface supplies its own ordered
+ *     candidate list (e.g. `--as` flag → `github.operatorHandle` →
+ *     `git user.email` for `/epic-deliver`; bare `operatorHandle` for the
+ *     plan/standalone paths).
+ *   - **Missing-handle behaviour** — `'null'` (return null; the caller fails
+ *     closed at acquire time) vs `'throw'` (refuse immediately with surface
+ *     wording). The divergence between the plan path (`null`) and the
+ *     standalone path (`throw`) is intentional: the plan path also calls
+ *     `resolveOperator` on its best-effort release leg, where a missing
+ *     handle must degrade to a `no-operator` no-op rather than throw.
+ *   - **Refusal wording** — each surface renders its own operator-facing
+ *     message via `renderRefusal(result, ticketId)`.
+ *   - **Liveness anchoring** — the plan/standalone paths have no heartbeat
+ *     ledger, so they anchor `heartbeatAt` to `now` (fail-closed: every
+ *     foreign claim reads live). `/epic-deliver` threads a real
+ *     `heartbeatAt` through from the lifecycle ledger, so it opts out of
+ *     anchoring.
+ *
+ * The unclaimed / already-held / foreign-claim decision table itself (and
+ * the steal transfer) lives in `ticket-lease.acquireLease`; this kernel owns
+ * the fail-closed parameterisation and the refuse-by-throw boundary that the
+ * three guards previously each re-implemented.
+ *
+ * Per `.agents/rules/orchestration-error-handling.md`, failures surface via
+ * `throw new Error(...)`, never `Logger.fatal`.
+ */
+
+import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
+
+/**
+ * Resolve the operator handle from an ordered candidate list, applying the
+ * surface's missing-handle policy.
+ *
+ * Each candidate is passed through the shared `normalizeOperatorHandle` so a
+ * leading `@` is stripped (the assignees API expects bare logins, not
+ * `@`-prefixed mentions) and the shipped `@[USERNAME]` placeholder maps to
+ * `null` — otherwise the assignee PATCH is rejected (HTTP 422) and the
+ * self-held-claim comparison (`owner === operator`) never matches. The first
+ * candidate that normalises to a non-null handle wins.
+ *
+ * @param {object} opts
+ * @param {Array<string|null|undefined>} opts.candidates  Ordered raw handles.
+ * @param {'null'|'throw'} [opts.missingHandleBehavior='null']  What to do
+ *   when no candidate resolves: return `null`, or throw with the surface's
+ *   configured wording.
+ * @param {string} [opts.missingHandleMessage]  Error message used when
+ *   `missingHandleBehavior` is `'throw'`.
+ * @returns {string|null} Bare operator handle, or `null` (policy `'null'`).
+ * @throws {Error} When no candidate resolves and the policy is `'throw'`.
+ */
+export function resolveOperatorFromCandidates({
+  candidates,
+  missingHandleBehavior = 'null',
+  missingHandleMessage,
+} = {}) {
+  for (const raw of candidates ?? []) {
+    const normalized = normalizeOperatorHandle(raw);
+    if (normalized !== null) return normalized;
+  }
+  if (missingHandleBehavior === 'throw') {
+    throw new Error(missingHandleMessage);
+  }
+  return null;
+}
+
+/**
+ * Acquire a ticket lease, failing closed by throwing the surface's refusal
+ * message when the claim is refused (live foreign owner, no `steal`).
+ *
+ * When `anchorHeartbeatToNow` is set (the plan/standalone paths, which have
+ * no heartbeat ledger), `heartbeatAt` and `now` are both anchored to the
+ * same resolved clock value so `isClaimLive` returns true for ANY foreign
+ * owner — `acquireLease` then refuses a foreign assignee unless `steal` is
+ * set, while unclaimed and self-held tickets still proceed without a write.
+ * When unset (`/epic-deliver`), the caller-supplied `heartbeatAt` / `now`
+ * pass through untouched.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider          Ticketing provider.
+ * @param {number} opts.ticketId          Ticket to claim.
+ * @param {string} opts.operator          Resolved operator handle.
+ * @param {number|null} [opts.heartbeatAt=null]  Current owner's last
+ *   heartbeat (epoch ms). Ignored when `anchorHeartbeatToNow` is set.
+ * @param {boolean} [opts.steal=false]    Forcibly transfer a foreign claim.
+ * @param {object} [opts.config]          Resolved config (TTL default).
+ * @param {number} [opts.now]             Injectable clock (epoch ms; tests).
+ * @param {boolean} [opts.anchorHeartbeatToNow=false]  Fail-closed liveness
+ *   anchoring for surfaces with no heartbeat source.
+ * @param {(result: object, ticketId: number) => string} opts.renderRefusal
+ *   Renders the operator-facing refusal message for a refused claim.
+ * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
+ * @throws {Error} When the claim is refused (`result.acquired === false`).
+ */
+export async function acquireLeaseFailClosed({
+  provider,
+  ticketId,
+  operator,
+  heartbeatAt = null,
+  steal = false,
+  config,
+  now,
+  anchorHeartbeatToNow = false,
+  renderRefusal,
+}) {
+  let resolvedHeartbeatAt = heartbeatAt;
+  let resolvedNow = now;
+  if (anchorHeartbeatToNow) {
+    resolvedNow =
+      typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+    resolvedHeartbeatAt = resolvedNow;
+  }
+  const result = await acquireLease({
+    provider,
+    ticketId,
+    operator,
+    heartbeatAt: resolvedHeartbeatAt,
+    steal,
+    config,
+    now: resolvedNow,
+  });
+  if (!result.acquired) {
+    throw new Error(renderRefusal(result, ticketId));
+  }
+  return result;
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-heartbeat.js

@@ -23,8 +23,8 @@
  *
  * The schema declares `additionalProperties: false`, so this emitter's
  * signature is deliberately narrow: only the schema-allowed fields are
- * accepted. Earlier per-child counters (`taskId`, `tasksDone`,
- * `tasksTotal`, `currentTaskId`) were dropped under Epic #3078's
+ * accepted. The earlier per-child Task id and progress counters
+ * were dropped under Epic #3078's
  * 3-tier hard cutover — they would fail strict validation and have no
  * meaning now that the Story is the leaf execution unit with no child
  * tickets. The optional `operator` field (Story #3480) records the handle

package/.agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js

@@ -109,7 +109,7 @@ export const extractPrNumber = parsePrNumberFromUrl;
  *
  * Exported so tests can stub.
  */
-export function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     [
@@ -134,7 +134,7 @@ export function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * can detect the BEHIND condition (PR head is behind its base branch)
  * AFTER every required check is green. Exported so tests can stub.
  */
-export function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     ['pr', 'view', prUrl, '--json', 'mergeStateStatus'],
@@ -154,7 +154,7 @@ export function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
  * BEHIND" (the conservative recovery branch). Pure — exported for
  * tests.
  */
-export function parseMergeStateStatus(stdout) {
+function parseMergeStateStatus(stdout) {
   const trimmed = String(stdout ?? '').trim();
   if (trimmed.length === 0) return '';
   try {
@@ -172,7 +172,7 @@ export function parseMergeStateStatus(stdout) {
  * loop to fast-forward the PR head with its base branch. Exported so
  * tests can stub and assert call counts.
  */
-export function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn('gh', ['pr', 'update-branch', prUrl], {
     cwd,
     encoding: 'utf-8',
@@ -192,7 +192,7 @@ export function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
  * the same definition as the downstream predicate. Pure — exported
  * for tests.
  */
-export const GREEN_CHECK_OUTCOMES = Object.freeze(
+const GREEN_CHECK_OUTCOMES = Object.freeze(
   new Set(['success', 'neutral', 'skipped']),
 );
 
@@ -202,7 +202,7 @@ export const GREEN_CHECK_OUTCOMES = Object.freeze(
  * regardless of mergeStateStatus, so we never auto-recover into a
  * failing PR.
  */
-export function allGreen(outcomes) {
+function allGreen(outcomes) {
   const values = Object.values(outcomes);
   if (values.length === 0) return false;
   for (const v of values) {
@@ -271,7 +271,7 @@ export function allTerminal(outcomes) {
  * behaviour is reviewable. Called only when the poll loop exits via
  * the iteration cap.
  */
-export function promotePendingToTimedOut(outcomes) {
+function promotePendingToTimedOut(outcomes) {
   const out = {};
   for (const [k, v] of Object.entries(outcomes)) {
     out[k] = v === 'pending' ? 'timed_out' : v;

package/.agents/scripts/lib/orchestration/post-merge/phases/notification.js

@@ -21,7 +21,7 @@ export async function notificationPhase(ctx, state) {
     storyId,
     story,
     epicBranch,
-    orchestration,
+    config,
     progress,
     provider,
     notifyFn = notify,
@@ -39,7 +39,7 @@ export async function notificationPhase(ctx, state) {
       level: 'story',
       epicId,
     },
-    { orchestration },
+    { config },
   );
   // Fire a rolled-up `epic-progress` webhook so operators see the Epic's
   // overall stories-done count tick up at each story-close, without
@@ -66,7 +66,7 @@ export async function notificationPhase(ctx, state) {
           level: 'epic',
           epicId,
         },
-        { orchestration, skipComment: true },
+        { config, skipComment: true },
       );
     } catch (err) {
       logger?.warn?.(

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -54,9 +54,9 @@ function findStillRegisteredEntry(entries, storyId) {
   });
 }
 
-function resolveWorktreeRoot(repoRoot, orchestration) {
+function resolveWorktreeRoot(repoRoot, delivery) {
   if (!repoRoot) return null;
-  const configuredRoot = orchestration?.worktreeIsolation?.root ?? '.worktrees';
+  const configuredRoot = delivery?.worktreeIsolation?.root ?? '.worktrees';
   return path.join(repoRoot, configuredRoot);
 }
 
@@ -263,7 +263,7 @@ function logStaleRegistryEntry({ state, stillRegistered, logger }) {
 
 export async function worktreeReapPhase(ctx) {
   const {
-    orchestration,
+    delivery,
     storyId,
     epicId,
     epicBranch,
@@ -276,7 +276,7 @@ export async function worktreeReapPhase(ctx) {
     recordPendingCleanupFn = recordPendingCleanup,
     pathExistsFn = fs.existsSync,
   } = ctx;
-  const wtConfig = orchestration?.worktreeIsolation;
+  const wtConfig = delivery?.worktreeIsolation;
   const log = reapPhaseLogger(progress);
   const skipState = resolveSkipState(wtConfig, log);
   if (skipState) return skipState;
@@ -309,7 +309,7 @@ export async function worktreeReapPhase(ctx) {
     stillRegistered,
     reapResult,
     storyId,
-    orchestration,
+    delivery,
     repoRoot,
     logger,
     recordPendingCleanupFn,
@@ -352,7 +352,7 @@ function applyStillRegisteredState({
   stillRegistered,
   reapResult,
   storyId,
-  orchestration,
+  delivery,
   repoRoot,
   logger,
   recordPendingCleanupFn,
@@ -370,7 +370,7 @@ function applyStillRegisteredState({
       reason: 'still-registered-after-reap',
     };
   }
-  const worktreeRoot = resolveWorktreeRoot(repoRoot, orchestration);
+  const worktreeRoot = resolveWorktreeRoot(repoRoot, delivery);
   let manifestEntry = null;
   if (worktreeRoot) {
     try {

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -53,28 +53,51 @@ export function preflightCachePath({ epicId, cwd }) {
 }
 
 /**
- * Stable string fingerprint of an Epic snapshot. The hash is keyed on the
- * exact fields `runSnapshotPhase` reads (`getTicket(epicId)` return value)
- * so that any drift the snapshot phase would observe forces a cache miss.
+ * Per-ticket fingerprint fields shared by the Epic and each Story in the
+ * cache key: id, body, sorted labels, and updatedAt. Story bodies carry
+ * the dependency edges, so hashing them means a Story-dependency edit
+ * forces a cache miss (Story #4019 — the previous Epic-only key let
+ * dependency edits slip through unnoticed).
+ *
+ * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} ticket
+ * @returns {{ id: number|string|null, body: string, labels: string[], updatedAt: string|null }}
+ */
+function ticketFingerprint(ticket) {
+  const t = ticket && typeof ticket === 'object' ? ticket : {};
+  return {
+    id: t.id ?? t.number ?? null,
+    body: typeof t.body === 'string' ? t.body : '',
+    labels: Array.isArray(t.labels) ? [...t.labels].map(String).sort() : [],
+    updatedAt: typeof t.updatedAt === 'string' ? t.updatedAt : null,
+  };
+}
+
+/**
+ * Stable string fingerprint of an Epic snapshot **plus its Story
+ * dependency state**. The hash is keyed on the exact fields
+ * `runSnapshotPhase` reads (`getTicket(epicId)` return value) and on each
+ * Story's id/body/labels/updatedAt, so that any drift the snapshot or
+ * wave-DAG phases would observe — including a Story-dependency edit —
+ * forces a cache miss (Story #4019).
  *
  * Labels are sorted to absorb GitHub's non-deterministic label order
- * across responses. The hash is sha256; we return the full hex digest so
+ * across responses; stories are sorted by id so enumeration order never
+ * perturbs the key. The hash is sha256; we return the full hex digest so
  * the cache key is collision-resistant for the lifetime of a delivery.
  *
  * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} epic
+ * @param {Array<{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }>} [stories]
  * @returns {string}
  */
-export function computeBaseSha(epic) {
+export function computeBaseSha(epic, stories = []) {
   if (!epic || typeof epic !== 'object') {
     throw new TypeError('computeBaseSha: epic snapshot must be an object');
   }
-  const id = epic.id ?? epic.number ?? null;
-  const body = typeof epic.body === 'string' ? epic.body : '';
-  const labels = Array.isArray(epic.labels)
-    ? [...epic.labels].map(String).sort()
-    : [];
-  const updatedAt = typeof epic.updatedAt === 'string' ? epic.updatedAt : null;
-  const payload = JSON.stringify({ id, body, labels, updatedAt });
+  const epicPrint = ticketFingerprint(epic);
+  const storyPrints = (Array.isArray(stories) ? stories : [])
+    .map(ticketFingerprint)
+    .sort((a, b) => Number(a.id ?? 0) - Number(b.id ?? 0));
+  const payload = JSON.stringify({ ...epicPrint, stories: storyPrints });
   return createHash('sha256').update(payload).digest('hex');
 }
 

package/.agents/scripts/lib/orchestration/review-providers/codex.js

@@ -31,6 +31,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { parseProviderFindings } from './parse-findings.js';
 import { renderDepthDirective } from './review-depth.js';
 
 /**
@@ -173,66 +174,10 @@ export function mapCodexSeverity(raw) {
  * @throws {Error} when stdout is not parseable JSON.
  */
 export function parseCodexFindings(rawStdout) {
-  const text = (rawStdout ?? '').trim();
-  if (text.length === 0) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    throw new Error(
-      `[codex-review] Failed to parse /codex:review stdout as JSON: ${
-        err?.message ?? err
-      }`,
-    );
-  }
-
-  // Unwrap a single layer of envelope when present.
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-    else if (parsed.result !== undefined) parsed = parsed.result;
-    else if (parsed.data !== undefined) parsed = parsed.data;
-  }
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-  }
-
-  if (!Array.isArray(parsed)) return [];
-
-  /** @type {Finding[]} */
-  const findings = [];
-  for (const entry of parsed) {
-    if (!entry || typeof entry !== 'object') continue;
-    const title =
-      typeof entry.title === 'string' && entry.title.trim().length > 0
-        ? entry.title.trim()
-        : null;
-    const body =
-      typeof entry.body === 'string' && entry.body.trim().length > 0
-        ? entry.body
-        : typeof entry.message === 'string' && entry.message.trim().length > 0
-          ? entry.message
-          : null;
-    if (!title || !body) continue;
-
-    /** @type {Finding} */
-    const finding = {
-      severity: mapCodexSeverity(entry.severity),
-      title,
-      body,
-    };
-    if (typeof entry.file === 'string' && entry.file.length > 0) {
-      finding.file = entry.file;
-    }
-    if (Number.isInteger(entry.line) && entry.line > 0) {
-      finding.line = entry.line;
-    }
-    if (typeof entry.category === 'string' && entry.category.length > 0) {
-      finding.category = entry.category;
-    }
-    findings.push(finding);
-  }
-  return findings;
+  return parseProviderFindings(rawStdout, {
+    errorPrefix: '[codex-review] Failed to parse /codex:review stdout as JSON',
+    mapSeverity: mapCodexSeverity,
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -42,14 +42,14 @@
 
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../../config-resolver.js';
-import { runOnPool } from '../../cpu-pool.js';
+import { POOL_SERIAL_THRESHOLD, runOnPool } from '../../cpu-pool.js';
 import { gitSpawn } from '../../git-utils.js';
 import {
   calculateReport,
   classifyReport,
 } from '../../maintainability-engine.js';
-import { transpileIfNeeded } from '../../maintainability-utils.js';
+import { PROJECT_ROOT } from '../../project-root.js';
+import { transpileIfNeeded } from '../../transpile.js';
 import {
   hashCommandConfig,
   recordPass,
@@ -67,10 +67,11 @@ const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
  * `analyzeChangedFiles` scores in-process (the pre-pool serial path). At or
  * above it, per-file `calculateReportForFile` scoring is offloaded to the
  * shared worker pool so the event loop is not blocked during epic-scoped
- * reviews (f-performance). Tuned to match the `SERIAL_THRESHOLD` used by the
- * maintainability baseline scan in `maintainability-utils.js`.
+ * reviews (f-performance). Single-sourced in `cpu-pool.js` (see the
+ * `POOL_SERIAL_THRESHOLD` docstring for the tuning rationale); the
+ * `SERIAL_THRESHOLD` export name is preserved as this module's public API.
  */
-export const SERIAL_THRESHOLD = 8;
+export const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
 const JS_MAINTAINABILITY_EXTS = new Set(['.js', '.mjs', '.cjs']);
 

package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js

@@ -0,0 +1,105 @@
+/**
+ * review-providers/parse-findings.js — shared JSON-findings parser.
+ *
+ * Story #3981 — extracts the verbatim-duplicated parsing logic from
+ * `parseCodexFindings` (codex.js) and `parseSecurityReviewFindings`
+ * (security-review.js) into one templated parser. Both adapters emit
+ * JSON; the parser is liberal in what it accepts:
+ *   - A bare array of finding objects.
+ *   - An object with a `findings` array.
+ *   - Either shape wrapped in an outer envelope with a `result` or
+ *     `data` key (covers minor wire-format drift across versions
+ *     without re-shimming).
+ *
+ * Each entry's severity is funnelled through the caller-supplied
+ * `mapSeverity` so the canonical enum is the only thing that reaches
+ * the renderer. Entries without a `title` or `body` are skipped — the
+ * orchestrator cannot post an empty finding, and silently dropping the
+ * entry is safer than fabricating one.
+ *
+ * Per-provider deltas ride in as options:
+ *   - `errorPrefix`     — prefix for the JSON-parse failure message.
+ *   - `mapSeverity`     — provider severity vocabulary → canonical enum.
+ *   - `defaultCategory` — when set, entries missing a `category` get
+ *     this value (security-review defaults to `'security'`); when
+ *     omitted, `category` is only set when present (codex behavior).
+ *
+ * @typedef {import('./types.js').Finding}  Finding
+ * @typedef {import('./types.js').Severity} Severity
+ */
+
+/**
+ * Parse a provider's raw stdout into `Finding[]`.
+ *
+ * @param {string} rawStdout
+ * @param {{
+ *   errorPrefix: string,
+ *   mapSeverity: (raw: unknown) => Severity,
+ *   defaultCategory?: string,
+ * }} options
+ * @returns {Finding[]}
+ * @throws {Error} when stdout is not parseable JSON.
+ */
+export function parseProviderFindings(rawStdout, options) {
+  const { errorPrefix, mapSeverity, defaultCategory } = options;
+  const text = (rawStdout ?? '').trim();
+  if (text.length === 0) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${errorPrefix}: ${err?.message ?? err}`);
+  }
+
+  // Unwrap a single layer of envelope when present.
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+    else if (parsed.result !== undefined) parsed = parsed.result;
+    else if (parsed.data !== undefined) parsed = parsed.data;
+  }
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+  }
+
+  if (!Array.isArray(parsed)) return [];
+
+  /** @type {Finding[]} */
+  const findings = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== 'object') continue;
+    const title =
+      typeof entry.title === 'string' && entry.title.trim().length > 0
+        ? entry.title.trim()
+        : null;
+    const body =
+      typeof entry.body === 'string' && entry.body.trim().length > 0
+        ? entry.body
+        : typeof entry.message === 'string' && entry.message.trim().length > 0
+          ? entry.message
+          : null;
+    if (!title || !body) continue;
+
+    /** @type {Finding} */
+    const finding = {
+      severity: mapSeverity(entry.severity),
+      title,
+      body,
+    };
+    const category =
+      typeof entry.category === 'string' && entry.category.length > 0
+        ? entry.category
+        : defaultCategory;
+    if (category !== undefined) {
+      finding.category = category;
+    }
+    if (typeof entry.file === 'string' && entry.file.length > 0) {
+      finding.file = entry.file;
+    }
+    if (Number.isInteger(entry.line) && entry.line > 0) {
+      finding.line = entry.line;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}