From 75298f49866367eb93f5ad539702e35f595ef4b2 Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Thu, 8 Oct 2026 21:54:37 -0500
Subject: [PATCH 1/6] fix: bound every test script and lab tree with a per-tree
 process budget

The kernel compares the process limit with the user's whole process count,
so one runaway scratch tree (a shim whose basename is itself) filled the
table and cost every lane its forks. bin/fm-proc-budget.sh sets the limit to
the current count plus a headroom (default 1500) for one command tree only.
bin/fm-test-run.sh starts each script under it, bin/fm-live-lab.sh starts
every lab process under it, and the crewmate brief scaffolds carry a rule
that routes ad-hoc shim, lab, and measurement scripts through it.
---
 bin/fm-brief.sh              |   8 ++
 bin/fm-live-lab.sh           |   5 +-
 bin/fm-proc-budget.sh        | 124 +++++++++++++++++++++
 bin/fm-test-run.sh           |  20 ++++
 docs/scripts.md              |   1 +
 tests/fm-brief.test.sh       |  35 ++++++
 tests/fm-proc-budget.test.sh | 206 +++++++++++++++++++++++++++++++++++
 tests/fm-test-run.test.sh    |  54 +++++++++
 8 files changed, 452 insertions(+), 1 deletion(-)
 create mode 100755 bin/fm-proc-budget.sh
 create mode 100755 tests/fm-proc-budget.test.sh

diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh
index 02ce92f3adf..fe313768d4f 100755
--- a/bin/fm-brief.sh
+++ b/bin/fm-brief.sh
@@ -596,6 +596,12 @@ IFS= read -r -d '' SHARED_INFRA_RULE <<'EOF' || true
 EOF
 SHARED_INFRA_RULE=${SHARED_INFRA_RULE%$'\n'}
 
+# One shared string keeps the ship and scout process-budget rule identical.
+# The kernel counts the user's whole process table, so one runaway scratch tree
+# starves every lane; bin/fm-proc-budget.sh owns the budget, this is the one
+# line that reaches ad-hoc scripts no runner wraps.
+SHARED_PROC_BUDGET_RULE="9. Run any shim, lab, or measurement script through \`$FM_ROOT/bin/fm-proc-budget.sh -- <command...>\`: a runaway process tree then stops at its own limit instead of starving every lane of fork."
+
 if [ -n "$BASE_BRANCH" ]; then
   SETUP_BASE="You are in a disposable git worktree of $REPO, at a detached HEAD on a clean copy of its base branch.
 Base branch: $BASE_BRANCH"
@@ -661,6 +667,7 @@ $CREWMATE_PAUSE_INSTRUCTIONS
    Firstmate's reply normally writes that closing line at answer time; when a blocker or wait clears WITHOUT a firstmate reply, append \`resolved [at=<epoch>]: {how it cleared}\` yourself (same \`[key=<slug>]\` if you opened it with one) as you resume.
 $SHARED_INFRA_RULE
 $PRIVATE_SERVICE_RULE
+$SHARED_PROC_BUDGET_RULE
 
 $WAIT_BLOCK$INBOX_SECTION
 
@@ -742,6 +749,7 @@ $ASK_USER_BLOCK
    Firstmate's reply normally writes that closing line at answer time; when a blocker or wait clears WITHOUT a firstmate reply, append \`resolved [at=<epoch>]: {how it cleared}\` yourself (same \`[key=<slug>]\` if you opened it with one) as you resume.
 $SHARED_INFRA_RULE
 $PRIVATE_SERVICE_RULE
+$SHARED_PROC_BUDGET_RULE
 
 $WAIT_BLOCK$INBOX_SECTION
 
diff --git a/bin/fm-live-lab.sh b/bin/fm-live-lab.sh
index 4b6176a2acf..feb5a3ffbfe 100755
--- a/bin/fm-live-lab.sh
+++ b/bin/fm-live-lab.sh
@@ -172,11 +172,14 @@ lab_env_base() {
   [ -z "${CLAUDE_DIR:-}" ] || printf '%s\n' "CLAUDE_CONFIG_DIR=$CLAUDE_DIR"
 }
 
+# Every lab process starts under bin/fm-proc-budget.sh, so a runaway process tree
+# in the lab (the private tmux server carries the budget to every pane) stops at
+# its own limit instead of starving the user's other sessions of fork.
 lab_run() {  # [NAME=VALUE...] <command...>: run in the lab's clean environment
   local -a base=()
   local line
   while IFS= read -r line; do base+=("$line"); done < <(lab_env_base)
-  env -i "${base[@]}" "$@"
+  "$SCRIPT_DIR/fm-proc-budget.sh" -- env -i "${base[@]}" "$@"
 }
 
 # window_id <name>: the tmux id of the lab window with exactly this name, or
diff --git a/bin/fm-proc-budget.sh b/bin/fm-proc-budget.sh
new file mode 100755
index 00000000000..815b4ead6dc
--- /dev/null
+++ b/bin/fm-proc-budget.sh
@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# fm-proc-budget.sh - run a command tree under a per-tree process budget.
+#
+# Usage:
+#   fm-proc-budget.sh [<extra>] -- <command...>   run <command...> with a budget
+#   fm-proc-budget.sh --count                     print the user's process count
+#   fm-proc-budget.sh --check                     exit 0 when a budget can be set here
+#
+# The kernel compares RLIMIT_NPROC with the user's WHOLE process count, not with
+# one process tree. A runaway tree therefore starves every other process of the
+# same user until the cap is full, and a bash 3.2 script exits 128 at its first
+# failed fork. The only handle is to stop the runaway early: this wrapper reads
+# the current count and sets the limit (soft and hard) to count + <extra>, then
+# execs the command, so only the tree below it carries the lowered limit and the
+# rest of the user keeps its headroom. <extra> is a positive decimal integer;
+# omit it for FM_PROC_BUDGET_EXTRA, or 1500 when that is unset.
+#
+# The budget only tightens. A limit the command already inherits that is lower
+# than count + <extra> stays as it is, and the hard limit is lowered with the
+# soft one so the tree cannot raise it again; a nested wrapper therefore never
+# widens an outer budget.
+#
+# Only commands started through the wrapper are protected. Route every shim,
+# lab, and measurement script through it; bin/fm-test-run.sh and
+# bin/fm-live-lab.sh do so for the trees they start.
+#
+# FM_PROC_BUDGET=off runs the command with no budget, for a host where the
+# budget turns out to starve a legitimate tree.
+#
+# The budget is headroom over the count at the moment the command starts, so a
+# tree that outlives a large rise in the rest of the user's processes can meet
+# the limit without having grown.
+#
+# Exit status: the command's own, 2 for a malformed call, and 125 when no budget
+# can be set (an unreadable process count, or a limit the host refuses). The
+# command never runs unbudgeted behind the caller's back in those two cases.
+set -u
+
+fm_proc_budget_error() {
+  echo "fm-proc-budget: $*" >&2
+}
+
+fm_proc_budget_usage() {
+  fm_proc_budget_error "usage: fm-proc-budget.sh [<extra>] -- <command...> | --count | --check"
+}
+
+# The kernel counts what RLIMIT_NPROC is compared with: processes on Darwin,
+# tasks (threads included) on Linux.
+fm_proc_budget_count() {
+  local uid count
+  uid=$(id -u) || return 1
+  set -o pipefail
+  case "$(uname -s)" in
+    Linux) count=$(ps -L -U "$uid" -o lwp= | wc -l) || return 1 ;;
+    *) count=$(ps -U "$uid" -o pid= | wc -l) || return 1 ;;
+  esac
+  count=$(printf '%s' "$count" | tr -d '[:space:]')
+  case "$count" in
+    ''|*[!0-9]*|0) return 1 ;;
+  esac
+  printf '%s\n' "$count"
+}
+
+# fm_proc_budget_apply <extra>: lower this process's limit to count + <extra>
+# unless the inherited limit is already lower. Prints nothing on success.
+fm_proc_budget_apply() {
+  local extra=$1 count current limit
+  count=$(fm_proc_budget_count) || {
+    fm_proc_budget_error "cannot read the process count, so no budget can be set"
+    return 125
+  }
+  limit=$((count + extra))
+  current=$(ulimit -u) || {
+    fm_proc_budget_error "cannot read the current process limit"
+    return 125
+  }
+  case "$current" in
+    ''|*[!0-9]*) ;;  # unlimited: the budget is the only bound
+    *) [ "$limit" -lt "$current" ] || return 0 ;;
+  esac
+  ulimit -u "$limit" 2>/dev/null || {
+    fm_proc_budget_error "this host refused a process limit of $limit (count $count + $extra)"
+    return 125
+  }
+}
+
+case "${1:-}" in
+  --count)
+    fm_proc_budget_count || {
+      fm_proc_budget_error "cannot read the process count"
+      exit 125
+    }
+    exit 0
+    ;;
+  --check)
+    # The limit is applied in a subshell, so this process keeps its own.
+    ( fm_proc_budget_apply 1500 ) || exit 1
+    echo "fm-proc-budget: a process budget can be set on this host"
+    exit 0
+    ;;
+esac
+
+extra=${FM_PROC_BUDGET_EXTRA:-1500}
+if [ "${1:-}" != -- ] && [ "$#" -gt 0 ]; then
+  extra=$1
+  shift
+fi
+if [ "${1:-}" != -- ]; then
+  fm_proc_budget_usage
+  exit 2
+fi
+shift
+[ "$#" -gt 0 ] || { fm_proc_budget_usage; exit 2; }
+case "$extra" in
+  ''|*[!0-9]*|0|0[0-9]*)
+    fm_proc_budget_error "extra must be a positive decimal integer, got '$extra'"
+    exit 2
+    ;;
+esac
+
+if [ "${FM_PROC_BUDGET:-}" != off ]; then
+  fm_proc_budget_apply "$extra" || exit 125
+fi
+exec "$@"
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 82594584617..90d3efc1522 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -134,6 +134,13 @@
 # The marker must be a nonnegative decimal integer or execution exits 125;
 # 0 denotes degraded work and imposes no budget.
 # Without python3 or the pool tool beside it, scripts run directly.
+#
+# Every executed script also runs under a per-tree process budget
+# (bin/fm-proc-budget.sh owns it): a script that forks without bound stops at its
+# own limit instead of filling the user's process table for every other lane.
+# The budget is taken when the script starts, after any pass wait. FM_PROC_BUDGET=off
+# disables it, FM_PROC_BUDGET_EXTRA sizes it, and a host that cannot set one runs
+# scripts without it and says so on stderr.
 # With a usable pool, --jobs above its size still starts that many workers,
 # but only pool-size scripts run at once.
 #
@@ -849,6 +856,7 @@ tests/fm-pr-check-security.test.sh 300675
 tests/fm-pr-reviewers.test.sh 273
 tests/fm-pr-state-live-e2e.test.sh 47
 tests/fm-pr-state.test.sh 531
+tests/fm-proc-budget.test.sh 8000
 tests/fm-procevent-quota.test.sh 2459
 tests/fm-procevent-when.test.sh 25674
 tests/fm-procevent.test.sh 370820
@@ -2467,6 +2475,13 @@ elif ! command -v python3 >/dev/null 2>&1; then
   CPU_PASS_ACTIVE=0
   log "running without CPU passes: python3 not found"
 fi
