refactor(engine): type capture failures

[jrusso1020]

What

Replace message-parsed capture retry policy with typed CaptureFailure values and peer abort.

Why

Stringified worker errors lost causes and let sibling workers continue after fatal authoring failures.

How

Classify cancellation, browser, protocol, memory, verification, authoring, and IO failures; preserve diagnostics and abort peers on the first fatal kind.

Test plan

• capture classification and parallel peer-abort tests; producer capture-stage tests
• Stack-wide lint, format, build, typecheck, and relevant integration gates

[jrusso1020]

• refactor(repo): resolve changed-code audit #2174
• test(engine): isolate peer abort regression #2173
• refactor(cli): decompose render phases #2172
• refactor(cli): centralize process lifecycle #2171
• fix(cloudrun): publish adapter contract #2170
• test(repo): execute packed subpaths #2169
• refactor(repo): centralize package subpaths #2168
• refactor(core): own edit protocol contract #2167
• test(compiler): enforce preview render parity #2166
• refactor(studio): gate SDK operation families #2165
• refactor(studio): gate Acorn writer migration #2164
• refactor(producer): make capture plans immutable #2163
• refactor(producer): unify render requests #2162
• refactor(engine): type capture failures #2161 👈 (View in Graphite)
• refactor(engine): manage child process lifecycles #2160
• refactor(engine): add fingerprinted browser leases #2159
• refactor(render): centralize execution ownership #2158
• refactor(core): unify composition contract #2157
• fix(studio): enforce optimistic file concurrency #2156
• fix(studio): make sdk cutover transactional #2155
• fix(render): publish artifacts atomically #2154
• fix(render): surface structured outcomes #2153
• fix(player): own connection and media resources #2152
• fix(core): preserve runtime transport contract #2151
• fix(player): version runtime protocol #2150
• test(repo): verify packed consumers #2149
• test(repo): enforce workspace contracts #2148
• fix(core): enforce strict runtime safety #2147
• test(producer): gate source tests by execution lane #2146
• fix(core): make timing masks safe for source loaders #2145
• chore(repo): forbid tracked generated artifacts #2144
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

The typed failure boundary is a strong improvement overall: cancellation is authoritative, worker diagnostics stay immutable and attached to the representative failure, and the first fatal worker now stops sibling capture without hiding cleanup. The linear same-line I/O scan and 100k-character adversarial test also close the CodeQL finding without broadening classification.

One retry regression remains:

• [P1] Preserve retryability for the drawElement worker watchdog timeout — packages/engine/src/services/captureFailure.ts:57-64 enumerates protocol timeout strings but omits the engine's own drawElement worker encode timed out (frame N) failure. That error is produced by the 30-second lost-message/OOM-killed-worker watchdog at packages/engine/src/services/drawElementService.ts:674-684 (and the batch sibling at :901-906), then propagates through captureFrameRange's awaited encodeResult. On this exact head, classifyCaptureFailure(new Error("drawElement worker encode timed out (frame 42)")) returns authoring, so parallelCoordinator.ts:594-598 treats it as fatal and aborts peers, while renderOrchestrator.ts:817-821 refuses the worker-halving retry. Before this PR, the broad timed out recovery matcher covered this concrete failure. Please classify this exact watchdog failure as non-fatal/retryable and pin both classification and recovery behavior with a regression test.

Exact head reviewed: 9ad957786d14040f72b87ac2f72ac59a028e6f90. All exact-head required checks are green; this is a code-contract blocker rather than a CI failure.

Verdict: REQUEST CHANGES
Reasoning: The typed model and peer-abort mechanism are sound, but a real engine-generated worker timeout regresses from retryable to fatal, causing avoidable render failures instead of the prior recovery path.

— Magi

[jrusso1020]

Fixed Magi’s P1 on exact head 5da9f7ab3d53d7b5b95f216d63532f20cb6036dd.

• Added a narrowly scoped drawElement worker encode timed out (frame N) protocol-timeout classification, preserving non-fatal peer behavior and Producer’s worker-halving retry.
• Added direct Engine classification coverage and a wrapped [Parallel] Capture failed Producer recovery regression.
• Validation: Engine classification 13/13; full Producer render-orchestrator 142/142; full Engine 1,131 passed / 3 skipped; Engine and Producer typechecks; lint/format/tracked-artifact/fallow hooks; package-subpath sync; full workspace build on exact restacked top 4deb4510c18b79c95b8c5dc1a64420257c437a03.
• PRs refactor(engine): type capture failures #2161–refactor(repo): resolve changed-code audit #2174 were restacked and republished. Exact head remains on live main c268f5ba8 with behind_by: 0 and merge base exactly live main.

Fresh exact-head CI is running. This is a substantive head change and requires a fresh exact-head review after all required checks are green.

[miguel-heygen]

Fresh exact-head re-review at 5da9f7ab3d53d7b5b95f216d63532f20cb6036dd.

The prior blocker is resolved:

• packages/engine/src/services/captureFailure.ts:57-66 now recognizes only the concrete drawElement worker encode timed out (frame N) watchdog signature as protocol_timeout; direct execution on this head returns { kind: "protocol_timeout", fatal: false }.
• packages/producer/src/services/renderOrchestrator.ts:817-821 therefore retains the worker-halving recovery path, and packages/producer/src/services/renderOrchestrator.test.ts:1505-1525 pins the wrapped [Parallel] Capture failed boundary rather than testing only the inner classifier.

The broader design remains sound: cancellation wins over an existing typed failure at captureFailure.ts:136-142; worker-local causes and diagnostics are preserved at parallelCoordinator.ts:493-506; and the first genuinely fatal failure aborts peers while Promise.all still waits for their teardown at parallelCoordinator.ts:589-637. The linear same-line I/O classifier retains its 100k-character adversarial regression. I also swept the engine/Producer timeout emitters again; no remaining capture-path timeout lost the old retry contract.

Verification: Engine classifier suite 13/13 locally; exact-head GitHub checks report 40 success, 8 intentional skips, 0 pending/failing; PR is mergeable and based exactly on live main.

Verdict: APPROVE
Reasoning: The exact watchdog regression is fixed narrowly and covered at both the Engine classification and Producer recovery boundaries; the typed failure and peer-abort contracts now preserve prior retry behavior without reintroducing broad string matching.

— Magi