[t3dotgg]

When the HTML preview browser cannot start because Node throws during spawn (for example spawn UNKNOWN when Windows policy blocks the executable), the agent saw a generic "Internal error" instead of a clear browser error.

Takeover of #21782 by @ScottN-PV. Their commit is kept with its authorship. I kept their catchDefect on the spawn effect and their typed preview error test, and dropped the publish test to keep the PR focused.

The spawn effect now maps a synchronous spawn throw to the existing HtmlRenderBrowserError ("the browser could not be started"), the same error as an async spawn failure. This covers the MCP preview and publish paths, which share launchBrowser. It does not fix the root cause in #21686: a policy-blocked browser location still cannot start, and the error does not name the location.

Proof: HtmlRender.test.ts "reports a typed preview error" points the browser path inside a regular file, so spawn throws ENOTDIR synchronously. It fails on main (defect, not a typed error) and passes here. Ran vp test run apps/server/src/htmlRender/HtmlRender.test.ts and vp run check:changed (all pass). Not checked: a real Windows policy block. The test skips on Windows, where this path fails asynchronously instead.

Refs #21686

Made by Claude Opus 5.5 in Claude Code, running in T3 Code.
🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at 8212834

Macroscope's review found this PR approvable — This is a narrowly scoped server bug fix that normalizes synchronous browser spawn failures into the existing typed preview error while leaving successful rendering unchanged. A focused regression test covers the failure path, and no product defaults or static-analysis overrides are changed.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	4.9 KiB	5.0 KiB	+23 B (+0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+23 B (+1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.8 KiB	20.9 KiB	+41 B (+0.2%)	29.3 KiB	✅
Codex	Live turn messages	1	2	+1 (+100.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	+7 B (+0.1%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+7 B (+0.6%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: e822ba7 · PR result: 8212834 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 25dcfa98-c904-48e4-8395-b39bcdbfee88

📥 Commits

Reviewing files that changed from the base of the PR and between e822ba7 and 8212834.

📒 Files selected for processing: 2

• apps/server/src/htmlRender/HtmlRender.test.ts
• apps/server/src/htmlRender/headlessChrome.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

📝 Walkthrough

Synchronous browser startup failures are converted to HtmlRenderBrowserError. A live test checks the error message and ENOTDIR cause when an invalid browser path is used.

Changes: Browser startup error handling

Layer / File(s)	Summary
Convert and verify startup failures apps/server/src/htmlRender/headlessChrome.ts, apps/server/src/htmlRender/HtmlRender.test.ts	launchBrowser converts synchronous startup defects into HtmlRenderBrowserError with the original cause. A live test checks the error message and ENOTDIR cause for an invalid browser path. The test is skipped on Windows.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: maria-rcks

Merge Risk: ⚪ Minimal · up to 82128

The browser-start error handling is ready to merge after normal checks; no actionable risk remains.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly identifies the server fix: HTML preview now reports a browser-start error instead of a generic internal error.
Description check		The description covers the problem, implementation, scope, issue reference, focused verification commands, observed results, and untested Windows behavior. It also identifies the agent and harness. Th…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description covers the problem, implementation, scope, issue reference, focused verification commands, observed results, and untested Windows behavior. It also identifies the agent and harness. The description is sufficiently complete for this focused bug fix.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}