fix(api): describe a failed snapshot build by its cause, not its tail (DEV-2570)

[demtario]

Problem

A snapshot install/build that failed was described with execTail — the last 800/1200 characters of stderr + stdout. A tail cuts at the front, so the first line of the message was whatever the tool printed last: pnpm's progress counter (DEMOS-1W) or the middle of its self-update box (DEMOS-1Y). Sentry titles an issue from that first line, so neither issue named the failure — and because the message was multi-line, the browser SDK fed lines 2..n to its stack-frame regexes and invented the culprit │ Changelog: (v/11.22).

One failure, two mistitled issues: the Worker files one from the catch-all in index.ts, and the browser files another because describeApiFailure relays body.error verbatim into an ApiError.

Fix

DEV-2533 already solved this for the Tier-2 boot log. Rather than a second copy of those regexes, the rule set moves to packages/runtime/src/failure-log.ts: bootFailureDetail stays as a thin wrapper with the boot defaults (and the same export container-boot-failure.test.mjs imports), and a new execFailureDetail handles the builder's two streams.

Its tiers run across the streams rather than within a concatenation of them — an announced cause on either stream outranks a merely mentioned one on either — because pnpm keeps counting on stdout after diagnosing on stderr, while vite/ng/next report real errors on stdout and leave deprecation noise on stderr. The window, the empty-output wording, and the byte cap on the kept log became options; the boot path keeps its previous behaviour exactly (uncapped tail — capping here would measure the cleaned, redacted string rather than the 2500 bytes the status route already tailed).

runBuild now throws BuildFailure: a one-line message, with the output kept apart in log and the machine code in code, mirroring ContainerBootFailure. The route catch-all reports it under context: snapshot-build, fingerprinted by phase and code so one defect stays one issue, with the log as an extra.

Before / after, on the DEMOS-1W fixture:

install failed: tps://registry.npmjs.org/          <- old rule, and the message continued for 6 more lines
install failed: ERR_PNPM_NO_MATCHING_VERSION  No matching version found for handsontable@13106 …

Rollout

The message changes, so grouping changes: DEMOS-1W and DEMOS-1Y stop receiving events and correctly titled issues appear in their place. Expected, not a regression — resolve both once the successors show up.

Out of scope

The underlying handsontable@13106 install failure is DEMOS-1X / DEV-2565. The duplicate client-side report also stays: describeApiFailure files an issue for every 500, and the single-line message makes that issue readable, which is what this ticket is about; suppressing the duplicate is a separate change.

Verification

• pnpm test — 767 tests, 765 pass, 0 fail, 2 pre-existing todo. 16 new in pipeline/failure-log.test.mjs, each verified red against the old tail rule; container-boot-failure.test.mjs passes unedited, which is the regression guard for the extraction.
• pnpm -r run typecheck — 4 projects clean.
• wrangler deploy --dry-run — the Worker bundles the new @handsontable/demo-runtime/failure-log subpath.
• Not run: the end-to-end acceptance (a real install failure producing an ERR_PNPM_*-titled issue). Needs a deploy.

🤖 Generated with Claude Code

---

Note

^{Cursor Bugbot is generating a summary for commit 0d2d246. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0d2d246. Configure here.}