@soleur/opencode 0.0.0-stage → 3.354.2

package/scripts/ruff-requirements.txt

@@ -0,0 +1,22 @@
+# Pinned ruff for plugins/soleur/scripts/lint-ratchet.py (installed with pip --require-hashes --only-binary=:all:).
+# Bump recipe: take the version and one sha256 per wheel from https://pypi.org/pypi/ruff/<version>/json,
+# replace the pin and ALL hash lines below, then run: python3 plugins/soleur/scripts/lint-ratchet.py ruff --update
+# (a hash line carries no trailing comment: pip rejects a continuation followed by one).
+ruff==0.16.10 \
+    --hash=sha256:1dfc6f0088149fb6a362c1c446bcbb3fd2157b3852fe2fa68409276eab9ad9b3 \
+    --hash=sha256:25a65fe998c4e6861ec079ada5826a2fc605e6cbccbe9dcd7fac1f54e791621b \
+    --hash=sha256:2a12e01cb9156c10c466f63b46eaae5ecea28dfbd21b5836353ae498e7d1349a \
+    --hash=sha256:3031a4a2e8e7b8a46f70be45f198c35a11ece509a94b80334d8d397a33c67550 \
+    --hash=sha256:3e70175e29cc94c26ea296c80e470180b744b7419026898e58f520c6ab32578e \
+    --hash=sha256:488b0fe3f3574210e5cf80d9f59b9e3ab17a127a8155de3f307b392589cfb511 \
+    --hash=sha256:494401c86df4c4c25f69b9419605d944467ee98c42fb6ad405ef4fa40b8fb67d \
+    --hash=sha256:6553498afc35f580f036030795810b9e6bcea31604b0fd9e8d352795473042e3 \
+    --hash=sha256:7ae7375f803b5520dc9f546bed7e3a0acb70b91812e9bb4b19927de22f25b77d \
+    --hash=sha256:92e59a70bcbd9d3a5483656da906ec28edfdacfce00afd99edb8b4e9d15644be \
+    --hash=sha256:97f2015c92aa97105b0eab19eb5d224884399281cfc5da86a92db4ab5e7fb2ca \
+    --hash=sha256:a3b8471dea115d37f123882be852bed13403746d3a76c11de4a19ec5f9ff5a03 \
+    --hash=sha256:bc2610fb269fa56dd8a68669ae470fa6272902668c0fc2ebc3aa112b2633d5b8 \
+    --hash=sha256:bd83d1235a5258d318477bc5b576303974cbdef5df0c01a1bff14efcc23bd12a \
+    --hash=sha256:d203abc0ff2b773ee33d00ab8df0bb67046fbc7c07b119332f08b9b345cf8221 \
+    --hash=sha256:e748ff95c934c4e978783b8e687bc174e7bd84e8ad24e3243e1ecfcda5e0282d \
+    --hash=sha256:f33f43a864a8483eebd160e713336c8bab02c934feaff0a33cf5ccb41546d09a

