fix(shared-ols): unmapped Host gets 421, not a 200 that hides a dead site

The shared-OLS catch-all (`map _health *`) served html/index.html -- HTTP 200, 11 bytes, "shared-ols" -- to any Host no customer vhost claimed. Three live customer sites (joshuaknapp.net, streamers.channel, blog.anti-social.online) sat in exactly that state for ~2 months on whp01 and no monitor noticed, because every uptime check asks "is it 200?" and it was. A tier-wide catch-all that answers 200 makes a missing vhost indistinguishable from a working site. An unmapped Host now gets 421 Misdirected Request with a short generic body. 421 is semantically exact (the server cannot produce a response for the requested authority) and, unlike 404, cannot be confused with a normal answer from a real site. The discriminator is the request path plus the client address, NOT the Host -- the vhost is selected by the listener map, so by the time these rules run the Host is no longer available to branch on: * `/healthz` from an internal client address (loopback, RFC1918) -> 200 "ok" * everything else, every path, every Host, both listeners -> 421 The 421 for `/` is UNCONDITIONAL: no header, source address or Host talks this vhost into a 200 there, so the property the change exists to guarantee does not rest on anything spoofable. The address gate only hardens /healthz, and X-Forwarded-For cannot be used against it because HAProxy replaces that header with the real client IP. Health probes keep passing unchanged. Both forms were run against a container carrying this change and both exit 0 with "ok": curl -fsSk https://127.0.0.1/healthz (Dockerfile.shared-ols HEALTHCHECK) curl -sfk https://localhost/healthz (WHP setup-shared-ols.sh --health-cmd) `docker inspect` reported healthy with failingStreak=0, on a container with a customer site and on a zero-site container. Measured on the lab VM against OLS 1.8.4 (the production base image): unmapped Host, `/`, :443 and :80 -> 421, 356 bytes, identical for every unmapped Host (no enumeration signal) unmapped Host, any deeper path -> the same 421 configured site, both names, :443/:80 -> 200, served normally litespeed -t -> 0 [ERROR] lines (warnings only, and only about the lab fixture's uid/gid) Two OLS behaviours were measured rather than assumed, and both shaped the implementation -- see the comment block in entrypoint-shared-ols.sh: `context / { type redirect statusCode 421 }` silently degrades to a 302 with an unexpanded Location, and the `errorpage 421` body is fetched as a fresh request through the same rewrite rules (so it needs a %{THE_REQUEST} guard, since %{IS_SUBREQ} and %{ENV:REDIRECT_STATUS} are not populated). The old index.html is removed, not just bypassed: if these rules ever stopped applying, `context /` would fall back to the docRoot index, and with no index.html that is a 403 -- wrong-but-loud, rather than a 200 that is wrong-and-silent. Known consumer to land alongside this: whp-monitoring's probe_shared_ols_catchall() currently detects the catch-all by matching `200` + body `shared-ols`, a signature this change deletes. It must also accept 421, or the detector silently stops detecting. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merge branch 'fix/ols-watcher-scope'
2026-08-22 19:44:01 -07:00 · 2026-08-13 21:39:37 -07:00 · 2026-08-13 21:39:14 -07:00 · 2026-08-13 21:29:48 -07:00 · 2026-08-13 15:03:49 -07:00 · 2026-08-13 14:47:08 -07:00
26 changed files with 2722 additions and 52 deletions
@@ -6,6 +6,56 @@ on:
      - trunk

 jobs:
+  # Shell gate. Runs FIRST and costs seconds; the images below do not depend on
+  # it (a red job here does not block a push that is otherwise fine), but it is
+  # the only place the ENTRYPOINT logic is executed at all. The .phpt suite and
+  # the Dockerfile's `lsphp -i` probe both test the extension, and both were
+  # green for the release whose entrypoint declared that same extension
+  # missing — see scripts/tests/lsphp-info-probe.test.sh for what went wrong
+  # and why it needed a test outside the image build to catch it.
+  Shell-Checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Runner images differ on whether they are root and whether sudo exists.
+      - name: Install shellcheck
+        run: |
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            (apt-get update && apt-get install -y shellcheck) ||
+            (sudo apt-get update && sudo apt-get install -y shellcheck)
+          fi
+          shellcheck --version
+
+      - name: Syntax check every shell script
+        run: |
+          set -euo pipefail
+          find scripts ext -name '*.sh' -print0 | xargs -0 -n1 bash -n
+
+      # Deliberately NOT repo-wide. The older scripts (entrypoint.sh,
+      # entrypoint-fpm.sh, create-vhost.sh, create-php-config.sh,
+      # detect-memory.sh) carry pre-existing SC2154/SC2027 findings that predate
+      # this job; listing them here would make the gate red on arrival and
+      # therefore ignored. This is the set that is clean today — the scripts
+      # that run `set -o pipefail` plus the tests. Add files as they are fixed;
+      # do not add one that is not yet clean.
+      - name: shellcheck (warnings and above, on the clean set)
+        run: |
+          shellcheck -S warning \
+            scripts/entrypoint-lsphp.sh \
+            scripts/entrypoint-litespeed.sh \
+            scripts/entrypoint-shared-ols.sh \
+            scripts/render-shared-ols-config.sh \
+            scripts/ols-htaccess-watcher.sh \
+            scripts/create-vhost-litespeed.sh \
+            scripts/install-lscache-wp.sh \
+            scripts/tune-mpm.sh \
+            scripts/tests/lsphp-info-probe.test.sh
+
+      - name: lsphp probe regression test
+        run: ./scripts/tests/lsphp-info-probe.test.sh
+
  Build-and-Push:
    runs-on: ubuntu-latest
    strategy:
@@ -21,6 +21,108 @@

 ARG OLS_VERSION=1.8.4
 ARG PHPVER=83
