From 5be8f087bd2196f8a2e71b6f0d6d1ca762b4615c Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 19:15:14 +0800
Subject: [PATCH 1/8] feat: add fseventsd footprint early warning

---
 bin/fm-telemetry.sh           | 218 ++++++++++++++++++++++++++++++++++
 bin/fm-watch.sh               |  11 ++
 tests/fm-telemetry.test.sh    | 125 +++++++++++++++++++
 tests/fm-watcher-lock.test.sh |  43 +++++++
 4 files changed, 397 insertions(+)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index 2628340f5e0..b6d1cdd5548 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -5,6 +5,7 @@
 #   fm-telemetry.sh arm
 #   fm-telemetry.sh disarm
 #   fm-telemetry.sh status
+#   fm-telemetry.sh fseventsd-check         internal fleet early-warning check
 #   fm-telemetry.sh record [owner-token]   internal detached recorder mode
 #   fm-telemetry.sh fsync <file>           internal durable-flush helper
 #
@@ -36,6 +37,14 @@
 # with its age; losing the start-up race is reported on stdout instead, so it
 # never lands in that stream.
 # Nothing auto-arms this tool and it never installs a launch agent.
+# The fleet watcher's existing slow-check path calls `fseventsd-check` at most
+# once every five minutes. On macOS it samples fseventsd with top, keeps a
+# bounded three-hour history under state/telemetry/, and emits only a newly
+# reached warning, action, or emergency level. The accepted thresholds are:
+# warning above 512 MiB twice or above 256 MiB/hour for two hours; action above
+# 2 GiB, a doubling within one hour, or a warning combined with warning-or-worse
+# memory pressure or more than 8 GiB swap; emergency for sustained growth from
+# the action range toward 4 GiB plus worsening memory pressure.
 #
 # FM_TELEMETRY_INTERVAL controls the cadence in whole seconds from 15 through
 # 30 (default 20).
@@ -64,6 +73,8 @@ TELEMETRY_DIR="$STATE/telemetry"
 LOCK_LINK="$TELEMETRY_DIR/.record.lock"
 GUARD_LINK="$TELEMETRY_DIR/.record.guard"
 DIAGNOSTICS_LOG="$TELEMETRY_DIR/recorder.err"
+FSEVENTSD_HISTORY="$TELEMETRY_DIR/fseventsd-samples"
+FSEVENTSD_ALERT="$TELEMETRY_DIR/fseventsd-alert"
 INTERVAL=${FM_TELEMETRY_INTERVAL:-20}
 MAX_BYTES=${FM_TELEMETRY_MAX_BYTES:-209715200}
 FSYNC_PYTHON="${FM_TELEMETRY_PYTHON:-/usr/bin/python3}"
@@ -82,6 +93,8 @@ Usage:
   fm-telemetry.sh arm       start one detached recorder for this FM_HOME
   fm-telemetry.sh disarm    stop this home's recorder cleanly
   fm-telemetry.sh status    report running state and newest snapshot age
+  fm-telemetry.sh fseventsd-check
+                           run the internal fleet early-warning check
 
 Configuration:
   FM_TELEMETRY_INTERVAL     seconds between snapshots (15..30, default 20)
@@ -314,6 +327,210 @@ capture_processes() {
   } >> "$SNAPSHOT_TMP"
 }
 
+size_to_bytes() {
+  local raw=${1:-} unit number multiplier
+  [ -n "$raw" ] || return 1
+  unit=${raw#"${raw%?}"}
+  case "$unit" in
+    K|k) number=${raw%?}; multiplier=1024 ;;
+    M|m) number=${raw%?}; multiplier=1048576 ;;
+    G|g) number=${raw%?}; multiplier=1073741824 ;;
+    T|t) number=${raw%?}; multiplier=1099511627776 ;;
+    [0-9]) number=$raw; multiplier=1 ;;
+    *) return 1 ;;
+  esac
+  awk -v value="$number" -v multiplier="$multiplier" 'BEGIN {
+    if (value !~ /^[0-9]+([.][0-9]+)?$/) exit 1
+    printf "%.0f\n", value * multiplier
+  }'
+}
+
+bytes_to_mib() {
+  awk -v bytes="$1" 'BEGIN { printf "%.2f", bytes / 1048576 }'
+}
+
+bytes_to_gib() {
+  awk -v bytes="$1" 'BEGIN { printf "%.2f", bytes / 1073741824 }'
+}
+
+fseventsd_sample() {
+  local pid top_output mem_raw swap_output swap_raw
+  FSEVENTSD_MEM_BYTES=
+  FSEVENTSD_PRESSURE_LEVEL=-1
+  FSEVENTSD_SWAP_BYTES=0
+  command -v pgrep >/dev/null 2>&1 || return 1
+  command -v top >/dev/null 2>&1 || return 1
+  pid=$(pgrep -x fseventsd 2>/dev/null | head -1)
+  case "$pid" in ''|*[!0-9]*) return 1 ;; esac
+  top_output=$(top -l 1 -pid "$pid" \
+    -stats pid,command,mem,rsize,compressed,cpu,time,threads 2>/dev/null) || return 1
+  mem_raw=$(printf '%s\n' "$top_output" |
+    awk -v pid="$pid" '$1 == pid && $2 == "fseventsd" { print $3; exit }')
+  FSEVENTSD_MEM_BYTES=$(size_to_bytes "$mem_raw") || return 1
+
+  if command -v sysctl >/dev/null 2>&1; then
+    FSEVENTSD_PRESSURE_LEVEL=$(sysctl -n kern.memorystatus_vm_pressure_level 2>/dev/null || printf '%s' -1)
+    case "$FSEVENTSD_PRESSURE_LEVEL" in ''|*[!0-9]*) FSEVENTSD_PRESSURE_LEVEL=-1 ;; esac
+    swap_output=$(sysctl -n vm.swapusage 2>/dev/null || true)
+    swap_raw=$(printf '%s\n' "$swap_output" |
+      awk '{ for (i = 1; i <= NF; i++) if ($i == "used" && $(i + 1) == "=") { print $(i + 2); exit } }')
+    if [ -n "$swap_raw" ]; then
+      FSEVENTSD_SWAP_BYTES=$(size_to_bytes "$swap_raw") || FSEVENTSD_SWAP_BYTES=0
+    fi
+  fi
+}
+
+fseventsd_alert_rank() {
+  case "$1" in
+    warning) printf '1\n' ;;
+    action) printf '2\n' ;;
+    emergency) printf '3\n' ;;
+    *) printf '0\n' ;;
+  esac
+}
+
+fseventsd_record_sample() {
+  local now=$1 mem=$2 pressure=$3 swap=$4 cutoff tmp
+  cutoff=$((now - 10800))
+  tmp=$(umask 077; mktemp "$TELEMETRY_DIR/.fseventsd-history.XXXXXX") || return 1
+  if [ -f "$FSEVENTSD_HISTORY" ]; then
+    awk -v cutoff="$cutoff" '$1 >= cutoff' "$FSEVENTSD_HISTORY" > "$tmp" || {
+      rm -f "$tmp"
+      return 1
+    }
+  fi
+  printf '%s %s %s %s\n' "$now" "$mem" "$pressure" "$swap" >> "$tmp" || {
+    rm -f "$tmp"
+    return 1
+  }
+  mv -f "$tmp" "$FSEVENTSD_HISTORY"
+}
+
+fseventsd_publish_alert() {
+  local severity=$1 message=$2 previous=none previous_rank current_rank tmp
+  [ ! -f "$FSEVENTSD_ALERT" ] || previous=$(sed -n '1p' "$FSEVENTSD_ALERT")
+  previous_rank=$(fseventsd_alert_rank "$previous")
+  current_rank=$(fseventsd_alert_rank "$severity")
+  [ "$current_rank" -gt "$previous_rank" ] || return 0
+  tmp=$(umask 077; mktemp "$TELEMETRY_DIR/.fseventsd-alert.XXXXXX") || return 1
+  printf '%s\n' "$severity" > "$tmp" || { rm -f "$tmp"; return 1; }
+  mv -f "$tmp" "$FSEVENTSD_ALERT" || { rm -f "$tmp"; return 1; }
+  printf '%s\n' "$message"
+}
+
+fseventsd_check() {
+  local now last last_epoch previous='' preprevious='' previous_count=0
+  local prev_epoch=0 prev_mem=0 prev_pressure=-1
+  local preprev_epoch=0 preprev_mem=0
+  local growth_rate_mib='' doubling=0 warning=0
+  local severity=none reasons='' message mem_mib swap_gib
+  local warning_bytes=536870912 action_bytes=2147483648 swap_action_bytes=8589934592
+
+  now=${FM_TELEMETRY_NOW:-$(date '+%s' 2>/dev/null || true)}
+  case "$now" in ''|*[!0-9]*) return 0 ;; esac
+  mkdir -p "$TELEMETRY_DIR" || return 0
+  if [ -s "$FSEVENTSD_HISTORY" ]; then
+    last=$(tail -n 1 "$FSEVENTSD_HISTORY" 2>/dev/null || true)
+    last_epoch=${last%% *}
+    case "$last_epoch" in
+      ''|*[!0-9]*) ;;
+      *)
+        if [ "$now" -ge "$last_epoch" ] && [ "$((now - last_epoch))" -lt 300 ]; then
+          return 0
+        fi
+        ;;
+    esac
+    previous=$last
+    previous_count=$(wc -l < "$FSEVENTSD_HISTORY" | tr -d '[:space:]')
+    if [ "$previous_count" -ge 2 ]; then
+      preprevious=$(tail -n 2 "$FSEVENTSD_HISTORY" | sed -n '1p')
+    fi
+  fi
+
+  fseventsd_sample || return 0
+  if [ -n "$previous" ]; then
+    read -r prev_epoch prev_mem prev_pressure _ <<EOF
+$previous
+EOF
+  fi
+  if [ -n "$preprevious" ]; then
+    read -r preprev_epoch preprev_mem _ <<EOF
+$preprevious
+EOF
+  fi
+
+  if [ "$prev_epoch" -le "$now" ] && [ "$((now - prev_epoch))" -le 600 ] \
+    && [ "$prev_mem" -gt "$warning_bytes" ] && [ "$FSEVENTSD_MEM_BYTES" -gt "$warning_bytes" ]; then
+    warning=1
+    reasons='two consecutive samples above 512 MiB'
+  fi
+  if [ -f "$FSEVENTSD_HISTORY" ]; then
+    growth_rate_mib=$(awk -v now="$now" -v mem="$FSEVENTSD_MEM_BYTES" '
+      $1 >= now - 7500 && $1 <= now - 7200 { epoch = $1; bytes = $2 }
+      END {
+        if (epoch > 0 && mem > bytes) {
+          rate = (mem - bytes) * 3600 / (now - epoch) / 1048576
+          if (rate > 256) printf "%.2f", rate
+        }
+      }' "$FSEVENTSD_HISTORY")
+    if [ -n "$growth_rate_mib" ]; then
+      warning=1
+      [ -z "$reasons" ] || reasons="$reasons; "
+      reasons="${reasons}growth ${growth_rate_mib} MiB/hour for 2h"
+    fi
+    if awk -v now="$now" -v mem="$FSEVENTSD_MEM_BYTES" '
+      $1 >= now - 3600 && $1 < now && $2 > 0 && mem >= 2 * $2 { found = 1 }
+      END { exit(found ? 0 : 1) }' "$FSEVENTSD_HISTORY"; then
+      doubling=1
+    fi
+  fi
+
+  if [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ]; then
+    severity=action
+    reasons='MEM above 2 GiB'
+  elif [ "$doubling" -eq 1 ]; then
+    severity=action
+    reasons='doubling within one hour'
+  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge 1 ]; then
+    severity=action
+    reasons="${reasons}; warning plus yellow memory pressure"
+  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_SWAP_BYTES" -gt "$swap_action_bytes" ]; then
+    severity=action
+    reasons="${reasons}; warning plus more than 8 GiB swap"
+  elif [ "$warning" -eq 1 ]; then
+    severity=warning
+  fi
+
+  if [ "$preprev_epoch" -gt 0 ] && [ "$prev_epoch" -gt "$preprev_epoch" ] \
+    && [ "$now" -gt "$prev_epoch" ] && [ "$((prev_epoch - preprev_epoch))" -le 600 ] \
+    && [ "$((now - prev_epoch))" -le 600 ] && [ "$preprev_mem" -lt "$prev_mem" ] \
+    && [ "$prev_mem" -lt "$FSEVENTSD_MEM_BYTES" ] \
+    && [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ] \
+    && [ "$FSEVENTSD_PRESSURE_LEVEL" -gt "$prev_pressure" ] \
+    && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge 1 ]; then
+    severity=emergency
+    reasons='sustained growth toward 4 GiB plus worsening memory pressure'
+  fi
+
+  fseventsd_record_sample "$now" "$FSEVENTSD_MEM_BYTES" \
+    "$FSEVENTSD_PRESSURE_LEVEL" "$FSEVENTSD_SWAP_BYTES" || return 0
+  if [ "$severity" = none ]; then
+    rm -f "$FSEVENTSD_ALERT"
+    return 0
+  fi
+
+  mem_mib=$(bytes_to_mib "$FSEVENTSD_MEM_BYTES")
+  swap_gib=$(bytes_to_gib "$FSEVENTSD_SWAP_BYTES")
+  case "$severity" in
+    warning) message="WARNING: fseventsd MEM=${mem_mib} MiB; $reasons" ;;
+    action) message="ACTION: fseventsd MEM=${mem_mib} MiB; $reasons; pressure_level=$FSEVENTSD_PRESSURE_LEVEL swap_used=${swap_gib} GiB" ;;
+    emergency)
+      message="EMERGENCY: fseventsd MEM=${mem_mib} MiB; $reasons; stop launching new work, save state, and reduce workload before the machine wedges"
+      ;;
+  esac
+  fseventsd_publish_alert "$severity" "$message"
+}
+
 fsync_file() {
   local target=${1:-}
   if [ -z "$target" ] || [ ! -f "$target" ]; then
@@ -672,6 +889,7 @@ case "${1:-}" in
   arm) arm ;;
   disarm) disarm ;;
   status) status ;;
