fix(mutmut): switch container to :ro repo mount + tmpfs scratch dir

v1.1 item B from the 2026-05-18 pre-release sweep — closes the

host-tree-corruption hazard that nearly shipped a live mutation

to git on 2026-05-18 (caught at stage time).

## Problem

Prior layout: -v "$REPO_ROOT:/work" (read-write bind mount).

Every mutation mutmut applied was a real write to the HOST

filesystem under /c/Users/PC/wl_manager/. When mutmut died

between mutate-and-restore (SIGKILL, container stop, host reboot),

the source file stayed in mutated state and `git diff` showed it

as a normal edit. The 2026-05-18 session caught a live

`_csv_file_hash → None` mutation about to be staged in Phase 2 —

would have silently broken CSV-hash bootstrapping if missed.

## Fix

Two-mount layout:

  /repo    — host repo, READ-ONLY (`:ro` bind mount).

             mutmut cannot write here at all.

  /scratch — tmpfs (in-RAM, 512 MiB cap). Populated from /repo

             at container creation via 'cp -a /repo/. /scratch/'.

             mutmut runs with WORKDIR=/scratch and mutates the

             tmpfs copy. Host /repo is untouchable.

Helper functions added to scripts/mutmut.sh:

  - populate_scratch()  — copies /repo into /scratch as root

  - scratch_is_empty()  — detects tmpfs wipe after container

                          stop/start cycles, triggers re-populate

Source-refresh semantics: 'scripts/mutmut.sh kill' then re-run.

The fresh container repopulates /scratch from current /repo. The

tmpfs is intentionally not refreshed on every 'run' invocation —

that would invalidate mutmut's incremental cache (keyed on source

file timestamps) and lose the cross-run speedup.

## Verification

Verified end-to-end:

  1. Mount inspect: /c/Users/PC/wl_manager -> /repo, rw=false

  2. Tmpfs config: {"/scratch":"size=536870912"} (512 MiB cap)

  3. /scratch/bin/ contains the wl_*.py module copies

  4. Deliberate write attempt to /repo/bin/wl_validation.py:

       'Read-only file system' (exit non-zero)

  5. Host file sha256 unchanged after fresh container creation

       (pre and post both c8553865...)

  6. pytest tests/unit/test_validation.py inside /scratch:

       33 passed (+1 vs host because Linux symlink test runs;

       Windows host skips it)

## Doc update

docs/MUTATION_TESTING.md "Recommended improvements" marks item 2

(volume mount switch) CLOSED with the verification evidence above.

Open list renumbers 2->1, 3->2, 4->3 (markdownlint ordered-list

rule).

doc-drift: OK (33 docs against build 660).

Author: RelativisticJet

docs/MUTATION_TESTING.md

@@ -209,25 +209,28 @@ queued as v1.1 maintenance work.
    doc. Escape hatch: explicit `TEST_RUNNER_FILES` env var still
    overrides auto-derivation.
 
-### Open (queued for v1.1 release prep)
+2. ~~**Switch the volume mount to read-only.**~~ — DONE. The host
+   repo is now mounted at `/repo` as `:ro`; a 512 MiB tmpfs is
+   mounted at `/scratch` and populated from `/repo` at container
+   creation. mutmut runs with `WORKDIR=/scratch` and mutates the
+   tmpfs copy only — the host tree is unreachable from inside the
+   container. Verified: a deliberate write attempt to
+   `/repo/bin/wl_validation.py` fails with "Read-only file system";
+   host file sha256 unchanged after a fresh container creation.
+   Source-refresh signal: `scripts/mutmut.sh kill` then re-run (the
+   tmpfs is repopulated from `/repo` only on container creation).
 
-1. **Switch the volume mount to read-only.** Replace
-   `-v "$REPO_ROOT:/work"` with `-v "$REPO_ROOT:/work:ro"` and have
-   mutmut use a tmpfs (or container-local) scratch dir for its
-   mutations. This removes the host-tree-corruption hazard entirely.
-   Mutmut's internal cache lives in `mutants/.mutmut-cache` and can
-   stay on a separate writable volume. Estimated effort: 1 hour
-   (test the cache-survives-restart property).
+### Open (queued for v1.1 release prep)
 
-2. **Re-run wl_validation with the correct selector** to get a
+1. **Re-run wl_validation with the correct selector** to get a
    fresh survivor count after the 2 new tests above. Expected
    result: ≤8 survivors (the equivalent mutants), down from 12.
 
-3. **Run wl_csv.py with the correct selector**. Expected: real
+2. **Run wl_csv.py with the correct selector**. Expected: real
    survivor count, plausibly 5-20 genuine gaps in CSV diff /
    hash-registry logic.
 
-4. **Add `bin/wl_audit.py` mutation pass.** The 37 reported survivors
+3. **Add `bin/wl_audit.py` mutation pass.** The 37 reported survivors
    on `wl_audit.py` from a prior session need the same re-validation
    under the correct selector before deciding what to do with them.
 

scripts/mutmut.sh

@@ -52,6 +52,35 @@
 # is named `wl_manager_mutmut` and stays up between commands;
 # `scripts/mutmut.sh kill` tears it down when you're done.
 #