+PROC_BUDGET_ACTIVE=1
+if [ ! -x "$ROOT/bin/fm-proc-budget.sh" ] || [ "${FM_PROC_BUDGET:-}" = off ]; then
+  PROC_BUDGET_ACTIVE=0
+elif ! proc_budget_note=$("$ROOT/bin/fm-proc-budget.sh" --check 2>&1); then
+  PROC_BUDGET_ACTIVE=0
+  log "running without process budgets: $proc_budget_note"
+fi
 if [ "$JOBS" -gt 1 ] || [ "$MODE" = changed ] || [ "$MODE" = scripts ]; then
   SELECTION_DESC="${SELECTION_DESC};jobs=$JOBS"
 fi
@@ -2647,6 +2662,11 @@ run_script_bounded() {  # <script> <out> <stream> <id>
   else
     cmd=(bash "$script")
   fi
+  if [ "$PROC_BUDGET_ACTIVE" -eq 1 ]; then
+    # Innermost, so the budget is taken when the script starts, not before a
+    # pass wait or after another script has already grown the process count.
+    cmd=("$ROOT/bin/fm-proc-budget.sh" -- "${cmd[@]}")
+  fi
   if [ "$PER_SCRIPT_TIMEOUT_SECS" -gt 0 ]; then
     # The bound runs inside the pass holder so the pass wait stays outside it.
     # shellcheck disable=SC2016
diff --git a/docs/scripts.md b/docs/scripts.md
index 711e9fbd41d..34927675558 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -55,6 +55,7 @@ The shared no-mistakes gate lifecycle boundary is summarized in [architecture.md
 | `fm-test-isolation-proof.sh` | Concurrent isolation harness and portable candidate set owner |
 | `fm-cpu-pass.sh`         | Reserve an exact positive worker count, no larger than the host CPU count, while a CPU-heavy burst runs ([protocol](cpu-pass-pool.md)) |
 | `fm-cpu-pass.py`         | The engine behind `fm-cpu-pass.sh`                                                   |
+| `fm-proc-budget.sh`      | Run a command tree under a per-tree process budget so a runaway tree stops at its own limit instead of filling the user's process table |
 | `fm-load-report.sh`      | Record host load and judge it with pipeline agent durations ([recipe](cpu-pass-pool.md#judging-the-pool)) |
 | `fm-load-report.py`      | The engine behind `fm-load-report.sh`                                                |
 | `fm-ensure-agents-md.sh` | Manually initialize project agent-memory files (see the helper's header and help) |
diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh
index 95d53fc5fdf..d351e4a0725 100755
--- a/tests/fm-brief.test.sh
+++ b/tests/fm-brief.test.sh
@@ -1512,11 +1512,46 @@ test_crewmate_scaffolds_require_stopping_private_services() {
   pass "fm-brief.sh: ship and scout scaffolds require stopping private services and naming them in the status line"
 }
 
+# A runaway scratch tree fills the user's whole process table and costs every
+# lane its forks (the 2026-10-08 fork-EAGAIN incident), and only the worker's
+# own brief reaches an ad-hoc shim, lab, or measurement script. Every crewmate
+# scaffold carries the one-line rule that routes such a script through
+# bin/fm-proc-budget.sh; the emitted line must be identical for ship and scout.
+test_crewmate_scaffolds_route_scratch_scripts_through_the_process_budget() {
+  local home="$TMP_ROOT/proc-budget-home" mode brief ship_rule scout_rule
+  mkdir -p "$home/data"
+  for mode in no-mistakes direct-PR local-only; do
+    FM_HOME="$home" "$ROOT/bin/fm-brief.sh" "brief-budget-$mode" alpha --mode "$mode" >/dev/null 2>&1 \
+      || fail "fm-brief.sh --mode $mode exited non-zero"
+    brief="$home/data/brief-budget-$mode/brief.md"
+    assert_grep "9. Run any shim, lab, or measurement script through" "$brief" \
+      "$mode ship brief lacks the process-budget rule"
+    assert_grep "$ROOT/bin/fm-proc-budget.sh" "$brief" \
+      "$mode ship brief does not name the process-budget wrapper by path"
+  done
+  FM_HOME="$home" "$ROOT/bin/fm-brief.sh" brief-budget-scout alpha --scout >/dev/null 2>&1 \
+    || fail "fm-brief.sh --scout exited non-zero"
+  brief="$home/data/brief-budget-scout/brief.md"
+  assert_grep "9. Run any shim, lab, or measurement script through" "$brief" \
+    "scout brief lacks the process-budget rule"
+  ship_rule=$(grep '^9\. Run any shim' "$home/data/brief-budget-no-mistakes/brief.md")
+  scout_rule=$(grep '^9\. Run any shim' "$brief")
+  [ -n "$ship_rule" ] && [ "$ship_rule" = "$scout_rule" ] \
+    || fail "ship and scout process-budget rules have drifted apart"
+  FM_SECONDMATE_CHARTER='Supervise the alpha domain.' \
+    FM_HOME="$home" "$ROOT/bin/fm-brief.sh" brief-budget-mate --secondmate alpha >/dev/null 2>&1 \
+    || fail "fm-brief.sh --secondmate exited non-zero"
+  assert_no_grep "fm-proc-budget.sh" "$home/data/brief-budget-mate/brief.md" \
+    "a secondmate charter is not a crewmate scratch-script rule"
+  pass "fm-brief.sh: every crewmate scaffold routes scratch scripts through the process budget"
+}
+
 test_script_parses
 test_no_heredoc_in_command_substitution
 test_help_includes_entire_header
 test_ship_modes_generate_clean_briefs
 test_ship_mode_is_required_and_closed_set
+test_crewmate_scaffolds_route_scratch_scripts_through_the_process_budget
 test_ship_mode_is_explicit_not_registry
 test_delivery_flags_are_refused_where_they_do_not_apply
 test_faster_paths_use_configured_authority_without_stacked_review
diff --git a/tests/fm-proc-budget.test.sh b/tests/fm-proc-budget.test.sh
new file mode 100755
index 00000000000..227b44c71f0
--- /dev/null
+++ b/tests/fm-proc-budget.test.sh
@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# fm-proc-budget.test.sh - bin/fm-proc-budget.sh: the per-tree process budget.
+#
+# The kernel compares the RLIMIT_NPROC limit with the user's whole process
+# count, so a runaway tree can starve every other process of the same user.
+# These cases drive the wrapper as a separate process: the limit arithmetic
+# against a stub `ps`, the refusals, and the incident reproduction - a shim
+# whose `basename` is itself, run under a small budget - which must stop inside
+# the budgeted tree while an unbudgeted probe keeps forking.
+# Child commands are single-quoted on purpose: they expand in the child bash.
+# shellcheck disable=SC2016
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+# shellcheck source=bin/fm-timeout-lib.sh
+. "$ROOT/bin/fm-timeout-lib.sh"
+
+WRAP="$ROOT/bin/fm-proc-budget.sh"
+TMP_ROOT=$(fm_test_tmproot fm-proc-budget)
+unset FM_PROC_BUDGET FM_PROC_BUDGET_EXTRA
+
+assert_present "$WRAP" "bin/fm-proc-budget.sh is missing"
+[ -x "$WRAP" ] || fail "bin/fm-proc-budget.sh must be executable"
+
+# A `ps` that reports a fixed number of processes, so the arithmetic is exact.
+mkdir -p "$TMP_ROOT/stub-ps"
+cat >"$TMP_ROOT/stub-ps/ps" <<'SH'
+#!/bin/sh
+i=0
+while [ "$i" -lt "${FM_TEST_PS_COUNT:-0}" ]; do
+  echo "$i"
+  i=$((i + 1))
+done
+exit "${FM_TEST_PS_STATUS:-0}"
+SH
+chmod +x "$TMP_ROOT/stub-ps/ps"
+
+# The child is a builtin-only bash, so lowering the limit below the host's real
+# process count (the stub reports far fewer) never blocks the child itself.
+limit_with_stub() {  # <ps-count> <wrapper args...>
+  local count=$1
+  shift
+  PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=$count \
+    "$WRAP" "$@" -- bash -c 'ulimit -u'
+}
+
+test_default_extra_is_added_to_the_count() {
+  local got
+  got=$(limit_with_stub 7) || fail "wrapper refused a plain command"
+  assert_equals 1507 "$got" "the default budget is the process count plus 1500"
+  pass "default budget is the current count plus 1500"
+}
+
+test_explicit_and_env_extra() {
+  local got
+  got=$(limit_with_stub 7 40) || fail "wrapper refused an explicit extra"
+  assert_equals 47 "$got" "an explicit extra replaces the default"
+  got=$(FM_PROC_BUDGET_EXTRA=90 limit_with_stub 7) || fail "wrapper refused FM_PROC_BUDGET_EXTRA"
+  assert_equals 97 "$got" "FM_PROC_BUDGET_EXTRA replaces the default"
+  got=$(FM_PROC_BUDGET_EXTRA=90 limit_with_stub 7 40) || fail "wrapper refused both extras"
+  assert_equals 47 "$got" "an explicit extra wins over FM_PROC_BUDGET_EXTRA"
+  pass "explicit extra and FM_PROC_BUDGET_EXTRA set the budget"
+}
+
+test_budget_never_widens_the_inherited_limit() {
+  local real low got
+  real=$("$WRAP" --count) || fail "--count failed"
+  low=$((real + 1500))
+  got=$(PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=100000 \
+    bash -c 'ulimit -u "$1"; shift; exec "$@"' _ "$low" "$WRAP" 1500 -- bash -c 'ulimit -u') \
+    || fail "wrapper failed under a lower inherited limit"
+  assert_equals "$low" "$got" "a budget above the inherited limit leaves it unchanged"
+  got=$(PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=7 \
+    bash -c 'ulimit -u "$1"; shift; exec "$@"' _ "$low" "$WRAP" 40 -- \
+    bash -c 'ulimit -u 99999 2>/dev/null && echo raised; ulimit -u') \
+    || fail "wrapper failed under a higher inherited limit"
+  assert_equals 47 "$got" "a budget below the inherited limit lowers it, and the child cannot raise it again"
+  pass "a budget only ever tightens the limit it inherits"
+}
+
+test_exit_status_and_arguments_pass_through() {
+  local rc out
+  "$WRAP" 100 -- bash -c 'exit 7'
+  rc=$?
+  expect_code 7 "$rc" "the child's exit status is the wrapper's"
+  out=$("$WRAP" 100 -- printf '%s|' 'a b' c) || fail "arguments were not passed through"
+  assert_equals 'a b|c|' "$out" "arguments reach the child intact"
+  out=$("$WRAP" -- printf 'x') || fail "omitting the extra must use the default"
+  assert_equals x "$out" "-- alone selects the default budget"
+  pass "exit status and arguments pass through"
+}
+
+test_kill_switch_runs_the_command_unbudgeted() {
+  local inherited got
+  inherited=$(ulimit -u)
+  got=$(FM_PROC_BUDGET=off PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=7 \
+    "$WRAP" 40 -- bash -c 'ulimit -u') || fail "FM_PROC_BUDGET=off refused the command"
+  assert_equals "$inherited" "$got" "FM_PROC_BUDGET=off leaves the limit alone"
+  pass "FM_PROC_BUDGET=off runs the command without a budget"
+}
+
+test_refusals_never_run_the_command() {
+  local rc marker="$TMP_ROOT/ran" args
+  for args in "" "nope" "0" "-5" "1.5"; do
+    rm -f "$marker"
+    if [ -z "$args" ]; then
+      "$WRAP" -- 2>/dev/null
+    else
+      "$WRAP" "$args" -- touch "$marker" 2>/dev/null
+    fi
+    rc=$?
+    expect_code 2 "$rc" "bad extra '${args}'"
+    assert_absent "$marker" "a refused call must not run the command (extra '${args}')"
+  done
+  "$WRAP" 100 touch "$marker" 2>/dev/null
+  rc=$?
+  expect_code 2 "$rc" "a missing -- separator"
+  assert_absent "$marker" "a call without -- must not run the command"
+
+  # No readable process count means no budget can be set; the command must not
+  # run unbudgeted behind the caller's back.
+  PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=0 "$WRAP" 100 -- touch "$marker" 2>/dev/null
+  rc=$?
+  expect_code 125 "$rc" "an empty process count"
+  assert_absent "$marker" "an unreadable count must not run the command"
+  PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=50 FM_TEST_PS_STATUS=1 \
+    "$WRAP" 100 -- touch "$marker" 2>/dev/null
+  rc=$?
+  expect_code 125 "$rc" "a failing ps"
+  assert_absent "$marker" "a failing ps must not run the command"
+  pass "bad calls and an unreadable process count never run the command"
+}
+
+test_check_reports_whether_a_budget_can_be_set() {
+  "$WRAP" --check >"$TMP_ROOT/check.out" 2>&1 || fail "--check failed on this host: $(cat "$TMP_ROOT/check.out")"
+  if PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=0 "$WRAP" --check >"$TMP_ROOT/check.out" 2>&1; then
+    fail "--check must fail when the process count is unreadable"
+  fi
+  [ -s "$TMP_ROOT/check.out" ] || fail "--check must say why it failed"
+  pass "--check reports whether a budget can be set"
+}
+
+# The incident, leashed. Worker fm-board-listener-retire linked `basename` to a
+# shim whose first line calls `basename`: every call started another copy, with
+# no base case, until the user's process cap stopped it and every other lane
+# lost forks. SHIM_MAX_DEPTH is only a safety valve so a regression of the
+# wrapper cannot pile up thousands of processes on the host.
+make_bomb() {  # <dir>
+  local dir=$1 name
+  mkdir -p "$dir"
+  cat >"$dir/shim.sh" <<'SH'
+#!/usr/bin/env bash
+SHIM_DEPTH=$(( ${SHIM_DEPTH:-0} + 1 )); export SHIM_DEPTH
+printf '%s\n' "$SHIM_DEPTH" >> "$SHIM_LOG"
+[ "$SHIM_DEPTH" -le "$SHIM_MAX_DEPTH" ] || exit 99
+n=$(basename "$0")
+exec "$n" "$@"
+SH
+  chmod +x "$dir/shim.sh"
+  for name in basename date; do ln -sf shim.sh "$dir/$name"; done
+}
+
+test_budget_stops_a_runaway_tree_inside_the_tree() {
+  local bomb="$TMP_ROOT/bomb" log="$TMP_ROOT/bomb.log" err="$TMP_ROOT/bomb.err"
+  local probe="$TMP_ROOT/probe.out" true_bin depth probe_pid rc
+  true_bin=/usr/bin/true
+  [ -x "$true_bin" ] || true_bin=/bin/true
+  make_bomb "$bomb"
+  : >"$log"
+
+  # An unbudgeted probe forks as fast as it can for as long as the bomb runs;
+  # a fork failure outside the budgeted tree ends it without the done marker.
+  bash -c '
+    n=0
+    while [ ! -e "$2" ]; do "$1" || exit 3; n=$((n + 1)); done
+    echo "done $n" >"$3"
+  ' _ "$true_bin" "$TMP_ROOT/probe.stop" "$probe" 2>"$TMP_ROOT/probe.err" &
+  probe_pid=$!
+
+  fm_run_timed 90 "$WRAP" 300 -- env PATH="$bomb:$PATH" SHIM_LOG="$log" SHIM_MAX_DEPTH=1500 \
+    date +%s >"$TMP_ROOT/bomb.out" 2>"$err"
+  rc=$?
+  : >"$TMP_ROOT/probe.stop"
+  wait "$probe_pid"
+  expect_code 0 $? "the unbudgeted probe must keep forking while the budgeted tree runs away"
+
+  depth=$(tail -1 "$log")
+  [ -n "$depth" ] || fail "the bomb never started: $(cat "$err")"
+  [ "$depth" -gt 20 ] || fail "the bomb did not recurse (depth $depth): the case would be vacuous"
+  [ "$depth" -lt 1500 ] || fail "the budget did not stop the runaway tree (depth $depth, rc $rc)"
+  assert_contains "$(cat "$err")" "Resource temporarily unavailable" \
+    "the runaway tree must meet the process limit inside its own tree"
+  [ -s "$probe" ] || fail "the probe outside the budget lost a fork: $(cat "$TMP_ROOT/probe.err")"
+  assert_contains "$(cat "$probe")" "done " "the probe outside the budget must finish cleanly"
+  pass "a budgeted runaway tree stops at depth $depth while an unbudgeted probe forks freely"
+}
+
+test_default_extra_is_added_to_the_count
+test_explicit_and_env_extra
+test_budget_never_widens_the_inherited_limit
+test_exit_status_and_arguments_pass_through
+test_kill_switch_runs_the_command_unbudgeted
+test_refusals_never_run_the_command
+test_check_reports_whether_a_budget_can_be_set
+test_budget_stops_a_runaway_tree_inside_the_tree
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index e15cc042629..a2ee4453829 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -2132,6 +2132,59 @@ SH
   pass "the runner reaps the stub a killed script left behind"
 }
 
+# A script that forks without bound must stop at its own limit instead of
+# filling the user's process table for every other lane (the 2026-10-08
+# fork-EAGAIN incident), so the runner starts each script under the per-tree
+# process budget of bin/fm-proc-budget.sh. The fixture reports the limit it
+# runs under; the runner's own limit is the comparison.
+test_each_script_runs_under_a_process_budget() {
+  local tmp repo fixture inherited seen
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-budget.XXXXXX")
+  repo="$tmp/repo"
+  fixture=tests/fm-budget-fixture.test.sh
+  mkdir -p "$repo/bin" "$repo/tests" "$tmp/failing-ps"
+  cp "$RUNNER" "$repo/bin/fm-test-run.sh"
+  cp "$ROOT/bin/fm-proc-budget.sh" "$ROOT/bin/fm-timeout-lib.sh" "$repo/bin/"
+  cp "$ROOT/tests/git-config-helpers.sh" "$repo/tests/"
+  cat >"$repo/$fixture" <<'SH'
+#!/usr/bin/env bash
+echo "ok - fixture runs under limit $(ulimit -u)"
+SH
+  printf '#!/bin/sh\nexit 1\n' >"$tmp/failing-ps/ps"
+  chmod +x "$repo/bin/fm-test-run.sh" "$repo/$fixture" "$tmp/failing-ps/ps"
+  inherited=$(ulimit -u)
+
+  "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out" 2>"$tmp/err" \
+    || fail "the budgeted run failed: $(cat "$tmp/out" "$tmp/err")"
+  seen=$(sed -n 's/.*fixture runs under limit //p' "$tmp/out")
+  case "$seen" in
+    ''|*[!0-9]*) fail "the fixture did not report a numeric limit (got '$seen'): $(cat "$tmp/out")" ;;
+  esac
+  [ "$seen" -lt "$inherited" ] \
+    || fail "the script ran without a process budget (limit $seen, inherited $inherited)"
+
+  FM_PROC_BUDGET_EXTRA=900 "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out2" 2>"$tmp/err2" \
+    || fail "the sized run failed: $(cat "$tmp/out2" "$tmp/err2")"
+  [ "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out2")" -lt "$seen" ] \
+    || fail "FM_PROC_BUDGET_EXTRA=900 must give a smaller budget than the default"
+
+  FM_PROC_BUDGET=off "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out3" 2>"$tmp/err3" \
+    || fail "the unbudgeted run failed: $(cat "$tmp/out3" "$tmp/err3")"
+  assert_equals "$inherited" "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out3")" \
+    "FM_PROC_BUDGET=off must leave the inherited limit alone"
+
+  # A host that cannot read its process count still runs the suite, loudly.
+  PATH="$tmp/failing-ps:$PATH" "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out4" 2>"$tmp/err4" \
+    || fail "a host without a readable process count must still run scripts: $(cat "$tmp/out4" "$tmp/err4")"
+  assert_contains "$(cat "$tmp/err4")" "running without process budgets" \
+    "a host that cannot set a budget must say so"
+  assert_equals "$inherited" "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out4")" \
+    "without a budget the script keeps the inherited limit"
+
+  rm -rf "$tmp"
+  pass "each script runs under a per-tree process budget"
+}
+
 # The duration regression this guard exists for: a suite whose scripts are all
 # green but whose wall clock outgrew its caller's invocation budget. The caller
 # gets killed mid-run and retries invisibly, so an over-budget run has to be a
@@ -2494,6 +2547,7 @@ test_changed_shared_fixture_selects_its_readers
 test_concurrent_runs_are_ordered_longest_first
 test_per_script_timeout_bounds_a_hang
 test_runner_reaps_stubs_a_killed_script_left_behind
+test_each_script_runs_under_a_process_budget
 test_changed_bound_gives_slow_watcher_suites_headroom
 test_max_wall_ms_is_a_result_not_advice
 test_jobs_parallel_scheduler_and_failure_propagation

From 8274bfb7195c6192c5bdb385c37dd960fd07f205 Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Fri, 9 Oct 2026 02:27:37 -0500
Subject: [PATCH 2/6] no-mistakes(review): Seal process budgets and fix lab
 coverage and inheritance

---
 bin/fm-brief.sh              |  2 +-
 bin/fm-herdr-lab.sh          |  4 +-
 bin/fm-proc-budget.sh        | 47 ++++++++-------------
 bin/fm-test-run.sh           | 11 ++---
 docs/scripts.md              |  2 +-
 tests/fm-brief.test.sh       | 27 ++++++++++++
 tests/fm-herdr-lab.test.sh   | 46 ++++++++++++++++++---
 tests/fm-proc-budget.test.sh | 80 ++++++++++++++++++++----------------
 tests/fm-test-run.test.sh    | 56 ++++++++++++++-----------
 9 files changed, 167 insertions(+), 108 deletions(-)

diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh
index fe313768d4f..a0591437b88 100755
--- a/bin/fm-brief.sh
+++ b/bin/fm-brief.sh
@@ -600,7 +600,7 @@ SHARED_INFRA_RULE=${SHARED_INFRA_RULE%$'\n'}
 # The kernel counts the user's whole process table, so one runaway scratch tree
 # starves every lane; bin/fm-proc-budget.sh owns the budget, this is the one
 # line that reaches ad-hoc scripts no runner wraps.
-SHARED_PROC_BUDGET_RULE="9. Run any shim, lab, or measurement script through \`$FM_ROOT/bin/fm-proc-budget.sh -- <command...>\`: a runaway process tree then stops at its own limit instead of starving every lane of fork."
+SHARED_PROC_BUDGET_RULE="9. Run any shim, lab, or measurement script through \`$(shell_quote "$FM_ROOT/bin/fm-proc-budget.sh") -- <command...>\`: a runaway process tree then stops at its own limit instead of starving every lane of fork."
 
 if [ -n "$BASE_BRANCH" ]; then
   SETUP_BASE="You are in a disposable git worktree of $REPO, at a detached HEAD on a clean copy of its base branch.
diff --git a/bin/fm-herdr-lab.sh b/bin/fm-herdr-lab.sh
index 12a041f2acc..0be0bbeaf4c 100755
--- a/bin/fm-herdr-lab.sh
+++ b/bin/fm-herdr-lab.sh
@@ -302,7 +302,7 @@ fm_herdr_lab_viewer_start() { # <session>
     trap 'trap - INT TERM; [ -z "${launcher_pid:-}" ] || fm_herdr_lab_cancel_viewer_launcher "$launcher_pid"; exit 130' INT
     trap 'trap - INT TERM; [ -z "${launcher_pid:-}" ] || fm_herdr_lab_cancel_viewer_launcher "$launcher_pid"; exit 143' TERM
   fi
-  nohup python3 "$launcher" "$name" "$record" >"$log" 2>&1 &
+  nohup "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fm-proc-budget.sh" -- python3 "$launcher" "$name" "$record" >"$log" 2>&1 &
   launcher_pid=$!
 
   waited=0
@@ -434,7 +434,7 @@ fm_herdr_lab_provision() { # <session>
   else
     fm_herdr_lab_prepare "$name" || return 1
   fi
-  fm_herdr_lab_raw "$name" server >/dev/null 2>&1 &
+  HERDR_SESSION="$name" "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fm-proc-budget.sh" -- herdr server --session "$name" >/dev/null 2>&1 &
   server_pid=$!
   attempt=0
   max_attempts=300
diff --git a/bin/fm-proc-budget.sh b/bin/fm-proc-budget.sh
index 815b4ead6dc..070200ad1d6 100755
--- a/bin/fm-proc-budget.sh
+++ b/bin/fm-proc-budget.sh
@@ -3,8 +3,6 @@
 #
 # Usage:
 #   fm-proc-budget.sh [<extra>] -- <command...>   run <command...> with a budget
-#   fm-proc-budget.sh --count                     print the user's process count
-#   fm-proc-budget.sh --check                     exit 0 when a budget can be set here
 #
 # The kernel compares RLIMIT_NPROC with the user's WHOLE process count, not with
 # one process tree. A runaway tree therefore starves every other process of the
@@ -13,7 +11,7 @@
 # the current count and sets the limit (soft and hard) to count + <extra>, then
 # execs the command, so only the tree below it carries the lowered limit and the
 # rest of the user keeps its headroom. <extra> is a positive decimal integer;
-# omit it for FM_PROC_BUDGET_EXTRA, or 1500 when that is unset.
+# omit it for 1500.
 #
 # The budget only tightens. A limit the command already inherits that is lower
 # than count + <extra> stays as it is, and the hard limit is lowered with the
@@ -22,10 +20,7 @@
 #
 # Only commands started through the wrapper are protected. Route every shim,
 # lab, and measurement script through it; bin/fm-test-run.sh and
-# bin/fm-live-lab.sh do so for the trees they start.
-#
-# FM_PROC_BUDGET=off runs the command with no budget, for a host where the
-# budget turns out to starve a legitimate tree.
+# bin/fm-live-lab.sh and bin/fm-herdr-lab.sh do so for the trees they start.
 #
 # The budget is headroom over the count at the moment the command starts, so a
 # tree that outlives a large rise in the rest of the user's processes can meet
@@ -41,7 +36,7 @@ fm_proc_budget_error() {
 }
 
 fm_proc_budget_usage() {
-  fm_proc_budget_error "usage: fm-proc-budget.sh [<extra>] -- <command...> | --count | --check"
+  fm_proc_budget_error "usage: fm-proc-budget.sh [<extra>] -- <command...>"
 }
 
 # The kernel counts what RLIMIT_NPROC is compared with: processes on Darwin,
@@ -64,19 +59,27 @@ fm_proc_budget_count() {
 # fm_proc_budget_apply <extra>: lower this process's limit to count + <extra>
 # unless the inherited limit is already lower. Prints nothing on success.
 fm_proc_budget_apply() {
-  local extra=$1 count current limit
+  local extra=$1 count current hard limit
   count=$(fm_proc_budget_count) || {
     fm_proc_budget_error "cannot read the process count, so no budget can be set"
     return 125
   }
   limit=$((count + extra))
-  current=$(ulimit -u) || {
+  current=$(ulimit -S -u) || {
     fm_proc_budget_error "cannot read the current process limit"
     return 125
   }
+  hard=$(ulimit -H -u) || {
+    fm_proc_budget_error "cannot read the hard process limit"
+    return 125
+  }
   case "$current" in
     ''|*[!0-9]*) ;;  # unlimited: the budget is the only bound
-    *) [ "$limit" -lt "$current" ] || return 0 ;;
+    *) [ "$limit" -lt "$current" ] || limit=$current ;;
+  esac
+  case "$hard" in
+    ''|*[!0-9]*) ;;
+    *) [ "$limit" -lt "$hard" ] || limit=$hard ;;
   esac
   ulimit -u "$limit" 2>/dev/null || {
     fm_proc_budget_error "this host refused a process limit of $limit (count $count + $extra)"
@@ -84,23 +87,7 @@ fm_proc_budget_apply() {
   }
 }
 
-case "${1:-}" in
-  --count)
-    fm_proc_budget_count || {
-      fm_proc_budget_error "cannot read the process count"
-      exit 125
-    }
-    exit 0
-    ;;
-  --check)
-    # The limit is applied in a subshell, so this process keeps its own.
-    ( fm_proc_budget_apply 1500 ) || exit 1
-    echo "fm-proc-budget: a process budget can be set on this host"
-    exit 0
-    ;;
-esac
-
-extra=${FM_PROC_BUDGET_EXTRA:-1500}
+extra=1500
 if [ "${1:-}" != -- ] && [ "$#" -gt 0 ]; then
   extra=$1
   shift
