test: centralize the GNU-vs-BSD stat trap; close a hermetic-isolation gap

CHANGELOG.md

@@ -188,6 +188,30 @@ the arm compares normally. When an arm is still refused, the root carries `reaso
 debug trace. Both `ok=` postures and `reason=` are defined in the legend. Gates:
 `test/scoutheadconflictcheck.sh` arms T9(a)–(e), `test/mergescoutcheck.sh`. (CodeRabbit review on #295)
 
+### Fixed — sixteen gates now share one GNU/BSD `stat` compat helper instead of a per-gate copy
+
+`stat -f` is GNU coreutils' filesystem-stat flag, not BSD's format-string flag, so it succeeds with junk
+instead of failing — a caller-local `stat -f ... || stat -c ...` one-liner never reaches its own fallback on
+Linux. Sixteen gates each hand-rolled the same detect-once-and-redefine fix independently:
+`cachehashcheck.sh`, `cachesplitcheck.sh`, `clonecachecheck.sh`, `codexpromptroutecheck.sh`,
+`evictioncheck.sh`, `g1freshcheck.sh`, `headsnapcachecheck.sh`, `mcpeditmodecheck.sh`,
+`portablecachecheck.sh`, `prcontextcheck.sh`, `qsnapcachecheck.sh`, `qsnapprefetchcheck.sh`,
+`statgatecheck.sh`, `cacheisolationcheck.sh`, `qsnapproducercheck.sh`, `sidecarsymlinkcheck.sh` and
+`tempfilesymlinkcheck.sh` all now source the new shared `test/lib/statcompat.sh` instead — one place defines
+the GNU-vs-BSD `stat` compat logic, not seventeen.
+
+### Fixed — a gate that varies `HOME=` per invocation could still leak into an ambiently-set agent-home variable
+
+`CODEX_HOME`/`AGENTS_HOME`/`HERMES_HOME`/`CLAUDE_CONFIG_DIR`/`RIPWIRE_DATA_HOME` override the default an
+agent's tools derive from `HOME`, so a gate that only sets `HOME=` per invocation is not actually sandboxed
+on a machine where any of these is already exported ambiently. `codexpromptroutecheck.sh`,
+`claudeconfigdircheck.sh`, `skillinstallcheck.sh` and `hermesinstallcheck.sh` now source the new shared
+`test/lib/clean-env.sh` before varying `HOME=`, closing that leak in each. `claudeconfigdircheck.sh` — the
+gate that exists specifically to test `CLAUDE_CONFIG_DIR` relocation — was the one this hit hardest: with
+`CLAUDE_CONFIG_DIR` exported ambiently (a developer whose real Claude Code config is relocated, exactly the
+case this gate tests for), its "unset" baseline arm wrote real files into that directory and then failed
+comparing against its own contaminated baseline.
+
 ### Fixed — an ambiguous `--expand` buried its body behind the ranked map, and the escape hatch was stderr-only
 
 Reported by @mariadb-KyleHutchinson in #289: `--expand=SYM` on a name matching more than one definition, in a

test/cachehashcheck.sh

@@ -42,6 +42,7 @@
 
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"          # allow a repo-relative RIPWIRE_BIN
 TMP="$( mktemp -d )"; trap 'rm -rf "$TMP"' EXIT
@@ -94,18 +95,6 @@ touch -r "$TMP/f.cpp.ref" "$WORK/f.cpp"
 touch -r "$DIR_REF" "$WORK" 2>/dev/null || true
 
 # Confirm the mtime restore actually worked (sanity on the attack itself, not the tool under test).
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then   # GNU coreutils
-    mtime_of(){ stat -c '%Y'  "$1" 2>/dev/null; }
-else                                     # BSD / macOS
-    mtime_of(){ stat -f '%m' "$1" 2>/dev/null; }
-fi
 ref_mtime="$( mtime_of "$TMP/f.cpp.ref" )"
 new_mtime="$( mtime_of "$WORK/f.cpp" )"
 if [ "$ref_mtime" = "$new_mtime" ]; then

test/cacheisolationcheck.sh

@@ -3,6 +3,7 @@
 set -u
 
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 fail=0
@@ -30,7 +31,7 @@ PRIVATE="$SHARED/ripwire"
 if [ -d "$PRIVATE" ]; then ok "creates a dedicated TMPDIR/ripwire directory"; else no "missing private directory: $PRIVATE"; fi
 
 if [ -d "$PRIVATE" ]; then
-    if stat --version >/dev/null 2>&1; then mode="$( stat -c %a "$PRIVATE" )"; else mode="$( stat -f %Lp "$PRIVATE" )"; fi
+    mode="$( mode_of "$PRIVATE" )"
     if [ "$mode" = "700" ]; then ok "private directory mode is 0700"; else no "private directory mode is $mode, expected 700"; fi
 fi
 

test/cachesplitcheck.sh

@@ -29,6 +29,7 @@
 
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"          # allow a repo-relative RIPWIRE_BIN
 TMP="$( mktemp -d )"; trap 'rm -rf "$TMP"' EXIT
@@ -46,16 +47,6 @@ CORPUS="$ROOT/test/fixture"
 XDG="$TMP/xdg"; mkdir -p "$XDG"
 CACHEDIR="$XDG/ripwire"
 
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then inode_of(){ stat -c %i "$1" 2>/dev/null; }   # GNU coreutils
-else                                    inode_of(){ stat -f %i "$1" 2>/dev/null; }   # BSD / macOS
-fi
 # glob helper: echo the single matching class file (or empty). Y4: shard-aware lookup — a blob may
 # live flat under $CACHEDIR or under $CACHEDIR/<xx>/ (2-hex-char shard), so search both via find -maxdepth 2.
 richfile(){ find "$CACHEDIR" -maxdepth 2 -type f -name 'ripwire-*-rich.bin' 2>/dev/null | head -1; }

test/claudeconfigdircheck.sh

@@ -43,6 +43,7 @@
 # otherwise fall back to it. Exits non-zero on any failure. Does NOT edit regression.sh.
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/clean-env.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 fail=0

test/clonecachecheck.sh

@@ -29,6 +29,7 @@
 
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 TMP="$( mktemp -d )"; trap 'rm -rf "$TMP"' EXIT
@@ -66,21 +67,6 @@ FIVE_DAYS_AGO=$(( $(date +%s) - 5*86400 ))
 touch -t "$(date -r "$FIVE_DAYS_AGO" +%Y%m%d%H%M.%S 2>/dev/null || date -d "@$FIVE_DAYS_AGO" +%Y%m%d%H%M.%S)" "$CACHEDIR" 2>/dev/null \
     || touch -d "@$FIVE_DAYS_AGO" "$CACHEDIR" 2>/dev/null
 
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then   # GNU coreutils
-    mtime_of(){ stat -c '%Y'  "$1" 2>/dev/null; }
-    mode_of(){  stat -c '%a'  "$1" 2>/dev/null; }
-else                                     # BSD / macOS
-    mtime_of(){ stat -f '%m'  "$1" 2>/dev/null; }
-    mode_of(){  stat -f '%Lp' "$1" 2>/dev/null; }
-fi
-
 BEFORE_MTIME="$( mtime_of "$CACHEDIR" )"
 
 env -u TMPDIR XDG_CACHE_HOME="$XDG" "$BIN" "$URL" >"$TMP/a_stdout" 2>"$TMP/a_stderr"

test/codexpromptroutecheck.sh

@@ -4,6 +4,7 @@
 # and length, never prompt text, and hook installation stays idempotent.
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/clean-env.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 HOOK="$ROOT/hooks/ripwire-codex-route.sh"
@@ -137,9 +138,9 @@ OFF="$( printf '%s\n' "{\"prompt\":\"$PROMPT\",\"cwd\":\"$TMP/repo\",\"session_i
     && ok "routing-meter opt-out keeps advice but writes no log or pending state" \
     || no "routing-meter opt-out suppressed advice or wrote state"
 
-HOME="$TMP/home" CODEX_HOME="$TMP/home/.codex" AGENTS_HOME="$TMP/home/.agents" \
+HOME="$TMP/home" CODEX_HOME="$TMP/home/.codex" AGENTS_HOME="$TMP/home/.agents" RIPWIRE_DATA_HOME="$TMP/home/.local/share/ripwire" \
     bash "$ROOT/skills/install.sh" --codex --hook >/dev/null
-HOME="$TMP/home" CODEX_HOME="$TMP/home/.codex" AGENTS_HOME="$TMP/home/.agents" \
+HOME="$TMP/home" CODEX_HOME="$TMP/home/.codex" AGENTS_HOME="$TMP/home/.agents" RIPWIRE_DATA_HOME="$TMP/home/.local/share/ripwire" \
     bash "$ROOT/skills/install.sh" --codex --hook >/dev/null
 SETTINGS="$TMP/home/.codex/hooks.json"
 jq -e --arg cmd "$HOOK" '[.hooks.UserPromptSubmit[]?.hooks[]? | select(.command == $cmd)] | length == 1' "$SETTINGS" >/dev/null 2>&1 \

test/evictioncheck.sh

@@ -48,6 +48,7 @@
 # Usage:  test/evictioncheck.sh   |   RIPWIRE_BIN=build_r2a1/ripwire test/evictioncheck.sh
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 fail=0
@@ -63,16 +64,7 @@ REPO="$TMP/repo"; mkdir -p "$REPO"
 
 # apparent (logical) byte size of a file — what fs::file_size measures, NOT `du`'s block-usage view
 # (a sparse file's disk usage is ~0 but its apparent size is what the sweep's byte budget compares against).
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then apparentsize(){ stat -c %s "$1" 2>/dev/null || echo 0; }   # GNU coreutils
-else                                    apparentsize(){ stat -f %z "$1" 2>/dev/null || echo 0; }   # BSD / macOS
-fi
+apparentsize(){ size_of "$1" || echo 0; }
 # Y4: shard-aware — every blob glob below now looks at both the flat top-level AND any 2-hex-char shard
 # subdir (mindepth/maxdepth bound it to exactly the layouts the sweep itself understands; never an
 # open-ended walk of a shared $TMPDIR).

test/g1freshcheck.sh

@@ -18,6 +18,7 @@
 
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 ASAN_BIN="$ROOT/asan/ripwire"
 ASAN_DIR="$ROOT/asan"
 SRC_DIR="$ROOT/src"
@@ -46,19 +47,6 @@ if [ ! -f "$ASAN_BIN" ]; then
 fi
 
 # Both asan/ripwire and src/ exist. Check if the binary is older than the newest src file.
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then   # GNU coreutils
-    mtime_of(){ stat -c '%Y' "$1" 2>/dev/null; }
-else                                     # BSD / macOS
-    mtime_of(){ stat -f '%m' "$1" 2>/dev/null; }
-fi
-
 asan_mtime="$( mtime_of "$ASAN_BIN" )" || {
     no "could not stat asan/ripwire"
     exit 1

test/headsnapcachecheck.sh

@@ -28,6 +28,7 @@
 # Usage:  test/headsnapcachecheck.sh   |   RIPWIRE_BIN=build_w2e/ripwire test/headsnapcachecheck.sh
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 fail=0
@@ -41,16 +42,6 @@ REPO="$( mktemp -d )"; TMP="$( mktemp -d )"; trap 'rm -rf "$REPO" "$TMP"' EXIT
 XDG="$TMP/xdg"; mkdir -p "$XDG"
 CACHEDIR="$XDG/ripwire"
 
-# L3 (Linux probe): portable stat reader(s). GNU coreutils and BSD/macOS disagree on both the flag and the
-# format directives, and the `stat -f FMT ... || stat -c FMT ...` fallback this gate used is a TRAP. On GNU,
-# `-f` means FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on
-# coreutils 9.11, `stat -f %i FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1. The
-# `||` arm then appends the right number under six lines of junk -- so a string compare fails, a numeric
-# compare dies with "integer expression expected", and a `|| echo MISSING` variant reports MISSING forever
-# (a gate that then passes by comparing nothing to nothing). Detect the flavour ONCE, use one form.
-if stat --version >/dev/null 2>&1; then inode_of(){ stat -c %i "$1" 2>/dev/null; }   # GNU coreutils
-else                                    inode_of(){ stat -f %i "$1" 2>/dev/null; }   # BSD / macOS
-fi
 # Y4: shard-aware lookup — a blob may be flat under $CACHEDIR or under $CACHEDIR/<xx>/ (2-hex shard).
 snapfiles(){ find "$CACHEDIR" -maxdepth 2 -type f -name 'ripwire-qheadsnap-*.bin' 2>/dev/null; }
 nsnap(){ snapfiles | wc -l | tr -d ' '; }

