posix-kernel: serve mounted docroot via host path on Windows

An earlier iteration created an NTFS junction at <kernel-tempdir>/
wordpress so nginx + php-fpm could reach the user-supplied --mount
via a /dev/shm/.../wordpress POSIX path. The junction is created
without error on Windows Server 2025 / Node 24, but fs.statSync
traversal through it inside the kernel returns ENOENT — PHP's
is_dir / is_file / include all fail, display_errors=off silences
them, the request comes back 200 with empty body.

nginx's POSIX argv parser is the only thing that actually requires
the kernel-shaped path. Once nginx is started, every request goes
through fastcgi_pass, so nginx's `root` directive is only used to
populate $document_root — which we override anyway via a hardcoded
fastcgi_param DOCUMENT_ROOT. Stop relying on the junction: keep
`root` kernel-shaped to satisfy nginx, and hand PHP-FPM the real
host filesystem path through DOCUMENT_ROOT + SCRIPT_FILENAME. The
kernel passes anything outside /dev/shm/ straight to Node fs.*,
which handles Windows-native paths natively.

Also unifies KernelLimitedPHPApi: documentRoot / cwd /
translateVfsPathsInCode all use the host path now; the kernelRoot
field and toKernel helper (introduced for macOS back-translation)
are gone.

Bundles a second Windows-CI fix that accumulated alongside: allocate
a per-boot host port for php-fpm so fileParallelism doesn't
EADDRINUSE on the hard-coded 9000.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mho22

packages/playground/cli/src/posix-kernel/boot.ts

@@ -2,10 +2,11 @@
  * Boot WordPress backed by wasm-posix-kernel.
  *
  * Spawns one Node `worker_thread` that owns the kernel; inside it,
- * php-fpm listens on the kernel's TCP loopback (127.0.0.1:9000) and
- * nginx listens on the user-chosen port (kernel TCP bridge to the host).
- * The returned `runtime` lets blueprint v1 spawn additional `php.wasm`
- * CLI processes against the same worker, capturing their stdout/stderr.
+ * php-fpm listens on a per-boot host-reserved port and nginx listens
+ * on the user-chosen port (both via the kernel's TCP bridge to the
+ * host — see `kernel-worker.ts:startTcpListener`). The returned
+ * `runtime` lets blueprint v1 spawn additional `php.wasm` CLI
+ * processes against the same worker, capturing their stdout/stderr.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
@@ -17,6 +18,7 @@ import {
 	type NodeKernelHost,
 	type SpawnOptions,
 } from './host-bridge';
+import { reserveFreePort } from '../start-server';
 
 import ROUTER_PHP from './router.php?raw';
 import NGINX_CONF_TEMPLATE from './configs/nginx.conf?raw';
@@ -51,7 +53,6 @@ export interface PosixKernelBootResult extends AsyncDisposable {
 	[Symbol.asyncDispose](): Promise<void>;
 }
 
-const FPM_LOOPBACK_PORT = 9000;
 const FPM_BOOT_GRACE_MS = 2_000;
 const NGINX_READY_TIMEOUT_MS = 15_000;
 