+
+## ---- stage 1: build the cac_path_parity extension --------------------------
+## $_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] parity with cac-fpm, enforced
+## from RINIT so a customer's .user.ini cannot displace it — see
+## ext/cac-path-parity/cac_path_parity.c for why this is an extension and not an
+## auto_prepend_file.
+##
+## WHICH lsphp THE .so IS BUILT AGAINST — read this before touching the apt lines.
+## `lsphp${PHPVER}-dev` is NOT available at the version the base image ships:
+## the LiteSpeed apt repo carries only the CURRENT release, and every prebuilt
+## OLS base image is behind it (measured 2026-08-05 on OLS 1.8.4:
+##   lsphp81 8.1.33 base / 8.1.34 repo, lsphp83 8.3.28 / 8.3.32,
+##   lsphp85 8.5.0 / 8.5.8).
+## Pinning -dev to the base version fails on all three with
+## `E: Version '<base>' for 'lsphp<NN>-dev' was not found`.
+##
+## So installing -dev necessarily UPGRADES lsphp in this stage. The parity we can
+## have — and the one this file now guarantees — is the other direction: the
+## shipped runtime is pinned to whatever version this stage compiled against.
+## That version is recorded here and consumed by stage 2, so the two apt layers
+## are cache-locked to each other. Without this, `COPY ./ext` invalidating only
+## THIS stage while stage 2's apt layer stayed cached produced a real, repeatable
+## skew (reviewer measured a .so built on 8.3.32 shipped next to an 8.3.30
+## runtime, with lsphp83-common at 8.3.31 — the vendor family is not always
+## uniformly versioned either).
+##
+## Benign in practice (PHP holds ABI stable across a patch series) but it is the
+## riskier direction — headers NEWER than the runtime — and the runtime assertion
+## in stage 2 catches only load failure, never silent struct-layout drift.
+##
+## Separate stage on purpose: the compiler + headers (~400MB) stay out of the
+## shipped image, which gains only the ~40KB .so. Costs ~1-2 min of CI per PHP
+## version; both stages share the same base layer, so no extra pull.
+FROM litespeedtech/openlitespeed:${OLS_VERSION}-lsphp${PHPVER} AS ext-build
+ARG PHPVER=83
+
+## Toolchain layer, deliberately BEFORE the source COPY so editing the extension
+## does not re-resolve the PHP version (which is what caused the skew above).
+## Records the exact lsphp version the headers belong to; stage 2 pins to it.
+RUN set -e; \
+    apt-get update; \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        build-essential autoconf pkg-config \
+        lsphp${PHPVER}-dev; \
+    RTV=$(dpkg-query -W -f='${Version}' lsphp${PHPVER}); \
+    DEVV=$(dpkg-query -W -f='${Version}' lsphp${PHPVER}-dev); \
+    if [ "$RTV" != "$DEVV" ]; then \
+        echo "FATAL: lsphp${PHPVER}=$RTV but lsphp${PHPVER}-dev=$DEVV — the headers" >&2; \
+        echo "       do not belong to the PHP in this stage. Refusing to build." >&2; \
+        exit 1; \
+    fi; \
+    mkdir -p /build-out; \
+    printf '%s' "$RTV" > /build-out/lsphp.version; \
+    echo "cac_path_parity will be compiled against lsphp${PHPVER} $RTV"
+
+## Build, then RUN THE .phpt SUITE as a build gate. Before this, ext/…/tests/
+## existed but nothing ever executed it — neither this Dockerfile nor
+## .gitea/workflows/build-push.yaml — so six green tests were documentation. It
+## costs ~1s per PHP version and it runs against the SAME lsphp build the .so
+## will ship next to.
+##
+## Two guards around `make test`, because its default failure mode is silence:
+##  - if PHP_EXECUTABLE is missing the Makefile prints "Cannot run tests without
+##    CLI sapi." and EXITS 0. The lsphp packages do ship a real CLI
+##    (php-config --php-binary => .../bin/phpN.N), but assert it rather than
+##    trusting it.
+##  - a run that executes ZERO tests also exits 0, so assert the summary shows
+##    every .phpt in the directory both ran and passed. Same reasoning as the
+##    `lsphp -i` probe below: an assertion that cannot fail is worse than none.
+COPY ./ext/cac-path-parity /usr/src/cac-path-parity
+RUN set -e; \
+    cd /usr/src/cac-path-parity; \
+    /usr/local/lsws/lsphp${PHPVER}/bin/phpize; \
+    ./configure --enable-cac-path-parity \
+        --with-php-config=/usr/local/lsws/lsphp${PHPVER}/bin/php-config; \
+    make -j"$(nproc)"; \
+    PHP_BIN=$(/usr/local/lsws/lsphp${PHPVER}/bin/php-config --php-binary); \
+    if [ ! -x "$PHP_BIN" ]; then \
+        echo "FATAL: no CLI php at '$PHP_BIN' — \`make test\` would print" >&2; \
+        echo "       'Cannot run tests without CLI sapi.' and exit 0." >&2; \
+        exit 1; \
+    fi; \
+    EXPECTED=$(ls tests/*.phpt | wc -l); \
+    if [ "$EXPECTED" -lt 1 ]; then echo "FATAL: no .phpt tests found" >&2; exit 1; fi; \
+    if ! NO_INTERACTION=1 REPORT_EXIT_STATUS=1 make test >/tmp/make-test.log 2>&1; then \
+        cat /tmp/make-test.log >&2; \
+        echo "FATAL: cac_path_parity .phpt suite FAILED — not shipping this .so." >&2; \
+        exit 1; \
+    fi; \
+    cat /tmp/make-test.log; \
+    if ! grep -Eq "^Number of tests : +${EXPECTED} +${EXPECTED} *$" /tmp/make-test.log; then \
+        echo "FATAL: expected all ${EXPECTED} .phpt tests to run; the summary above disagrees." >&2; \
+        exit 1; \
+    fi; \
+    if ! grep -Eq "^Tests failed +: +0 " /tmp/make-test.log; then \
+        echo "FATAL: run-tests.php reported failures." >&2; \
+        exit 1; \
+    fi; \
+    echo "cac_path_parity: ${EXPECTED}/${EXPECTED} .phpt tests passed"; \
+    cp modules/cac_path_parity.so /build-out/
+
+## ---- stage 2: the shipped sidecar image ------------------------------------
 FROM litespeedtech/openlitespeed:${OLS_VERSION}-lsphp${PHPVER}
 ARG PHPVER=83
 ENV PHPVER=${PHPVER}
@@ -29,12 +131,40 @@ ENV PHPVER=${PHPVER}
 ## base lacks is lsphpNN-ldap. setpriv (util-linux) is already on the Ubuntu
 ## base; we add nothing else the sidecar doesn't need. All apt cache cleaned in
 ## the same layer to keep the image small.
-RUN apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+##
+## VERSION LOCKSTEP: `apt-get install lsphpNN-ldap` pulls lsphpNN-common forward,
+## which drags the whole lsphpNN family to the repo's current release — the same
+## upgrade the ext-build stage gets. Left implicit, the two stages resolve that
+## independently and Docker caches them independently, so they drift apart (see
+## the long comment on stage 1). Copying stage 1's recorded version in BEFORE
+## this layer makes the version part of this layer's cache key: same version =>
+## cache hit, new version => this layer re-runs and lands on the same one. The
+## explicit `=$V` pins then make a mid-build repo roll a LOUD apt failure instead
+## of a silent skew. Verified satisfiable on PHP 8.1/8.3/8.5 (2026-08-05).
+COPY --from=ext-build /build-out/lsphp.version /etc/cac-lsphp-build.version
+RUN set -e; \
+    V=$(cat /etc/cac-lsphp-build.version); \
+    apt-get update; \
+    if ! DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        ca-certificates \
-        lsphp${PHPVER}-ldap && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
+        lsphp${PHPVER}="$V" lsphp${PHPVER}-common="$V" lsphp${PHPVER}-ldap="$V"; then \
+        echo "FATAL: lsphp${PHPVER} $V is what cac_path_parity was compiled against," >&2; \
+        echo "       but the LiteSpeed repo no longer offers it (it keeps only the" >&2; \
+        echo "       current release). The ext-build stage is almost certainly a stale" >&2; \
+        echo "       cache hit — rebuild with --no-cache." >&2; \
+        exit 1; \
+    fi; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+    RTV=$(dpkg-query -W -f='${Version}' lsphp${PHPVER}); \
+    CMV=$(dpkg-query -W -f='${Version}' lsphp${PHPVER}-common); \
+    if [ "$RTV" != "$V" ] || [ "$CMV" != "$V" ]; then \
+        echo "FATAL: cac_path_parity.so was compiled against lsphp${PHPVER} $V but this" >&2; \
+        echo "       image would ship lsphp${PHPVER}=$RTV / -common=$CMV." >&2; \
+        echo "       Rebuild with --no-cache so both stages resolve the same release." >&2; \
+        exit 1; \
+    fi; \
+    echo "runtime lsphp${PHPVER} pinned to $V (the version cac_path_parity was built against)"

 ## Scripts + the SHARED production lsphp ini (reused verbatim from the litespeed
 ## image — same runtime, same tuning). Scripts layer last (they change most).
@@ -54,6 +184,34 @@ RUN bash -c 'set -e; \
    cp /etc/lsws-templates/lsphp-overrides.ini "$SCAN_DIR/99-prod-overrides.ini"; \
    echo "wrote overrides to $SCAN_DIR"'

+## Install the cac_path_parity extension into lsphp's own extension_dir and load
+## it unconditionally. It is INERT until the entrypoint writes the per-site
+## cac_path_parity.from/.to mapping, so it is safe in any context (including
+## wp-cli runs, where $_SERVER carries no filesystem paths).
+##
+## The trailing `lsphp -i | grep` is a BUILD-TIME ASSERTION: if the .so fails to
+## load (ABI drift after a base-image PHP bump, bad build) the image build fails
+## here rather than shipping a sidecar that silently lost path parity. Note its
+## limit: it proves the .so LOADS, not that it was built against these exact
+## structs — silent layout drift would sail straight through. The version lockstep
+## above is what actually removes that possibility; this stays as the backstop.
+## NOTE: probe lsphp with `-i` ONLY. The lsphp binary is the LSAPI SAPI, not the
+## CLI — it accepts just -[b|c|n|h|i|q|s|v|?] and answers anything else (`-m`,
+## `-r`) by printing its usage text and exiting 0. A `lsphp -m | grep` check
+## therefore never matches AND never fails, which is exactly the kind of silent
+## always-false assertion this whole change exists to eliminate.
+COPY --from=ext-build /build-out/cac_path_parity.so /tmp/cac_path_parity.so
+RUN bash -c 'set -e; \
+    LSPHP="/usr/local/lsws/lsphp${PHPVER}/bin/lsphp"; \
+    EXT_DIR=$("$LSPHP" -i 2>/dev/null | awk -F" => " "/^extension_dir/ {print \$2; exit}"); \
+    SCAN_DIR=$("$LSPHP" -i 2>/dev/null | awk -F"=> " "/^Scan this dir/ {print \$2; exit}"); \
+    mkdir -p "$EXT_DIR" "$SCAN_DIR"; \
+    mv /tmp/cac_path_parity.so "$EXT_DIR/"; \
+    printf "; installed by Dockerfile.lsphp\nextension=cac_path_parity.so\n" \
+        > "$SCAN_DIR/00-cac-path-parity.ini"; \
+    "$LSPHP" -i 2>/dev/null | grep -q "^cac_path_parity support => enabled$"; \
+    echo "cac_path_parity installed into $EXT_DIR and verified loadable"'
+
 ## php-lsapi gates .user.ini parsing behind this env var (see entrypoint-lsphp.sh
 ## for the full explanation). Set here so the value is visible in `docker inspect`
 ## and survives an entrypoint override; the entrypoint re-exports it with the same
@@ -24,9 +24,13 @@ FROM litespeedtech/openlitespeed:${OLS_VERSION}-lsphp${PHPVER}
 ##   - gettext-base: envsubst for render-shared-ols-config.sh
 ##   - openssl: self-signed cert for the :443 listener (HAProxy verifies none)
 ##   - curl/ca-certificates: HEALTHCHECK
+##   - procps: provides pgrep, which entrypoint-shared-ols.sh's ols_running()
+##     liveness check depends on. Only transitively present via the base image
+##     today (Ubuntu 24.04 pulls it in) — pin it explicitly so it can't be
+##     pruned as "unused" and silently break the supervisor's crash detection.
 RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
-        inotify-tools gettext-base openssl ca-certificates curl && \
+        inotify-tools gettext-base openssl ca-certificates curl procps && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*

@@ -51,6 +55,13 @@ EXPOSE 80 443

 ## Health: the entrypoint renders a catch-all _health vhost serving /healthz, so
 ## this passes from boot (zero customer sites) onward. Self-signed :443.
+##
+## MUST stay on /healthz, and must stay a LOOPBACK request. That vhost answers
+## 421 for every other path/Host so an unmapped customer hostname can never look
+## "up" to a monitor; /healthz answers 200 only for an internal client address
+## (loopback here). Probing `/` instead would fail the healthcheck and restart
+## the whole shared tier. WHP's setup-shared-ols.sh overrides this with the
+## equivalent `curl -sfk https://localhost/healthz`; keep the two in step.
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD curl -fsSk https://127.0.0.1/healthz || exit 1

@@ -0,0 +1,291 @@
+# Decision record: entrypoint boot posture on a failed `lsphp -i` probe, and CI gating for the pipeline-shape check
+
+Date: 2026-08-05
+Status: recommendations for sign-off; nothing here is implemented by this document.
+Background: the SIGPIPE-under-pipefail fix (here-strings replacing `printf | awk` in
+`scripts/entrypoint-lsphp.sh` and `scripts/entrypoint-litespeed.sh`) removed a boot-killing
+141 and, as a side effect, changed what happens when `lsphp -i` *genuinely* produces
+nothing. Two judgement calls were flagged for a human decision. This document is that
+decision's working-out.
+
+---
+
+## Call 1 — boot posture when `lsphp -i` genuinely fails
+
+### What actually happens today (post-fix, as-written in the repo)
+
+The two container types are **not** currently symmetric, which matters for the decision:
+
+- **`cac-lsphp`** (`scripts/entrypoint-lsphp.sh`): fail-open, but *not silent*. An empty
+  `SCAN_DIR` falls to an else-branch that distinguishes "lsphp answered but reported no
+  scan dir" from "`lsphp -i` produced no usable output at all" (`lsphp_info_is_usable`,
+  keyed on the `PHP Version =>` banner), prints a distinct `WARNING:` to stderr for each,
+  and every boot ends with a summary line
+  `entrypoint-lsphp: $_SERVER path parity = <MODE> (...)` where `<MODE>` becomes
+  `none (no scan dir)` or `none (lsphp -i unusable)`. So `docker logs` carries a
+  greppable verdict — but nothing on the platform consumes it.
+- **`cac-litespeed`** (`scripts/entrypoint-litespeed.sh`, lines 81–102): fail-open and
+  **completely silent**. `if [ -n "$SCAN_DIR" ] ... fi` with no else. An empty probe means
+  the per-site `error_log` ini and the opcache override ini are simply never written, and
+  nothing says so anywhere.
+- **Shared tiers** (`entrypoint-shared-ols.sh`, `entrypoint-shared-httpd.sh`): no
+  `lsphp -i` probe exists in them at all. The question is moot there today, but the
+  blast-radius argument below still applies if one is ever added.
+
+What degradation costs the customer, concretely:
+
+| Lost fragment | cac-lsphp | cac-litespeed | Customer-visible symptom |
+|---|---|---|---|
+| `99-user-error-log.ini` | yes | yes | PHP errors go to stderr/`docker logs` instead of `/home/$user/logs/php-fpm/error.log`. Baked `log_errors = On` still applies, so errors are *not lost* — they are somewhere the customer can't see and support doesn't look first. Ticket shape: "my error log is empty." |
+| `99-user-opcache.ini` | yes | yes | Panel-set opcache overrides silently revert to baked defaults (64 MB / 8000 files). A site tuned up for a big codebase gets cache thrash; hard to attribute. |
+| `99-cac-path-parity.ini` | yes | n/a | Extension gets no mapping ⇒ `$_SERVER` path parity with cac-fpm is lost entirely in the "no output" case (the auto_prepend fallback is only written in the "extension missing from module list" branch, which requires the probe to have answered). Symptom: Wordfence/path-sensitive plugins misbehave after migration; extremely hard to diagnose from the outside. |
+
+### The premise to examine first
+
+The fail-open argument assumes "the site serves either way; only ini fragments differ."
+That is true when `lsphp -i` answers but lacks a `Scan this dir` line (weird packaging,
+still a working interpreter). It is **much weaker** when `lsphp -i` produces *nothing*:
+the same `$LSPHP_BIN` that just failed to print phpinfo is what the entrypoint `exec`s
+as PID 1 to serve requests. A binary that can't run `-i` because of a missing shared
+library will not serve LSAPI either — fail-open in that case doesn't buy a serving
+container, it buys a container that passes `docker ps`, then wedges or crash-loops
+*after* the entrypoint's diagnostic moment has passed. So the two sub-cases deserve
+different treatment, and conflating them is the main framing error in a flat
+"fail-open vs fail-closed" question.
+
+But there is a counterweight, and it is specific to this fleet: **`lsphp -i` can fail
+transiently on a healthy image.** These hosts have documented fork-starvation episodes
+(Committed_AS pinned against CommitLimit during backup windows; it has broken backups
+before). A `fork()`/`execve` failure at boot time yields exactly "empty `LSPHP_INFO`"
+through the `|| true`. Under fail-closed, a container (re)starting during a memory-pressure
+window would refuse to boot **because of the host's state, not its own**, and its restart
+policy would then add restart churn to a host already under pressure. The previous
+incident has the same shape: the last time "the probe returned nothing useful" happened
+in production, the image was *fine* — the probe itself was broken (the SIGPIPE bug), and
+the fail-closed behavior converted a cosmetic probe defect into a fleet-wide
+fails-to-boot on busy hosts only. Historically, probe-side failures have outnumbered
+genuinely-corrupt-image failures **1–0 (or 2–0 counting fork starvation as observed
+class)**. That base rate is the strongest single argument against pure fail-closed.
+
+### Options
+
+**A. Fail-open as fixed (status quo).**
+- Buys: no false boot failures from probe-side defects or host memory pressure; matches
+  the extension's documented posture; sibling entrypoints consistent (once litespeed
+  gains the warning it currently lacks).
+- Costs: "starts but serves degraded" is precisely the state this platform is worst at
+  noticing — the container watchdog's filter has historically been `exited|dead|created`
+  only, blind to running-but-wrong, and its post-start verify checks `State.Running`, so
+  it would even score a restart of a degraded container as success. Nothing alerts on the
+  stderr WARNINGs. Realistic outcome of a genuine failure under Option A: **weeks of
+  silent degradation**, surfaced eventually as a confusing customer ticket ("where are my
+  errors?" / plugin misbehavior), with the diagnostic clue buried in `docker logs` of a
+  container nobody had reason to inspect.
+
+**B. Fail-closed (`exit 1`) whenever `lsphp -i` yields nothing usable.**
+- Buys: loud, immediate, operator-visible failure; watchdog catches `exited`; the
+  diagnostic (the WARNING line) is the *last* thing in `docker logs`, exactly where an
+  on-call looks first. A genuinely broken image cannot masquerade as healthy for weeks.
+- Costs: converts transient host-side failures (fork starvation) and any future
+  probe-side defect into customer downtime. On a bad-image push, every container that
+  restarts goes down *hard* — arguably correct (they weren't going to serve anyway), but
+  it also means a probe regression like the one just fixed would again be a mass boot
+  outage rather than a mass warning. The customer experience of B's false positive is
+  strictly worse than A's true positive: total outage vs. degraded-but-serving.
+- Note: B is not "the old behavior restored" — the old behavior also failed to boot on
+  *healthy* images because the probe itself was the broken part. Anyone arguing "the old
+  crash-loop caught real problems" should first account for the fact that the only
+  production firing of that crash was a false positive.
+
+**C. Fail-open + a machine-detectable degraded marker (middle).**
+Boot and serve, but make the degraded state a *first-class, monitorable fact* rather than
+a log line:
+1. On any degraded branch, write a marker file (e.g. `/run/cac-degraded` containing the
+   mode string) in addition to the existing stderr WARNING, in **both** entrypoints —
+   and add the currently missing warning + summary line to `entrypoint-litespeed.sh` so
+   the two siblings really are consistent (today's "consistency" claim is only half true).
+2. Retry the probe once or twice with a short sleep before accepting degradation. This
+   is nearly free and specifically absorbs the fork-starvation transient, which is the
+   most likely real-world cause of an empty probe on this fleet.
+3. Surface the marker: either a periodic platform check (`docker exec ... test -f
+   /run/cac-degraded` across cac containers, or grepping the boot summary line
+   `path parity = none` from `docker logs --tail`) wired into existing monitoring/alerting,
+   or fold it into the health story. **Caution on the healthcheck route:** the
+   HEALTHCHECKs (all seven Dockerfiles have one) are liveness probes; making "degraded
+   config" report unhealthy is tempting but risky — if the watchdog ever learns to
+   restart unhealthy containers, a persistently-degraded-but-serving site would be
+   restart-looped for a condition a restart cannot fix. Keep degraded ≠ unhealthy;
+   alert on the marker through a channel that pages a human instead of triggering an
+   automated restart.
+
+### Recommendation
+
+**Option C, with one fail-closed carve-out considered and (narrowly) rejected.**
+
+The carve-out I weighed: fail closed *only* in the `lsphp -i is unusable` sub-case (probe
+empty), fail open in the `answered but no scan dir` sub-case — on the logic that an
+interpreter that can't print phpinfo probably can't serve. I recommend against it, for
+two reasons. First, the fork-starvation transient lands in exactly that sub-case and
+would cause real, host-pressure-correlated boot failures of healthy sites; the retry in
+C(2) mitigates but can't eliminate it. Second, if the binary truly cannot execute, the
+final `exec "$LSPHP_BIN" -b ...` fails on its own a few lines later and PID 1 dies
+anyway — fail-closed-at-the-probe mostly duplicates a crash the container will have
+regardless, while adding a new false-positive class. The genuinely dangerous residue —
+binary runs but is subtly broken — is better caught by the existing HEALTHCHECK
+(TCP :9000 + `pgrep lsphp`), which *does* fail in that world; the platform gap is that
+the watchdog ignores unhealthy, and that gap is worth closing on its own merits.
+
+Per-type answer: same posture for `cac-lsphp` and `cac-litespeed` (their failure domains
+are equivalent for this probe; the current behavioral gap between them is an oversight,
+not a design). For **shared-tier** entrypoints the answer is *more* strongly fail-open
+than for per-site containers, should a similar probe ever appear there: a fail-closed
+shared tier takes down every site on the host, and the marginal diagnostic value of a
+crash over a marker does not scale with the blast radius.
+
+Why C over A, stated so it can be disagreed with: A and C serve the customer identically;
+they differ only in whether the platform can *notice*. The honest failure-likelihood
+ranking on this fleet is (1) transient probe failure under memory pressure, (2) probe
+logic regression, (3) genuinely broken image — and only (3) is the case where B
+outperforms. C handles (1) with the retry, (2) and (3) with the marker + alert, and its
+worst case is "degraded for as long as the alerting channel takes to be read" instead of
+A's "degraded for weeks" or B's "down because the host was busy." If you believe a
+corrupt image push is *more* likely than a probe/host transient, B becomes defensible —
+but the recent incident history says otherwise.
+
+What a customer experiences, per option, when the failure is genuine: A/C — site up,
+error log empty, opcache defaults, possible plugin path weirdness; C additionally gets it
+noticed and fixed in hours. B — site down until an operator acts, but the operator is
+paged immediately by existing machinery. Which failure gets silently tolerated for weeks:
+A's, unambiguously. B's cannot be (crash-loops are loud); C's only if the marker alert is
+never actually wired up — which is why C **is not done** until the alerting side ships,
+and shipping the marker without the consumer would be A with extra steps.
+
+Before committing, measure:
+- Fleet scan: does `path parity = none` (or an empty scan dir) occur on any live
+  container today? (`docker logs` grep across cac-lsphp/litespeed containers.) If it
+  already fires, the fix priority changes from "posture" to "why".
+- Frequency of boot-time fork failures during backup windows (correlate container start
+  timestamps with `MemAvailable` dips) — validates or kills the retry rationale.
+- Whether the watchdog's unhealthy-blindness fix (in progress platform-side) will ever
+  auto-restart on unhealthy; that decides whether degraded may ever map to unhealthy.
+
+---
+
+## Call 2 — should the new CI check gate releases?
+
+### What actually exists (`.gitea/workflows/build-push.yaml`)
+
+A `Shell-Checks` job runs on every push to trunk: (1) `bash -n` over every script,
+(2) `shellcheck -S warning` over an explicit allow-list of the pipefail-era scripts,
+(3) `scripts/tests/lsphp-info-probe.test.sh`, whose section 5 is the structural scan
+that outlaws early-exit-reader pipelines in any `pipefail`-enabled script under
+`scripts/` and `ext/`. None of the six image build jobs has `needs: Shell-Checks`, and
+the workflow's own comment says so: "a red job here does not block a push that is
+otherwise fine." So today a red check produces a red run *annotation* while all seven
+images publish anyway.
+
+False-positive surface, honestly assessed:
+- `bash -n` and the test's sections 1–4 are deterministic (the pre-fix pipeline is run
+  only informationally; no pass/fail depends on the race). Near-zero FP risk.
+- `shellcheck` runs against a hand-curated clean set, so it goes red only when a listed
+  file regresses or a new shellcheck version tightens — low FP risk, nonzero.
+- The structural scan is a line-oriented awk text scan with flat quote-stripping. Its
+  own header is candid: it can miss multi-line pipelines (false negatives) and could
+  misread exotic quoting (false positives). It requires the reader to be the first word
+  after `|` and special-cases `case a|b)`, `sed "s|x|y|"`, `||`. FP risk is real but
+  bounded — and an FP is a *visible* red on a specific line, trivially triaged.
+
+### Options
+
+**A. Leave it non-blocking (status quo).**
+Buys: zero risk that a scanner quirk halts a release. Costs: this platform's own history
+says non-blocking signals decay into wallpaper — one-shot installers drifted, the
+watchdog's blind spot sat unnoticed, and this exact bug class shipped to production
+through a green build gate and **two** code reviews. A check that exists precisely
+because the build gate can't see entrypoint runtime, but that cannot stop a release,
+protects nothing on the day it matters; it merely timestamps the moment the regression
+was ignorable. The failure it would have caught kills PID 1 on busy production hosts
+only — the single most expensive place to discover it.
+
+**B. Hard gate now (add `needs: Shell-Checks` to all six build jobs).**
+Buys: the regression class physically cannot ship again through this pipeline. Costs: an
+unproven scanner acquires veto power over every release, including emergency ones. Worth
+sizing that cost concretely rather than abstractly: releases here are operator-driven
+pushes to trunk, not a high-frequency train; a false red costs the minutes needed to read
+the offending line, either fix real sloppiness or adjust the scanner, and re-push. There
+is no mechanism by which a red silently *delays* an unattended release for days, because
+releases are attended. The scary version of "blocks all releases" mostly doesn't apply to
+this repo's release model. The one genuinely bad scenario: an urgent security rebuild
+blocked at 2 a.m. by a scanner FP — mitigable, since the operator can comment out one
+`needs:` line in the same push, an escape hatch that is itself visible in the diff.
+
+**C. Staged: soft-fail now, hard gate after N clean runs.**
+Buys: evidence before enforcement; if the scanner has an FP mode, it is discovered while
+red is cheap. Costs: N pushes of window during which the bug class can ship again, and a
+follow-up task of exactly the kind this platform historically forgets (see: one-shot
+installer drift). If staged, the flip must be a dated calendar/scheduler entry or a
+tracked ticket, not an intention.
+
+**D. Split the gate: hard-gate the deterministic steps now, soft-fail the scanner.**
+Put `bash -n` + the probe regression test (sections 1–4) in a blocking job immediately —
+they have effectively no FP surface and section 2's marker check alone prevents the
+specific regression (reintroducing the inline pipelines) — and leave shellcheck + the
+structural scan non-blocking until proven. Buys: immediate protection against the exact
+bug that happened, zero new FP-block risk. Costs: two jobs to maintain; the structural
+scan (the only piece that generalizes beyond this one probe) stays advisory.
+
+### Recommendation
+
+**B — make it a hard gate now**, with C's discipline applied only to future *additions*
+to the check, and one prerequisite: run the full `Shell-Checks` job as-is against the
+current trunk and the last ~5 release tags first (locally or via a manual dispatch) to
+confirm it is green on everything already shipped. If that back-test is green, gate. If
+it is not, fix or scope the scanner, then gate.
+
+Reasoning, laid out to be disagreeable-with: the decision hinges on comparing the two
+error costs *as they occur in this repo's actual release process*. A false red costs an
+attended operator minutes, with a one-line escape hatch, and every FP found makes the
+scanner better. A false green — or a true red that doesn't block — reproduces a
+production incident whose failure mode is "customer containers refuse to boot, but only
+on hosts busy enough to have collapsed pipe buffers," i.e. undetectable in dev by
+construction. The asymmetry is roughly minutes-of-operator-time vs.
+production-boot-outage, and the probability of FP red is bounded by a back-test we can
+run *today* instead of estimating. Choosing C is defensible only if you weight "new check
+might be flaky in ways a back-test can't reveal" highly — plausible for a check with
+runtime/timing behavior, but sections 1–4 are deterministic and section 5 is a pure text
+scan over files that are fully known at back-test time. Flakiness that a back-test can't
+surface would have to come from the runner environment (shellcheck version drift is the
+main one — worth pinning the shellcheck version when gating). D is the fallback if the
+back-test turns up scanner noise that can't be resolved same-day.
+
+Two obligations come with gating, or the gate rots:
+1. The shellcheck allow-list must grow with the repo — a new `set -o pipefail` script
+   that never gets listed is invisibly exempt from step (2) (the structural scan, by
+   contrast, auto-discovers pipefail scripts). A one-line CI assertion that every
+   pipefail-enabled script appears in the shellcheck list would close that seam.
+2. Green must not be oversold: the scanner's documented limits (single-line pipelines,
+   flat quote-stripping) mean a multi-line pipeline reintroduction passes it. The gate
+   raises the floor; it does not replace review. Record that limit where reviewers see
+   it (it already is, in the test header — keep it there).
+
+Before committing, measure: the back-test above (mandatory); shellcheck version on the
+Gitea runner vs. pinned (drift is the likeliest future FP source); and after gating,
+track red-run causes for the first month — if more than ~1 in 10 reds is a scanner FP,
+revisit with D.
+
+---
+
+## Framing notes (where the question as posed deserves push-back)
+
+1. "Previously it failed loudly and the watchdog caught it" is only half the history:
+   the *only* production firing of the loud failure was a false positive (the probe's own
+   SIGPIPE), not a broken image. The old posture's loudness was never demonstrated on a
+   genuine failure; pricing it as a proven detection mechanism overstates its record.
+2. The fail-open "consistency with the sibling" claim is currently aspirational:
+   `entrypoint-litespeed.sh` fails open *silently* while `entrypoint-lsphp.sh` fails open
+   loudly with mode strings. Whatever posture is chosen, making the siblings actually
+   consistent (warning + summary line + marker in both) is part of the work.
+3. "Fail-open vs fail-closed" flattens two distinct sub-cases — probe empty vs. probe
+   answered without a scan dir — that have different likely causes and different serving
+   prognoses. The entrypoint already distinguishes them in its reporting; the decision
+   should too (and above, does).
@@ -0,0 +1,41 @@
+# phpize / configure / make artifacts from building this extension locally.
+# The shipped build happens inside Dockerfile.lsphp's ext-build stage, so
+# nothing generated here is ever committed.
+.deps
+.libs/
+Makefile
+Makefile.fragments
+Makefile.global
+Makefile.objects
+acinclude.m4
+aclocal.m4
+autom4te.cache/
+build/
+config.guess
+config.h
+config.h.in
+config.log
+config.nice
+config.status
+config.sub
+configure
+configure.ac
+include/
+install-sh
+libtool
+ltmain.sh
+missing
+mkinstalldirs
+modules/
+run-tests.php
+*.lo
+*.la
+*.o
+*.so
+tests/*.php
+tests/*.diff
+tests/*.exp
+tests/*.log
+tests/*.out
+tests/*.sh
+!tests/fpm-parity-check.sh
@@ -0,0 +1,378 @@
+/*
+ * cac_path_parity — $_SERVER filesystem-path parity for the shared-ols tier.
+ *
+ * WHAT PROBLEM THIS SOLVES
+ * ------------------------
+ * A site on the standalone tiers (cac / cac-fpm / cac-litespeed) sees:
+ *
+ *     $_SERVER['DOCUMENT_ROOT']    = /home/<user>/public_html
+ *     $_SERVER['SCRIPT_FILENAME']  = /home/<user>/public_html/index.php
+ *
+ * On the shared-ols tier the webserver is a SHARED OpenLiteSpeed container that
+ * serves every tenant out of one bulk `/docker/users -> /mnt/users:ro` mount, so
+ * its vhost docRoot is /mnt/users/<user>/<domain>/public_html. OLS has no
+ * ProxyFCGISetEnvIf-style remap (unlike shared-httpd -> cac-fpm): it hands lsphp
+ * exactly that path. The cac-lsphp sidecar symlinks /mnt/users/<user>/<domain>
+ * -> /home/<user>, so every file OPERATION resolves and PHP's own __FILE__ /
+ * __DIR__ / realpath() / getcwd() already report /home/<user>/... — but the RAW
+ * strings OLS put in $_SERVER still read /mnt/users. Moving a site from cac-fpm
+ * to cac-lsphp therefore changed two $_SERVER values, which is exactly the kind
+ * of difference that surfaces later as a broken plugin path or a mismatched
+ * absolute path stored in the database.
+ *
+ * WHY THIS IS AN EXTENSION AND NOT AN auto_prepend_file
+ * -----------------------------------------------------
+ * The first fix was an `auto_prepend_file` drop-in that realpath()'d the two
+ * keys. `auto_prepend_file` is PHP_INI_PERDIR, so ANY site with its own
+ * .user.ini auto_prepend_file silently displaces it and the normaliser never
+ * runs — the state 7 live shared_ols sites are actually in today (Wordfence and
+ * cPanel imports). PHP resolves a single winning value for auto_prepend_file
+ * after the .user.ini chain is parsed, so there is no way to "chain" from the
+ * losing side either.
+ *
+ * The obvious hardening — `php_admin_value auto_prepend_file` — is WORSE, not
+ * better: making our prepend un-overridable makes the customer's prepend
+ * un-runnable, which would disable those same 7 Wordfence WAFs. The two goals
+ * are irreconcilable as long as the mechanism IS the prepend hook.
+ *
+ * An extension sidesteps that entirely. RINIT runs before any userland code and
+ * cannot be displaced by .user.ini, and it consumes no userland hook — so the
+ * customer's auto_prepend_file remains the only prepend in play and keeps
+ * working untouched. Both constraints are satisfied at once.
+ *
+ * The mapping comes from two PHP_INI_SYSTEM entries. PHP_INI_SYSTEM is NOT
+ * settable from .user.ini (which honours only PHP_INI_PERDIR/PHP_INI_USER), nor
+ * from ini_set(), nor from .htaccess — so a customer cannot point the rewrite
+ * somewhere else or switch it off. The cac-lsphp entrypoint writes them from the
+ * same `user`/`domain` env the symlink is built from, so the two can't drift.
+ *
+ * WHY A STRING PREFIX SWAP AND NOT realpath()
+ * -------------------------------------------
+ * The old normaliser called realpath(), which worked only because the sidecar
+ * symlinks /mnt/users/<user>/<domain> -> /home/<user>. A plain prefix swap is
+ * better on every axis that matters here:
+ *
+ *   - It is byte-identical to cac-fpm BY CONSTRUCTION. realpath() resolves ALL
+ *     symlinks, so a customer who makes public_html itself a symlink would get
+ *     some third path — cac-fpm reports the literal /home/<user>/public_html.
+ *   - It cannot fail. realpath() returns false for a path that does not exist
+ *     (and is constrained by open_basedir), leaving the value half-normalised.
+ *   - It costs no syscall. realpath() is an lstat chain on every request.
+ *
+ * The prefix is this site's FULL mount path (/mnt/users/<user>/<domain>), not
+ * the bare bulk-mount root, and it only matches on a path-component boundary —
+ * so a value pointing at another tenant, or one that is already canonical, is
+ * never touched.
+ *
+ * FAILURE MODES — every one of them leaves $_SERVER untouched and lets the
+ * request proceed. Nothing here can warn, throw, or 500 a customer site:
+ *   - mapping unset/empty (any tier that is not shared-ols) -> RINIT returns
+ *     immediately, extension is inert.
+ *   - either side of the mapping not an ABSOLUTE path       -> inert. Nothing
+ *     the entrypoint writes is anything else, and a relative prefix cannot
+ *     usefully match a SAPI-supplied path, so a malformed mapping is treated
+ *     exactly like an absent one.
+ *   - $_SERVER absent or not an array                       -> return.
+ *   - key absent from $_SERVER                              -> skip that key.
+ *   - key present but not a string                          -> skip that key.
+ *   - value shorter than the prefix / prefix mismatch       -> skip that key.
+ *   - value matches the prefix mid-component                -> skip that key.
+ * There is no error path, no userland-visible diagnostic, and no dependency on
+ * the filesystem being readable.
+ *
+ * The one thing this CANNOT detect is a well-formed but WRONG mapping: it will
+ * confidently rewrite to a wrong path and say nothing. That is accepted by
+ * construction rather than overlooked — entrypoint-lsphp.sh derives from/to from
+ * the same two variables it builds the compatibility symlink from, so a wrong
+ * mapping means the symlink is wrong too and the site is already broken in a far
+ * louder way. The only runtime signal is `lsphp -i`, which prints
+ * "Rewriting => active" alongside the live from/to values.
+ *
+ * That row is what the post-deploy fleet canary greps, so MINFO's "active" test
+ * must stay a mirror of the conditions RINIT actually rewrites under — see
+ * PHP_MINFO_FUNCTION below, which shares cacpp_mapping_active() with RINIT
+ * precisely so the two cannot drift. A MINFO that reported "active" for a
+ * mapping RINIT treats as inert would mask exactly the failure the canary
+ * exists to catch.
+ *
+ * SCOPE / KNOWN LIMITS
+ * --------------------
+ * Only $_SERVER is rewritten. LSAPI also answers getenv('DOCUMENT_ROOT') from
+ * the request environment, and that still returns the /mnt/users string. That is
+ * a deliberate limit: touching the SAPI environment risks the request env lsphp
+ * itself reads. Real-world PHP (WordPress and its plugin ecosystem) reads
+ * $_SERVER, not getenv(), for these.
+ *
+ * The sidecar's compatibility symlink is still REQUIRED and is not replaced by
+ * this extension: it is what makes the path OLS sends actually resolve on disk.
+ * This extension only corrects the strings.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "php.h"
+#include "php_ini.h"
+#include "ext/standard/info.h"
+#include "SAPI.h"
+#include "zend_compile.h" /* zend_is_auto_global_str() */
+#include "php_cac_path_parity.h"
+
+ZEND_DECLARE_MODULE_GLOBALS(cac_path_parity)
+
+#define CACPP_G(v) ZEND_MODULE_GLOBALS_ACCESSOR(cac_path_parity, v)
+
+/*
+ * The $_SERVER keys that carry a FILESYSTEM path. URI-derived keys (PHP_SELF,
+ * SCRIPT_NAME, REQUEST_URI) are already identical across tiers and are left
+ * alone. PATH_TRANSLATED and CONTEXT_DOCUMENT_ROOT are usually absent under
+ * OLS; rewriting them is a no-op when they are, and correct when they are not.
+ */
+static const struct {
+	const char *name;
+	size_t      len;
+} cacpp_keys[] = {
+	{ ZEND_STRL("DOCUMENT_ROOT") },
+	{ ZEND_STRL("SCRIPT_FILENAME") },
+	{ ZEND_STRL("PATH_TRANSLATED") },
+	{ ZEND_STRL("CONTEXT_DOCUMENT_ROOT") },
+};
+
+/* clang-format off */
+PHP_INI_BEGIN()
+	/*
+	 * PHP_INI_SYSTEM is load-bearing: it is the reason a customer's .user.ini
+	 * cannot reach these. Do not relax to PERDIR.
+	 */
+	STD_PHP_INI_ENTRY("cac_path_parity.from", "", PHP_INI_SYSTEM, OnUpdateString,
+	                  from, zend_cac_path_parity_globals, cac_path_parity_globals)
+	STD_PHP_INI_ENTRY("cac_path_parity.to",   "", PHP_INI_SYSTEM, OnUpdateString,
+	                  to,   zend_cac_path_parity_globals, cac_path_parity_globals)
+PHP_INI_END()
+/* clang-format on */
+
+static PHP_GINIT_FUNCTION(cac_path_parity)
+{
+#if defined(COMPILE_DL_CAC_PATH_PARITY) && defined(ZTS)
+	ZEND_TSRMLS_CACHE_UPDATE();
+#endif
+	cac_path_parity_globals->from = NULL;
+	cac_path_parity_globals->to   = NULL;
+}
+
+/*
+ * THE MAPPING PREDICATE — one definition, two callers.
+ *
+ * RINIT uses it to decide whether to rewrite; MINFO uses it to REPORT whether
+ * rewriting is live. Those two tests were written out longhand in two places
+ * and promptly drifted: the absolute-path guard was added to RINIT only, so
+ * `lsphp -i` went on printing "Rewriting => active" for a mapping RINIT had
+ * already decided to ignore. That row is the fleet canary's signal, so the lie
+ * masked precisely the failure the canary looks for. Keep them sharing this.
+ *
+ * Pure predicates over two NUL-terminated strings: no allocation, no side
+ * effect, no way to fail — MINFO gains no error path by calling them, and the
+ * fail-open invariant is untouched.
+ */
+static int cacpp_mapping_configured(const char *from, const char *to)
+{
+	return from != NULL && *from != '\0' && to != NULL && *to != '\0';
+}
+
+static int cacpp_mapping_active(const char *from, const char *to)
+{
+	return cacpp_mapping_configured(from, to) && *from == '/' && *to == '/';
+}
+
+/* Trailing slashes would defeat the component-boundary test below. */
+static size_t cacpp_trim(const char *s, size_t len)
+{
+	while (len > 1 && s[len - 1] == '/') {
+		len--;
+	}
+	return len;
+}
+
+static void cacpp_rewrite_key(zval *server, const char *key, size_t key_len,
+                              const char *from, size_t from_len,
+                              const char *to, size_t to_len)
+{
+	zval *val = zend_hash_str_find(Z_ARRVAL_P(server), key, key_len);
+	if (val == NULL) {
+		return;
+	}
+	ZVAL_DEREF(val);
+	if (Z_TYPE_P(val) != IS_STRING) {
+		return;
+	}
+
+	const char *s   = Z_STRVAL_P(val);
+	size_t      len = Z_STRLEN_P(val);
+
+	if (len < from_len || memcmp(s, from, from_len) != 0) {
+		return;
+	}
+	/*
+	 * Only replace on a PATH-COMPONENT boundary. Without this,
+	 * from=/mnt/users/bob/site.com would also match a sibling directory
+	 * /mnt/users/bob/site.com.bak and silently rewrite another site's path
+	 * into this site's /home.
+	 */
+	if (len != from_len && s[from_len] != '/') {
+		return;
+	}
+
+	size_t tail_len = len - from_len;
+
+	/*
+	 * to="/" is the one absolute prefix that survives cacpp_trim() as a bare
+	 * separator, and the tail always starts with one — splicing both would give
+	 * "//public_html". Drop it when there IS a tail; keep it when there is not
+	 * (value == from exactly, where "/" is the correct answer). Unreachable from
+	 * the entrypoint, which always writes to=/home/<user>.
+	 */
+	size_t eff_to_len = to_len;
+	if (tail_len > 0 && eff_to_len == 1 && to[0] == '/') {
+		eff_to_len = 0;
+	}
+
+	zend_string *out = zend_string_alloc(eff_to_len + tail_len, 0);
+
+	memcpy(ZSTR_VAL(out), to, eff_to_len);
+	memcpy(ZSTR_VAL(out) + eff_to_len, s + from_len, tail_len);
+	ZSTR_VAL(out)[eff_to_len + tail_len] = '\0';
+
+	zval nv;
+	ZVAL_STR(&nv, out);
+	/*
+	 * Update the track_vars array IN PLACE. $_SERVER in the symbol table and
+	 * PG(http_globals)[TRACK_VARS_SERVER] are two references to the SAME
+	 * zend_array, which is why this is visible to userland. Do NOT
+	 * SEPARATE_ARRAY() here: that would copy the array and leave the symbol
+	 * table pointing at the original, i.e. silently do nothing. This is the
+	 * same in-place pattern php_register_variable_ex() uses.
+	 */
+	zend_hash_str_update(Z_ARRVAL_P(server), key, key_len, &nv);
+}
+
+PHP_RINIT_FUNCTION(cac_path_parity)
+{
+#if defined(ZTS) && defined(COMPILE_DL_CAC_PATH_PARITY)
+	ZEND_TSRMLS_CACHE_UPDATE();
+#endif
+
+	const char *from = CACPP_G(from);
+	const char *to   = CACPP_G(to);
+
+	/* Unconfigured (any tier that isn't shared-ols) => completely inert. */
+	if (!cacpp_mapping_configured(from, to)) {
+		return SUCCESS;
+	}
+
+	/*
+	 * Both sides must be ABSOLUTE. The entrypoint only ever writes absolute
+	 * paths; a relative prefix would be a typo or a mangled ini, and matching it
+	 * against a SAPI-supplied path could only ever produce nonsense. Treat it
+	 * like an absent mapping — inert, no diagnostic, request proceeds.
+	 */
+	if (!cacpp_mapping_active(from, to)) {
+		return SUCCESS;
+	}
+
+	/*
+	 * With auto_globals_jit=On (the default) $_SERVER is not built yet at
+	 * RINIT — php_hash_environment() only MARKED it for lazy creation. Reading
+	 * PG(http_globals)[TRACK_VARS_SERVER] here without this call finds IS_UNDEF
+	 * and the extension silently does nothing, which is precisely the failure
+	 * the auto_prepend approach had. Forcing the auto-global now builds it (via
+	 * the SAPI's register_server_variables) so there is something to rewrite,
+	 * and the later userland access gets the corrected array.
+	 */
+	zend_is_auto_global_str(ZEND_STRL("_SERVER"));
+
+	zval *server = &PG(http_globals)[TRACK_VARS_SERVER];
+	if (Z_TYPE_P(server) != IS_ARRAY) {
+		return SUCCESS;
+	}
+
+	size_t from_len = cacpp_trim(from, strlen(from));
+	size_t to_len   = cacpp_trim(to, strlen(to));
+
+	for (size_t i = 0; i < sizeof(cacpp_keys) / sizeof(cacpp_keys[0]); i++) {
+		cacpp_rewrite_key(server, cacpp_keys[i].name, cacpp_keys[i].len,
+		                  from, from_len, to, to_len);
+	}
+
+	return SUCCESS;
+}
+
+PHP_MINIT_FUNCTION(cac_path_parity)
+{
+	REGISTER_INI_ENTRIES();
+	return SUCCESS;
+}
+
+PHP_MSHUTDOWN_FUNCTION(cac_path_parity)
+{
+	UNREGISTER_INI_ENTRIES();
+	return SUCCESS;
+}
+
+PHP_MINFO_FUNCTION(cac_path_parity)
+{
+	const char *from = CACPP_G(from);
+	const char *to   = CACPP_G(to);
+
+	/*
+	 * Report what RINIT would ACTUALLY do, by asking the same predicates RINIT
+	 * asks — never a longhand copy of them (see cacpp_mapping_active above for
+	 * what that cost last time). Three distinct answers, because "configured but
+	 * ignored" is a different operational problem from "not configured" and the
+	 * canary must be able to tell them apart.
+	 */
+	const char *state;
+	if (cacpp_mapping_active(from, to)) {
+		state = "active";
+	} else if (cacpp_mapping_configured(from, to)) {
+		state = "inactive (mapping not absolute)";
+	} else {
+		state = "inactive (unconfigured)";
+	}
+
+	php_info_print_table_start();
+	php_info_print_table_header(2, "cac_path_parity support", "enabled");
+	php_info_print_table_row(2, "Version", PHP_CAC_PATH_PARITY_VERSION);
+	/*
+	 * The canary greps for this row: "active" proves the mapping is live — and,
+	 * since the predicate is shared with RINIT, proves the request path agrees.
+	 */
+	php_info_print_table_row(2, "Rewriting", state);
+	php_info_print_table_end();
+
+	DISPLAY_INI_ENTRIES();
+}
+
+zend_module_entry cac_path_parity_module_entry = {
+	STANDARD_MODULE_HEADER,
+	"cac_path_parity",
+	NULL,                          /* no userland functions — by design */
+	PHP_MINIT(cac_path_parity),
+	PHP_MSHUTDOWN(cac_path_parity),
+	PHP_RINIT(cac_path_parity),
+	NULL,                          /* RSHUTDOWN */
+	PHP_MINFO(cac_path_parity),
+	PHP_CAC_PATH_PARITY_VERSION,
+	PHP_MODULE_GLOBALS(cac_path_parity),
+	PHP_GINIT(cac_path_parity),
+	NULL,                          /* GSHUTDOWN */
+	NULL,                          /* post-deactivate */
+	STANDARD_MODULE_PROPERTIES_EX
+};
+
+#ifdef COMPILE_DL_CAC_PATH_PARITY
+#if defined(ZTS)
+ZEND_TSRMLS_CACHE_DEFINE()
+#endif
+ZEND_GET_MODULE(cac_path_parity)
+#endif
@@ -0,0 +1,15 @@
+dnl config.m4 for the cac_path_parity extension.
+dnl Built out-of-tree against the image's own lsphp:
+dnl   phpize && ./configure --with-php-config=/usr/local/lsws/lsphpNN/bin/php-config
+dnl No external libraries, no optional features — pure core API.
+
+PHP_ARG_ENABLE([cac_path_parity],
+  [whether to enable cac_path_parity support],
+  [AS_HELP_STRING([--enable-cac-path-parity],
+    [Enable cac_path_parity ($_SERVER path parity for the shared-ols tier)])],
+  [no])
+
+if test "$PHP_CAC_PATH_PARITY" != "no"; then
+  AC_DEFINE(HAVE_CAC_PATH_PARITY, 1, [Have cac_path_parity support])
+  PHP_NEW_EXTENSION(cac_path_parity, cac_path_parity.c, $ext_shared)
+fi
@@ -0,0 +1,24 @@
+/*
+ * cac_path_parity — $_SERVER filesystem-path parity for the shared-ols tier.
+ *
+ * See cac_path_parity.c for the full rationale.
+ */
+
+#ifndef PHP_CAC_PATH_PARITY_H
+#define PHP_CAC_PATH_PARITY_H
+
+extern zend_module_entry cac_path_parity_module_entry;
+#define phpext_cac_path_parity_ptr &cac_path_parity_module_entry
+
+#define PHP_CAC_PATH_PARITY_VERSION "1.0.0"
+
+#if defined(ZTS) && defined(COMPILE_DL_CAC_PATH_PARITY)
+ZEND_TSRMLS_CACHE_EXTERN()
+#endif
+
+ZEND_BEGIN_MODULE_GLOBALS(cac_path_parity)
+	char *from;
+	char *to;
+ZEND_END_MODULE_GLOBALS(cac_path_parity)
+
+#endif /* PHP_CAC_PATH_PARITY_H */
@@ -0,0 +1,25 @@
+--TEST--
+cac_path_parity: rewrites the configured prefix on a filesystem $_SERVER key
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com/public_html
+HTTP_HOST=site.com
+--FILE--
+<?php
+// NOTE: the CLI SAPI overwrites DOCUMENT_ROOT (to "") and SCRIPT_FILENAME /
+// PATH_TRANSLATED (to the script path) AFTER the env import, so those three
+// cannot be driven from --ENV-- here. They go through the identical code path
+// as CONTEXT_DOCUMENT_ROOT (one loop over one key table); the real web-SAPI
+// proof for them is tests/fpm-parity-check.sh.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+// Non-path vars must be untouched.
+var_dump($_SERVER['HTTP_HOST']);
+?>
+--EXPECT--
+string(21) "/home/bob/public_html"
+string(8) "site.com"
@@ -0,0 +1,18 @@
+--TEST--
+cac_path_parity: a sibling dir sharing the prefix is NOT rewritten
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com.bak/public_html
+--FILE--
+<?php
+// Replacement happens only on a path-COMPONENT boundary. Without that guard a
+// neighbouring directory would be folded into this container's /home.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(39) "/mnt/users/bob/site.com.bak/public_html"
@@ -0,0 +1,17 @@
+--TEST--
+cac_path_parity: an exact prefix match (no trailing component) is rewritten
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com/
+cac_path_parity.to=/home/bob/
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com
+--FILE--
+<?php
+// Also covers trailing slashes in the configured values being tolerated.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(9) "/home/bob"
@@ -0,0 +1,16 @@
+--TEST--
+cac_path_parity: completely inert when no mapping is configured
+--EXTENSIONS--
+cac_path_parity
+--INI--
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com/public_html
+--FILE--
+<?php
+// cac-fpm / cac-litespeed never configure a mapping, so the extension must be
+// a no-op there. This is the no-regression guarantee for the other tiers.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(35) "/mnt/users/bob/site.com/public_html"
@@ -0,0 +1,20 @@
+--TEST--
+cac_path_parity: works with auto_globals_jit=On (lazy $_SERVER, the default)
+--EXTENSIONS--
+cac_path_parity
+--INI--
+auto_globals_jit=1
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com/public_html
+--FILE--
+<?php
+// With auto_globals_jit=On, $_SERVER does not exist yet when extension RINIT
+// runs. The extension forces the auto-global so there is something to rewrite;
+// drop that call and this test prints the /mnt/users path.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(21) "/home/bob/public_html"
@@ -0,0 +1,25 @@
+--TEST--
+cac_path_parity: mapping is PHP_INI_SYSTEM — userland cannot change it
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com/public_html
+--FILE--
+<?php
+// PHP_INI_SYSTEM entries are not modifiable at runtime, and .user.ini honours
+// only PHP_INI_PERDIR|PHP_INI_USER — so a customer cannot redirect or disable
+// the rewrite the way they can displace an auto_prepend_file.
+var_dump(ini_set('cac_path_parity.from', '/tmp'));
+var_dump(ini_set('cac_path_parity.to', '/tmp'));
+var_dump(ini_get('cac_path_parity.from'));
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+bool(false)
+bool(false)
+string(23) "/mnt/users/bob/site.com"
+string(21) "/home/bob/public_html"
@@ -0,0 +1,20 @@
+--TEST--
+cac_path_parity: a non-absolute mapping is inert, not applied
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=mnt/users/bob/site.com/public_html
+--FILE--
+<?php
+// The value here is deliberately relative TOO, so the prefix would match and be
+// rewritten if the absolute-path guard in RINIT were removed. Nothing the
+// entrypoint writes looks like this; the guard exists so a mangled ini degrades
+// to "inert" rather than to "confidently wrong".
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(34) "mnt/users/bob/site.com/public_html"
@@ -0,0 +1,20 @@
+--TEST--
+cac_path_parity: to=/ does not produce a doubled separator
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/
+variables_order=EGPCS
+--ENV--
+CONTEXT_DOCUMENT_ROOT=/mnt/users/bob/site.com/public_html
+--FILE--
+<?php
+// Degenerate mapping, unreachable from entrypoint-lsphp.sh (which always writes
+// to=/home/<user>). Before the eff_to_len collapse this returned
+// "//public_html". A path with a doubled leading slash is not the same string as
+// the cac-fpm value, which is the entire point of this extension.
+var_dump($_SERVER['CONTEXT_DOCUMENT_ROOT']);
+?>
+--EXPECT--
+string(12) "/public_html"
@@ -0,0 +1,30 @@
+--TEST--
+cac_path_parity: MINFO reports a non-absolute mapping as INACTIVE, not active
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+--FILE--
+<?php
+// `lsphp -i | grep Rewriting` is the signal the post-deploy fleet canary uses to
+// confirm parity is live on a host. When the absolute-path guard was added to
+// RINIT, MINFO was left testing only "both values non-empty" — so this exact
+// mapping (relative `from`, silently INERT since 007) still printed
+// "Rewriting => active". A canary that reports healthy for a dead mapping hides
+// precisely the failure it was deployed to find.
+//
+// MINFO and RINIT now share cacpp_mapping_active(); revert MINFO to the
+// non-empty test and this prints "active".
+ob_start();
+phpinfo(INFO_MODULES);
+$info = ob_get_clean();
+
+// Also assert the row is unique, so the match below cannot be some other
+// module's identically-named row.
+var_dump(preg_match_all('/^Rewriting => (.+)$/m', $info, $m));
+var_dump(rtrim($m[1][0]));
+?>
+--EXPECT--
+int(1)
+string(31) "inactive (mapping not absolute)"
@@ -0,0 +1,24 @@
+--TEST--
+cac_path_parity: MINFO reports a well-formed mapping as ACTIVE
+--EXTENSIONS--
+cac_path_parity
+--INI--
+cac_path_parity.from=/mnt/users/bob/site.com
+cac_path_parity.to=/home/bob
+--FILE--
+<?php
+// The other half of 009. Tightening MINFO must not overshoot into the opposite
+// lie: a canary that reports "inactive" on a perfectly good mapping would page
+// the fleet for nothing and, worse, train us to ignore the row. This mapping is
+// the exact shape entrypoint-lsphp.sh writes (/mnt/users/<user>/<domain> ->
+// /home/<user>), and 001 proves RINIT really does rewrite under it.
+ob_start();
+phpinfo(INFO_MODULES);
+$info = ob_get_clean();
+
+var_dump(preg_match_all('/^Rewriting => (.+)$/m', $info, $m));
+var_dump(rtrim($m[1][0]));
+?>
+--EXPECT--
+int(1)
+string(6) "active"
@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+## fpm-parity-check.sh — end-to-end proof under a REAL web SAPI.
+##
+## WHY NOT .phpt: the CLI SAPI overwrites DOCUMENT_ROOT / SCRIPT_FILENAME /
+## PATH_TRANSLATED after importing the environment, and the cli-server SAPI does
+## not process .user.ini at all — so neither can exercise the two things that
+## actually matter here.
+##
+## WHY PHP-FPM: php-fpm takes DOCUMENT_ROOT and SCRIPT_FILENAME as caller-
+## supplied FastCGI params and honours .user.ini — structurally the same shape as
+## OpenLiteSpeed handing a detached lsphp its LSAPI params. It is the closest
+## analogue available without an OLS runtime.
+##
+## Asserts:
+##   1. CONTROL   — no mapping => PHP reports the raw /mnt/users paths, i.e. the
+##                  test reproduces the bug before claiming to fix it.
+##   2. FIX       — mapping    => both keys read /home/<user>/... .
+##   3. WORDFENCE — mapping AND a customer .user.ini auto_prepend_file (the state
+##                  7 live shared_ols sites are in): paths are STILL corrected
+##                  AND the customer's prepend STILL runs. This is the case the
+##                  old auto_prepend_file normaliser silently lost.
+##   4. OLD       — for the record: the previous auto_prepend mechanism, with the
+##                  same customer .user.ini, does NOT run. This is the evidence
+##                  that hardening the prepend hook could not have worked.
+##
+## Exit codes: 0 = all assertions passed, 1 = an assertion FAILED, 2 = the
+## harness could not run (missing binary, php-fpm refused to start, .so would not
+## load). 2 is deliberately distinct from 1: a startup problem previously
+## surfaced as all nine assertions failing with an empty `got:`, which reads like
+## nine parity bugs and is the opposite of the truth.
+##
+## Usage:  ./fpm-parity-check.sh [ROOT] [PHP_FPM_BIN] [EXT_SO]
+##   ROOT defaults to /mnt/users (falls back to a temp dir if not creatable).
+##   PHP_FPM_BIN is auto-detected; every packaging of php-fpm this repo touches
+##   uses a different name (`php-fpm` in the official docker images,
+##   `php-fpm8.N` on Debian/Ubuntu, /usr/sbin/... unlinked from PATH), so a
+##   single hardcoded default is guaranteed to be wrong somewhere and its only
+##   symptom was a silent `SKIP`.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+find_fpm() {
+	local c
+	for c in php-fpm php-fpm8.5 php-fpm8.4 php-fpm8.3 php-fpm8.2 php-fpm8.1; do
+		if command -v "$c" >/dev/null 2>&1; then command -v "$c"; return 0; fi
+	done
+	for c in /usr/local/sbin/php-fpm /usr/sbin/php-fpm /usr/sbin/php-fpm8.*; do
+		if [ -x "$c" ]; then echo "$c"; return 0; fi
+	done
+	return 1
+}
+
+ROOT="${1:-/mnt/users}"
+FPM_BIN="${2:-$(find_fpm || true)}"
+EXT_SO="${3:-$HERE/../modules/cac_path_parity.so}"
+PORT="${PORT:-9001}"
+
+command -v cgi-fcgi >/dev/null || { echo "SKIP: cgi-fcgi not installed (apt install libfcgi-bin)"; exit 0; }
+[ -n "$FPM_BIN" ] && [ -x "$FPM_BIN" ] || { echo "SKIP: php-fpm not found (pass it as \$2)"; exit 0; }
+[ -f "$EXT_SO" ] || { echo "SKIP: $EXT_SO not built (run phpize && ./configure && make)"; exit 0; }
+
+## `${VAR%%$'\n'*}` rather than `| head -1`: same first line, no pipeline, so
+## nothing here can be decided by a SIGPIPE race under the pipefail on line 39.
+## This one only ever fed an echo, so it could not have misled anyone — it is
+## changed so that "no pipefail script in this repo pipes into an early-exit
+## reader" stays a rule with no exceptions to remember.
+FPM_VERSION=$("$FPM_BIN" -n -v 2>/dev/null || true)
+echo "php-fpm:   $FPM_BIN (${FPM_VERSION%%$'\n'*})"
+echo "extension: $EXT_SO"
+
+## Pre-flight. If the .so will not load into THIS php-fpm (PHP API mismatch is
+## the usual cause) every assertion below would fail identically and blame the
+## extension's logic. Say what actually happened instead.
+## Captured into a variable and matched with a here-string, not piped into
+## `grep -qx`. `grep -q` exits on its first match, and with `set -o pipefail`
+## (line 39) a writer still writing at that moment dies 141 and the pipeline
+## reads FALSE — announcing "cannot load the extension" *because* the extension
+## was listed. The reason to change it is structural, not that `php-fpm -m` is
+## small: there is no payload size that makes this shape safe (41 KB SIGPIPEs
+## about 11% of the time into a 64 KB pipe — see the note over the probe helpers
+## in scripts/entrypoint-lsphp.sh), and this pre-flight exists precisely to stop
+## a harness malfunction being reported as an extension fault, so it must not
+## have one of its own. (The same construct on 40 KB of `lsphp -i` is what broke
+## entrypoint-lsphp.sh in production.)
+##
+## A here-string, not the `[[ ]]` form those helpers use, on purpose: `<<<`
+## spills to /tmp/sh-thd.XXXXXX above ~4-64 KB depending on the bash build, so
+## it is a writable-temp-dir precondition, which is unacceptable on a boot path
+## and irrelevant here — `php-fpm -m` is ~1 KB, and this harness has already
+## created a docroot and a pool config by the time it runs.
+FPM_MODULES=$("$FPM_BIN" -n -d "extension=$EXT_SO" -m 2>/dev/null || true)
+if ! grep -qx 'cac_path_parity' <<<"$FPM_MODULES"; then
+	echo "HARNESS FAILURE: $FPM_BIN cannot load $EXT_SO" >&2
+	"$FPM_BIN" -n -d "extension=$EXT_SO" -m 2>&1 | grep -i 'unable\|warning\|error' >&2
+	echo "  The .so must be built against the same PHP as this php-fpm binary." >&2
+	exit 2
+fi
+
+mkdir -p "$ROOT" 2>/dev/null || ROOT="$(mktemp -d)/mnt/users"
+USER_NAME=bob
+SITE="$ROOT/$USER_NAME/site.com"
+DOCROOT="$SITE/public_html"
+HOME_PATH="/home/$USER_NAME"
+TMP="$(mktemp -d)"
+fail=0
+
+## php-fpm REFUSES to start as root unless the pool names a non-root user/group,
+## and the pool this script generates had neither — so as shipped it never got
+## past startup in any root context (which is every container in this repo).
+## Resolve a real unprivileged account rather than assuming www-data exists.
+POOL_USER=""
+POOL_GROUP=""
+if [ "$(id -u)" -eq 0 ]; then
+	for u in www-data nobody daemon; do
+		if id -u "$u" >/dev/null 2>&1; then POOL_USER="$u"; break; fi
+	done
+	for g in www-data nogroup nobody daemon; do
+		if getent group "$g" >/dev/null 2>&1; then POOL_GROUP="$g"; break; fi
+	done
+	[ -n "$POOL_USER" ] && [ -n "$POOL_GROUP" ] || {
+		echo "HARNESS FAILURE: running as root but found no unprivileged user/group for the pool" >&2
+		exit 2
+	}
+fi
+
+mkdir -p "$DOCROOT" || { echo "cannot create $DOCROOT"; exit 1; }
+## The pool worker is not root: it has to be able to read the fixtures under
+## $TMP (mktemp -d is 0700) and walk down to $DOCROOT.
+chmod 755 "$TMP"
+trap 'rm -rf "$TMP"; rm -f "$DOCROOT/.user.ini"' EXIT
+
+cat > "$DOCROOT/probe.php" <<'PHP'
+<?php
+echo "DOCUMENT_ROOT="   . $_SERVER['DOCUMENT_ROOT']   . "\n";
+echo "SCRIPT_FILENAME=" . $_SERVER['SCRIPT_FILENAME'] . "\n";
+echo "PREPEND_RAN="     . (defined('CUSTOMER_PREPEND_RAN') ? 'yes' : 'no') . "\n";
+PHP
+
+## Stand-in for the customer's wordfence-waf.php.
+cat > "$SITE/customer-waf.php" <<'PHP'
+<?php
+define('CUSTOMER_PREPEND_RAN', 1);
+PHP
+
+## Stand-in for the OLD mechanism (scripts/cac-lsphp-normalize.php).
+cat > "$TMP/old-normalize.php" <<'PHP'
+<?php
+foreach (array('DOCUMENT_ROOT', 'SCRIPT_FILENAME') as $k) {
+    if (!empty($_SERVER[$k]) && strncmp($_SERVER[$k], '/mnt/users/', 11) === 0) {
+        $r = realpath($_SERVER[$k]);
+        if ($r !== false) { $_SERVER[$k] = $r; }
+    }
+}
+PHP
+
+{
+	echo "[global]"
+	echo "error_log = $TMP/fpm-error.log"
+	echo "daemonize = no"
+	echo "[www]"
+	echo "listen = 127.0.0.1:$PORT"
+	echo "pm = static"
+	echo "pm.max_children = 2"
+	## Only when we are root: php-fpm hard-errors on a root pool, and warns
+	## (harmlessly, but noisily) if a non-root master names a user at all.
+	if [ -n "$POOL_USER" ]; then
+		echo "user = $POOL_USER"
+		echo "group = $POOL_GROUP"
+	fi
+} > "$TMP/fpm.conf"
+
+## Returns non-zero when php-fpm never answered. Callers MUST distinguish that
+## from an assertion failure — an unstarted php-fpm makes every expect() below
+## fail with an empty `got:`, which looks like nine parity bugs.
+run_case() {
+	: > "$TMP/fpm.out"
+	"$FPM_BIN" -n -y "$TMP/fpm.conf" -F -d user_ini.cache_ttl=0 "$@" \
+		>"$TMP/fpm.out" 2>&1 &
+	local pid=$! out=""
+	for _ in $(seq 1 40); do
+		sleep 0.15
+		## SC1007: `QUERY_STRING=` IS the intent — an empty FastCGI param in the
+		## per-command environment prefix, exactly as a webserver sends it for a
+		## URL with no query string. Not a truncated assignment.
+		# shellcheck disable=SC1007
+		out=$(SCRIPT_FILENAME="$DOCROOT/probe.php" DOCUMENT_ROOT="$DOCROOT" \
+			SCRIPT_NAME=/probe.php REQUEST_METHOD=GET QUERY_STRING= \
+			cgi-fcgi -bind -connect "127.0.0.1:$PORT" 2>/dev/null)
+		[ -n "$out" ] && break
+		## Master already gone => it will never answer; stop waiting 6s for it.
+		kill -0 "$pid" 2>/dev/null || break
+	done
+	kill "$pid" 2>/dev/null; wait "$pid" 2>/dev/null
+	printf '%s' "$out"
+	[ -n "$out" ]
+}
+
+die_startup() {
+	echo
+	echo "HARNESS FAILURE: php-fpm never answered for case '$1'." >&2
+	echo "  This is a STARTUP/environment failure, NOT a parity assertion failure." >&2
+	echo "  php-fpm: $FPM_BIN" >&2
+	echo "  pool user/group: ${POOL_USER:-<none, master is not root>}/${POOL_GROUP:-}" >&2
+	echo "  --- php-fpm output ---" >&2
+	sed 's/^/  /' "$TMP/fpm.out" >&2
+	echo "  --- pool error_log ---" >&2
+	[ -s "$TMP/fpm-error.log" ] && sed 's/^/  /' "$TMP/fpm-error.log" >&2
+	echo "  ----------------------" >&2
+	exit 2
+}
+
+expect() {
+	local label="$1" got="$2" want="$3"
+	if [ "$got" = "$want" ]; then
+		echo "  PASS  $label"
+	else
+		echo "  FAIL  $label"
+		echo "        want: $want"
+		echo "        got:  $got"
+		fail=1
+	fi
+}
+field() { printf '%s' "$1" | sed -n "s/^$2=//p"; }
+
+EXT=( -d "extension=$EXT_SO" )
+MAP=( -d "cac_path_parity.from=$SITE" -d "cac_path_parity.to=$HOME_PATH" )
+USERINI_LINE="auto_prepend_file = $SITE/customer-waf.php"
+
+echo "== 1. CONTROL: extension loaded, no mapping (reproduces the bug) =="
+rm -f "$DOCROOT/.user.ini"
+out=$(run_case "${EXT[@]}") || die_startup "1. CONTROL"
+expect "DOCUMENT_ROOT is the raw OLS path"   "$(field "$out" DOCUMENT_ROOT)"   "$DOCROOT"
+expect "SCRIPT_FILENAME is the raw OLS path" "$(field "$out" SCRIPT_FILENAME)" "$DOCROOT/probe.php"
+
+echo "== 2. FIX: mapping configured =="
+out=$(run_case "${EXT[@]}" "${MAP[@]}") || die_startup "2. FIX"
+expect "DOCUMENT_ROOT == cac-fpm value"   "$(field "$out" DOCUMENT_ROOT)"   "$HOME_PATH/public_html"
+expect "SCRIPT_FILENAME == cac-fpm value" "$(field "$out" SCRIPT_FILENAME)" "$HOME_PATH/public_html/probe.php"
+
+echo "== 3. WORDFENCE: customer .user.ini auto_prepend_file present =="
+printf '%s\n' "$USERINI_LINE" > "$DOCROOT/.user.ini"
+out=$(run_case "${EXT[@]}" "${MAP[@]}") || die_startup "3. WORDFENCE"
+expect "DOCUMENT_ROOT still corrected"      "$(field "$out" DOCUMENT_ROOT)"   "$HOME_PATH/public_html"
+expect "SCRIPT_FILENAME still corrected"      "$(field "$out" SCRIPT_FILENAME)" "$HOME_PATH/public_html/probe.php"
+expect "customer auto_prepend_file still ran" "$(field "$out" PREPEND_RAN)"     "yes"
+
+echo "== 4. OLD MECHANISM (why the prepend hook could not be hardened) =="
+out=$(run_case -d "auto_prepend_file=$TMP/old-normalize.php") || die_startup "4. OLD MECHANISM"
+expect "auto_prepend normaliser is displaced by the customer's .user.ini" \
+	"$(field "$out" DOCUMENT_ROOT)" "$DOCROOT"
+expect "customer's prepend is the one that ran" "$(field "$out" PREPEND_RAN)" "yes"
+
+rm -f "$DOCROOT/.user.ini"
+if [ "$fail" -eq 0 ]; then echo "ALL PASS"; else echo "FAILURES"; fi
+exit "$fail"
@@ -1,6 +1,16 @@
 <?php
 /**
- * cac-lsphp $_SERVER path normaliser (auto_prepend).
+ * cac-lsphp $_SERVER path normaliser (auto_prepend) — DEGRADED FALLBACK ONLY.
+ *
+ * SUPERSEDED by the cac_path_parity PHP extension (ext/cac-path-parity/), which
+ * does this from RINIT where a customer's .user.ini cannot displace it. The
+ * entrypoint only wires this file up when that extension is not loadable in the
+ * running image, and logs a WARNING when it does. Do not extend this script —
+ * fix the extension instead.
+ *
+ * It is kept because the flaw documented at the bottom of this docblock is
+ * exactly why the extension exists, and because an image where the extension
+ * failed to load should degrade to the old behaviour rather than to nothing.
 *
 * The shared-ols container serves from its bulk /docker/users->/mnt/users mount,
 * so OLS sends lsphp $_SERVER['DOCUMENT_ROOT'] / ['SCRIPT_FILENAME'] under
@@ -67,7 +67,46 @@ fi
 ## see lsphp's PHP errors in the exact same file on the new image.
 ## Rendered as a tiny ini in lsphp's scan dir; PHP merges it after the
 ## production-tuning overrides at startup.
-SCAN_DIR=$(/usr/local/lsws/lsphp${PHPVER}/bin/lsphp -i 2>/dev/null | awk -F'=> ' '/^Scan this dir/ {print $2; exit}')
+## Captured, then matched in the shell. As a single pipeline this was
+## `lsphp -i | awk '…{print;exit}'`: awk stops at the "Scan this dir" line,
+## which is near the top of the output, so lsphp can still be writing when awk
+## closes the pipe. lsphp then dies 141, `set -o pipefail` (line 12) makes that
+## the pipeline's status, and because this is a BARE ASSIGNMENT `set -e` KILLS
+## PID 1 — the container never starts. (Its twin in entrypoint-lsphp.sh chose a
+## degraded fallback instead; this one just exits.) That is a race on whether
+## the reader closes before the writer's last write() returns, not a function of
+## how big the output is: see the long note over the probe helpers in
+## entrypoint-lsphp.sh for the measurements. The rule is simply that no
+## `writer | early-exiting-reader` belongs in a pipefail script.
+##
+## A here-string would remove the pipeline, but bash spills a here-string to
+## /tmp/sh-thd.XXXXXX above a build-dependent size (65536 for the bash 5.2.21 in
+## this image, between 4096 and 16384 for Debian's 5.2.15) — and on this line,
+## a bare assignment, a temp file it cannot create is again `set -e` killing
+## PID 1: `docker run --read-only` reproduces exactly that. So the extraction is
+## done with parameter expansion, which allocates nothing.
+##
+## Same answer as the awk it replaces: first line starting "Scan this dir", then
+## the text between the FIRST and SECOND '=> ' on it (awk's $2 under -F'=> '),
+## empty if the line carries no separator, empty if there is no such line.
+## `|| true` on the capture keeps a genuinely failing lsphp as an empty
+## SCAN_DIR — which the `-n` test below already handles — not a boot failure.
+LSPHP_INFO=$(/usr/local/lsws/lsphp"${PHPVER}"/bin/lsphp -i 2>/dev/null || true)
+SCAN_DIR=""
+## The leading newline is what makes a match on LINE 1 behave like every other
+## line, exactly as awk's `^` anchor does.
+scan_rest=$'\n'"$LSPHP_INFO"
+if [[ $scan_rest == *$'\nScan this dir'* ]]; then
+  ## `#` takes the SHORTEST prefix, i.e. the FIRST matching line — awk's `exit`.
+  scan_rest=${scan_rest#*$'\nScan this dir'}
+  scan_line="Scan this dir${scan_rest%%$'\n'*}"
+  if [[ $scan_line == *'=> '* ]]; then
+    SCAN_DIR=${scan_line#*'=> '}
+    SCAN_DIR=${SCAN_DIR%%'=> '*}
+  fi
+  unset scan_line
+fi
+unset scan_rest
 if [ -n "$SCAN_DIR" ]; then
  cat > "$SCAN_DIR/99-user-error-log.ini" <<EOF
 ; rendered at container start by entrypoint-litespeed.sh
@@ -194,7 +233,34 @@ trap term_handler TERM INT
 ## down). We match the running message specifically — a bare grep for "running"
 ## would also match "not running". (This image keeps the pidfile under
 ## /tmp/lshttpd, not logs/, so we never hard-code a pidfile path.)
-ols_running() { /usr/local/lsws/bin/lswsctrl status 2>/dev/null | grep -qi 'running with pid'; }
+##
+## Read into a variable and match with a here-string rather than piping into
+## `grep -qi`: `grep -q` closes the pipe on its first match, and under the
+## `set -o pipefail` at the top of this file a writer that is still writing when
+## that happens dies 141 and the pipeline reports FALSE — i.e. "OLS is down"
+## precisely because the "running" line matched, which here means a spurious
+## relaunch of a healthy OLS, five of which trip the crash-loop cap and exit
+## PID 1. (Same defect that shipped in entrypoint-lsphp.sh's cac_path_parity
+## probe.) The reason to change it is STRUCTURAL — a pipefail script must not
+## pipe into an early-exit reader, whatever the payload — because "lswsctrl
+## prints one short line so it always wins" is a size argument, and size
+## arguments about this race are wrong: see the measurements over the probe
+## helpers in entrypoint-lsphp.sh, where 41 KB SIGPIPEd 11% of the time into a
+## 64 KB pipe. A non-zero `lswsctrl` still means "not running", exactly as
+## pipefail made it mean before.
+##
+## A here-string is the right shape HERE, where those helpers use `[[ ]]`: the
+## reason to avoid `<<<` there is that bash spills a large here-string to
+## /tmp/sh-thd.XXXXXX and so makes a writable temp dir a boot precondition. The
+## threshold is 65536 bytes in this image's bash 5.2.21 and no lower than 4096
+## in any bash this repo has met; `lswsctrl status` prints well under 100 bytes
+## and cannot approach it, so no temp file is ever created and the case-
+## insensitive match stays a plain `grep -i` instead of a hand-rolled glob.
+ols_running() {
+  local st
+  st=$(/usr/local/lsws/bin/lswsctrl status 2>/dev/null) || return 1
+  grep -qi 'running with pid' <<<"$st"
+}

 ## Crash-loop cap: if OLS can't stay up, bail out so Docker's restart policy and
 ## the site-health monitor escalate instead of us hot-looping forever.
@@ -22,6 +22,14 @@
 ## /home/$user/public_html files. PHP canonicalises the symlink, so
 ## __FILE__/__DIR__/realpath all report /home/$user/public_html (verified
 ## 2026-06-10) — the customer never sees the /mnt/users path.
+##
+## THE $_SERVER STRINGS: the symlink makes paths RESOLVE, but the raw strings OLS
+## put in $_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] still read /mnt/users.
+## The cac_path_parity extension (baked into the image, configured per-site
+## below) rewrites those two at request start, so a site moved from cac-fpm to
+## cac-lsphp sees byte-identical values. It replaced an auto_prepend_file
+## normaliser that any site's own .user.ini silently displaced — see
+## ext/cac-path-parity/cac_path_parity.c.

 set -euo pipefail

@@ -60,8 +68,33 @@ SAFE_DOMAIN="$domain"
 case "$domain" in
  \*.*) SAFE_DOMAIN="wildcard.${domain#\*.}" ;;
 esac
+
+## Both of these get interpolated into generated php.ini fragments below. They
+## are panel-validated and both already feed `ln -sfn` and the shared-ols vhost
+## config, so a hostile value is not reachable today — this is the belt to that
+## brace. A newline in $domain is an INI-DIRECTIVE INJECTION into the generated
+## fragment (measured against the pre-fix script: domain=$'evil.com\nprecision =
+## 7\n; ' put that directive in 99-cac-path-parity.ini and lsphp reported
+## `precision => 7`); `$(...)` yields an ini parse error and `"` an empty value,
+## and BOTH of those leave the
+## path-parity extension INERT — the exact silent parity loss this whole change
+## exists to eliminate. Quoting the emitted values (done below) neutralises
+## newlines and quotes; it does NOT neutralise php.ini's own `${VAR}`
+## interpolation, which is why the character class is checked as well.
+INI_TOKENS_OK=yes
+case "$user" in ''|*[!A-Za-z0-9._-]*) INI_TOKENS_OK=no ;; esac
+case "$SAFE_DOMAIN" in ''|*[!A-Za-z0-9._-]*) INI_TOKENS_OK=no ;; esac
+if [ "$INI_TOKENS_OK" != yes ]; then
+  echo "WARNING: entrypoint-lsphp: user/domain contain characters outside [A-Za-z0-9._-] — refusing to generate php.ini fragments from them, so the \$_SERVER path-parity mapping and the per-site error_log are BOTH skipped (the extension stays inert, log_errors stays On from the image defaults and PHP logs to stderr i.e. \`docker logs\`; requests are unaffected). user=$(printf '%q' "$user") domain=$(printf '%q' "$domain")" >&2
+fi
+
+## The exact path prefix the shared-ols container serves this site from — the
+## string OLS puts in SCRIPT_FILENAME/DOCUMENT_ROOT. Used twice: for the symlink
+## that makes it RESOLVE, and for the cac_path_parity mapping that makes it READ
+## like cac-fpm. Deriving both from one variable keeps them in lockstep.
+OLS_SITE_PATH="/mnt/users/$user/$SAFE_DOMAIN"
 mkdir -p "/mnt/users/$user"
-ln -sfn "/home/$user" "/mnt/users/$user/$SAFE_DOMAIN"
+ln -sfn "/home/$user" "$OLS_SITE_PATH"

 ## ---- detached-lsphp pool sizing ----
 # shellcheck source=/dev/null
@@ -76,6 +109,32 @@ export PHP_LSAPI_MAX_REQUESTS="${PHP_LSAPI_MAX_REQUESTS:-500}"
 export LSAPI_MAX_IDLE="${LSAPI_MAX_IDLE:-30}"
 export LSAPI_EXTRA_CHILDREN="${LSAPI_EXTRA_CHILDREN:-5}"
 export LSAPI_AVOID_FORK="${LSAPI_AVOID_FORK:-0}"
+## LSAPI_KEEP_LISTEN=2 works around a leak in lsphp's own bookkeeping — not a
+## setting we're tuning for taste. The master keeps a `busy` worker counter in
+## a MAP_SHARED page it shares with its children; measured live on whp01,
+## that counter drifts NEGATIVE over days of uptime (arclightcourt.com-01 was
+## at busy=-8 after 6.9 days; a healthy sibling sat at 0..9). php-src
+## sapi/litespeed/lsapilib.c computes each child's idle-exit grace period as
+## `10 + busy*10` seconds (capped by LSAPI_MAX_IDLE) INSIDE
+## `if (s_keep_listener == 1)` — with busy=-8 that's `wait_time = -70`, so
+## workers exit after ~1s idle instead of 10-30s. No worker then lingers in
+## accept(), so the master's "an idle worker is already accepting, don't
+## fork" guard never fires and it forks for every single connection —
+## observed slamming the hard child ceiling under bot traffic
+## (`Reached max children process limit`) and, on rejection, leaving the
+## pending connection to rot in the kernel backlog as a 503. Confirmed
+## asymmetry: the affected site logged 306 OLS-side `ExtConn timed out` /
+## deadlock / `oops! 503` errors where an identically-configured healthy
+## sibling logged 0. Restarting the container resets the counter to 0 (it's
+## initialised at master start) but it drifts negative again over about a
+## week — a reset, not a cure. LSAPI_KEEP_LISTEN=2 skips the `== 1` branch
+## entirely, so idle-exit timing is never derived from the leaked counter and
+## instead falls straight back to LSAPI_MAX_IDLE above. The is_enough_free_mem()
+## memory guard sits immediately above that branch in lsapilib.c and is NOT
+## part of it, so it still applies at =2 — this does not trade away the
+## memory-pressure protection LSAPI_MAX_IDLE exists for. Still overridable
+## (e.g. back to 1) per-container as an escape hatch.
+export LSAPI_KEEP_LISTEN="${LSAPI_KEEP_LISTEN:-2}"
 LSPHP_BIND="${LSPHP_BIND:-0.0.0.0:9000}"

 ## ---- .user.ini support ----
@@ -97,40 +156,331 @@ LSPHP_BIND="${LSPHP_BIND:-0.0.0.0:9000}"
 ## .user.ini has not been remediated yet.
 export LSPHP_ENABLE_USER_INI="${LSPHP_ENABLE_USER_INI:-on}"

-echo "Container memory: ${CONTAINER_MEMORY_MB}MB | PHP_LSAPI_CHILDREN=${PHP_LSAPI_CHILDREN} | LSAPI_MAX_IDLE=${LSAPI_MAX_IDLE} | PHPVER=${PHPVER} | bind=${LSPHP_BIND} | user_ini=${LSPHP_ENABLE_USER_INI}"
+echo "Container memory: ${CONTAINER_MEMORY_MB}MB | PHP_LSAPI_CHILDREN=${PHP_LSAPI_CHILDREN} | LSAPI_MAX_IDLE=${LSAPI_MAX_IDLE} | LSAPI_KEEP_LISTEN=${LSAPI_KEEP_LISTEN} | PHPVER=${PHPVER} | bind=${LSPHP_BIND} | user_ini=${LSPHP_ENABLE_USER_INI}"
+
+## Validate a numeric value destined for a generated php.ini fragment.
+## Sets INI_NUM to the value when it is acceptable, and to "" (plus a WARNING)
+## when it is not. Never fatal: a rejected override just leaves the image
+## default in place, and the site serves either way.
+##
+## Digits-only is what closes the injection: no newline, quote, `$` or `{` can
+## survive it, so neither an ini-directive injection nor php.ini's `${VAR}`
+## interpolation is reachable regardless of what the caller sent.
+##
+## The range bound is a separate, weaker concern: it is a sanity check, NOT a
+## guarantee that the value works. Measured — with `99-prod-overrides.ini`
+## setting `opcache.interned_strings_buffer = 16`, a memory_consumption of 8 or
+## 16 is ACCEPTED here and still aborts opcache at startup ("Insufficient shared
+## memory for interned strings buffer"), loading no opcache at all. The floor is
+## not raised to cover that because doing so would forfeit the superset property
+## below; the panel clamps at 32, well clear of it.
+validate_ini_num() {
+  local name="$1" val="$2" min="$3" max="$4"
+  INI_NUM=""
+  case "$val" in
+    ''|*[!0-9]*) ;;
+    *)
+      ## Length-cap first: `[ -lt ]` on a 25-digit string is an arithmetic
+      ## error, not a comparison. 7 digits covers every max below.
+      if [ "${#val}" -le 7 ] && [ "$val" -ge "$min" ] && [ "$val" -le "$max" ]; then
+        INI_NUM="$val"
+        return 0
+      fi
+      ;;
+  esac
+  echo "WARNING: entrypoint-lsphp: ${name}=$(printf '%q' "$val") is not a plain integer in ${min}-${max} — ignoring it; the image default from 99-prod-overrides.ini applies." >&2
+  return 0
+}

 ## ---- per-site ini drop-ins (identical mechanism to entrypoint-litespeed.sh) ----
 ## error_log → the same customer-visible path cac:phpNN / cac-litespeed use, so
 ## "where's my PHP error log?" is answered identically across all site types.
-SCAN_DIR=$("$LSPHP_BIN" -i 2>/dev/null | awk -F'=> ' '/^Scan this dir/ {print $2; exit}')
+## Capture lsphp's own info once and read both answers out of it. Probe with
+## `-i` ONLY: lsphp is the LSAPI SAPI, not the CLI — it accepts just
+## -[b|c|n|h|i|q|s|v|?] and answers `-m`/`-r` by printing usage and exiting 0, so
+## a `lsphp -m | grep` test never matches and never errors either.
+##
+## ---- CAC-TEST: probe helpers BEGIN ----
+## Everything between these two markers is extracted verbatim and executed by
+## scripts/tests/lsphp-info-probe.test.sh — the markers are inert comments with
+## no runtime effect, and they exist so the test exercises THE SHIPPED CODE
+## rather than a copy of it that can drift away from it. Keep BOTH markers: the
+## extractor refuses to emit anything unless it sees the END one, so a half-
+## deleted pair is reported there as a marker error instead of silently
+## sourcing the rest of this file.
+##
+## WHY THESE MATCH `$1` IN THE SHELL AND NEVER PIPE IT INTO A READER.
+##
+## What broke. Both probes used to be `printf '%s\n' "$LSPHP_INFO" | <reader>`,
+## and both readers stop early — `grep -q` at its first match, `awk` at `exit`.
+## When the reader closes the pipe with the writer still writing, the writer
+## takes SIGPIPE and dies 141; `set -o pipefail` (line 34) adopts 141 as the
+## PIPELINE's status; and the branch reads FALSE **because the thing it was
+## looking for was present early enough to stop the reader**. Measured on whp02
+## against the published cac-lsphp:php83: 5/5 runs status=141 with pipefail,
+## 0 without.
+##
+## THE RULE, and it is not about size. ANY `writer | early-exiting-reader`
+## under pipefail is a latent 141. PAYLOAD SIZE IS NOT A SAFETY ARGUMENT. Each
+## run is decided by a race — whether the reader's close lands before the
+## writer's final write() returns — and the payload only sets how many write()
+## syscalls the writer has to lose. Measured here against a default
+## 65536-byte pipe (confirmed with F_GETPIPE_SZ):
+##     41144 bytes -> 141 in  32/300 runs (11%) — well UNDER capacity
+##     65012 bytes -> 141 in  25/30  runs       — not 100% even AT capacity
+##     500 KB into a 1 MiB pipe -> 200/200 SIGPIPE written 4096 bytes at a
+##                                 time, 0/200 written as one 500 KB write
+## and strace caught printf dying having written 12086 of 40406 bytes into a
+## 65536-byte pipe, i.e. losing with 53 KB of room to spare. The reason the same
+## image failed 5/5 on whp02 and 10/10 clean in a dev container is the WRITER's
+## syscall size: bash <= 5.2.15 pushes ~37 KB per write, bash >= 5.2.21 pushes
+## 80-160 bytes, so the newer shell needs hundreds of chances to lose the race
+## and the older one needs a couple. (An earlier draft of this comment blamed
+## pipe capacity and fs.pipe-user-pages-soft. Both were wrong: that soft limit
+## clamps new pipes to two pages rather than one, applies only once a single uid
+## holds more than 1024 pipes, and is skipped entirely for CAP_SYS_RESOURCE.)
+##
+## The only SOUND reasons a call site is safe are structural:
+##   * the file does not set pipefail; or
+##   * the reader provably consumes to EOF (no `q`, `-q`, `-l`, `-m`, `exit`,
+##     `break`); or
+##   * the pipeline's status is discarded.
+## The reader's implementation is not a defence either: at 248 KB, mawk, gawk,
+## `grep -q` and `head -1` each returned 141 on 10/10, and these images have
+## already drifted between mawk 1.3.4 (cac-lsphp) and gawk 5.2.1
+## (cac-litespeed:php83) — not a property this repo controls.
+##
+## WHY PURE-BASH MATCHING RATHER THAN A HERE-STRING. `<<<` does remove the
+## pipeline, but it is not free: above a build-dependent size bash materialises
+## the string as /tmp/sh-thd.XXXXXX, so it makes a writable temp dir a
+## PRECONDITION OF BOOTING. Measured in this image (bash 5.2.21) the switch is
+## at exactly 65536 bytes and `lsphp -i` is 39934, so the here-string form was
+## not hitting disk here — but Debian's bash 5.2.15 switches somewhere between
+## 4096 and 16384, where the same payload would. What that costs is not
+## theoretical:
+##     docker run --read-only ... 'SCAN_DIR=$(awk ... <<<"$BIG")'
+##       -> bash: cannot create temp file for here-document: Read-only file
+##          system   ... and the script is dead: exit 1, PID 1 gone.
+## which is the exact boot failure this branch exists to remove, re-acquired
+## from a different direction and gated on which bash the base image ships.
+## `[[ ]]` and `${...}` allocate nothing and cannot fail that way. Where the
+## subject is a couple of hundred bytes and provably cannot approach the
+## threshold, a here-string is still fine — see `ols_running` in
+## entrypoint-litespeed.sh, which says so at the call site.
+##
+## THE PATTERNS ARE THE OLD ONES RE-EXPRESSED, NOT APPROXIMATED.
+##   grep -q '^cac_path_parity support => enabled$'  — an anchored whole-line
+##     match, so the subject is wrapped in a newline at BOTH ends and the glob
+##     matches \n<line>\n; the wrapping is what keeps the first line and an
+##     unterminated last line matching exactly as grep matched them.
+##   grep -q '^PHP Version => '                      — anchored at the start
+##     only, so only a leading newline is added.
+##   awk -F'=> ' '/^Scan this dir/ {print $2; exit}' — first matching line,
+##     then the text between the FIRST and SECOND '=> ' on it ($2), or empty if
+##     there is no separator. `${x#*'=> '}` then `${y%%'=> '*}` is that, exactly.
+## scripts/tests/lsphp-info-probe.test.sh asserts this equivalence against the
+## grep/awk originals over the edge cases (match on the first line, on the last
+## line with no trailing newline, decoy substrings, a second separator, an empty
+## value, a missing key), so "same answer as before" is checked, not asserted.
+##
+## Statuses are unchanged: a genuinely-absent extension is still a clean 1, and
+## a genuinely-missing "Scan this dir" line is still empty output with status 0.
+lsphp_info_has_parity_ext() {
+  [[ $'\n'"$1"$'\n' == *$'\ncac_path_parity support => enabled\n'* ]]
+}
+lsphp_info_scan_dir() {
+  local rest line val
+  rest=$'\n'"$1"
+  [[ $rest == *$'\nScan this dir'* ]] || return 0
+  ## `#` takes the SHORTEST prefix, i.e. the FIRST matching line — awk's `exit`.
+  rest=${rest#*$'\nScan this dir'}
+  line="Scan this dir${rest%%$'\n'*}"
+  val=""
+  if [[ $line == *'=> '* ]]; then
+    val=${line#*'=> '}
+    val=${val%%'=> '*}
+  fi
+  printf '%s\n' "$val"
+}
+## Did `lsphp -i` answer at all? Separates "the extension is not there" from
+## "our probe produced nothing to look in", so neither gets reported as the
+## other. Keyed on the phpinfo banner, which is line 2 of every `lsphp -i`
+## (verified against lsphp83 8.3.32) and is not something LSPHP_INFO could
+## contain from any other source.
+lsphp_info_is_usable() {
+  [[ $'\n'"$1" == *$'\nPHP Version => '* ]]
+}
+## ---- CAC-TEST: probe helpers END ----
+
+PATH_PARITY_MODE="none"
+LSPHP_INFO=$("$LSPHP_BIN" -i 2>/dev/null || true)
+SCAN_DIR=$(lsphp_info_scan_dir "$LSPHP_INFO")
+## `|| true` above is what keeps a broken probe survivable: fail-open is
+## deliberate here and below — the site serves either way, only the $_SERVER
+## strings differ. What the failure gets REPORTED as is handled at each of the
+## two places it changes the outcome (the parity branch, and the no-scan-dir
+## else at the bottom of this block).
 if [ -n "$SCAN_DIR" ]; then
  mkdir -p "$SCAN_DIR"
-  cat > "$SCAN_DIR/99-user-error-log.ini" <<EOF
-; rendered at container start by entrypoint-lsphp.sh
-error_log = /home/${user}/logs/php-fpm/error.log
-log_errors = On
-EOF
-  ## Normalise \$_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] from the OLS-sent
-  ## /mnt/users path back to /home/<user> so cac-lsphp is byte-for-byte 1:1 with
-  ## cac-fpm. Customer sites have no auto_prepend by default, so this is safe; a
-  ## site that sets its own .user.ini auto_prepend overrides it (paths still
-  ## resolve via the symlink either way).
+  ## Values emitted double-quoted via printf rather than interpolated into an
+  ## unquoted heredoc — see the INI_TOKENS_OK note above for what that prevents.
+  ##
+  ## Gated on INI_TOKENS_OK for the same reason the mapping below is: this
+  ## fragment interpolates $user into generated ini too. Leaving it ungated was
+  ## an INCONSISTENCY, not a live hole — a newline is inert inside the quotes,
+  ## and a `${`-bearing $user cannot exist because the useradd above would have
+  ## failed under `set -euo pipefail`. But "this particular unvetted value
+  ## happens to be contained" is the reasoning this branch already rejected one
+  ## screenful up, so it is not the reasoning that guards this line either.
+  ##
+  ## Rejecting costs such a user nothing it needs: `log_errors = On` is already
+  ## baked in by 99-prod-overrides.ini, so PHP still logs — to stderr, i.e.
+  ## `docker logs`, which is MORE visible than a per-site file, not less. No
+  ## legitimate user reaches this branch (verified fleet-wide: 30 shared_ols
+  ## sites across 4 hosts, none rejected by the charset check).
+  if [ "$INI_TOKENS_OK" = yes ]; then
+    {
+      echo '; rendered at container start by entrypoint-lsphp.sh'
+      printf 'error_log = "%s"\n' "/home/$user/logs/php-fpm/error.log"
+      echo 'log_errors = On'
+    } > "$SCAN_DIR/99-user-error-log.ini"
+  else
+    ## The container filesystem survives `docker restart`, so a fragment an
+    ## earlier boot wrote from a different env must not outlive the rejection.
+    rm -f "$SCAN_DIR/99-user-error-log.ini"
+  fi
+  ## ---- $_SERVER path parity with cac-fpm ----
+  ## Point the cac_path_parity extension at THIS site's mapping. Same two
+  ## values the compatibility symlink above is built from, so the rewrite and
+  ## the symlink can never disagree.
+  ##
+  ## Both settings are PHP_INI_SYSTEM: a customer's .user.ini (PHP_INI_PERDIR /
+  ## PHP_INI_USER only) cannot redirect or disable them, and the extension
+  ## occupies no userland hook — so the customer's own auto_prepend_file (the
+  ## Wordfence WAF on several live sites) keeps working untouched. That
+  ## combination is why this is an extension: the previous auto_prepend_file
+  ## normaliser was itself PHP_INI_PERDIR and any site with its own prepend
+  ## silently displaced it, while making OUR prepend win would have disabled
+  ## THEIRS. See ext/cac-path-parity/cac_path_parity.c.
+  if [ "$INI_TOKENS_OK" != yes ]; then
+    ## Already warned above. Write NOTHING: neither the mapping (we will not
+    ## generate ini from an unvetted string) nor the auto_prepend fallback (which
+    ## would not be correct for such a site either). The extension stays inert,
+    ## the request path is unaffected.
+    rm -f "$SCAN_DIR/99-cac-path-parity.ini" "$SCAN_DIR/99-cac-lsphp-normalize.ini"
+    PATH_PARITY_MODE="none (user/domain rejected)"
+  elif lsphp_info_has_parity_ext "$LSPHP_INFO"; then
+    {
+      echo '; rendered at container start by entrypoint-lsphp.sh'
+      printf 'cac_path_parity.from = "%s"\n' "$OLS_SITE_PATH"
+      printf 'cac_path_parity.to = "%s"\n'   "/home/$user"
+    } > "$SCAN_DIR/99-cac-path-parity.ini"
+    ## Drop the pre-extension fallback if an older image left one here — the
+    ## container filesystem survives a "docker restart", so an in-place upgrade
+    ## must not keep a stale auto_prepend pointing at the old normaliser.
+    rm -f "$SCAN_DIR/99-cac-lsphp-normalize.ini"
+    PATH_PARITY_MODE="extension"
+  else
+    ## Degraded fallback for an image built before the extension existed (or one
+    ## where it failed to load). Restores the old, .user.ini-defeatable
+    ## behaviour rather than losing normalisation entirely — but say so loudly,
+    ## because in this mode parity is NOT guaranteed.
+    ##
+    ## FAIL-OPEN, DELIBERATELY: a probe that cannot answer must never stop the
+    ## container. The site serves either way; only the $_SERVER strings differ.
    cat > "$SCAN_DIR/99-cac-lsphp-normalize.ini" <<'EOF'
-; rendered at container start by entrypoint-lsphp.sh
+; rendered at container start by entrypoint-lsphp.sh (DEGRADED FALLBACK)
 auto_prepend_file = /scripts/cac-lsphp-normalize.php
 EOF
+    ## ...but do not DIAGNOSE more than was established. The old wording said
+    ## "extension not loadable in this image" for EVERY reason this branch is
+    ## reached — including the probe breaking on its own, which is exactly what
+    ## happened (see the SIGPIPE note on the helpers above): a false verdict
+    ## that sent operators to rebuild an image whose extension was fine and
+    ## whose build gate had passed. The claim now carries its evidence, and the
+    ## evidence is real: reaching here at all means SCAN_DIR was parsed out of
+    ## this same output, so `lsphp -i` did answer and its module list is
+    ## authoritative. The case where it did NOT answer never gets here — it is
+    ## caught and reported honestly at the `lsphp_info_is_usable` check above.
+    PATH_PARITY_MODE="auto_prepend (DEGRADED)"
+    echo "WARNING: entrypoint-lsphp: cac_path_parity extension not loadable in this image — '${LSPHP_BIN} -i' answered (${#LSPHP_INFO} bytes, scan dir ${SCAN_DIR}) and does not list it — falling back to the auto_prepend normaliser, which a site's own .user.ini auto_prepend_file will silently displace. Rebuild/repull cac-lsphp:php${PHPVER}." >&2
+  fi
  ## Per-site opcache override (panel: Advanced Tuning → OpCache size); falls
  ## back to the baked lsphp-overrides.ini defaults when unset.
-  if [ -n "${OPCACHE_MEMORY_MB:-}" ] || [ -n "${OPCACHE_MAX_FILES:-}" ]; then
+  ##
+  ## SAME INJECTION CLASS AS THE MAPPING ABOVE, and it was left open when that
+  ## one was closed. These two lines interpolated the raw env into an UNQUOTED
+  ## `echo`, so (measured against the pre-fix script on this branch's image)
+  ## OPCACHE_MEMORY_MB=$'128\nprecision = 7\n; ' put `precision = 7` into
+  ## 99-user-opcache.ini and lsphp duly reported `precision => 7`.
+  ##
+  ## WHP does cast (int) and clamp these before setting the env
+  ## (web-files/libs/site-pool-env.php: 32-512 MB, 2000-32000 files) — but
+  ## "the panel validates it" is exactly the argument this branch rejected for
+  ## `domain`, and the panel is a different repo on a different release cadence.
+  ## Validate at the point of use, where the ini is actually generated.
+  ##
+  ## The accepted ranges below are deliberately a strict SUPERSET of the panel's
+  ## clamps (32-512 and 2000-32000), so widening a panel clamp later can never
+  ## start silently rejecting real sites here.
+  ##
+  ## Provenance, stated honestly: max_accelerated_files [200, 1000000] IS PHP's
+  ## own clamp. For memory_consumption, 8 is PHP's documented floor but 4096 is
+  ## OURS — PHP imposes no upper bound on that directive. It is a typo guard, not
+  ## a vendor limit. An out-of-range value is not merely ignored: PHP resets the
+  ## directive to its COMPILED default, discarding the image's own
+  ## `99-prod-overrides` value, which is a further reason to reject rather than
+  ## pass such a value through.
+  OPCACHE_LINES=()
+  if [ -n "${OPCACHE_MEMORY_MB:-}" ]; then
+    validate_ini_num OPCACHE_MEMORY_MB "$OPCACHE_MEMORY_MB" 8 4096
+    if [ -n "$INI_NUM" ]; then
+      OPCACHE_LINES+=("$(printf 'opcache.memory_consumption = "%s"' "$INI_NUM")")
+    fi
+  fi
+  if [ -n "${OPCACHE_MAX_FILES:-}" ]; then
+    validate_ini_num OPCACHE_MAX_FILES "$OPCACHE_MAX_FILES" 200 1000000
+    if [ -n "$INI_NUM" ]; then
+      OPCACHE_LINES+=("$(printf 'opcache.max_accelerated_files = "%s"' "$INI_NUM")")
+    fi
+  fi
+  if [ "${#OPCACHE_LINES[@]}" -gt 0 ]; then
    {
      echo "; rendered at container start by entrypoint-lsphp.sh"
      echo "; per-site override from WHP whp.sites.opcache_*_override"
-      [ -n "${OPCACHE_MEMORY_MB:-}" ] && echo "opcache.memory_consumption = ${OPCACHE_MEMORY_MB}"
-      [ -n "${OPCACHE_MAX_FILES:-}" ]  && echo "opcache.max_accelerated_files = ${OPCACHE_MAX_FILES}"
+      printf '%s\n' "${OPCACHE_LINES[@]}"
    } > "$SCAN_DIR/99-user-opcache.ini"
+  else
+    ## Nothing valid to say. Remove rather than leave whatever a previous boot
+    ## wrote. Defensive only — do not read this as fixing a reachable bug: the
+    ## writable layer does outlive a `docker restart`, but so does the
+    ## environment, and changing these vars requires a RECREATE, which starts
+    ## from a fresh layer with no stale fragment. Kept because it is free, and
+    ## because it makes "no valid override" mean the same thing on every boot
+    ## regardless of how the container got here.
+    rm -f "$SCAN_DIR/99-user-opcache.ini"
+  fi
+else
+  ## No scan dir means none of the per-site ini drop-ins land — including the
+  ## path-parity mapping. Previously this failed silently; it must not, because
+  ## the tier's cac-fpm parity guarantee is one of the things lost.
+  ##
+  ## Two different things land here and they are not the same report. "lsphp
+  ## reports no additional-ini scan dir" ASSERTS that lsphp answered us, which
+  ## is false when the probe produced nothing at all — and that was the wrong
+  ## half of the same mistake the parity branch above made: describing a probe
+  ## that could not answer as a finding about the image. Say which one it was.
+  if lsphp_info_is_usable "$LSPHP_INFO"; then
+    echo "WARNING: entrypoint-lsphp: lsphp reports no additional-ini scan dir — per-site error_log, opcache and \$_SERVER path-parity settings were NOT applied." >&2
+    PATH_PARITY_MODE="none (no scan dir)"
+  else
+    echo "WARNING: entrypoint-lsphp: '${LSPHP_BIN} -i' produced no usable phpinfo output (${#LSPHP_INFO} bytes) — per-site error_log, opcache and \$_SERVER path-parity settings were NOT applied. This is a PROBE failure and establishes nothing about what the image contains; run '${LSPHP_BIN} -i' in this container before concluding anything about it." >&2
+    PATH_PARITY_MODE="none (lsphp -i unusable)"
  fi
 fi

+echo "entrypoint-lsphp: \$_SERVER path parity = ${PATH_PARITY_MODE} (${OLS_SITE_PATH} -> /home/${user})"
+
 ## ---- ownership ----
 ## Ensure the dirs we created + the log file are customer-owned so lsphp (running
 ## as $user) can read code and write logs. Customer content is already
@@ -32,18 +32,127 @@ if [ ! -f "$CERT_FILE" ]; then
    -keyout "$KEY_FILE" -out "$CERT_FILE" -subj "/CN=shared-ols" 2>/dev/null
 fi

-## ---- health vhost (catch-all): valid server with zero customer sites +
-## answers HAProxy health checks that hit by IP / unknown Host with a 200 ----
+## ---- health vhost (catch-all) ----
+## This vhost is mapped `map _health *` by render-shared-ols-config.sh, so it
+## answers EVERY Host that no customer vhost claims. It exists so the server is
+## valid with zero customer sites and so local/edge health probes get a 200.
+##
+## IT MUST NOT ANSWER 200 FOR AN UNMAPPED CUSTOMER HOST.
+## It used to serve html/index.html ("shared-ols", 11 bytes) with HTTP 200 to
+## anything that fell through. Measured 2026-08: three live customer sites
+## (their vhost had silently stopped being rendered) served that 200 for ~2
+## months and no monitor noticed, because every uptime check asks "is it 200?"
+## and the answer was yes. A hostname this server cannot serve now gets
+## 421 Misdirected Request -- semantically exact (RFC 7540 s9.1.2: the server is
+## not able to produce a response for the combination of scheme and authority in
+## the request URI) and unambiguous to monitoring in a way 404 is not, since a
+## 404 is a perfectly normal answer from a real, working site.
+##
+## THE DISCRIMINATOR: request path /healthz AND an INTERNAL client address.
+##   * Path alone is not enough -- anyone can request /healthz.
+##   * REMOTE_ADDR is the half an outside caller cannot choose, BECAUSE of
+##     `useIpInProxyHeader 1` in httpd_config_base.tpl: OLS resolves the client
+##     IP from X-Forwarded-For, and HAProxy -- the only thing that can reach
+##     this tier, which has no host-published ports and sits on client-net --
+##     SETS (not appends) that header:
+##     `http-request set-header X-Forwarded-For %[var(txn.real_ip)]` in
+##     haproxy-manager-base/templates/hap_backend.tpl, which DISCARDS whatever
+##     the client sent. So a request arriving from outside carries the real
+##     public client IP. Verified on the lab: `-H 'X-Forwarded-For: 8.8.8.8'`
+##     on /healthz returns 421.
+##   * MEASURED LIMIT OF THE IP GATE, stated plainly rather than assumed away:
+##     OLS takes the FIRST element of a multi-value X-Forwarded-For as
+##     REMOTE_ADDR. `X-Forwarded-For: 10.0.0.1, 8.8.8.8` returns 200 on /healthz
+##     here, and anchoring the pattern ^...$ does NOT change that (tested both
+##     ways) -- because by the time the rule sees REMOTE_ADDR it is already the
+##     single token `10.0.0.1`. The anchors are kept because they are correct
+##     and free, not because they close that hole. What closes it is HAProxy:
+##     `http-request set-header X-Forwarded-For %[var(txn.real_ip)]` REPLACES
+##     whatever the client sent with one value.
+##   * AND THE GATE IS NOT LOAD-BEARING ANYWAY. It only guards /healthz. `/`,
+##     and every other path, is 421 UNCONDITIONALLY -- no header, source
+##     address or Host can talk this vhost into a 200 there. So even a total
+##     bypass of the IP gate buys an attacker a 3-byte `ok` on /healthz, never
+##     a "the site is up" answer on the URL a monitor actually requests. That
+##     is the property this change exists to guarantee, and it does not rest on
+##     anything spoofable.
+##   * The probes that MUST keep passing all originate inside: the Docker
+##     HEALTHCHECK (`curl -sfk https://127.0.0.1/healthz` in Dockerfile.shared-ols,
+##     overridden by WHP's setup-shared-ols.sh to `https://localhost/healthz`)
+##     connects over loopback and sends no X-Forwarded-For, so REMOTE_ADDR falls
+##     back to the peer, 127.0.0.1. An edge/host probe of the container IP comes
+##     from the docker gateway (172.16/12), also allowed.
+##
+## `/` is 421 for EVERY client, internal ones included -- there is deliberately
+## no "internal clients still get the old 200 page" escape hatch, because that
+## is exactly the response that hid the outage. Anything probing this tier for
+## liveness must ask for /healthz.
+##
+## WHY REWRITE AND NOT A REDIRECT CONTEXT: `context / { type redirect
+## statusCode 421 }` was measured on this image (OLS 1.8.4) and does NOT work --
+## 421 is not in OLS's accepted status-code list, so it silently degrades to a
+## 302 with a literal, unexpanded `Location: $DOC_ROOT/?`. A rewrite `[R=421,L]`
+## does emit a real 421.
+##
+## WHY THE THE_REQUEST GUARD ON THE ERROR PAGE: a bare [R=421] has no body, and
+## a bare 421 with no explanation is a support ticket. `errorpage 421` supplies
+## the body, but OLS fetches that URL as a fresh internal request that runs
+## through these same rules -- without an exception it is itself 421'd and the
+## body comes back empty (measured: content-length 0). %{IS_SUBREQ} and
+## %{ENV:REDIRECT_STATUS} are NOT populated by OLS's rewrite engine (both
+## measured, both no-ops), but %{THE_REQUEST} keeps the ORIGINAL request line
+## across the internal fetch. So: serve misdirected.html when the client did not
+## itself ask for it, which lets the error page render while a direct external
+## GET /misdirected.html still gets 421 -- no path on this catch-all answers 200
+## to an outside caller.
+##
+## The body is deliberately generic: no branding, no customer names, nothing
+## that reveals which hostnames this server does serve. Every unmapped Host and
+## every path gets the byte-identical 421, so the response cannot be used to
+## enumerate configured vs unconfigured hostnames.
 cat > "$HEALTH_DIR/vhconf.conf" <<'EOF'
 docRoot                   $VH_ROOT/html
 enableScript              0
+
+errorpage 421 {
+  url                     /misdirected.html
+}
+
+rewrite {
+  enable                  1
+  rules                   <<<END_rules
+  RewriteCond %{THE_REQUEST} !\s/+misdirected\.html
+  RewriteRule ^/?misdirected\.html$ - [L]
+  RewriteCond %{REMOTE_ADDR} ^(127\.0\.0\.1|::1|10\.[0-9.]+|192\.168\.[0-9.]+|172\.(1[6-9]|2[0-9]|3[01])\.[0-9.]+)$
+  RewriteRule ^/?healthz$ - [L]
+  RewriteRule .* - [R=421,L]
+  END_rules
+}
+
 context / {
  allowBrowse             1
  location                $DOC_ROOT/
 }
 EOF
 printf 'ok\n' > "$HEALTH_DIR/html/healthz"
-printf 'shared-ols\n' > "$HEALTH_DIR/html/index.html"
+cat > "$HEALTH_DIR/html/misdirected.html" <<'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>421 Misdirected Request</title></head>
+<body>
+<h1>421 Misdirected Request</h1>
+<p>This hostname is not configured on this server.</p>
+<p>If you own this domain, check that its DNS points to the correct server and
+that the site is active in your hosting control panel.</p>
+</body>
+</html>
+EOF
+## The old catch-all index.html ("shared-ols") is gone on purpose, and actively
+## removed so an in-place upgrade of a long-lived container cannot leave it
+## behind. If these rewrite rules were ever to stop applying, `context /` would
+## fall back to serving the docRoot index -- with no index.html that is a 403,
+## which is wrong-but-loud, instead of a 200 that is wrong-and-silent.
+rm -f "$HEALTH_DIR/html/index.html"

 ## ---- ownership: OLS reads conf/ as lsadm. chown the base conf dir + health dir
 ## NON-recursively (the per-site files under conf/shared-sites are written by the
@@ -51,7 +160,7 @@ printf 'shared-ols\n' > "$HEALTH_DIR/html/index.html"
 ## every container (re)start, delaying first-listen after a crash). The render
 ## script chowns the httpd_config.conf it produces. ----
 chown lsadm:nogroup "$LSWS_CONF" "$HEALTH_DIR" "$HEALTH_DIR/html" 2>/dev/null || true
-chown lsadm:nogroup "$HEALTH_DIR/vhconf.conf" "$HEALTH_DIR/html/healthz" "$HEALTH_DIR/html/index.html" 2>/dev/null || true
+chown lsadm:nogroup "$HEALTH_DIR/vhconf.conf" "$HEALTH_DIR/html/healthz" "$HEALTH_DIR/html/misdirected.html" 2>/dev/null || true

 ## ---- assemble httpd_config.conf from the panel's per-site files ----
 /scripts/render-shared-ols-config.sh
@@ -75,7 +184,48 @@ term_handler() {
 }
 trap term_handler TERM INT

-ols_running() { /usr/local/lsws/bin/lswsctrl status 2>/dev/null | grep -qi 'running with pid'; }
+## NOT `lswsctrl status` (unlike the otherwise-identical function in
+## entrypoint-litespeed.sh). `lswsctrl` appends a timestamped line to
+## logs/lsrestart.log on EVERY invocation it makes, including `status` — and
+## this loop polls every 3s forever. Measured on whp01: lsrestart.log is 96 MB,
+## holding 1,819,286 `status` lines against 2,429 real `restart` lines; at one
+## poll per 3s that's ~63 days of continuous polling, which is exactly the
+## file's age, and it isn't rotated on any host (whp01/whp02/sdbees all growing
+## at ~1.5 MB/day). So: check liveness directly instead of shelling out to a
+## tool whose logging is a side effect we don't want on a fixed timer.
+##
+## Verified (docker run litespeedtech/openlitespeed:1.8.4-lsphp83, the exact
+## base this image is built FROM — see Dockerfile.shared-ols): the running main
+## process shows in `ps` as `openlitespeed (lshttpd - main)`, one PID, always
+## present while OLS is up and absent the instant it is killed (checked via
+## `ps aux` immediately after `kill -9` on the main PID). `pgrep -f` matches
+## against the full command line, and no other process on this image's `ps`
+## output contains that string, so this cannot cross-match an unrelated
+## process. It also cannot self-match: pgrep excludes its own PID by default,
+## and the invoking process here is bash executing this script file, whose own
+## argv never contains the pattern text (only the *source lines* of this script
+## do, which `pgrep -f` never sees).
+##
+## Deliberately NOT the pidfile (/tmp/lshttpd/lshttpd.pid, confirmed present in
+## the same probe): pidfiles are known to go stale across a crash (verified —
+## after `kill -9` the file still held the dead PID), and treating a stale PID
+## as "alive" if the kernel ever reuses that number is a false positive this
+## supervisor cannot afford (see below). `pgrep -f` reads the live process
+## table, so there is no staleness window to reason about.
+##
+## Conservative on both failure directions, which matters because this is a
+## supervisor predicate, not a metric: a false negative makes start_ols() run
+## `lswsctrl start` against an already-running OLS — verified against the same
+## probe base image, that is NOT a no-op, it sends SIGUSR1 to the live main
+## process, i.e. the same graceful self-restart QUIC.cloud IP refreshes trigger
+## (see entrypoint-litespeed.sh's note on that handoff) — a brief, zero-
+## downtime blip at worst. A false positive is worse: it leaves a genuinely
+## dead OLS un-revived until some later poll happens to notice. So if this
+## predicate is ever in doubt it should err toward reporting "not running", not
+## "running".
+ols_running() {
+  pgrep -f 'lshttpd - main' >/dev/null 2>&1
+}

 MAX_STARTS=5
 WINDOW=60
@@ -15,6 +15,20 @@
 ## runs it and the panel monitors it (check-ols-htaccess-watcher.php).
 set -uo pipefail

+## WATCH_ROOT is deliberately left as the host-wide /mnt/users, not narrowed to
+## the shared-OLS tenant set, even though that set IS derivable in-container
+## (render-shared-ols-config.sh's $SITES_ROOT/*/site.meta VHROOT= is exactly
+## that list). Narrowing it would mean handing inotifywait a fixed argv list of
+## VHROOT dirs at process start — and inotifywait cannot be told to watch a NEW
+## directory once running. The panel provisions sites onto this container live,
+## between renders; a site added after the watcher started would then sit
+## outside every watch until the next container restart, i.e. exactly the
+## silent-failure mode (spec 7) this script exists to prevent, now for brand
+## new tenants instead of none. Doing this safely needs a reload path (SIGHUP
+## re-exec off the current site.meta list, coordinated with
+## render-shared-ols-config.sh) that does not exist yet and is its own change.
+## So: WATCH_ROOT stays broad, and correctness comes entirely from the path
+## match below, which is sufficient on its own.
 WATCH_ROOT="${OLS_WATCH_ROOT:-/mnt/users}"
 DEBOUNCE="${OLS_HTACCESS_DEBOUNCE:-15}"   # coalesce window (s)
 FLOOR="${OLS_HTACCESS_FLOOR:-60}"         # min seconds between restarts