@@ -118,7 +105,5 @@ case "$extra" in
     ;;
 esac
 
-if [ "${FM_PROC_BUDGET:-}" != off ]; then
-  fm_proc_budget_apply "$extra" || exit 125
-fi
+fm_proc_budget_apply "$extra" || exit 125
 exec "$@"
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 90d3efc1522..ad77d88e1bc 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -138,9 +138,9 @@
 # Every executed script also runs under a per-tree process budget
 # (bin/fm-proc-budget.sh owns it): a script that forks without bound stops at its
 # own limit instead of filling the user's process table for every other lane.
-# The budget is taken when the script starts, after any pass wait. FM_PROC_BUDGET=off
-# disables it, FM_PROC_BUDGET_EXTRA sizes it, and a host that cannot set one runs
-# scripts without it and says so on stderr.
+# The budget is taken when the script starts, after any pass wait. If the budget
+# cannot be set, that script fails with wrapper exit 125 rather than running
+# unbudgeted.
 # With a usable pool, --jobs above its size still starts that many workers,
 # but only pool-size scripts run at once.
 #
@@ -2476,11 +2476,8 @@ elif ! command -v python3 >/dev/null 2>&1; then
   log "running without CPU passes: python3 not found"
 fi
 PROC_BUDGET_ACTIVE=1
