From 631e7ca66038295d12a37dfddf840ca94bb10bd8 Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Wed, 5 Aug 2026 21:47:16 -0400
Subject: [PATCH 1/8] fix(tests): contain and reap test fixtures instead of
 leaking them into /tmp

/tmp is a tmpfs on some hosts, so a fixture the suite leaves behind is leaked
RAM. Fixtures accumulated without bound: most test files installed no EXIT trap,
and the ones that did still lost their fixtures whenever a run was killed. On one
host that reached 3.0 GB of RAM held by dead fixtures.

Fix it in the runner, which is the one place that already sits at both the start
and the end of every run, rather than in each test file.

- Every executed script now runs with TMPDIR, TMP, and FM_TASK_TMP_ROOT pointed
  at a private directory inside the run's own root, so fixtures built the way the
  suite builds them land inside the run. Each script's root is removed as soon as
  that script finishes, so peak usage stays at one script's fixtures.
- The run root is removed on a normal exit and on INT, TERM, HUP, and QUIT, and
  the runner then dies from the same signal so callers still see a signal death.
- An executing run first reaps fixture directories orphaned by runs that were
  killed outright, so an already-leaked host heals on the next run. The reap
  keeps anything it cannot establish: only direct children of the reap root, only
  mktemp-shaped fm- names, only directories this user owns, only entries past a
  minimum age, never a recorded tasktmp= path or a per-task scratch root, never a
  directory a process still holds open, and nothing at all when the in-use
  inventory or a home's task records cannot be read.
- bin/fm-spawn.sh roots per-task scratch at FM_TASK_TMP_ROOT, which is unset in
  normal operation so the real path is unchanged. A test that drives a real spawn
  previously stranded a /tmp/fm-<fixture id>/ that no teardown would ever claim.

Behavioural coverage in tests/fm-test-run.test.sh proves a completed run, an
interrupted run, and a killed run each leave no fixture behind, that a later run
reaps pre-existing orphans, and that a live task's recorded scratch directory and
a directory another process holds open are never removed.
---
 CONTRIBUTING.md                |   2 +
 bin/fm-spawn.sh                |   8 +-
 bin/fm-test-run.sh             | 342 ++++++++++++++++++++++++++++++++-
 tests/fm-backend-orca.test.sh  |   4 +-
 tests/fm-backend.test.sh       |   8 +-
 tests/fm-gotmp.test.sh         |   2 +-
 tests/fm-kimi-harness.test.sh  |   2 +-
 tests/fm-session-start.test.sh |   4 +-
 tests/fm-test-run.test.sh      | 331 +++++++++++++++++++++++++++++++
 tests/lib.sh                   |  29 ++-
 10 files changed, 701 insertions(+), 31 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7876f7cbdb..c6da486673 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -97,6 +97,8 @@ Family selection is the ordinary local path; `--all` is deliberate full regressi
 CI owns broad regression across required portable parallel shards, the portable serial lane, the Herdr lane, lint, invariants, the coverage guard, and stock macOS Bash compatibility in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 Use `bin/fm-test-run.sh --help` for lane names, `--jobs` rules, and required gate-skip flags when reproducing a lane locally.
 Discover tests by listing `tests/*.test.sh`: each is a self-contained bash script named `<subject>.test.sh`, and its header comment describes what it covers, so pass one to `bin/fm-test-run.sh` to focus on a subject with canonical timing output.