test/hermesinstallcheck.sh

@@ -13,6 +13,7 @@
 # Exits non-zero on any failure. Does NOT edit regression.sh.
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/clean-env.sh"
 SK="$ROOT/skills"
 fail=0
 ok(){ echo "  PASS  $1" || { fail=1; echo "  FAIL  could not write the PASS line for: $1"; }; return 0; }

test/lib/clean-env.sh

@@ -0,0 +1,6 @@
+# clean-env.sh — the agent-home-relocating env vars a gate must clear before it varies HOME= per
+# invocation: CODEX_HOME/AGENTS_HOME/HERMES_HOME/CLAUDE_CONFIG_DIR/RIPWIRE_DATA_HOME override the
+# default derived from HOME, so a gate that only sets HOME= is not sandboxed on a machine where any of
+# these is already exported ambiently. SOURCED, not run. Source this FIRST, then set whatever homes
+# the gate actually needs.
+unset CODEX_HOME AGENTS_HOME HERMES_HOME CLAUDE_CONFIG_DIR RIPWIRE_DATA_HOME

test/lib/statcompat.sh

@@ -0,0 +1,20 @@
+# statcompat.sh — GNU-vs-BSD `stat` compat, in one place. SOURCED, not run.
+#
+# GNU coreutils' `-f` is a different, valid flag (filesystem stat, not BSD's format string): it
+# succeeds with junk instead of failing, so a caller-local `stat -f ... || stat -c ...` one-liner never
+# reaches its own fallback on Linux. Twelve gates hand-rolled that same detect-once-and-redefine fix
+# independently before this file existed. Sourcing this gives every one of them a ready-to-call
+# function; no caller branches on the flavour itself.
+if stat --version >/dev/null 2>&1; then   # GNU coreutils
+    mtime_of()        { stat -c '%Y'    "$1" 2>/dev/null; }
+    inode_of()        { stat -c '%i'    "$1" 2>/dev/null; }
+    mode_of()         { stat -c '%a'    "$1" 2>/dev/null; }
+    size_of()         { stat -c '%s'    "$1" 2>/dev/null; }
+    inode_mtime_of()  { stat -c '%i %Y' "$1" 2>/dev/null; }
+else                                       # BSD / macOS
+    mtime_of()        { stat -f '%m'    "$1" 2>/dev/null; }
+    inode_of()        { stat -f '%i'    "$1" 2>/dev/null; }
+    mode_of()         { stat -f '%Lp'   "$1" 2>/dev/null; }
+    size_of()         { stat -f '%z'    "$1" 2>/dev/null; }
+    inode_mtime_of()  { stat -f '%i %m' "$1" 2>/dev/null; }
+fi