@@ -24,16 +38,17 @@ last_restart=0
 log() { echo "ols-htaccess-watcher: $*" >&2; }

 do_restart() {
+  path="$1"
  now=$(date +%s)
  if [ $((now - last_restart)) -lt "$FLOOR" ]; then
-    log "within ${FLOOR}s floor — coalescing, skipping restart"
+    log "within ${FLOOR}s floor — coalescing, skipping restart ($path)"
    return
  fi
  if "$LSWSCTRL" restart >/dev/null 2>&1; then
    last_restart=$now
-    log "graceful restart issued (.htaccess change)"
+    log "graceful restart issued — $path changed"
  else
-    log "WARNING: lswsctrl restart failed"
+    log "WARNING: lswsctrl restart failed ($path)"
  fi
 }

@@ -41,18 +56,34 @@ if ! command -v inotifywait >/dev/null 2>&1; then
  log "FATAL: inotifywait not installed (inotify-tools)"; exit 1
 fi
 mkdir -p "$WATCH_ROOT"
-log "watching $WATCH_ROOT for .htaccess changes (debounce=${DEBOUNCE}s floor=${FLOOR}s)"
+log "watching $WATCH_ROOT for docroot (public_html) .htaccess changes (debounce=${DEBOUNCE}s floor=${FLOOR}s)"