-if [ ! -x "$ROOT/bin/fm-proc-budget.sh" ] || [ "${FM_PROC_BUDGET:-}" = off ]; then
+if [ ! -x "$ROOT/bin/fm-proc-budget.sh" ]; then
   PROC_BUDGET_ACTIVE=0
-elif ! proc_budget_note=$("$ROOT/bin/fm-proc-budget.sh" --check 2>&1); then
-  PROC_BUDGET_ACTIVE=0
-  log "running without process budgets: $proc_budget_note"
 fi
 if [ "$JOBS" -gt 1 ] || [ "$MODE" = changed ] || [ "$MODE" = scripts ]; then
   SELECTION_DESC="${SELECTION_DESC};jobs=$JOBS"
diff --git a/docs/scripts.md b/docs/scripts.md
index 34927675558..4195023367f 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -55,7 +55,7 @@ The shared no-mistakes gate lifecycle boundary is summarized in [architecture.md
 | `fm-test-isolation-proof.sh` | Concurrent isolation harness and portable candidate set owner |
 | `fm-cpu-pass.sh`         | Reserve an exact positive worker count, no larger than the host CPU count, while a CPU-heavy burst runs ([protocol](cpu-pass-pool.md)) |
 | `fm-cpu-pass.py`         | The engine behind `fm-cpu-pass.sh`                                                   |
-| `fm-proc-budget.sh`      | Run a command tree under a per-tree process budget so a runaway tree stops at its own limit instead of filling the user's process table |
+| `fm-proc-budget.sh`      | Run `[<extra>] -- <command...>` with sealed soft/hard process limits (current user count + extra, default 1500), retaining tighter inherited limits and refusing execution when protection cannot be set |
 | `fm-load-report.sh`      | Record host load and judge it with pipeline agent durations ([recipe](cpu-pass-pool.md#judging-the-pool)) |
 | `fm-load-report.py`      | The engine behind `fm-load-report.sh`                                                |
 | `fm-ensure-agents-md.sh` | Manually initialize project agent-memory files (see the helper's header and help) |
diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh
index d351e4a0725..ad6bba3eb44 100755
--- a/tests/fm-brief.test.sh
+++ b/tests/fm-brief.test.sh
@@ -1546,12 +1546,39 @@ test_crewmate_scaffolds_route_scratch_scripts_through_the_process_budget() {
   pass "fm-brief.sh: every crewmate scaffold routes scratch scripts through the process budget"
 }
 
+test_process_budget_command_quotes_foreign_firstmate_path() {
+  local home="$TMP_ROOT/budget-foreign-home" mode id brief rule command got
+  local foreign_root="$TMP_ROOT/budget helper's root"
+  mkdir -p "$home/data" "$foreign_root/bin"
+  cp "$ROOT/bin/fm-proc-budget.sh" "$foreign_root/bin/"
+  for mode in no-mistakes direct-PR local-only scout; do
+    id="brief-budget-foreign-$mode"
+    if [ "$mode" = scout ]; then
+      FM_HOME="$home" FM_ROOT_OVERRIDE="$foreign_root" "$ROOT/bin/fm-brief.sh" "$id" foreign --scout >/dev/null 2>&1 \
+        || fail "foreign-root scout brief failed"
+    else
+      FM_HOME="$home" FM_ROOT_OVERRIDE="$foreign_root" "$ROOT/bin/fm-brief.sh" "$id" foreign --mode "$mode" >/dev/null 2>&1 \
+        || fail "foreign-root $mode brief failed"
+    fi
+    brief="$home/data/$id/brief.md"
+    rule=$(grep '^9\. Run any shim' "$brief")
+    command=${rule#*\`}
+    command=${command%%\`*}
+    command=${command% -- <command...>}
+    got=$(bash -c "$command -- printf '%s' 'budget command executed'") \
+      || fail "the emitted $mode budget command could not execute from a quoted root"
+    assert_equals "budget command executed" "$got" "the emitted $mode command must execute the wrapper"
+  done
+  pass "fm-brief.sh: emitted process-budget commands execute from foreign paths"
+}
+
 test_script_parses
 test_no_heredoc_in_command_substitution
 test_help_includes_entire_header
 test_ship_modes_generate_clean_briefs
 test_ship_mode_is_required_and_closed_set
 test_crewmate_scaffolds_route_scratch_scripts_through_the_process_budget
+test_process_budget_command_quotes_foreign_firstmate_path
 test_ship_mode_is_explicit_not_registry
 test_delivery_flags_are_refused_where_they_do_not_apply
 test_faster_paths_use_configured_authority_without_stacked_review
diff --git a/tests/fm-herdr-lab.test.sh b/tests/fm-herdr-lab.test.sh
index 24a630b0db4..2f2cf2ec1c0 100755
--- a/tests/fm-herdr-lab.test.sh
+++ b/tests/fm-herdr-lab.test.sh
@@ -46,6 +46,8 @@ case "$1 ${2:-}" in
     fi
     ;;
   "server --session")
+    ulimit -S -u > "$state/$session.limit"
+    ulimit -H -u >> "$state/$session.limit"
     if [ "${FM_FAKE_HERDR_SERVER_DELAY:-0}" != 0 ]; then
       "$FM_FAKE_HERDR_REAL_SLEEP" "$FM_FAKE_HERDR_SERVER_DELAY"
     fi
@@ -96,6 +98,23 @@ run_with_fake() {
     "$@"
 }
 
+assert_lab_process_budget() {
+  local file=$1 soft hard inherited
+  {
+    IFS= read -r soft
+    IFS= read -r hard
+  } < "$file" || fail "lab process did not record both limits"
+  case "$soft" in
+    ''|*[!0-9]*) fail "lab process did not inherit a numeric budget: $soft" ;;
+  esac
+  assert_equals "$soft" "$hard" "lab process must not be able to raise its budget"
+  inherited=$(ulimit -S -u)
+  case "$inherited" in
+    ''|*[!0-9]*) ;;
+    *) [ "$soft" -lt "$inherited" ] || fail "lab process did not lower the fixture's process limit" ;;
+  esac
+}
+
 test_refuses_unsafe_names() {
   local status=0 generated
   fm_herdr_lab_validate_name default >/dev/null 2>&1 || status=$?
@@ -111,12 +130,20 @@ test_refuses_unsafe_names() {
 }
 
 test_provision_run_and_guarded_teardown() {
-  local name='' line_count status=0 stop_line delete_line
+  local name='' line_count status=0 stop_line delete_line inherited
   name="fm-lab-behavior-$$"
   : > "$FAKE_LOG"
-  run_with_fake fm_herdr_lab_provision "$name" || fail "provision failed"
+  inherited=$(ulimit -S -u)
+  (
+    case "$inherited" in
+      ''|*[!0-9]*) ;;
+      *) ulimit -S -u "$((inherited - 1))" || exit 125 ;;
+    esac
+    run_with_fake fm_herdr_lab_provision "$name"
+  ) || fail "provision failed"
   [ "$(cat "$FAKE_STATE/$name")" = running ] || fail "provision did not start the named lab session"
   assert_present "$TRIPWIRES/$name.fleet-state.json" "provision did not record the fleet-state tripwire"
+  assert_lab_process_budget "$FAKE_STATE/$name.limit"
 
   run_with_fake fm_herdr_lab_cli "$name" workspace list >/dev/null || fail "safe run command failed"
   run_with_fake fm_herdr_lab_cli "$name" server >/dev/null 2>&1 || status=$?
@@ -323,20 +350,29 @@ write_viewer_record() {
 }
 
 test_viewer_start_cancels_an_unrecorded_launcher() {
-  local name="fm-lab-viewer-late-$$" out status=0 launcher_pid
+  local name="fm-lab-viewer-late-$$" out status=0 launcher_pid inherited
   local started="$TMP_ROOT/viewer-launcher-started"
   run_with_fake fm_herdr_lab_provision "$name" || fail "viewer-late fixture provision failed"
   cat > "$FAKEBIN/python3" <<'SH'
 #!/usr/bin/env bash
+ulimit -S -u > "$FM_FAKE_VIEWER_STARTED.limit"
+ulimit -H -u >> "$FM_FAKE_VIEWER_STARTED.limit"
 printf '%s\n' "$$" > "$FM_FAKE_VIEWER_STARTED"
 exec "$FM_FAKE_HERDR_REAL_SLEEP" 20
 SH
   chmod +x "$FAKEBIN/python3"
-  out=$(FM_FAKE_HERDR_FAST_POLL=1 FM_FAKE_HERDR_WAIT_MARKER="$started" \
-    FM_FAKE_VIEWER_STARTED="$started" run_with_fake fm_herdr_lab_viewer_start "$name" 2>&1) || status=$?
+  inherited=$(ulimit -S -u)
+  out=$(
+    if [ "$inherited" != unlimited ]; then
+      ulimit -S -u "$((inherited - 1))" || exit 125
+    fi
+    FM_FAKE_HERDR_FAST_POLL=1 FM_FAKE_HERDR_WAIT_MARKER="$started" \
+      FM_FAKE_VIEWER_STARTED="$started" run_with_fake fm_herdr_lab_viewer_start "$name" 2>&1
+  ) || status=$?
   rm -f "$FAKEBIN/python3"
   expect_code 1 "$status" "an unrecorded launcher must not outlive viewer start"
   assert_present "$started" "delayed viewer launcher did not start"
+  assert_lab_process_budget "$started.limit"
   launcher_pid=$(cat "$started")
   kill -0 "$launcher_pid" 2>/dev/null && fail "timed-out viewer launcher remained alive"
   assert_contains "$out" "did not become the foreground client" "launcher timeout was unclear"
diff --git a/tests/fm-proc-budget.test.sh b/tests/fm-proc-budget.test.sh
index 227b44c71f0..d1e60bf7539 100755
--- a/tests/fm-proc-budget.test.sh
+++ b/tests/fm-proc-budget.test.sh
@@ -10,6 +10,7 @@
 # Child commands are single-quoted on purpose: they expand in the child bash.
 # shellcheck disable=SC2016
 set -u
+set -o pipefail
 
 # shellcheck source=tests/lib.sh
 . "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
@@ -18,7 +19,6 @@ set -u
 
 WRAP="$ROOT/bin/fm-proc-budget.sh"
 TMP_ROOT=$(fm_test_tmproot fm-proc-budget)
-unset FM_PROC_BUDGET FM_PROC_BUDGET_EXTRA
 
 assert_present "$WRAP" "bin/fm-proc-budget.sh is missing"
 [ -x "$WRAP" ] || fail "bin/fm-proc-budget.sh must be executable"
@@ -45,40 +45,67 @@ limit_with_stub() {  # <ps-count> <wrapper args...>
     "$WRAP" "$@" -- bash -c 'ulimit -u'
 }
 
+effective_limit() {
+  local limit=$1 inherited
+  for inherited in "$(ulimit -S -u)" "$(ulimit -H -u)"; do
+    case "$inherited" in
+      ''|*[!0-9]*) ;;
+      *) [ "$limit" -lt "$inherited" ] || limit=$inherited ;;
+    esac
+  done
+  printf '%s\n' "$limit"
+}
+
 test_default_extra_is_added_to_the_count() {
   local got
   got=$(limit_with_stub 7) || fail "wrapper refused a plain command"
-  assert_equals 1507 "$got" "the default budget is the process count plus 1500"
+  assert_equals "$(effective_limit 1507)" "$got" "the default budget is the process count plus 1500, capped by inheritance"
   pass "default budget is the current count plus 1500"
 }
 
-test_explicit_and_env_extra() {
+test_explicit_extra() {
   local got
   got=$(limit_with_stub 7 40) || fail "wrapper refused an explicit extra"
-  assert_equals 47 "$got" "an explicit extra replaces the default"
-  got=$(FM_PROC_BUDGET_EXTRA=90 limit_with_stub 7) || fail "wrapper refused FM_PROC_BUDGET_EXTRA"
-  assert_equals 97 "$got" "FM_PROC_BUDGET_EXTRA replaces the default"
-  got=$(FM_PROC_BUDGET_EXTRA=90 limit_with_stub 7 40) || fail "wrapper refused both extras"
-  assert_equals 47 "$got" "an explicit extra wins over FM_PROC_BUDGET_EXTRA"
-  pass "explicit extra and FM_PROC_BUDGET_EXTRA set the budget"
+  assert_equals "$(effective_limit 47)" "$got" "an explicit extra replaces the default, capped by inheritance"
+  pass "explicit extra sets the budget"
 }
 
 test_budget_never_widens_the_inherited_limit() {
   local real low got
-  real=$("$WRAP" --count) || fail "--count failed"
-  low=$((real + 1500))
+  case "$(uname -s)" in
+    Linux) real=$(ps -L -U "$(id -u)" -o lwp= | wc -l) || fail "cannot read the baseline task count" ;;
+    *) real=$(ps -U "$(id -u)" -o pid= | wc -l) || fail "cannot read the baseline process count" ;;
+  esac
+  low=$(effective_limit "$((real + 1500))")
   got=$(PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=100000 \
-    bash -c 'ulimit -u "$1"; shift; exec "$@"' _ "$low" "$WRAP" 1500 -- bash -c 'ulimit -u') \
+    bash -c 'ulimit -u "$1" || exit 125; shift; exec "$@"' _ "$low" "$WRAP" 1500 -- \
+    bash -c 'printf "%s %s\n" "$(ulimit -S -u)" "$(ulimit -H -u)"') \
     || fail "wrapper failed under a lower inherited limit"
-  assert_equals "$low" "$got" "a budget above the inherited limit leaves it unchanged"
+  assert_equals "$low $low" "$got" "a budget above the inherited limit leaves both limits unchanged"
   got=$(PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=7 \
-    bash -c 'ulimit -u "$1"; shift; exec "$@"' _ "$low" "$WRAP" 40 -- \
+    bash -c 'ulimit -u "$1" || exit 125; shift; exec "$@"' _ "$low" "$WRAP" 40 -- \
     bash -c 'ulimit -u 99999 2>/dev/null && echo raised; ulimit -u') \
     || fail "wrapper failed under a higher inherited limit"
-  assert_equals 47 "$got" "a budget below the inherited limit lowers it, and the child cannot raise it again"
+  assert_equals "$(effective_limit 47)" "$got" "a budget below the inherited limit lowers it, and the child cannot raise it again"
   pass "a budget only ever tightens the limit it inherits"
 }
 
+test_retained_soft_limit_seals_the_hard_limit() {
+  local real low got
+  case "$(uname -s)" in
+    Linux) real=$(ps -L -U "$(id -u)" -o lwp= | wc -l) || fail "cannot read the baseline task count" ;;
+    *) real=$(ps -U "$(id -u)" -o pid= | wc -l) || fail "cannot read the baseline process count" ;;
+  esac
+  low=$(effective_limit "$((real + 500))")
+  low=$((low - 1))
+  got=$(PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=100000 \
+    bash -c 'ulimit -S -u "$1" || exit 125; shift; exec "$@"' _ "$low" "$WRAP" -- \
+    bash -c 'ulimit -S -u "$1" 2>/dev/null && echo raised; printf "%s %s\n" "$(ulimit -S -u)" "$(ulimit -H -u)"' _ "$((low + 1))") \
+    || fail "wrapper failed under a lower inherited soft limit"
+  assert_equals "$low $low" "$got" "a retained soft limit must also seal the hard limit and prevent raising it"
+  pass "a retained soft limit seals the inherited hard limit"
+}
+
 test_exit_status_and_arguments_pass_through() {
   local rc out
   "$WRAP" 100 -- bash -c 'exit 7'
@@ -91,15 +118,6 @@ test_exit_status_and_arguments_pass_through() {
   pass "exit status and arguments pass through"
 }
 
-test_kill_switch_runs_the_command_unbudgeted() {
-  local inherited got
-  inherited=$(ulimit -u)
-  got=$(FM_PROC_BUDGET=off PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=7 \
-    "$WRAP" 40 -- bash -c 'ulimit -u') || fail "FM_PROC_BUDGET=off refused the command"
-  assert_equals "$inherited" "$got" "FM_PROC_BUDGET=off leaves the limit alone"
-  pass "FM_PROC_BUDGET=off runs the command without a budget"
-}
-
 test_refusals_never_run_the_command() {
   local rc marker="$TMP_ROOT/ran" args
   for args in "" "nope" "0" "-5" "1.5"; do
@@ -132,15 +150,6 @@ test_refusals_never_run_the_command() {
   pass "bad calls and an unreadable process count never run the command"
 }
 
-test_check_reports_whether_a_budget_can_be_set() {
-  "$WRAP" --check >"$TMP_ROOT/check.out" 2>&1 || fail "--check failed on this host: $(cat "$TMP_ROOT/check.out")"
-  if PATH="$TMP_ROOT/stub-ps:$PATH" FM_TEST_PS_COUNT=0 "$WRAP" --check >"$TMP_ROOT/check.out" 2>&1; then
-    fail "--check must fail when the process count is unreadable"
-  fi
-  [ -s "$TMP_ROOT/check.out" ] || fail "--check must say why it failed"
-  pass "--check reports whether a budget can be set"
-}
-
 # The incident, leashed. Worker fm-board-listener-retire linked `basename` to a
 # shim whose first line calls `basename`: every call started another copy, with
 # no base case, until the user's process cap stopped it and every other lane
@@ -197,10 +206,9 @@ test_budget_stops_a_runaway_tree_inside_the_tree() {
 }
 
 test_default_extra_is_added_to_the_count
-test_explicit_and_env_extra
+test_explicit_extra
 test_budget_never_widens_the_inherited_limit
+test_retained_soft_limit_seals_the_hard_limit
 test_exit_status_and_arguments_pass_through
-test_kill_switch_runs_the_command_unbudgeted
 test_refusals_never_run_the_command
-test_check_reports_whether_a_budget_can_be_set
 test_budget_stops_a_runaway_tree_inside_the_tree
diff --git a/tests/fm-test-run.test.sh b/tests/fm-test-run.test.sh
index a2ee4453829..3b977258093 100755
--- a/tests/fm-test-run.test.sh
+++ b/tests/fm-test-run.test.sh
@@ -2138,11 +2138,11 @@ SH
 # process budget of bin/fm-proc-budget.sh. The fixture reports the limit it
 # runs under; the runner's own limit is the comparison.
 test_each_script_runs_under_a_process_budget() {
-  local tmp repo fixture inherited seen
+  local tmp repo fixture inherited seen expected count
   tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-test-run-budget.XXXXXX")
   repo="$tmp/repo"
   fixture=tests/fm-budget-fixture.test.sh
-  mkdir -p "$repo/bin" "$repo/tests" "$tmp/failing-ps"
+  mkdir -p "$repo/bin" "$repo/tests" "$tmp/failing-ps" "$tmp/budget-ps"
   cp "$RUNNER" "$repo/bin/fm-test-run.sh"
   cp "$ROOT/bin/fm-proc-budget.sh" "$ROOT/bin/fm-timeout-lib.sh" "$repo/bin/"
   cp "$ROOT/tests/git-config-helpers.sh" "$repo/tests/"
@@ -2151,35 +2151,41 @@ test_each_script_runs_under_a_process_budget() {
 echo "ok - fixture runs under limit $(ulimit -u)"
 SH
   printf '#!/bin/sh\nexit 1\n' >"$tmp/failing-ps/ps"
-  chmod +x "$repo/bin/fm-test-run.sh" "$repo/$fixture" "$tmp/failing-ps/ps"
-  inherited=$(ulimit -u)
+  case "$(uname -s)" in
+    Linux) count=$(set -o pipefail; ps -L -U "$(id -u)" -o lwp= | wc -l) || fail "cannot read the baseline task count" ;;
+    *) count=$(set -o pipefail; ps -U "$(id -u)" -o pid= | wc -l) || fail "cannot read the baseline process count" ;;
+  esac
+  cat >"$tmp/budget-ps/ps" <<SH
+#!/bin/sh
+i=0
+while [ "\$i" -lt "$count" ]; do
+  echo "\$i"
+  i=\$((i + 1))
+done
+SH
+  chmod +x "$repo/bin/fm-test-run.sh" "$repo/$fixture" "$tmp/failing-ps/ps" "$tmp/budget-ps/ps"
+  inherited=$(ulimit -S -u)
+  expected=$((count + 1500))
+  case "$inherited" in
+    ''|*[!0-9]*) ;;
+    *) [ "$expected" -lt "$inherited" ] || expected=$inherited ;;
+  esac
 
-  "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out" 2>"$tmp/err" \
+  PATH="$tmp/budget-ps:$PATH" "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out" 2>"$tmp/err" \
     || fail "the budgeted run failed: $(cat "$tmp/out" "$tmp/err")"
   seen=$(sed -n 's/.*fixture runs under limit //p' "$tmp/out")
   case "$seen" in
     ''|*[!0-9]*) fail "the fixture did not report a numeric limit (got '$seen'): $(cat "$tmp/out")" ;;
   esac
-  [ "$seen" -lt "$inherited" ] \
-    || fail "the script ran without a process budget (limit $seen, inherited $inherited)"
-
-  FM_PROC_BUDGET_EXTRA=900 "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out2" 2>"$tmp/err2" \
-    || fail "the sized run failed: $(cat "$tmp/out2" "$tmp/err2")"
-  [ "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out2")" -lt "$seen" ] \
-    || fail "FM_PROC_BUDGET_EXTRA=900 must give a smaller budget than the default"
-
-  FM_PROC_BUDGET=off "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out3" 2>"$tmp/err3" \
-    || fail "the unbudgeted run failed: $(cat "$tmp/out3" "$tmp/err3")"
-  assert_equals "$inherited" "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out3")" \
-    "FM_PROC_BUDGET=off must leave the inherited limit alone"
-
-  # A host that cannot read its process count still runs the suite, loudly.
-  PATH="$tmp/failing-ps:$PATH" "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out4" 2>"$tmp/err4" \
-    || fail "a host without a readable process count must still run scripts: $(cat "$tmp/out4" "$tmp/err4")"
-  assert_contains "$(cat "$tmp/err4")" "running without process budgets" \
-    "a host that cannot set a budget must say so"
-  assert_equals "$inherited" "$(sed -n 's/.*fixture runs under limit //p' "$tmp/out4")" \
-    "without a budget the script keeps the inherited limit"
+  assert_equals "$expected" "$seen" "the script budget must be capped by its inherited limit"
+
+  if PATH="$tmp/failing-ps:$PATH" "$repo/bin/fm-test-run.sh" "$fixture" >"$tmp/out4" 2>"$tmp/err4"; then
+    fail "a runner with an unreadable process count must fail"
+  fi
+  assert_not_contains "$(cat "$tmp/out4" "$tmp/err4")" "fixture runs under limit" \
+    "a failed budget must prevent fixture execution"
+  assert_contains "$(cat "$tmp/out4" "$tmp/err4")" "cannot read the process count" \
+    "a failed budget must report the wrapper's refusal"
 
   rm -rf "$tmp"
   pass "each script runs under a per-tree process budget"

From 3b0b9f1c039d32a0eb37d2d074fb6c52eb911272 Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Fri, 9 Oct 2026 04:49:16 -0500
Subject: [PATCH 3/6] no-mistakes(document): Clarify process-budget ownership
 and launch coverage

---
 bin/fm-herdr-lab.sh   |  3 +++
 bin/fm-live-lab.sh    |  6 +++---
 bin/fm-proc-budget.sh | 25 +++++++++++++------------
 bin/fm-test-run.sh    |  7 +++----
 docs/scripts.md       |  2 +-
 5 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/bin/fm-herdr-lab.sh b/bin/fm-herdr-lab.sh
index 0be0bbeaf4c..74ebac294c3 100755
--- a/bin/fm-herdr-lab.sh
+++ b/bin/fm-herdr-lab.sh
@@ -27,6 +27,9 @@
 # destructive call.
 # Provision records the running default session as a fleet-state tripwire and
 # teardown requires that record to be identical afterward.
+# Provision's server and the viewer launcher start through bin/fm-proc-budget.sh;
+# its header owns the inherited process-budget contract. Status, stop, and
+# teardown client calls are not wrapped, so budget setup cannot block cleanup.
 # The viewer command attaches or detaches one real foreground Herdr client on
 # an owned lab session over a fixed 40-row by 120-column pty;
 # bin/fm-herdr-lab-viewer.py owns the pty mechanics.
diff --git a/bin/fm-live-lab.sh b/bin/fm-live-lab.sh
index feb5a3ffbfe..6e80b31867f 100755
--- a/bin/fm-live-lab.sh
+++ b/bin/fm-live-lab.sh
@@ -39,6 +39,9 @@
 #                    tmux-dir, with no user tmux config (its plugins never run
 #                    in a lab), started from an empty environment so no inherited
 #                    TMUX, Herdr, or Pi marker reaches a lab process.
+#                    The server starts through bin/fm-proc-budget.sh (whose
+#                    header owns the budget contract), so every pane inherits
+#                    its process limit.
 #                    TREEHOUSE_ROOT points into <lab-root>, so a worker's pool
 #                    never lands in ~/.treehouse, and DISABLE_AUTOUPDATER=1
 #                    keeps Claude Code from replacing the shared binary under
@@ -172,9 +175,6 @@ lab_env_base() {
   [ -z "${CLAUDE_DIR:-}" ] || printf '%s\n' "CLAUDE_CONFIG_DIR=$CLAUDE_DIR"
 }
 
-# Every lab process starts under bin/fm-proc-budget.sh, so a runaway process tree
-# in the lab (the private tmux server carries the budget to every pane) stops at
-# its own limit instead of starving the user's other sessions of fork.
 lab_run() {  # [NAME=VALUE...] <command...>: run in the lab's clean environment
   local -a base=()
   local line
diff --git a/bin/fm-proc-budget.sh b/bin/fm-proc-budget.sh
index 070200ad1d6..6cf6d47100f 100755
--- a/bin/fm-proc-budget.sh
+++ b/bin/fm-proc-budget.sh
@@ -4,14 +4,14 @@
 # Usage:
 #   fm-proc-budget.sh [<extra>] -- <command...>   run <command...> with a budget
 #
-# The kernel compares RLIMIT_NPROC with the user's WHOLE process count, not with
-# one process tree. A runaway tree therefore starves every other process of the
-# same user until the cap is full, and a bash 3.2 script exits 128 at its first
-# failed fork. The only handle is to stop the runaway early: this wrapper reads
-# the current count and sets the limit (soft and hard) to count + <extra>, then
-# execs the command, so only the tree below it carries the lowered limit and the
-# rest of the user keeps its headroom. <extra> is a positive decimal integer;
-# omit it for 1500.
+# The kernel compares RLIMIT_NPROC with the user's WHOLE count, not with one
+# process tree: processes on Darwin, tasks (threads included) on Linux.
+# A runaway tree therefore starves every other process of the same user until
+# the cap is full, and a bash 3.2 script exits 128 at its first failed fork.
+# This wrapper reads the current count and sets the limit (soft and hard) to
+# count + <extra>, then execs the command, so only the tree below it carries the
+# lowered limit and the rest of the user keeps its headroom. <extra> is a
+# positive decimal integer; omit it for 1500.
 #
 # The budget only tightens. A limit the command already inherits that is lower
 # than count + <extra> stays as it is, and the hard limit is lowered with the
@@ -19,8 +19,8 @@
 # widens an outer budget.
 #
 # Only commands started through the wrapper are protected. Route every shim,
-# lab, and measurement script through it; bin/fm-test-run.sh and
-# bin/fm-live-lab.sh and bin/fm-herdr-lab.sh do so for the trees they start.
+# lab, and measurement script through it. The headers of bin/fm-test-run.sh,
+# bin/fm-live-lab.sh, and bin/fm-herdr-lab.sh own their launch integration.
 #
 # The budget is headroom over the count at the moment the command starts, so a
 # tree that outlives a large rise in the rest of the user's processes can meet
@@ -29,6 +29,9 @@
 # Exit status: the command's own, 2 for a malformed call, and 125 when no budget
 # can be set (an unreadable process count, or a limit the host refuses). The
 # command never runs unbudgeted behind the caller's back in those two cases.
+#
+# tests/fm-proc-budget.test.sh is the regression entry point for a leashed
+# recursive shim and an unbudgeted probe that must keep forking alongside it.
 set -u
 
 fm_proc_budget_error() {
@@ -39,8 +42,6 @@ fm_proc_budget_usage() {
   fm_proc_budget_error "usage: fm-proc-budget.sh [<extra>] -- <command...>"
 }
 
-# The kernel counts what RLIMIT_NPROC is compared with: processes on Darwin,
-# tasks (threads included) on Linux.
 fm_proc_budget_count() {
   local uid count
   uid=$(id -u) || return 1
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index ad77d88e1bc..6c1f9b28e44 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -135,12 +135,11 @@
 # 0 denotes degraded work and imposes no budget.
 # Without python3 or the pool tool beside it, scripts run directly.
 #
-# Every executed script also runs under a per-tree process budget
-# (bin/fm-proc-budget.sh owns it): a script that forks without bound stops at its
-# own limit instead of filling the user's process table for every other lane.
+# When the sibling bin/fm-proc-budget.sh is present and executable, every
+# executed script runs through it; its header owns the process-budget contract.
 # The budget is taken when the script starts, after any pass wait. If the budget
 # cannot be set, that script fails with wrapper exit 125 rather than running
-# unbudgeted.
+# unbudgeted. Without the executable wrapper, scripts run without this budget.
 # With a usable pool, --jobs above its size still starts that many workers,
 # but only pool-size scripts run at once.
 #
diff --git a/docs/scripts.md b/docs/scripts.md
index 4195023367f..e9025dd5579 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -55,7 +55,7 @@ The shared no-mistakes gate lifecycle boundary is summarized in [architecture.md
 | `fm-test-isolation-proof.sh` | Concurrent isolation harness and portable candidate set owner |
 | `fm-cpu-pass.sh`         | Reserve an exact positive worker count, no larger than the host CPU count, while a CPU-heavy burst runs ([protocol](cpu-pass-pool.md)) |
 | `fm-cpu-pass.py`         | The engine behind `fm-cpu-pass.sh`                                                   |
-| `fm-proc-budget.sh`      | Run `[<extra>] -- <command...>` with sealed soft/hard process limits (current user count + extra, default 1500), retaining tighter inherited limits and refusing execution when protection cannot be set |
+| [`fm-proc-budget.sh`](../bin/fm-proc-budget.sh) | Bound a command tree's process growth; its header owns the budget contract |
 | `fm-load-report.sh`      | Record host load and judge it with pipeline agent durations ([recipe](cpu-pass-pool.md#judging-the-pool)) |
 | `fm-load-report.py`      | The engine behind `fm-load-report.sh`                                                |
 | `fm-ensure-agents-md.sh` | Manually initialize project agent-memory files (see the helper's header and help) |

From 473f9aaff082bc688e85debd16393f1e25daa683 Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Fri, 9 Oct 2026 06:57:03 -0500
Subject: [PATCH 4/6] no-mistakes(ci): Fixed the Stop-hook hang behind Behavior
 portable serial 7. Empty host output incorrectly triggered a crash retry
 before an explicit hand-back failure was classified, allowing the replacement
 host to park indefinitely. Removed that retry condition while preserving
 bounded retries for signal exits. Added behavioral coverage for
 empty/nonempty output with and without a live successor, and updated the
 supervision documentation. The regression failed before the fix. Afterward,
 both fm-claude-stop-autoarm and fm-supervision-host-hook suites passed
 through the budgeted runner with no skips. A targeted real-host smoke also
 confirmed notification without retry when readiness output was absent.
 ShellCheck with sourced dependencies and Bash syntax checks passed. Temporary
 fixtures were removed

---
 bin/fm-claude-stop-autoarm.sh        |  2 +-
 docs/supervision-host.md             |  2 ++
 tests/fm-claude-stop-autoarm.test.sh | 40 ++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/bin/fm-claude-stop-autoarm.sh b/bin/fm-claude-stop-autoarm.sh
index 8e3501fe2c9..0f89277238a 100755
--- a/bin/fm-claude-stop-autoarm.sh
+++ b/bin/fm-claude-stop-autoarm.sh
@@ -449,7 +449,7 @@ while [ "$attempt" -lt "$AUTOARM_ATTEMPTS" ]; do
     # A host that died without a close may have left its cycle running with
     # no owner to deliver the close; retrying lets the next host stop what it
     # left and own a fresh cycle, which the healthy-watcher predicate cannot.
-    if [ "$HOST_RC" -gt 128 ] || [ -z "$OUT" ] || [ ! -s "$OUT" ]; then
+    if [ "$HOST_RC" -gt 128 ]; then
       [ "$attempt" -lt "$AUTOARM_ATTEMPTS" ] || break
       [ -z "$OUT" ] || rm -f "$OUT" 2>/dev/null || true
       OUT=
diff --git a/docs/supervision-host.md b/docs/supervision-host.md
index 3d2425909ee..f2890c09f6a 100644
--- a/docs/supervision-host.md
+++ b/docs/supervision-host.md
@@ -270,6 +270,8 @@ So it never stops the owner's host or watcher or releases its leases.
 ### A host that dies without a close
 
 The host's owner retries it.
+Claude's Stop hook retries a non-actionable host close as a crash only when its exit status is above 128, not merely because its output is empty.
+An explicit failed hand-back instead reaches the failure-notification path immediately, even if no readiness line was printed or its successor watcher remains healthy.
 Grok's model and Codex's checkpoint see it as a failed cycle and start the next one.
 Before it arms, the next host does two things:
 
diff --git a/tests/fm-claude-stop-autoarm.test.sh b/tests/fm-claude-stop-autoarm.test.sh
index f34469fe299..6f4b285381a 100755
--- a/tests/fm-claude-stop-autoarm.test.sh
+++ b/tests/fm-claude-stop-autoarm.test.sh
@@ -1468,6 +1468,11 @@ printf 'supervision-host: the away session could not take this wake: fixture; re
 for i in 1 2 3 4 5 6 7 8 9 10; do printf 'supervision-host: outcome %s for demo [routine]: fixture %s\n' "$i" "$i"; done
 SH
         ;;
+      failed-handback|failed-handback-silent)
+        printf "printf 'pending:handling:fixture-generation\\n' > \"\$FM_HOME/state/.watcher-down\"\n"
+        [ "$kind" = failed-handback-silent ] || printf "printf 'watcher: started pid=123 (beacon fresh)\\n'\n"
+        printf 'exit 1\n'
+        ;;
       crash)
         printf 'kill -KILL "$$"\n'
         ;;
@@ -1668,6 +1673,40 @@ test_host_lost_announced_handback_notifies_once_per_episode() {
   pass "auto-arm: a lost host hand-back on an announced marker notifies once per failure episode"
 }
 
+# An explicit failed hand-back must notify, not park on another host, even if
+# the first arm closed before its readiness line was streamed to the owner.
+test_host_failed_handback_is_not_retried() {
+  local kind successor dir out status pid identity
+  for kind in failed-handback failed-handback-silent; do
+    for successor in absent live; do
+      dir=$(make_primary_dir "$TMP_ROOT/host-$kind-$successor")
+      rm -f "$dir/config/supervision-host-off"
+      : > "$dir/state/task.meta"
+      write_host_fixture "$dir" "$kind"
+      pid=
+      if [ "$successor" = live ]; then
+        sleep 60 &
+        pid=$!
+        identity=$(watcher_identity "$dir" "$pid") || fail "could not identify the successor watcher"
+        record_watcher_lock "$dir" "$pid" "$identity"
+        touch "$dir/state/.last-watcher-beat"
+      fi
+      out=$(run_autoarm "$dir" 2>/dev/null); status=$?
+      if [ -n "$pid" ]; then
+        kill "$pid" 2>/dev/null || true
+        wait "$pid" 2>/dev/null || true
+      fi
+      expect_code 2 "$status" "$kind/$successor: a failed hand-back must notify main"
+      assert_contains "$out" 'auto-arm FAILED' "$kind/$successor: the failure notice is missing"
+      assert_present "$dir/state/.claude-autoarm-failure-notified" "$kind/$successor: the failure episode was not recorded"
+      [ "$(epoch_outcome "$dir")" = failed ] || fail "$kind/$successor: the hook did not commit the failure"
+      [ "$(wc -l < "$dir/state/host-ran" | tr -d ' ')" -eq 1 ] \
+        || fail "$kind/$successor: the failed hand-back was retried"
+    done
+  done
+  pass "auto-arm: explicit failed hand-backs notify without retry, with or without output or a live successor"
+}
+
 test_host_crash_is_retried_then_reported() {
   local dir out status
   dir=$(make_primary_dir "$TMP_ROOT/host-crash")
@@ -1794,6 +1833,7 @@ test_host_stand_down_is_silent
 test_host_benign_rewake_refusal_opens_no_failure_episode
 test_host_lost_handback_notifies_once_per_episode
 test_host_lost_announced_handback_notifies_once_per_episode
+test_host_failed_handback_is_not_retried
 test_host_crash_is_retried_then_reported
 test_arguments_never_arm
 test_fm_lock_status_still_works_with_shared_lib

From 886fa337f902b28899ddbf64098a9ae1a7d129bb Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Fri, 9 Oct 2026 07:22:06 -0500
Subject: [PATCH 5/6] no-mistakes(document): Align process-budget and
 supervision failure documentation

---
 bin/fm-claude-stop-autoarm.sh | 21 ++++++++-------------
 bin/fm-proc-budget.sh         |  2 +-
 docs/architecture.md          |  2 +-
 docs/cpu-pass-pool.md         |  4 ++--
 docs/turnend-guard.md         |  6 +++---
 docs/watcher-continuity.md    |  4 ++--
 6 files changed, 17 insertions(+), 22 deletions(-)

diff --git a/bin/fm-claude-stop-autoarm.sh b/bin/fm-claude-stop-autoarm.sh
index 0f89277238a..530ad1977b0 100755
--- a/bin/fm-claude-stop-autoarm.sh
+++ b/bin/fm-claude-stop-autoarm.sh
@@ -72,10 +72,9 @@
 #     line, which is actionable here like a wake line; its rewake banner
 #     carries every "supervision-host:" line the host printed, in order, while
 #     its wake lines keep the arm's eight-line cap. A "supervision-host stood
-#     down:" close exits 0 silently, and a host that died without a close is
-#     retried instead of being judged by the healthy-watcher predicate
-#     (docs/supervision-host.md). On a home that opted out nothing below
-#     changes.
+#     down:" close exits 0 silently; docs/supervision-host.md owns host-close
+#     retry and failed-hand-back classification. On a home that opted out
+#     nothing below changes.
 #   - Translation: while supervision is still needed and AFK remains inactive,
 #     an actionable arm close (signal:/stale:/check:/heartbeat) prints one
 #     rewake banner to stderr and exits 2, which wakes Claude even while idle
@@ -83,15 +82,11 @@
 #     the harness delivers the collected stderr only on exit 2, so an owned
 #     terminal commit decides the exit. Markerless outcomes commit with the
 #     ledger write; the failure notice additionally requires its marker write.
-#     A refused generation exits 0 silently even after printing. A close that
-#     reports no actionable reason is benign when a live identity-matched
-#     watcher still has a fresh beacon.
-#   - Failure handling: a typed failure is rechecked against the same live,
-#     fresh watcher predicate and retried a bounded number of times in this
-#     hook. Only an exhausted failure with no verified watcher emits one
-#     last-resort notice per failure episode; later consecutive failures still
-#     exit 2 to guarantee the next Stop-owned retry without repeating notice,
-#     until the synchronous guard has consumed its attended fail-open.
+#     A refused generation exits 0 silently even after printing.
+#   - Failure handling: docs/watcher-continuity.md "Claude arm failures" owns
+#     direct-arm close classification and retries; docs/supervision-host.md owns
+#     host closes. docs/turnend-guard.md owns failure-episode notices and the
+#     attended fail-open boundary.
 #
 # The epoch ledger state/.claude-autoarm-epoch records the latest claim
 # generation and outcome, and binds rewake outcomes to the session-lock pid and
diff --git a/bin/fm-proc-budget.sh b/bin/fm-proc-budget.sh
index 6cf6d47100f..12b230cd05c 100755
--- a/bin/fm-proc-budget.sh
+++ b/bin/fm-proc-budget.sh
@@ -11,7 +11,7 @@
 # This wrapper reads the current count and sets the limit (soft and hard) to
 # count + <extra>, then execs the command, so only the tree below it carries the
 # lowered limit and the rest of the user keeps its headroom. <extra> is a
-# positive decimal integer; omit it for 1500.
+# positive decimal integer without leading zeros; omit it for 1500.
 #
 # The budget only tightens. A limit the command already inherits that is lower
 # than count + <extra> stays as it is, and the hard limit is lowered with the
diff --git a/docs/architecture.md b/docs/architecture.md
index 75e88fbd5c8..e185790d876 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -185,7 +185,7 @@ The arm layer records one bounded lifecycle row per observed cycle in `state/.wa
 Pi, omp, and OpenCode verify session-lock ownership and launch one singleton successor from their child-close handlers before delivering an actionable wake prompt, with bounded exponential retry for failed restoration.
 Pi additionally retains an established predecessor across ordinary same-process session shutdown until the replacement generation commits its tracked arm, and its active-versus-handoff generation marker prevents an absent replacement extension from satisfying the fresh-beacon handoff tolerance.
 Claude's `bin/fm-claude-stop-autoarm.sh` hook fires on every Stop and, when the home is eligible and still needs supervision, claims one home-scoped cycle, foregrounds the arm wrapper (or the [supervision host](supervision-host.md), which runs by default on Claude), and translates actionable closes into exit-2 rewakes.
-It suppresses failed-looking closes when the same identity-matched watcher is healthy, retries genuine failures within a bound, and coordinates exhausted failure episodes with the Claude turn-end guard as documented in [`turnend-guard.md`](turnend-guard.md).
+Close classification and retries are owned by [`watcher-continuity.md`](watcher-continuity.md#claude-arm-failures) for direct arms and [`supervision-host.md`](supervision-host.md#failure-direction) for hosts; [`turnend-guard.md`](turnend-guard.md#failure-progression-and-block-budget) owns failure-episode coordination.
 [`watcher-continuity.md`](watcher-continuity.md) owns Claude's residual active-turn coverage and watcher-status command-gating boundary.
 Cursor's `bin/fm-turnend-guard-cursor.sh` hook is the same between-turns shape in one synchronous step: it parks the awaited `stop` hook on the arm wrapper and translates an actionable close into one `followup_message`, with a generation baton that makes an older park still running after the next `stop` claim stand down instead of leaking a stale duplicate wake.
 The existing turn-end guard remains the final backstop for every harness-engine protocol, with pi-signed sharing Pi's protocol, omp's blocking `session_stop` hook compelling one continuation per turn, the `--claude` mode cooperating with the auto-arm claim, and Cursor's `--cursor` mode rendering a block as one bounded follow-up because its `stop` step cannot be blocked.
diff --git a/docs/cpu-pass-pool.md b/docs/cpu-pass-pool.md
index b224bebccd4..7c91338f52e 100644
--- a/docs/cpu-pass-pool.md
+++ b/docs/cpu-pass-pool.md
@@ -72,8 +72,8 @@ Phase 1 completes only when the Vernant participant lands as a separate Vernant-
 
 `bin/fm-load-report.sh` records host load and reads pipeline agent durations; its [engine header](../bin/fm-load-report.py) owns the sample format and command behavior, while this recipe owns the measurement window and acceptance criteria.
 
-1. Only once Phase 1 is complete, note the time with `date +%s` and start one recorder per host: `nohup bin/fm-load-report.sh watch --interval 60 >/dev/null 2>&1 &`.
-2. After 24 to 48 hours of normal fleet work, run `bin/fm-load-report.sh report --since <that epoch>`.
+1. Only once Phase 1 is complete, note the time with `date +%s` and start one recorder per host: `nohup bin/fm-proc-budget.sh -- bin/fm-load-report.sh watch --interval 60 >/dev/null 2>&1 &`.
+2. After 24 to 48 hours of normal fleet work, run `bin/fm-proc-budget.sh -- bin/fm-load-report.sh report --since <that epoch>`.
 3. Read its two verdicts: `load_within_2x_cpus` (1-minute load p95 at or under twice the CPU count) and `converged_within_2_fix_rounds` (the fixed first ten pipeline runs that reached review and were created after the recorded cutover epoch, ordered by creation time then run id, completed successfully with at most two review-fix rounds and none hit a timeout).
    Failed and cancelled cohort members count as not converged.
    The convergence verdict is pending (`null` in JSON, `pending` in text) until ten review-reaching runs exist and every pending or running run that sorts at or before the tenth member is terminal, including runs that have not reached review yet.
diff --git a/docs/turnend-guard.md b/docs/turnend-guard.md
index 542e0b16171..91a2de2137d 100644
--- a/docs/turnend-guard.md
+++ b/docs/turnend-guard.md
@@ -386,13 +386,13 @@ An upgrade mid-session can therefore neither double-arm nor deadlock, and a fail
 #### Failure progression and block budget
 
 Fresh `failed` and `failed-suppressed` outcomes enter or advance the failure progression instead of acting as unconditional recovery proof.
-The auto-arm itself rechecks the healthy watcher predicate and retries a bounded number of times before reporting a genuine failure.
+The auto-arm's close classification and retries are owned by [`watcher-continuity.md`](watcher-continuity.md#claude-arm-failures) for direct arms and [`supervision-host.md`](supervision-host.md#failure-direction) for host closes.
 
 The foreground arm legitimately follows a healthy watcher until its next wake.
 The hook therefore catches HUP, TERM, and INT from host timeout or teardown and commits the ordinary durable failed outcome and failure-notice marker before exiting 2 for a recovery turn.
 Claude drops that exit 2 when it terminated the hook at the configured timeout itself, so a park that outlives the timeout ends without a rewake (`bin/fm-claude-stop-autoarm.sh` header).
 
-The first fresh exhausted-failure epoch preserves its handoff without consuming a blocked-stop count.
+The first fresh failed epoch preserves its handoff without consuming a blocked-stop count.
 Later fresh failed epochs advance the same monotonic progression instead of resetting it.
 When none of those proofs appears, the guard re-blocks up to `FM_CLAUDE_TURNEND_BLOCK_BUDGET` times (default 3, below Claude's 8-block override).
 In Claude mode, positive watcher recovery clears the block budget, failure notice, and attended alarm together under the existing budget lock before either hook reports ordinary recovery.
@@ -412,7 +412,7 @@ Whenever both coordination locks are needed, positive auto-arm recovery and the
 
 The one loud attended fail-open is available only when all of these hold:
 
-- The auto-arm has recorded an exhausted failure.
+- The auto-arm has recorded a failure.
 - Its one notice is already consumed.
 - The block budget is exhausted.
 - A final check finds neither a healthy watcher nor an automatic continuation.
diff --git a/docs/watcher-continuity.md b/docs/watcher-continuity.md
index cc85d770da5..5c282709410 100644
--- a/docs/watcher-continuity.md
+++ b/docs/watcher-continuity.md
@@ -131,7 +131,7 @@ The stale-owner claim occurs only after the existing AFK and supervision-need ga
 
 ### Claude arm failures
 
-After each non-actionable arm close, the hook rechecks the identity-matched watcher lock and fresh beacon before retrying a bounded number of times.
+With the supervision host disabled, after each non-actionable arm close the hook rechecks the identity-matched watcher lock and fresh beacon before retrying a bounded number of times.
 The beacon is `state/.last-watcher-beat`, which only the watcher process touches.
 
 - A cycle-end failure is benign when that live-watcher predicate is true.
@@ -146,7 +146,7 @@ The Claude turn-end guard owns that notice commit contract, the monotonic failur
 
 On a non-Pi primary, a home that runs the supervision host runs `bin/fm-supervision-host.sh` in place of the arm its re-arm owner would start.
 The host owns successive watcher cycles through the same arm.
-[supervision-host.md](supervision-host.md#failure-direction) owns the hand-back's downtime restoration, including when the successor already exited; the arm's recovery and acknowledgement contracts below still apply.
+[supervision-host.md](supervision-host.md#failure-direction) owns host-close handling and hand-back downtime restoration; the arm's recovery and acknowledgement contracts below still apply.
 
 ## Actionable wake ordering
 

From dab28e7da6dd63a15dcd2a709e8b536df83c43e5 Mon Sep 17 00:00:00 2001
From: Charles Brooker <charles@greentreetherapeutics.com>
Date: Fri, 9 Oct 2026 09:09:26 -0500
Subject: [PATCH 6/6] no-mistakes(document): Distinguish CPU-pass exemptions
 from process budgets

---
 bin/fm-test-run.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 6c1f9b28e44..793f199cc61 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -129,11 +129,11 @@
 # An unnested runner takes one pass per executed script from the host-wide pool
 # (bin/fm-cpu-pass.sh; docs/cpu-pass-pool.md owns the protocol), outside its
 # per-script bound, so participating test bursts across worktrees take turns.
-# A runner already inside a pass (FM_CPU_PASS_HELD set) runs directly with at
-# most that many concurrent scripts, reporting a reduced --jobs on stderr.
+# A runner already inside a pass (FM_CPU_PASS_HELD set) takes no additional pass
+# and runs at most that many concurrent scripts, reporting a reduced --jobs on stderr.
 # The marker must be a nonnegative decimal integer or execution exits 125;
-# 0 denotes degraded work and imposes no budget.
-# Without python3 or the pool tool beside it, scripts run directly.
+# 0 denotes degraded work with no CPU-pass concurrency limit.
+# Without python3 or the pool tool beside it, scripts run without a CPU pass.
 #
 # When the sibling bin/fm-proc-budget.sh is present and executable, every
 # executed script runs through it; its header owns the process-budget contract.