test/mcpeditmodecheck.sh

@@ -18,6 +18,7 @@
 
 set -u
 ROOT="$( cd "$( dirname "$0" )/.." && pwd )"
+. "$ROOT/test/lib/statcompat.sh"
 BIN="${1:-${RIPWIRE_BIN:-$ROOT/build/ripwire}}"
 [ "${BIN#/}" = "$BIN" ] && BIN="$ROOT/$BIN"
 TMP="$( mktemp -d )"; trap 'rm -rf "$TMP"' EXIT
@@ -30,18 +31,6 @@ no(){ printf '  FAIL  %s\n' "$*"; fail=1; }
 
 echo "mcpeditmodecheck: BIN=$BIN"
 
-# portable "octal mode of a file" (BSD/macOS stat -f vs GNU stat -c).
-# L3 (Linux probe): the `stat -f FMT ... || stat -c FMT ...` fallback this used is a TRAP. On GNU, `-f` means
-# FILESYSTEM status and takes NO format argument, so FMT is parsed as a second FILE: measured on coreutils
-# 9.11, `stat -f '%Lp' FILE` PRINTS a six-line filesystem block for FILE on stdout and exits 1, so the `||`
-# arm appends the right mode under six lines of junk and `[ "$PERM" = "700" ]` can never hold. Detect the
-# flavour ONCE, use one form.
-file_mode(){
-    if stat --version >/dev/null 2>&1; then stat -c '%a'  "$1" 2>/dev/null   # GNU coreutils
-    else                                   stat -f '%Lp' "$1" 2>/dev/null   # BSD / macOS
-    fi
-}
-
 # drive one replace_symbol_body call through the MCP server (spec-conforming params.arguments form),
 # echo the tools/call response line.
 mcp_replace(){ # $1=dir  $2=symbol  $3=new_body
@@ -64,11 +53,11 @@ int run_tool( int x )
 }
 CPP
 chmod 0755 "$W1/exec.cpp"
-BEFORE_MODE="$( file_mode "$W1/exec.cpp" )"
+BEFORE_MODE="$( mode_of "$W1/exec.cpp" )"
 [ "$BEFORE_MODE" = "755" ] || { echo "  (setup) could not set fixture mode to 0755 (got $BEFORE_MODE)"; }
 
 R1="$( mcp_replace "$W1" run_tool 'int run_tool( int x )\n{\n    return x + 2;\n}' )"
-AFTER_MODE="$( file_mode "$W1/exec.cpp" )"
+AFTER_MODE="$( mode_of "$W1/exec.cpp" )"
 
 case "$R1" in
     *applied*) : ;;