-## -m monitor, -r recursive. We filter to .htaccess in the read loop rather than
-## --include so this works on older inotify-tools too. modify/create/delete/move
-## all matter (delete of .htaccess also changes rewrite behavior).
-inotifywait -m -r -e modify,create,delete,move "$WATCH_ROOT" --format '%f' 2>/dev/null |
-while read -r fname; do
-  case "$fname" in
-    .htaccess) ;;
+## -m monitor, -r recursive. We filter in the read loop rather than --include
+## so this works on older inotify-tools too. modify/create/delete/move all
+## matter (delete of .htaccess also changes rewrite behavior).
+##
+## --format '%w%f' (full path), NOT '%f' (basename only). OLS reads .htaccess
+## (RewriteFile) only from a vhost's DOCROOT — VHROOT, i.e.
+## /mnt/users/<user>/<domain>/public_html (see render-shared-ols-config.sh /
+## entrypoint-lsphp.sh) — never anything below it. A basename-only match fires
+## for ANY .htaccess anywhere under a tenant, at any depth, and WordPress
+## plugins write plenty of those that OLS never opens: measured on whp01 over
+## 24h, this watcher fired 63 restarts, of which the docroot .htaccess actually
+## changed in 0. All 28 distinct files behind those 63 were plugin guard files
+## — Wordfence self-healing waf/views/vendor/tmp/models/lib/.htaccess, W3 Total
+## Cache writing one per cached URL under wp-content/cache/page_enhanced/, plus
+## WPForms/Gravity Forms/UpdraftPlus/Groundhogg/WP Staging upload guards — and
+## most of those tenants are on the shared Apache tier (cac-fpm), not this OLS
+## tier at all, so their cache churn was restarting the OLS serving 15 unrelated
+## tenants for no reason. Matching the full path down to /public_html/.htaccess
+## is what actually ties a change to something OLS will reread.
+inotifywait -m -r -e modify,create,delete,move "$WATCH_ROOT" --format '%w%f' 2>/dev/null |
+while read -r path; do
+  case "$path" in
+    */public_html/.htaccess) ;;
    *) continue ;;
  esac
