caproom 0.3.1 → 0.5.0

package/bin/caproom

@@ -3,10 +3,12 @@
 # on macOS/Linux. macOS has no working RLIMIT_AS/DATA/RSS or launchd RSS
 # enforcement (verified empirically — both are no-ops on modern macOS), so
 # this uses whichever real enforcement mechanism is available:
-#   1. Docker cgroup (--memory) — hard cap, zero race window. Used when
-#      `docker` is installed and the daemon is running.
-#   2. Polling watchdog (ps RSS + SIGKILL) — fallback, no dependencies,
-#      works everywhere, has a small race window (poll interval).
+#   1. Host-native polling watchdog (process-tree RSS + SIGKILL) — the
+#      DEFAULT. Runs in your real environment: same PATH, auth, native
+#      binaries, tty. Small race window bounded by --interval.
+#   2. Docker cgroup (--memory) — opt-in via --docker. Hard cap, zero race
+#      window, but runs the command inside a Linux container (native-module
+#      and toolchain drift; see README). Fails loudly if the daemon is down.
 set -euo pipefail
 
 usage() {
@@ -18,27 +20,41 @@ usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <co
        caproom park <pid>
        caproom wake <pid>
        caproom status <pid>
+       caproom guard [--threshold <pct>] [--interval <sec>] <pid...>
        caproom init <command> [--limit <mb>] [--grace <sec>]
 
   --limit <mb>     memory cap in MB (default: 4096)
-  --image <name>   docker image to run the command in, when using the docker
-                    backend (default: node:22-slim)
-  --interval <sec> watchdog poll interval in seconds, fallback backend only
-                    (default: 0.2)
+  --interval <sec> watchdog poll interval in seconds (default: 0.2)
   --grace <sec>    seconds to wait after SIGTERM before SIGKILL, watchdog
                     backend only (default: 5) — gives the process a chance
                     to flush/save state before a hard kill
-  --force-watchdog force the polling watchdog even if Docker is available
+  --docker         opt in to the Docker cgroup backend instead of the default
+                    host-native watchdog (needs the daemon running)
+  --image <name>   docker image used by the --docker backend
+                    (default: node:22-slim)
+  --force-watchdog no-op; the host-native watchdog IS the default — kept so
+                    existing scripts and 'init' snippets keep working
 
-park / wake — freeze an idle process so the kernel can reclaim/compress its
-memory without killing it. For a long-running agent sitting on stale
-subprocesses: `caproom park <pid>` (SIGSTOP) instead of killing it. It stays
-alive, keeps its PID, keeps its state — just isn't scheduled and its memory
-becomes eligible for compression under system memory pressure. `caproom wake
+park / wake — freeze an idle process so the kernel CAN reclaim/compress its
+memory without killing it. Honest semantics: SIGSTOP only makes the pages
+eligible — the kernel reclaims them lazily, when real memory pressure hits.
+Park a 2GB agent on a quiet machine and it may stay ~2GB resident for hours.
+Park is insurance against OOM, not immediate RAM return; use it for processes
+too expensive to restart. `caproom park <pid>` (SIGSTOP), `caproom wake
 <pid>` (SIGCONT) brings it back instantly, same state, no restart needed.
 Any agent can call these directly — they're just SIGSTOP/SIGCONT, no daemon,
 no tracking file required.
 
+guard — watch SYSTEM-WIDE free memory (not any single process) and auto-park
+tracked pids (SIGSTOP) when free mem drops below --threshold percent, before
+the kernel OOM-killer has to pick a victim. Use it when unrelated heavy
+processes (e.g. a GPU inference job in one terminal, a TTS job in another)
+share a box and neither is individually over any --limit cap. Foreground,
+blocking; exits once all watched pids have exited. Does not auto-wake —
+`caproom wake <pid>` when memory pressure clears:
+
+  caproom guard --threshold 10 --interval 5 -- 12345 12346
+
 init <command> — print a shell snippet that auto-caps <command> on every
 invocation, so a new terminal tab is capped with no extra typing. Append the
 output to your shell rc (~/.zshrc, ~/.bashrc):
@@ -50,8 +66,11 @@ env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL, CA
 examples:
   caproom --limit 2048 -- npm run build
   caproom --limit 512 -- claude --dangerously-skip-permissions -p "task"
+  caproom --limit 4096 --docker --image python:3.12-slim -- python train.py
   caproom park 12345
   caproom wake 12345
+  caproom top --json [--pid <pid>] [--park-min-mb <mb>]
+  caproom watch [--threshold-mb <mb>] [--auto-park] [--auto-wake-free-pct <pct>] [--json] <pid...>
   caproom init claude --limit 6144 --grace 10
 EOF
   exit "$code"
@@ -86,7 +105,7 @@ cmd_park() {
   [[ -z "$pid" ]] && { echo "usage: caproom park <pid>" >&2; exit 1; }
   kill -0 "$pid" 2>/dev/null || { echo "caproom: no such pid $pid" >&2; exit 1; }
   kill -STOP "$pid"
-  echo "caproom: pid $pid parked (SIGSTOP) — memory now eligible for kernel reclaim under pressure. wake with: caproom wake $pid" >&2
+  echo "caproom: pid $pid parked (SIGSTOP) — pages now eligible for kernel reclaim, but the kernel acts only under real memory pressure; on a quiet machine RSS may not drop. wake with: caproom wake $pid" >&2
 }
 
 cmd_wake() {
@@ -103,10 +122,334 @@ cmd_status() {
   ps -o pid,stat,rss,etime,command -p "$pid" 2>/dev/null || { echo "caproom: no such pid $pid" >&2; exit 1; }
 }
 
+# ---- process-tree inventory (top / watch foundation) ----
+
+# One ps pass filling the SNAP_* global arrays for the current user.
+read_snapshot() {
+  SNAP_PID=(); SNAP_PPID=(); SNAP_RSS=(); SNAP_ST=(); SNAP_ET=(); SNAP_CMD=()
+  local myuid uid pid ppid rss st et cmd
+  myuid="$(id -u)"
+  while read -r uid pid ppid rss st et cmd; do
+    [[ "$uid" != "$myuid" ]] && continue
+    SNAP_PID+=("$pid"); SNAP_PPID+=("$ppid"); SNAP_RSS+=("${rss:-0}")
+    SNAP_ST+=("${st:-?}"); SNAP_ET+=("${et:-0}"); SNAP_CMD+=("${cmd:-}")
+  done < <(ps -eo uid=,pid=,ppid=,rss=,state=,etime=,command=)
+}
+
+# Walk the subtree of $1 over the existing SNAP_* arrays, filling
+# TREE_PIDS / TREE_RSS_KB. Does NOT re-read ps — cheap enough to call
+# once per tree root from a single snapshot.
+walk_tree() {
+  local root="$1" cur i j
+  local -a lpids=("${SNAP_PPID[@]}") lq=()
+  TREE_PIDS=(); TREE_RSS_KB=0
+  lq=("$root")
+  while [[ ${#lq[@]} -gt 0 ]]; do
+    cur="${lq[0]}"
+    if [[ ${#lq[@]} -gt 1 ]]; then lq=("${lq[@]:1}"); else lq=(); fi
+    for i in "${!SNAP_PID[@]}"; do
+      if [[ "${SNAP_PID[$i]}" == "$cur" ]]; then
+        TREE_PIDS+=("$cur")
+        TREE_RSS_KB=$(( TREE_RSS_KB + SNAP_RSS[$i] ))
+        for j in "${!lpids[@]}"; do
+          if [[ "${lpids[$j]}" == "$cur" ]]; then
+            lq+=("${SNAP_PID[$j]}")
+            lpids[$j]=""
+          fi
+        done
+        break
+      fi
+    done
+  done
+}
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/ }"
+  s="${s//$'\r'/ }"
+  s="${s//$'\t'/ }"
+  printf '%s' "$s"
+}
+
+cmd_top() {
+  local json=0 park_min_kb=$(( 512 * 1024 )) filter_pid=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --json) json=1; shift ;;
+      --park-min-mb) park_min_kb=$(( $2 * 1024 )); shift 2 ;;
+      --pid) filter_pid="$2"; shift 2 ;;
+      *) echo "caproom top: unknown option $1" >&2; exit 1 ;;
+    esac
+  done
+
+  read_snapshot
+  [[ ${#SNAP_PID[@]} -eq 0 ]] && { [[ $json -eq 1 ]] && printf '{"schema":1,"ts":%s,"limit_mb_default":%s,"processes":[]}\n' "$(date +%s)" "${CAPROOM_LIMIT_MB:-4096}"; return 0; }
+
+  # Tree roots: parents outside the visible set (or init-reparented).
+  local -a roots=()
+  local i j p found
+  if [[ -n "$filter_pid" ]]; then
+    found=""
+    for i in "${!SNAP_PID[@]}"; do
+      [[ "${SNAP_PID[$i]}" == "$filter_pid" ]] && { roots+=("$filter_pid"); found=1; break; }
+    done
+    if [[ -z "$found" ]]; then
+      echo "caproom: no such pid $filter_pid (or not owned by you)" >&2
+      exit 1
+    fi
+  else
+    for i in "${!SNAP_PID[@]}"; do
+      [[ "${SNAP_PID[$i]}" == "$$" ]] && continue   # never report ourselves
+      p="${SNAP_PPID[$i]}"
+      if [[ "$p" == "1" ]]; then roots+=("${SNAP_PID[$i]}"); continue; fi
+      found=""
+      for j in "${!SNAP_PID[@]}"; do
+        if [[ "${SNAP_PID[$j]}" == "$p" ]]; then found=1; break; fi
+      done
+      [[ -z "$found" ]] && roots+=("${SNAP_PID[$i]}")
+    done
+  fi
+
+  # Walk each root once; keep results in parallel arrays, then sort by
+  # tree RSS descending via a sortable temp stream.
+  local -a r_pid=() r_trss=() r_tpids=() r_st=() r_et=() r_cmd=() order=()
+  for p in "${roots[@]}"; do
+    walk_tree "$p"
+    local tjoin=""
+    [[ ${#TREE_PIDS[@]} -gt 0 ]] && tjoin="$(printf '%s,' "${TREE_PIDS[@]}")" && tjoin="${tjoin%,}"
+    for i in "${!SNAP_PID[@]}"; do
+      if [[ "${SNAP_PID[$i]}" == "$p" ]]; then
+        r_pid+=("$p"); r_trss+=("$TREE_RSS_KB")
+        r_tpids+=("$tjoin")
+        r_st+=("${SNAP_ST[$i]}"); r_et+=("${SNAP_ET[$i]}")
+        r_cmd+=("${SNAP_CMD[$i]}")
+        order+=("$(printf '%010d %d\n' "$TREE_RSS_KB" $(( ${#r_pid[@]} - 1 )))")
+        break
+      fi
+    done
+  done
+
+  if [[ $json -eq 1 ]]; then
+    local ts out='[' first=1 idx state cand reason kb
+    ts="$(date +%s)"
+    local -a sorted
+    sorted=($(printf '%s\n' "${order[@]:-}" | sort -rn | awk '{print $2}'))
+    for idx in "${sorted[@]:-}"; do
+      [[ -z "$idx" ]] && continue
+      kb="${r_trss[$idx]}"
+      local st0="${r_st[$idx]:0:1}"
+      case "$st0" in
+        T) state="parked" ;;
+        Z) state="zombie" ;;
+        *) state="running" ;;
+      esac
+      cand=false; reason=""
+      if [[ "$state" == "running" && ( "$st0" == "S" || "$st0" == "I" ) ]] && [[ "$kb" -ge "$park_min_kb" ]]; then
+        cand=true
+        reason="root sleeping + tree_rss ${kb}KB >= ${park_min_kb}KB park threshold"
+      fi
+      [[ $first -eq 1 ]] || out+=','
+      first=0
+      out+="{\"pid\":${r_pid[$idx]},\"cmd\":\"$(json_escape "${r_cmd[$idx]}")\",\"tree_rss_kb\":${kb},\"tree_pids\":[${r_tpids[$idx]}],\"state\":\"$state\",\"park_candidate\":$cand,\"reason\":\"$(json_escape "$reason")\"}"
+    done
+    out+=']'
+    printf '{"schema":1,"ts":%s,"limit_mb_default":%s,"processes":%s}\n' "$ts" "${CAPROOM_LIMIT_MB:-4096}" "$out"
+  else
+    local idx mb
+    printf '%-8s %10s %-8s %-9s %s\n' PID TREE_MB STATE ETIME COMMAND
+    local -a sorted
+    sorted=($(printf '%s\n' "${order[@]:-}" | sort -rn | awk '{print $2}'))
+    for idx in "${sorted[@]:-}"; do
+      [[ -z "$idx" ]] && continue
+      mb=$(( r_trss[idx] / 1024 ))
+      case "${r_st[$idx]}" in T) printf '%-8s %10s %-8s %-9s %s\n' "${r_pid[$idx]}" "$mb" PARKED "${r_et[$idx]}" "${r_cmd[$idx]:0:60}" ;; *) printf '%-8s %10s %-8s %-9s %s\n' "${r_pid[$idx]}" "$mb" "-" "${r_et[$idx]}" "${r_cmd[$idx]:0:60}" ;; esac
+    done
+  fi
+}
+
+cmd_watch() {
+  # Daemon: watch explicit pids, emit events when their TREE crosses a
+  # RSS threshold. --auto-park freezes breaching trees (SIGSTOP every pid
+  # in the snapshot) — only for pids passed explicitly, since stopping a
+  # mid-write process risks corruption; naming the pid IS the opt-in.
+  # --auto-wake-free-pct N undoes its own parks when free memory recovers.
+  local threshold_kb=$(( 2048 * 1024 )) interval=5 json=0 auto=0 wake_pct=""
+  local -a pids=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --threshold-mb) threshold_kb=$(( $2 * 1024 )); shift 2 ;;
+      --interval) interval="$2"; shift 2 ;;
+      --auto-park) auto=1; shift ;;
+      --auto-wake-free-pct) wake_pct="$2"; shift 2 ;;
+      --json) json=1; shift ;;
+      *) pids+=("$1"); shift ;;
+    esac
+  done
+  [[ ${#pids[@]} -eq 0 ]] && { echo "usage: caproom watch [--threshold-mb <mb>] [--interval <sec>] [--auto-park] [--auto-wake-free-pct <pct>] [--json] <pid...>" >&2; exit 1; }
+
+  local -a parked_by_us=() breaching=()
+  local mode
+  mode="watch"
+  [[ $auto -eq 1 ]] && mode="auto-park"
+  if [[ $json -eq 1 ]]; then
+    printf '{"schema":1,"event":"started","ts":%s,"mode":"%s","threshold_kb":%s,"pids":[%s]}\n' "$(date +%s)" "$mode" "$threshold_kb" "$(printf '%s,' "${pids[@]}" | sed 's/,$//')"
+  else
+    echo "caproom: watching ${#pids[@]} pid(s), tree threshold $(( threshold_kb / 1024 ))MB, poll ${interval}s$([[ $auto -eq 1 ]] && echo ', AUTO-PARK ARMED')$([[ -n "$wake_pct" ]] && echo ", auto-wake at >=${wake_pct}% free")" >&2
+  fi
+
+  while :; do
+    local -a alive=()
+    local pid i st0
+    for pid in "${pids[@]}"; do
+      kill -0 "$pid" 2>/dev/null && alive+=("$pid")
+    done
+    if [[ ${#alive[@]} -eq 0 ]]; then
+      [[ $json -eq 1 ]] && printf '{"schema":1,"event":"all-exited","ts":%s}\n' "$(date +%s)"
+      echo "caproom: watch: all watched pids exited" >&2
+      exit 0
+    fi
+    pids=("${alive[@]}")
+
+    # Auto-wake first: restore what WE parked once pressure clears.
+    if [[ -n "$wake_pct" && ${#parked_by_us[@]} -gt 0 ]]; then
+      local pct
+      pct=$(mem_free_pct)
+      if [[ "$pct" -ge "$wake_pct" ]]; then
+        local -a woke=()
+        for pid in "${parked_by_us[@]}"; do
+          if kill -0 "$pid" 2>/dev/null && kill -CONT "$pid" 2>/dev/null; then
+            woke+=("$pid")
+            if [[ $json -eq 1 ]]; then
+              printf '{"schema":1,"event":"woke","ts":%s,"pid":%s,"free_pct":%s}\n' "$(date +%s)" "$pid" "$pct"
+            else
+              echo "caproom: watch: free mem ${pct}% >= ${wake_pct}% — waking pid $pid" >&2
+            fi
+          fi
+        done
+        parked_by_us=()
+      fi
+    fi
+
+    read_snapshot
+    for pid in "${pids[@]}"; do
+      local found=""
+      for i in "${!SNAP_PID[@]}"; do
+        [[ "${SNAP_PID[$i]}" == "$pid" ]] && { found="$i"; break; }
+      done
+      [[ -z "$found" ]] && continue
+      st0="${SNAP_ST[$found]:0:1}"
+      [[ "$st0" == "T" || "$st0" == "Z" ]] && continue   # already parked/dead
+      walk_tree "$pid"
+      if [[ "$TREE_RSS_KB" -ge "$threshold_kb" ]]; then
+        local is_breaching=""
+        local ev1
+        for ev1 in ${breaching[@]+"${breaching[@]}"}; do [[ "$ev1" == "$pid" ]] && is_breaching=1 && break; done
+        if [[ -n "$is_breaching" ]]; then continue; fi
+        breaching+=("$pid")
+        if [[ $auto -eq 1 ]]; then
+          local tp stopped=0
+          for tp in "${TREE_PIDS[@]}"; do
+            kill -STOP "$tp" 2>/dev/null && { parked_by_us+=("$tp"); stopped=$(( stopped + 1 )); }
+          done
+          if [[ $json -eq 1 ]]; then
+            printf '{"schema":1,"event":"parked","ts":%s,"pid":%s,"tree_rss_kb":%s,"tree_pids":[%s],"stopped":%s}\n' "$(date +%s)" "$pid" "$TREE_RSS_KB" "$(printf '%s,' "${TREE_PIDS[@]}" | sed 's/,$//')" "$stopped"
+          else
+            echo "caproom: watch: tree of pid $pid hit $(( TREE_RSS_KB / 1024 ))MB (>= $(( threshold_kb / 1024 ))MB) — PARKED tree (${stopped} pids, wake: caproom wake $pid)" >&2
+          fi
+        else
+          if [[ $json -eq 1 ]]; then
+            printf '{"schema":1,"event":"breach","ts":%s,"pid":%s,"tree_rss_kb":%s}\n' "$(date +%s)" "$pid" "$TREE_RSS_KB"
+          else
+            echo "caproom: watch: tree of pid $pid hit $(( TREE_RSS_KB / 1024 ))MB (>= $(( threshold_kb / 1024 ))MB) — no --auto-park, reporting only" >&2
+          fi
+        fi
+      else
+        local -a keep=()
+        local was_breaching=0 ev2
+        for ev2 in ${breaching[@]+"${breaching[@]}"}; do
+          if [[ "$ev2" == "$pid" ]]; then was_breaching=1; else keep+=("$ev2"); fi
+        done
+        if [[ $was_breaching -eq 1 ]]; then
+          breaching=()
+          local k2
+          for k2 in ${keep[@]+"${keep[@]}"}; do breaching+=("$k2"); done
+          if [[ $json -eq 1 ]]; then
+            printf '{"schema":1,"event":"recovered","ts":%s,"pid":%s,"tree_rss_kb":%s}\n' "$(date +%s)" "$pid" "$TREE_RSS_KB"
+          else
+            echo "caproom: watch: pid $pid back under threshold ($(( TREE_RSS_KB / 1024 ))MB)" >&2
+          fi
+        fi
+      fi
+    done
+    sleep "$interval"
+  done
+}
+
+mem_free_pct() {  if [[ "$(uname)" == "Darwin" ]]; then
+    local page_size free inactive total_bytes avail_bytes
+    page_size=$(vm_stat | awk '/page size of/ {print $8}')
+    free=$(vm_stat | awk '/Pages free/ {gsub("\\.","",$3); print $3}')
+    inactive=$(vm_stat | awk '/Pages inactive/ {gsub("\\.","",$3); print $3}')
+    total_bytes=$(sysctl -n hw.memsize)
+    avail_bytes=$(( (free + inactive) * page_size ))
+    echo $(( avail_bytes * 100 / total_bytes ))
+  else
+    local avail_kb total_kb
+    avail_kb=$(awk '/MemAvailable/ {print $2}' /proc/meminfo)
+    total_kb=$(awk '/MemTotal/ {print $2}' /proc/meminfo)
+    echo $(( avail_kb * 100 / total_kb ))
+  fi
+}
+
+cmd_guard() {
+  local threshold=10
+  local interval=5
+  local pids=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --threshold) threshold="$2"; shift 2 ;;
+      --interval) interval="$2"; shift 2 ;;
+      --) shift ;;
+      *) pids+=("$1"); shift ;;
+    esac
+  done
+  [[ ${#pids[@]} -eq 0 ]] && { echo "usage: caproom guard [--threshold <pct>] [--interval <sec>] <pid...>" >&2; exit 1; }
+  echo "caproom: guarding ${#pids[@]} pid(s), park when system free mem < ${threshold}% (poll ${interval}s)" >&2
+  local parked=()
+  while :; do
+    local alive=()
+    local pid
+    for pid in "${pids[@]}"; do
+      kill -0 "$pid" 2>/dev/null && alive+=("$pid")
+    done
+    if [[ ${#alive[@]} -eq 0 ]]; then
+      echo "caproom: guard: all watched pids exited" >&2
+      exit 0
+    fi
+    pids=("${alive[@]}")
+    local pct
+    pct=$(mem_free_pct)
+    if [[ "$pct" -lt "$threshold" ]]; then
+      for pid in "${pids[@]}"; do
+        if [[ ! " ${parked[*]:-} " == *" $pid "* ]]; then
+          echo "caproom: system free mem ${pct}% < ${threshold}% threshold — about to blow, parking pid $pid (SIGSTOP)" >&2
+          kill -STOP "$pid" 2>/dev/null && parked+=("$pid")
+        fi
+      done
+    fi
+    sleep "$interval"
+  done
+}
+
 case "${1:-}" in
   park) shift; cmd_park "$@"; exit 0 ;;
   wake) shift; cmd_wake "$@"; exit 0 ;;
   status) shift; cmd_status "$@"; exit 0 ;;
+  top) shift; cmd_top "$@"; exit 0 ;;
+  watch) shift; cmd_watch "$@"; exit 0 ;;
+  guard) shift; cmd_guard "$@"; exit 0 ;;
   init) shift; cmd_init "$@"; exit 0 ;;
   help|-h|--help) usage help ;;
 esac
@@ -115,7 +458,7 @@ LIMIT_MB="${CAPROOM_LIMIT_MB:-4096}"
 IMAGE="${CAPROOM_IMAGE:-node:22-slim}"
 INTERVAL="${CAPROOM_INTERVAL:-0.2}"
 GRACE="${CAPROOM_GRACE:-5}"
-FORCE_WATCHDOG=0
+USE_DOCKER=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -123,7 +466,10 @@ while [[ $# -gt 0 ]]; do
     --image) IMAGE="$2"; shift 2 ;;
     --interval) INTERVAL="$2"; shift 2 ;;
     --grace) GRACE="$2"; shift 2 ;;
-    --force-watchdog) FORCE_WATCHDOG=1; shift ;;
+    --docker) USE_DOCKER=1; shift ;;
+    # legacy no-op: the watchdog IS the default now; accepted so old
+    # scripts and init snippets keep working
+    --force-watchdog) shift ;;
     --) shift; break ;;
     -h|--help) usage help ;;
     *) break ;;
@@ -132,10 +478,6 @@ done
 
 [[ $# -eq 0 ]] && usage
 
-docker_available() {
-  [[ "$FORCE_WATCHDOG" -eq 0 ]] && command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
-}
-
 run_docker() {
   echo "caproom: docker cgroup backend, limit=${LIMIT_MB}m image=${IMAGE}" >&2
   exec docker run --rm -i \
@@ -143,26 +485,50 @@ run_docker() {
     -v "$PWD:/work" -w /work "$IMAGE" "$@"
 }
 
+collect_tree() {
+  # Snapshot ps once and walk the descendant tree of $1 into TREE_PIDS /
+  # TREE_RSS_KB (see read_snapshot / walk_tree). Plain indexed arrays only
+  # so macOS's stock bash 3.2 works.
+  read_snapshot
+  walk_tree "$1"
+}
+
 run_watchdog() {
-  echo "caproom: watchdog backend (docker unavailable), limit=${LIMIT_MB}m poll=${INTERVAL}s" >&2
+  echo "caproom: watchdog backend (host-native), limit=${LIMIT_MB}m poll=${INTERVAL}s (process-tree RSS)" >&2
   local limit_kb=$(( LIMIT_MB * 1024 ))
   "$@" &
   local pid=$!
   local exit_code=0
   while kill -0 "$pid" 2>/dev/null; do
-    local rss_kb
-    rss_kb=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ')
-    if [[ -n "$rss_kb" && "$rss_kb" -gt "$limit_kb" ]]; then
-      echo "caproom: pid $pid RSS ${rss_kb}KB exceeded ${limit_kb}KB cap — sending SIGTERM (grace ${GRACE}s)" >&2
-      kill -TERM "$pid" 2>/dev/null || true
+    collect_tree "$pid"
+    if [[ "${#TREE_PIDS[@]}" -gt 0 && "$TREE_RSS_KB" -gt "$limit_kb" ]]; then
+      local overshoot=$(( TREE_RSS_KB * 100 / limit_kb ))
+      echo "caproom: pid $pid tree RSS ${TREE_RSS_KB}KB exceeded ${limit_kb}KB cap (+${overshoot}%) — killing tree (grace ${GRACE}s)" >&2
+      # Signal EVERY pid in the tree, not just the root: children that
+      # survive a root-only TERM get orphaned and keep allocating past
+      # the cap after caproom exits.
+      kill -TERM "${TREE_PIDS[@]}" 2>/dev/null || true
+      local -a breach_pids=("${TREE_PIDS[@]}")
       local waited=0
       while kill -0 "$pid" 2>/dev/null && [[ "$waited" -lt "$GRACE" ]]; do
         sleep 1
         waited=$(( waited + 1 ))
       done
-      if kill -0 "$pid" 2>/dev/null; then
-        echo "caproom: pid $pid still alive after ${GRACE}s grace — SIGKILL" >&2
-        kill -9 "$pid" 2>/dev/null || true
+      # Escalate against anything that ignored TERM — root OR child.
+      # Scanning the breach-time snapshot (not re-walking from the root)
+      # also catches the case where the root died but a stubborn child
+      # survived it. Children spawned DURING the grace window are not in
+      # the snapshot; same accepted gap as detached daemons generally.
+      local sp sweep=0
+      for sp in "${breach_pids[@]}"; do
+        if kill -0 "$sp" 2>/dev/null; then
+          kill -9 "$sp" 2>/dev/null || true
+          sweep=$(( sweep + 1 ))
+        fi
+      done
+      if [[ "$sweep" -gt 0 ]]; then
+        echo "caproom: SIGKILLed ${sweep} survivor(s) after grace — exit 137" >&2
+        wait "$pid" 2>/dev/null || true
         exit 137
       fi
       wait "$pid" 2>/dev/null || exit_code=$?
@@ -175,8 +541,16 @@ run_watchdog() {
   exit "$exit_code"
 }
 
-if docker_available; then
-  run_docker "$@"
+if [[ "$USE_DOCKER" -eq 1 ]]; then
+  # Explicit opt-in must fail loudly rather than silently downgrade —
+  # the caller asked for a hard cap, a silent watchdog switch would
+  # quietly change the guarantee they asked for.
+  if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+    run_docker "$@"
+  else
+    echo "caproom: --docker requested but the docker daemon is not reachable" >&2
+    exit 1
+  fi
 else
   run_watchdog "$@"
 fi