+The runner is also the single owner of fixture cleanup: it gives every executed script a private `TMPDIR` and removes it when that script finishes, on an interrupted run as well as a normal one, and it reaps fixture directories orphaned by earlier killed runs, so a new test needs no temp-root `EXIT` trap of its own.
+That matters because `/tmp` is a tmpfs on some hosts, where a leaked fixture is leaked RAM rather than disk; the runner's header owns the reap's safety rules and its test-only environment seams.
 Tests that need a real optional backend or an explicit opt-in (real herdr/zellij/cmux smoke tests, the live Pi regression) skip themselves and print the tool or environment gate needed to enable them, so the portable suite remains safe on machines without those tools.
 The [Herdr backend guide](docs/herdr-backend.md#destructive-lab-safety) owns the lane's isolation boundary, while [runtime backend verification](docs/verification/runtime-backends.md#herdr) owns active empirical evidence; live harness credential tests remain opt-in.
 
diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh
index 6cdf9879ac..4d70237013 100755
--- a/bin/fm-spawn.sh
+++ b/bin/fm-spawn.sh
@@ -1325,7 +1325,13 @@ fi
 # Nested (not a bare /tmp/fm-<id>/gotmp) so other per-task temp can live alongside
 # later, and teardown cleans one deterministic path. GOTMPDIR (not TMPDIR) is the
 # targeted knob: TMPDIR is too broad (affects every program's temp, not just Go's).
-TASK_TMP="/tmp/fm-$ID"
+#
+# FM_TASK_TMP_ROOT relocates that root and is unset in normal operation, so the
+# real path is unchanged. bin/fm-test-run.sh sets it to the executed script's
+# private temp root: a test that drives a real spawn would otherwise leave a
+# /tmp/fm-<fixture id>/ behind with no task and no teardown to remove it, and on
+# a tmpfs /tmp that residue is held in RAM.
+TASK_TMP="${FM_TASK_TMP_ROOT:-/tmp}/fm-$ID"
 mkdir -p "$TASK_TMP/gotmp"
 
 # Per-harness turn-end hook where enabled: a file that touches
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 973032d43d..bec9ef6c1c 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -43,10 +43,48 @@
 #                   families never schedule under --jobs.
 #   -h, --help      print this header
 #
+# Fixture containment:
+#   Every executed script runs with TMPDIR and TMP pointed at a private
+#   directory inside this run's own root, so a fixture built the way the suite
+#   builds them - mktemp -d "${TMPDIR:-/tmp}/fm-<prefix>.XXXXXX", directly or
+#   through tests/lib.sh fm_test_tmproot - lands inside the run instead of
+#   beside it. Each script's private root is removed as soon as that script
+#   finishes, and the run root is removed on normal exit and on INT, TERM, HUP,
+#   or QUIT. This is the single owner of fixture cleanup: no test file needs its
+#   own EXIT trap for temp roots, and an interrupted run cleans up too. /tmp is
+#   a tmpfs on some hosts, where a leaked fixture is leaked RAM, not disk.
+#   FM_TASK_TMP_ROOT is pointed at the same private directory, so a test that
+#   drives a real bin/fm-spawn.sh keeps its per-task scratch root inside the run
+#   instead of leaving a /tmp/fm-<fixture id>/ that no teardown will ever claim.
+#
+# Orphan reap:
+#   An executing run first reaps fixture directories orphaned by earlier runs
+#   that were killed outright (SIGKILL leaves no trap to run), so a host that
+#   already leaked heals on the next test run. The reap is deliberately narrow
+#   and keeps anything it cannot establish:
+#     - only direct children of the reap root, never a wider glob;
+#     - only names shaped like an mktemp fixture, fm-<prefix>.<6+ alphanumerics>;
+#     - only directories (never symlinks) owned by the current user;
+#     - only entries older than the minimum age, so a concurrent run is safe;
+#     - never a path recorded as tasktmp= by any discoverable Firstmate home,
+#       and never a per-task scratch root (identified by its gotmp/ child);
+#     - never a directory any process still holds open;
+#     - nothing at all if the in-use inventory or a home's task records cannot
+#       be read.
+#   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MIN_AGE_SECONDS (default
+#   900), FM_TEST_REAP_MAX (default 500), and FM_TEST_REAP_HOMES (extra
+#   colon-separated Firstmate homes whose state/*.meta to read) exist so this
+#   behavior is testable without touching the host's real /tmp.
+#   FM_TEST_RUN_ACTIVE=1 is exported to every executed script and suppresses the
+#   reap in a nested run.
+#
 # Per-script machine-parseable markers (stdout):
 #   FM_TEST_BEGIN <iso8601> <script> family=<family> expected_gate_skip=<class>
 #   FM_TEST_END <iso8601> <script> exit=<code> duration_ms=<n> gate_skip=<true|false>
 #
+# Reap marker (stdout, once, executing runs only):
+#   FM_TEST_REAP root=<dir> removed=<n> kept=<n>
+#
 # After all scripts (stdout):
 #   FM_TEST_SUMMARY total=<n> failed=<n> skipped_gate=<n> duration_ms=<n>
 #   FM_TEST_SUMMARY_FAMILY family=<name> count=<n> duration_ms=<n> failed=<n>
@@ -119,6 +157,276 @@ now_ms() {
   fi
 }
 
+# --- run root, fixture containment, and orphan reap -------------------------
+
+REAP_ROOT=${FM_TEST_REAP_ROOT:-/tmp}
+REAP_MIN_AGE_SECONDS=${FM_TEST_REAP_MIN_AGE_SECONDS:-900}
+REAP_MAX=${FM_TEST_REAP_MAX:-500}
+# Descriptor 9 is held open inside the run root for its whole life. A concurrent
+# runner's reap sees this open file and keeps the root, which is what makes the
+# reap safe to run while another suite is in flight. Executed scripts get it
+# closed so only this runner pins the root.
+RUN_TMP=
+
+# shellcheck disable=SC2329 # Registered by the EXIT and signal traps below.
+remove_run_tmp() {
+  local doomed=$RUN_TMP
+  [ -n "$doomed" ] || return 0
+  RUN_TMP=
+  exec 9<&-
+  rm -rf "$doomed" 2>/dev/null || true
+}
+
+# Remove the run root, then die from the same signal so a caller (a shell, CI,
+# or a supervising script) still sees a normal signal death rather than a
+# swallowed interrupt.
+# shellcheck disable=SC2329 # Registered by the signal traps below.
+on_run_signal() {
+  local sig=$1
+  trap - EXIT INT TERM HUP QUIT
+  remove_run_tmp
+  kill -s "$sig" "$$" 2>/dev/null || true
+  exit 1
+}
+
+# Create this run's private root once and arm removal for both a normal exit and
+# an interruption. Every temp path the runner needs lives under it, so one
+# removal covers the whole run.
+ensure_run_tmp() {
+  [ -z "$RUN_TMP" ] || return 0
+  RUN_TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run.XXXXXX") \
+    || die "could not create a run temp root"
+  chmod 0700 "$RUN_TMP" || die "could not chmod 0700 run temp root $RUN_TMP"
+  trap 'remove_run_tmp' EXIT
+  trap 'on_run_signal INT' INT
+  trap 'on_run_signal TERM' TERM
+  trap 'on_run_signal HUP' HUP
+  trap 'on_run_signal QUIT' QUIT
+  : >"$RUN_TMP/.fm-test-run-live"
+  exec 9<"$RUN_TMP/.fm-test-run-live"
+}
+
+# One stat field, GNU format first and BSD format second. Prints nothing and
+# fails when neither works, so every caller can treat that as "unknown".
+stat_field() {
+  local gnu=$1 bsd=$2 path=$3 value
+  value=$(stat -c "$gnu" "$path" 2>/dev/null) || value=
+  if [ -z "$value" ]; then
+    value=$(stat -f "$bsd" "$path" 2>/dev/null) || value=
+  fi
+  [ -n "$value" ] || return 1
+  printf '%s\n' "$value"
+}
+
+# True when <name> looks like a directory mktemp -d built from a
+# "fm-<prefix>.XXXXXX" template: the template's random suffix is at least six
+# characters and always alphanumeric. A Firstmate per-task scratch root is
+# /tmp/fm-<task id> with no such suffix, so this alone already separates the two
+# populations; the tasktmp and gotmp checks below cover a task id that happens to
+# end in a matching suffix.
+reap_name_is_fixture() {
+  local name=$1 stem suffix
+  case "$name" in
+    fm-?*.?*) ;;
+    *) return 1 ;;
+  esac
+  stem=${name%.*}
+  suffix=${name##*.}
+  [ "${stem#fm-}" != "" ] || return 1
+  [ "${#suffix}" -ge 6 ] || return 1
+  case "$suffix" in
+    *[!A-Za-z0-9]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Firstmate homes whose state/*.meta may record a live task's scratch root:
+# this checkout, an explicit FM_HOME, the primary checkout this worktree belongs
+# to, extra homes named by FM_TEST_REAP_HOMES, and every secondmate home each of
+# those registers.
+reap_candidate_homes() {
+  local seeded common home extra
+  {
+    printf '%s\n' "$ROOT"
+    [ -z "${FM_HOME:-}" ] || printf '%s\n' "$FM_HOME"
+    common=$(git -C "$ROOT" rev-parse --git-common-dir 2>/dev/null || true)
+    if [ -n "$common" ]; then
+      case "$common" in
+        /*) ;;
+        *) common="$ROOT/$common" ;;
+      esac
+      [ ! -d "$common" ] || printf '%s\n' "$(dirname "$common")"
+    fi
+    if [ -n "${FM_TEST_REAP_HOMES:-}" ]; then
+      while IFS= read -r extra; do
+        [ -n "$extra" ] || continue
+        printf '%s\n' "$extra"
+      done < <(printf '%s\n' "${FM_TEST_REAP_HOMES//:/$'\n'}")
+    fi
+  } | LC_ALL=C sort -u >"$RUN_TMP/reap-homes-seed"
+
+  while IFS= read -r seeded; do
+    [ -n "$seeded" ] || continue
+    printf '%s\n' "$seeded"
+    [ -f "$seeded/data/secondmates.md" ] || continue
+    while IFS= read -r home; do
+      [ -n "$home" ] || continue
+      printf '%s\n' "$home"
+    done < <(sed -n 's/.*(home: *\([^;)]*\).*/\1/p' "$seeded/data/secondmates.md")
+  done <"$RUN_TMP/reap-homes-seed" | LC_ALL=C sort -u
+}
+
+# Every tasktmp= path recorded by a discoverable home. Fails when a home's task
+# records exist but cannot be read, because an unreadable record is exactly the
+# ambiguity that must stop the reap rather than widen it.
+reap_protected_tasktmp() {
+  local home meta rc=0
+  local -a metas
+  while IFS= read -r home; do
+    [ -n "$home" ] || continue
+    [ -d "$home/state" ] || continue
+    if [ ! -r "$home/state" ] || [ ! -x "$home/state" ]; then
+      log "orphan reap skipped: unreadable task records in $home/state"
+      rc=1
+      continue
+    fi
+    metas=()
+    for meta in "$home"/state/*.meta; do
+      [ -f "$meta" ] || continue
+      if [ ! -r "$meta" ]; then
+        log "orphan reap skipped: unreadable task record $meta"
+        rc=1
+        continue
+      fi
+      metas+=("$meta")
+    done
+    # One reader per home rather than one per task record.
+    [ "${#metas[@]}" -eq 0 ] || sed -n 's/^tasktmp=//p' "${metas[@]}"
+  done < <(reap_candidate_homes)
+  return "$rc"
+}
+
+# Absolute paths under <root> that some process still holds: a working
+# directory, an open descriptor, a running executable, or a mapping. /proc is
+# exact and cheap where it exists; lsof covers hosts without it. Fails when
+# neither is available, which keeps the reap from running blind rather than
+# guessing that nothing is in use.
+reap_inuse_paths() {
+  local root=$1 proc link target root_re
+  root_re=$(printf '%s' "$root" | sed 's/[^A-Za-z0-9_/-]/\\&/g')
+  if [ -r /proc/self/fd ] && find /proc/self -maxdepth 0 -printf '' 2>/dev/null; then
+    # One find over the descriptor, cwd, and exe links of every process. A
+    # per-link readlink loop costs seconds on a busy host; this costs
+    # milliseconds.
+    find /proc/[0-9]*/cwd /proc/[0-9]*/exe /proc/[0-9]*/fd/ \
+      -maxdepth 1 -type l -printf '%l\n' 2>/dev/null \
+      | grep -E "^${root_re}(/|\$)" || true
+    grep -haoE "${root_re}/[^[:space:]]+" /proc/[0-9]*/maps 2>/dev/null || true
+    return 0
+  fi
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -n -P -Fn 2>/dev/null | sed -n "s|^n\\(${root}/.*\\)|\\1|p"
+    return 0
+  fi
+  if [ -r /proc/self/fd ]; then
+    for proc in /proc/[0-9]*; do
+      for link in "$proc/cwd" "$proc/exe" "$proc"/fd/*; do
+        target=$(readlink "$link" 2>/dev/null) || continue
+        case "$target" in
+          "$root"/*) printf '%s\n' "$target" ;;
+        esac
+      done
+    done
+    return 0
+  fi
+  return 1
+}
+
+# Remove fixture directories orphaned by earlier killed runs. Every rejection
+# keeps the directory; nothing here removes on a maybe.
+reap_orphan_fixtures() {
+  local root=$REAP_ROOT now uid entry name age mtime owner removed=0 kept=0 examined=0
+  local protected inuse
+
+  [ -z "${FM_TEST_RUN_ACTIVE:-}" ] || return 0
+
+  case "$root" in
+    /*) ;;
+    *) log "orphan reap skipped: reap root must be an absolute path (got '$root')"; return 0 ;;
+  esac
+  if [ -L "$root" ] || [ ! -d "$root" ]; then
+    log "orphan reap skipped: reap root is not a directory: $root"
+    return 0
+  fi
+  case "$REAP_MIN_AGE_SECONDS" in
+    ''|*[!0-9]*) log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"; return 0 ;;
+  esac
+  case "$REAP_MAX" in
+    ''|*[!0-9]*) log "orphan reap skipped: FM_TEST_REAP_MAX must be a non-negative integer"; return 0 ;;
+  esac
+
+  protected="$RUN_TMP/reap-protected"
+  inuse="$RUN_TMP/reap-inuse"
+  if ! reap_protected_tasktmp >"$protected"; then
+    log "orphan reap skipped: could not read every task record, so no directory is safe to remove"
+    return 0
+  fi
+  if ! reap_inuse_paths "$root" >"$inuse"; then
+    log "orphan reap skipped: no way to tell which directories are still in use (no /proc, no lsof)"
+    return 0
+  fi
+
+  now=$(date +%s)
+  uid=$(id -u)
+  for entry in "$root"/fm-*; do
+    [ -e "$entry" ] || continue
+    name=$(basename "$entry")
+    reap_name_is_fixture "$name" || continue
+    if [ "$examined" -ge "$REAP_MAX" ]; then
+      log "orphan reap bounded at $REAP_MAX entries; re-run to continue"
+      break
+    fi
+    examined=$((examined + 1))
+    if [ -L "$entry" ] || [ ! -d "$entry" ]; then
+      kept=$((kept + 1))
+      continue
+    fi
+    if [ -d "$entry/gotmp" ]; then
+      kept=$((kept + 1))
+      continue
+    fi
+    owner=$(stat_field %u %u "$entry") || owner=
+    if [ "$owner" != "$uid" ]; then
+      kept=$((kept + 1))
+      continue
+    fi
+    mtime=$(stat_field %Y %m "$entry") || mtime=
+    case "$mtime" in
+      ''|*[!0-9]*) kept=$((kept + 1)); continue ;;
+    esac
+    age=$((now - mtime))
+    if [ "$age" -lt "$REAP_MIN_AGE_SECONDS" ]; then
+      kept=$((kept + 1))
+      continue
+    fi
+    if grep -qxF "$entry" "$protected"; then
+      kept=$((kept + 1))
+      continue
+    fi
+    if grep -qE "^$(printf '%s' "$entry" | sed 's/[^A-Za-z0-9_/-]/\\&/g')(/|\$)" "$inuse"; then
+      kept=$((kept + 1))
+      continue
+    fi
+    if rm -rf "$entry" 2>/dev/null; then
+      removed=$((removed + 1))
+    else
+      kept=$((kept + 1))
+    fi
+  done
+
+  printf 'FM_TEST_REAP root=%s removed=%s kept=%s\n' "$root" "$removed" "$kept"
+}
+
 # Primary family for one tests/*.test.sh basename. Unmapped scripts are
 # unclassified so new tests are still runnable and visible in summaries.
 family_for_basename() {
@@ -371,7 +679,9 @@ select_lane() {
 run_coverage_guard() {
   local tmp missing extra a b
   local -a saved_scripts=()
-  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-coverage.XXXXXX")
+  ensure_run_tmp
+  tmp="$RUN_TMP/coverage"
+  mkdir -p "$tmp"
 
   all_repo_tests | LC_ALL=C sort -u >"$tmp/all"
   list_proven_isolated | LC_ALL=C sort -u >"$tmp/proven"
@@ -1132,8 +1442,9 @@ if [ "${#SCRIPTS[@]}" -eq 0 ]; then
   log "nothing to run"
   printf 'FM_TEST_SUMMARY total=0 failed=0 skipped_gate=0 duration_ms=0\n'
   if [ -n "$JSON_PATH" ]; then
-    empty_rec=$(mktemp)
-    empty_fam=$(mktemp)
+    ensure_run_tmp
+    empty_rec="$RUN_TMP/empty-records.tsv"
+    empty_fam="$RUN_TMP/empty-families.tsv"
     : >"$empty_rec"
     : >"$empty_fam"
     started=$(now_iso)
@@ -1159,11 +1470,11 @@ if [ "$JOBS" -gt 1 ]; then
   done
 fi
 
-RUN_TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run.XXXXXX")
+ensure_run_tmp
+reap_orphan_fixtures
 RECORDS="$RUN_TMP/records.tsv"
 FAMILIES_TSV="$RUN_TMP/families.tsv"
 : >"$RECORDS"
-trap 'rm -rf "$RUN_TMP"' EXIT
 
 RUN_STARTED_ISO=$(now_iso)
 RUN_STARTED_MS=$(now_ms)
@@ -1240,11 +1551,17 @@ record_script_result() {
 
 run_one_serial() {
   local script=$1
-  local base family expected out begin_iso begin_ms end_ms end_iso duration rc
+  local base family expected out script_tmp begin_iso begin_ms end_ms end_iso duration rc
   base=$(basename "$script")
   family=$(family_for_basename "$base")
   expected=$(expected_gate_skip_for_family "$family")
   out="$RUN_TMP/out.$TOTAL"
+  # Private temp root for this one script. Fixtures land inside it, and it is
+  # removed as soon as the script finishes, so peak temp usage stays at one
+  # script's fixtures rather than the whole run's.
+  script_tmp="$RUN_TMP/t$TOTAL"
+  mkdir -p "$script_tmp" || die "could not create per-script temp root $script_tmp"
+  chmod 0700 "$script_tmp" || die "could not chmod 0700 per-script temp root $script_tmp"
   begin_iso=$(now_iso)
   begin_ms=$(now_ms)
 
@@ -1254,7 +1571,10 @@ run_one_serial() {
   set +e
   # Stream live output while retaining a copy for gate-skip detection.
   # PIPESTATUS[0] is the test script; tee's exit is ignored for aggregate.
-  bash "$script" 2>&1 | tee "$out"
+  # The run-root descriptor is closed in the child so only this runner keeps the
+  # root pinned against a concurrent reap.
+  TMPDIR="$script_tmp" TMP="$script_tmp" FM_TASK_TMP_ROOT="$script_tmp" \
+    FM_TEST_RUN_ACTIVE=1 bash "$script" 9<&- 2>&1 | tee "$out"
   rc=${PIPESTATUS[0]}
   set -e
   : "${rc:=1}"
@@ -1265,6 +1585,7 @@ run_one_serial() {
   if [ "$duration" -lt 0 ]; then
     duration=0
   fi
+  rm -rf "$script_tmp"
   record_script_result "$script" "$rc" "$duration" "$out" "$end_iso"
 }
 
@@ -1312,6 +1633,8 @@ else
         ;;
     esac
     record_script_result "$script" "$rc" "$duration" "$out" "$end_iso"
+    # The worker's fixtures are done with; free them now rather than at run end.
+    rm -rf "$work/tmp"
   }
 
   worker_pid_is_running() {
@@ -1355,13 +1678,12 @@ else
       "$(now_iso)" "$script" "$family" "$expected"
     (
       set +e
-      export TMPDIR="$work/tmp"
-      export TMP="$work/tmp"
       unset FM_HOME FM_STATE_OVERRIDE FM_DATA_OVERRIDE FM_ROOT_OVERRIDE \
         FM_PROJECTS_OVERRIDE FM_CONFIG_OVERRIDE FM_BACKEND 2>/dev/null || true
       cd "$ROOT" || exit 1
       begin_ms=$(now_ms)
-      bash "$script" >"$work/output" 2>&1
+      TMPDIR="$work/tmp" TMP="$work/tmp" FM_TASK_TMP_ROOT="$work/tmp" \
+        FM_TEST_RUN_ACTIVE=1 bash "$script" 9<&- >"$work/output" 2>&1
       rc=$?
       end_ms=$(now_ms)
       duration=$((end_ms - begin_ms))
diff --git a/tests/fm-backend-orca.test.sh b/tests/fm-backend-orca.test.sh
index a54e448d10..c105077e54 100755
--- a/tests/fm-backend-orca.test.sh
+++ b/tests/fm-backend-orca.test.sh
@@ -500,11 +500,11 @@ test_spawn_writes_orca_metadata_and_launches_harness() {
   assert_grep "worktree=$wt" "$state/$id.meta" "meta missing Orca worktree path"
   assert_not_contains "$(cat "$log")" $'orca\x1f''terminal'$'\x1f''create' \
     "spawn should reuse the implicit terminal returned by Orca worktree creation"
-  assert_contains "$(cat "$log")" $'orca\x1f''terminal'$'\x1f''send'$'\x1f''--terminal'$'\x1f''term-spawn'$'\x1f''--text'$'\x1f''export GOTMPDIR=/tmp/fm-orcaspawnz1/gotmp'$'\x1f''--enter'$'\x1f''--json' \
+  assert_contains "$(cat "$log")" $'orca\x1f''terminal'$'\x1f''send'$'\x1f''--terminal'$'\x1f''term-spawn'$'\x1f''--text'$'\x1f'"export GOTMPDIR=${FM_TASK_TMP_ROOT:-/tmp}/fm-orcaspawnz1/gotmp"$'\x1f''--enter'$'\x1f''--json' \
     "spawn did not export GOTMPDIR through the Orca terminal"
   assert_contains "$(cat "$log")" "CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false claude --dangerously-skip-permissions" \
     "spawn did not send the selected harness launch command through Orca"
-  rm -rf "/tmp/fm-$id"
+  rm -rf "${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
   pass "fm-spawn.sh --backend orca: reuses implicit terminal, records metadata, launches harness"
 }
 
diff --git a/tests/fm-backend.test.sh b/tests/fm-backend.test.sh
index 6810dae77f..4f9a8fa1a9 100755
--- a/tests/fm-backend.test.sh
+++ b/tests/fm-backend.test.sh
@@ -915,7 +915,7 @@ run_spawn_symlink_case() {  # <label> <physical|logical>
   assert_contains "$out" "worktree=$wt" \
     "fm-spawn.sh did not resolve a symlinked-prefix project to its real worktree when the backend reports $first_reply cwd"
 
-  rm -rf "/tmp/fm-$id"
+  rm -rf "${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
 }
 
 test_spawn_symlinked_project_prefix_avoids_false_refusal() {
@@ -1077,7 +1077,7 @@ test_spawn_default_backend_writes_no_meta_field() {
   expect_code 0 $? "explicit --backend tmux should spawn successfully"$'\n'"$out"
   assert_no_grep 'backend=' "$state/$id.meta" \
     "an explicit --backend tmux (the default) must not write backend= to meta (P1 compatibility contract)"
-  rm -rf "/tmp/fm-$id"
+  rm -rf "${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
   pass "fm-spawn.sh: an explicit --backend tmux resolves silently and writes no backend= (missing means tmux)"
 }
 
@@ -1101,7 +1101,7 @@ test_spawn_explicit_backend_flag_beats_autodetect_herdr_env() {
   expect_code 0 $? "explicit --backend tmux should spawn successfully even with HERDR_ENV=1 set"$'\n'"$out"
   assert_no_grep 'backend=' "$state/$id.meta" \
     "an explicit --backend tmux must win over an ambient HERDR_ENV=1 auto-detect marker"
-  rm -rf "/tmp/fm-$id"
+  rm -rf "${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
   pass "fm-spawn.sh: explicit --backend tmux wins over an ambient HERDR_ENV=1 auto-detect marker"
 }
 
@@ -1131,7 +1131,7 @@ test_spawn_autodetect_nesting_resolves_tmux_silently() {
   case "$out" in
     *NOTICE*) fail "auto-detecting tmux (even nested inside herdr) must stay silent, no NOTICE expected"$'\n'"$out" ;;
   esac
-  rm -rf "/tmp/fm-$id"
+  rm -rf "${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
   pass "fm-spawn.sh: auto-detect resolves nested tmux-in-herdr to tmux and stays silent end to end"
 }
 
diff --git a/tests/fm-gotmp.test.sh b/tests/fm-gotmp.test.sh
index 996d7efa8e..c0d21fc536 100755
--- a/tests/fm-gotmp.test.sh
+++ b/tests/fm-gotmp.test.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Behavior tests for per-task GOTMPDIR support (fm-gotmp).
 #
-# fm-spawn gives each task a temp root /tmp/fm-<id>/ with Go's build temp nested at
+# fm-spawn gives each task a temp root <FM_TASK_TMP_ROOT or /tmp>/fm-<id>/ with Go's build temp nested at
 # gotmp/, exports GOTMPDIR into the crewmate pane, and records tasktmp= in the task's
 # meta. fm-teardown reads tasktmp= and removes the whole root on cleanup.
 #
diff --git a/tests/fm-kimi-harness.test.sh b/tests/fm-kimi-harness.test.sh
index 8c11c314b6..c67fecdd04 100755
--- a/tests/fm-kimi-harness.test.sh
+++ b/tests/fm-kimi-harness.test.sh
@@ -179,7 +179,7 @@ EOF
 test_kimi_launch_then_send_is_verified() {
   local id rec out rc launch pointer brief_real meta task_tmp
   id="kimi-success-z1-$$"
-  task_tmp="/tmp/fm-$id"
+  task_tmp="${FM_TASK_TMP_ROOT:-/tmp}/fm-$id"
   KIMI_RUNTIME_TASK_TMP=$task_tmp
   rm -rf "$task_tmp"
   rec=$(make_spawn_case success "$id")
diff --git a/tests/fm-session-start.test.sh b/tests/fm-session-start.test.sh
index 37b2a3c9c6..ed76b6905b 100755
--- a/tests/fm-session-start.test.sh
+++ b/tests/fm-session-start.test.sh
@@ -29,9 +29,9 @@ SESSION_START="$ROOT/bin/fm-session-start.sh"
 BASE_PATH=${FM_TEST_BASE_PATH:-/usr/bin:/bin:/usr/sbin:/sbin}
 TMP_ROOT=$(fm_test_tmproot fm-session-start-tests)
 SESSION_START_SECOND_MATE_ID="fmtest-sm-${TMP_ROOT##*.}"
-SESSION_START_SECOND_MATE_TMP="/tmp/fm-$SESSION_START_SECOND_MATE_ID"
+SESSION_START_SECOND_MATE_TMP="${FM_TASK_TMP_ROOT:-/tmp}/fm-$SESSION_START_SECOND_MATE_ID"
 SESSION_START_HERDR_SECOND_MATE_ID="fmtest-herdr-${TMP_ROOT##*.}"
-SESSION_START_HERDR_SECOND_MATE_TMP="/tmp/fm-$SESSION_START_HERDR_SECOND_MATE_ID"
+SESSION_START_HERDR_SECOND_MATE_TMP="${FM_TASK_TMP_ROOT:-/tmp}/fm-$SESSION_START_HERDR_SECOND_MATE_ID"
 FM_TEST_CLEANUP_DIRS+=("$TMP_ROOT" "$SESSION_START_SECOND_MATE_TMP" "$SESSION_START_HERDR_SECOND_MATE_TMP")
 trap fm_test_cleanup EXIT
 fm_git_identity fmtest fmtest@example.invalid
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index cfb1578fc4..b0e4c9ca1c 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -567,6 +567,327 @@ assert len(doc["scripts"])==3
   pass "aggregate-json merges lane timing artifacts"
 }
 
+# --- fixture containment and orphan reap ------------------------------------
+#
+# /tmp is a tmpfs on some hosts, so a fixture the suite leaves behind is leaked
+# RAM. These exercise the runner's containment and reap through real runs: a
+# probe script builds a fixture exactly the way the suite does, and the
+# assertions are about what survives on disk afterwards.
+
+# Write a test script that builds one fixture under TMPDIR, records its path to
+# <record>, and then runs <trailer> (empty for a script that just exits).
+write_fixture_probe() {
+  local path=$1 record=$2 trailer=${3:-}
+  cat >"$path" <<SH
+#!/usr/bin/env bash
+set -eu
+probe=\$(mktemp -d "\${TMPDIR:-/tmp}/fm-probe.XXXXXX")
+mkdir -p "\$probe/payload"
+head -c 4096 /dev/zero >"\$probe/payload/blob"
+printf '%s\n' "\$probe" >'$record'
+echo "ok - probe built \$probe"
+$trailer
+SH
+  chmod +x "$path"
+}
+
+# Runner invocation with the nested-run suppression cleared, so a reap actually
+# runs even when this file is itself executing under the runner.
+run_runner_unnested() {
+  env -u FM_TEST_RUN_ACTIVE "$RUNNER" "$@"
+}
+
+test_completed_run_leaves_no_fixture() {
+  local tmp probe record fixture root
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-contain.XXXXXX")
+  probe="$tmp/probe.test.sh"
+  record="$tmp/fixture-path"
+  write_fixture_probe "$probe" "$record"
+  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
+    || fail "probe run should pass: $(cat "$tmp/err")"
+  [ -s "$record" ] || fail "probe did not record its fixture path"
+  fixture=$(cat "$record")
+  case "$fixture" in
+    /tmp/fm-probe.*) fail "fixture was built directly in /tmp, not inside the run: $fixture" ;;
+  esac
+  assert_absent "$fixture" "a completed run must leave no fixture behind: $fixture"
+  # The run root that contained it is gone too, not just the fixture.
+  root=$(dirname "$(dirname "$fixture")")
+  assert_absent "$root" "a completed run must remove its own temp root: $root"
+  rm -rf "$tmp"
+  pass "a run that completes normally leaves no fixture behind"
+}
+
+test_fixture_removed_when_run_is_interrupted() {
+  local tmp probe record fixture root pid waited
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-interrupt.XXXXXX")
+  probe="$tmp/probe.test.sh"
+  record="$tmp/fixture-path"
+  write_fixture_probe "$probe" "$record" 'sleep 120'
+  # Monitor mode puts the background runner in its own process group, so the
+  # signal reaches the runner and the test it is running together - the same
+  # shape as a terminal interrupt, which is how the leak accumulated.
+  set -m
+  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
+  pid=$!
+  set +m
+  waited=0
+  while [ ! -s "$record" ]; do
+    waited=$((waited + 1))
+    [ "$waited" -lt 600 ] || { kill -KILL -- "-$pid" 2>/dev/null; fail "probe never built its fixture"; }
+    sleep 0.1
+  done
+  fixture=$(cat "$record")
+  assert_present "$fixture" "probe fixture should exist while the run is live"
+  kill -INT -- "-$pid" 2>/dev/null || fail "could not interrupt the run"
+  wait "$pid" 2>/dev/null || true
+  waited=0
+  while [ -e "$fixture" ]; do
+    waited=$((waited + 1))
+    [ "$waited" -lt 100 ] || fail "an interrupted run left its fixture behind: $fixture"
+    sleep 0.1
+  done
+  root=$(dirname "$(dirname "$fixture")")
+  assert_absent "$root" "an interrupted run must remove its own temp root: $root"
+  rm -rf "$tmp"
+  pass "a run interrupted mid-way leaves no fixture behind"
+}
+
+test_spawned_task_scratch_is_contained() {
+  local tmp probe record scratch
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-taskscratch.XXXXXX")
+  probe="$tmp/probe.test.sh"
+  record="$tmp/scratch-path"
+  # Mirrors what bin/fm-spawn.sh does for a task: a per-task root with gotmp/
+  # nested inside it, rooted at FM_TASK_TMP_ROOT. A test that drives a real spawn
+  # would otherwise strand this under /tmp with no task and no teardown.
+  cat >"$probe" <<SH
+#!/usr/bin/env bash
+set -eu
+[ -n "\${FM_TASK_TMP_ROOT:-}" ] || { echo "not ok - runner did not set FM_TASK_TMP_ROOT"; exit 1; }
+scratch="\$FM_TASK_TMP_ROOT/fm-probe-task"
+mkdir -p "\$scratch/gotmp"
+printf '%s\n' "\$scratch" >'$record'
+echo "ok - task scratch at \$scratch"
+SH
+  chmod +x "$probe"
+  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
+    || fail "probe run should pass: $(cat "$tmp/err")"
+  [ -s "$record" ] || fail "probe did not record its task scratch root"
+  scratch=$(cat "$record")
+  assert_absent "/tmp/fm-probe-task" "task scratch must never be stranded in /tmp"
+  assert_absent "$scratch" "a completed run must remove the task scratch it created: $scratch"
+  rm -rf "$tmp"
+  pass "a task scratch root created during a run is contained and removed"
+}
+
+test_killed_run_is_healed_by_the_next_run() {
+  local tmp scratch probe record fixture root out pid waited
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-killed.XXXXXX")
+  scratch="$tmp/scratch"
+  mkdir -p "$scratch"
+  probe="$tmp/probe.test.sh"
+  record="$tmp/fixture-path"
+  write_fixture_probe "$probe" "$record" 'sleep 120'
+  # SIGKILL runs no trap at all. This is exactly how the leak accumulated, so
+  # the run root must survive the kill and then be reaped by the next run.
+  set -m
+  TMPDIR="$scratch" run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
+  pid=$!
+  set +m
+  waited=0
+  while [ ! -s "$record" ]; do
+    waited=$((waited + 1))
+    [ "$waited" -lt 600 ] || { kill -KILL -- "-$pid" 2>/dev/null; fail "probe never built its fixture"; }
+    sleep 0.1
+  done
+  fixture=$(cat "$record")
+  kill -KILL -- "-$pid" 2>/dev/null || fail "could not kill the run"
+  wait "$pid" 2>/dev/null || true
+  assert_present "$fixture" "a killed run cannot clean up after itself"
+  root=$(dirname "$(dirname "$fixture")")
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$tmp/plain.test.sh"
+  chmod +x "$tmp/plain.test.sh"
+  out=$(FM_TEST_REAP_ROOT="$scratch" FM_TEST_REAP_MIN_AGE_SECONDS=0 \
+    run_runner_unnested "$tmp/plain.test.sh" 2>"$tmp/err2") \
+    || fail "healing run should pass: $(cat "$tmp/err2")"
+  assert_contains "$out" "removed=1" "the next run should reap the killed run's root: $out"
+  assert_absent "$root" "a killed run's root must be reaped by the next run: $root"
+  assert_absent "$fixture" "the killed run's fixture must be gone with its root: $fixture"
+  rm -rf "$tmp"
+  pass "a killed run's fixtures are reaped by the next run"
+}
+
+# Build an isolated reap root plus a Firstmate home whose recorded task scratch
+# lives inside it. Echoes "<reap root>|<home>".
+init_reap_fixture() {
+  local tmp=$1 reap home
+  reap="$tmp/reap"
+  home="$tmp/home"
+  mkdir -p "$reap" "$home/state"
+  printf '%s|%s\n' "$reap" "$home"
+}
+
+# One aged, fixture-shaped directory inside the reap root.
+make_orphan() {
+  local reap=$1 name=$2
+  mkdir -p "$reap/$name/payload"
+  head -c 2048 /dev/zero >"$reap/$name/payload/blob"
+  touch -t 200001010000 "$reap/$name"
+  printf '%s\n' "$reap/$name"
+}
+
+test_reap_clears_pre_existing_orphans() {
+  local tmp reap home orphan fresh probe out
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  orphan=$(make_orphan "$reap" "fm-secondmate-safety.Ab12Cd")
+  fresh="$reap/fm-recent-run.Zz99Yy"
+  mkdir -p "$fresh"
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || fail "reap run should pass: $(cat "$tmp/err")"
+  assert_contains "$out" "FM_TEST_REAP root=$reap" "reap marker missing"
+  assert_contains "$out" "removed=1" "reap should report the one removed orphan: $out"
+  assert_absent "$orphan" "a pre-existing orphan must be reaped: $orphan"
+  assert_present "$fresh" "a fixture younger than the minimum age must be kept: $fresh"
+  rm -rf "$tmp"
+  pass "a later run reaps pre-existing orphans and spares recent ones"
+}
+
+test_reap_never_touches_a_live_task_scratch() {
+  local tmp reap home tasktmp gotmp probe out
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-task.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  # Fixture-shaped on purpose: only the recorded tasktmp= can save it.
+  tasktmp=$(make_orphan "$reap" "fm-livetask.Qq77Rr")
+  fm_write_meta "$home/state/livetask.meta" \
+    "window=firstmate:fm-livetask" \
+    "worktree=$home/wt" \
+    "project=alpha" \
+    "tasktmp=$tasktmp"
+  # A per-task scratch root is also recognisable by its gotmp/ child.
+  gotmp=$(make_orphan "$reap" "fm-othertask.Ss88Tt")
+  mkdir -p "$gotmp/gotmp"
+  touch -t 200001010000 "$gotmp"
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || fail "reap run should pass: $(cat "$tmp/err")"
+  assert_contains "$out" "removed=0" "no directory should have been removed: $out"
+  assert_present "$tasktmp" "a live task's recorded scratch must never be removed: $tasktmp"
+  assert_present "$tasktmp/payload/blob" "a live task's scratch contents must be intact"
+  assert_present "$gotmp" "a per-task scratch root must never be removed: $gotmp"
+  rm -rf "$tmp"
+  pass "the reap never touches a live task's scratch directory"
+}
+
+test_reap_never_removes_a_held_open_fixture() {
+  local tmp reap home held probe out holder waited
+  if [ ! -r /proc/self/fd ] && ! command -v lsof >/dev/null 2>&1; then
+    pass "held-open fixtures: no in-use inventory on this host, nothing to assert"
+    return 0
+  fi
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-open.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  held=$(make_orphan "$reap" "fm-watcher-lock-tests.Uu66Vv")
+  : >"$held/payload/handle"
+  bash -c 'exec 7<"$1"; printf ready >"$2"; sleep 120' _ "$held/payload/handle" "$tmp/holder-ready" &
+  holder=$!
+  waited=0
+  while [ ! -s "$tmp/holder-ready" ]; do
+    waited=$((waited + 1))
+    [ "$waited" -lt 600 ] || { kill "$holder" 2>/dev/null; fail "holder never opened the fixture"; }
+    sleep 0.1
+  done
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || { kill "$holder" 2>/dev/null; fail "reap run should pass: $(cat "$tmp/err")"; }
+  kill "$holder" 2>/dev/null || true
+  wait "$holder" 2>/dev/null || true
+  assert_contains "$out" "removed=0" "a held-open fixture must not be removed: $out"
+  assert_present "$held" "a directory another process holds open must be kept: $held"
+  rm -rf "$tmp"
+  pass "the reap never removes a fixture another process still holds open"
+}
+
+test_reap_stays_within_fm_fixture_names() {
+  local tmp reap home probe out plain file nosuffix link target
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-scope.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  plain="$reap/unrelated.Ab12Cd"
+  nosuffix="$reap/fm-plainname"
+  file="$reap/fm-a-file.Ab12Cd"
+  target="$tmp/link-target"
+  link="$reap/fm-symlink.Ab12Cd"
+  mkdir -p "$plain" "$nosuffix" "$target"
+  : >"$file"
+  ln -s "$target" "$link"
+  touch -t 200001010000 "$plain" "$nosuffix" "$file" "$target"
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || fail "reap run should pass: $(cat "$tmp/err")"
+  assert_contains "$out" "removed=0" "nothing outside the fixture shape may be removed: $out"
+  assert_present "$plain" "a non-fm- name must never be considered: $plain"
+  assert_present "$nosuffix" "an fm- name without an mktemp suffix must be kept: $nosuffix"
+  assert_present "$file" "a plain file must be kept: $file"
+  assert_present "$link" "a symlink must be kept: $link"
+  assert_present "$target" "a symlink's target must never be followed: $target"
+  rm -rf "$tmp"
+  pass "the reap only considers mktemp-shaped fm- directories in its own root"
+}
+
+test_reap_is_suppressed_inside_a_nested_run() {
+  local tmp reap home orphan probe out
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-nested.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  orphan=$(make_orphan "$reap" "fm-nested.Ww55Xx")
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_RUN_ACTIVE=1 FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    "$RUNNER" "$probe" 2>"$tmp/err") \
+    || fail "nested run should pass: $(cat "$tmp/err")"
+  assert_not_contains "$out" "FM_TEST_REAP" "a nested run must not reap"
+  assert_present "$orphan" "a nested run must leave orphans to its parent: $orphan"
+  rm -rf "$tmp"
+  pass "the reap is suppressed inside a nested run"
+}
+
+test_reap_refuses_when_task_records_cannot_be_read() {
+  local tmp reap home orphan probe out
+  if [ "$(id -u)" = 0 ]; then
+    pass "unreadable task records: root bypasses directory permissions, nothing to assert"
+    return 0
+  fi
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-unreadable.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  orphan=$(make_orphan "$reap" "fm-unreadable.Yy44Zz")
+  chmod 000 "$home/state"
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || { chmod 755 "$home/state"; fail "run should still pass: $(cat "$tmp/err")"; }
+  chmod 755 "$home/state"
+  assert_not_contains "$out" "FM_TEST_REAP" "an unreadable task record must stop the reap entirely"
+  assert_present "$orphan" "nothing may be removed when task records cannot be read: $orphan"
+  rm -rf "$tmp"
+  pass "the reap refuses entirely when a home's task records cannot be read"
+}
+
 test_list_all_exact_suite_coverage
 test_family_selection
 test_single_script_selection
@@ -582,3 +903,13 @@ test_portable_shard_union_and_coverage_guard
 test_jobs_requires_proven_isolated
 test_jobs_parallel_scheduler_and_failure_propagation
 test_aggregate_json
+test_completed_run_leaves_no_fixture
+test_fixture_removed_when_run_is_interrupted
+test_spawned_task_scratch_is_contained
+test_killed_run_is_healed_by_the_next_run
+test_reap_clears_pre_existing_orphans
+test_reap_never_touches_a_live_task_scratch
+test_reap_never_removes_a_held_open_fixture
+test_reap_stays_within_fm_fixture_names
+test_reap_is_suppressed_inside_a_nested_run
+test_reap_refuses_when_task_records_cannot_be_read
diff --git a/tests/lib.sh b/tests/lib.sh
index 66c2a86e4d..7b78d35126 100644
--- a/tests/lib.sh
+++ b/tests/lib.sh
@@ -59,18 +59,27 @@ pass() {
   printf 'ok - %s\n' "$1"
 }
 
-# --- self-cleaning temp root ------------------------------------------------
+# --- temp roots -------------------------------------------------------------
 #
-# fm_test_tmproot <prefix> echoes a fresh temp dir and registers it for removal
-# on EXIT. The first call installs the cleanup trap. A test file that needs
-# extra teardown (e.g. killing a daemon) should define its own EXIT trap and
-# call fm_test_cleanup from inside it so registered dirs are still removed.
+# fm_test_tmproot <prefix> echoes a fresh temp dir under TMPDIR.
 #
-# The EXIT trap cannot run when the test process is killed abruptly, so the dir
-# is orphaned in a temp root every firstmate home on the host shares. The
-# fm- prefix is forced here rather than trusted to each caller so bin/fm-tmp-
-# sweep.sh's session-start reclamation matches every scratch dir this suite has
-# ever created, including ones added after that sweep shipped.
+# bin/fm-test-run.sh is the single owner of fixture cleanup: it points TMPDIR at
+# a private directory for each executed script and removes it when that script
+# finishes, on an interrupted run as well as a normal one, and reaps fixtures
+# orphaned by earlier killed runs. A test file therefore needs no EXIT trap of
+# its own for its temp roots.
+#
+# The fm- prefix is still forced here rather than trusted to each caller, so a
+# fixture that escapes the runner entirely - a direct `bash tests/<name>.test.sh`
+# run killed outright - matches bin/fm-tmp-sweep.sh's session-start reclamation,
+# which is the backstop for scratch the runner never saw.
+#
+# The registration below is only a convenience for a direct
+# `bash tests/<name>.test.sh` run, and it takes effect only when the function is
+# called in this shell: the common `root=$(fm_test_tmproot p)` form runs it in a
+# command-substitution subshell, so the registered array never reaches the
+# caller. A test file that needs extra teardown (e.g. killing a daemon) should
+# define its own EXIT trap and call fm_test_cleanup from inside it.
 
 FM_TEST_CLEANUP_DIRS=()
 

From f6bc6952c44c574037bf2aba6b1d35f53f040f02 Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 01:59:43 -0400
Subject: [PATCH 2/8] refactor(tests): give the scratch reap one owner instead
 of two

PR #10 shipped a bootstrap-time reap of orphaned /tmp scratch while this branch
was stuck, and both ended up implementing the same destructive predicate: name
convention, ownership, age gating, an lsof/procfs open-handle inventory, and
refuse-on-ambiguity. Two copies of "is this scratch dir safe to remove" drift the
moment only one is edited, so bin/fm-tmp-sweep.sh is now the single owner and
bin/fm-test-run.sh delegates to it.

Both trigger points still ship, because they fire at different moments: session
start heals the host on a long horizon, and a test run heals it on a short one.

The sweep gains the protections that previously existed only in the runner, so
the bootstrap sweep is strictly safer than before rather than weakened:

- A directory any discoverable home records as a live task's tasktmp= is never
  removed, nor an ancestor that would take it along. Reading the records also
  fails the sweep as a whole when a home's task records exist but cannot be read,
  which is reported as the new exit status 3 so a caller cannot report a
  completed sweep. A task id is normally not mktemp-shaped and never reaches the
  check, but a dotted one is, and deleting live scratch corrupts running work.
- A per-task scratch root, identified by its gotmp/ child, is never removed.
- --age-minutes expresses the runner's much shorter horizon, and --max bounds how
  many candidates one sweep examines.

The runner keeps only what is genuinely its own: fixture containment through
TMPDIR/TMP/FM_TASK_TMP_ROOT, per-script root removal, and the signal-safe run
root. Its FM_TEST_REAP stdout marker keeps carrying removed=<n>, and the sweep's
per-candidate lines go to stderr with the rest of the runner's logging.

The reap now refuses a tree with a recent write anywhere inside it rather than
only a recent top-level mtime, which is what the sweep already did and is the
stronger check: a long test writes deep in its tree without restamping the root
it was handed. tests/fm-test-run.test.sh's orphan fixture is aged out all the way
down to match.
---
 bin/fm-test-run.sh         | 294 +++++++++----------------------------
 bin/fm-tmp-sweep.sh        | 165 ++++++++++++++++++++-
 tests/fm-test-run.test.sh  |   5 +-
 tests/fm-tmp-sweep.test.sh | 112 ++++++++++++++
 4 files changed, 341 insertions(+), 235 deletions(-)

diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index bec9ef6c1c..3c9741503b 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -60,30 +60,25 @@
 # Orphan reap:
 #   An executing run first reaps fixture directories orphaned by earlier runs
 #   that were killed outright (SIGKILL leaves no trap to run), so a host that
-#   already leaked heals on the next test run. The reap is deliberately narrow
-#   and keeps anything it cannot establish:
-#     - only direct children of the reap root, never a wider glob;
-#     - only names shaped like an mktemp fixture, fm-<prefix>.<6+ alphanumerics>;
-#     - only directories (never symlinks) owned by the current user;
-#     - only entries older than the minimum age, so a concurrent run is safe;
-#     - never a path recorded as tasktmp= by any discoverable Firstmate home,
-#       and never a per-task scratch root (identified by its gotmp/ child);
-#     - never a directory any process still holds open;
-#     - nothing at all if the in-use inventory or a home's task records cannot
-#       be read.
+#   already leaked heals on the next test run. bin/fm-tmp-sweep.sh is the single
+#   owner of which directories are safe to remove and of every refusal that
+#   protects a live task, an in-use directory, or an operational home; this
+#   runner only supplies the shorter age window a test host wants and the homes
+#   this checkout can see. Read that script's header for the full contract.
 #   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MIN_AGE_SECONDS (default
-#   900), FM_TEST_REAP_MAX (default 500), and FM_TEST_REAP_HOMES (extra
-#   colon-separated Firstmate homes whose state/*.meta to read) exist so this
-#   behavior is testable without touching the host's real /tmp.
-#   FM_TEST_RUN_ACTIVE=1 is exported to every executed script and suppresses the
-#   reap in a nested run.
+#   900, rounded up to whole minutes), FM_TEST_REAP_MAX (default 500), and
+#   FM_TEST_REAP_HOMES (extra colon-separated Firstmate homes whose state/*.meta
+#   to read) exist so this behavior is testable without touching the host's real
+#   /tmp. FM_TEST_RUN_ACTIVE=1 is exported to every executed script and
+#   suppresses the reap in a nested run.
 #
 # Per-script machine-parseable markers (stdout):
 #   FM_TEST_BEGIN <iso8601> <script> family=<family> expected_gate_skip=<class>
 #   FM_TEST_END <iso8601> <script> exit=<code> duration_ms=<n> gate_skip=<true|false>
 #
-# Reap marker (stdout, once, executing runs only):
-#   FM_TEST_REAP root=<dir> removed=<n> kept=<n>
+# Reap marker (stdout, once, executing runs only, and never when the sweep
+# refused as a whole):
+#   FM_TEST_REAP root=<dir> removed=<n>
 #
 # After all scripts (stdout):
 #   FM_TEST_SUMMARY total=<n> failed=<n> skipped_gate=<n> duration_ms=<n>
@@ -206,225 +201,72 @@ ensure_run_tmp() {
   exec 9<"$RUN_TMP/.fm-test-run-live"
 }
 
-# One stat field, GNU format first and BSD format second. Prints nothing and
-# fails when neither works, so every caller can treat that as "unknown".
-stat_field() {
-  local gnu=$1 bsd=$2 path=$3 value
-  value=$(stat -c "$gnu" "$path" 2>/dev/null) || value=
-  if [ -z "$value" ]; then
-    value=$(stat -f "$bsd" "$path" 2>/dev/null) || value=
-  fi
-  [ -n "$value" ] || return 1
-  printf '%s\n' "$value"
-}
-
-# True when <name> looks like a directory mktemp -d built from a
-# "fm-<prefix>.XXXXXX" template: the template's random suffix is at least six
-# characters and always alphanumeric. A Firstmate per-task scratch root is
-# /tmp/fm-<task id> with no such suffix, so this alone already separates the two
-# populations; the tasktmp and gotmp checks below cover a task id that happens to
-# end in a matching suffix.
-reap_name_is_fixture() {
-  local name=$1 stem suffix
-  case "$name" in
-    fm-?*.?*) ;;
-    *) return 1 ;;
-  esac
-  stem=${name%.*}
-  suffix=${name##*.}
-  [ "${stem#fm-}" != "" ] || return 1
-  [ "${#suffix}" -ge 6 ] || return 1
-  case "$suffix" in
-    *[!A-Za-z0-9]*) return 1 ;;
-  esac
-  return 0
-}
-
-# Firstmate homes whose state/*.meta may record a live task's scratch root:
-# this checkout, an explicit FM_HOME, the primary checkout this worktree belongs
-# to, extra homes named by FM_TEST_REAP_HOMES, and every secondmate home each of
-# those registers.
-reap_candidate_homes() {
-  local seeded common home extra
-  {
-    printf '%s\n' "$ROOT"
-    [ -z "${FM_HOME:-}" ] || printf '%s\n' "$FM_HOME"
-    common=$(git -C "$ROOT" rev-parse --git-common-dir 2>/dev/null || true)
-    if [ -n "$common" ]; then
-      case "$common" in
-        /*) ;;
-        *) common="$ROOT/$common" ;;
-      esac
-      [ ! -d "$common" ] || printf '%s\n' "$(dirname "$common")"
-    fi
-    if [ -n "${FM_TEST_REAP_HOMES:-}" ]; then
-      while IFS= read -r extra; do
-        [ -n "$extra" ] || continue
-        printf '%s\n' "$extra"
-      done < <(printf '%s\n' "${FM_TEST_REAP_HOMES//:/$'\n'}")
-    fi
-  } | LC_ALL=C sort -u >"$RUN_TMP/reap-homes-seed"
-
-  while IFS= read -r seeded; do
-    [ -n "$seeded" ] || continue
-    printf '%s\n' "$seeded"
-    [ -f "$seeded/data/secondmates.md" ] || continue
-    while IFS= read -r home; do
-      [ -n "$home" ] || continue
-      printf '%s\n' "$home"
-    done < <(sed -n 's/.*(home: *\([^;)]*\).*/\1/p' "$seeded/data/secondmates.md")
-  done <"$RUN_TMP/reap-homes-seed" | LC_ALL=C sort -u
-}
-
-# Every tasktmp= path recorded by a discoverable home. Fails when a home's task
-# records exist but cannot be read, because an unreadable record is exactly the
-# ambiguity that must stop the reap rather than widen it.
-reap_protected_tasktmp() {
-  local home meta rc=0
-  local -a metas
-  while IFS= read -r home; do
-    [ -n "$home" ] || continue
-    [ -d "$home/state" ] || continue
-    if [ ! -r "$home/state" ] || [ ! -x "$home/state" ]; then
-      log "orphan reap skipped: unreadable task records in $home/state"
-      rc=1
-      continue
-    fi
-    metas=()
-    for meta in "$home"/state/*.meta; do
-      [ -f "$meta" ] || continue
-      if [ ! -r "$meta" ]; then
-        log "orphan reap skipped: unreadable task record $meta"
-        rc=1
-        continue
-      fi
-      metas+=("$meta")
-    done
-    # One reader per home rather than one per task record.
-    [ "${#metas[@]}" -eq 0 ] || sed -n 's/^tasktmp=//p' "${metas[@]}"
-  done < <(reap_candidate_homes)
-  return "$rc"
-}
-
-# Absolute paths under <root> that some process still holds: a working
-# directory, an open descriptor, a running executable, or a mapping. /proc is
-# exact and cheap where it exists; lsof covers hosts without it. Fails when
-# neither is available, which keeps the reap from running blind rather than
-# guessing that nothing is in use.
-reap_inuse_paths() {
-  local root=$1 proc link target root_re
-  root_re=$(printf '%s' "$root" | sed 's/[^A-Za-z0-9_/-]/\\&/g')
-  if [ -r /proc/self/fd ] && find /proc/self -maxdepth 0 -printf '' 2>/dev/null; then
-    # One find over the descriptor, cwd, and exe links of every process. A
-    # per-link readlink loop costs seconds on a busy host; this costs
-    # milliseconds.
-    find /proc/[0-9]*/cwd /proc/[0-9]*/exe /proc/[0-9]*/fd/ \
-      -maxdepth 1 -type l -printf '%l\n' 2>/dev/null \
-      | grep -E "^${root_re}(/|\$)" || true
-    grep -haoE "${root_re}/[^[:space:]]+" /proc/[0-9]*/maps 2>/dev/null || true
-    return 0
-  fi
-  if command -v lsof >/dev/null 2>&1; then
-    lsof -n -P -Fn 2>/dev/null | sed -n "s|^n\\(${root}/.*\\)|\\1|p"
-    return 0
-  fi
-  if [ -r /proc/self/fd ]; then
-    for proc in /proc/[0-9]*; do
-      for link in "$proc/cwd" "$proc/exe" "$proc"/fd/*; do
-        target=$(readlink "$link" 2>/dev/null) || continue
-        case "$target" in
-          "$root"/*) printf '%s\n' "$target" ;;
-        esac
-      done
-    done
-    return 0
-  fi
-  return 1
-}
-
-# Remove fixture directories orphaned by earlier killed runs. Every rejection
-# keeps the directory; nothing here removes on a maybe.
+# Reap fixtures orphaned by runs that were killed outright, so a host that has
+# already leaked heals on the next test run.
+#
+# The decision "is this scratch directory safe to remove" lives in exactly one
+# place, bin/fm-tmp-sweep.sh, and this delegates to it rather than keeping a
+# second copy. Session start sweeps the same shared root on a longer horizon;
+# two implementations of a destructive predicate would drift the moment only one
+# was edited. The runner contributes only what it alone knows: the much shorter
+# horizon a test host wants, and which firstmate homes this checkout can see,
+# whose recorded task scratch must never be deleted out from under live work.
 reap_orphan_fixtures() {
-  local root=$REAP_ROOT now uid entry name age mtime owner removed=0 kept=0 examined=0
-  local protected inuse
+  local sweep="$ROOT/bin/fm-tmp-sweep.sh" homes common out line status age_minutes removed
 
+  # A nested run inherits the outer run's root, which the outer run already
+  # swept; sweeping again would only race it.
   [ -z "${FM_TEST_RUN_ACTIVE:-}" ] || return 0
 
-  case "$root" in
-    /*) ;;
-    *) log "orphan reap skipped: reap root must be an absolute path (got '$root')"; return 0 ;;
-  esac
-  if [ -L "$root" ] || [ ! -d "$root" ]; then
-    log "orphan reap skipped: reap root is not a directory: $root"
+  if [ ! -x "$sweep" ]; then
+    log "orphan reap skipped: $sweep is not executable"
     return 0
   fi
   case "$REAP_MIN_AGE_SECONDS" in
-    ''|*[!0-9]*) log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"; return 0 ;;
-  esac
-  case "$REAP_MAX" in
-    ''|*[!0-9]*) log "orphan reap skipped: FM_TEST_REAP_MAX must be a non-negative integer"; return 0 ;;
+    ''|*[!0-9]*)
+      log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"
+      return 0
+      ;;
   esac
-
-  protected="$RUN_TMP/reap-protected"
-  inuse="$RUN_TMP/reap-inuse"
-  if ! reap_protected_tasktmp >"$protected"; then
-    log "orphan reap skipped: could not read every task record, so no directory is safe to remove"
-    return 0
-  fi
-  if ! reap_inuse_paths "$root" >"$inuse"; then
-    log "orphan reap skipped: no way to tell which directories are still in use (no /proc, no lsof)"
-    return 0
+  # Rounded up, so a caller asking for any nonzero age never gets a zero window.
+  age_minutes=$(( (REAP_MIN_AGE_SECONDS + 59) / 60 ))
+
+  # Homes whose state/*.meta may record a live task's scratch root: this
+  # checkout, an explicit FM_HOME, the primary checkout this worktree belongs to,
+  # and any extra homes the caller names. The sweep expands each one's registered
+  # secondmates itself.
+  homes="$ROOT"
+  [ -z "${FM_HOME:-}" ] || homes="$homes:$FM_HOME"
+  common=$(git -C "$ROOT" rev-parse --git-common-dir 2>/dev/null || true)
+  if [ -n "$common" ]; then
+    case "$common" in
+      /*) ;;
+      *) common="$ROOT/$common" ;;
+    esac
+    [ ! -d "$common" ] || homes="$homes:$(dirname "$common")"
   fi
+  [ -z "${FM_TEST_REAP_HOMES:-}" ] || homes="$homes:$FM_TEST_REAP_HOMES"
 
-  now=$(date +%s)
-  uid=$(id -u)
-  for entry in "$root"/fm-*; do
-    [ -e "$entry" ] || continue
-    name=$(basename "$entry")
-    reap_name_is_fixture "$name" || continue
-    if [ "$examined" -ge "$REAP_MAX" ]; then
-      log "orphan reap bounded at $REAP_MAX entries; re-run to continue"
-      break
-    fi
-    examined=$((examined + 1))
-    if [ -L "$entry" ] || [ ! -d "$entry" ]; then
-      kept=$((kept + 1))
-      continue
-    fi
-    if [ -d "$entry/gotmp" ]; then
-      kept=$((kept + 1))
-      continue
-    fi
-    owner=$(stat_field %u %u "$entry") || owner=
-    if [ "$owner" != "$uid" ]; then
-      kept=$((kept + 1))
-      continue
-    fi
-    mtime=$(stat_field %Y %m "$entry") || mtime=
-    case "$mtime" in
-      ''|*[!0-9]*) kept=$((kept + 1)); continue ;;
-    esac
-    age=$((now - mtime))
-    if [ "$age" -lt "$REAP_MIN_AGE_SECONDS" ]; then
-      kept=$((kept + 1))
-      continue
-    fi
-    if grep -qxF "$entry" "$protected"; then
-      kept=$((kept + 1))
-      continue
-    fi
-    if grep -qE "^$(printf '%s' "$entry" | sed 's/[^A-Za-z0-9_/-]/\\&/g')(/|\$)" "$inuse"; then
-      kept=$((kept + 1))
-      continue
-    fi
-    if rm -rf "$entry" 2>/dev/null; then
-      removed=$((removed + 1))
-    else
-      kept=$((kept + 1))
-    fi
-  done
+  out=$("$sweep" --root "$REAP_ROOT" --age-minutes "$age_minutes" \
+    --max "$REAP_MAX" --protect-homes "$homes" 2>&1) && status=0 || status=$?
+
+  removed=0
+  if [ -n "$out" ]; then
+    while IFS= read -r line; do
+      [ -n "$line" ] || continue
+      log "orphan reap: $line"
+      case "$line" in
+        *": removed") removed=$((removed + 1)) ;;
+      esac
+    done <<<"$out"
+  fi
 
-  printf 'FM_TEST_REAP root=%s removed=%s kept=%s\n' "$root" "$removed" "$kept"
+  # Status 3 is the sweep refusing as a whole, so nothing was reaped and this run
+  # must not claim otherwise.
+  [ "$status" -ne 3 ] || return 0
+  # The count stays on stdout with the marker: the sweep's own lines are progress
+  # for a human and go to stderr with the rest of the runner's logging.
+  printf 'FM_TEST_REAP root=%s removed=%s\n' "$REAP_ROOT" "$removed"
 }
 
 # Primary family for one tests/*.test.sh basename. Unmapped scripts are
diff --git a/bin/fm-tmp-sweep.sh b/bin/fm-tmp-sweep.sh
index 9183622975..69e6e944f4 100755
--- a/bin/fm-tmp-sweep.sh
+++ b/bin/fm-tmp-sweep.sh
@@ -12,8 +12,15 @@
 # writes. This sweep is the backstop for that leak; making EXIT traps survive
 # SIGKILL is a separate, much larger problem and is deliberately out of scope.
 #
+# This is the single owner of the "is this scratch directory safe to remove"
+# decision. Both reap trigger points call it rather than reimplementing the
+# checks: bin/fm-bootstrap.sh sweeps at session start, and bin/fm-test-run.sh
+# sweeps at the start of a test run. Keeping one implementation is deliberate -
+# two copies of a destructive predicate drift the moment only one is edited.
+#
 # Usage:
-#   fm-tmp-sweep.sh [--age-hours <n>] [--root <dir>] [--timeout <seconds>]
+#   fm-tmp-sweep.sh [--age-hours <n> | --age-minutes <n>] [--root <dir>]
+#                   [--timeout <seconds>] [--max <n>] [--protect-homes <list>]
 #                   [--dry-run] [--verbose]
 #   fm-tmp-sweep.sh -h | --help
 #
@@ -22,6 +29,7 @@
 #   - its name matches this repo's scratch convention, fm-<slug>.<6 mktemp chars>
 #   - it is a real directory, not a symlink, and is owned by the current user
 #   - it holds neither the current working directory nor FM_HOME
+#   - the sweep has not yet examined --max candidates
 #   - the sweep still has time budget left; once the budget trips, every
 #     remaining candidate is counted and deferred without further probing
 #   - nothing anywhere inside it has been modified within the age window
@@ -29,6 +37,11 @@
 #     marker, or real home content under data/ (backlog.md, projects.md,
 #     secondmates.md). Bare empty state/, data/ and config/ directories are a
 #     common test-fixture shape and are NOT home evidence.
+#   - it is not, and does not contain, a scratch root any discoverable home
+#     records as a live task's tasktmp=, and it carries no per-task gotmp/
+#     marker. A task id is normally not mktemp-shaped so it never reaches this
+#     check, but a dotted task id can be, and deleting a live task's scratch
+#     corrupts running work.
 #   - no live process holds a path inside it open
 # A candidate failing any of those is left exactly as it is; the sweep never
 # forces, never follows symlinks out of the temp root, and never touches a path
@@ -44,11 +57,28 @@
 #   "<root>: skipped: <reason>"   - a whole-sweep limit (open handles could not
 #                                   be checked, time budget exhausted)
 # Healthy skips - young, in use, not ours, not matching - stay silent unless
-# --verbose is passed. Exit status is 0 unless the arguments are invalid.
+# --verbose is passed.
+#
+# Exit status:
+#   0  the sweep ran; individual candidates may still have been skipped
+#   1  the arguments were invalid
+#   3  the sweep refused as a whole before examining anything, because a home's
+#      task records could not be read and a live task's scratch therefore could
+#      not be ruled out. Callers that report a completed sweep must not report
+#      one here. bin/fm-bootstrap.sh ignores the status and classifies output.
 #
 # Environment overrides (defaults are the operating contract; these exist for
 # tests and one-off manual runs, not as a configuration surface):
 #   FM_TMP_SWEEP_AGE_HOURS   age window in hours (default 12)
+#   FM_TMP_SWEEP_AGE_MINUTES age window in minutes; wins over the hours form.
+#                            The test runner sweeps on a much shorter horizon
+#                            than session start, because a fixture orphaned
+#                            minutes ago is already dead weight
+#   FM_TMP_SWEEP_MAX         stop after examining this many candidates
+#                            (default 500); 0 means no bound
+#   FM_TMP_SWEEP_HOMES       extra firstmate homes to read task records from,
+#                            colon-separated. FM_HOME and the secondmate homes
+#                            each discoverable home registers are always read
 #   FM_TMP_SWEEP_ROOT        temp root to sweep (default ${TMPDIR:-/tmp})
 #   FM_TMP_SWEEP_TIMEOUT     whole-sweep time budget in seconds (default 20);
 #                            0 leaves no time for any candidate, so every one
@@ -74,17 +104,23 @@ die() {
 }
 
 AGE_HOURS=${FM_TMP_SWEEP_AGE_HOURS:-12}
+AGE_MINUTES_OPT=${FM_TMP_SWEEP_AGE_MINUTES:-}
 ROOT_DIR=${FM_TMP_SWEEP_ROOT:-${TMPDIR:-/tmp}}
 BUDGET=${FM_TMP_SWEEP_TIMEOUT:-20}
+MAX=${FM_TMP_SWEEP_MAX:-500}
+PROTECT_HOMES=${FM_TMP_SWEEP_HOMES:-}
 PROC_ROOT=${FM_TMP_SWEEP_PROC_ROOT:-/proc}
 DRY_RUN=0
 VERBOSE=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --age-hours) [ $# -ge 2 ] || die "--age-hours needs a value"; AGE_HOURS=$2; shift 2 ;;
+    --age-hours) [ $# -ge 2 ] || die "--age-hours needs a value"; AGE_HOURS=$2; AGE_MINUTES_OPT=; shift 2 ;;
+    --age-minutes) [ $# -ge 2 ] || die "--age-minutes needs a value"; AGE_MINUTES_OPT=$2; shift 2 ;;
     --root) [ $# -ge 2 ] || die "--root needs a value"; ROOT_DIR=$2; shift 2 ;;
     --timeout) [ $# -ge 2 ] || die "--timeout needs a value"; BUDGET=$2; shift 2 ;;
+    --max) [ $# -ge 2 ] || die "--max needs a value"; MAX=$2; shift 2 ;;
+    --protect-homes) [ $# -ge 2 ] || die "--protect-homes needs a value"; PROTECT_HOMES=$2; shift 2 ;;
     --dry-run) DRY_RUN=1; shift ;;
     --verbose) VERBOSE=1; shift ;;
     -h|--help) usage; exit 0 ;;
@@ -98,9 +134,22 @@ esac
 case "$BUDGET" in
   ''|*[!0-9]*) die "timeout must be a non-negative integer, got '$BUDGET'" ;;
 esac
-[ -d "$ROOT_DIR" ] || exit 0
+case "$MAX" in
+  ''|*[!0-9]*) die "max must be a non-negative integer, got '$MAX'" ;;
+esac
 
-AGE_MINUTES=$((AGE_HOURS * 60))
+# The minutes form wins when it is set, so a caller on a short horizon does not
+# have to express itself in whole hours.
+if [ -n "$AGE_MINUTES_OPT" ]; then
+  case "$AGE_MINUTES_OPT" in
+    ''|*[!0-9]*) die "age minutes must be a non-negative integer, got '$AGE_MINUTES_OPT'" ;;
+  esac
+  AGE_MINUTES=$AGE_MINUTES_OPT
+else
+  AGE_MINUTES=$((AGE_HOURS * 60))
+fi
+
+[ -d "$ROOT_DIR" ] || exit 0
 
 note() {
   [ "$VERBOSE" -eq 1 ] || return 0
@@ -159,6 +208,90 @@ looks_like_home() {
   return 1
 }
 
+# --- live task scratch ------------------------------------------------------
+#
+# bin/fm-spawn.sh roots a task's scratch at "${FM_TASK_TMP_ROOT:-/tmp}/fm-<task
+# id>" and records it as tasktmp= in state/<id>.meta. That name normally carries
+# no mktemp suffix, so it never reaches the candidate list at all - but a task id
+# ending in a dot plus six alphanumerics is shaped exactly like a fixture, and
+# removing a live task's scratch corrupts work in flight. Reading the records is
+# cheap next to the probes that follow, and it is the only check that can tell a
+# live task's scratch from an abandoned fixture.
+
+# candidate_homes: the homes whose task records may name a live scratch root -
+# this session's FM_HOME, every home named by --protect-homes, and every
+# secondmate each of those registers.
+candidate_homes() {
+  local seeded home
+  {
+    [ -z "${FM_HOME:-}" ] || printf '%s\n' "$FM_HOME"
+    if [ -n "$PROTECT_HOMES" ]; then
+      printf '%s\n' "${PROTECT_HOMES//:/$'\n'}"
+    fi
+  } | LC_ALL=C sort -u | while IFS= read -r seeded; do
+    [ -n "$seeded" ] || continue
+    printf '%s\n' "$seeded"
+    [ -r "$seeded/data/secondmates.md" ] || continue
+    while IFS= read -r home; do
+      [ -n "$home" ] && printf '%s\n' "$home"
+    done < <(sed -n 's/.*(home: *\([^;)]*\).*/\1/p' "$seeded/data/secondmates.md")
+  done
+}
+
+# protected_tasktmp: every tasktmp= path those homes record. Fails when a home's
+# task records exist but cannot be read: an unreadable record is exactly the
+# ambiguity that must stop the sweep rather than let it delete on a guess.
+protected_tasktmp() {
+  local home meta rc=0
+  local -a metas
+  while IFS= read -r home; do
+    [ -n "$home" ] || continue
+    [ -d "$home/state" ] || continue
+    if [ ! -r "$home/state" ] || [ ! -x "$home/state" ]; then
+      rc=1
+      continue
+    fi
+    metas=()
+    for meta in "$home"/state/*.meta; do
+      [ -f "$meta" ] || continue
+      if [ ! -r "$meta" ]; then
+        rc=1
+        continue
+      fi
+      metas+=("$meta")
+    done
+    [ "${#metas[@]}" -eq 0 ] || sed -n 's/^tasktmp=//p' "${metas[@]}"
+  done < <(candidate_homes | LC_ALL=C sort -u)
+  return "$rc"
+}
+
+PROTECTED_PATHS=
+if ! PROTECTED_PATHS=$(protected_tasktmp); then
+  report "$ROOT_DIR: skipped: a firstmate home's task records could not be read, so no scratch dir is safe to remove"
+  exit 3
+fi
+PROTECTED_PATHS=$'\n'"$PROTECTED_PATHS"$'\n'
+
+# is_live_task_scratch <dir>: true when <dir> is a recorded scratch root, sits
+# inside one, or contains one. All three directions matter: the sweep must not
+# remove a live scratch root, nor an ancestor that would take it with it.
+is_live_task_scratch() {
+  local dir=$1 p
+  case "$PROTECTED_PATHS" in
+    *$'\n'"$dir"$'\n'*) return 0 ;;
+  esac
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    case "$p" in
+      "$dir"/*) return 0 ;;
+    esac
+    case "$dir" in
+      "$p"/*) return 0 ;;
+    esac
+  done <<<"$PROTECTED_PATHS"
+  return 1
+}
+
 # --- open-handle inventory --------------------------------------------------
 #
 # Built at most once per run, and only after a candidate has already cleared the
@@ -311,9 +444,14 @@ for entry in ${candidates[@]+"${candidates[@]}"}; do
   index=$((index + 1))
   name=${entry##*/}
 