-  ## A tenant .htaccess changed. Coalesce the save-burst, then restart ONCE.
+  ## A tenant DOCROOT .htaccess changed. Coalesce the save-burst, then restart ONCE.
  ##
  ## The coalesce is HARD-BOUNDED to DEBOUNCE seconds: a previous version blocked
  ## on `read -t DEBOUNCE` which, on a busy multi-tenant server, never timed out
@@ -69,5 +100,5 @@ while read -r fname; do
      break      # ~2s of total quiet — the burst has settled
    fi
  done
-  do_restart
+  do_restart "$path"
 done
@@ -82,18 +82,61 @@ awk '
 } >> "$TMP"

 ## --- 4. emit per-site vhost stanzas + collect listener map lines ---
+##
+## First value of KEY= in a site.meta, as plain data. This replaces
+## `sed -n 's/^KEY=//p' "$meta" | head -1`, which was a pipeline whose reader
+## (`head -1`) exits after one line while the writer (`sed`) may still be
+## flushing: the writer then dies 141, and `set -euo pipefail` (line 22) makes
+## the whole ASSIGNMENT fail, which aborts this script mid-render. A truncated
+## httpd_config.conf is never written (the render is atomic), but the effect is
+## that a site the panel just provisioned silently never appears in the config
+## and every subsequent render fails the same way.
+##
+## Measured in this image, `sed -n 's/^DOMAINS=//p' | head -1`:
+##   400 matching lines (~6 KB of sed output)   -> 0 0 0 0 0
+##   6000 matching lines (~90 KB of sed output) -> 141 141 141
+## Do not read a threshold into those two rows. There is no size below which
+## this is safe: each run is a RACE on whether `head` closes the pipe before
+## `sed`'s final write() returns, and the payload only decides how many write()
+## syscalls sed has to lose. Measured against a default 65536-byte pipe
+## (F_GETPIPE_SZ), 41144 bytes SIGPIPEd on 32 of 300 runs — 11%, well under
+## capacity — and 65012 bytes still only on 25 of 30, so it is neither safe
+## below capacity nor certain at it; strace caught a writer dying having put
+## 12086 of 40406 bytes into a 65536-byte pipe. What actually separated a host
+## that failed 5/5 from one that passed 10/10 was the WRITER's syscall size
+## (bash <= 5.2.15 writes ~37 KB at a time, >= 5.2.21 writes 80-160 bytes), not
+## the host's pipe capacity. (An earlier draft of this comment blamed
+## fs.pipe-user-pages-soft; that limit clamps new pipes to two pages, not one,
+## only past 1024 pipes for one uid, and never for CAP_SYS_RESOURCE.)
+##
+## So the rule this file follows is structural, not statistical: under pipefail,
+## a writer piped into a reader that can stop early (`head`, `grep -q`/`-l`/`-m`,
+## `sed q`, `awk ... exit`, `read`) is a latent 141 — full stop. A call site is
+## only sound when the file does not set pipefail, or the reader provably runs
+## to EOF, or the status is thrown away. "A site.meta would never be that big"
+## was never one of those, least of all for panel-written input we do not
+## validate.
+##
+## awk reads the FILE directly and stops at the first hit: no pipeline, so
+## nothing for pipefail to adopt. Same semantics as before, verified against
+## the old form on duplicate keys, decoy keys (`notVHNAME=`), empty values and
+## missing keys: first match wins, the rest of the line is the value, verbatim.
+meta_value() {
+  awk -v k="$1" 'index($0, k "=") == 1 { print substr($0, length(k) + 2); exit }' "$2"
+}
+
 maps=""
 site_count=0
 for meta in "$SITES_ROOT"/*/site.meta; do
  [ -e "$meta" ] || continue
  sdir=$(dirname "$meta")
-  ## PARSE site.meta with sed — do NOT `source` it. The panel writes these values
+  ## EXTRACT from site.meta — do NOT `source` it. The panel writes these values
  ## (derived from DB domains), so they should be safe, but sourcing paneldata as
  ## shell would execute any metacharacters as root in this container if a value
-  ## ever slipped validation. sed extraction treats them as plain data.
-  VHNAME=$(sed -n 's/^VHNAME=//p'  "$meta" | head -1)
-  VHROOT=$(sed -n 's/^VHROOT=//p'  "$meta" | head -1)
-  DOMAINS=$(sed -n 's/^DOMAINS=//p' "$meta" | head -1)
+  ## ever slipped validation. meta_value treats them as plain data.
+  VHNAME=$(meta_value VHNAME  "$meta")
+  VHROOT=$(meta_value VHROOT  "$meta")
+  DOMAINS=$(meta_value DOMAINS "$meta")
  if [ -z "$VHNAME" ] || [ -z "$VHROOT" ] || [ -z "$DOMAINS" ] || [ ! -f "$sdir/vhconf.conf" ]; then
    echo "render-shared-ols: skipping $sdir (incomplete: VHNAME/VHROOT/DOMAINS/vhconf.conf)" >&2
    continue
@@ -113,8 +156,25 @@ for meta in "$SITES_ROOT"/*/site.meta; do
 done

 ## --- 5. ALWAYS add a health vhost mapped to the catch-all so the server is
