@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/system/node/README.md

@@ -0,0 +1,141 @@
+# @product-lab/system-node
+
+Node implementations of the system ports in [`@product-lab/ports/system`](../../../core/ports/src/driven/system/index.d.ts) (refactor step 1). Classes with their dependencies in the constructor; no constructor does I/O.
+
+| Class | Port | Notes |
+| --- | --- | --- |
+| `SystemClock` | `Clock` | `performance.now()`, `Date`, timers |
+| `NodeMachineMetrics` | `MachineMetrics` | Backlog 25: `node:os` load average (0 on Windows), `availableParallelism()`, free and total memory, and this process's resident memory; read by run recordings every few seconds (`tests/basics.test.ts`). Backlog 37: `freeDiskBytes(path)` (`statfs`) and `directoryBytes(path)` (links never followed), the bisect's disk guard and per-probe use. Backlog 241: each sample, since the previous one, also has the CPUs' idle share (`os.cpus()` times), this process's longest event-loop delay (`monitorEventLoopDelay`, 20 ms resolution) and its utilization (`performance.eventLoopUtilization`), the numbers the media driver's `pace.json` has; on macOS the memory pressure level (`sysctl -n kern.memorystatus_vm_pressure_level`: 1 normal, 2 warn, 4 critical), read in the background at most every `PRESSURE_READ_MS` (10 s), so a sample reports the last level read; Linux and Windows have none. Nothing keeps the process alive: the histogram's timer is Node's own, the `sysctl` child and its pipes are unreferenced (`tests/node-machine-metrics.test.ts`, with a referenced timer as the control) |
+| `GitChangeSource` | `ChangeSource` | Phase 7: files changed between the merge base of a base revision and HEAD, plus uncommitted and untracked ones, relative to the lab's directory (`../` outside it); read-only git, no fetch; an unknown base or an option-like revision is refused; every git command runs through a `CommandRunner` (default `NodeCommandRunner`) bounded by `timeoutMs` (default 30 000 ms), a non-zero exit rejects with git's first stderr line, and an uncommitted file that cannot be read rejects `revision` rather than counting as deleted (`tests/git-change-source.test.ts`, a real temporary repository). Backlog 37: `commits` (first-parent commits that changed the lab's directory between two, oldest first; refused when the first is not an ancestor), `checkout` (`git worktree add --detach` into a new directory, with the lockfile at its top and its sha256; the lab's checkout untouched) and `removeCheckout` (forced remove, the directory deleted, `git worktree prune`) |
+| `NodeSourceWatcher` | `SourceWatcher` | Hot reload of app code (backlog item 5): `fs.watch`, recursive on a watched directory (FSEvents on macOS, inotify on Linux), a watched file or a path not created yet through its nearest existing parent directory; reports changed paths relative to the lab with `/` separators (a watch of `.`, the lab's directory, reports every change under it, an editor's safe write by rename included), not debounced (the application's `AppReloads` debounces). `digest`: sha256 over each regular file's relative path and content in path order, an ignored directory skipped whole, symbolic links not followed. `tests/node-source-watcher.test.ts` (real temporary directory) |
+| `NodeConditionedLinks` | `ConditionedLinks` (backlog 31) | One identity's conditioned link to one loopback endpoint (`node-conditioned-links.ts`): a TCP proxy on a port the caller reserved, carrying every byte as sent through the domain's `ConditionedWire` (one per direction of each connection: in order, a burst at its speed, half the round trip each way while throttled); offline refuses new connections and cuts the open ones; half-closes travel through the wire, so an answer sent before its server closes still arrives. A plain `http:` or `ws:` endpoint is named as the request's `Host` in the first request head of each connection (`request-head.ts`: a local Substrate node answers "Provided Host header is not whitelisted" to any other), and a plain request is made its connection's only one (`Connection: close`); a WebSocket upgrade keeps its connection, and bytes that do not start a request pass as sent. A public endpoint is refused, never proxied. Backpressure is not modelled. `tests/node-conditioned-links.test.ts` (real loopback sockets) |
+| `NodeChainGates` | `ChainGates` (backlog 92) | Origin gates in front of local chain nodes (`node-chain-gates.ts`): one loopback TCP relay per plain `ws:` loopback chain route that accepts connections (a closed port, TLS and a public node are kept as they are). It holds each connection's first request head, decides it once, then pipes bytes both ways (backpressure, no per-message parsing). A request with neither `Origin` nor `Sec-Fetch-Site` (a native host, Node's fetch and WebSocket) passes; a browser's passes only from an admitted origin (`admit`), otherwise the connection is reset unanswered (a 403 would still resolve a no-cors fetch) and recorded (`refused()`: chain, gate URL, kind, origin, time). The node sees its own address as `Host` and a plain request is its connection's only one (`request-head.ts`), so no later request on a kept-alive connection skips the gate. A half-close travels on for a grace (5 s, `halfCloseGraceMs`), then both sides are cut; either side closing or failing destroys both; `close()` cuts everything. Substrate's own `--rpc-cors` cannot do this: its RPC server adds CORS headers but refuses no WebSocket upgrade. `tests/node-chain-gates.test.ts` (real loopback sockets: a closed upstream, a half-closed client, keep-alive, close) |
+| `NodeAppProxies` | `AppProxies` | The lab's proxy in front of an app's dev server (backlog items 64 to 66; `src/app-proxy/`): an HTTP reverse proxy on a loopback port that passes every request and answer as sent, except that an HTML document the browser loads gets the host's bridge script (the domain's `injectScriptTag`; then `no-store`, no validators), bodies are asked for uncompressed and documents unconditionally, a redirect to exactly the dev server's origin names the proxy, and the connection to the dev server is the proxy's own (one per request, since dev servers close idle kept-alive sockets). It reads the document's framing headers and never changes them (`framing()`). WebSockets are tunnelled byte for byte (`web-socket-tunnel.ts`); an update socket it understands (`VITE_UPDATES` in `vite-updates.ts`, Vite's `vite-hmr` subprotocol, checked against Vite 7.3.6) is read message by message: each announced update is put to the policy and forwarded or dropped, the same announcement on several pages' sockets is one update, and the page's side stays open when the dev server's closes (`lost`). A socket or an event stream it does not understand passes untouched and is reported once (`unknown-socket`), never for a declared dev server. `tests/node-app-proxy.test.ts` (real loopback servers, Node's WebSocket client; controls: an asset, a fragment, a conditional request, a dead dev server) |
+| `RandomIdGenerator` | `IdGenerator` | random UUIDs |
+| `ConsoleLogger` | `Logger` | level filter; details as JSON; with `redactor` (a `Redactor`'s `text`), every line scrubbed before it is written (backlog 89: the composition root passes the runtime's, so a provider logging a secret of the lab never prints it) |
+| `ProcessEnvironmentVariables` | `EnvironmentVariables` | wraps `process.env` (or any object), read when asked |
+| `NodeProcessRunner` | `ProcessRunner` | `open(directory)` returns `NodeOwnedProcesses` (moved from core's `ProcessSupervisor`). Each entry records its `StopPolicy` (`ProcessPlan.stop`: SIGINT or SIGTERM, grace, kill grace; default SIGTERM, 5 s, 3 s) in `processes.json`, and `stop` follows it, so a later owner stops a tree the way its starter asked; `commands(id)` lists the command lines of the tree's live members (refactor step 7, for Engine's setup-job wait); `adoptChild` removed. `ProcessPlan.stdout` opens its own file (0600 even when it exists, truncated) for the root's standard output, with standard error still in the log. `stdout` must be an absolute path: this process opens it, so a relative one would resolve against the caller's cwd, not `plan.cwd`. It is opened without truncation after the log, and compared with the log by descriptor (device and inode), so the log itself is refused before anything is truncated. That covers a path, a hard link, and a symlink that pointed at a log not yet created. A symlink to another file is allowed. Descriptors are closed on success and on every open or spawn error. Members are learned by polling (`refreshMs`, default 1 s): a descendant spawned and orphaned between two refreshes, after its parent exited, is not tracked. `exited` never rejects: when the anchor exits before its command and the process table can no longer be read, the command counts as exited (1) and the reason is logged (`tests/owned-group-anchor.test.ts`). Since backlog 13a (1 October 2026) a registry records its `owner`, the lab process that last started into it, and since 2 October each record its own starter (`owner`), and `reapAbandoned(root)` stops the records whose starter is gone in the registries under `root` (a registry several lab processes share, like a host's, keeps a live process's records; records without their own owner fall back to the registry's; owner checked by fingerprint, every member's fingerprint checked again by the stop; a registry without an owner, written before owners existed, is kept and listed; never a saved environment's directory, whose processes are meant to outlive the command). `tests/reap-abandoned.test.ts`: a child lab process starts `sleep` and is SIGKILLed, the next reap stops the `sleep`; controls: an owner still running is left alone, an unowned registry is kept; negative control (the dead-owner check disabled) fails the first test; a shared registry (the killed process started last) stops only the killed one's record, and with the registry-level owner alone (mutation) that test fails |
+| `NodeCommandRunner` | `CommandRunner` | One-shot commands (`host rebase-check`'s git). The command runs to completion with its output captured, or appends both streams to an absolute `outputFile` without capturing them (long build logs). `timeoutMs` is required and positive. On macOS and Linux the command leads a new process group (spawned detached), and a timeout, an abort or an output overflow sends SIGKILL to the whole group, so its descendants in the group die with it, and `run` rejects. An already-aborted signal rejects before spawning. After the command exits, its output may stay open at most `drainMs` (default 2000 ms; a descendant holding the pipes): then the group is killed, the pipes are released and `run` rejects, so a run settles by `timeoutMs` + `drainMs` at the latest. A descendant that left the group (`setsid`, `setpgid`) is not signalled, and a run that completes signals nothing (the command's remaining group members are its own). On Windows only the command is signalled. `env` is laid over `process.env` (`undefined` removes a variable), `input` is written to stdin, and captured streams are capped (`maxOutputBytes`, default 16 MiB, overridable per command request). It does not persist process-tree ownership, unlike `NodeProcessRunner` (`tests/node-command-runner.test.ts`) |
+| `NodeSyncCommandRunner` | `SyncCommandRunner` | Bounded synchronous one-shot commands for setup and template APIs. Captured output uses private temporary files and a per-stream byte cap, so a descendant inheriting output cannot hold a pipe open. A POSIX command runs in its own group; after a timeout, or when descendants still run after the direct child exited, the group is killed and the call throws. After a normal exit the group gets up to 2 s to empty by itself, since a helper that exits with its leader (tsx's esbuild service) can still be in it for a moment; on Linux only live members count (`/proc`), never zombies (2 October 2026, GitHub run 37029798588; `procLiveMembers`). A group that answers EPERM because its remaining members are all exiting (macOS, before they are reaped) is waited for, polling, up to 2 s; one that still refuses then is an error naming the group (`killGroupRemainder` in `src/process-group.ts`; q10-tests, 28 September 2026, a `kill EPERM` under load). Temporary files are removed before return. `output: "inherit"` keeps live terminal output for long builds. Windows can kill only the direct child. See `tests/node-sync-command-runner.test.ts` |
+| `NodeTerminalCommandRunner` | `TerminalCommandRunner` | An interactive program on this terminal (the terminal app's agent beside the lab): spawned with the terminal's standard streams, never detached, so it stays in the terminal's foreground process group and gets its keys and Ctrl-C; no timeout, it ends when the person ends it. `env` is laid over `process.env` (`undefined` removes a variable). Resolves with the exit code or the signal; a program that cannot start rejects (`tests/node-terminal-command-runner.test.ts`) |
+| `signalProcessGroup` | (helper) | Signals a POSIX process group (`process.kill(-pid, signal)`); `false` when the group is already gone (`ESRCH`) or on Windows, any other error thrown. The one group-kill helper: `NodeCommandRunner`, `NodeSyncCommandRunner`, `tools/eval` and `tools/verify` use it (`src/process-group.ts`) |
+| `PsProcessTable`, `ProcessTable`, `sameProcess` | (used by the runner) | the `ps`-based process table `NodeProcessRunner` reads (tests substitute a fake `ProcessTable`), including `command(pid)` and the optional `listAsync()` the background refresh uses; `sameProcess` compares pid, start time and group |
+| `liveRecordedMembers` | (for tests and live proofs) | `liveRecordedMembers(directory, id, table?)`: the members of the tree a registry recorded as `id` (`<directory>/processes.json`, `REGISTRY_FILE`) that are alive with their recorded fingerprint, the group anchor left out, each with its command line. For a test that kills a service its lab started, to prove a dead service is reported `failed` (backlog 235): by the registry's own record, never by a command line every lane's processes can match. `tests/recorded-members.test.ts`: a recorded tree beside a bystander with the very same command line (only the tree is returned; killed, the record reads `failed`), and a stale fingerprint, the anchor, an unknown id and a missing registry giving nothing |
+| `NodeTreeCloner` | `TreeCloner` | Fixtures: copies a directory tree through the `CommandRunner`: on macOS `cp -c -R -p` (an APFS clone: copy-on-write, near-instant whatever the size), elsewhere `cp --reflink=auto -a` (reflink where the file system has it; `cp` does not say whether it did, so it is reported as `reflink`); when that fails, a plain `cp -R -p`, reported as `copy`. Refuses an existing target. Bounded by `timeoutMs` (default 10 minutes) and the caller's signal (`tests/node-tree-cloner.test.ts`) |
+| `TcpPortAllocator` | `PortAllocator` | binds loopback briefly to probe; `reserve(range)` never hands a port out twice, also to concurrent callers (the port is claimed before its probe; since 30 September 2026, when three identities created at once got the same host ports). With `holders` (an `OsPorts`), a port that cannot be bound is refused naming what holds it: "Cannot bind port 52000: held by node (pid 97474, listening); choose another port" (backlog 114) |
+| `claimPortBlock`, `portsFree`, `PORT_GRID`, `PORT_LOCKS` | (used by the composition root and tests) | `src/port-blocks.ts` (moved from tools/verify's `tests/port-block.ts`, 6 October 2026): a free block of a 100-port grid (a wider one takes every cell it covers, all or none, released together: a lab's own sessions' 500 ports), claimed with a lock file holding this process's id in `/tmp/product-lab-port-blocks` (`PRODUCT_LAB_PORT_LOCKS`), released when the process ends, taken over from a process that is gone. `TcpPortAllocator`'s `lab` option hands out a lab's own ports with `next()`: its declared range, else blocks a `claim` takes, one more when they are used up; `within(range)` is a view on a range sharing what was handed out. `block(size, seed, { exact })` keeps a block apart from `next`: claimed, or the top of what is left of the range (at most half of it); with `exact`, exactly `size` or an error naming the range, the size asked and what is left (`ports: { size }`, 7 October 2026). `tests/claimed-lab-ports.test.ts`: two labs claiming at once get blocks of their own (control: without the lock they share ports); a wide block takes one lock per cell, a one-cell claim never lands inside it, and a failed wide claim keeps no cell |
+| `NodeOsPorts` | `OsPorts` | the OS's ephemeral range (macOS `sysctl net.inet.ip.portrange.first/last`, Linux `/proc/sys/net/ipv4/ip_local_port_range`, read once) and a port's holder (macOS `netstat -anv -p tcp`, Linux `ss -Htanp`), through the `CommandRunner` and `FileSystem` it is given; another OS or a failed reading says nothing (backlog 114; `tests/node-os-ports.test.ts`) |
+| `FileLockManager` | `LockManager` | mkdir lock plus `owner.json`; fingerprint liveness; atomic stale reclaim |
+| `NodeHttpProbe` | `HttpProbe` | whether something answers HTTP at a URL (since 5 October 2026, the environment overview's services): one `HEAD`, the redirect not followed, the body cancelled, bounded by the call's `timeoutMs`; any answer is a status, no answer an `error` in words ("connection refused", "no answer within 2000 ms", "host not found"); the caller's own abort rejects. `tests/node-http-probe.test.ts` |
+| `HttpJsonRpcClient`, `WebSocketJsonRpcClient` | `JsonRpcClient` | one call per request; `ws://` sent over `http://` by the HTTP client, which refuses redirects (step 7: the environment adapters' JSON-RPC now goes through it); every call is bounded: the call's `timeoutMs`, else the client's, else 300 000 ms. An `error` reply rejects with the domain's `JsonRpcError` (`method`, `rpcMessage`, `rpcCode`; the message is unchanged: `<method> failed: <message> (<code>)`) |
+| `LsofConnectionMonitor`, `parseLsof`, `descendants`, `isLoopbackEndpoint`, `hostOf` | `ConnectionMonitor` | refactor step 8: samples every socket of the watched roots' process trees (`ps -axo pid=,ppid=`, `lsof -nP -a -p … -i -F pcPn`) every `intervalMs` (default 250) and reports distinct remotes and non-loopback peers. Each probe has a 5 s timeout and `stop()` waits for the sample in flight at most `stopTimeoutMs` (constructor option, default 15 s); failed or malformed samples make `stop()` reject, so an incomplete scan cannot report zero public peers. `lsof` exits 1 with nothing on stderr when it cannot locate a requested pid: with no output that means no sockets, and a partial listing is accepted only when a requested pid it did not list has exited (`processRunning`), since a watched process that exits during a run is normal (backlog 34a); any other code, a diagnostic or a timeout fails. The probe is injectable (`ConnectionProbe`, `connectionProbeWith(execute, running)`) for tests. Moved from `@product-lab/platform`'s `connectionGuard` |
+| `NodeProcessSandbox` | `ProcessSandbox` | Picks the machine's sandbox by platform; constructing it does no I/O. macOS: `SandboxExecSandbox`; Linux: `LinuxNamespaceSandbox`; elsewhere unsupported (`wrap` throws). `mechanism` is the chosen sandbox's one-line account of what it enforces and reports, for session evidence |
+| `SandboxExecSandbox`, `networkDenyProfile`, `SANDBOX_EXEC_MECHANISM` | `ProcessSandbox` | docs/verification/2026-09-25-cli-deny.md: `supported` when `/usr/bin/sandbox-exec` exists. Writes a private SBPL profile (`spec.profileDir/network-deny.sb`: `(allow default)`, then `deny`/`allow network-outbound` only — every other operation keeps its default, unlike a `(deny default)` profile, which was tried and rejected as brittle) and wraps the plan as `sandbox-exec -f <profile> <command> <args>`. The loopback is the machine's, so `connectPorts`/`listenPorts` are ignored; Seatbelt's `localhost` also matches this machine's own interface addresses (a connection that stays on the machine; docs/verification/2026-09-25-linux-sandbox.md) |
+| `LinuxNamespaceSandbox`, `LINUX_NETNS_LAUNCHER`, `LINUX_NAMESPACE_MECHANISM` | `ProcessSandbox` | docs/verification/2026-09-25-linux-sandbox.md: the process runs in an unprivileged user and network namespace of its own (`unshare --user --map-root-user --net`, loopback up with `ip`), where only loopback is active and no external network route exists (inactive kernel tunnel fallbacks are accepted); `linux-network-namespace.mjs` (plain JavaScript, run by the lab's Node) forwards exactly `spec.connectPorts` to this machine's 127.0.0.1 and `spec.listenPorts` from it, over filesystem Unix sockets. Anything else fails at `connect()` (`ENETUNREACH`; `ECONNREFUSED` on an undeclared loopback port), unreported. `supported` runs the mechanism once (a namespace, loopback up, no active external interface or route) on first read and caches it; the reason names what refused it (missing `unshare`/`ip`, AppArmor's `apparmor_restrict_unprivileged_userns`, disabled user namespaces, a container's seccomp profile). Config in `spec.profileDir/network-namespace.json`. The process is uid 0 of its own user namespace, mapped to the invoking user |
+
+`NodeProcessRunner` and `FileLockManager` take a `FileSystem` (`NodeFileSystem` from [`@product-lab/storage-filesystem`](../../storage/filesystem/README.md)); this package does not import it. Wiring them together is the caller's job: the composition root (`composition/src/node-system.ts`, `NodeSystem`) and `tools/verify/src/node-system.ts`. Adapters receive the ports, never these classes.
+
+| | |
+| --- | --- |
+| Nx project | `system-node` |
+| Tags | `scope:provider`, `type:adapter` |
+| Depends on | `@product-lab/ports`; `@product-lab/domain` (`LoopbackUrl`, for the connection monitor, since step 8) |
+| Used by | the composition root (`composition/src/node-system.ts`, `gateway-program.ts`, `host-tool-services.ts` for `NodeCommandRunner`); `examples/notes` (`lab/deployed-local.ts`: the Bulletin reader's WebSocket client and the connection check; the Cucumber hooks' connection check), `examples/notes` also `lab/chain.ts` (`SystemClock`) and its E2E tests; `tools/verify` (`src/node-system.ts`, `live/deploy/`), `tools/spikes/browser`, `tools/eval` (`src/processes.ts`: `NodeSyncCommandRunner` and `signalProcessGroup`; `reference/lab/chain.ts`, `SystemClock` through `@parity/product-lab/system-node`). Another example takes the composition root's `NodeSystem` and imports no class from here. `NodeProcessSandbox` reaches `adapters/host/truapi-cli` only as the `ProcessSandbox` port (`system.sandbox`, `denyByDefault`) |
+
+`@product-lab/system-node/process` (`src/process.ts`) exports `ProcessEnvironmentVariables`, `NodeStdioWorker`, `FileLockManager`, `NodeProcessRunner`, `SystemClock`, `RandomIdGenerator` and `ConsoleLogger` alone: the index loads the domain (about 300 modules), and `product-lab mcp` needs these before it loads the lab (entrypoints/mcp/README.md, "Start").
+
+## Owned processes
+
+`open(directory)` reads `<directory>/processes.json`, re-derives every recorded tree from the process table (the root, its descendants and its process-group members, never this process or its group) and refreshes it every second until `close()`. `start(id, plan)` runs the command under a group anchor (`OWNED_GROUP_ANCHOR`, `src/owned-group-anchor.mjs`), started detached with output appended to `<directory>/<id>.log` (0600) and the injected environment under `plan.env` (`undefined` removes an inherited variable). `stop(id)` signals each recorded member after checking its fingerprint (pid, group, start time), following the entry's `StopPolicy` (default SIGTERM, then SIGKILL), and fails if a member survives; a member refusing a signal with EPERM (macOS, while it exits) is logged and waited for. A reused pid never authorizes a signal.
+
+**The group anchor.** Members are otherwise learned by polling, and a descendant that its parent orphaned before a refresh used to be missed. The anchor closes that gap for descendants that stay in the tree's process group:
+- The anchor leads the tree's new session and process group, and runs the command in it, with its standard output and error, `cwd` (the caller's working directory when the plan names none, as before anchors) and environment. The IPC channel is not inherited, and the anchor itself writes nothing.
+- The tree is recorded (`processes.json`: `anchor`, and at first `root`) before the anchor is sent the command. If recording fails, only the anchor exists: it is ended, and `start` rejects. A stop during a start waits until the command has started. A spawn error, which the anchor reports, means no command ran.
+- The anchor spawns the command before it acknowledges it. So a start never acknowledged (the anchor died first, or its message was lost or late past `runMs`) may leave the command running:
+  - while the anchor lives, its group is adopted and the tree stopped. The record goes only once that stop succeeded; a failed stop keeps it;
+  - once the anchor has exited, nothing establishes which processes are the tree's (a group id and 1 s start times do not). So nothing is adopted or signalled: the record is kept (`stopped`, with the error), and `start` rejects saying that no cleanup was attempted and the command may still run.
+- Once the command has started, it becomes the recorded `root`. `OwnedProcess.pid` is the command's pid, and so is `status`'s `running`, as before anchors. The anchor is a member (counted in `processes`, signalled by a stop, which it ignores for SIGINT and SIGTERM). `commands(id)` leaves it out.
+- At the command's exit, the anchor waits until the registry has refreshed the tree, then is released. While it lives, POSIX does not reuse its pid, which is the group's id, so every process in the group belongs to the tree however quickly it was orphaned. `exited` then resolves with the command's code (1 when signalled).
+- Its waits are bounded (`anchor`: `runMs` for the command to be sent, `releaseMs` for the release, default 10 s each). If the registry's process goes away, the anchor exits at once when no command runs, or else once the command exits; until then it keeps the group findable for a later owner.
+- Not covered, and not supported: a descendant that leaves the group (`setsid`, `setpgid`) before the registry saw it is never recorded. An entry with no recorded member alive is not proof its whole tree is gone.
+- Records written before anchors (no `anchor`) are read as before.
+
+## Locks
+
+`tryAcquire({ path, onStale, ownerless, record })` creates `path` atomically and writes `owner.json` (token, pid, fingerprint, time, `record`). A holder whose fingerprint no longer runs is stale: reported, or reclaimed by renaming the lock aside (of two reclaimers one gets `raced`); the reclaimed record is kept under `reclaimed`. A lock without a readable owner record is reported, treated as stale, or held for a grace period after its creation. `release()` removes the lock only for the token that took it.
+
+## Tests
+
+The app-proxy fixture registers listener cleanup before proxy startup; an occupied proxy-port control verifies that failed startup releases its dev listener. Test ports are independently allocated, never derived from an adjacent port.
+
+The process-tree readiness controls count the anchor, command and child separately; the gated child must appear before readiness passes.
+
+`bunx nx run system-node:test`: real process trees for the runner (registry in memory; `tests/owned-group-anchor.test.ts`: a command exiting 0 or non-zero before any refresh with a descendant in its group, an escaped `setsid` descendant pinned as not covered, a stop during a start, a failed recording, a spawn error, a crashed controller (`tests/anchor-controller.ts`, registry on disk through `tests/disk-files.ts`) while the command runs and after it exits, reused pids, the anchor's own bounds, the command's default and named `cwd`, and a start never acknowledged: `tests/unacknowledging-anchor.mjs` as `anchor.path`, silent (stopped) or dying (refused, record kept)), real one-shot commands for `NodeCommandRunner` (exit code, cwd, env overlay and removal, stdin; timeout, abort, pre-aborted, a missing command and a zero timeout rejected; descendants: one holding the output after the command exits (settles within `drainMs`, group killed), a timeout with one in the group (both killed, on time), one that left the group (not killed, still settles by timeout + drain), and controls: a descendant with closed output neither delays nor fails a run, and 4 MiB of output is read in full with a 50 ms drain), fakes for the process table (EPERM, survivors, group capture), locks (liveness, clock), JSON-RPC transports and the connection probe (lsof output, process trees, exit 1 with a partial listing, a bounded `stop()`, and real `ps`/`lsof` with a watched process that exits), real loopback sockets for ports (a block found free at the start of the run from an OS-assigned port, or `SYSTEM_NODE_TEST_PORT_BASE`). `tests/node-process-sandbox.test.ts`: platform selection, construction and profile/plan-wrapping unit tests plus live smoke tests (gated to where `sandbox-exec` is supported) that spawn a wrapped process and assert a public connect gets `EPERM` while loopback still works, and record that the machine's own address counts as `localhost`. `tests/linux-namespace-sandbox.test.ts`: the probe and the wrap against fakes everywhere; on Linux where the probe passes, live smoke tests (this machine's own non-loopback address reachable unsandboxed and `ENETUNREACH` sandboxed, a public address refused at once, a declared loopback port reached through the forwarder and an undeclared one refused although it listens, a declared listen port reached from outside, exit codes and SIGTERM passed through) and a leaky control (a plan left unwrapped fails the same deny check, "reached … outside loopback"). `tools/linux` runs them on Linux in a container. On disk and across a crashed owner process: `tools/verify/tests/system-adapters.test.ts`.
+
+
+## Source revisions for compatibility
+
+`GitChangeSource.revision` records the lab directory’s Git tree plus a digest of its uncommitted files, for the suite combination and run bundles. A directory HEAD does not hold yet (a lab created but not committed) has git's empty tree, and every file in it counts as uncommitted (3 October 2026). This implements the optional `ChangeSource` revision method; it does not modify Git state. Test with `bunx nx run system-node:test`.
+
+The Linux probe checks interface types, activity and IPv4/IPv6 routes. Kernel-created inactive fallback tunnel devices are allowed only without non-loopback routes; physical interfaces (even down), active tunnels and malformed probe output are refused. Docker Desktop creates these fallback devices in otherwise isolated namespaces.
+
+`NodeStdioWorker` implements the protected fd-3 `StdioWorker` port for MCP. The worker's protocol channel is separate from its diagnostics on stderr. Startup is bounded; abort and stop signal its detached group, escalate after a ten-second grace, and report a failed cleanup if the child still has not exited three seconds after SIGKILL. It cleans the group when the direct child exits. `NodeCommandRunner` and `NodeSyncCommandRunner` share `process-group.ts` for group signaling; the synchronous runner's group-liveness probe and kill are `killGroupRemainder` there.
+
+`PsProcessTable` bounds each synchronous `ps` read at five seconds, including registry refreshes during stop and Ctrl-C recovery. A failed table read throws instead of reporting a clean stop. The registry's once-a-second background refresh reads the table with `listAsync()` (`ps` through `spawn`, the same five-second bound and retry), so it never blocks the event loop; every `ps`, both reads, runs in a session of its own (`PS_OPTIONS.detached`, setsid), outside the terminal's foreground process group, so a terminal that names its foreground process in the title (macOS Terminal) no longer flips to "ps" every second and the terminal's Ctrl-C no longer reaches it (lane E2, 6 October 2026; `execFile` drops `detached`, so the background read spawns: checked in a pty, and over 30 s of a running Notes lab no `ps` was in the terminal's foreground group, against 6 of 167 samples before); at most one such read is in flight, and a read the registry outran (a start, a stop or an on-demand refresh changed the records meanwhile) is dropped, so it cannot remove a process recorded after it was taken (`tests/background-refresh.test.ts`). Before (2 October 2026), each tick ran `ps` synchronously and stalled every timer of the owning process under a loaded machine. Since backlog item 85 (2 October 2026) the reads of every call that is awaited are asynchronous too: `start` (its check and the anchor's handshake, the command found at its start and the group recorded at its exit), `stop` (its signals and survivor wait, the unacknowledged-start path) and the watch of a command whose anchor ended. They follow the same rule: a read the registry outran is taken again (three times, then the synchronous read decides), never applied. A `start` is joinable by `stop` from its first instruction. Still synchronous, because their port methods return at once: `open` (the first load), `status()` and `commands()`.
+
+A read that misses a running root does not decide on its own (backlog 100, 4 October 2026): when a recorded root
+that should run, was seen alive and has no reported exit is absent, and no other process holds its pid, a second read
+decides. `status()`, `commands()` and the awaited refreshes read again at once; the background refresh sets the read
+aside and the next tick decides. A pid that now names another process (another start time or group), or an exit the
+anchor reported, still counts at once (`tests/root-confirmation.test.ts`).
+
+`NodeCommandRunner` and descendants (26 September 2026): it used to signal only the command and to settle on `close`, so a descendant holding the output pipes held a run past its timeout (about 30 s in the reproducing tests). The process group and the bounded drain above fix that for descendants that stay in the group. Not covered: a descendant that leaves the group keeps running (the run still settles), and a pid reused between the group's last member exiting and the drain's signal (after the command's exit), which needs the system's process ids to wrap. Use the owned-process registry for managed services.
+
+App proxy hardening (item82): one canonical announcement is fingerprinted independently of proxy history; recent decisions retain at most128 SHA256 keys. The understood WebSocket transport caps headers at16KiB, frame/message bytes at16MiB, fragment count at4096 and deferred output at32MiB+120KiB. Invalid or oversized traffic closes deliberately. Accepted frame bytes are preserved; both directions pause on write backpressure. Held sockets answer Ping and complete Close after upstream loss; callback failures close both peers. Pure Vite interpretation and recent decision rules are in the domain.
+
+Transport qualification: the exact deferred-output cap is33,677,312bytes **per writer/direction**, separate from frame buffers, Node writable buffers and transient text/concatenation allocations; this is not a measured total connection memory/RSS bound. Understood text validates strict UTF-8 only after completing a message (including fragments), before forwarding or server policy decisions. Close status and UTF-8 reason validate before forwarding or held-page echo. Valid completed text and Close frame bytes are retained unchanged.
+
+
+Framing document reader (item82): `NodeDocumentHeaders` implements `DocumentHeadersReader`. It reads only response headers, follows at most five loopback HTTP(S) redirects manually, cancels each body and bounds the complete read, including stalled body cancellation, at3000ms. A nonloopback initial address or redirect is refused before contact. This is the one Node read implementation used by composition's shared framing inspection; the host adapters and panel do not construct it.
+
+
+## Same-origin native bridge (item 83)
+
+`NodeAppProxies.bridge()` binds one credential-free loopback HTTP(S) native script to a fresh opaque URL under the reserved `/.product-lab/bridge/` namespace. HTML documents name that proxy URL. GET/HEAD of the current URL fetch only the configured native endpoint, preserve its exact uncompressed bytes, and return JavaScript with `Cache-Control: no-store`. Query targets, other methods and expired bindings are refused. Replacement, unset and close cancel outstanding reads; replacement also rotates the route when the native port is reused. No application's CSP or framing header changes. Existing update transport and immutable build identity remain intact. Before serving the script the route checks once that the bound path is not an application asset (a HEAD to the dev server); since backlog 225 that check starts when the bridge is bound and has its own 60 s deadline, kept apart from the native read's 3 s: a dev server answers its first unknown path by compiling its not-found page (4.4 s measured on a cold Next dev server under load), and inside the 3 s the page's first load got a 502 and ran without its host. A passed check is kept for the binding; a failed one is made again.
+
+API-name correction: `bridge()` is a method on the `AppProxy` returned by `NodeAppProxies.open()`, rather than on `NodeAppProxies` itself. The preceding description applies to that returned proxy.
+
+One 3000 ms deadline covers the exact application-path HEAD collision probe and native GET. Native headers are capped at 16 KiB and the script at 2 MiB. Redirects are never followed; caller cookies and conditionals are never sent to the host. A successful non-HTML application asset at the generated path is refused with 409. HTML SPA fallback is accepted, but an intentional HTML route is indistinguishable from it. Unsupported HEAD replies refuse with explicit 502; this check does not atomically protect against later application route changes. The whole namespace is reserved, including missing/expired URLs; consumers must keep their routes outside it. The native socket remains at its original endpoint, so `script-src 'self'` still needs a suitable `connect-src` allowance. Nonce/hash-only scripts and strict-dynamic are unqualified.
+
+Focused checks: `node --import tsx --test adapters/system/node/tests/node-app-bridge.test.ts adapters/system/node/tests/node-app-proxy.test.ts`. `APP_BRIDGE_TEST_PORT_BASE` selects the new fixture block (default 45300; one distinct ten-port slice per case); `APP_PROXY_TEST_PORT_BASE` optionally selects distinct ports for the older proxy tests, whose default remains independent OS allocation. All fixture listeners close with their tests.
+
+## Explicit Next App Router profile (1 October 2026)
+
+The known protocol registry includes `next-webpack-app-router`, qualified against pinned stock Next16.3.1 webpack. Consumers must explicitly declare that profile; default socket discovery continues to identify Vite. An undeclared Next socket passes as unknown. Per-socket readers retain the first sync hash, and this profile disables decision deduplication so repeated identical router announcements reach the policy. Reader exceptions close the selected socket and report explicit refusal; Turbopack is refused. Custom supplied protocol lists keep their existing discovery behavior. This does not qualify general Pages Router initial sync. Tests: `bunx nx run system-node:test` and the real profile in `verify:test` with its documented prerequisite.
+
+## Supported dev servers (1 October 2026)
+
+`NodeAppProxies` knows these update protocols (`src/app-proxy/`). Only Vite is found by itself; the others share or use
+generic socket paths and are read only when the lab declares them (`AppProxyRequest.updates`, from
+`apps.<id>.devServer.updates`). The table for app authors is in [the app skill of the AI kit](../../../entrypoints/cli/ai-kit/skills/product-lab-app/SKILL.md#the-dev-servers-own-updates-appdevserverupdates).
+
+| Declared | Export | Socket | Checked against |
+| --- | --- | --- | --- |
+| `"vite"` (or nothing) | `VITE_UPDATES` | subprotocol `vite-hmr` | Vite 7.3.6 |
+| `"next-webpack-app-router"` | (registry only) | `/_next/hmr` | stock Next 16.3.1 webpack, App Router |
+| `"next-turbopack"` | `NEXT_TURBOPACK_UPDATES` | `/_next/hmr` | stock Next 16.3.1 Turbopack, App Router (`tools/verify/tests/next-turbopack-app-proxy.test.ts`) |
+| `"webpack-dev-server"` | `WEBPACK_DEV_SERVER_UPDATES` | `/ws` | webpack-dev-server 6.0.0, @rspack/dev-server 2.2.1 (`tools/verify/tests/webpack-dev-server-app-proxy.test.ts`) |
+| `{ hold: "<path>" }` | (no reader) | the declared path | `tests/hold-updates.test.ts` (fake upstream socket) |
+
+The readers are pure functions in `@product-lab/domain/apps` (`readNextTurbopackAnnouncement`,
+`readWebpackDevServerAnnouncement`) behind per-socket state (`createReader`); both disable decision deduplication,
+since two builds can send identical bytes. A declared hold reads nothing: the tunnel (`web-socket-tunnel.ts`,
+`deliverNow`) keeps each complete data message from the dev server, in order, while the policy refuses
+`{ kind: "update", paths: [] }`; the proxy asks again every `holdPollMs` (default 50) while any socket keeps one and
+then releases all of them. Control frames and the page's messages pass; a Close from the dev server drops what waits;
+more than 32 MiB held refuses the socket. A hold announces no update (`protocol()` is `"hold"`), so the lab numbers no
+builds for it. Focused checks: `node --import tsx --test adapters/system/node/tests/hold-updates.test.ts`.
+
+For a declared `"webpack-dev-server"`, `serveApp` (composition) adds the dev servers' own proxy setting
+(`client.webSocketURL`) to the start command, so the page's socket reaches this proxy at all; see
+`core/domain/src/apps/dev-server-socket.ts`.

package/adapters/system/node/src/app-proxy/bridge-script.d.ts

@@ -0,0 +1,21 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+/** Session replacement invalidates both its script path and any outstanding upstream read. */
+export declare class BridgeScript {
+    private readonly origin;
+    private readonly app;
+    private binding;
+    private closed;
+    constructor(origin: string, app: URL);
+    get url(): string | undefined;
+    set(script: string | undefined): void;
+    /** The application-path check for `path`, under its own deadline; rejections are kept for serve() to report. */
+    private check;
+    /** The binding's check; when it failed (the app was not up yet, or an asset was there), it is made again, once. */
+    private checkedOnce;
+    close(): void;
+    /** True only for the explicitly reserved namespace. Every other app path remains an app request. */
+    handle(incoming: IncomingMessage, response: ServerResponse): boolean;
+    private serve;
+    /** No redirects, no caller headers, no body decoding, and one combined route deadline. */
+    private read;
+}

package/adapters/system/node/src/app-proxy/bridge-script.js

@@ -0,0 +1,186 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomUUID } from "node:crypto";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { LoopbackUrl } from "@parity/product-lab/domain";
+import { isHtmlContentType } from "@parity/product-lab/domain/apps";
+const PREFIX = "/.product-lab/bridge/";
+const MAX_BYTES = 2 * 1024 * 1024;
+const DEADLINE_MS = 3000;
+const COLLISION_DEADLINE_MS = 60_000;
+class BridgeFailure extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class BridgeScript {
+    origin;
+    app;
+    binding;
+    closed = false;
+    constructor(origin, app) {
+        this.origin = origin;
+        this.app = app;
+    }
+    get url() {
+        return this.binding ? new URL(this.binding.path, this.origin).href : undefined;
+    }
+    set(script) {
+        if (this.closed)
+            throw new Error("The app proxy is closed");
+        const url = script === undefined ? undefined : LoopbackUrl.tryParse(script, { protocols: ["http:", "https:"], withoutCredentials: true });
+        if (script !== undefined && !url)
+            throw new Error("The bridge script must be a loopback http(s) URL");
+        this.binding?.abort.abort(new BridgeFailure(410, "The native bridge binding was replaced"));
+        if (!url) {
+            this.binding = undefined;
+            return;
+        }
+        const path = `${PREFIX}${randomUUID()}.js`;
+        const abort = new AbortController();
+        this.binding = { native: new URL(url.href), path, abort, checked: this.check(path, abort.signal) };
+    }
+    check(path, replaced) {
+        const own = new AbortController();
+        const stop = () => own.abort(replaced.reason);
+        replaced.addEventListener("abort", stop, { once: true });
+        const timer = setTimeout(() => own.abort(new BridgeFailure(502, `The native bridge route could not check the application path within ${COLLISION_DEADLINE_MS} ms`)), COLLISION_DEADLINE_MS);
+        const checked = this.read(new URL(path, this.app), "HEAD", own.signal, true).then(() => undefined, (error) => { throw own.signal.aborted ? own.signal.reason : error; }).finally(() => {
+            clearTimeout(timer);
+            replaced.removeEventListener("abort", stop);
+        });
+        checked.catch(() => undefined);
+        return checked;
+    }
+    async checkedOnce(binding, signal) {
+        const settled = (checked) => new Promise((resolve, reject) => {
+            const stop = () => reject(signal.reason);
+            if (signal.aborted)
+                return stop();
+            signal.addEventListener("abort", stop, { once: true });
+            checked.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop));
+        });
+        try {
+            await settled(binding.checked);
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            binding.checked = this.check(binding.path, binding.abort.signal);
+            await settled(binding.checked);
+        }
+    }
+    close() {
+        this.closed = true;
+        this.binding?.abort.abort(new BridgeFailure(410, "The native bridge proxy closed"));
+        this.binding = undefined;
+    }
+    handle(incoming, response) {
+        let requestUrl;
+        try {
+            requestUrl = new URL(incoming.url ?? "/", this.origin);
+        }
+        catch {
+            response.writeHead(400, { "content-type": "text/plain", "cache-control": "no-store" }).end("Invalid app proxy request URL\n");
+            return true;
+        }
+        if (!requestUrl.pathname.startsWith(PREFIX))
+            return false;
+        const fail = (status, detail) => {
+            response.writeHead(status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }).end(`${detail}\n`);
+        };
+        if (requestUrl.origin !== new URL(this.origin).origin || requestUrl.search || requestUrl.hash) {
+            fail(400, "The native bridge route accepts no request-supplied target or query");
+            return true;
+        }
+        const binding = this.binding;
+        if (!binding || requestUrl.pathname !== binding.path) {
+            fail(404, "No native bridge is bound to this route");
+            return true;
+        }
+        if (incoming.method !== "GET" && incoming.method !== "HEAD") {
+            fail(405, "The native bridge route accepts GET or HEAD only");
+            return true;
+        }
+        void this.serve(binding, incoming, response);
+        return true;
+    }
+    async serve(binding, incoming, response) {
+        const abort = new AbortController();
+        const replaced = () => abort.abort(binding.abort.signal.reason);
+        binding.abort.signal.addEventListener("abort", replaced, { once: true });
+        let timer;
+        const abandoned = () => { if (!response.writableEnded)
+            abort.abort(new BridgeFailure(502, "The native bridge request closed")); };
+        response.once("close", abandoned);
+        try {
+            await this.checkedOnce(binding, abort.signal);
+            timer = setTimeout(() => abort.abort(new BridgeFailure(502, `The native bridge read exceeded ${DEADLINE_MS} ms`)), DEADLINE_MS);
+            const bytes = await this.read(binding.native, "GET", abort.signal, false);
+            if (binding !== this.binding || this.closed)
+                throw new BridgeFailure(410, "The native bridge binding was replaced");
+            response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store", "content-length": bytes.length });
+            response.end(incoming.method === "HEAD" ? undefined : bytes);
+        }
+        catch (error) {
+            if (response.destroyed)
+                return;
+            const failure = abort.signal.aborted ? abort.signal.reason : error;
+            response.writeHead(failure instanceof BridgeFailure ? failure.status : 502, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end(`${failure instanceof BridgeFailure ? failure.message : `The native bridge could not be read: ${failure instanceof Error ? failure.message : "unknown read failure"}`}\n`);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            binding.abort.signal.removeEventListener("abort", replaced);
+            response.off("close", abandoned);
+        }
+    }
+    read(url, method, signal, collision) {
+        const target = new URL(url);
+        if (target.hostname === "localhost")
+            target.hostname = "127.0.0.1";
+        return new Promise((resolve, reject) => {
+            const outgoing = (target.protocol === "https:" ? httpsRequest : httpRequest)(target, {
+                method, signal, agent: false, maxHeaderSize: 16 * 1024,
+                headers: { "accept-encoding": "identity", host: url.host },
+                ...(target.protocol === "https:" && url.hostname === "localhost" ? { servername: "localhost" } : {}),
+            }, (answer) => {
+                const status = answer.statusCode ?? 502;
+                const refuse = (failure) => { answer.destroy(); reject(failure); };
+                answer.on("error", reject);
+                if (status >= 300 && status < 400)
+                    return refuse(new BridgeFailure(502, "The native bridge route refuses redirects"));
+                if (collision) {
+                    if (status >= 200 && status < 300 && !isHtmlContentType(answer.headers["content-type"]))
+                        return refuse(new BridgeFailure(409, "The native bridge route collides with an application asset"));
+                    if (status !== 404 && status !== 410 && !(status >= 200 && status < 300))
+                        return refuse(new BridgeFailure(502, `The native bridge route could not check the application path (${status})`));
+                    answer.destroy();
+                    resolve(Buffer.alloc(0));
+                    return;
+                }
+                if (status !== 200)
+                    return refuse(new BridgeFailure(502, `The configured native bridge returned ${status}`));
+                if (answer.headers["content-encoding"] && answer.headers["content-encoding"] !== "identity")
+                    return refuse(new BridgeFailure(502, "The configured native bridge returned an encoded script"));
+                if (Number(answer.headers["content-length"] ?? 0) > MAX_BYTES)
+                    return refuse(new BridgeFailure(502, `The native bridge script exceeds ${MAX_BYTES} bytes`));
+                const chunks = [];
+                let length = 0;
+                answer.on("data", (bytes) => {
+                    length += bytes.length;
+                    if (length > MAX_BYTES)
+                        return refuse(new BridgeFailure(502, `The native bridge script exceeds ${MAX_BYTES} bytes`));
+                    chunks.push(bytes);
+                });
+                answer.once("end", () => resolve(Buffer.concat(chunks, length)));
+            });
+            outgoing.once("error", reject);
+            outgoing.end();
+        });
+    }
+}

package/adapters/system/node/src/app-proxy/next-turbopack-updates.d.ts

@@ -0,0 +1,2 @@
+import type { DevServerUpdateProtocol } from "@parity/product-lab/ports/system";
+export declare const NEXT_TURBOPACK_UPDATES: DevServerUpdateProtocol;

package/adapters/system/node/src/app-proxy/next-turbopack-updates.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readNextTurbopackAnnouncement } from "@parity/product-lab/domain/apps";
+export const NEXT_TURBOPACK_UPDATES = {
+    id: "next-turbopack",
+    deduplicate: false,
+    owns: ({ path }) => path === "/_next/hmr" || path.endsWith("/_next/hmr"),
+    read: (message) => readNextTurbopackAnnouncement(message),
+    createReader: () => {
+        const state = {};
+        return { read: (message) => readNextTurbopackAnnouncement(message, state) };
+    },
+};

package/adapters/system/node/src/app-proxy/next-webpack-updates.d.ts

@@ -0,0 +1,2 @@
+import type { DevServerUpdateProtocol } from "@parity/product-lab/ports/system";
+export declare const NEXT_WEBPACK_UPDATES: DevServerUpdateProtocol;

package/adapters/system/node/src/app-proxy/next-webpack-updates.js

@@ -0,0 +1,19 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { nextWebpackSyncHash, readNextWebpackAppAnnouncement } from "@parity/product-lab/domain/apps";
+export const NEXT_WEBPACK_UPDATES = {
+    id: "next-webpack-app-router",
+    deduplicate: false,
+    owns: ({ path }) => path === "/_next/hmr" || path.endsWith("/_next/hmr"),
+    read: readNextWebpackAppAnnouncement,
+    createReader: () => {
+        let syncHash;
+        return { read(message) {
+                const announcement = readNextWebpackAppAnnouncement(message, syncHash);
+                const hash = nextWebpackSyncHash(message);
+                if (syncHash === undefined && hash !== undefined)
+                    syncHash = hash;
+                return announcement;
+            } };
+    },
+};

package/adapters/system/node/src/app-proxy/node-app-proxy.d.ts

@@ -0,0 +1,15 @@
+import type { AppProxies, AppProxy, AppProxyRequest, DevServerUpdateProtocol } from "@parity/product-lab/ports/system";
+export interface NodeAppProxiesOptions {
+    /** The update protocols the proxy understands (default: Vite, stock Next webpack and Turbopack, and webpack-dev-server). */
+    readonly protocols?: readonly DevServerUpdateProtocol[];
+    /** Milliseconds since an arbitrary start (default `performance.now`). */
+    readonly now?: () => number;
+    /** While a hold socket keeps messages, how often the policy is asked again, in ms (default 50). */
+    readonly holdPollMs?: number;
+}
+/** Opens the lab's app proxies on loopback ports. */
+export declare class NodeAppProxies implements AppProxies {
+    private readonly options;
+    constructor(options?: NodeAppProxiesOptions);
+    open(request: AppProxyRequest): Promise<AppProxy>;
+}