-  # Checked before the recursive age walk and the open-handle probe, because
-  # those are the sweep's dominant costs; checking after them would let a root
-  # full of large trees run far past the budget it claims to honour.
+  # Both bounds are checked before the recursive age walk and the open-handle
+  # probe, because those are the sweep's dominant costs; checking after them
+  # would let a root full of large trees run far past the limits it claims to
+  # honour.
+  if [ "$MAX" -gt 0 ] && [ "$index" -gt "$MAX" ]; then
+    deferred=$((total - index + 1))
+    break
+  fi
   if [ "$SECONDS" -ge "$BUDGET" ]; then
     deferred=$((total - index + 1))
     break
@@ -335,6 +473,17 @@ for entry in ${candidates[@]+"${candidates[@]}"}; do
     continue
   fi
 
+  # A per-task scratch root carries a gotmp/ child; a recorded tasktmp= names it
+  # outright. Either one means live work owns this directory.
+  if [ -d "$entry/gotmp" ]; then
+    report "$name: skipped: looks like a live task's scratch root, not a fixture"
+    continue
+  fi
+  if is_live_task_scratch "$entry"; then
+    report "$name: skipped: a firstmate home records it as a live task's scratch root"
+    continue
+  fi
+
   if [ "$CHECKER" != none ] && ! build_in_use_names; then
     CHECKER=none
   fi
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index b0e4c9ca1c..d7b0758494 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -729,11 +729,14 @@ init_reap_fixture() {
 }
 
 # One aged, fixture-shaped directory inside the reap root.