+  fseventsd-check) fseventsd_check ;;
   record) shift; record "${1:-}" ;;
   fsync) shift; fsync_file "${1:-}" ;;
   -h|--help|help) usage ;;
diff --git a/bin/fm-watch.sh b/bin/fm-watch.sh
index a01af557e27..be78d4f15c0 100755
--- a/bin/fm-watch.sh
+++ b/bin/fm-watch.sh
@@ -53,6 +53,8 @@
 #                          only - never an automatic interrupt, signal, or restart
 #                          of the worker or its tool process.
 #   check: <script>: <out> authenticated check output, always actionable
+#   check: fseventsd: <out> built-in host-footprint early warning, sampled on
+#                          the same bounded slow-check cadence
 #   check: process-event result captured: <keys>
 #                          a durably captured process-to-event result is queued
 #                          and has not been surfaced yet; reported once per
@@ -1022,6 +1024,15 @@ while :; do
   # never run until the fleet went quiet. Checks are due only every
   # CHECK_INTERVAL, so most cycles skip this block and fall straight through.
   if [ "$(age_of "$STATE/.last-check")" -ge "$CHECK_INTERVAL" ]; then
+    FM_HOME="$FM_HOME" FM_STATE_OVERRIDE="$STATE" \
+      run_check_capture "$SCRIPT_DIR/fm-telemetry.sh" fseventsd-check || exit 1
+    out=$FM_CHECK_RESULT
+    if [ -n "$out" ]; then
+      reason="check: fseventsd: $out"
+      fm_wake_append check fseventsd "$reason" || exit 1
+      touch "$STATE/.last-check"
+      wake "$reason"
+    fi
     rejected_checks=
     for c in "$STATE"/*.check.sh; do
       [ -e "$c" ] || continue
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index cba5cad0c1d..be468fa94c3 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -59,6 +59,44 @@ SH
   chmod +x "$fakebin"/*
 }
 
+write_fake_fseventsd_samplers() {
+  local fakebin=$1
+  mkdir -p "$fakebin"
+  cat > "$fakebin/pgrep" <<'SH'
+#!/usr/bin/env bash
+[ "${1:-}" = -x ] && [ "${2:-}" = fseventsd ] || exit 1
+printf '342\n'
+SH
+  cat > "$fakebin/top" <<'SH'
+#!/usr/bin/env bash
+printf 'PID COMMAND MEM RPRVT CMPRS %%CPU TIME #TH\n'
+printf '342 fseventsd %s %s 2M 0.0 00:01.00 10\n' \
+  "${FM_FAKE_FSEVENTSD_MEM:-5M}" "${FM_FAKE_FSEVENTSD_MEM:-5M}"
+SH
+  cat > "$fakebin/sysctl" <<'SH'
+#!/usr/bin/env bash
+case "$*" in
+  '-n kern.memorystatus_vm_pressure_level')
+    printf '%s\n' "${FM_FAKE_PRESSURE_LEVEL:-0}"
+    ;;
+  '-n vm.swapusage')
+    printf 'total = 16384.00M  used = %s  free = 8192.00M  (encrypted)\n' \
+      "${FM_FAKE_SWAP_USED:-0.00M}"
+    ;;
+  *) exit 1 ;;
+esac
+SH
+  chmod +x "$fakebin"/*
+}
+
+fseventsd_check() {
+  local home=$1 fakebin=$2 now=$3 mem=$4 pressure=$5 swap=$6
+  FM_HOME="$home" FM_TELEMETRY_NOW="$now" \
+    FM_FAKE_FSEVENTSD_MEM="$mem" FM_FAKE_PRESSURE_LEVEL="$pressure" \
+    FM_FAKE_SWAP_USED="$swap" PATH="$fakebin:/usr/bin:/bin" \
+    "$TELEMETRY" fseventsd-check
+}
+
 record_once() {
   local home=$1 fakebin=$2
   FM_HOME="$home" FM_TELEMETRY_RECORD_ONCE=1 \
@@ -139,6 +177,89 @@ test_record_writes_parseable_durable_snapshot() {
   pass "record writes one bounded, parseable snapshot dated in UTC and releases its lock"
 }
 
+test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-cadence-home"
+  fakebin="$TMP_ROOT/fseventsd-cadence-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  out=$(fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M)
+  [ -z "$out" ] || fail "the first high fseventsd sample warned without a consecutive sample: $out"
+  out=$(fseventsd_check "$home" "$fakebin" 1100 5M 0 0.00M)
+  [ -z "$out" ] || fail "a fseventsd sample inside five minutes produced output: $out"
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 0 0.00M)
+  assert_contains "$out" 'WARNING: fseventsd' "two consecutive samples above 512 MiB did not warn"
+  assert_contains "$out" 'two consecutive samples above 512 MiB' "the warning did not identify its threshold"
+  out=$(fseventsd_check "$home" "$fakebin" 1600 600M 0 0.00M)
+  [ -z "$out" ] || fail "an unchanged warning episode re-alerted: $out"
+  pass "fseventsd warning samples at most every five minutes, requires two high samples, and dedupes the episode"
+}
+
+test_fseventsd_check_warns_after_two_hours_of_fast_growth() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-growth-home"
+  fakebin="$TMP_ROOT/fseventsd-growth-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  out=$(fseventsd_check "$home" "$fakebin" 1000 100M 0 0.00M)
+  [ -z "$out" ] || fail "the growth baseline produced an alert: $out"
+  out=$(fseventsd_check "$home" "$fakebin" 8200 700M 0 0.00M)
+  assert_contains "$out" 'WARNING: fseventsd' "growth above 256 MiB/hour for two hours did not warn"
+  assert_contains "$out" '300.00 MiB/hour for 2h' "the growth warning did not report its measured rate"
+  pass "fseventsd warns when two-hour growth exceeds 256 MiB per hour"
+}
+
+test_fseventsd_check_surfaces_action_thresholds() {
+  local fakebin out home
+  fakebin="$TMP_ROOT/fseventsd-action-fakebin"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  home="$TMP_ROOT/fseventsd-action-size-home"
+  mkdir -p "$home/state"
+  out=$(fseventsd_check "$home" "$fakebin" 1000 2049M 0 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "MEM above 2 GiB did not surface action"
+  assert_contains "$out" 'MEM above 2 GiB' "the action did not identify the 2 GiB boundary"
+
+  home="$TMP_ROOT/fseventsd-action-double-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 100M 0 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 201M 0 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "doubling within one hour did not surface action"
+  assert_contains "$out" 'doubling within one hour' "the doubling action did not identify its threshold"
+
+  home="$TMP_ROOT/fseventsd-action-pressure-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 1 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "warning plus yellow memory pressure did not surface action"
+  assert_contains "$out" 'warning plus yellow memory pressure' "the pressure action did not identify its threshold"
+
+  home="$TMP_ROOT/fseventsd-action-swap-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 0 8193M)
+  assert_contains "$out" 'ACTION: fseventsd' "warning plus more than 8 GiB swap did not surface action"
+  assert_contains "$out" 'warning plus more than 8 GiB swap' "the swap action did not identify its threshold"
+  pass "fseventsd action surfaces size, doubling, and warning-plus-pressure thresholds"
+}
+
+test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-emergency-home"
+  fakebin="$TMP_ROOT/fseventsd-emergency-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  fseventsd_check "$home" "$fakebin" 1000 2500M 0 0.00M >/dev/null
+  fseventsd_check "$home" "$fakebin" 1300 3000M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1600 3500M 3 0.00M)
+  assert_contains "$out" 'EMERGENCY: fseventsd' "sustained growth toward 4 GiB with worsening pressure did not surface emergency"
+  assert_contains "$out" 'stop launching new work, save state, and reduce workload' "the emergency omitted the accepted operational response"
+  pass "fseventsd emergency requires sustained growth toward 4 GiB plus worsening pressure"
+}
+
 test_fsync_helper_flushes_the_named_file() {
   local home out rc
   home="$TMP_ROOT/fsync-home"
@@ -595,6 +716,10 @@ test_concurrent_arms_over_a_stale_lock_keep_one_recorder() {
 }
 
 test_record_writes_parseable_durable_snapshot
+test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning
+test_fseventsd_check_warns_after_two_hours_of_fast_growth
+test_fseventsd_check_surfaces_action_thresholds
+test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
 test_fsync_helper_flushes_the_named_file
 test_fsync_helper_commits_the_containing_directory
 test_record_surfaces_durability_failure
diff --git a/tests/fm-watcher-lock.test.sh b/tests/fm-watcher-lock.test.sh
index a3628b1694f..5d8f4213f46 100755
--- a/tests/fm-watcher-lock.test.sh
+++ b/tests/fm-watcher-lock.test.sh
@@ -751,6 +751,48 @@ SH
   pass "arm propagates an immediate watcher wake before confirmation"
 }
 
+test_watcher_surfaces_fseventsd_warning_on_slow_check_path() {
+  local dir state fakebin out drain_out
+  dir=$(make_case fseventsd-warning-wake)
+  state="$dir/state"
+  fakebin="$dir/fakebin"
+  out="$dir/watch.out"
+  drain_out="$dir/drain.out"
+  mark_pr_check_migration_complete "$state"
+  cat > "$fakebin/pgrep" <<'SH'
+#!/usr/bin/env bash
+[ "${1:-}" = -x ] && [ "${2:-}" = fseventsd ] || exit 1
+printf '342\n'
+SH
+  cat > "$fakebin/top" <<'SH'
+#!/usr/bin/env bash
+printf 'PID COMMAND MEM RPRVT CMPRS %%CPU TIME #TH\n'
+printf '342 fseventsd 600M 600M 2M 0.0 00:01.00 10\n'
+SH
+  cat > "$fakebin/sysctl" <<'SH'
+#!/usr/bin/env bash
+case "$*" in
+  '-n kern.memorystatus_vm_pressure_level') printf '0\n' ;;
+  '-n vm.swapusage') printf 'total = 16384.00M  used = 0.00M  free = 16384.00M\n' ;;
+  *) exit 1 ;;
+esac
+SH
+  chmod +x "$fakebin/pgrep" "$fakebin/top" "$fakebin/sysctl"
+
+  FM_HOME="$dir" FM_STATE_OVERRIDE="$state" FM_TELEMETRY_NOW=1000 \
+    PATH="$fakebin:$PATH" "$ROOT/bin/fm-telemetry.sh" fseventsd-check >/dev/null \
+    || fail "could not establish the fseventsd warning baseline"
+  FM_HOME="$dir" FM_STATE_OVERRIDE="$state" FM_TELEMETRY_NOW=1300 \
+    PATH="$fakebin:$PATH" FM_POLL=5 FM_SIGNAL_GRACE=1 FM_CHECK_INTERVAL=0 \
+    FM_HEARTBEAT=999999 "$WATCH" > "$out" || fail "watcher did not surface the fseventsd warning"
+  grep -F 'check: fseventsd: WARNING: fseventsd' "$out" >/dev/null \
+    || fail "watcher omitted the fseventsd warning reason: $(cat "$out")"
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$drain_out" || fail "drain after fseventsd warning failed"
+  grep "$(printf '\tcheck\t')" "$drain_out" | grep -F 'fseventsd' | grep -F 'WARNING' >/dev/null \
+    || fail "fseventsd warning was not queued through the durable wake path"
+  pass "watcher surfaces fseventsd warnings through its existing slow-check wake path"
+}
+
 test_arm_waits_for_peer_beacon_after_child_stands_down() {
   local dir state fakebin armout peer identity armpid status i
   dir=$(make_case arm-peer-startup-race)
@@ -1123,6 +1165,7 @@ test_attached_arm_signal_is_recorded_in_cycle_ledger
 test_arm_starts_and_self_heals
 test_arm_hup_cleans_child_and_temp_output
 test_arm_propagates_immediate_wake_before_confirmation
+test_watcher_surfaces_fseventsd_warning_on_slow_check_path
 test_arm_waits_for_peer_beacon_after_child_stands_down
 test_arm_fails_loud_when_no_fresh_watcher_confirmable
 test_cycle_exit_ledger_links_successor_and_stays_bounded

From a3d9303989e7496f7aa88ed8914dc9cb9de0287b Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 19:33:08 +0800
Subject: [PATCH 2/8] no-mistakes(review): fix fseventsd pressure encoding,
 doubling floor, growth window

---
 bin/fm-telemetry.sh        |  23 ++++++---
 tests/fm-telemetry.test.sh | 103 +++++++++++++++++++++++++++++++------
 2 files changed, 101 insertions(+), 25 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index b6d1cdd5548..b0856c31339 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -42,9 +42,12 @@
 # bounded three-hour history under state/telemetry/, and emits only a newly
 # reached warning, action, or emergency level. The accepted thresholds are:
 # warning above 512 MiB twice or above 256 MiB/hour for two hours; action above
-# 2 GiB, a doubling within one hour, or a warning combined with warning-or-worse
-# memory pressure or more than 8 GiB swap; emergency for sustained growth from
-# the action range toward 4 GiB plus worsening memory pressure.
+# 2 GiB, a doubling within one hour once already above 512 MiB, or a warning
+# combined with warning-or-worse memory pressure or more than 8 GiB swap;
+# emergency for sustained growth from the action range toward 4 GiB while memory
+# pressure is sustained at warning-or-worse or is still rising.
+# Memory-pressure levels use the kernel's dispatch encoding, where 1 is normal,
+# 2 is warning and 4 is critical, so only 2 or above counts as pressure here.
 #
 # FM_TELEMETRY_INTERVAL controls the cadence in whole seconds from 15 through
 # 30 (default 20).
@@ -54,6 +57,8 @@
 # (default /usr/bin/python3).
 # FM_TELEMETRY_RECORD_ONCE=1 is a test seam that makes internal record mode take
 # one snapshot and exit.
+# FM_TELEMETRY_NOW is a test seam that overrides the whole-second clock used by
+# `fseventsd-check` for its cadence, history and growth windows.
 # Internal record mode without an owner token re-execs itself with a synthesized
 # one, so every recorder carries its token in argv and status and disarm have a
 # single liveness rule.
@@ -425,6 +430,7 @@ fseventsd_check() {
   local growth_rate_mib='' doubling=0 warning=0
   local severity=none reasons='' message mem_mib swap_gib
   local warning_bytes=536870912 action_bytes=2147483648 swap_action_bytes=8589934592
+  local pressure_warn_level=2
 
   now=${FM_TELEMETRY_NOW:-$(date '+%s' 2>/dev/null || true)}
   case "$now" in ''|*[!0-9]*) return 0 ;; esac
@@ -466,7 +472,7 @@ EOF
   fi
   if [ -f "$FSEVENTSD_HISTORY" ]; then
     growth_rate_mib=$(awk -v now="$now" -v mem="$FSEVENTSD_MEM_BYTES" '
-      $1 >= now - 7500 && $1 <= now - 7200 { epoch = $1; bytes = $2 }
+      $1 >= now - 10800 && $1 <= now - 7200 { epoch = $1; bytes = $2 }
       END {
         if (epoch > 0 && mem > bytes) {
           rate = (mem - bytes) * 3600 / (now - epoch) / 1048576
@@ -478,7 +484,7 @@ EOF
       [ -z "$reasons" ] || reasons="$reasons; "
       reasons="${reasons}growth ${growth_rate_mib} MiB/hour for 2h"
     fi
-    if awk -v now="$now" -v mem="$FSEVENTSD_MEM_BYTES" '
+    if [ "$FSEVENTSD_MEM_BYTES" -gt "$warning_bytes" ] && awk -v now="$now" -v mem="$FSEVENTSD_MEM_BYTES" '
       $1 >= now - 3600 && $1 < now && $2 > 0 && mem >= 2 * $2 { found = 1 }
       END { exit(found ? 0 : 1) }' "$FSEVENTSD_HISTORY"; then
       doubling=1
@@ -491,7 +497,7 @@ EOF
   elif [ "$doubling" -eq 1 ]; then
     severity=action
     reasons='doubling within one hour'
-  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge 1 ]; then
+  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=action
     reasons="${reasons}; warning plus yellow memory pressure"
   elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_SWAP_BYTES" -gt "$swap_action_bytes" ]; then
@@ -506,8 +512,9 @@ EOF
     && [ "$((now - prev_epoch))" -le 600 ] && [ "$preprev_mem" -lt "$prev_mem" ] \
     && [ "$prev_mem" -lt "$FSEVENTSD_MEM_BYTES" ] \
     && [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ] \
-    && [ "$FSEVENTSD_PRESSURE_LEVEL" -gt "$prev_pressure" ] \
-    && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge 1 ]; then
+    && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ] \
+    && { [ "$prev_pressure" -ge "$pressure_warn_level" ] \
+      || [ "$FSEVENTSD_PRESSURE_LEVEL" -gt "$prev_pressure" ]; }; then
     severity=emergency
     reasons='sustained growth toward 4 GiB plus worsening memory pressure'
   fi
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index be468fa94c3..2a9d5b28b93 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -77,7 +77,7 @@ SH
 #!/usr/bin/env bash
 case "$*" in
   '-n kern.memorystatus_vm_pressure_level')
-    printf '%s\n' "${FM_FAKE_PRESSURE_LEVEL:-0}"
+    printf '%s\n' "${FM_FAKE_PRESSURE_LEVEL:-1}"
     ;;
   '-n vm.swapusage')
     printf 'total = 16384.00M  used = %s  free = 8192.00M  (encrypted)\n' \
@@ -184,14 +184,14 @@ test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning() {
   mkdir -p "$home/state"
   write_fake_fseventsd_samplers "$fakebin"
 
-  out=$(fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M)
   [ -z "$out" ] || fail "the first high fseventsd sample warned without a consecutive sample: $out"
-  out=$(fseventsd_check "$home" "$fakebin" 1100 5M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1100 5M 1 0.00M)
   [ -z "$out" ] || fail "a fseventsd sample inside five minutes produced output: $out"
-  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 1 0.00M)
   assert_contains "$out" 'WARNING: fseventsd' "two consecutive samples above 512 MiB did not warn"
   assert_contains "$out" 'two consecutive samples above 512 MiB' "the warning did not identify its threshold"
-  out=$(fseventsd_check "$home" "$fakebin" 1600 600M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1600 600M 1 0.00M)
   [ -z "$out" ] || fail "an unchanged warning episode re-alerted: $out"
   pass "fseventsd warning samples at most every five minutes, requires two high samples, and dedupes the episode"
 }
@@ -203,9 +203,9 @@ test_fseventsd_check_warns_after_two_hours_of_fast_growth() {
   mkdir -p "$home/state"
   write_fake_fseventsd_samplers "$fakebin"
 
-  out=$(fseventsd_check "$home" "$fakebin" 1000 100M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1000 100M 1 0.00M)
   [ -z "$out" ] || fail "the growth baseline produced an alert: $out"
-  out=$(fseventsd_check "$home" "$fakebin" 8200 700M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 8200 700M 1 0.00M)
   assert_contains "$out" 'WARNING: fseventsd' "growth above 256 MiB/hour for two hours did not warn"
   assert_contains "$out" '300.00 MiB/hour for 2h' "the growth warning did not report its measured rate"
   pass "fseventsd warns when two-hour growth exceeds 256 MiB per hour"
@@ -218,28 +218,28 @@ test_fseventsd_check_surfaces_action_thresholds() {
 
   home="$TMP_ROOT/fseventsd-action-size-home"
   mkdir -p "$home/state"
-  out=$(fseventsd_check "$home" "$fakebin" 1000 2049M 0 0.00M)
+  out=$(fseventsd_check "$home" "$fakebin" 1000 2049M 1 0.00M)
   assert_contains "$out" 'ACTION: fseventsd' "MEM above 2 GiB did not surface action"
   assert_contains "$out" 'MEM above 2 GiB' "the action did not identify the 2 GiB boundary"
 
   home="$TMP_ROOT/fseventsd-action-double-home"
   mkdir -p "$home/state"
-  fseventsd_check "$home" "$fakebin" 1000 100M 0 0.00M >/dev/null
-  out=$(fseventsd_check "$home" "$fakebin" 1300 201M 0 0.00M)
+  fseventsd_check "$home" "$fakebin" 1000 300M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 601M 1 0.00M)
   assert_contains "$out" 'ACTION: fseventsd' "doubling within one hour did not surface action"
   assert_contains "$out" 'doubling within one hour' "the doubling action did not identify its threshold"
 
   home="$TMP_ROOT/fseventsd-action-pressure-home"
   mkdir -p "$home/state"
-  fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M >/dev/null
-  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 1 0.00M)
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 2 0.00M)
   assert_contains "$out" 'ACTION: fseventsd' "warning plus yellow memory pressure did not surface action"
   assert_contains "$out" 'warning plus yellow memory pressure' "the pressure action did not identify its threshold"
 
   home="$TMP_ROOT/fseventsd-action-swap-home"
   mkdir -p "$home/state"
-  fseventsd_check "$home" "$fakebin" 1000 600M 0 0.00M >/dev/null
-  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 0 8193M)
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 1 8193M)
   assert_contains "$out" 'ACTION: fseventsd' "warning plus more than 8 GiB swap did not surface action"
   assert_contains "$out" 'warning plus more than 8 GiB swap' "the swap action did not identify its threshold"
   pass "fseventsd action surfaces size, doubling, and warning-plus-pressure thresholds"
@@ -252,14 +252,79 @@ test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure(
   mkdir -p "$home/state"
   write_fake_fseventsd_samplers "$fakebin"
 
-  fseventsd_check "$home" "$fakebin" 1000 2500M 0 0.00M >/dev/null
-  fseventsd_check "$home" "$fakebin" 1300 3000M 1 0.00M >/dev/null
-  out=$(fseventsd_check "$home" "$fakebin" 1600 3500M 3 0.00M)
+  fseventsd_check "$home" "$fakebin" 1000 2500M 1 0.00M >/dev/null
+  fseventsd_check "$home" "$fakebin" 1300 3000M 2 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1600 3500M 4 0.00M)
   assert_contains "$out" 'EMERGENCY: fseventsd' "sustained growth toward 4 GiB with worsening pressure did not surface emergency"
   assert_contains "$out" 'stop launching new work, save state, and reduce workload' "the emergency omitted the accepted operational response"
   pass "fseventsd emergency requires sustained growth toward 4 GiB plus worsening pressure"
 }
 
+test_fseventsd_check_reads_the_kernel_memory_pressure_encoding() {
+  local home fakebin out
+  fakebin="$TMP_ROOT/fseventsd-encoding-fakebin"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  home="$TMP_ROOT/fseventsd-encoding-normal-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 1 0.00M)
+  assert_contains "$out" 'WARNING: fseventsd' "steady-state normal pressure did not stay at the warning tier"
+  case "$out" in
+    *ACTION*) fail "normal pressure level 1 was treated as yellow memory pressure: $out" ;;
+  esac
+
+  home="$TMP_ROOT/fseventsd-encoding-critical-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 4 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "critical pressure level 4 did not escalate the warning"
+  pass "fseventsd pressure escalation follows the kernel normal/warn/critical encoding"
+}
+
+test_fseventsd_check_ignores_doubling_below_the_warning_floor() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-doubling-floor-home"
+  fakebin="$TMP_ROOT/fseventsd-doubling-floor-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  out=$(fseventsd_check "$home" "$fakebin" 1000 2M 1 0.00M)
+  [ -z "$out" ] || fail "a healthy post-boot baseline alerted: $out"
+  out=$(fseventsd_check "$home" "$fakebin" 1300 5M 1 0.00M)
+  [ -z "$out" ] || fail "a healthy daemon settling from 2 MiB to 5 MiB alerted: $out"
+  pass "fseventsd doubling only counts once the footprint is above 512 MiB"
+}
+
+test_fseventsd_check_emergency_accepts_sustained_pressure_without_a_rise() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-emergency-sustained-home"
+  fakebin="$TMP_ROOT/fseventsd-emergency-sustained-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  fseventsd_check "$home" "$fakebin" 1000 2600M 2 0.00M >/dev/null
+  fseventsd_check "$home" "$fakebin" 1300 3000M 2 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1600 3500M 2 0.00M)
+  assert_contains "$out" 'EMERGENCY: fseventsd' "sustained warn-or-worse pressure did not surface emergency"
+  pass "fseventsd emergency treats sustained warn-or-worse pressure as worsening"
+}
+
+test_fseventsd_check_measures_two_hour_growth_across_irregular_spacing() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-growth-spacing-home"
+  fakebin="$TMP_ROOT/fseventsd-growth-spacing-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  fseventsd_check "$home" "$fakebin" 1100 100M 1 0.00M >/dev/null
+  fseventsd_check "$home" "$fakebin" 1600 150M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 8700 800M 1 0.00M)
+  assert_contains "$out" 'WARNING: fseventsd' "growth was missed when no sample landed in a narrow two-hour window"
+  assert_contains "$out" 'MiB/hour for 2h' "the growth warning did not report its measured rate"
+  pass "fseventsd two-hour growth uses the newest sample at least two hours old"
+}
+
 test_fsync_helper_flushes_the_named_file() {
   local home out rc
   home="$TMP_ROOT/fsync-home"
@@ -720,6 +785,10 @@ test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning
 test_fseventsd_check_warns_after_two_hours_of_fast_growth
 test_fseventsd_check_surfaces_action_thresholds
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
+test_fseventsd_check_reads_the_kernel_memory_pressure_encoding
+test_fseventsd_check_ignores_doubling_below_the_warning_floor
+test_fseventsd_check_emergency_accepts_sustained_pressure_without_a_rise
+test_fseventsd_check_measures_two_hour_growth_across_irregular_spacing
 test_fsync_helper_flushes_the_named_file
 test_fsync_helper_commits_the_containing_directory
 test_record_surfaces_durability_failure

From ea43c84a505e6213134c6c5658940999feaaf36c Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 19:46:05 +0800
Subject: [PATCH 3/8] no-mistakes(review): retain fseventsd action evidence,
 drop dead pressure clause

---
 bin/fm-telemetry.sh           | 16 ++++++++--------
 tests/fm-telemetry.test.sh    | 24 ++++++++++++++++++++++++
 tests/fm-watcher-lock.test.sh |  2 +-
 3 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index b0856c31339..d672883c852 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -45,7 +45,7 @@
 # 2 GiB, a doubling within one hour once already above 512 MiB, or a warning
 # combined with warning-or-worse memory pressure or more than 8 GiB swap;
 # emergency for sustained growth from the action range toward 4 GiB while memory
-# pressure is sustained at warning-or-worse or is still rising.
+# pressure is at warning-or-worse.
 # Memory-pressure levels use the kernel's dispatch encoding, where 1 is normal,
 # 2 is warning and 4 is critical, so only 2 or above counts as pressure here.
 #
@@ -425,7 +425,7 @@ fseventsd_publish_alert() {
 
 fseventsd_check() {
   local now last last_epoch previous='' preprevious='' previous_count=0
-  local prev_epoch=0 prev_mem=0 prev_pressure=-1
+  local prev_epoch=0 prev_mem=0
   local preprev_epoch=0 preprev_mem=0
   local growth_rate_mib='' doubling=0 warning=0
   local severity=none reasons='' message mem_mib swap_gib
@@ -455,7 +455,7 @@ fseventsd_check() {
 
   fseventsd_sample || return 0
   if [ -n "$previous" ]; then
-    read -r prev_epoch prev_mem prev_pressure _ <<EOF
+    read -r prev_epoch prev_mem _ <<EOF
 $previous
 EOF
   fi
@@ -493,10 +493,12 @@ EOF
 
   if [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ]; then
     severity=action
-    reasons='MEM above 2 GiB'
+    [ -z "$reasons" ] || reasons="$reasons; "
+    reasons="${reasons}MEM above 2 GiB"
   elif [ "$doubling" -eq 1 ]; then
     severity=action
-    reasons='doubling within one hour'
+    [ -z "$reasons" ] || reasons="$reasons; "
+    reasons="${reasons}doubling within one hour"
   elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=action
     reasons="${reasons}; warning plus yellow memory pressure"
@@ -512,9 +514,7 @@ EOF
     && [ "$((now - prev_epoch))" -le 600 ] && [ "$preprev_mem" -lt "$prev_mem" ] \
     && [ "$prev_mem" -lt "$FSEVENTSD_MEM_BYTES" ] \
     && [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ] \
-    && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ] \
-    && { [ "$prev_pressure" -ge "$pressure_warn_level" ] \
-      || [ "$FSEVENTSD_PRESSURE_LEVEL" -gt "$prev_pressure" ]; }; then
+    && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=emergency
     reasons='sustained growth toward 4 GiB plus worsening memory pressure'
   fi
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index 2a9d5b28b93..924c7dab57f 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -245,6 +245,29 @@ test_fseventsd_check_surfaces_action_thresholds() {
   pass "fseventsd action surfaces size, doubling, and warning-plus-pressure thresholds"
 }
 
+test_fseventsd_action_retains_the_warning_evidence_it_measured() {
+  local home fakebin out
+  fakebin="$TMP_ROOT/fseventsd-action-evidence-fakebin"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  home="$TMP_ROOT/fseventsd-action-evidence-doubling-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 1300M 1 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "a doubling above the warning floor did not surface action"
+  assert_contains "$out" 'two consecutive samples above 512 MiB' "the doubling action dropped the sustained 512 MiB breach it measured"
+  assert_contains "$out" 'doubling within one hour' "the doubling action did not identify its own threshold"
+
+  home="$TMP_ROOT/fseventsd-action-evidence-size-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 2500M 1 0.00M)
+  assert_contains "$out" 'ACTION: fseventsd' "MEM above 2 GiB did not surface action"
+  assert_contains "$out" 'two consecutive samples above 512 MiB' "the 2 GiB action dropped the sustained 512 MiB breach it measured"
+  assert_contains "$out" 'MEM above 2 GiB' "the 2 GiB action did not identify its own threshold"
+  pass "fseventsd action alerts keep every warning reason measured in the same sample"
+}
+
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure() {
   local home fakebin out
   home="$TMP_ROOT/fseventsd-emergency-home"
@@ -784,6 +807,7 @@ test_record_writes_parseable_durable_snapshot
 test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning
 test_fseventsd_check_warns_after_two_hours_of_fast_growth
 test_fseventsd_check_surfaces_action_thresholds
+test_fseventsd_action_retains_the_warning_evidence_it_measured
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
 test_fseventsd_check_reads_the_kernel_memory_pressure_encoding
 test_fseventsd_check_ignores_doubling_below_the_warning_floor
diff --git a/tests/fm-watcher-lock.test.sh b/tests/fm-watcher-lock.test.sh
index 5d8f4213f46..ce0efd3f7ef 100755
--- a/tests/fm-watcher-lock.test.sh
+++ b/tests/fm-watcher-lock.test.sh
@@ -772,7 +772,7 @@ SH
   cat > "$fakebin/sysctl" <<'SH'
 #!/usr/bin/env bash
 case "$*" in
-  '-n kern.memorystatus_vm_pressure_level') printf '0\n' ;;
+  '-n kern.memorystatus_vm_pressure_level') printf '1\n' ;;
   '-n vm.swapusage') printf 'total = 16384.00M  used = 0.00M  free = 16384.00M\n' ;;
   *) exit 1 ;;
 esac

From 39acdce694bf4641b24c7cd5d090801477967674 Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 19:54:19 +0800
Subject: [PATCH 4/8] no-mistakes(review): retain fseventsd emergency evidence,
 update scripts index

---
 bin/fm-telemetry.sh        |  5 +++--
 docs/scripts.md            |  2 +-
 tests/fm-telemetry.test.sh | 20 ++++++++++++++++++++
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index d672883c852..0fb4b5353f6 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -516,7 +516,8 @@ EOF
     && [ "$FSEVENTSD_MEM_BYTES" -gt "$action_bytes" ] \
     && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=emergency
-    reasons='sustained growth toward 4 GiB plus worsening memory pressure'
+    [ -z "$reasons" ] || reasons="$reasons; "
+    reasons="${reasons}sustained growth toward 4 GiB plus worsening memory pressure"
   fi
 
   fseventsd_record_sample "$now" "$FSEVENTSD_MEM_BYTES" \
@@ -532,7 +533,7 @@ EOF
     warning) message="WARNING: fseventsd MEM=${mem_mib} MiB; $reasons" ;;
     action) message="ACTION: fseventsd MEM=${mem_mib} MiB; $reasons; pressure_level=$FSEVENTSD_PRESSURE_LEVEL swap_used=${swap_gib} GiB" ;;
     emergency)
-      message="EMERGENCY: fseventsd MEM=${mem_mib} MiB; $reasons; stop launching new work, save state, and reduce workload before the machine wedges"
+      message="EMERGENCY: fseventsd MEM=${mem_mib} MiB; $reasons; pressure_level=$FSEVENTSD_PRESSURE_LEVEL swap_used=${swap_gib} GiB; stop launching new work, save state, and reduce workload before the machine wedges"
       ;;
   esac
   fseventsd_publish_alert "$severity" "$message"
diff --git a/docs/scripts.md b/docs/scripts.md
index ead852c5438..a0f811d179e 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -104,7 +104,7 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize
 | `fm-check-register.sh`   | Bind an intentional custom watcher check to its current bytes                       |
 | `fm-check-lib.sh`        | Validate custom-check registrations and prepare private execution snapshots          |
 | `fm-tool-update-check.sh` | Report watched tooling with an update available, and updates installed but left inert by PATH order |
-| `fm-telemetry.sh`        | Arm, disarm, or report the never-auto-armed detached host resource-snapshot recorder that keeps durable pruned daily logs under `state/telemetry/` |
+| `fm-telemetry.sh`        | Arm, disarm, or report the never-auto-armed detached host resource-snapshot recorder that keeps durable pruned daily logs under `state/telemetry/`, and run the watcher's fseventsd footprint early-warning check |
 | `fm-pr-lib.sh`           | Own canonical task and PR validation plus private atomic PR-poll publication and identity-bound retirement |
 | `fm-pr-poll.sh`          | Provide the byte-static watcher program for validated PR/MR-poll sidecars           |
 | `fm-pr-check-migrate.sh` | Quarantine older task polls without execution and rebuild only canonical polls       |
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index 924c7dab57f..09b9ea9e33f 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -283,6 +283,25 @@ test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure(
   pass "fseventsd emergency requires sustained growth toward 4 GiB plus worsening pressure"
 }
 
+test_fseventsd_emergency_retains_the_evidence_it_measured() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-emergency-evidence-home"
+  fakebin="$TMP_ROOT/fseventsd-emergency-evidence-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  fseventsd_check "$home" "$fakebin" 1000 2600M 2 9000M >/dev/null
+  fseventsd_check "$home" "$fakebin" 1300 3000M 2 9000M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1600 3500M 2 9000M)
+  assert_contains "$out" 'EMERGENCY: fseventsd' "the sustained climb did not surface emergency"
+  assert_contains "$out" 'two consecutive samples above 512 MiB' "the emergency dropped the sustained 512 MiB breach it measured"
+  assert_contains "$out" 'MEM above 2 GiB' "the emergency dropped the 2 GiB action reason it measured"
+  assert_contains "$out" 'sustained growth toward 4 GiB plus worsening memory pressure' "the emergency did not identify its own threshold"
+  assert_contains "$out" 'pressure_level=2' "the emergency omitted the memory-pressure level"
+  assert_contains "$out" 'swap_used=8.79 GiB' "the emergency omitted the swap figure"
+  pass "fseventsd emergency reports every reason and telemetry the action tier carries"
+}
+
 test_fseventsd_check_reads_the_kernel_memory_pressure_encoding() {
   local home fakebin out
   fakebin="$TMP_ROOT/fseventsd-encoding-fakebin"
@@ -809,6 +828,7 @@ test_fseventsd_check_warns_after_two_hours_of_fast_growth
 test_fseventsd_check_surfaces_action_thresholds
 test_fseventsd_action_retains_the_warning_evidence_it_measured
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
+test_fseventsd_emergency_retains_the_evidence_it_measured
 test_fseventsd_check_reads_the_kernel_memory_pressure_encoding
 test_fseventsd_check_ignores_doubling_below_the_warning_floor
 test_fseventsd_check_emergency_accepts_sustained_pressure_without_a_rise

From feb01f91c825d4f2dc38da75d2b3be65fca00647 Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 20:05:02 +0800
Subject: [PATCH 5/8] no-mistakes(review): label fseventsd pressure by level,
 guard reason separators

---
 bin/fm-telemetry.sh        | 15 +++++++++++----
 tests/fm-telemetry.test.sh | 11 +++++++++++
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index 0fb4b5353f6..974fbabb9cc 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -428,9 +428,9 @@ fseventsd_check() {
   local prev_epoch=0 prev_mem=0
   local preprev_epoch=0 preprev_mem=0
   local growth_rate_mib='' doubling=0 warning=0
-  local severity=none reasons='' message mem_mib swap_gib
+  local severity=none reasons='' message mem_mib swap_gib pressure_label
   local warning_bytes=536870912 action_bytes=2147483648 swap_action_bytes=8589934592
-  local pressure_warn_level=2
+  local pressure_warn_level=2 pressure_critical_level=4
 
   now=${FM_TELEMETRY_NOW:-$(date '+%s' 2>/dev/null || true)}
   case "$now" in ''|*[!0-9]*) return 0 ;; esac
@@ -501,10 +501,17 @@ EOF
     reasons="${reasons}doubling within one hour"
   elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=action
-    reasons="${reasons}; warning plus yellow memory pressure"
+    if [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_critical_level" ]; then
+      pressure_label='red critical'
+    else
+      pressure_label=yellow
+    fi
+    [ -z "$reasons" ] || reasons="$reasons; "
+    reasons="${reasons}warning plus ${pressure_label} memory pressure"
   elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_SWAP_BYTES" -gt "$swap_action_bytes" ]; then
     severity=action
-    reasons="${reasons}; warning plus more than 8 GiB swap"
+    [ -z "$reasons" ] || reasons="$reasons; "
+    reasons="${reasons}warning plus more than 8 GiB swap"
   elif [ "$warning" -eq 1 ]; then
     severity=warning
   fi
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index 09b9ea9e33f..1498d0e1700 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -321,6 +321,17 @@ test_fseventsd_check_reads_the_kernel_memory_pressure_encoding() {
   fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
   out=$(fseventsd_check "$home" "$fakebin" 1300 600M 4 0.00M)
   assert_contains "$out" 'ACTION: fseventsd' "critical pressure level 4 did not escalate the warning"
+  assert_contains "$out" 'warning plus red critical memory pressure' "critical pressure level 4 was reported as yellow"
+  assert_contains "$out" 'pressure_level=4' "the critical-pressure action omitted the measured level"
+
+  home="$TMP_ROOT/fseventsd-encoding-warn-home"
+  mkdir -p "$home/state"
+  fseventsd_check "$home" "$fakebin" 1000 600M 1 0.00M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 600M 2 0.00M)
+  assert_contains "$out" 'warning plus yellow memory pressure' "warn pressure level 2 was not reported as yellow"
+  case "$out" in
+    *critical*) fail "warn pressure level 2 was reported as critical: $out" ;;
+  esac
   pass "fseventsd pressure escalation follows the kernel normal/warn/critical encoding"
 }
 

From e7b086ab374c3574b1efe0a1147353793b47b781 Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 20:16:00 +0800
Subject: [PATCH 6/8] no-mistakes(review): report every fseventsd action reason
 that holds

---
 bin/fm-telemetry.sh        | 12 ++++++++----
 tests/fm-telemetry.test.sh | 19 +++++++++++++++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index 974fbabb9cc..b49bcf6d744 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -495,11 +495,13 @@ EOF
     severity=action
     [ -z "$reasons" ] || reasons="$reasons; "
     reasons="${reasons}MEM above 2 GiB"
-  elif [ "$doubling" -eq 1 ]; then
+  fi
+  if [ "$doubling" -eq 1 ]; then
     severity=action
     [ -z "$reasons" ] || reasons="$reasons; "
     reasons="${reasons}doubling within one hour"
-  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
+  fi
+  if [ "$warning" -eq 1 ] && [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_warn_level" ]; then
     severity=action
     if [ "$FSEVENTSD_PRESSURE_LEVEL" -ge "$pressure_critical_level" ]; then
       pressure_label='red critical'
@@ -508,11 +510,13 @@ EOF
     fi
     [ -z "$reasons" ] || reasons="$reasons; "
     reasons="${reasons}warning plus ${pressure_label} memory pressure"
-  elif [ "$warning" -eq 1 ] && [ "$FSEVENTSD_SWAP_BYTES" -gt "$swap_action_bytes" ]; then
+  fi
+  if [ "$warning" -eq 1 ] && [ "$FSEVENTSD_SWAP_BYTES" -gt "$swap_action_bytes" ]; then
     severity=action
     [ -z "$reasons" ] || reasons="$reasons; "
     reasons="${reasons}warning plus more than 8 GiB swap"
-  elif [ "$warning" -eq 1 ]; then
+  fi
+  if [ "$severity" = none ] && [ "$warning" -eq 1 ]; then
     severity=warning
   fi
 
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index 1498d0e1700..8010b47389e 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -268,6 +268,24 @@ test_fseventsd_action_retains_the_warning_evidence_it_measured() {
   pass "fseventsd action alerts keep every warning reason measured in the same sample"
 }
 
+test_fseventsd_action_reports_every_condition_that_holds() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-action-cooccurring-home"
+  fakebin="$TMP_ROOT/fseventsd-action-cooccurring-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  fseventsd_check "$home" "$fakebin" 1000 600M 4 9000M >/dev/null
+  out=$(fseventsd_check "$home" "$fakebin" 1300 2500M 4 9000M)
+  assert_contains "$out" 'ACTION: fseventsd' "co-occurring action conditions did not surface action"
+  assert_contains "$out" 'two consecutive samples above 512 MiB' "the alert dropped the sustained 512 MiB breach"
+  assert_contains "$out" 'MEM above 2 GiB' "the alert dropped the 2 GiB threshold it crossed"
+  assert_contains "$out" 'doubling within one hour' "the alert dropped the doubling it measured"
+  assert_contains "$out" 'warning plus red critical memory pressure' "the alert dropped the critical memory pressure it measured"
+  assert_contains "$out" 'warning plus more than 8 GiB swap' "the alert dropped the swap breach it measured"
+  pass "fseventsd action reports every threshold that holds in the same sample"
+}
+
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure() {
   local home fakebin out
   home="$TMP_ROOT/fseventsd-emergency-home"
@@ -838,6 +856,7 @@ test_fseventsd_check_enforces_five_minute_sampling_and_consecutive_warning
 test_fseventsd_check_warns_after_two_hours_of_fast_growth
 test_fseventsd_check_surfaces_action_thresholds
 test_fseventsd_action_retains_the_warning_evidence_it_measured
+test_fseventsd_action_reports_every_condition_that_holds
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
 test_fseventsd_emergency_retains_the_evidence_it_measured
 test_fseventsd_check_reads_the_kernel_memory_pressure_encoding

From 91ae7175a6c1faa9c4383ede3821152be149904a Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 20:52:26 +0800
Subject: [PATCH 7/8] no-mistakes(review): isolate watcher tests from live
 fseventsd, alert on write failure

---
 bin/fm-telemetry.sh           | 10 ++++++++-
 tests/fm-telemetry.test.sh    | 39 ++++++++++++++++++++++++++++++++++-
 tests/fm-watcher-lock.test.sh | 36 ++++++++++++++++++++++++++++++++
 tests/lib.sh                  |  8 +++++++
 4 files changed, 91 insertions(+), 2 deletions(-)

diff --git a/bin/fm-telemetry.sh b/bin/fm-telemetry.sh
index b49bcf6d744..02d8d5d8f27 100755
--- a/bin/fm-telemetry.sh
+++ b/bin/fm-telemetry.sh
@@ -59,6 +59,12 @@
 # one snapshot and exit.
 # FM_TELEMETRY_NOW is a test seam that overrides the whole-second clock used by
 # `fseventsd-check` for its cadence, history and growth windows.
+# FM_TELEMETRY_FSEVENTSD_DISABLE=1 makes `fseventsd-check` a no-op before it
+# samples anything; the shared test library sets it so watcher tests never read
+# the live host, and production never sets it.
+# A sample whose history could not be persisted is still alerted on, with the
+# persistence failure reported as a diagnostic, so a full disk cannot silence a
+# level that was already measured.
 # Internal record mode without an owner token re-execs itself with a synthesized
 # one, so every recorder carries its token in argv and status and disarm have a
 # single liveness rule.
@@ -432,6 +438,7 @@ fseventsd_check() {
   local warning_bytes=536870912 action_bytes=2147483648 swap_action_bytes=8589934592
   local pressure_warn_level=2 pressure_critical_level=4
 
+  case "${FM_TELEMETRY_FSEVENTSD_DISABLE:-0}" in ''|0) ;; *) return 0 ;; esac
   now=${FM_TELEMETRY_NOW:-$(date '+%s' 2>/dev/null || true)}
   case "$now" in ''|*[!0-9]*) return 0 ;; esac
   mkdir -p "$TELEMETRY_DIR" || return 0
@@ -532,7 +539,8 @@ EOF
   fi
 
   fseventsd_record_sample "$now" "$FSEVENTSD_MEM_BYTES" \
-    "$FSEVENTSD_PRESSURE_LEVEL" "$FSEVENTSD_SWAP_BYTES" || return 0
+    "$FSEVENTSD_PRESSURE_LEVEL" "$FSEVENTSD_SWAP_BYTES" \
+    || diagnostic "could not persist the fseventsd sample history"
   if [ "$severity" = none ]; then
     rm -f "$FSEVENTSD_ALERT"
     return 0
diff --git a/tests/fm-telemetry.test.sh b/tests/fm-telemetry.test.sh
index 8010b47389e..ca38d4d3069 100755
--- a/tests/fm-telemetry.test.sh
+++ b/tests/fm-telemetry.test.sh
@@ -91,7 +91,7 @@ SH
 
 fseventsd_check() {
   local home=$1 fakebin=$2 now=$3 mem=$4 pressure=$5 swap=$6
-  FM_HOME="$home" FM_TELEMETRY_NOW="$now" \
+  FM_HOME="$home" FM_TELEMETRY_NOW="$now" FM_TELEMETRY_FSEVENTSD_DISABLE=0 \
     FM_FAKE_FSEVENTSD_MEM="$mem" FM_FAKE_PRESSURE_LEVEL="$pressure" \
     FM_FAKE_SWAP_USED="$swap" PATH="$fakebin:/usr/bin:/bin" \
     "$TELEMETRY" fseventsd-check
@@ -286,6 +286,41 @@ test_fseventsd_action_reports_every_condition_that_holds() {
   pass "fseventsd action reports every threshold that holds in the same sample"
 }
 
+test_fseventsd_check_is_disabled_by_its_seam() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-disabled-home"
+  fakebin="$TMP_ROOT/fseventsd-disabled-fakebin"
+  mkdir -p "$home/state"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  out=$(FM_HOME="$home" FM_TELEMETRY_NOW=1000 FM_TELEMETRY_FSEVENTSD_DISABLE=1 \
+    FM_FAKE_FSEVENTSD_MEM=2049M FM_FAKE_PRESSURE_LEVEL=4 FM_FAKE_SWAP_USED=9000M \
+    PATH="$fakebin:/usr/bin:/bin" "$TELEMETRY" fseventsd-check)
+  [ -z "$out" ] || fail "the disabled check still alerted: $out"
+  [ ! -e "$home/state/telemetry/fseventsd-samples" ] ||
+    fail "the disabled check still sampled and persisted history"
+  out=$(fseventsd_check "$home" "$fakebin" 1000 2049M 4 9000M)
+  assert_contains "$out" 'ACTION: fseventsd' "the check did not run once its seam was cleared"
+  pass "fseventsd-check samples nothing while its disable seam is set"
+}
+
+test_fseventsd_alerts_even_when_history_cannot_be_persisted() {
+  local home fakebin out
+  home="$TMP_ROOT/fseventsd-unwritable-home"
+  fakebin="$TMP_ROOT/fseventsd-unwritable-fakebin"
+  mkdir -p "$home/state/telemetry"
+  write_fake_fseventsd_samplers "$fakebin"
+
+  printf '900 104857600 1 0\n' > "$home/state/telemetry/fseventsd-samples"
+  chmod 000 "$home/state/telemetry/fseventsd-samples" ||
+    fail "could not make the sample history unreadable"
+  out=$(fseventsd_check "$home" "$fakebin" 1000 2500M 2 0.00M 2>/dev/null)
+  chmod 600 "$home/state/telemetry/fseventsd-samples"
+  assert_contains "$out" 'ACTION: fseventsd' "a failed history write silenced the measured action level"
+  assert_contains "$out" 'MEM above 2 GiB' "the alert lost the threshold it measured"
+  pass "fseventsd alerts on a measured level even when its history cannot be persisted"
+}
+
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure() {
   local home fakebin out
   home="$TMP_ROOT/fseventsd-emergency-home"
@@ -857,6 +892,8 @@ test_fseventsd_check_warns_after_two_hours_of_fast_growth
 test_fseventsd_check_surfaces_action_thresholds
 test_fseventsd_action_retains_the_warning_evidence_it_measured
 test_fseventsd_action_reports_every_condition_that_holds
+test_fseventsd_check_is_disabled_by_its_seam
+test_fseventsd_alerts_even_when_history_cannot_be_persisted
 test_fseventsd_check_emergency_requires_sustained_growth_and_worsening_pressure
 test_fseventsd_emergency_retains_the_evidence_it_measured
 test_fseventsd_check_reads_the_kernel_memory_pressure_encoding
diff --git a/tests/fm-watcher-lock.test.sh b/tests/fm-watcher-lock.test.sh
index ce0efd3f7ef..41d34a9a2c3 100755
--- a/tests/fm-watcher-lock.test.sh
+++ b/tests/fm-watcher-lock.test.sh
@@ -780,9 +780,11 @@ SH
   chmod +x "$fakebin/pgrep" "$fakebin/top" "$fakebin/sysctl"
 
   FM_HOME="$dir" FM_STATE_OVERRIDE="$state" FM_TELEMETRY_NOW=1000 \
+    FM_TELEMETRY_FSEVENTSD_DISABLE=0 \
     PATH="$fakebin:$PATH" "$ROOT/bin/fm-telemetry.sh" fseventsd-check >/dev/null \
     || fail "could not establish the fseventsd warning baseline"
   FM_HOME="$dir" FM_STATE_OVERRIDE="$state" FM_TELEMETRY_NOW=1300 \
+    FM_TELEMETRY_FSEVENTSD_DISABLE=0 \
     PATH="$fakebin:$PATH" FM_POLL=5 FM_SIGNAL_GRACE=1 FM_CHECK_INTERVAL=0 \
     FM_HEARTBEAT=999999 "$WATCH" > "$out" || fail "watcher did not surface the fseventsd warning"
   grep -F 'check: fseventsd: WARNING: fseventsd' "$out" >/dev/null \
@@ -793,6 +795,39 @@ SH
   pass "watcher surfaces fseventsd warnings through its existing slow-check wake path"
 }
 
+test_watcher_tests_never_sample_the_live_fseventsd() {
+  local dir state fakebin out probe wpid
+  dir=$(make_case fseventsd-no-live-sampling)
+  state="$dir/state"
+  fakebin="$dir/fakebin"
+  out="$dir/watch.out"
+  probe="$dir/sampled"
+  mark_pr_check_migration_complete "$state"
+  cat > "$fakebin/pgrep" <<SH
+#!/usr/bin/env bash
+printf 'sampled\n' >> "$probe"
+exit 1
+SH
+  cat > "$fakebin/top" <<SH
+#!/usr/bin/env bash
+printf 'sampled\n' >> "$probe"
+exit 1
+SH
+  chmod +x "$fakebin/pgrep" "$fakebin/top"
+
+  PATH="$fakebin:$PATH" FM_HOME="$dir" FM_STATE_OVERRIDE="$state" \
+    FM_POLL=0.2 FM_SIGNAL_GRACE=1 FM_CHECK_INTERVAL=0 FM_HEARTBEAT=999999 \
+    "$WATCH" > "$out" &
+  wpid=$!
+  sleep 2
+  kill -0 "$wpid" 2>/dev/null || fail "watcher exited on its own: $(cat "$out")"
+  kill "$wpid" 2>/dev/null || true
+  wait "$wpid" 2>/dev/null || true
+  [ ! -e "$probe" ] || fail "the watcher sampled fseventsd despite the shared test seam"
+  grep -F 'fseventsd' "$out" >/dev/null && fail "a disabled fseventsd check still produced a wake: $(cat "$out")"
+  pass "the shared test seam keeps watcher spawns from sampling the live fseventsd"
+}
+
 test_arm_waits_for_peer_beacon_after_child_stands_down() {
   local dir state fakebin armout peer identity armpid status i
   dir=$(make_case arm-peer-startup-race)
@@ -1166,6 +1201,7 @@ test_arm_starts_and_self_heals
 test_arm_hup_cleans_child_and_temp_output
 test_arm_propagates_immediate_wake_before_confirmation
 test_watcher_surfaces_fseventsd_warning_on_slow_check_path
+test_watcher_tests_never_sample_the_live_fseventsd
 test_arm_waits_for_peer_beacon_after_child_stands_down
 test_arm_fails_loud_when_no_fresh_watcher_confirmable
 test_cycle_exit_ledger_links_successor_and_stays_bounded
diff --git a/tests/lib.sh b/tests/lib.sh
index 915741ba0d5..504ab1f43b4 100644
--- a/tests/lib.sh
+++ b/tests/lib.sh
@@ -34,6 +34,14 @@ FM_TEST_LIB_SOURCED=1
 # strips this to verify real refusal.
 export FM_GATE_REFUSE_BYPASS=1
 
+# Every watcher spawn evaluates the slow-check block on its first cycle, because
+# a missing .last-check reads as "due immediately" regardless of FM_CHECK_INTERVAL.
+# Without this the fseventsd early-warning check would run pgrep/top against the
+# live host in every watcher test, coupling unrelated suites to this machine's real
+# fseventsd footprint and adding a subprocess of latency to each first cycle. Tests
+# that exercise the check itself set FM_TELEMETRY_FSEVENTSD_DISABLE=0 with fakes.
+export FM_TELEMETRY_FSEVENTSD_DISABLE=1
+
 # Resolve the repo root from this library's own location. Consumed by sourcing
 # test files, not by this library, so it reads as "unused" here.
 # shellcheck disable=SC2034

From ed904116ee0cd1b91a3bb841f03149f4bb4ca6af Mon Sep 17 00:00:00 2001
From: Ivan Li <ivan@withally.com>
Date: Mon, 24 Aug 2026 21:16:28 +0800
Subject: [PATCH 8/8] no-mistakes(document): document fseventsd early-warning
 wake in architecture

---
 docs/architecture.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 4616991e323..bc8d380a069 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -9,7 +9,9 @@ firstmate's always-loaded operating contract and routing index for conditional p
 ## Event-driven supervision
 
 A zero-token bash watcher (`bin/fm-watch.sh`) sleeps on the fleet, classifies detected wakes in bash, and wakes the first mate only when something is actionable.
-Actionable wakes include captain-relevant status signals, no-verb signals whose crew is not provably working, authenticated check output such as PR merge polling or a Relay mention, stale panes whose crew is not provably working whether their status log looks terminal or non-terminal, provably-working stale panes that persist past `FM_STALE_ESCALATE_SECS` without their own task worktree being written, declared external waits and verified captain-held transfers that remain declared past `FM_PAUSE_RESURFACE_SECS`, and heartbeat backstop hits.
+Actionable wakes include captain-relevant status signals, no-verb signals whose crew is not provably working, authenticated check output such as PR merge polling or a Relay mention, the built-in fseventsd footprint early warning, stale panes whose crew is not provably working whether their status log looks terminal or non-terminal, provably-working stale panes that persist past `FM_STALE_ESCALATE_SECS` without their own task worktree being written, declared external waits and verified captain-held transfers that remain declared past `FM_PAUSE_RESURFACE_SECS`, and heartbeat backstop hits.
+That fseventsd early warning runs on the same bounded slow-check cadence and wakes only when the host's fseventsd memory footprint newly reaches a warning, action, or emergency level, so a level that is merely still true never re-wakes.
+`bin/fm-telemetry.sh` owns its sampling, its bounded history under `state/telemetry/`, and the thresholds themselves.
 Repeated provably-working stale escalations on the same unchanged pane add an escalation count to the wake reason and, at `FM_WEDGE_DEMAND_INSPECT_COUNT`, a `demand-deep-inspection` marker.
 A pane holding a file newer than the start of its own quiet window, anywhere in the worktree recorded for that task, is deferred instead of escalated, because a crew writing source, then tests, then documentation behind a static pane is liveness that neither pane quietness nor the run step can show.
 That deferral re-surfaces on the same `FM_PAUSE_RESURFACE_SECS` cadence as a declared wait, with a reason naming the write evidence rather than a wedge, and it is bounded to one pruned, depth-bounded, wall-clock-bounded walk (`FM_WORKTREE_WRITE_PRUNE`, `FM_WORKTREE_WRITE_MAXDEPTH`, `FM_WORKTREE_WRITE_TIMEOUT`) taken only in the branch that was about to escalate, never on every poll.