chore: pin the shared-memory project key

Ties every collaborator's Claude Code to the same shared-memory project automatically, instead of each machine inferring a key from the directory name. Read by project.identify at session start. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merge branch 'fix/ols-watcher-scope'
2026-08-23 08:09:04 -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
27 changed files with 2584 additions and 46 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:
@@ -0,0 +1 @@
 cloud-hosting-platform/cloud-apache-container
@@ -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 && \
+        lsphp${PHPVER}="$V" lsphp${PHPVER}-common="$V" lsphp${PHPVER}-ldap="$V"; then \
-    apt-get clean && \
+        echo "FATAL: lsphp${PHPVER} $V is what cac_path_parity was compiled against," >&2; \
-    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
+        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/*
@@ -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
+  ## Values emitted double-quoted via printf rather than interpolated into an
-; rendered at container start by entrypoint-lsphp.sh
+  ## unquoted heredoc — see the INI_TOKENS_OK note above for what that prevents.
-error_log = /home/${user}/logs/php-fpm/error.log
+  ##
-log_errors = On
+  ## Gated on INI_TOKENS_OK for the same reason the mapping below is: this
-EOF
+  ## fragment interpolates $user into generated ini too. Leaving it ungated was
-  ## Normalise \$_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] from the OLS-sent
+  ## an INCONSISTENCY, not a live hole — a newline is inert inside the quotes,
-  ## /mnt/users path back to /home/<user> so cac-lsphp is byte-for-byte 1:1 with
+  ## and a `${`-bearing $user cannot exist because the useradd above would have
-  ## cac-fpm. Customer sites have no auto_prepend by default, so this is safe; a
+  ## failed under `set -euo pipefail`. But "this particular unvetted value
-  ## site that sets its own .user.ini auto_prepend overrides it (paths still
+  ## happens to be contained" is the reasoning this branch already rejected one
-  ## resolve via the symlink either way).
+  ## screenful up, so it is not the reasoning that guards this line either.
-  cat > "$SCAN_DIR/99-cac-lsphp-normalize.ini" <<'EOF'
+  ##
-; rendered at container start by entrypoint-lsphp.sh
+  ## 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 (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}"
+      printf '%s\n' "${OPCACHE_LINES[@]}"
      [ -n "${OPCACHE_MAX_FILES:-}" ]  && echo "opcache.max_accelerated_files = ${OPCACHE_MAX_FILES}"
    } > "$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
@@ -75,7 +75,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
+## -m monitor, -r recursive. We filter in the read loop rather than --include
-## --include so this works on older inotify-tools too. modify/create/delete/move
+## so this works on older inotify-tools too. modify/create/delete/move all
-## all matter (delete of .htaccess also changes rewrite behavior).
+## 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
+## --format '%w%f' (full path), NOT '%f' (basename only). OLS reads .htaccess
-  case "$fname" in
+## (RewriteFile) only from a vhost's DOCROOT — VHROOT, i.e.
-    .htaccess) ;;
+## /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.
+  ## ever slipped validation. meta_value treats them as plain data.
-  VHNAME=$(sed -n 's/^VHNAME=//p'  "$meta" | head -1)
+  VHNAME=$(meta_value VHNAME  "$meta")
-  VHROOT=$(sed -n 's/^VHROOT=//p'  "$meta" | head -1)
+  VHROOT=$(meta_value VHROOT  "$meta")
-  DOMAINS=$(sed -n 's/^DOMAINS=//p' "$meta" | head -1)
+  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
@@ -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
		`@@ -0,0 +1 @@`
							`cloud-hosting-platform/cloud-apache-container`