+# The reap refuses a tree with any recent write anywhere inside it, not just a
+# recent top-level mtime, so an orphan fixture has to be aged out all the way
+# down. Deepest paths first: writing or stamping a child restamps its parent.
 make_orphan() {
   local reap=$1 name=$2
   mkdir -p "$reap/$name/payload"
   head -c 2048 /dev/zero >"$reap/$name/payload/blob"
-  touch -t 200001010000 "$reap/$name"
+  touch -t 200001010000 "$reap/$name/payload/blob" "$reap/$name/payload" "$reap/$name"
   printf '%s\n' "$reap/$name"
 }
 
diff --git a/tests/fm-tmp-sweep.test.sh b/tests/fm-tmp-sweep.test.sh
index 04b0d38911..8e5c14c73f 100755
--- a/tests/fm-tmp-sweep.test.sh
+++ b/tests/fm-tmp-sweep.test.sh
@@ -312,6 +312,112 @@ test_missing_root_is_a_silent_no_op() {
   pass "sweep treats an absent temp root as a silent no-op"
 }
 
+# make_home <dir> <task id> <tasktmp>: a firstmate home whose task records name
+# <tasktmp> as a live task's scratch root.
+make_home() {
+  local home=$1 id=$2 tasktmp=$3
+  mkdir -p "$home/state" "$home/data"
+  printf 'window=w\ntasktmp=%s\n' "$tasktmp" > "$home/state/$id.meta"
+  printf '%s\n' "$home"
+}
+
+test_leaves_a_live_tasks_scratch_root() {
+  local root home live orphan out
+  root=$(new_root live-task)
+  # A task id ending in a dot plus six alphanumerics is shaped exactly like a
+  # mktemp fixture, which is the only way a live scratch root reaches the
+  # candidate list at all.
+  live=$(make_stale_dir "$root" fm-report.v2beta)
+  orphan=$(make_stale_dir "$root" fm-teardown-tests.aB3xY9)
+  home=$(make_home "$TMP_ROOT/live-task-home" report.v2beta "$live")
+
+  out=$(run_sweep "$root" --protect-homes "$home")
+  assert_present "$live" "a scratch root a home records as a live task must never be removed"
+  assert_absent "$orphan" "an ordinary orphan beside it must still be reclaimed"
+  assert_contains "$out" "fm-report.v2beta: skipped: a firstmate home records it as a live task's scratch root" \
+    "refusing a live task's scratch must be reported"
+  pass "sweep never removes a scratch root a home records as a live task's"
+}
+
+test_leaves_a_task_scratch_root_carrying_gotmp() {
+  local root dir out
+  root=$(new_root gotmp)
+  dir=$(make_stale_dir "$root" fm-someid.aB3xY9)
+  mkdir -p "$dir/gotmp"
+  age_out "$dir/gotmp" "$dir"
+
+  out=$(run_sweep "$root")
+  assert_present "$dir" "a per-task scratch root carrying gotmp/ must never be removed"
+  assert_contains "$out" "fm-someid.aB3xY9: skipped: looks like a live task's scratch root" \
+    "refusing a per-task scratch root must be reported"
+  pass "sweep never removes a per-task scratch root carrying gotmp/"
+}
+
+test_refuses_when_task_records_cannot_be_read() {
+  local root home dir out
+  if [ "$(id -u)" = 0 ]; then
+    pass "unreadable task records: root bypasses directory permissions, nothing to assert"
+    return 0
+  fi
+  root=$(new_root unreadable-records)
+  dir=$(make_stale_dir "$root" fm-teardown-tests.aB3xY9)
+  home=$(make_home "$TMP_ROOT/unreadable-home" sometask /nowhere)
+  chmod 000 "$home/state"
+
+  out=$(run_sweep "$root" --protect-homes "$home")
+  chmod 755 "$home/state"
+  assert_present "$dir" \
+    "an unreadable task record must stop the sweep rather than let it guess"
+  assert_contains "$out" "task records could not be read" \
+    "refusing on unreadable task records must say so"
+  pass "sweep refuses entirely when a home's task records cannot be read"
+}
+
+test_reads_secondmate_homes_for_live_scratch() {
+  local root primary second live out
+  root=$(new_root secondmate-task)
+  live=$(make_stale_dir "$root" fm-second.aB3xY9)
+  second=$(make_home "$TMP_ROOT/second-home" second.aB3xY9 "$live")
+  primary="$TMP_ROOT/primary-home"
+  mkdir -p "$primary/data" "$primary/state"
+  printf -- '- second (home: %s; scope: things)\n' "$second" > "$primary/data/secondmates.md"
+
+  out=$(run_sweep "$root" --protect-homes "$primary")
+  assert_present "$live" \
+    "a live task recorded by a registered secondmate home must be protected too"
+  assert_contains "$out" "fm-second.aB3xY9: skipped: a firstmate home records it" \
+    "protecting a secondmate's live task must be reported"
+  pass "sweep reads registered secondmate homes for live task scratch"
+}
+
+test_age_minutes_window() {
+  local root recent out
+  root=$(new_root age-minutes)
+  recent=$(make_fresh_dir "$root" fm-recent.aB3xY9)
+  # Ten minutes old: stale under a 5-minute window, fresh under the 12h default.
+  touch -d '10 minutes ago' "$recent/nested/payload" "$recent/nested" "$recent" 2>/dev/null \
+    || touch -A -001000 "$recent/nested/payload" "$recent/nested" "$recent"
+
+  out=$(run_sweep "$root" --age-minutes 5)
+  assert_absent "$recent" "a dir past the minutes window must be reclaimed"
+  assert_contains "$out" "fm-recent.aB3xY9: removed" "the minutes window must report its removal"
+  pass "sweep honours a minutes-granularity age window"
+}
+
+test_max_bounds_the_examination() {
+  local root out i
+  root=$(new_root max-bound)
+  for i in 1 2 3; do
+    make_stale_dir "$root" "fm-bounded$i.aB3xY9" >/dev/null
+  done
+
+  out=$(run_sweep "$root" --max 1)
+  [ "$(find "$root" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 2 ] \
+    || fail "--max 1 must examine exactly one candidate and defer the rest"
+  assert_contains "$out" "deferred" "a bounded sweep must say what it deferred"
+  pass "sweep stops after --max candidates and defers the rest"
+}
+
 test_removes_stale_scratch_dir
 test_leaves_fresh_scratch_dir
 test_leaves_dir_with_recent_deep_write
@@ -328,5 +434,11 @@ test_dry_run_reports_without_removing
 test_age_window_is_configurable
 test_rejects_invalid_arguments
 test_missing_root_is_a_silent_no_op
+test_leaves_a_live_tasks_scratch_root
+test_leaves_a_task_scratch_root_carrying_gotmp
+test_refuses_when_task_records_cannot_be_read
+test_reads_secondmate_homes_for_live_scratch
+test_age_minutes_window
+test_max_bounds_the_examination
 
 echo "all fm-tmp-sweep tests passed"

From 5e6fd8bb2aaa187099001a7f60ac92462de48146 Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 02:55:14 -0400
Subject: [PATCH 3/8] docs(contributing): point fixture cleanup at the reap's
 real owner

The reap's safety rules moved to bin/fm-tmp-sweep.sh when the runner stopped
keeping a second copy of them, so the cross-reference has to follow.
---
 CONTRIBUTING.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c6da486673..10f48709b7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -98,7 +98,8 @@ CI owns broad regression across required portable parallel shards, the portable
 Use `bin/fm-test-run.sh --help` for lane names, `--jobs` rules, and required gate-skip flags when reproducing a lane locally.
 Discover tests by listing `tests/*.test.sh`: each is a self-contained bash script named `<subject>.test.sh`, and its header comment describes what it covers, so pass one to `bin/fm-test-run.sh` to focus on a subject with canonical timing output.
 The runner is also the single owner of fixture cleanup: it gives every executed script a private `TMPDIR` and removes it when that script finishes, on an interrupted run as well as a normal one, and it reaps fixture directories orphaned by earlier killed runs, so a new test needs no temp-root `EXIT` trap of its own.
-That matters because `/tmp` is a tmpfs on some hosts, where a leaked fixture is leaked RAM rather than disk; the runner's header owns the reap's safety rules and its test-only environment seams.
+That matters because `/tmp` is a tmpfs on some hosts, where a leaked fixture is leaked RAM rather than disk.
+`bin/fm-tmp-sweep.sh` is the single owner of which orphaned scratch directories are safe to remove, for both the runner's reap and the session-start sweep, and the runner's header owns its own test-only environment seams.
 Tests that need a real optional backend or an explicit opt-in (real herdr/zellij/cmux smoke tests, the live Pi regression) skip themselves and print the tool or environment gate needed to enable them, so the portable suite remains safe on machines without those tools.
 The [Herdr backend guide](docs/herdr-backend.md#destructive-lab-safety) owns the lane's isolation boundary, while [runtime backend verification](docs/verification/runtime-backends.md#herdr) owns active empirical evidence; live harness credential tests remain opt-in.
 

From f07d85deaac8a683b2ede2e25db8da1d1ff0cfe5 Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 09:37:25 -0400
Subject: [PATCH 4/8] fix(tests): stop worker children before removing the run
 root

A signal aimed at the runner alone - what a supervisor or `timeout` produces -
left the --jobs worker subshells running. A child kept executing against a
TMPDIR that had just been removed and recreated the run root underneath the
cleanup, leaving exactly the orphan this runner exists to prevent.

Stop this run's worker process tree first, then remove the root. The tree is
walked breadth-first from one ps snapshot so the walk cannot chase pids that
appear mid-scan, descendants are polled rather than the worker subshells
themselves (a direct child is a zombie between its death and the wait, and
would hold the deadline open), and anything still alive is killed.

The array guard is subscripted. Worker slots are numbered from 1, so an
unsubscripted ${WORKER_PIDS+x} asks about element 0 and is empty for every
populated run, which made the guard inert exactly when it had work to do.

The regression test drives a real --jobs run whose workers rebuild a directory
under their own TMPDIR, signals the runner PID alone, and fails if anything
survives in the temp root. Without the fix it reports the leaked run root.
---
 bin/fm-test-run.sh        | 77 +++++++++++++++++++++++++++++++++++++--
 tests/fm-test-run.test.sh | 75 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+), 3 deletions(-)

diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 3c9741503b..d06542ef1d 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -172,13 +172,84 @@ remove_run_tmp() {
   rm -rf "$doomed" 2>/dev/null || true
 }
 
-# Remove the run root, then die from the same signal so a caller (a shell, CI,
-# or a supervising script) still sees a normal signal death rather than a
-# swallowed interrupt.
+# Every pid in the process tree rooted at the given pids, walked breadth-first
+# from one ps snapshot so the walk cannot chase pids that appear mid-scan.
+# shellcheck disable=SC2329 # Called from stop_run_workers below.
+run_process_tree_pids() {
+  local table=$1 frontier=" $2 " found=" $2 " next pid ppid
+  while [ -n "${frontier// /}" ]; do
+    next=
+    while read -r pid ppid; do
+      [ -n "$pid" ] || continue
+      case "$frontier" in *" $ppid "*) ;; *) continue ;; esac
+      case "$found" in *" $pid "*) continue ;; esac
+      found="$found$pid "
+      next="$next$pid "
+    done <<<"$table"
+    frontier=" $next"
+  done
+  printf '%s\n' "$found"
+}
+
+# Stop the worker subshells this run started, and the scripts they launched,
+# before the run root is removed. Otherwise a child keeps executing against a
+# deleted TMPDIR and can recreate the run root after the removal, leaving
+# exactly the orphan this runner exists to prevent.
+# shellcheck disable=SC2329 # Called from on_run_signal below.
+stop_run_workers() {
+  local slot pid roots table tree waited alive
+  # Worker slots are numbered from 1, so the array must be tested through a
+  # subscript: an unsubscripted ${WORKER_PIDS+x} asks about element 0 and is
+  # empty for every populated run, and for the serial path that never declares
+  # the array at all.
+  [ -n "${WORKER_PIDS[*]+x}" ] || return 0
+  roots=
+  for slot in "${!WORKER_PIDS[@]}"; do
+    pid=${WORKER_PIDS[$slot]}
+    [ -n "$pid" ] || continue
+    roots="$roots $pid"
+  done
+  [ -n "${roots// /}" ] || return 0
+  table=$(ps -eo pid=,ppid= 2>/dev/null || true)
+  if [ -n "$table" ]; then
+    tree=$(run_process_tree_pids "$table" "${roots# }")
+  else
+    tree=$roots
+  fi
+  for pid in $tree; do
+    kill -s TERM "$pid" 2>/dev/null || true
+  done
+  # Poll the descendants only: a worker subshell is a direct child of this
+  # shell, so between its death and the wait below it is a zombie that still
+  # answers kill -0 and would hold this loop open for the whole deadline.
+  waited=0
+  while [ "$waited" -lt 40 ]; do
+    alive=0
+    for pid in $tree; do
+      case " $roots " in *" $pid "*) continue ;; esac
+      if kill -0 "$pid" 2>/dev/null; then
+        alive=1
+        break
+      fi
+    done
+    [ "$alive" -eq 1 ] || break
+    waited=$((waited + 1))
+    sleep 0.05
+  done
+  for pid in $tree; do
+    kill -s KILL "$pid" 2>/dev/null || true
+  done
+  wait 2>/dev/null || true
+}
+
+# Stop this run's children, remove the run root, then die from the same signal
+# so a caller (a shell, CI, or a supervising script) still sees a normal signal
+# death rather than a swallowed interrupt.
 # shellcheck disable=SC2329 # Registered by the signal traps below.
 on_run_signal() {
   local sig=$1
   trap - EXIT INT TERM HUP QUIT
+  stop_run_workers
   remove_run_tmp
   kill -s "$sig" "$$" 2>/dev/null || true
   exit 1
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index d7b0758494..d110def696 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -718,6 +718,80 @@ test_killed_run_is_healed_by_the_next_run() {
   pass "a killed run's fixtures are reaped by the next run"
 }
 
+# Backstop for the looping worker fixtures below, so a failing assertion cannot
+# strand them. Targets the run's own process group by PID rather than a command
+# name, which cannot reach a process this test did not start. Always succeeds:
+# an already-empty group is the expected outcome.
+reap_stray_workers() {
+  local pid=$1
+  kill -KILL -- "-$pid" 2>/dev/null || true
+  return 0
+}
+
+test_signalled_jobs_run_stops_its_workers() {
+  local tmp repo runner reap runtmp a b f pid waited live leftover
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-jobs-signal.XXXXXX")
+  repo="$tmp/repo"
+  runner="$repo/bin/fm-test-run.sh"
+  reap="$tmp/reap"
+  runtmp="$tmp/runtmp"
+  a=tests/fm-brief.test.sh
+  b=tests/fm-composer-lib.test.sh
+  mkdir -p "$repo/bin" "$repo/tests" "$reap" "$runtmp"
+  cp "$RUNNER" "$runner"
+  chmod +x "$runner"
+  # Each worker script keeps rebuilding a directory under its own TMPDIR, so a
+  # child still running when the run root is removed recreates that root - the
+  # orphan this runner exists to prevent, and the one a signal aimed at the
+  # runner alone used to produce.
+  for f in "$a" "$b"; do
+    # shellcheck disable=SC2016 # $TMPDIR must be expanded by the worker, not here.
+    printf '#!/usr/bin/env bash\nwhile :; do mkdir -p "$TMPDIR/live"; sleep 0.05; done\n' \
+      >"$repo/$f"
+    chmod +x "$repo/$f"
+  done
+  # Monitor mode only so the run owns a process group this test can clean up by
+  # PID. The signal below still goes to the runner PID alone, never the group -
+  # that is the case a supervisor or `timeout` produces, and the one where the
+  # workers used to outlive the removal of their TMPDIR.
+  set -m
+  TMPDIR="$runtmp" FM_TEST_REAP_ROOT="$reap" \
+    env -u FM_TEST_RUN_ACTIVE "$runner" --jobs 2 "$a" "$b" >"$tmp/out" 2>"$tmp/err" &
+  pid=$!
+  set +m
+  waited=0
+  live=
+  while [ -z "$live" ]; do
+    for f in "$runtmp"/fm-test-run.*/w*/tmp/live; do
+      [ -d "$f" ] || continue
+      live=$f
+      break
+    done
+    [ -n "$live" ] && break
+    waited=$((waited + 1))
+    if [ "$waited" -ge 600 ]; then
+      kill -KILL "$pid" 2>/dev/null || true
+      reap_stray_workers "$pid"
+      rm -rf "$tmp"
+      fail "workers never started under --jobs"
+    fi
+    sleep 0.1
+  done
+  kill -TERM "$pid" 2>/dev/null || fail "could not signal the run"
+  wait "$pid" 2>/dev/null || true
+  # Long enough for any child that outlived the runner to rebuild what the
+  # removal took away.
+  sleep 1
+  leftover=$(ls -A "$runtmp" 2>/dev/null || true)
+  reap_stray_workers "$pid"
+  if [ -n "$leftover" ]; then
+    rm -rf "$tmp"
+    fail "a signalled --jobs run left its run root behind: $leftover"
+  fi
+  rm -rf "$tmp"
+  pass "a signalled --jobs run stops its workers before removing the run root"
+}
+
 # Build an isolated reap root plus a Firstmate home whose recorded task scratch
 # lives inside it. Echoes "<reap root>|<home>".
 init_reap_fixture() {
@@ -910,6 +984,7 @@ test_completed_run_leaves_no_fixture
 test_fixture_removed_when_run_is_interrupted
 test_spawned_task_scratch_is_contained
 test_killed_run_is_healed_by_the_next_run
+test_signalled_jobs_run_stops_its_workers
 test_reap_clears_pre_existing_orphans
 test_reap_never_touches_a_live_task_scratch
 test_reap_never_removes_a_held_open_fixture

From 9aeaedb234917fd0729652acc10197ae335c4adf Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 12:00:02 -0400
Subject: [PATCH 5/8] no-mistakes(review): harden the scratch reap's bounds,
 horizon, and abort path

---
 bin/fm-spawn.sh            |   9 ++-
 bin/fm-test-run.sh         |  81 ++++++++++++++++++---------
 bin/fm-tmp-sweep.sh        |  81 ++++++++++++++++++++++-----
 tests/fm-test-run.test.sh  | 109 +++++++++++++++++++++++++++++++++++--
 tests/fm-tmp-sweep.test.sh |  84 +++++++++++++++++++++++++++-
 5 files changed, 315 insertions(+), 49 deletions(-)

diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh
index 4d70237013..eb5ccaac53 100755
--- a/bin/fm-spawn.sh
+++ b/bin/fm-spawn.sh
@@ -1330,7 +1330,14 @@ fi
 # real path is unchanged. bin/fm-test-run.sh sets it to the executed script's
 # private temp root: a test that drives a real spawn would otherwise leave a
 # /tmp/fm-<fixture id>/ behind with no task and no teardown to remove it, and on
-# a tmpfs /tmp that residue is held in RAM.
+# a tmpfs /tmp that residue is held in RAM. It must be absolute: this path is
+# recorded as tasktmp= and reaches an unguarded rm -rf in bin/fm-teardown.sh,
+# which would resolve a relative value against whatever directory teardown
+# happens to run in.
+case "${FM_TASK_TMP_ROOT:-/tmp}" in
+  /*) ;;
+  *) echo "error: FM_TASK_TMP_ROOT must be an absolute path, got '$FM_TASK_TMP_ROOT'" >&2; exit 1 ;;
+esac
 TASK_TMP="${FM_TASK_TMP_ROOT:-/tmp}/fm-$ID"
 mkdir -p "$TASK_TMP/gotmp"
 
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index d06542ef1d..17c902b85f 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -62,15 +62,19 @@
 #   that were killed outright (SIGKILL leaves no trap to run), so a host that
 #   already leaked heals on the next test run. bin/fm-tmp-sweep.sh is the single
 #   owner of which directories are safe to remove and of every refusal that
-#   protects a live task, an in-use directory, or an operational home; this
-#   runner only supplies the shorter age window a test host wants and the homes
-#   this checkout can see. Read that script's header for the full contract.
-#   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MIN_AGE_SECONDS (default
-#   900, rounded up to whole minutes), FM_TEST_REAP_MAX (default 500), and
+#   protects a live task, an in-use directory, or an operational home, including
+#   the age window; this runner supplies only the candidate cap a test host
+#   wants and the homes this checkout can see. Read that script's header for the
+#   full contract. The sweep's own conservative age window applies unchanged: a
+#   shorter one would shorten the destructive horizon for scratch owned by other
+#   live firstmate tooling in the same shared root, and containment plus the
+#   signal traps above already cover this runner's own fixtures.
+#   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MAX (default 500),
 #   FM_TEST_REAP_HOMES (extra colon-separated Firstmate homes whose state/*.meta
-#   to read) exist so this behavior is testable without touching the host's real
-#   /tmp. FM_TEST_RUN_ACTIVE=1 is exported to every executed script and
-#   suppresses the reap in a nested run.
+#   to read), and FM_TEST_REAP_MIN_AGE_SECONDS (unset by default; when set,
+#   rounded up to whole minutes and passed to the sweep) exist so this behavior
+#   is testable without touching the host's real /tmp. FM_TEST_RUN_ACTIVE=1 is
+#   exported to every executed script and suppresses the reap in a nested run.
 #
 # Per-script machine-parseable markers (stdout):
 #   FM_TEST_BEGIN <iso8601> <script> family=<family> expected_gate_skip=<class>
@@ -155,7 +159,9 @@ now_ms() {
 # --- run root, fixture containment, and orphan reap -------------------------
 
 REAP_ROOT=${FM_TEST_REAP_ROOT:-/tmp}
-REAP_MIN_AGE_SECONDS=${FM_TEST_REAP_MIN_AGE_SECONDS:-900}
+# Unset means "use the sweep's own window", which is the operating contract. It
+# is a test seam, not a knob this runner turns.
+REAP_MIN_AGE_SECONDS=${FM_TEST_REAP_MIN_AGE_SECONDS:-}
 REAP_MAX=${FM_TEST_REAP_MAX:-500}
 # Descriptor 9 is held open inside the run root for its whole life. A concurrent
 # runner's reap sees this open file and keeps the root, which is what makes the
@@ -242,9 +248,21 @@ stop_run_workers() {
   wait 2>/dev/null || true
 }
 
+# Every exit removes the run root, and every exit must stop this run's children
+# first. A signal is not the only way to leave with workers still in flight: any
+# `die` or set -e abort during dispatch does the same, and a surviving child
+# then recreates the run root through its own TMPDIR after the removal. On the
+# normal path every worker slot is already unset, so this costs nothing.
+# shellcheck disable=SC2329 # Registered by the EXIT trap below.
+on_run_exit() {
+  stop_run_workers
+  remove_run_tmp
+}
+
 # Stop this run's children, remove the run root, then die from the same signal
 # so a caller (a shell, CI, or a supervising script) still sees a normal signal
-# death rather than a swallowed interrupt.
+# death rather than a swallowed interrupt. The EXIT trap is cleared first, so
+# the workers are stopped once, not twice.
 # shellcheck disable=SC2329 # Registered by the signal traps below.
 on_run_signal() {
   local sig=$1
@@ -262,12 +280,14 @@ ensure_run_tmp() {
   [ -z "$RUN_TMP" ] || return 0
   RUN_TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run.XXXXXX") \
     || die "could not create a run temp root"
-  chmod 0700 "$RUN_TMP" || die "could not chmod 0700 run temp root $RUN_TMP"
-  trap 'remove_run_tmp' EXIT
+  # Armed before anything else can fail, so even a die between here and the
+  # first script still takes the root with it.
+  trap 'on_run_exit' EXIT
   trap 'on_run_signal INT' INT
   trap 'on_run_signal TERM' TERM
   trap 'on_run_signal HUP' HUP
   trap 'on_run_signal QUIT' QUIT
+  chmod 0700 "$RUN_TMP" || die "could not chmod 0700 run temp root $RUN_TMP"
   : >"$RUN_TMP/.fm-test-run-live"
   exec 9<"$RUN_TMP/.fm-test-run-live"
 }
@@ -277,13 +297,17 @@ ensure_run_tmp() {
 #
 # The decision "is this scratch directory safe to remove" lives in exactly one
 # place, bin/fm-tmp-sweep.sh, and this delegates to it rather than keeping a
-# second copy. Session start sweeps the same shared root on a longer horizon;
-# two implementations of a destructive predicate would drift the moment only one
-# was edited. The runner contributes only what it alone knows: the much shorter
-# horizon a test host wants, and which firstmate homes this checkout can see,
-# whose recorded task scratch must never be deleted out from under live work.
+# second copy. Two implementations of a destructive predicate would drift the
+# moment only one was edited. The runner contributes only what it alone knows: a
+# bound on how much work one test run should spend reclaiming, and which
+# firstmate homes this checkout can see, whose recorded task scratch must never
+# be deleted out from under live work. The age window is the sweep's own, not
+# this runner's: /tmp is shared with other live firstmate tooling, and a shorter
+# window here would put that tooling's scratch at risk to heal something
+# containment and the signal traps already handle.
 reap_orphan_fixtures() {
-  local sweep="$ROOT/bin/fm-tmp-sweep.sh" homes common out line status age_minutes removed
+  local sweep="$ROOT/bin/fm-tmp-sweep.sh" homes common out line status removed
+  local -a age_args=()
 
   # A nested run inherits the outer run's root, which the outer run already
   # swept; sweeping again would only race it.
@@ -293,14 +317,17 @@ reap_orphan_fixtures() {
     log "orphan reap skipped: $sweep is not executable"
     return 0
   fi
-  case "$REAP_MIN_AGE_SECONDS" in
-    ''|*[!0-9]*)
-      log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"
-      return 0
-      ;;
-  esac
-  # Rounded up, so a caller asking for any nonzero age never gets a zero window.
-  age_minutes=$(( (REAP_MIN_AGE_SECONDS + 59) / 60 ))
+  if [ -n "$REAP_MIN_AGE_SECONDS" ]; then
+    case "$REAP_MIN_AGE_SECONDS" in
+      *[!0-9]*)
+        log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"
+        return 0
+        ;;
+    esac
+    # Rounded up, so a caller asking for any nonzero age never gets a zero
+    # window. Unset leaves the window to the sweep, which is the normal path.
+    age_args=(--age-minutes "$(( (REAP_MIN_AGE_SECONDS + 59) / 60 ))")
+  fi
 
   # Homes whose state/*.meta may record a live task's scratch root: this
   # checkout, an explicit FM_HOME, the primary checkout this worktree belongs to,
@@ -318,7 +345,7 @@ reap_orphan_fixtures() {
   fi
   [ -z "${FM_TEST_REAP_HOMES:-}" ] || homes="$homes:$FM_TEST_REAP_HOMES"
 
-  out=$("$sweep" --root "$REAP_ROOT" --age-minutes "$age_minutes" \
+  out=$("$sweep" --root "$REAP_ROOT" ${age_args[@]+"${age_args[@]}"} \
     --max "$REAP_MAX" --protect-homes "$homes" 2>&1) && status=0 || status=$?
 
   removed=0
diff --git a/bin/fm-tmp-sweep.sh b/bin/fm-tmp-sweep.sh
index 69e6e944f4..bbee928660 100755
--- a/bin/fm-tmp-sweep.sh
+++ b/bin/fm-tmp-sweep.sh
@@ -55,7 +55,8 @@
 #                                   really an operational home) or failed to
 #                                   remove
 #   "<root>: skipped: <reason>"   - a whole-sweep limit (open handles could not
-#                                   be checked, time budget exhausted)
+#                                   be checked, time budget exhausted, the
+#                                   --max candidate cap reached)
 # Healthy skips - young, in use, not ours, not matching - stay silent unless
 # --verbose is passed.
 #
@@ -71,11 +72,14 @@
 # tests and one-off manual runs, not as a configuration surface):
 #   FM_TMP_SWEEP_AGE_HOURS   age window in hours (default 12)
 #   FM_TMP_SWEEP_AGE_MINUTES age window in minutes; wins over the hours form.
-#                            The test runner sweeps on a much shorter horizon
-#                            than session start, because a fixture orphaned
-#                            minutes ago is already dead weight
+#                            Exists for a caller that cannot express its window
+#                            in whole hours; no caller shortens the default
 #   FM_TMP_SWEEP_MAX         stop after examining this many candidates
-#                            (default 500); 0 means no bound
+#                            (default 0, meaning unbounded). A caller that
+#                            wants a bound passes --max: session start must
+#                            reclaim everything it can, so bounding it by
+#                            default would strand orphans on the very host that
+#                            leaked the most
 #   FM_TMP_SWEEP_HOMES       extra firstmate homes to read task records from,
 #                            colon-separated. FM_HOME and the secondmate homes
 #                            each discoverable home registers are always read
@@ -107,7 +111,7 @@ AGE_HOURS=${FM_TMP_SWEEP_AGE_HOURS:-12}
 AGE_MINUTES_OPT=${FM_TMP_SWEEP_AGE_MINUTES:-}
 ROOT_DIR=${FM_TMP_SWEEP_ROOT:-${TMPDIR:-/tmp}}
 BUDGET=${FM_TMP_SWEEP_TIMEOUT:-20}
-MAX=${FM_TMP_SWEEP_MAX:-500}
+MAX=${FM_TMP_SWEEP_MAX:-0}
 PROTECT_HOMES=${FM_TMP_SWEEP_HOMES:-}
 PROC_ROOT=${FM_TMP_SWEEP_PROC_ROOT:-/proc}
 DRY_RUN=0
@@ -145,8 +149,10 @@ if [ -n "$AGE_MINUTES_OPT" ]; then
     ''|*[!0-9]*) die "age minutes must be a non-negative integer, got '$AGE_MINUTES_OPT'" ;;
   esac
   AGE_MINUTES=$AGE_MINUTES_OPT
+  AGE_WINDOW="${AGE_MINUTES}m"
 else
   AGE_MINUTES=$((AGE_HOURS * 60))
+  AGE_WINDOW="${AGE_HOURS}h"
 fi
 
 [ -d "$ROOT_DIR" ] || exit 0
@@ -218,11 +224,17 @@ looks_like_home() {
 # cheap next to the probes that follow, and it is the only check that can tell a
 # live task's scratch from an abandoned fixture.
 
+# Emitted by candidate_homes in place of a home it could not enumerate. The
+# discovery walk runs inside a pipeline, so an exit status cannot reach the
+# caller; the failure has to travel as a line. No real home path can collide
+# with it.
+HOME_SCAN_FAILED='!fm-tmp-sweep: a home registry could not be read'
+
 # candidate_homes: the homes whose task records may name a live scratch root -
 # this session's FM_HOME, every home named by --protect-homes, and every
 # secondmate each of those registers.
 candidate_homes() {
-  local seeded home
+  local seeded home registry
   {
     [ -z "${FM_HOME:-}" ] || printf '%s\n' "$FM_HOME"
     if [ -n "$PROTECT_HOMES" ]; then
@@ -231,21 +243,55 @@ candidate_homes() {
   } | LC_ALL=C sort -u | while IFS= read -r seeded; do
     [ -n "$seeded" ] || continue
     printf '%s\n' "$seeded"
-    [ -r "$seeded/data/secondmates.md" ] || continue
+    registry="$seeded/data/secondmates.md"
+    # An unreadable registry hides a whole class of homes, so every live task
+    # those homes record goes unseen - the same ambiguity as an unreadable task
+    # record, and it must stop the sweep the same way. A registry that simply
+    # is not there says the home has no secondmates, which is not ambiguous.
+    # An unsearchable data/ is indistinguishable from a missing registry by
+    # test alone, so it is checked first.
+    if [ -d "$seeded/data" ] && [ ! -x "$seeded/data" ]; then
+      printf '%s\n' "$HOME_SCAN_FAILED"
+      continue
+    fi
+    if [ ! -r "$registry" ]; then
+      if [ -e "$registry" ] || [ -L "$registry" ]; then
+        printf '%s\n' "$HOME_SCAN_FAILED"
+      fi
+      continue
+    fi
     while IFS= read -r home; do
       [ -n "$home" ] && printf '%s\n' "$home"
-    done < <(sed -n 's/.*(home: *\([^;)]*\).*/\1/p' "$seeded/data/secondmates.md")
+    done < <(sed -n 's/.*(home: *\([^;)]*\).*/\1/p' "$registry")
   done
 }
 
+# emit_protected_path <recorded>: a recorded tasktmp= value in every form a
+# candidate could be compared against. Candidates are always ROOT_PHYS-prefixed,
+# so a recorded path written through a symlinked temp root - /tmp on macOS -
+# never matches verbatim and the protection would be inert. The recorded value
+# is kept alongside the resolved one: a scratch root that has already gone means
+# resolution fails, and dropping it there would silently unprotect it.
+emit_protected_path() {
+  local recorded=$1 phys
+  [ -n "$recorded" ] || return 0
+  printf '%s\n' "$recorded"
+  phys=$(resolve_phys "$recorded") || return 0
+  [ "$phys" = "$recorded" ] || printf '%s\n' "$phys"
+}
+
 # protected_tasktmp: every tasktmp= path those homes record. Fails when a home's
 # task records exist but cannot be read: an unreadable record is exactly the
 # ambiguity that must stop the sweep rather than let it delete on a guess.
 protected_tasktmp() {
-  local home meta rc=0
+  local home meta recorded rc=0
   local -a metas
   while IFS= read -r home; do
     [ -n "$home" ] || continue
+    if [ "$home" = "$HOME_SCAN_FAILED" ]; then
+      rc=1
+      continue
+    fi
     [ -d "$home/state" ] || continue
     if [ ! -r "$home/state" ] || [ ! -x "$home/state" ]; then
       rc=1
@@ -260,7 +306,10 @@ protected_tasktmp() {
       fi
       metas+=("$meta")
     done
-    [ "${#metas[@]}" -eq 0 ] || sed -n 's/^tasktmp=//p' "${metas[@]}"
+    [ "${#metas[@]}" -eq 0 ] && continue
+    while IFS= read -r recorded; do
+      emit_protected_path "$recorded"
+    done < <(sed -n 's/^tasktmp=//p' "${metas[@]}")
   done < <(candidate_homes | LC_ALL=C sort -u)
   return "$rc"
 }
@@ -414,6 +463,10 @@ dir_in_use() {
 removed=0
 unverified=0
 deferred=0
+# Which of the two bounds stopped the examination. An operator reading the
+# deferral line diagnoses a slow host and a capped run differently, so the two
+# must never share a reason.
+deferred_reason=
 
 # Pass one is the cheap pass: name, type, ownership and live-containment filters
 # only, no syscall heavier than a stat. It exists so that when the time budget
@@ -450,10 +503,12 @@ for entry in ${candidates[@]+"${candidates[@]}"}; do
   # honour.
   if [ "$MAX" -gt 0 ] && [ "$index" -gt "$MAX" ]; then
     deferred=$((total - index + 1))
+    deferred_reason="the --max $MAX candidate cap was reached"
     break
   fi
   if [ "$SECONDS" -ge "$BUDGET" ]; then
     deferred=$((total - index + 1))
+    deferred_reason="${BUDGET}s sweep budget exhausted"
     break
   fi
 
@@ -461,7 +516,7 @@ for entry in ${candidates[@]+"${candidates[@]}"}; do
   # top-level mtime alone is not enough: a long test writes deep in its tree
   # without ever restamping the root it was handed.
   if [ -n "$(find "$entry" -mmin "-$AGE_MINUTES" -print 2>/dev/null | head -n 1)" ]; then
-    note "$name: skipped: modified within ${AGE_HOURS}h"
+    note "$name: skipped: modified within $AGE_WINDOW"
     continue
   fi
 
@@ -513,6 +568,6 @@ if [ "$unverified" -gt 0 ]; then
   report "$ROOT_PHYS: skipped: $unverified stale scratch dir(s) left in place: cannot verify open handles (needs lsof or a readable procfs)"
 fi
 if [ "$deferred" -gt 0 ]; then
-  report "$ROOT_PHYS: skipped: ${BUDGET}s sweep budget exhausted after removing $removed, $deferred candidate(s) deferred to the next session"
+  report "$ROOT_PHYS: skipped: $deferred_reason after removing $removed, $deferred candidate(s) deferred to the next session"
 fi
 exit 0
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index d110def696..6d606a1f99 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -593,7 +593,15 @@ SH
 
 # Runner invocation with the nested-run suppression cleared, so a reap actually
 # runs even when this file is itself executing under the runner.
+#
+# Clearing that suppression means the reap runs for real, so every call site has
+# to aim it at a fixture root. The host's /tmp holds scratch belonging to other
+# live firstmate sessions, and reaping it as a side effect of running the suite
+# would delete their work. Refusing here rather than defaulting keeps the next
+# test that reaches for this helper from silently inheriting the real /tmp.
 run_runner_unnested() {
+  [ -n "${FM_TEST_REAP_ROOT:-}" ] \
+    || fail "run_runner_unnested needs FM_TEST_REAP_ROOT aimed at a fixture root"
   env -u FM_TEST_RUN_ACTIVE "$RUNNER" "$@"
 }
 
@@ -602,8 +610,10 @@ test_completed_run_leaves_no_fixture() {
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-contain.XXXXXX")
   probe="$tmp/probe.test.sh"
   record="$tmp/fixture-path"
+  mkdir -p "$tmp/reap"
   write_fixture_probe "$probe" "$record"
-  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
+  FM_TEST_REAP_ROOT="$tmp/reap" \
+    run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
     || fail "probe run should pass: $(cat "$tmp/err")"
   [ -s "$record" ] || fail "probe did not record its fixture path"
   fixture=$(cat "$record")
@@ -623,12 +633,14 @@ test_fixture_removed_when_run_is_interrupted() {
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-interrupt.XXXXXX")
   probe="$tmp/probe.test.sh"
   record="$tmp/fixture-path"
+  mkdir -p "$tmp/reap"
   write_fixture_probe "$probe" "$record" 'sleep 120'
   # Monitor mode puts the background runner in its own process group, so the
   # signal reaches the runner and the test it is running together - the same
   # shape as a terminal interrupt, which is how the leak accumulated.
   set -m
-  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
+  FM_TEST_REAP_ROOT="$tmp/reap" \
+    run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
   pid=$!
   set +m
   waited=0
@@ -671,7 +683,9 @@ printf '%s\n' "\$scratch" >'$record'
 echo "ok - task scratch at \$scratch"
 SH
   chmod +x "$probe"
-  run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
+  mkdir -p "$tmp/reap"
+  FM_TEST_REAP_ROOT="$tmp/reap" \
+    run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" \
     || fail "probe run should pass: $(cat "$tmp/err")"
   [ -s "$record" ] || fail "probe did not record its task scratch root"
   scratch=$(cat "$record")
@@ -685,14 +699,15 @@ test_killed_run_is_healed_by_the_next_run() {
   local tmp scratch probe record fixture root out pid waited
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-killed.XXXXXX")
   scratch="$tmp/scratch"
-  mkdir -p "$scratch"
+  mkdir -p "$scratch" "$tmp/reap"
   probe="$tmp/probe.test.sh"
   record="$tmp/fixture-path"
   write_fixture_probe "$probe" "$record" 'sleep 120'
   # SIGKILL runs no trap at all. This is exactly how the leak accumulated, so
   # the run root must survive the kill and then be reaped by the next run.
   set -m
-  TMPDIR="$scratch" run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
+  TMPDIR="$scratch" FM_TEST_REAP_ROOT="$tmp/reap" \
+    run_runner_unnested "$probe" >"$tmp/out" 2>"$tmp/err" &
   pid=$!
   set +m
   waited=0
@@ -792,6 +807,77 @@ test_signalled_jobs_run_stops_its_workers() {
   pass "a signalled --jobs run stops its workers before removing the run root"
 }
 
+test_aborted_jobs_run_stops_its_workers() {
+  local tmp repo runner reap runtmp fakebin started real_chmod a b c f pid rc leftover
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-jobs-abort.XXXXXX")
+  repo="$tmp/repo"
+  runner="$repo/bin/fm-test-run.sh"
+  reap="$tmp/reap"
+  runtmp="$tmp/runtmp"
+  fakebin="$tmp/fakebin"
+  started="$tmp/started"
+  a=tests/fm-brief.test.sh
+  b=tests/fm-composer-lib.test.sh
+  c=tests/fm-crew-state.test.sh
+  mkdir -p "$repo/bin" "$repo/tests" "$reap" "$runtmp" "$fakebin" "$started"
+  cp "$RUNNER" "$runner"
+  chmod +x "$runner"
+  # Same worker shape as the signalled case: each keeps rebuilding a directory
+  # under its own TMPDIR, so a child still running when the run root is removed
+  # recreates that root. Each also announces itself outside the run root, so a
+  # run that aborted before any worker started cannot pass this vacuously.
+  for f in "$a" "$b" "$c"; do
+    cat >"$repo/$f" <<SH
+#!/usr/bin/env bash
+: >"$started/\$(basename "\$0")"
+while :; do mkdir -p "\$TMPDIR/live"; sleep 0.05; done
+SH
+    chmod +x "$repo/$f"
+  done
+  # An abort that is not a signal: the third worker root's chmod fails, which is
+  # a plain \`|| die\` while the first two workers are already in flight. A full
+  # tmpfs - the failure mode this whole change exists for - produces exactly
+  # this. The delay gives the running workers time to announce themselves first.
+  real_chmod=$(command -v chmod)
+  cat >"$fakebin/chmod" <<SH
+#!/usr/bin/env bash
+last=
+for arg in "\$@"; do last=\$arg; done
+case "\$last" in
+  */w3/tmp) sleep 1; exit 1 ;;
+esac
+exec "$real_chmod" "\$@"
+SH
+  chmod +x "$fakebin/chmod"
+  # Monitor mode only so this test can clean up the run's process group by PID.
+  set -m
+  PATH="$fakebin:$PATH" TMPDIR="$runtmp" FM_TEST_REAP_ROOT="$reap" \
+    env -u FM_TEST_RUN_ACTIVE "$runner" --jobs 3 "$a" "$b" "$c" \
+    >"$tmp/out" 2>"$tmp/err" &
+  pid=$!
+  set +m
+  wait "$pid" && rc=0 || rc=$?
+  # Long enough for any child that outlived the runner to rebuild what the
+  # removal took away.
+  sleep 1
+  leftover=$(ls -A "$runtmp" 2>/dev/null || true)
+  reap_stray_workers "$pid"
+  if [ "$rc" -eq 0 ]; then
+    rm -rf "$tmp"
+    fail "a failed worker root setup must abort the run"
+  fi
+  if [ -z "$(ls -A "$started" 2>/dev/null || true)" ]; then
+    rm -rf "$tmp"
+    fail "no worker ever started, so the abort proved nothing"
+  fi
+  if [ -n "$leftover" ]; then
+    rm -rf "$tmp"
+    fail "an aborted --jobs run left its run root behind: $leftover"
+  fi
+  rm -rf "$tmp"
+  pass "a --jobs run aborting without a signal stops its workers before removing the run root"
+}
+
 # Build an isolated reap root plus a Firstmate home whose recorded task scratch
 # lives inside it. Echoes "<reap root>|<home>".
 init_reap_fixture() {
@@ -815,12 +901,20 @@ make_orphan() {
 }
 
 test_reap_clears_pre_existing_orphans() {
-  local tmp reap home orphan fresh probe out
+  local tmp reap home orphan fresh recent probe out
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap.XXXXXX")
   IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
   orphan=$(make_orphan "$reap" "fm-secondmate-safety.Ab12Cd")
   fresh="$reap/fm-recent-run.Zz99Yy"
   mkdir -p "$fresh"
+  # Twenty minutes old. The runner takes the sweep's own conservative window
+  # rather than shortening it, because this root is shared with other live
+  # firstmate tooling whose scratch can sit unwritten for far longer than a test
+  # fixture - bin/fm-home-seed.sh's rollback backup waits out a whole clone.
+  # A genuinely leaked fixture is days old, so nothing is lost by waiting.
+  recent="$reap/fm-seed-backup.Bb22Cc"
+  mkdir -p "$recent"
+  touch -d '20 minutes ago' "$recent" 2>/dev/null || touch -A -002000 "$recent"
   probe="$tmp/probe.test.sh"
   printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
   chmod +x "$probe"
@@ -831,6 +925,8 @@ test_reap_clears_pre_existing_orphans() {
   assert_contains "$out" "removed=1" "reap should report the one removed orphan: $out"
   assert_absent "$orphan" "a pre-existing orphan must be reaped: $orphan"
   assert_present "$fresh" "a fixture younger than the minimum age must be kept: $fresh"
+  assert_present "$recent" \
+    "the runner must not shorten the sweep's age window for other tooling's scratch: $recent"
   rm -rf "$tmp"
   pass "a later run reaps pre-existing orphans and spares recent ones"
 }
@@ -985,6 +1081,7 @@ test_fixture_removed_when_run_is_interrupted
 test_spawned_task_scratch_is_contained
 test_killed_run_is_healed_by_the_next_run
 test_signalled_jobs_run_stops_its_workers
+test_aborted_jobs_run_stops_its_workers
 test_reap_clears_pre_existing_orphans
 test_reap_never_touches_a_live_task_scratch
 test_reap_never_removes_a_held_open_fixture
diff --git a/tests/fm-tmp-sweep.test.sh b/tests/fm-tmp-sweep.test.sh
index 8e5c14c73f..54679f3b0c 100755
--- a/tests/fm-tmp-sweep.test.sh
+++ b/tests/fm-tmp-sweep.test.sh
@@ -390,6 +390,53 @@ test_reads_secondmate_homes_for_live_scratch() {
   pass "sweep reads registered secondmate homes for live task scratch"
 }
 
+test_unreadable_secondmate_registry_refuses_the_sweep() {
+  local root dir home out
+  if [ "$(id -u)" = 0 ]; then
+    pass "unreadable secondmate registry: root bypasses file permissions, nothing to assert"
+    return 0
+  fi
+  root=$(new_root unreadable-registry)
+  dir=$(make_stale_dir "$root" fm-teardown-tests.aB3xY9)
+  home="$TMP_ROOT/unreadable-registry-home"
+  mkdir -p "$home/state" "$home/data"
+  printf -- '- second (home: %s; scope: things)\n' "$TMP_ROOT/second" > "$home/data/secondmates.md"
+  chmod 000 "$home/data/secondmates.md"
+
+  out=$(run_sweep "$root" --protect-homes "$home")
+  chmod 644 "$home/data/secondmates.md"
+  # A registry that is simply absent says the home has no secondmates, which
+  # every other case here relies on. One that exists and cannot be read hides a
+  # whole class of homes, so the live tasks they record go unseen - the same
+  # ambiguity as an unreadable task record, and it must refuse the same way.
+  assert_present "$dir" \
+    "an unreadable secondmate registry must stop the sweep rather than let it guess"
+  assert_contains "$out" "task records could not be read" \
+    "refusing on an unreadable secondmate registry must say so"
+  pass "sweep refuses entirely when a home's secondmate registry cannot be read"
+}
+
+test_protects_a_live_task_recorded_through_a_symlinked_root() {
+  local root real live recorded home out
+  real=$(new_root symlinked-root-real)
+  root="$TMP_ROOT/symlinked-root"
+  ln -s "$real" "$root"
+  live=$(make_stale_dir "$real" fm-symtask.aB3xY9)
+  # What bin/fm-spawn.sh records on a host whose temp root is a symlink - macOS,
+  # where /tmp points at /private/tmp. Candidates always carry the resolved
+  # root, so a verbatim comparison can never match and the protection would be
+  # inert on exactly the hosts where the two spellings differ.
+  recorded="$root/fm-symtask.aB3xY9"
+  home=$(make_home "$TMP_ROOT/symlinked-root-home" symtask.aB3xY9 "$recorded")
+
+  out=$(run_sweep "$root" --protect-homes "$home")
+  assert_present "$live" \
+    "a live task recorded through a symlinked temp root must still be protected"
+  assert_contains "$out" "fm-symtask.aB3xY9: skipped: a firstmate home records it" \
+    "protecting a live task through a symlinked root must be reported"
+  pass "sweep resolves recorded task scratch before comparing it to a candidate"
+}
+
 test_age_minutes_window() {
   local root recent out
   root=$(new_root age-minutes)
@@ -414,8 +461,38 @@ test_max_bounds_the_examination() {
   out=$(run_sweep "$root" --max 1)
   [ "$(find "$root" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 2 ] \
     || fail "--max 1 must examine exactly one candidate and defer the rest"
-  assert_contains "$out" "deferred" "a bounded sweep must say what it deferred"
-  pass "sweep stops after --max candidates and defers the rest"
+  # The reason matters as much as the count: an operator told the time budget
+  # ran out goes looking for a slow host instead of for the cap they set.
+  assert_contains "$out" "the --max 1 candidate cap was reached after removing 1, 2 candidate(s) deferred" \
+    "a bounded sweep must name the cap it stopped on"
+  assert_not_contains "$out" "budget exhausted" \
+    "the candidate cap must never be reported as the time budget"
+  pass "sweep stops after --max candidates and reports the cap as the reason"
+}
+
+# The session-start sweep is bounded only by its time budget, and must stay that
+# way: capping it by default would strand orphans on exactly the host that
+# leaked the most, which is the host this sweep exists for. The bound belongs to
+# the caller that wants it - bin/fm-test-run.sh passes its own --max.
+test_default_max_is_unbounded() {
+  local root out i
+  local -a dirs=()
+  root=$(new_root unbounded-default)
+  i=1
+  while [ "$i" -le 501 ]; do
+    dirs+=("$root/fm-bulk$i.aB3xY9")
+    i=$((i + 1))
+  done
+  mkdir -p "${dirs[@]}"
+  age_out "${dirs[@]}"
+
+  # A generous budget, so this measures the candidate bound and nothing else.
+  out=$(run_sweep "$root" --timeout 600)
+  [ "$(find "$root" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 0 ] \
+    || fail "the default sweep must examine more than 500 candidates, not cap itself"
+  assert_not_contains "$out" "deferred" \
+    "an unbounded sweep with time to spare must defer nothing"
+  pass "sweep examines every candidate by default and bounds only when asked"
 }
 
 test_removes_stale_scratch_dir
@@ -440,5 +517,8 @@ test_refuses_when_task_records_cannot_be_read
 test_reads_secondmate_homes_for_live_scratch
 test_age_minutes_window
 test_max_bounds_the_examination
+test_default_max_is_unbounded
+test_unreadable_secondmate_registry_refuses_the_sweep
+test_protects_a_live_task_recorded_through_a_symlinked_root
 
 echo "all fm-tmp-sweep tests passed"

From 501ecc0d74f9fe983360b15cf1ebad748b034b8c Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 12:15:22 -0400
Subject: [PATCH 6/8] no-mistakes(review): scope the reap's short window to its
 own run roots

---
 bin/fm-test-run.sh         | 120 +++++++++++++++++++++++--------------
 bin/fm-tmp-sweep.sh        |  89 ++++++++++++++++++++++-----
 tests/fm-test-run.test.sh  |  33 ++++++++++
 tests/fm-tmp-sweep.test.sh |  54 ++++++++++++++++-
 4 files changed, 236 insertions(+), 60 deletions(-)

diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 17c902b85f..db4181fb89 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -62,19 +62,26 @@
 #   that were killed outright (SIGKILL leaves no trap to run), so a host that
 #   already leaked heals on the next test run. bin/fm-tmp-sweep.sh is the single
 #   owner of which directories are safe to remove and of every refusal that
-#   protects a live task, an in-use directory, or an operational home, including
-#   the age window; this runner supplies only the candidate cap a test host
-#   wants and the homes this checkout can see. Read that script's header for the
-#   full contract. The sweep's own conservative age window applies unchanged: a
-#   shorter one would shorten the destructive horizon for scratch owned by other
-#   live firstmate tooling in the same shared root, and containment plus the
-#   signal traps above already cover this runner's own fixtures.
-#   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MAX (default 500),
-#   FM_TEST_REAP_HOMES (extra colon-separated Firstmate homes whose state/*.meta
-#   to read), and FM_TEST_REAP_MIN_AGE_SECONDS (unset by default; when set,
-#   rounded up to whole minutes and passed to the sweep) exist so this behavior
-#   is testable without touching the host's real /tmp. FM_TEST_RUN_ACTIVE=1 is
-#   exported to every executed script and suppresses the reap in a nested run.
+#   protects a live task, an in-use directory, or an operational home; this
+#   runner supplies only the candidate cap a test host wants, the homes this
+#   checkout can see, and the horizons below. Read that script's header for the
+#   full contract.
+#
+#   The reap runs as two passes. The first is scoped by name to fm-test-run.*,
+#   the run roots this runner alone creates, on a short window: SIGKILL runs no
+#   trap, so the reap is the only thing that reclaims a killed run, and every
+#   fixture is nested inside that root. The second uses the sweep's own
+#   conservative window over everything else, because the shared root also holds
+#   scratch belonging to live firstmate tooling that can sit unwritten far
+#   longer than a fixture. No tool has to register itself to stay out of the
+#   short window; it cannot reach a name this runner did not create.
+#   FM_TEST_REAP_ROOT (default /tmp), FM_TEST_REAP_MIN_AGE_SECONDS (default 900,
+#   rounded up to whole minutes, and applied only to the first pass),
+#   FM_TEST_REAP_MAX (default 500), and FM_TEST_REAP_HOMES (extra
+#   colon-separated Firstmate homes whose state/*.meta to read) exist so this
+#   behavior is testable without touching the host's real /tmp.
+#   FM_TEST_RUN_ACTIVE=1 is exported to every executed script and suppresses the
+#   reap in a nested run.
 #
 # Per-script machine-parseable markers (stdout):
 #   FM_TEST_BEGIN <iso8601> <script> family=<family> expected_gate_skip=<class>
@@ -159,9 +166,15 @@ now_ms() {
 # --- run root, fixture containment, and orphan reap -------------------------
 
 REAP_ROOT=${FM_TEST_REAP_ROOT:-/tmp}
-# Unset means "use the sweep's own window", which is the operating contract. It
-# is a test seam, not a knob this runner turns.
-REAP_MIN_AGE_SECONDS=${FM_TEST_REAP_MIN_AGE_SECONDS:-}
+# The short window, and the only names it is ever allowed to reach. SIGKILL runs
+# no trap, so the reap is the only thing that reclaims a killed run, and waiting
+# out the sweep's conservative window would hold that run's fixtures in the
+# tmpfs for half a day. Scoping the short window to the prefix this runner alone
+# creates buys that back without shortening the horizon for any other tool's
+# scratch in the shared root - by construction, so nothing has to register
+# itself to stay safe.
+RUN_TMP_PREFIX=fm-test-run.
+REAP_MIN_AGE_SECONDS=${FM_TEST_REAP_MIN_AGE_SECONDS:-900}
 REAP_MAX=${FM_TEST_REAP_MAX:-500}
 # Descriptor 9 is held open inside the run root for its whole life. A concurrent
 # runner's reap sees this open file and keeps the root, which is what makes the
@@ -278,7 +291,7 @@ on_run_signal() {
 # removal covers the whole run.
 ensure_run_tmp() {
   [ -z "$RUN_TMP" ] || return 0
-  RUN_TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run.XXXXXX") \
+  RUN_TMP=$(mktemp -d "${TMPDIR:-/tmp}/${RUN_TMP_PREFIX}XXXXXX") \
     || die "could not create a run temp root"
   # Armed before anything else can fail, so even a die between here and the
   # first script still takes the root with it.
@@ -301,13 +314,18 @@ ensure_run_tmp() {
 # moment only one was edited. The runner contributes only what it alone knows: a
 # bound on how much work one test run should spend reclaiming, and which
 # firstmate homes this checkout can see, whose recorded task scratch must never
-# be deleted out from under live work. The age window is the sweep's own, not
-# this runner's: /tmp is shared with other live firstmate tooling, and a shorter
-# window here would put that tooling's scratch at risk to heal something
-# containment and the signal traps already handle.
+# be deleted out from under live work, plus the one prefix it alone creates.
+#
+# Two passes, because the two things being reclaimed have different horizons. A
+# run root left by a SIGKILL is dead the moment its runner is, and it is the one
+# artifact this runner can say that about with certainty, so it gets the short
+# window - scoped by name so the short window cannot reach anything else. Every
+# other orphan waits out the sweep's own conservative window, because the shared
+# root also holds scratch belonging to live firstmate tooling that can sit
+# unwritten far longer than a fixture.
 reap_orphan_fixtures() {
-  local sweep="$ROOT/bin/fm-tmp-sweep.sh" homes common out line status removed
-  local -a age_args=()
+  local sweep="$ROOT/bin/fm-tmp-sweep.sh" homes common age_minutes
+  local removed=0 refused=0 pass_removed status
 
   # A nested run inherits the outer run's root, which the outer run already
   # swept; sweeping again would only race it.
@@ -317,17 +335,14 @@ reap_orphan_fixtures() {
     log "orphan reap skipped: $sweep is not executable"
     return 0
   fi
-  if [ -n "$REAP_MIN_AGE_SECONDS" ]; then
-    case "$REAP_MIN_AGE_SECONDS" in
-      *[!0-9]*)
-        log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"
-        return 0
-        ;;
-    esac
-    # Rounded up, so a caller asking for any nonzero age never gets a zero
-    # window. Unset leaves the window to the sweep, which is the normal path.
-    age_args=(--age-minutes "$(( (REAP_MIN_AGE_SECONDS + 59) / 60 ))")
-  fi
+  case "$REAP_MIN_AGE_SECONDS" in
+    ''|*[!0-9]*)
+      log "orphan reap skipped: FM_TEST_REAP_MIN_AGE_SECONDS must be a non-negative integer"
+      return 0
+      ;;
+  esac
+  # Rounded up, so a caller asking for any nonzero age never gets a zero window.
+  age_minutes=$(( (REAP_MIN_AGE_SECONDS + 59) / 60 ))
 
   # Homes whose state/*.meta may record a live task's scratch root: this
   # checkout, an explicit FM_HOME, the primary checkout this worktree belongs to,
@@ -345,10 +360,32 @@ reap_orphan_fixtures() {
   fi
   [ -z "${FM_TEST_REAP_HOMES:-}" ] || homes="$homes:$FM_TEST_REAP_HOMES"
 
-  out=$("$sweep" --root "$REAP_ROOT" ${age_args[@]+"${age_args[@]}"} \
-    --max "$REAP_MAX" --protect-homes "$homes" 2>&1) && status=0 || status=$?
+  pass_removed=$(reap_sweep_pass "$sweep" --root "$REAP_ROOT" --max "$REAP_MAX" \
+    --protect-homes "$homes" --name-prefix "$RUN_TMP_PREFIX" \
+    --age-minutes "$age_minutes") && status=0 || status=$?
+  removed=$((removed + pass_removed))
+  [ "$status" -ne 3 ] || refused=1
+
+  pass_removed=$(reap_sweep_pass "$sweep" --root "$REAP_ROOT" --max "$REAP_MAX" \
+    --protect-homes "$homes") && status=0 || status=$?
+  removed=$((removed + pass_removed))
+  [ "$status" -ne 3 ] || refused=1
 
-  removed=0
+  # Status 3 is the sweep refusing as a whole, so nothing was reaped and this run
+  # must not claim otherwise.
+  [ "$refused" -eq 0 ] || return 0
+  # The count stays on stdout with the marker: the sweep's own lines are progress
+  # for a human and go to stderr with the rest of the runner's logging.
+  printf 'FM_TEST_REAP root=%s removed=%s\n' "$REAP_ROOT" "$removed"
+}
+
+# One sweep invocation. Echoes how many directories it removed and returns the
+# sweep's own exit status, so the caller can total the passes and still notice a
+# whole-sweep refusal.
+# shellcheck disable=SC2329 # Called from reap_orphan_fixtures above.
+reap_sweep_pass() {
+  local out line status removed=0
+  out=$("$@" 2>&1) && status=0 || status=$?
   if [ -n "$out" ]; then
     while IFS= read -r line; do
       [ -n "$line" ] || continue
@@ -358,13 +395,8 @@ reap_orphan_fixtures() {
       esac
     done <<<"$out"
   fi
-
-  # Status 3 is the sweep refusing as a whole, so nothing was reaped and this run
-  # must not claim otherwise.
-  [ "$status" -ne 3 ] || return 0
-  # The count stays on stdout with the marker: the sweep's own lines are progress
-  # for a human and go to stderr with the rest of the runner's logging.
-  printf 'FM_TEST_REAP root=%s removed=%s\n' "$REAP_ROOT" "$removed"
+  printf '%s\n' "$removed"
+  return "$status"
 }
 
 # Primary family for one tests/*.test.sh basename. Unmapped scripts are
diff --git a/bin/fm-tmp-sweep.sh b/bin/fm-tmp-sweep.sh
index bbee928660..439106ad53 100755
--- a/bin/fm-tmp-sweep.sh
+++ b/bin/fm-tmp-sweep.sh
@@ -21,12 +21,16 @@
 # Usage:
 #   fm-tmp-sweep.sh [--age-hours <n> | --age-minutes <n>] [--root <dir>]
 #                   [--timeout <seconds>] [--max <n>] [--protect-homes <list>]
-#                   [--dry-run] [--verbose]
+#                   [--name-prefix <prefix>] [--dry-run] [--verbose]
 #   fm-tmp-sweep.sh -h | --help
 #
 # A candidate is removed only when every one of these holds, checked in this
 # order so the cheap filters run before the expensive ones:
 #   - its name matches this repo's scratch convention, fm-<slug>.<6 mktemp chars>
+#   - its name starts with --name-prefix, when one was given. This can only
+#     narrow the set above, never widen it, so a caller wanting a shorter age
+#     window for its own artifacts can scope that window to names only it
+#     creates instead of applying it to everything in the shared root
 #   - it is a real directory, not a symlink, and is owned by the current user
 #   - it holds neither the current working directory nor FM_HOME
 #   - the sweep has not yet examined --max candidates
@@ -64,9 +68,12 @@
 #   0  the sweep ran; individual candidates may still have been skipped
 #   1  the arguments were invalid
 #   3  the sweep refused as a whole before examining anything, because a home's
-#      task records could not be read and a live task's scratch therefore could
-#      not be ruled out. Callers that report a completed sweep must not report
-#      one here. bin/fm-bootstrap.sh ignores the status and classifies output.
+#      records could not be read and a live task's scratch therefore could not
+#      be ruled out. The message names which records - task records under
+#      state/, or the home directory and secondmate registry that decide which
+#      homes are read at all - so an operator inspects the right place. Callers
+#      that report a completed sweep must not report one here.
+#      bin/fm-bootstrap.sh ignores the status and classifies output.
 #
 # Environment overrides (defaults are the operating contract; these exist for
 # tests and one-off manual runs, not as a configuration surface):
@@ -83,6 +90,9 @@
 #   FM_TMP_SWEEP_HOMES       extra firstmate homes to read task records from,
 #                            colon-separated. FM_HOME and the secondmate homes
 #                            each discoverable home registers are always read
+#   FM_TMP_SWEEP_NAME_PREFIX consider only candidates whose name starts with
+#                            this prefix (default none). Narrows the candidate
+#                            set and never widens it
 #   FM_TMP_SWEEP_ROOT        temp root to sweep (default ${TMPDIR:-/tmp})
 #   FM_TMP_SWEEP_TIMEOUT     whole-sweep time budget in seconds (default 20);
 #                            0 leaves no time for any candidate, so every one
@@ -113,6 +123,7 @@ ROOT_DIR=${FM_TMP_SWEEP_ROOT:-${TMPDIR:-/tmp}}
 BUDGET=${FM_TMP_SWEEP_TIMEOUT:-20}
 MAX=${FM_TMP_SWEEP_MAX:-0}
 PROTECT_HOMES=${FM_TMP_SWEEP_HOMES:-}
+NAME_PREFIX=${FM_TMP_SWEEP_NAME_PREFIX:-}
 PROC_ROOT=${FM_TMP_SWEEP_PROC_ROOT:-/proc}
 DRY_RUN=0
 VERBOSE=0
@@ -125,6 +136,15 @@ while [ $# -gt 0 ]; do
     --timeout) [ $# -ge 2 ] || die "--timeout needs a value"; BUDGET=$2; shift 2 ;;
     --max) [ $# -ge 2 ] || die "--max needs a value"; MAX=$2; shift 2 ;;
     --protect-homes) [ $# -ge 2 ] || die "--protect-homes needs a value"; PROTECT_HOMES=$2; shift 2 ;;
+    --name-prefix)
+      [ $# -ge 2 ] || die "--name-prefix needs a value"
+      # An empty prefix would read as "scope this pass" while scoping nothing,
+      # which is the one way this option could hand a caller a wider sweep than
+      # it asked for. Absent means unscoped; present has to mean something.
+      [ -n "$2" ] || die "name prefix must not be empty"
+      NAME_PREFIX=$2
+      shift 2
+      ;;
     --dry-run) DRY_RUN=1; shift ;;
     --verbose) VERBOSE=1; shift ;;
     -h|--help) usage; exit 0 ;;
@@ -230,6 +250,13 @@ looks_like_home() {
 # with it.
 HOME_SCAN_FAILED='!fm-tmp-sweep: a home registry could not be read'
 
+# Bits protected_tasktmp sets, so the whole-sweep refusal can name where the
+# operator should actually look. An unreadable state/<id>.meta and an
+# unreadable home directory or secondmate registry are both fatal ambiguity,
+# but they send an operator to different places.
+AMBIGUOUS_TASK_RECORDS=1
+AMBIGUOUS_HOME_RECORDS=2
+
 # candidate_homes: the homes whose task records may name a live scratch root -
 # this session's FM_HOME, every home named by --protect-homes, and every
 # secondmate each of those registers.
@@ -281,27 +308,35 @@ emit_protected_path() {
 }
 
 # protected_tasktmp: every tasktmp= path those homes record. Fails when a home's
-# task records exist but cannot be read: an unreadable record is exactly the
-# ambiguity that must stop the sweep rather than let it delete on a guess.
+# records exist but cannot be read: an unreadable record is exactly the
+# ambiguity that must stop the sweep rather than let it delete on a guess. The
+# returned status carries which kind of record was unreadable.
 protected_tasktmp() {
   local home meta recorded rc=0
   local -a metas
   while IFS= read -r home; do
     [ -n "$home" ] || continue
     if [ "$home" = "$HOME_SCAN_FAILED" ]; then
-      rc=1
+      rc=$((rc | AMBIGUOUS_HOME_RECORDS))
+      continue
+    fi
+    # An unsearchable home root looks exactly like a home with no state/ from
+    # the outside, so without this it would be skipped silently and every live
+    # task it records would go unprotected.
+    if [ -d "$home" ] && [ ! -x "$home" ]; then
+      rc=$((rc | AMBIGUOUS_HOME_RECORDS))
       continue
     fi
     [ -d "$home/state" ] || continue
     if [ ! -r "$home/state" ] || [ ! -x "$home/state" ]; then
-      rc=1
+      rc=$((rc | AMBIGUOUS_TASK_RECORDS))
       continue
     fi
     metas=()
     for meta in "$home"/state/*.meta; do
       [ -f "$meta" ] || continue
       if [ ! -r "$meta" ]; then
-        rc=1
+        rc=$((rc | AMBIGUOUS_TASK_RECORDS))
         continue
       fi
       metas+=("$meta")
@@ -315,8 +350,18 @@ protected_tasktmp() {
 }
 
 PROTECTED_PATHS=
-if ! PROTECTED_PATHS=$(protected_tasktmp); then
-  report "$ROOT_DIR: skipped: a firstmate home's task records could not be read, so no scratch dir is safe to remove"
+AMBIGUITY=0
+PROTECTED_PATHS=$(protected_tasktmp) || AMBIGUITY=$?
+if [ "$AMBIGUITY" -ne 0 ]; then
+  case "$AMBIGUITY" in
+    "$AMBIGUOUS_TASK_RECORDS")
+      AMBIGUITY_CAUSE="a firstmate home's task records could not be read" ;;
+    "$AMBIGUOUS_HOME_RECORDS")
+      AMBIGUITY_CAUSE="a firstmate home's directory or secondmate registry could not be read" ;;
+    *)
+      AMBIGUITY_CAUSE="a firstmate home's task records could not be read, and so could not another home's directory or secondmate registry" ;;
+  esac
+  report "$ROOT_DIR: skipped: $AMBIGUITY_CAUSE, so no scratch dir is safe to remove"
   exit 3
 fi
 PROTECTED_PATHS=$'\n'"$PROTECTED_PATHS"$'\n'
@@ -324,12 +369,20 @@ PROTECTED_PATHS=$'\n'"$PROTECTED_PATHS"$'\n'
 # is_live_task_scratch <dir>: true when <dir> is a recorded scratch root, sits
 # inside one, or contains one. All three directions matter: the sweep must not
 # remove a live scratch root, nor an ancestor that would take it with it.
+#
+# The walk is pure parameter expansion. A here-string or a pipe would make this
+# check depend on a writable temp root, and it runs only for candidates that
+# already cleared the age gate - which is to say on exactly the leaked or full
+# root this sweep exists to drain. A failure there would fall through to "not
+# live", the one direction that ends in a removal.
 is_live_task_scratch() {
-  local dir=$1 p
+  local dir=$1 rest=${PROTECTED_PATHS#$'\n'} p
   case "$PROTECTED_PATHS" in
     *$'\n'"$dir"$'\n'*) return 0 ;;
   esac
-  while IFS= read -r p; do
+  while [ -n "$rest" ]; do
+    p=${rest%%$'\n'*}
+    rest=${rest#*$'\n'}
     [ -n "$p" ] || continue
     case "$p" in
       "$dir"/*) return 0 ;;
@@ -337,7 +390,7 @@ is_live_task_scratch() {
     case "$dir" in
       "$p"/*) return 0 ;;
     esac
-  done <<<"$PROTECTED_PATHS"
+  done
   return 1
 }
 
@@ -480,6 +533,14 @@ for entry in "$ROOT_PHYS"/fm-*.??????; do
   # suffix is exactly six alphanumerics. Matching the convention rather than a
   # list of today's prefixes keeps new test files covered with no edit here.
   [[ $name =~ ^fm-[A-Za-z0-9][A-Za-z0-9._-]*\.[A-Za-z0-9]{6}$ ]] || continue
+  # Applied after the convention check and quoted so the prefix is literal, so
+  # it can only remove names from the set the convention already allowed.
+  if [ -n "$NAME_PREFIX" ]; then
+    case "$name" in
+      "$NAME_PREFIX"*) ;;
+      *) continue ;;
+    esac
+  fi
   [ -L "$entry" ] && continue
   [ -d "$entry" ] || continue
   [ -O "$entry" ] || { note "$name: skipped: owned by another user"; continue; }
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index 6d606a1f99..7622536fde 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -931,6 +931,38 @@ test_reap_clears_pre_existing_orphans() {
   pass "a later run reaps pre-existing orphans and spares recent ones"
 }
 
+test_reap_uses_a_short_window_only_for_its_own_run_roots() {
+  local tmp reap home killed foreign old probe out
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-window.XXXXXX")
+  IFS='|' read -r reap home <<<"$(init_reap_fixture "$tmp")"
+  # Both twenty minutes old: past the runner's short window, well inside the
+  # sweep's conservative one, so only the name decides which window applies.
+  # SIGKILL runs no trap, so the reap is the only thing that reclaims a killed
+  # run - and every fixture it stranded is nested inside that one root.
+  killed="$reap/fm-test-run.Dd77Ee"
+  foreign="$reap/fm-home-seed.Ff88Gg"
+  mkdir -p "$killed" "$foreign"
+  touch -d '20 minutes ago' "$killed" "$foreign" 2>/dev/null \
+    || touch -A -002000 "$killed" "$foreign"
+  old=$(make_orphan "$reap" "fm-home-seed.Hh99Ii")
+  probe="$tmp/probe.test.sh"
+  printf '#!/usr/bin/env bash\necho "ok - probe"\n' >"$probe"
+  chmod +x "$probe"
+  out=$(FM_TEST_REAP_ROOT="$reap" FM_TEST_REAP_HOMES="$home" \
+    run_runner_unnested "$probe" 2>"$tmp/err") \
+    || fail "reap run should pass: $(cat "$tmp/err")"
+  assert_contains "$out" "removed=2" \
+    "the marker must total both passes: the killed root and the old orphan: $out"
+  assert_absent "$killed" \
+    "a killed run's root must be reclaimed on the short window: $killed"
+  assert_present "$foreign" \
+    "another tool's scratch of the same age must never see the short window: $foreign"
+  assert_absent "$old" \
+    "a genuinely old orphan must still be reclaimed by the conservative pass: $old"
+  rm -rf "$tmp"
+  pass "the reap's short window reaches only the run roots this runner creates"
+}
+
 test_reap_never_touches_a_live_task_scratch() {
   local tmp reap home tasktmp gotmp probe out
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-reap-task.XXXXXX")
@@ -1083,6 +1115,7 @@ test_killed_run_is_healed_by_the_next_run
 test_signalled_jobs_run_stops_its_workers
 test_aborted_jobs_run_stops_its_workers
 test_reap_clears_pre_existing_orphans
+test_reap_uses_a_short_window_only_for_its_own_run_roots
 test_reap_never_touches_a_live_task_scratch
 test_reap_never_removes_a_held_open_fixture
 test_reap_stays_within_fm_fixture_names
diff --git a/tests/fm-tmp-sweep.test.sh b/tests/fm-tmp-sweep.test.sh
index 54679f3b0c..745bd17d14 100755
--- a/tests/fm-tmp-sweep.test.sh
+++ b/tests/fm-tmp-sweep.test.sh
@@ -411,11 +411,59 @@ test_unreadable_secondmate_registry_refuses_the_sweep() {
   # ambiguity as an unreadable task record, and it must refuse the same way.
   assert_present "$dir" \
     "an unreadable secondmate registry must stop the sweep rather than let it guess"
-  assert_contains "$out" "task records could not be read" \
-    "refusing on an unreadable secondmate registry must say so"
+  # Naming the wrong records sends the operator to inspect state/ and find
+  # nothing wrong, which is the same misdirection as reporting a candidate cap
+  # as an exhausted time budget.
+  assert_contains "$out" "directory or secondmate registry could not be read" \
+    "refusing on an unreadable registry must name the registry, not task records"
+  assert_not_contains "$out" "task records could not be read" \
+    "an unreadable registry must not be reported as an unreadable task record"
   pass "sweep refuses entirely when a home's secondmate registry cannot be read"
 }
 
+test_unsearchable_home_root_refuses_the_sweep() {
+  local root dir home out
+  if [ "$(id -u)" = 0 ]; then
+    pass "unsearchable home root: root bypasses directory permissions, nothing to assert"
+    return 0
+  fi
+  root=$(new_root unsearchable-home)
+  dir=$(make_stale_dir "$root" fm-teardown-tests.aB3xY9)
+  home=$(make_home "$TMP_ROOT/unsearchable-home-root" sometask "$TMP_ROOT/nowhere")
+  chmod 000 "$home"
+
+  out=$(run_sweep "$root" --protect-homes "$home")
+  chmod 755 "$home"
+  # From outside, a home with no search permission is indistinguishable from a
+  # home that simply has no state/ - so without refusing, every live task it
+  # records would go unprotected while the sweep reported a clean run.
+  assert_present "$dir" \
+    "a home that exists but cannot be searched must stop the sweep, not be skipped"
+  assert_contains "$out" "directory or secondmate registry could not be read" \
+    "refusing on an unsearchable home must name the home, not task records"
+  pass "sweep refuses entirely when a home exists but cannot be searched"
+}
+
+test_name_prefix_narrows_the_candidate_set() {
+  local root scoped unscoped outside out
+  root=$(new_root name-prefix)
+  scoped=$(make_stale_dir "$root" fm-test-run.aB3xY9)
+  unscoped=$(make_stale_dir "$root" fm-other-tool.Cc44Dd)
+  # Outside the naming convention entirely: a prefix must narrow what the
+  # convention already allowed, never reach past it.
+  outside="$root/test-run.Ee55Ff"
+  mkdir -p "$outside"
+  age_out "$outside"
+
+  out=$(run_sweep "$root" --name-prefix fm-test-run.)
+  assert_absent "$scoped" "a candidate matching the prefix must still be reclaimed"
+  assert_present "$unscoped" \
+    "a stale candidate outside the prefix must be left to an unscoped pass: $unscoped"
+  assert_present "$outside" "a prefix must never widen the sweep past the name convention"
+  assert_contains "$out" "fm-test-run.aB3xY9: removed" "the scoped removal must be reported"
+  pass "sweep --name-prefix narrows the candidate set and cannot widen it"
+}
+
 test_protects_a_live_task_recorded_through_a_symlinked_root() {
   local root real live recorded home out
   real=$(new_root symlinked-root-real)
@@ -519,6 +567,8 @@ test_age_minutes_window
 test_max_bounds_the_examination
 test_default_max_is_unbounded
 test_unreadable_secondmate_registry_refuses_the_sweep
+test_unsearchable_home_root_refuses_the_sweep
+test_name_prefix_narrows_the_candidate_set
 test_protects_a_live_task_recorded_through_a_symlinked_root
 
 echo "all fm-tmp-sweep tests passed"

From ab76b5609898c676d4beb76b9e704d17be4e322d Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 12:29:52 -0400
Subject: [PATCH 7/8] no-mistakes(document): document sweep whole-root refusal
 and runner fixture ownership

---
 .agents/skills/bootstrap-diagnostics/SKILL.md | 3 ++-
 docs/scripts.md                               | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/bootstrap-diagnostics/SKILL.md b/.agents/skills/bootstrap-diagnostics/SKILL.md
index ddd0f26fc5..5f517a49a2 100644
--- a/.agents/skills/bootstrap-diagnostics/SKILL.md
+++ b/.agents/skills/bootstrap-diagnostics/SKILL.md
@@ -46,8 +46,9 @@ When any diagnostic needs captain attention, report the plain consequence and re
   Keep each affected poll unavailable, inspect the named private state path, and do not bypass the migration or execute a quarantined artifact; a completed safe-scan marker allows unrelated authenticated polls to continue while private repair remains pending.
 - `SCRATCH_SWEEP: <name>: skipped: <reason>` - the temp-root scratch sweep found a stale orphaned scratch directory but deliberately left it in place, either because removal failed or because it does not look like scratch at all (`looks like a firstmate home` means a home is sitting in the temp root and must be moved or removed by hand, never swept).
   The shared temp filesystem is small and every home on the host writes into it, so a leak that keeps being skipped eventually fills it and makes every command on the machine fail silently on temp writes; clear the named directory yourself once you have confirmed nothing is using it.
-- `SCRATCH_SWEEP: <temp root>: skipped: <reason>` - the sweep could not run to completion for the whole root: either no open-handle check was available (install `lsof`, or check why procfs or the temp root is unreadable) or the sweep's time budget ran out with candidates left.
+- `SCRATCH_SWEEP: <temp root>: skipped: <reason>` - the sweep could not run to completion for the whole root: no open-handle check was available (install `lsof`, or check why procfs or the temp root is unreadable), the sweep's time budget ran out with candidates left, or a firstmate home's records could not be read so the sweep refused before examining anything.
   A budget line is self-healing across sessions and needs attention only if the deferred count keeps growing; a missing open-handle check disables reclamation entirely and does need fixing.
+  An unreadable-records line means nothing at all was reclaimed this session, so never report a completed sweep after one: repair the records the reason names (a home's task records under `state/`, or the home directory or secondmate registry that decides which homes are read) rather than clearing the temp root by hand, because a live task's recorded scratch is exactly what could not be ruled out.
 - `SECONDMATE_SYNC: secondmate <id>: skipped: <reason>` - the local-HEAD secondmate sync left a live secondmate home on its existing checkout because the home was dirty, diverged, unsafe, on the wrong branch, missing the primary target commit, or otherwise not fast-forwardable, or because inherited local-material propagation failed; bootstrap continued, but inspect the reason because the secondmate's tracked instructions, inherited settings, or shared captain preferences may be stale after a primary update.
 - `SECONDMATE_LIVENESS: secondmate <id>: skipped: <reason>|respawn failed after <cause>: <reason>` - the session-start liveness sweep could not guarantee that the registered secondmate is running a real agent process.
   Investigate the reason because that secondmate is not guaranteed live.
diff --git a/docs/scripts.md b/docs/scripts.md
index 49a2a8a5b9..5885742773 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -24,7 +24,7 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize
 | `fm-install-herdr.sh`    | Install CI's exact-version Herdr pin with official asset URL, SHA-256, and protocol checks |
 | `fm-install-treehouse.sh`| Install CI's exact-version Treehouse pin for real-Herdr E2E that needs spawn worktrees |
 | `fm-herdr-ci-cleanup.sh` | Snapshot and tear down only job-owned `fm-lab-*` sessions in the Herdr CI lane       |
-| `fm-test-run.sh`         | Behavior-test runner: selection, portable lanes, proven-isolated `--jobs`, coverage guard, timing/JSON |
+| `fm-test-run.sh`         | Behavior-test runner: selection, portable lanes, proven-isolated `--jobs`, coverage guard, timing/JSON, and fixture containment plus the orphan reap for the suite |
 | `fm-test-isolation-proof.sh` | Concurrent isolation proof and proven-isolated candidate set owner |
 | `fm-ensure-agents-md.sh` | Ensure a project's real `AGENTS.md`, its `CLAUDE.md` symlink, and the canonical self-governance section |
 | `fm-guard.sh`            | Warn on primary-checkout tangles, pending queued wakes, and stale watcher liveness   |

From 549f377c0c7a9fbef36c59f4e061b156c0d26682 Mon Sep 17 00:00:00 2001
From: Bchue <bchue@homeserver.tail25a02d.ts.net>
Date: Sun, 9 Aug 2026 13:23:22 -0400
Subject: [PATCH 8/8] no-mistakes: apply CI fixes

---
 tests/fm-pi-watch-extension.test.sh | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/tests/fm-pi-watch-extension.test.sh b/tests/fm-pi-watch-extension.test.sh
index f888319489..4d5e77e3ed 100755
--- a/tests/fm-pi-watch-extension.test.sh
+++ b/tests/fm-pi-watch-extension.test.sh
@@ -889,11 +889,19 @@ test_pi_session_transition_generation_owner() {
   mkdir -p "$repo/bin" "$home/state" "$home/config"
   install_pi_watch_extension_fixture "$repo"
   plugin="$repo/.pi/extensions/fm-primary-pi-watch.ts"
+  # The child pid file is this fixture's publication point: the assertions below
+  # wait on it and then immediately read the arm log for the same pid. So the arm
+  # log entry is appended first, and the pid file is published by rename, never
+  # by a create-then-write a reader can observe half done. Written the other way
+  # round, an arm child that is descheduled between the two writes is seen as
+  # started while the arm log still lists only its dead predecessors, and the
+  # live-arm-child assertions fail on a scheduling accident.
   cat > "$repo/bin/fm-watch-arm.sh" <<'SH'
 #!/usr/bin/env bash
 printf 'watcher: started pid=%s\n' "$$"
-printf '%s\n' "$$" > "${FM_CHILD_PID_FILE:?}"
 printf 'arm pid=%s\n' "$$" >> "${FM_ARM_LOG:?}"
+printf '%s\n' "$$" > "${FM_CHILD_PID_FILE:?}.new"
+mv -f "${FM_CHILD_PID_FILE:?}.new" "${FM_CHILD_PID_FILE:?}"
 trap 'exit 0' TERM INT
 while :; do sleep 0.2; done
 SH