refactor(envlite): fail loudly on Unix without pcntl; clarify test name

Author: sirreal

tools/local-env/envlite.php

@@ -288,16 +288,23 @@ function envlite_pcntl_exec_available(): bool {
 }
 
 /**
- * Launches the dev server. On Unix with pcntl available, replaces the current
- * process via pcntl_exec — same PID, no parent-child relay. On Windows (or
- * any environment without pcntl_exec), falls back to envlite_proc_stream
- * which inherits stdio so SIGINT still reaches the child. Returns only on
- * error or when the fallback child exits.
+ * Launches the dev server. On Unix, requires pcntl (enforced by Phase 0 at
+ * init time and re-checked here for safety) and replaces the current process
+ * via pcntl_exec — same PID, no parent-child relay. On Windows, falls back
+ * to envlite_proc_stream which inherits stdio so SIGINT still reaches the
+ * child. Returns only on error or when the Windows-fallback child exits.
  */
 function envlite_run_dev_server(string $repoRoot, int $port): int {
     $argv = envlite_dev_server_argv($repoRoot, $port);
 
-    if (envlite_pcntl_exec_available()) {
+    if (PHP_OS_FAMILY !== 'Windows') {
+        if (!function_exists('pcntl_exec')) {
+            // Phase 0 enforces pcntl on Unix, but `serve` skips Phase 0 — so a
+            // checkout cached from a different system could land here. The spec
+            // says Unix uses pcntl_exec; do not silently degrade to proc_open.
+            envlite_log(null, 'pcntl extension is required on Unix; reinstall PHP with pcntl');
+            return 1;
+        }
         // pcntl_exec uses the *current* working directory; chdir first so
         // `-t src` resolves relative to the repo root, matching the proc_open
         // path's $cwd argument.

tools/local-env/tests/test_dev_server.php

@@ -22,8 +22,9 @@ function test_dev_server_argv_does_not_include_php_binary_first() {
 
 function test_dev_server_pcntl_replaces_process_on_unix() {
     if (!envlite_pcntl_exec_available()) {
-        // Windows or pcntl-less Unix: the helper takes the proc_open branch.
-        // Verified separately in test_dev_server_fallback_uses_proc_open.
+        // Windows or pcntl-less Unix: skip the pcntl_exec replacement check.
+        // proc_stream behavior is covered by
+        // test_dev_server_proc_stream_propagates_child_exit_with_dev_server_argv_shape.
         return;
     }
 
@@ -45,10 +46,10 @@ function test_dev_server_pcntl_replaces_process_on_unix() {
     envlite_assert_eq(7, $exit, 'pcntl_exec must replace process; child exit must be 7');
 }
 
-function test_dev_server_fallback_uses_proc_open_when_pcntl_unavailable() {
-    // We can't disable pcntl in-process. Instead, exercise envlite_proc_stream
-    // directly with the same argv shape envlite_run_dev_server constructs for
-    // the Windows fallback, and assert it returns the child's exit code.
+function test_dev_server_proc_stream_propagates_child_exit_with_dev_server_argv_shape() {
+    // pcntl can't be disabled in-process to test the actual fallback selection.
+    // Instead, verify that envlite_proc_stream propagates the child exit code
+    // when called with the argv shape envlite_run_dev_server uses on Windows.
     $argv = array_merge([PHP_BINARY], ['-r', 'exit(0);']);
     $exit = envlite_proc_stream($argv);
     envlite_assert_eq(0, $exit, 'proc_open fallback must propagate child exit code');