-## valid with zero customer sites and HAProxy health checks (which hit by IP /
-## unknown Host) get a 200. Exact-domain maps above win over this '*'. ---
+## valid with zero customer sites. Exact-domain maps above win over this '*'.
+##
+## THIS MAP IS WHY AN UNMAPPED HOST GETS AN ANSWER AT ALL. Anything the loop
+## above did not emit a `map` for -- a customer domain whose site dir went
+## missing, a stale DNS record, a scanner probing by IP -- lands here. It used
+## to answer 200 with an 11-byte "shared-ols" body, which is how three live
+## customer sites stayed silently broken for ~2 months: every uptime monitor
+## asks "is it 200?" and it was.
+##
+## The health vhost (its vhconf.conf is written by entrypoint-shared-ols.sh,
+## which carries the full rationale) now answers 421 Misdirected Request with a
+## short generic body for any Host it cannot serve, and keeps 200 ONLY for
+## GET /healthz from an internal client address -- the Docker HEALTHCHECK and
+## edge liveness probes. Do NOT reintroduce a 200 here for `/`: probe /healthz.
+##
+## The listener `map` itself is unchanged, deliberately. Dropping the catch-all
+## instead would make OLS answer an unmapped Host from whichever vhost it
+## considers first, which is worse: an unmapped Host would be served SOMEONE
+## ELSE'S SITE. ---
 {
  echo ""
  echo "virtualhost _health {"
@@ -0,0 +1,564 @@
+#!/usr/bin/env bash
+## lsphp-info-probe.test.sh — regression test for the SIGPIPE-under-pipefail
+## class of bug that shipped in cac-lsphp (trunk 9343a56) and silently turned
+## $_SERVER path parity off on every shared-ols site whose host lost the race.
+##
+## THE BUG. entrypoint-lsphp.sh asked "is cac_path_parity loaded?" with
+##
+##     printf '%s\n' "$LSPHP_INFO" | grep -q '^cac_path_parity support => enabled$'
+##
+## under `set -euo pipefail`. `grep -q` exits the instant it matches; printf is
+## still pushing the rest of `lsphp -i` into the pipe, takes SIGPIPE, and exits
+## 141; pipefail prefers that over grep's 0. So the test read FALSE **because
+## the extension was present** — present early enough in the output to stop the
+## reader — and the container fell back to the degraded auto_prepend normaliser
+## the extension exists to replace, while telling the operator the extension was
+## "not loadable in this image".
+##
+## THE RULE THIS FILE ENFORCES, stated so nobody re-derives a wrong one: ANY
+## `writer | early-exiting-reader` under pipefail is a latent 141. PAYLOAD SIZE
+## IS NOT A SAFETY ARGUMENT — each run is a race on whether the reader's close
+## lands before the writer's final write() returns, and size only sets how many
+## write() syscalls the writer must survive. Measured against a default
+## 65536-byte pipe: 41144 bytes SIGPIPEd on 32/300 runs (11%, well UNDER
+## capacity) and 65012 bytes on 25/30 (not certain even AT capacity); 500 KB
+## into a 1 MiB pipe was 200/200 when written 4096 bytes at a time and 0/200 as
+## a single write. A call site is sound only for a STRUCTURAL reason: the file
+## does not set pipefail, or the reader provably consumes to EOF (no `q`, `-q`,
+## `-l`, `-m`, `exit`, `break`), or the pipeline's status is discarded. Section 4
+## below prints this race happening at ~41 KB; if the numbers there ever read as
+## "small payloads are fine", the numbers are right and the reading is wrong.
+##
+## WHY THE EXISTING SUITE DID NOT CATCH IT. The .phpt suite and
+## fpm-parity-check.sh both test the EXTENSION; nothing executed the
+## ENTRYPOINT's branch logic, and the Dockerfile's own `lsphp -i | grep -q`
+## build gate runs under `bash -c 'set -e'` with NO pipefail, so it reported the
+## extension present in the very image whose entrypoint declared it missing.
+##
+## WHAT THIS ASSERTS.
+##   1. behaviour — the SHIPPED probe helpers (extracted verbatim from
+##      entrypoint-lsphp.sh, never copied, so they cannot drift) return the
+##      right answer AND a clean exit status under `set -euo pipefail` with a
+##      realistic ~40 KB phpinfo body.
+##   2. structure — no script in this repo that enables pipefail pipes into a
+##      reader that can exit before its writer finishes. This is the check that
+##      fails deterministically against trunk; assertion 1's *old* form is a
+##      RACE (measured 141 on 3 of 5 runs here, 5 of 5 on whp02, and 0 of 5
+##      under a different Docker daemon), so no behavioural assertion about the
+##      broken code could be trusted to fail on every machine. Section 4 runs
+##      the old form anyway and prints what it did, for the record.
+##   3. equivalence — the helpers' pure-bash matching answers exactly what the
+##      grep/awk patterns they replaced answer, checked case by case against
+##      those same patterns reading a FILE (a file, so the reference itself
+##      cannot SIGPIPE). Section 6.
+##   4. the scan's own coverage — every reader shape section 5 claims to catch
+##      is caught, and a matched set of safe shapes is NOT flagged. Section 7.
+##      Without this the scan's regexes are unfalsified and can quietly stop
+##      matching; `grep -l` and `sed q` were both missed until section 7 existed.
+##
+## SCOPE LIMITS, stated rather than hidden. The structural scan is a text scan,
+## so it under-reports in known ways:
+##   - it reads one line at a time. The repo's only multi-line pipeline
+##     (ols-htaccess-watcher.sh's `inotifywait … |` / `while read`) is invisible
+##     to it and was reviewed by hand: that reader loops until EOF, i.e. until
+##     the writer has already gone, so it cannot produce this failure.
+##   - its quote stripping is flat, so a pipe nested inside a command
+##     substitution inside a quoted string (`echo "x ($(a | head -1))"`) is read
+##     as quoted text and skipped.
+##   - the reader list is an ENUMERATION, not a proof. It knows `grep`
+##     (-q/-l/-L/-m and their long forms), `head`, `read`, `awk … exit` and
+##     `sed` with a q/Q command; it does not know an early exit hidden in
+##     `perl -ne '… last'`, `python -c`, `jq`, `head -c`, or any project-local
+##     program that stops reading. A reader not on the list is not thereby safe.
+##   - it only inspects the FIRST word after a pipe, so `foo | LC_ALL=C grep -q`
+##     or `foo | { grep -q x; }` reads as an unknown reader and is skipped.
+## It is a guard against reintroducing the shape, not a proof of its absence.
+##
+## Usage: scripts/tests/lsphp-info-probe.test.sh [REPO_ROOT]
+## Exit: 0 all assertions passed, 1 an assertion FAILED, 2 the test could not run.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${1:-$(cd "$HERE/../.." && pwd)}"
+ENTRYPOINT="$ROOT/scripts/entrypoint-lsphp.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+pass=0; fail=0
+ok()   { pass=$((pass+1)); echo "  ok   — $1"; }
+bad()  { fail=$((fail+1)); echo "  FAIL — $1" >&2; }
+die()  { echo "HARNESS FAILURE: $*" >&2; exit 2; }
+
+[ -f "$ENTRYPOINT" ] || die "no entrypoint at $ENTRYPOINT (pass REPO_ROOT as \$1)"
+
+## ---------------------------------------------------------------------------
+## 1. Extract the real probe helpers. Not a copy: whatever the shipped
+##    entrypoint says between the markers is what runs below, so a future edit
+##    that reintroduces a pipeline is tested, not narrated.
+##
+##    A missing block is an assertion FAILURE, not a harness error, and it does
+##    not stop the run: against a pre-fix checkout the probes are still inline
+##    pipelines, and section 5 below is what names them. Bailing out here would
+##    have replaced that report with "could not run".
+##
+##    BOUNDED ON PURPOSE. The extraction buffers and emits NOTHING until it has
+##    seen the END marker, so deleting or mistyping that one line is a marker
+##    error (exit 4) rather than a slurp of every line after BEGIN into a file
+##    this harness then `source`s. That is not hypothetical: it happened during
+##    development and only failed loudly by luck — `set -u` tripped over an
+##    unbound variable two statements into the entrypoint's real boot code. An
+##    extractor whose failure mode is "execute arbitrary parts of the program
+##    under test" is not a safe thing to leave lying around, however careful the
+##    markers are today.
+##      exit 0 = both markers, block on stdout
+##      exit 3 = no BEGIN marker at all (pre-fix checkout, or block removed)
+##      exit 4 = BEGIN seen, END missing — refuse to emit, refuse to source
+## ---------------------------------------------------------------------------
+HAVE_HELPERS=yes
+XRC=0
+awk '
+  /^## ---- CAC-TEST: probe helpers BEGIN ----$/ { f = 1 }
+  f { buf = buf $0 ORS }
+  f && /^## ---- CAC-TEST: probe helpers END ----$/ { printf "%s", buf; found = 1; exit 0 }
+  END { if (found) exit 0; else if (f) exit 4; else exit 3 }
+' "$ENTRYPOINT" > "$TMP/helpers.sh" || XRC=$?
+
+case "$XRC" in
+  0)
+    for fn in lsphp_info_has_parity_ext lsphp_info_scan_dir lsphp_info_is_usable; do
+      if ! grep -q "^${fn}()" "$TMP/helpers.sh"; then
+        HAVE_HELPERS=no
+        bad "the probe-helper block in ${ENTRYPOINT#"$ROOT"/} defines no ${fn}()"
+      fi
+    done
+    ;;
+  4)
+    HAVE_HELPERS=no
+    : > "$TMP/helpers.sh"
+    bad "${ENTRYPOINT#"$ROOT"/} has a 'CAC-TEST: probe helpers BEGIN' marker with no matching END marker. Nothing was extracted — an unterminated block would otherwise have pulled the whole rest of the entrypoint into a file this test sources and runs."
+    ;;
+  3)
+    HAVE_HELPERS=no
+    bad "no probe-helper markers in ${ENTRYPOINT#"$ROOT"/} — either they were removed, or this is a pre-fix checkout where the probes are still inline pipelines (trunk 9343a56). Section 5 says which lines."
+    ;;
+  *)
+    HAVE_HELPERS=no
+    bad "extracting the probe-helper block from ${ENTRYPOINT#"$ROOT"/} failed (awk exit $XRC)"
+    ;;
+esac
+
+## ---------------------------------------------------------------------------
+## 2. Fixtures. Shaped like real `lsphp -i`: the two lines the probes look for
+##    sit near the TOP (that is what lets a reader stop early), with tens of KB
+##    of body after them. A fixture whose marker is near the end could not
+##    SIGPIPE at all and would make this whole test vacuous, so both properties
+##    are asserted before anything else runs.
+## ---------------------------------------------------------------------------
+SCAN_PATH='/usr/local/lsws/lsphp83/etc/php/8.3/mods-available'
+make_fixture() {  # $1=outfile  $2=yes|no (include the cac_path_parity line)
+  {
+    printf 'phpinfo()\nPHP Version => 8.3.27\n\n'
+    printf 'System => Linux 6ecb4e0a1c1f 5.15.0 #1 SMP x86_64\n'
+    printf 'Server API => LiteSpeed V8.3\n'
+    printf 'Configuration File (php.ini) Path => /usr/local/lsws/lsphp83/etc/php/8.3/litespeed\n'
+    printf 'Scan this dir for additional .ini files => %s\n' "$SCAN_PATH"
+    printf 'PHP API => 20230831\nDebug Build => no\nThread Safety => disabled\n\n'
+    printf 'bcmath\n\nBCMath support => enabled\n\n'
+    printf 'calendar\n\nCalendar support => enabled\n\n'
+    [ "$2" = yes ] && printf 'cac_path_parity\n\ncac_path_parity support => enabled\nRewriting => active\n\n'
+    printf 'Core\n\nPHP Version => 8.3.27\n\n'
+    ## ~40 KB of directive rows, exactly the shape phpinfo() prints them in.
+    local i=0
+    while [ "$i" -lt 700 ]; do
+      printf 'some.directive_%03d => local_value_%03d => master_value_%03d\n' "$i" "$i" "$i"
+      i=$((i+1))
+    done
+  } > "$1"
+}
+make_fixture "$TMP/info-present.txt" yes
+make_fixture "$TMP/info-absent.txt"  no
+: > "$TMP/info-empty.txt"
+
+echo "== fixture sanity =="
+FIX_BYTES=$(wc -c < "$TMP/info-present.txt")
+MATCH_OFF=$(grep -b -m1 '^cac_path_parity support => enabled$' "$TMP/info-present.txt" | cut -d: -f1)
+if [ "$FIX_BYTES" -ge 32768 ]; then
+  ok "fixture is ${FIX_BYTES} bytes (realistic 'lsphp -i' is ~40 KB)"
+else
+  bad "fixture is only ${FIX_BYTES} bytes — too small to reproduce the failure"
+fi
+if [ "$MATCH_OFF" -lt $((FIX_BYTES / 4)) ]; then
+  ok "match sits at byte ${MATCH_OFF} of ${FIX_BYTES} — most of the body is still unwritten when a reader could stop"
+else
+  bad "match at byte ${MATCH_OFF} of ${FIX_BYTES} leaves too small a tail; the test would be vacuous"
+fi
+
+## ---------------------------------------------------------------------------
+## 3. Behaviour, under the REAL option set (`set -euo pipefail`, as line 34 of
+##    the entrypoint sets it). Each case runs in its own bash process so the
+##    options and the exit status are the genuine article, not something this
+##    harness simulated.
+## ---------------------------------------------------------------------------
+cat > "$TMP/runner.sh" <<'RUNNER'
+#!/usr/bin/env bash
+set -euo pipefail
+# shellcheck disable=SC1091
+source "$1"                      # the extracted probe helpers
+LSPHP_INFO=$(cat "$2")
+case "$3" in
+  has_ext)  lsphp_info_has_parity_ext "$LSPHP_INFO" ;;
+  scan_dir) lsphp_info_scan_dir "$LSPHP_INFO" ;;
+  usable)   lsphp_info_is_usable "$LSPHP_INFO" ;;
+  legacy)   printf '%s\n' "$LSPHP_INFO" | grep -q '^cac_path_parity support => enabled$' ;;
+  *) echo "unknown case $3" >&2; exit 99 ;;
+esac
+RUNNER
+
+## NOT `out=$(run …)`: command substitution runs the function in a subshell,
+## where an exit status assigned to RC would be thrown away with it. Run in this
+## shell, capture stdout through a file, and RC is the real thing.
+RC=0; out=""
+run() {  # $1=fixture $2=case -> sets RC and out
+  RC=0
+  bash "$TMP/runner.sh" "$TMP/helpers.sh" "$1" "$2" >"$TMP/out" 2>&1 || RC=$?
+  out=$(cat "$TMP/out")
+}
+
+echo "== the shipped probes under set -euo pipefail =="
+if [ "$HAVE_HELPERS" = no ]; then
+  echo "  (skipped — no probe helpers to run; see the failure above)"
+fi
+if [ "$HAVE_HELPERS" = yes ]; then
+
+run "$TMP/info-present.txt" has_ext
+if [ "$RC" -eq 0 ]; then
+  ok "extension present => branch TAKEN (exit 0)"
+elif [ "$RC" -eq 141 ]; then
+  bad "exit 141 (SIGPIPE): the probe is a pipeline again — this is the original bug"
+else
+  bad "extension present => exit $RC (expected 0). Output: $out"
+fi
+
+run "$TMP/info-absent.txt" has_ext
+if [ "$RC" -eq 1 ]; then
+  ok "extension genuinely absent => branch NOT taken (exit 1, a clean 'no')"
+else
+  bad "extension absent => exit $RC (expected 1). Output: $out"
+fi
+
+run "$TMP/info-present.txt" scan_dir
+if [ "$RC" -eq 0 ] && [ "$out" = "$SCAN_PATH" ]; then
+  ok "scan-dir probe returns '$out' (exit 0)"
+elif [ "$RC" -eq 141 ]; then
+  bad "scan-dir probe exit 141 (SIGPIPE) — as a bare assignment under set -e that KILLS PID 1"
+else
+  bad "scan-dir probe => exit $RC, got '$out', expected '$SCAN_PATH'"
+fi
+
+run "$TMP/info-present.txt" usable
+if [ "$RC" -eq 0 ]; then ok "usability probe: real phpinfo body => usable (exit 0)"
+else bad "usability probe on real body => exit $RC (expected 0)"; fi
+
+run "$TMP/info-empty.txt" usable
+if [ "$RC" -eq 1 ]; then ok "usability probe: empty body => NOT usable (exit 1)"
+else bad "usability probe on empty body => exit $RC (expected 1)"; fi
+
+## The two failure causes must be reported as the different things they are.
+## A probe that cannot answer has established nothing about the image, and the
+## old message asserted the opposite of that for every reason it fired.
+## SC2016: these patterns are the entrypoint's literal text, `$` and all.
+# shellcheck disable=SC2016
+if grep -q 'if lsphp_info_is_usable "$LSPHP_INFO"; then' "$ENTRYPOINT" &&
+   grep -q 'This is a PROBE failure and establishes nothing' "$ENTRYPOINT"; then
+  ok "a probe that produced nothing is reported as OUR failure, not as a verdict on the image"
+else
+  bad "entrypoint no longer reports an unusable 'lsphp -i' as a probe failure"
+fi
+# shellcheck disable=SC2016
+if grep -q 'not loadable in this image' "$ENTRYPOINT" &&
+   grep -q 'answered (${#LSPHP_INFO} bytes, scan dir ${SCAN_DIR}) and does not list it' "$ENTRYPOINT"; then
+  ok "the 'extension not loadable' verdict now ships the evidence it rests on"
+else
+  bad "the 'extension not loadable' message no longer states what it observed"
+fi
+
+fi   # HAVE_HELPERS
+
+## ---------------------------------------------------------------------------
+## 4. The old form, for the record. NOT asserted: it is a race, and asserting a
+##    race would make this suite flap on whichever machine happens to win it.
+## ---------------------------------------------------------------------------
+echo "== the pre-fix pipeline form on the same input (informational) =="
+if [ "$HAVE_HELPERS" = no ]; then
+  echo "  (skipped — the runner needs the helper block to source)"
+fi
+legacy_rcs=""
+if [ "$HAVE_HELPERS" = yes ]; then
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  run "$TMP/info-present.txt" legacy
+  legacy_rcs="$legacy_rcs $RC"
+done
+echo "  10 runs of 'printf | grep -q' under pipefail:${legacy_rcs}"
+echo "  (0 = happened to finish writing, 141 = writer SIGPIPEd and pipefail reported the"
+echo "   extension MISSING because it was present. Either value is expected here.)"
+fi
+
+## ---------------------------------------------------------------------------
+## 5. Structural scan — the deterministic guard, and the part of this file that
+##    fails against trunk on EVERY machine. Any script that turns on pipefail
+##    and pipes into a reader that can stop early has this bug latent in it
+##    whether or not today's buffer sizes expose it, so the shape is what gets
+##    outlawed, not the symptom.
+##
+##    It is a text scan, so it is honest about its limits: it strips quoted
+##    spans and comments (that is what keeps `case a|b)`, `sed "s|x|y|"` and
+##    `echo "a | b"` from being reported), it requires the reader to be the
+##    FIRST word after a pipe, and it reads one line at a time. This file is
+##    skipped because section 4 runs the broken form on purpose.
+## ---------------------------------------------------------------------------
+echo "== structural scan: early-exit readers in pipefail scripts =="
+mapfile -t PIPEFAIL_FILES < <(grep -rl --include='*.sh' -E '^[[:space:]]*set[[:space:]]+-[a-zA-Z]*[[:space:]]*o?[[:space:]]*pipefail|^[[:space:]]*set[[:space:]]+-o[[:space:]]+pipefail' "$ROOT/scripts" "$ROOT/ext" 2>/dev/null | sort)
+[ "${#PIPEFAIL_FILES[@]}" -gt 0 ] || die "found no pipefail-enabled scripts under $ROOT — the scan would be vacuous"
+
+cat > "$TMP/scan.awk" <<'AWKPROG'
+# Does this `grep …` invocation stop reading before EOF? -q/-l/-L/-m do; -c,
+# -i, -v, -o, -n and the rest read the whole input and are none of our business.
+# Walked option by option rather than pattern-matched in one go, because the
+# letters have to be read the way grep reads them: a cluster like -im1 stops
+# early, -e/-f/-A/-B/-C/-d/-D swallow the rest of their token as an ARGUMENT
+# (so `grep -eq` is the pattern "q", not --quiet), and the first non-option word
+# is the pattern, after which nothing is a flag any more.
+function grep_stops_early(s,    a, k, j, t, c, m) {
+  if (s !~ /^[[:space:]]*grep([[:space:];&)]|$)/) return 0
+  sub(/^[[:space:]]*grep([[:space:]]+|$)/, "", s)
+  m = split(s, a, /[[:space:]]+/)
+  for (k = 1; k <= m; k++) {
+    t = a[k]
+    if (t == "") continue
+    if (t == "--") return 0
+    if (t ~ /^--/) {
+      if (t ~ /^--(quiet|silent|max-count|files-with-match|files-without-match)/) return 1
+      continue
+    }
+    if (t !~ /^-/) return 0                    # the pattern; options are over
+    sub(/^-/, "", t)
+    for (j = 1; j <= length(t); j++) {
+      c = substr(t, j, 1)
+      if (c == "q" || c == "l" || c == "L" || c == "m") return 1
+      if (c ~ /[efABCdD]/) break                # rest of the token is its argument
+    }
+  }
+  return 0
+}
+{
+  raw = $0
+  l = raw
+  gsub(/\\"/, "X", l); gsub(/\\'/, "X", l)          # escaped quotes are not delimiters
+  while (match(l, /'[^']*'/)) l = substr(l, 1, RSTART-1) "SQ" substr(l, RSTART+RLENGTH)
+  while (match(l, /"[^"]*"/))             l = substr(l, 1, RSTART-1) "DQ" substr(l, RSTART+RLENGTH)
+  if (l ~ /^[[:space:]]*#/) next                        # whole-line comment
+  sub(/[[:space:]]#.*/, "", l)                          # trailing comment
+
+  # `u` = the line with quote CHARACTERS dropped but their contents KEPT, used
+  # only to read a command's script argument. `l` cannot serve for that: it
+  # replaces a whole quoted span with a placeholder, so `sed 'q'` and
+  # `awk '{exit}'` lose the very token that makes them early-exit readers.
+  u = raw
+  gsub(/["']/, "", u)
+  sub(/[[:space:]]#.*/, "", u)
+
+  gsub(/\|\|/, " ", l)                                  # || is not a pipeline
+  if (l !~ /\|/) next
+  n = split(l, seg, "|")
+  for (i = 2; i <= n; i++) {
+    r = seg[i]
+    if (grep_stops_early(r))                                        { print NR ": " raw; next }
+    # The `[[:space:];&)]|$` tail rather than a bare `[[:space:]]|$`: a reader
+    # can be the last word of a compound command (`… | head; }`), which the
+    # whitespace-only form silently skipped.
+    if (r ~ /^[[:space:]]*head([[:space:];&)]|$)/)                     { print NR ": " raw; next }
+    if (r ~ /^[[:space:]]*(while[[:space:]]+)?read([[:space:];&)]|$)/) { print NR ": " raw; next }
+    if (r ~ /^[[:space:]]*awk([[:space:];&)]|$)/ && u ~ /exit/)         { print NR ": " raw; next }
+    # sed: a q/Q command anywhere in the script — `/re/q`, `2q`, `$q`, `1p;q`,
+    # `{…;q}`, and the bare `sed q` / `sed 'q'` that the earlier pattern missed
+    # (it required a `;`, `{` or `/` in front of the q, which a lone script has
+    # none of). Anchored on what may PRECEDE the q and what may FOLLOW it, so a
+    # q inside a replacement — `sed s/a/q/` — is not read as the command (which
+    # is what the trailing `/` exclusion buys: a command q is never followed by
+    # another delimiter, a replacement q always is).
+    if (r ~ /^[[:space:]]*sed([[:space:];&)]|$)/ &&
+        (u ~ /[;{\/][[:space:]]*[qQ]([^[:alnum:]\/]|$)/ ||
+         u ~ /[[:space:]]([0-9]+|\$)?[qQ]([[:space:];}]|$)/))       { print NR ": " raw; next }
+  }
+}
+AWKPROG
+
+offenders=0
+for f in "${PIPEFAIL_FILES[@]}"; do
+  [ "$(basename "$f")" = "$(basename "${BASH_SOURCE[0]}")" ] && continue
+  while IFS= read -r hit; do
+    offenders=$((offenders+1))
+    echo "  FAIL — ${f#"$ROOT"/}:${hit}" >&2
+  done < <(awk -f "$TMP/scan.awk" "$f")
+done
+if [ "$offenders" -eq 0 ]; then
+  ok "${#PIPEFAIL_FILES[@]} pipefail-enabled scripts, no pipeline whose reader can outrun its writer"
+else
+  bad "$offenders pipeline(s) above pipe into an early-exit reader under pipefail."
+  echo "       Read the value into a variable and match it in the shell (see" >&2
+  echo "       lsphp_info_has_parity_ext in scripts/entrypoint-lsphp.sh), or give the" >&2
+  echo "       reader the file directly. Neither is a pipeline, so there is no second" >&2
+  echo "       exit status for pipefail to prefer. A here-string also works, but it" >&2
+  echo "       spills to a temp file above a build-dependent size, so it is not the" >&2
+  echo "       right shape on a boot path." >&2
+fi
+
+## ---------------------------------------------------------------------------
+## 6. Equivalence. The helpers answer with `[[ ]]` and `${…}` what they used to
+##    answer with grep and awk, and "same patterns, different plumbing" is a
+##    claim that has to be checked rather than asserted — an anchored line match
+##    re-expressed as a glob is exactly where an off-by-one lives.
+##
+##    The reference runs the ORIGINAL grep/awk patterns over a FILE, so the
+##    reference itself cannot SIGPIPE and cannot be accused of the bug it is
+##    refereeing. The file is written the way the old pipeline fed them,
+##    `printf '%s\n' "$SUBJECT"`, so the comparison is against the pre-fix
+##    behaviour byte for byte and not against a tidier reading of it.
+## ---------------------------------------------------------------------------
+echo "== pure-bash matching vs the grep/awk patterns it replaced =="
+if [ "$HAVE_HELPERS" = no ]; then
+  echo "  (skipped — no probe helpers to compare)"
+else
+  # shellcheck disable=SC1091
+  source "$TMP/helpers.sh"
+
+  NL=$'\n'
+  eq_fail=0
+  eq_case() {   # $1 = label, $2 = subject
+    local label="$1" subj="$2" f="$TMP/eq.txt"
+    local ref_has ref_use new_has new_use ref_scan new_scan
+    printf '%s\n' "$subj" > "$f"
+
+    ref_has=0; grep -q '^cac_path_parity support => enabled$' "$f" || ref_has=$?
+    new_has=0; lsphp_info_has_parity_ext "$subj"                   || new_has=$?
+    ref_use=0; grep -q '^PHP Version => ' "$f"                     || ref_use=$?
+    new_use=0; lsphp_info_is_usable "$subj"                        || new_use=$?
+    ref_scan=$(awk -F'=> ' '/^Scan this dir/ {print $2; exit}' "$f")
+    new_scan=$(lsphp_info_scan_dir "$subj")
+
+    if [ "$ref_has" = "$new_has" ] && [ "$ref_use" = "$new_use" ] && [ "$ref_scan" = "$new_scan" ]; then
+      ok "equivalent on: $label"
+    else
+      eq_fail=$((eq_fail+1))
+      bad "NOT equivalent on: $label — has_ext grep=$ref_has bash=$new_has; usable grep=$ref_use bash=$new_use; scan_dir awk='$ref_scan' bash='$new_scan'"
+    fi
+  }
+
+  SD='Scan this dir for additional .ini files'
+  PARITY='cac_path_parity support => enabled'
+  eq_case "empty subject"                 ""
+  eq_case "match on the first line"       "${PARITY}${NL}tail line"
+  eq_case "match on the last line"        "head line${NL}${PARITY}"
+  eq_case "match is the only line"        "${PARITY}"
+  eq_case "match sandwiched"              "a${NL}${PARITY}${NL}b"
+  eq_case "not at line start (decoy)"     "x ${PARITY}${NL}b"
+  eq_case "trailing space defeats the \$" "${PARITY} ${NL}b"
+  eq_case "prefix-only line (decoy)"      "cac_path_parity support => enabled but no${NL}b"
+  eq_case "genuinely absent"              "a${NL}b${NL}c"
+  eq_case "embedded blank lines"          "a${NL}${NL}${PARITY}${NL}${NL}b"
+  eq_case "banner first, scan dir second" "PHP Version => 8.3.27${NL}${SD} => /a/b"
+  eq_case "scan dir on the first line"    "${SD} => /a/b${NL}PHP Version => 8.3.27"
+  eq_case "scan dir on the last line"     "PHP Version => 8.3.27${NL}${SD} => /a/b"
+  eq_case "scan dir, second separator"    "${SD} => /a => /b${NL}x"
+  eq_case "scan dir, empty value"         "${SD} => ${NL}x"
+  eq_case "scan dir, no separator"        "Scan this dir is broken${NL}x"
+  eq_case "scan dir, first of two wins"   "${SD} => /first${NL}${SD} => /second"
+  eq_case "scan dir, value has spaces"    "${SD} =>  /a b/c ${NL}x"
+  eq_case "scan-dir line is a prefix"     "Scan this directory => /a/b${NL}x"
+  eq_case "banner not at line start"      "x PHP Version => 8.3.27${NL}b"
+  eq_case "banner without trailing space" "PHP Version =>${NL}b"
+  eq_case "CR-terminated lines"           $'PHP Version => 8.3.27\r'"${NL}${PARITY}"$'\r'
+  eq_case "glob metacharacters in body"   "*${NL}?${NL}[a-z]${NL}${PARITY}${NL}]["
+  eq_case "realistic 40 KB body"          "$(cat "$TMP/info-present.txt")"
+  [ "$eq_fail" -eq 0 ] || echo "  (an inequivalence here means the shipped probe now answers something the old grep/awk did not)" >&2
+fi
+
+## ---------------------------------------------------------------------------
+## 7. The scan's own coverage. Section 5 only proves something if its regexes
+##    actually match the shapes it claims to outlaw — an unfalsified scanner
+##    reports "clean" just as loudly when it has stopped matching anything.
+##    `grep -l foo` and `sed q` were both silently missed until this section
+##    existed; both are asserted below, alongside the safe forms that must NOT
+##    be reported, because a scanner that flags everything is no better.
+## ---------------------------------------------------------------------------
+echo "== the structural scan catches what it claims to =="
+cat > "$TMP/scan-bad.sh" <<'BADSH'
+set -euo pipefail
+a() { producer | grep -q needle; }
+b() { producer | grep -qx needle; }
+c() { producer | grep -m1 needle; }
+d() { producer | grep -im1 needle; }
+e() { producer | grep -l foo; }
+f() { producer | grep -L foo; }
+g() { producer | grep --quiet foo; }
+h() { producer | grep --files-with-matches foo; }
+i() { producer | head -1; }
+j() { producer | head; }
+k() { producer | read -r x; }
+l() { producer | while read -r x; do :; done; }
+m() { producer | awk '/x/ {print; exit}'; }
+n() { producer | sed q; }
+o() { producer | sed 'q'; }
+p() { producer | sed 2q; }
+q() { producer | sed -n '1p;q'; }
+r() { producer | sed -n '/x/{p;q}'; }
+s() { producer | sed '$q'; }
+BADSH
+cat > "$TMP/scan-good.sh" <<'GOODSH'
+set -euo pipefail
+a() { producer | grep -c needle; }
+b() { producer | grep -i needle; }
+c() { producer | grep -v needle; }
+d() { producer | grep -o needle; }
+e() { producer | awk '{print $1}'; }
+f() { producer | sed -n 's/^K=//p'; }
+g() { producer | sed 's/a/q/'; }
+h() { producer | sed -e 'y/abc/xqz/'; }
+i() { producer | wc -l; }
+j() { producer | sort -u; }
+k() { producer | tail -1; }
+l() { case $x in a|b) : ;; esac; }
+m() { echo "a | head -1"; }
+n() { echo 'x | grep -q y'; }
+o() { grep -q needle <<<"$1"; }
+p() { grep -q needle "$file"; }
+# q() { producer | grep -q commented-out; }
+r() { producer | grep -eq foo; }
+GOODSH
+missed=""; falsely=""; hits_bad=""
+while IFS= read -r line; do
+  fn=${line#*: }; fn=${fn%%(*}
+  hits_bad="$hits_bad $fn"
+done < <(awk -f "$TMP/scan.awk" "$TMP/scan-bad.sh")
+for want in a b c d e f g h i j k l m n o p q r s; do
+  case " ${hits_bad:-} " in *" $want "*) ;; *) missed="$missed $want" ;; esac
+done
+mapfile -t good_hits < <(awk -f "$TMP/scan.awk" "$TMP/scan-good.sh")
+if [ -z "$missed" ]; then
+  ok "all 19 early-exit reader shapes are reported (incl. grep -l/-L/--quiet and bare 'sed q')"
+else
+  bad "the scan misses these shapes in scan-bad.sh:$missed"
+  awk -f "$TMP/scan.awk" "$TMP/scan-bad.sh" >&2
+fi
+if [ "${#good_hits[@]}" -eq 0 ]; then
+  ok "18 read-to-EOF / quoted / non-pipeline forms are not reported"
+else
+  falsely=$(printf '%s; ' "${good_hits[@]}")
+  bad "the scan false-positives on: $falsely"
+fi
+
+echo
+echo "passed: $pass   failed: $fail"
+[ "$fail" -eq 0 ] || exit 1
+exit 0