package/scripts/run-in-pid-namespace.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# run-in-pid-namespace.sh [--] <command> [args...]
+#
+# Runs <command> as PID 1 of a fresh PID namespace (own /proc), via
+#   unshare -Urpf --kill-child --mount-proc
+# and REFUSES (rc 125, no unsandboxed fallback) when it cannot arrange that. Use it to run a
+# MUTANT of any helper that signals processes: a helper that walks $PPID upward and signals the
+# outermost ancestor whose argv matches is bounded only by its own match predicate, so a mutant
+# of that predicate (-v, a dropped pattern, a catch-all) walks to the top of the user's session
+# and ends it. Inside the namespace the command has no ancestor at all, so such a walk stops at
+# the command itself. The incident this exists for: see
+# knowledge-base/project/learnings/test-failures/2026-10-09-an-inverted-match-mutant-of-an-ancestor-walking-helper-ended-the-desktop-session-four-times.md
+#
+# Exit codes: the command's own code on success; 125 = refused (the command never started; the
+# FIRST stderr line is "RUN_IN_PID_NAMESPACE_REFUSED reason=<missing-unshare|userns-unavailable|
+# not-isolating> ..."; a wrapped command that itself exits 125 prints no such line, so a caller
+# tells them apart by the marker, not the code); 2 = usage error.
+#
+# Trust anchor: PATH. The probe and the run use one absolute unshare, but sh, awk and the other tools
+# resolve through the caller's PATH, so a caller who controls PATH controls them.
+#
+# What a PID namespace does NOT bound: filesystem writes (the mount namespace is created for
+# /proc only), network, IPC, abstract unix sockets, the D-Bus session bus, path-based sockets under XDG_RUNTIME_DIR (hyprctl,
+# tmux, sway/i3 IPC) and the session manager (loginctl terminate-session still reaches the host). The caller is mapped to uid 0
+# inside, so id -u and root-guard branches differ. The command is PID 1 there, so a signal it
+# sends ITSELF is ignored: bound a run with `timeout -k <grace> <secs> <this script> ...`, never
+# a plain `timeout`. A backgrounded child does not outlive the command (--kill-child).
+set -u
+
+readonly MARKER=RUN_IN_PID_NAMESPACE_REFUSED
+
+# Shared context-sanitize lib (#10395), beside this script under lib/. When it
+# is unreadable the same-name fallback carries this site's pre-change strip set
+# (C0+DEL) — never weaker than today.
+_ctx_lib="$(cd "${BASH_SOURCE[0]%/*}" 2>/dev/null && pwd -P)/lib/context-sanitize.sh"
+_ctx_lib="${_ctx_lib:-/nonexistent/context-sanitize.sh}"
+# shellcheck source=/dev/null
+[[ -r "$_ctx_lib" ]] && . "$_ctx_lib" || true
+declare -F soleur_ctx_sanitize >/dev/null 2>&1 \
+  || soleur_ctx_sanitize() { LC_ALL=C tr -d '\000-\037\177'; }
+
+[[ "${1:-}" == "--" ]] && shift
+if [[ $# -eq 0 ]]; then
+  printf 'usage: %s [--] <command> [args...]\n' "${0##*/}" >&2
+  exit 2
+fi
+# `exec` reads a leading dash as an option, and `exec --` is not portable (dash, the sh of Debian and
+# Ubuntu, rejects it), so a command word that begins with a dash is refused here, before anything
+# starts. A file whose name begins with a dash runs when given as a path (./-name).
+if [[ "$1" == -* ]]; then
+  printf '%s: the command must not begin with "-" (give a path such as ./%s)\n' "${0##*/}" "$1" >&2
+  exit 2
+fi
+
+# The isolation property, written ONCE and used by the probe and by the run: this shell is PID 1
+# and /proc is the namespace's own (NSpid has exactly one field; a wrapper that drops
+# --mount-proc keeps $$ at 1 but shows the host's process list, so $$ alone is not enough).
+# shellcheck disable=SC2016  # the single quotes are intentional: this text runs inside the namespace
+CHECK='[ "$$" = 1 ] && [ "$(awk "/^NSpid:/{print NF-1}" /proc/self/status 2>/dev/null)" = 1 ]'
+
+refuse() { # reason cause remedy
+  {
+    printf '%s reason=%s\n' "$MARKER" "$1"
+    printf 'cause: %s\n' "$2"
+    printf 'remedy: %s\n' "$3"
+    printf 'no unsandboxed fallback: run the mutant on a host that allows user namespaces, or do not run it.\n'
+  } >&2
+  exit 125
+}
+
+# Resolve unshare ONCE to an absolute path: `type -P` consults PATH only, so a shell function or alias
+# named unshare cannot decide the probe, a relative PATH entry is refused, and the probe and the run use
+# the same binary.
+u="$(type -P unshare 2>/dev/null || true)"
+if [[ -z "$u" || "$u" != /* ]]; then
+  refuse missing-unshare "unshare (util-linux) was not found on PATH as an absolute path" \
+    "use a Linux host with util-linux; stock macOS has no unshare, so use a Linux VM"
+fi
+
+probe_err="$("$u" -Urpf --kill-child --mount-proc -- sh -c "$CHECK || exit 97" 2>&1 >/dev/null)"
+probe_rc=$?
+if [[ "$probe_rc" -ne 0 ]]; then
+  # One line, control characters stripped, cut short: the text comes from whatever unshare is.
+  first="$(printf '%s\n' "$probe_err" | head -n 1 | soleur_ctx_sanitize | cut -c1-200)"
+  if [[ "$probe_rc" -eq 97 ]]; then
+    refuse not-isolating "the unshare on PATH ran the command without a fresh PID namespace and its own /proc (or awk or /proc/self/status was unusable inside it)" \
+      "check which unshare resolves first on PATH and that it is util-linux unshare"
+  fi
+  refuse userns-unavailable "unshare failed (rc $probe_rc): ${first:-no message}" \
+    "run the mutant on a disposable VM or container that allows unprivileged user namespaces; enabling them on a workstation (sysctl kernel.unprivileged_userns_clone, kernel.apparmor_restrict_unprivileged_userns, user.max_user_namespaces) or allowing unshare in a container seccomp profile weakens that host, so do it only on a throwaway host. On a restricted CI runner every seat on a signalling helper refuses until the runner relaxes the sysctl"
+fi
+
+# The same check runs again inside the namespace right before the command (it keeps the property
+# true at the instant of the exec even if the probe and this run disagreed). A plain `exec` (never
+# `exec --`, which dash rejects) leaves the command as PID 1 with no ancestor; a command word that
+# begins with a dash was refused above, so exec cannot read it as an option.
+RUN="$CHECK || { printf '%s\\n' '$MARKER reason=not-isolating (re-check inside the namespace failed)' >&2; exit 125; }; exec \"\$@\""
+exec "$u" -Urpf --kill-child --mount-proc -- sh -c "$RUN" sh "$@"

package/scripts/run-in-pid-namespace.test.sh

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# Tests for plugins/soleur/scripts/run-in-pid-namespace.sh: the helper that runs a command as PID 1 of
+# a fresh PID namespace and REFUSES (rc 125, marker line, command never started) when it cannot.
+#
+# Two kinds of rows. ALWAYS-RUN rows use a stub `unshare` on a private PATH, so the helper's logic is
+# proven on every host (CI shapes where user namespaces are restricted, macOS). REAL-NAMESPACE rows
+# need working user namespaces; one probe decides, and where they are unavailable they are COUNTED as
+# skipped (a SKIP line names how many and why) and the real helper's refusal is asserted instead (R8).
+# SOLEUR_REQUIRE_REAL_NS=1 turns "unavailable" into a FAIL.
+#
+# The containment row (N4) never runs a lethal walker: it uses a nonce-scoped fixture walker
+# (plugins/soleur/test/fixtures/ancestor-signal/walker-nonce.txt) that signals only ancestors whose
+# argv carries a per-run 32-hex nonce, so even a helper that regressed to run in place could only
+# reach the fixture's own `victim`.
+#
+# Run: bash plugins/soleur/scripts/run-in-pid-namespace.test.sh
+
+# shellcheck disable=SC2319  # check() deliberately consumes the status of the condition on the line above
+set -uo pipefail
+export TMPDIR="${TMPDIR:-/var/tmp}"
+unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR 2>/dev/null || true
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUT="$DIR/run-in-pid-namespace.sh"
+WALKER="$DIR/../test/fixtures/ancestor-signal/walker-nonce.txt"
+BASH_BIN="$(type -P bash)"
+
+FIX="$(mktemp -d -t runinns.XXXXXXXX)" || { echo "FATAL: mktemp failed" >&2; exit 2; }
+trap 'rm -rf "$FIX"' EXIT
+
+# shellcheck source=../test/test-helpers.sh
+source "$DIR/../test/test-helpers.sh" || { echo "FATAL: could not source test-helpers.sh" >&2; exit 2; }
+set +e -uo pipefail
+assert_fixture_dir "$FIX"
+[[ -f "$SUT" ]] || { printf '[FATAL] SUT missing at %s\n' "$SUT" >&2; exit 1; }
+[[ -f "$WALKER" ]] || { printf '[FATAL] walker fixture missing at %s\n' "$WALKER" >&2; exit 1; }
+
+passes=0; fails=0; cases=0; skipped=0
+FAILURES=()
+ok() { passes=$((passes + 1)); printf '  ok: %s\n' "$1"; }
+bad() { fails=$((fails + 1)); FAILURES+=("$1"); printf '  FAIL: %s\n' "$1"; }
+check() { # description condition-result(0=true)
+  cases=$((cases + 1))
+  if [[ "$2" -eq 0 ]]; then ok "$1"; else bad "$1"; fi
+}
+
+# Instrument self-test: drive both verdict helpers once, require both counters to move, then unwind.
+_p0=$passes; _f0=$fails; _c0=$cases; _l0=${#FAILURES[@]}
+ok "selftest" >/dev/null; bad "selftest" >/dev/null
+if [[ $passes -ne $((_p0 + 1)) || $fails -ne $((_f0 + 1)) ]]; then
+  printf 'FATAL: ok()/bad() do not record verdicts\n' >&2; exit 1
+fi
+passes=$_p0; fails=$_f0; cases=$_c0; FAILURES=()
+
+# --- private PATHs ------------------------------------------------------------
+mkdir -p "$FIX/nobin" "$FIX/stub"
+assert_fixture_dir "$FIX"
+for t in bash sh awk tr cut head cat env; do
+  src="$(type -P "$t" 2>/dev/null || true)"
+  [[ -n "$src" ]] && ln -sf "$src" "$FIX/nobin/$t"
+done
+REAL_UNSHARE="$(type -P unshare 2>/dev/null || true)"
+W="$FIX/witness"
+
+# run the helper with a private PATH; sets OUT (stdout+stderr) and RC
+run_helper() { # path-dir cmd...
+  local pdir="$1"; shift
+  RC=0
+  OUT="$(PATH="$pdir" "$BASH_BIN" "$SUT" "$@" 2>&1)" || RC=$?
+}
+first_line() { printf '%s\n' "$1" | head -n 1; }
+witness_cmd=(sh -c ': > "$1"' sh "$W")
+
+mkstub() { # name body -- writes $FIX/stub/<name>/unshare
+  mkdir -p "$FIX/stub/$1"; assert_fixture_dir "$FIX"
+  printf '#!/bin/sh\n%s\n' "$2" > "$FIX/stub/$1/unshare"; chmod +x "$FIX/stub/$1/unshare"
+  for t in bash sh awk tr cut head cat env; do ln -sf "$FIX/nobin/$t" "$FIX/stub/$1/$t" 2>/dev/null || true; done
+}
+
+echo "=== always-run rows (stub unshare) ==="
+
+# R6 witness control: the witness command, run directly, DOES create the witness.
+rm -f "$W"; "${witness_cmd[@]}"
+[[ -e "$W" ]]; check "R6 witness control: the witness command writes its file when it runs" $?
+rm -f "$W"
+
+# R1 unshare absent.
+rm -f "$W"; run_helper "$FIX/nobin" "${witness_cmd[@]}"
+[[ "$RC" -eq 125 && "$(first_line "$OUT")" == "RUN_IN_PID_NAMESPACE_REFUSED reason=missing-unshare"* && ! -e "$W" ]]
+check "R1 no unshare on PATH: rc 125, marker reason=missing-unshare, command never started" $?
+
+# R2 unshare fails (EPERM): rc 125, the stub's first line quoted on one line.
+mkstub fail 'echo "unshare: unshare failed: Operation not permitted" >&2; exit 1'
+rm -f "$W"; run_helper "$FIX/stub/fail" "${witness_cmd[@]}"
+[[ "$RC" -eq 125 && "$(first_line "$OUT")" == "RUN_IN_PID_NAMESPACE_REFUSED reason=userns-unavailable"* && ! -e "$W" ]]
+check "R2 failing unshare: rc 125, reason=userns-unavailable, command never started" $?
+printf '%s\n' "$OUT" | grep -cF >/dev/null -- "Operation not permitted"
+check "R2b the unshare message is quoted in the refusal" $?
+[[ "$(printf '%s\n' "$OUT" | grep -c '^RUN_IN_PID_NAMESPACE_REFUSED')" -eq 1 ]]
+check "R2c exactly one marker line" $?
+
+# R3 dishonest unshare: exits 0 and runs the command in place.
+mkstub dishonest 'while [ "$1" != "--" ]; do shift; done; shift; exec "$@"'
+rm -f "$W"; run_helper "$FIX/stub/dishonest" "${witness_cmd[@]}"
+[[ "$RC" -eq 125 && "$(first_line "$OUT")" == "RUN_IN_PID_NAMESPACE_REFUSED reason=not-isolating"* && ! -e "$W" ]]
+check "R3 dishonest unshare (runs in place): rc 125, reason=not-isolating, command never started" $?
+
+# R4 argv: a recording stub (lies on both calls by exiting 0 without running anything).
+mkstub rec 'n=$(cat "'"$FIX"'/calln" 2>/dev/null || echo 0); n=$((n+1)); echo $n > "'"$FIX"'/calln"; printf "%s\n" "$@" > "'"$FIX"'/argv.$n"; exit 0'
+rm -f "$FIX"/calln "$FIX"/argv.*; run_helper "$FIX/stub/rec" -- sh -c 'echo hi' x '' -n "a b"
+[[ "$RC" -eq 0 && -s "$FIX/argv.2" ]]; check "R4 recording stub sees a probe call and a run call" $?
+flags_ok=0
+for f in -U -r -p -f --kill-child --mount-proc; do
+  # combined -Urpf is equivalent to the split spellings
+  if [[ "$f" == --* ]]; then
+    [[ "$(grep -cxF -- "$f" "$FIX/argv.2")" -eq 1 ]] || flags_ok=1
+  else
+    letter="${f#-}"
+    [[ "$(sed -n '1,/^--$/p' "$FIX/argv.2" | grep -E -- '^-[A-Za-z]+$' | grep -c "$letter")" -ge 1 ]] || flags_ok=1
+  fi
+done
+check "R4b all of -U -r -p -f --kill-child --mount-proc precede -- in the run call" "$flags_ok"
+mapfile -t AV < "$FIX/argv.2"
+di=-1; for i in "${!AV[@]}"; do [[ "${AV[$i]}" == "--" ]] && { di=$i; break; }; done
+rest=""; if [[ "$di" -ge 0 ]]; then for ((i = di + 5; i < ${#AV[@]}; i++)); do rest+="${AV[$i]}|"; done; fi
+[[ "$di" -ge 0 && "${AV[$((di + 1))]:-}" == "sh" && "${AV[$((di + 2))]:-}" == "-c" && "${AV[$((di + 3))]:-}" == *'; exec "$@"' && "${AV[$((di + 4))]:-}" == "sh" && "$rest" == 'sh|-c|echo hi|x||-n|a b|' ]]
+check "R4c the whole argv after -- is sh -c <RUN ending exec \"\$@\"> sh then the command verbatim (spaces, an empty argument, a leading -n)" $?
+
+# R11 a command word that begins with a dash is refused before anything starts (exec would read it as an
+# option, and dash rejects exec --): rc 2, named message, no unshare call, command never started.
+rm -f "$W" "$FIX"/calln "$FIX"/argv.*; run_helper "$FIX/stub/rec" -touch "$W"
+[[ "$RC" -eq 2 && "$OUT" == *'must not begin with "-"'* && ! -e "$W" && ! -e "$FIX/calln" ]]
+check "R11 a command beginning with a dash is refused: rc 2, no unshare call, never started" $?
+
+# R5 usage.
+run_helper "$FIX/nobin"
+[[ "$RC" -eq 2 && "$OUT" == usage:* ]]; check "R5 no command: usage, rc 2" $?
+
+# R7 the in-namespace re-check: the probe call lies (exit 0), the run call executes in place.
+mkstub lateliar 'n=$(cat "'"$FIX"'/call7" 2>/dev/null || echo 0); n=$((n+1)); echo $n > "'"$FIX"'/call7"
+if [ "$n" -eq 1 ]; then echo probe-isolated >> "'"$FIX"'/log7"; exit 0; fi
+echo run-in-place >> "'"$FIX"'/log7"; while [ "$1" != "--" ]; do shift; done; shift; exec "$@"'
+rm -f "$W" "$FIX"/call7 "$FIX"/log7; run_helper "$FIX/stub/lateliar" "${witness_cmd[@]}"
+[[ "$RC" -eq 125 && "$OUT" == *"RUN_IN_PID_NAMESPACE_REFUSED reason=not-isolating"* && ! -e "$W" ]]
+check "R7 the check inside the namespace refuses when the run is not isolated: rc 125, marker, command never started" $?
+[[ "$(cat "$FIX/log7" 2>/dev/null | tr '\n' ' ')" == "probe-isolated run-in-place " ]]
+check "R7b positive control: the stub took the isolated branch on the probe and the in-place branch on the run" $?
+
+# R9 an exported function named unshare must not decide the probe: a failing unshare is on PATH, the function
+# would succeed, and the refusal must come from the PATH binary.
+rm -f "$W"
+RC=0; OUT="$(unshare() { return 0; }; export -f unshare; PATH="$FIX/stub/fail" "$BASH_BIN" "$SUT" "${witness_cmd[@]}" 2>&1)" || RC=$?
+[[ "$RC" -eq 125 && "$OUT" == "RUN_IN_PID_NAMESPACE_REFUSED reason=userns-unavailable"* && ! -e "$W" ]]
+check "R9 an exported shell function unshare does not decide the probe (the PATH binary does)" $?
+
+# R10 below: the helper must not refuse where the host itself can create the namespace.
+
+# --- probe decides the real-namespace branch ---------------------------------
+REAL_NS=no; REAL_WHY="no unshare on PATH"
+if [[ -n "$REAL_UNSHARE" ]]; then
+  PROBE_OUT="$("$BASH_BIN" "$SUT" sh -c 'echo ok' 2>&1)"; PROBE_RC=$?
+  if [[ "$PROBE_RC" -eq 0 && "$PROBE_OUT" == "ok" ]]; then REAL_NS=yes
+  else REAL_WHY="$(first_line "$PROBE_OUT" | cut -c1-120)"; fi
+fi
+
+# An INDEPENDENT host probe (the SUT is not involved): where the host can create the namespace and the helper
+# still refuses, the helper is broken, and that must be a FAIL, never a SKIP.
+HOST_NS=no
+if [[ -n "$REAL_UNSHARE" ]]; then
+  HOST_OUT="$("$REAL_UNSHARE" -Urpf --kill-child --mount-proc -- sh -c 'echo ok' 2>&1)"; HOST_RC=$?
+  [[ "$HOST_RC" -eq 0 && "$HOST_OUT" == "ok" ]] && HOST_NS=yes
+fi
+[[ "$HOST_NS" != "yes" || "$REAL_NS" == "yes" ]]
+check "R10 the helper does not refuse where the host itself can create the namespace (host=$HOST_NS, helper=$REAL_NS)" $?
+
+if [[ "$REAL_NS" == "yes" ]]; then
+  echo "=== real-namespace rows ==="
+  # N1 PID 1, no parent, own /proc.
+  OUT="$("$BASH_BIN" "$SUT" sh -c 'echo "$$ $PPID $(awk "/^NSpid:/{print NF-1}" /proc/self/status)"' 2>&1)"
+  [[ "$OUT" == "1 0 1" ]]; check "N1 the command is PID 1 with PPID 0 and its own /proc" $?
+  # N2 exit codes pass through; a wrapped 125 carries no marker.
+  "$BASH_BIN" "$SUT" sh -c 'exit 0'; r0=$?; "$BASH_BIN" "$SUT" sh -c 'exit 3'; r3=$?
+  OUT="$("$BASH_BIN" "$SUT" sh -c 'exit 125' 2>&1)"; r125=$?
+  [[ "$r0" -eq 0 && "$r3" -eq 3 ]]; check "N2 exit codes 0 and 3 pass through" $?
+  [[ "$r125" -eq 125 && "$OUT" != *RUN_IN_PID_NAMESPACE_REFUSED* ]]; check "N2b a wrapped command's own 125 passes through with no marker" $?
+  # N3 stdin, stdout, stderr, cwd; a dash-leading command name.
+  mkdir -p "$FIX/cwd"; assert_fixture_dir "$FIX"
+  OUT="$(cd "$FIX/cwd" && printf 'in\n' | "$BASH_BIN" "$SUT" sh -c 'read x; echo "out:$x:$(pwd)"; echo err >&2' 2>"$FIX/err3")"
+  [[ "$OUT" == "out:in:$FIX/cwd" && "$(cat "$FIX/err3")" == "err" ]]
+  check "N3 stdin, stdout, stderr and cwd pass through, nothing added on stderr" $?
+  cat > "$FIX/-dashcmd" <<'EOS'
+#!/bin/sh
+echo dash-ran
+EOS
+  chmod +x "$FIX/-dashcmd"
+  OUT="$(cd "$FIX" && "$BASH_BIN" "$SUT" -- ./-dashcmd 2>&1)"
+  [[ "$OUT" == "dash-ran" ]]; check "N3b a command whose file name begins with a dash runs when given as a path (./-name)" $?
+  # N4 containment: victim (outside, argv carries the nonce) -> helper -> top (PID 1, nonce) -> mid (nonce) -> walker.
+  NONCE="$(od -An -tx1 -N16 /dev/urandom | tr -d ' \n')"
+  [[ "$NONCE" =~ ^[0-9a-f]{32}$ ]]; check "N4 precondition: the nonce is 32 hex characters" $?
+  assert_fixture_dir "$FIX"
+  cat > "$FIX/top.sh" <<'EOS'
+#!/bin/sh
+sh "$FIX_DIR/mid.sh" "mid-$1"
+echo top-done > "$FIX_DIR/top-done"
+EOS
+  cat > "$FIX/mid.sh" <<'EOS'
+#!/bin/sh
+echo mid-started > "$FIX_DIR/mid-started"
+sh "$WALKER_PATH"
+echo mid-survived > "$FIX_DIR/mid-survived"
+EOS
+  rm -f "$FIX/mid-started" "$FIX/mid-survived" "$FIX/top-done" "$FIX/victim-survived"
+  FIX_DIR="$FIX" WALKER_PATH="$WALKER" WALKER_NONCE="$NONCE" SOLEUR_TEST_SUITE_PID=$$ VOUT="$FIX/victim-survived" \
+    timeout -k 5 60 "$BASH_BIN" -c '"$@"; echo victim-survived > "$VOUT"' "victim-$NONCE" \
+    "$BASH_BIN" "$SUT" sh "$FIX/top.sh" "top-$NONCE" > "$FIX/n4.out" 2>&1
+  [[ -e "$FIX/mid-started" && ! -e "$FIX/mid-survived" ]]
+  check "N4b positive control: the walker signalled the in-namespace middle process (it started, and died before its next line)" $?
+  [[ -e "$FIX/top-done" && -e "$FIX/victim-survived" ]]
+  check "N4c containment: PID 1 of the namespace finished and the outside ancestor carrying the nonce survived" $?
+  # Fail-closed preconditions of the fixture walker, rehearsed with kill replaced by echo on the host chain.
+  for pre in empty-nonce short-nonce nonhex-nonce unset-suite; do
+    case "$pre" in
+      empty-nonce) n=""; sp=$$ ;;
+      short-nonce) n="abc123"; sp=$$ ;;
+      nonhex-nonce) n="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"; sp=$$ ;;
+      unset-suite) n="$NONCE"; sp="" ;;
+    esac
+    O="$(WALKER_KILL=echo WALKER_NONCE="$n" SOLEUR_TEST_SUITE_PID="$sp" "$BASH_BIN" -c 'sh "$1"' "carrier-$n" "$WALKER" 2>&1)"
+    [[ -z "$O" ]]; check "N4d the fixture walker signals nothing: $pre" $?
+  done
+  O="$(WALKER_KILL=echo WALKER_NONCE="$NONCE" SOLEUR_TEST_SUITE_PID=$$ "$BASH_BIN" -c 'echo $$ > "$2"; sh "$1"; :' "carrier-$NONCE" "$WALKER" "$FIX/carrier.pid" 2>&1)"
+  [[ "$O" == "-TERM $(cat "$FIX/carrier.pid" 2>/dev/null)" ]]
+  check "N4e rehearsal with kill replaced by echo targets exactly the nonce-carrying ancestor, nothing above it" $?
+  # N5 a backgrounded child is gone after the helper returns; N5b the same after the helper is SIGKILLed.
+  has_proc() { # tag -> 0 when some process cmdline carries the tag (the bracket keeps this grep's own argv from matching)
+    grep -alqE -- "[${1:0:1}]${1:1}" /proc/[0-9]*/cmdline 2>/dev/null
+  }
+  T5="bgtag-$NONCE"
+  "$BASH_BIN" "$SUT" "$BASH_BIN" -c 'exec -a "$1" sleep 40 & exit 0' sh "$T5" >/dev/null 2>&1
+  gone=1; for _ in 1 2 3 4 5 6 7 8 9 10; do has_proc "$T5" || { gone=0; break; }; sleep 0.2; done
+  check "N5 a backgrounded child does not outlive the command (the helper returned)" "$gone"
+  T5b="bgkill-$NONCE"
+  "$BASH_BIN" "$SUT" "$BASH_BIN" -c 'exec -a "$1" sleep 40' sh "$T5b" >/dev/null 2>&1 &
+  hp=$!
+  up=1; for _ in 1 2 3 4 5 6 7 8 9 10; do has_proc "$T5b" && { up=0; break; }; sleep 0.2; done
+  [[ "$up" -eq 0 ]]; check "N5b control: the tagged child is running while the helper runs" $?
+  kill -KILL "$hp" 2>/dev/null; wait "$hp" 2>/dev/null
+  gone=1; for _ in 1 2 3 4 5 6 7 8 9 10; do has_proc "$T5b" || { gone=0; break; }; sleep 0.2; done
+  check "N5c SIGKILL of the helper reaps the tree (--kill-child)" "$gone"
+  # N6 nested use.
+  OUT="$("$BASH_BIN" "$SUT" "$BASH_BIN" "$SUT" sh -c 'echo "$$ $PPID"' 2>&1)"
+  [[ "$OUT" == "1 0" ]]; check "N6 a nested helper call works" $?
+  # N7 a wrapper unshare that drops --mount-proc is refused.
+  mkdir -p "$FIX/stub/noproc"; assert_fixture_dir "$FIX"
+  cat > "$FIX/stub/noproc/unshare" <<EOS
+#!/bin/sh
+for x; do shift; [ "\$x" = "--mount-proc" ] || set -- "\$@" "\$x"; done
+exec $REAL_UNSHARE "\$@"
+EOS
+  chmod +x "$FIX/stub/noproc/unshare"
+  for t in bash sh awk tr cut head cat env; do ln -sf "$FIX/nobin/$t" "$FIX/stub/noproc/$t" 2>/dev/null || true; done
+  rm -f "$W"; run_helper "$FIX/stub/noproc" "${witness_cmd[@]}"
+  [[ "$RC" -eq 125 && "$OUT" == *"reason=not-isolating"* && ! -e "$W" ]]
+  check "N7 a wrapper that drops --mount-proc is refused (host /proc has two NSpid fields)" $?
+else
+  # R8: where namespaces are unavailable the REAL helper must still refuse.
+  echo "SKIP real-namespace rows: user namespaces unavailable here ($REAL_WHY)"
+  skipped=$((skipped + 18))  # the 18 real-namespace rows: N1 N2 N2b N3 N3b N4 N4b N4c N4d x4 N4e N5 N5b N5c N6 N7
+  rm -f "$W"; RC=0; OUT="$("$BASH_BIN" "$SUT" "${witness_cmd[@]}" 2>&1)" || RC=$?
+  [[ "$RC" -eq 125 && "$(first_line "$OUT")" == "RUN_IN_PID_NAMESPACE_REFUSED reason="* && ! -e "$W" ]]
+  check "R8 the real helper refuses (rc 125, marker, command never started) where namespaces are unavailable" $?
+  if [[ "${SOLEUR_REQUIRE_REAL_NS:-}" == "1" ]]; then check "SOLEUR_REQUIRE_REAL_NS=1 but user namespaces are unavailable ($REAL_WHY)" 1; fi
+fi
+
+# --- verdict ------------------------------------------------------------------
+echo ""
+printf '=== run-in-pid-namespace: %d passed, %d failed (%d cases, %d skipped, real-namespace=%s) ===\n' "$passes" "$fails" "$cases" "$skipped" "$REAL_NS"
+if [[ "$REAL_NS" != "yes" ]]; then printf 'SKIP: %d real-namespace rows (%s)\n' "$skipped" "$REAL_WHY"; fi
+for f in ${FAILURES[@]+"${FAILURES[@]}"}; do printf '  - %s\n' "$f"; done
+# Anti-vacuity floors: literal thresholds on the line above each test, reported by printf, appended to the ledger the verdict reads.
+if [[ "$cases" -lt 16 ]]; then printf 'FAIL: vacuity floor: only %d cases ran (>= 16 always-run rows expected, R8 counted when namespaces are unavailable)\n' "$cases" >&2; FAILURES+=("always-run floor"); fi
+if [[ "$REAL_NS" == "yes" ]]; then
+  if [[ "$cases" -lt 33 ]]; then printf 'FAIL: vacuity floor: only %d cases ran (>= 33 expected with real namespaces)\n' "$cases" >&2; FAILURES+=("real-namespace floor"); fi
+  if [[ "$cases" -ne 33 ]]; then printf 'FAIL: conservation: %d cases ran, 33 planned with real namespaces\n' "$cases" >&2; FAILURES+=("planned total"); fi
+else
+  if [[ "$((cases + skipped))" -ne 34 ]]; then printf 'FAIL: conservation: %d cases + %d skipped != 34 planned\n' "$cases" "$skipped" >&2; FAILURES+=("planned total"); fi
+fi
+if [[ "$((passes + fails))" -ne "$cases" ]]; then printf 'FAIL: verdict conservation: %d passes + %d fails != %d cases\n' "$passes" "$fails" "$cases" >&2; FAILURES+=("conservation"); fi
+[[ "${#FAILURES[@]}" -eq 0 ]]