Serve a PHP error page and auto-recover when a site fails to start

[gcsecsey]

Related issues

• Fixes STU-1370
• Stacked on Bump Playground to 3.1.45 #4230 (the Playground 3.1.45 bump). This branch includes and depends on that bump, since the recovery only works once runCLI() throws instead of calling process.exit(). Review and merge Bump Playground to 3.1.45 #4230 first.

Important

Because this branch includes the 3.1.45 bump, it carries the same npm cooldown as #4230: CI cannot install 3.1.45 until 2026-07-18 (around 04:13 UTC), and local installs need npm install --min-release-age=0 until then.

⚠️ Visual change: needs human review in light + dark mode.

How AI was used in this PR

I used Claude to port the PHP-error recovery from an earlier branch onto current trunk (reconciling a file rename and the evolved ipc-handlers start flow), wire it into the start and stop handlers, and add unit tests for the error classification and parsing. I reviewed the logic and verified typecheck, build, and the tests myself. The end-to-end UX still needs manual verification since it cannot be exercised headless.

Proposed Changes

STU-1370: when a site has a fatal PHP error (for example in a theme or a mu-plugin), starting it should not just fail. The site should come up and show the error, the way the native-PHP runtime already does.

For the Playground (WASM) runtime this cannot be done the native way. Playground warm-boots WordPress at startup, so a fatal aborts the boot and the server never comes up, which means there is no live WordPress to render its own error page. This PR adds a Studio-side recovery that fills that gap:

• When a start fails with a PHP user error (not an infrastructure error such as a WASM-memory or port problem), Studio serves a lightweight error page on the site's port showing the parsed PHP error, and marks the site as running so it is reachable.
• A file watcher retries the start when a .php file changes, so fixing the error auto-recovers the site.
• If the error is introduced while the site is already running, nothing here kicks in. The warm Playground server serves WordPress's own error page per request.

Testing Instructions

Because this branch includes 3.1.45 (still in the npm cooldown), install with the cooldown bypassed. A plain npm install works from 2026-07-18 onward.

• Check out this branch and run npm install --min-release-age=0
• Launch Studio with npm start
• Create a new local WordPress site (or open an existing one), start it, and confirm it loads normally in the browser
• Case 1 (stopped site, error at start): with the site stopped, create wp-content/mu-plugins/fatal.php in the site folder containing <?php trigger_error( 'Intentional fatal for testing', E_USER_ERROR );, then start the site. Expected: the site comes up and serves an error page showing the PHP error, instead of a failure modal.
• Fix it: delete fatal.php. Expected: the file watcher retries and the real site loads automatically.
• Case 2 (running site, error at runtime): with the site running, add the same fatal to a .php file and reload the site in the browser. Expected: WordPress's own error page is served by the warm server.
• Regression: create and start a healthy site with no errors and confirm normal startup is unaffected.

State	Before fix	After fix
Stopped site, start with a PHP error	Cell	Cell
Running site, PHP error introduced at runtime	Cell	Cell
Healthy site (regression)	Cell	Cell

Known issues (draft / WIP)

• A start/stop race can leave the recovery error server holding the site's port, causing EADDRINUSE on a subsequent start. Fix in progress: tear down recovery (releasing the port) before any start, and stop faking the main-process running state.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?
• Confirm the merge date is on or after 2026-07-18 so CI can install 3.1.45 (inherited from Bump Playground to 3.1.45 #4230)