@@ -79,17 +80,24 @@ export async function bootPosixKernelWordPress(
 	const phpFpmBytes = readWasm(bridge.binaries.phpFpmWasm);
 	const nginxBytes = readWasm(bridge.binaries.nginxWasm);
 
+	// Reserve a free host port for php-fpm. The kernel's TCP bridge
+	// (`kernel-worker.ts:startTcpListener`) translates a kernel-side
+	// `listen()` into a real `net.createServer().listen(port, "0.0.0.0")`
+	// — so two concurrently-booted kernels can't share a hard-coded
+	// 9000 without colliding with `EADDRINUSE`. The port is internal
+	// (only nginx-in-the-kernel talks to it via fastcgi_pass).
+	const fpmPort = await reserveFreePort();
+
 	// Materialize the FastCGI router + php-fpm config from inlined
 	// `?raw` strings so the published CLI bundle is self-contained
 	// (no neighbouring .php / .conf source files in dist/).
 	writeFileSync(joinPaths(options.tempDirHostPath, 'router.php'), ROUTER_PHP);
-	const routerScriptKernelPath = joinPaths(
-		options.tempDirKernelPath,
-		'router.php'
+	const routerScriptHostPath = toPosixSeparators(
+		joinPaths(options.tempDirHostPath, 'router.php')
 	);
 	writeFileSync(
 		joinPaths(options.tempDirHostPath, 'php-fpm.conf'),
-		PHP_FPM_CONF
+		PHP_FPM_CONF.replaceAll('__FPM_PORT__', String(fpmPort))
 	);
 	const fpmConfKernelPath = joinPaths(
 		options.tempDirKernelPath,
@@ -108,13 +116,16 @@ export async function bootPosixKernelWordPress(
 		options.tempDirKernelPath,
 		'first-request-pending'
 	);
+	const documentRootForCgi = toPosixSeparators(options.wordPressRootHostPath);
 	const host = options.host ?? DEFAULT_HOST;
 	const renderedNginxConfKernelPath = renderNginxConf({
 		host,
 		port: options.port,
+		fpmPort,
 		serverName: options.serverName ?? 'localhost',
 		wordPressRootKernelPath: options.wordPressRootKernelPath,
-		routerScriptKernelPath,
+		documentRootForCgi,
+		routerScriptHostPath,
 		tempDirHostPath: options.tempDirHostPath,
 		tempDirKernelPath: options.tempDirKernelPath,
 		firstRequestMarkerKernelPath,
@@ -176,17 +187,16 @@ export async function bootPosixKernelWordPress(
 			kernelHost,
 			phpFpmBytes,
 			fpmConfKernelPath,
-			options.wordPressRootKernelPath
+			documentRootForCgi
+		);
+		// FPM is kernel-internal (only nginx-in-the-kernel connects to
+		// it); probe the kernel's loopback bridge, not the user-chosen
+		// nginx bind host.
+		await waitForLoopback(DEFAULT_HOST, fpmPort, FPM_BOOT_GRACE_MS).catch(
+			() => {
+				/* nginx will retry */
+			}
 		);
-		// FPM is kernel-internal; probe the kernel's loopback bridge,
-		// not the user-chosen nginx bind host.
-		await waitForLoopback(
-			DEFAULT_HOST,
-			FPM_LOOPBACK_PORT,
-			FPM_BOOT_GRACE_MS
-		).catch(() => {
-			/* nginx will retry */
-		});
 
 		spawnNginx(
 			kernelHost,
@@ -269,9 +279,11 @@ function concatBytes(chunks: Uint8Array[]): Uint8Array {
 function renderNginxConf(args: {
 	host: string;
 	port: number;
+	fpmPort: number;
 	serverName: string;
 	wordPressRootKernelPath: string;
-	routerScriptKernelPath: string;
+	documentRootForCgi: string;
+	routerScriptHostPath: string;
 	tempDirHostPath: string;
 	tempDirKernelPath: string;
 	firstRequestMarkerKernelPath: string;
@@ -280,9 +292,11 @@ function renderNginxConf(args: {
 	const rendered = args.template
 		.replaceAll('__HOST__', args.host)
 		.replaceAll('__PORT__', String(args.port))
+		.replaceAll('__FPM_PORT__', String(args.fpmPort))
 		.replaceAll('__SERVER_NAME__', args.serverName)
 		.replaceAll('__WORDPRESS_ROOT__', args.wordPressRootKernelPath)
-		.replaceAll('__ROUTER_SCRIPT__', args.routerScriptKernelPath)
+		.replaceAll('__DOCUMENT_ROOT__', args.documentRootForCgi)
+		.replaceAll('__ROUTER_SCRIPT__', args.routerScriptHostPath)
 		.replaceAll('__TEMP_DIR__', args.tempDirKernelPath)
 		.replaceAll(
 			'__FIRST_REQUEST_MARKER__',
@@ -296,6 +310,10 @@ function renderNginxConf(args: {
 	return joinPaths(args.tempDirKernelPath, 'nginx.conf');
 }
 
+function toPosixSeparators(p: string): string {
+	return p.replace(/\\/g, '/');
+}
+
 function spawnPhpFpm(
 	host: NodeKernelHost,
 	bytes: ArrayBuffer,

packages/playground/cli/src/posix-kernel/configs/nginx.conf

@@ -11,7 +11,15 @@ events {
 http {
     access_log off;
 
+    # Override every temp-path directive — the nginx WASM was built with
+    # `--http-*-temp-path=/tmp/nginx_*_temp`, and nginx mkdirs all of them
+    # at startup regardless of whether `proxy_pass` etc. are configured.
+    # The kernel does not rewrite `/tmp/`, so on Windows (where the host
+    # fs has no `/tmp/`) every mkdir fails and nginx aborts. (scgi/uwsgi
+    # modules aren't compiled into this nginx, so no overrides needed.)
     client_body_temp_path __TEMP_DIR__/client_body_temp;
+    fastcgi_temp_path __TEMP_DIR__/fastcgi_temp;
+    proxy_temp_path __TEMP_DIR__/proxy_temp;
 
     # Every request goes to PHP-FPM via the router script. The router
     # serves static files directly with the right Content-Type and
@@ -24,9 +32,9 @@ http {
         root __WORDPRESS_ROOT__;
 
         location / {
-            fastcgi_pass 127.0.0.1:9000;
+            fastcgi_pass 127.0.0.1:__FPM_PORT__;
             fastcgi_param SCRIPT_FILENAME __ROUTER_SCRIPT__;
-            fastcgi_param DOCUMENT_ROOT $document_root;
+            fastcgi_param DOCUMENT_ROOT __DOCUMENT_ROOT__;
             fastcgi_param DOCUMENT_URI $document_uri;
             fastcgi_param QUERY_STRING $query_string;
             fastcgi_param REQUEST_METHOD $request_method;

packages/playground/cli/src/posix-kernel/configs/php-fpm.conf

@@ -4,7 +4,7 @@ error_log = /dev/stderr
 log_level = notice
 
 [www]
-listen = 127.0.0.1:9000
+listen = 127.0.0.1:__FPM_PORT__
 
 ; The kernel runs every process as root; php-fpm refuses to start
 ; without an explicit user/group when invoked as root, even though

packages/playground/cli/src/posix-kernel/php-api.ts

@@ -45,25 +45,23 @@ const VFS_DOCROOT_IN_CODE = /(?<![\w/-])\/wordpress(?=$|[/"'`\s\\,;:)$])/g;
 export interface KernelLimitedPHPApiOptions {
 	serverUrl: string;
 	wordPressRootHostPath: string;
-	wordPressRootKernelPath: string;
 	phpWasmPath: string;
 	runtime: KernelRuntime;
 }
 
 export class KernelLimitedPHPApi {
 	readonly absoluteUrl: string;
 	/**
-	 * Kernel-side WordPress doc root. Not the VFS literal `/wordpress`.
+	 * Host filesystem doc root, not the VFS literal `/wordpress`.
 	 * Blueprint v1 steps embed `documentRoot` into PHP source via
 	 * `phpVar`, which base64-encodes the value past
 	 * `translateVfsPathsInCode`'s rewrite. The kernel-spawned `php -r`
 	 * resolves `${documentRoot}/wp-load.php` against this path; the
-	 * kernel's `/dev/shm/` rewrite then maps it back to the same bytes
-	 * nginx + php-fpm serve via the host path.
+	 * kernel passes the host path through `fs.*` unchanged (only
+	 * `/dev/shm/` is rewritten).
 	 */
 	readonly documentRoot: string;
 	private readonly hostRoot: string;
-	private readonly kernelRoot: string;
 	private readonly runtime: KernelRuntime;
 	private readonly phpWasmBytes: ArrayBuffer;
 	private readonly cookieJar = new Map<string, string>();
@@ -77,8 +75,7 @@ export class KernelLimitedPHPApi {
 	constructor(options: KernelLimitedPHPApiOptions) {
 		this.absoluteUrl = options.serverUrl;
 		this.hostRoot = options.wordPressRootHostPath;
-		this.kernelRoot = options.wordPressRootKernelPath;
-		this.documentRoot = this.kernelRoot;
+		this.documentRoot = this.hostRoot;
 		this.runtime = options.runtime;
 		this.phpWasmBytes = readWasm(options.phpWasmPath);
 		this.definesPluginPath = joinPaths(
@@ -182,7 +179,7 @@ export class KernelLimitedPHPApi {
 				'php',
 				'-d',
 				'display_errors=stderr',
-				this.toKernel(request.scriptPath),
+				this.toHost(request.scriptPath),
 			];
 		} else {
 			throw new Error(
@@ -200,7 +197,7 @@ export class KernelLimitedPHPApi {
 		const { exitCode, stdout, stderr } = await this.runtime.spawnCapturing({
 			programBytes: this.phpWasmBytes,
 			argv,
-			options: { env, cwd: this.kernelRoot, stdin },
+			options: { env, cwd: this.hostRoot, stdin },
 		});
 
 		return new PHPResponse(
@@ -302,7 +299,7 @@ export class KernelLimitedPHPApi {
 		const env: Record<string, string> = {
 			HOME: '/tmp',
 			PATH: '/usr/local/bin:/usr/bin:/bin',
-			DOCROOT: this.kernelRoot,
+			DOCROOT: this.hostRoot,
 		};
 		if (extra) {
 			for (const [k, v] of Object.entries(extra)) {
@@ -313,7 +310,7 @@ export class KernelLimitedPHPApi {
 	}
 
 	private translateVfsPathsInCode(code: string): string {
-		return code.replace(VFS_DOCROOT_IN_CODE, this.kernelRoot);
+		return code.replace(VFS_DOCROOT_IN_CODE, this.hostRoot);
 	}
 
 	private serializeCookies(): string {
@@ -366,29 +363,6 @@ export class KernelLimitedPHPApi {
 				vfsPath.slice(VFS_DOCUMENT_ROOT.length)
 			);
 		}
-		// Blueprint v1 builds paths from `documentRoot` (kernelRoot).
-		// When those paths flow back into fs methods Node would call
-		// `fs.openSync('/dev/shm/...')` and EPERM on macOS; translate
-		// the kernel prefix back to the host one first.
-		if (vfsPath === this.kernelRoot) {
-			return this.hostRoot;
-		}
-		if (vfsPath.startsWith(this.kernelRoot + '/')) {
-			return this.hostRoot + vfsPath.slice(this.kernelRoot.length);
-		}
-		return vfsPath;
-	}
-
-	private toKernel(vfsPath: string): string {
-		if (vfsPath === VFS_DOCUMENT_ROOT) {
-			return this.kernelRoot;
-		}
-		if (vfsPath.startsWith(VFS_DOCUMENT_ROOT + '/')) {
-			return joinPaths(
-				this.kernelRoot,
-				vfsPath.slice(VFS_DOCUMENT_ROOT.length)
-			);
-		}
 		return vfsPath;
 	}
 }

packages/playground/cli/src/posix-kernel/posix-kernel-handler.ts

@@ -6,6 +6,7 @@ import {
 	runBlueprintV1Steps,
 } from '@wp-playground/blueprints';
 import { RecommendedPHPVersion } from '@wp-playground/common';
+import { mkdirSync } from 'node:fs';
 import path from 'path';
 import { joinPaths } from '@php-wasm/util';
 import { type Mount } from '@php-wasm/cli-util';
@@ -63,20 +64,20 @@ export class PosixKernelHandler {
 		const tempDir = await createPosixKernelTempDir();
 
 		let wordPressRootHostPath: string;
-		let wordPressRootKernelPath: string;
+		// Value of nginx's `root` directive. Stays kernel-shaped because
+		// nginx's POSIX argv parser rejects `C:\…` as relative — PHP-FPM
+		// reads the real host path via the hardcoded `DOCUMENT_ROOT`
+		// fastcgi_param instead.
+		const wordPressRootKernelPath = joinPaths(
+			tempDir.kernelPath,
+			'wordpress'
+		);
+		const nginxRootHostPath = path.join(tempDir.hostPath, 'wordpress');
 		if (wordPressMount) {
-			// User-supplied --mount=/wordpress points at an arbitrary
-			// host directory that we can't relocate under /dev/shm/.
-			// On Linux/macOS the absolute path is already POSIX so the
-			// kernel accepts it; on Windows this branch still fails.
 			wordPressRootHostPath = path.resolve(wordPressMount.hostPath);
-			wordPressRootKernelPath = wordPressRootHostPath;
+			mkdirSync(nginxRootHostPath, { recursive: true });
 		} else {
-			wordPressRootHostPath = path.join(tempDir.hostPath, 'wordpress');
-			wordPressRootKernelPath = joinPaths(
-				tempDir.kernelPath,
-				'wordpress'
-			);
+			wordPressRootHostPath = nginxRootHostPath;
 			try {
 				await prepareWordPressForPosixKernel({
 					wordPressRoot: wordPressRootHostPath,
@@ -118,7 +119,6 @@ export class PosixKernelHandler {
 		const api = new KernelLimitedPHPApi({
 			serverUrl: booted.serverUrl,
 			wordPressRootHostPath,
-			wordPressRootKernelPath,
 			phpWasmPath: booted.runtime.phpWasmPath,
 			runtime: booted.runtime,
 		});

packages/playground/cli/tests/posix-kernel/php-api.spec.ts

@@ -47,7 +47,6 @@ describe('--experimental-posix-kernel KernelLimitedPHPApi.run stdout capture', (
 		api = new KernelLimitedPHPApi({
 			serverUrl: booted.serverUrl,
 			wordPressRootHostPath,
-			wordPressRootKernelPath,
 			phpWasmPath: booted.runtime.phpWasmPath,
 			runtime: booted.runtime,
 		});

packages/playground/cli/tests/posix-kernel/run-cli.spec.ts

@@ -159,7 +159,11 @@ describe(
 			);
 			expect(response.status).toBe(200);
 			const text = await response.text();
-			expect(text).toContain('http://127.0.0.1:9500');
+			// Compare against `cliServer.serverUrl` instead of the
+			// hard-coded `:9500` so the test still passes when another
+			// concurrent test holds 9500 and the handler falls back to
+			// a random port via `reserveFreePort()`.
+			expect(text).toContain(cliServer.serverUrl);
 		});
 	},
 	60_000 * 5