+# Host-tree safety: :ro mount + tmpfs scratch
+# -------------------------------------------
+#
+# Prior versions of this script mounted `$REPO_ROOT` at `/work` as
+# read-write. Every mutation mutmut applied was a real write to
+# the host filesystem. If mutmut was killed between mutate-and-
+# restore (SIGKILL, container stop, host reboot), the source file
+# stayed in mutated state and `git diff` showed it as a normal
+# edit. The 2026-05-18 session caught a live `_csv_file_hash → None`
+# mutation about to be staged — host-mount + interrupted mutmut
+# is a real foot-gun.
+#
+# Current layout: host repo is mounted READ-ONLY at /repo. A
+# tmpfs (in-RAM, ephemeral) is mounted at /scratch. At container
+# creation, /repo is copied into /scratch. mutmut runs WITH
+# /scratch as CWD and mutates /scratch/bin/*.py — the host /repo
+# is never written to.
+#
+# Implications:
+#   - To pick up source changes from the host, `scripts/mutmut.sh kill`
+#     and then re-run. The fresh container will copy current /repo
+#     into a fresh tmpfs. Editing host source between runs without
+#     `kill` is intentionally invisible to the mutator.
+#   - The mutmut cache (mutants/.mutmut-cache + .pytest_cache) lives
+#     in /scratch and persists across `start/stop` of the same
+#     container, but disappears on `kill` (container removal).
+#   - tmpfs default cap is 512 MiB (--tmpfs-size). Plenty for the
+#     ~10 MB working repo plus mutmut's tracking dirs.
+#
 # What gets mutated
 # -----------------
 #
@@ -199,25 +228,68 @@ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 # Posix path conversion for Windows Git Bash
 export MSYS_NO_PATHCONV=1
 
+populate_scratch() {
+    # Copy /repo into /scratch. /scratch is the tmpfs mutation surface;
+    # /repo is the read-only host mount. mutmut mutates /scratch only,
+    # so the host tree is never written to.
+    #
+    # We use `cp -a /repo/. /scratch/` (trailing dot+slash) to copy
+    # the CONTENTS of /repo into /scratch, not the /repo directory
+    # itself. The -a preserves mode/ownership/timestamps — important
+    # because mutmut keys its cache on source file timestamps.
+    #
+    # Running as -u 0 (root) inside the container because /scratch is
+    # owned by root after tmpfs mount; the default container user
+    # cannot write to a fresh root-owned mount.
+    echo "→ populating /scratch from /repo (tmpfs is fresh)..."
+    if ! docker exec -u 0 "$CONTAINER" sh -c 'cp -a /repo/. /scratch/'; then
+        echo "✖ scratch population failed — removing container." >&2
+        docker rm -f "$CONTAINER" >/dev/null
+        exit 1
+    fi
+}
+
+scratch_is_empty() {
+    # Quick check whether /scratch needs (re-)populating. We check for
+    # the presence of bin/ — a fresh tmpfs has no bin/ until populate
+    # runs. This lets us repopulate after `docker start` of a stopped
+    # container (tmpfs is wiped on container stop/start cycles).
+    ! docker exec "$CONTAINER" sh -c 'test -d /scratch/bin'
+}
+
 ensure_container() {
     if docker inspect "$CONTAINER" >/dev/null 2>&1; then
         # Container exists. Make sure it's running.
         if [ "$(docker inspect -f '{{.State.Running}}' "$CONTAINER")" != "true" ]; then
             docker start "$CONTAINER" >/dev/null
         fi
+        # tmpfs is wiped on container stop/start, so we may need to
+        # repopulate even on an existing container.
+        if scratch_is_empty; then
+            populate_scratch
+        fi
         return
     fi
     echo "→ creating mutmut container ($IMAGE)..."
+    # Mount layout:
+    #   /repo    — host repo, READ-ONLY. mutmut never writes here.
+    #   /scratch — tmpfs (in-RAM), 512 MiB cap. Copied from /repo
+    #              at startup; mutmut mutates files here.
+    #   -w /scratch — CWD so relative paths (bin/wl_X.py, tests/...)
+    #              resolve into the writable copy.
     docker run -d --name "$CONTAINER" \
-        -v "$REPO_ROOT:/work" \
-        -w /work \
+        -v "$REPO_ROOT:/repo:ro" \
+        --tmpfs /scratch:size=536870912 \
+        -w /scratch \
         --entrypoint sleep \
         "$IMAGE" infinity >/dev/null
 
     echo "→ installing deps..."
     # We DON'T use --quiet here so failures are visible. mutmut
     # 2.4.4 is the last 2.x release before 3.x rewrote the API
     # incompatibly; we pin it to keep the harness stable.
+    # pip installs into the container's writable layer (NOT /scratch),
+    # so deps survive tmpfs wipes across container start/stop.
     if ! docker exec "$CONTAINER" pip install \
             mutmut==2.4.4 \
             pytest==9.0.3 \
@@ -228,6 +300,8 @@ ensure_container() {
         docker rm -f "$CONTAINER" >/dev/null
         exit 1
     fi
+
+    populate_scratch
 }
 
 cmd_run() {