caproom 0.7.6 → 0.9.2

package/bin/caproom

@@ -1,1025 +0,0 @@
-#!/usr/bin/env bash
-# caproom — memory-cap any command (AI coding agents, builds, background jobs)
-# 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. 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() {
-  local stream=/dev/stderr
-  local code=1
-  if [[ "${1:-}" == "help" ]]; then stream=/dev/stdout; code=0; fi
-  cat >"$stream" << 'EOF'
-usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <command> [args...]
-       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)
-  --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
-  --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
-  --no-intercept-tty bypass stdio interposition for TUI/pty apps (OSC 10/11,
-                    DSR CPR, mouse DEC 1003) — exec directly and monitor via
-                    detached 'caproom watch --auto-park' instead
-  --pty            allocate a pty (forkpty) and forward bytes verbatim — full
-                    terminal fidelity for TUI (requires python3 or script)
-                    implies --no-intercept-tty + pty watchdog on the pty
-                    tree; fallback to bypass if pty alloc fails
-  --no-pty         disable pty allocation (use bypass or watchdog)
-
-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):
-
-  caproom init claude >> ~/.zshrc && source ~/.zshrc
-
-env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL, CAPROOM_GRACE, CAPROOM_BYPASS_TTY=1, CAPROOM_PTY=1
-
-TUI note: 'caproom -- <TUI>' (opencode, vim, htop, ...) bypasses stdio when [ -t 0 ] && [ -t 1 ]
-so terminal queries (OSC, mouse) stay on the pty. The cap is then advisory via a detached
-'caproom watch --auto-park' monitor, or via '--pty' which allocates a real pty (forkpty)
-and forwards bytes verbatim (python3 or script). Piped/batch 'caproom -- opencode run "task"'
-stays fully capped. Use --no-intercept-tty / CAPROOM_BYPASS_TTY=1 to force bypass, --pty /
-CAPROOM_PTY=1 to force pty.
-
-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 setup [--guard] [--threshold <pct>] [--uninstall]
-  caproom freemem
-  caproom init claude --limit 6144 --grace 10
-EOF
-  exit "$code"
-}
-
-cmd_init() {
-  local target="${1:-}"
-  [[ -z "$target" ]] && { echo "usage: caproom init <command> [--limit <mb>] [--grace <sec>]" >&2; exit 1; }
-  shift
-  local limit=4096
-  local grace=5
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --limit) limit="$2"; shift 2 ;;
-      --grace) grace="$2"; shift 2 ;;
-      *) echo "caproom: unknown init flag $1" >&2; exit 1 ;;
-    esac
-  done
-  local fn="${target}_capped"
-  local is_tui=0
-  case "$target" in
-    opencode|claude|codex|vim|nvim|htop|less|fzf|nano|emacs) is_tui=1 ;;
-  esac
-  if [[ $is_tui -eq 1 ]]; then
-    echo "caproom: warning: '$target' is a TUI — interactive tty runs will bypass stdio and use a detached 'caproom watch --auto-park' monitor to preserve pty (OSC 10/11, DSR CPR, mouse DEC 1003). Batch 'caproom -- $target run' stays fully capped. Set CAPROOM_BYPASS_TTY=1 to always bypass, or CAPROOM_BYPASS_TTY=0 + re-init to force legacy pipe mode." >&2
-    cat << EOF
-# caproom: auto-cap '$target' — added by 'caproom init $target'
-# override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
-# TUI note: when [ -t 0 ] && [ -t 1 ], '$target' runs directly and a detached 'caproom watch --auto-park' monitors it
-# (preserves OSC 10/11, DSR CPR, mouse DEC 1003). Batch/headless (piped) still goes through the watchdog.
-# Set CAPROOM_BYPASS_TTY=1 to always bypass, 0 to force legacy mode.
-$fn() {
-  if [ "\${CAPROOM_BYPASS_TTY:-0}" = "1" ]; then
-    command caproom --no-intercept-tty --limit "\${CAPROOM_LIMIT_MB:-$limit}" --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
-    return \$?
-  fi
-  if [ -t 0 ] && [ -t 1 ]; then
-    command $target "\$@" &
-    local _cap_pid=\$!
-    command caproom watch --threshold-mb "\${CAPROOM_LIMIT_MB:-$limit}" --interval "\${CAPROOM_INTERVAL:-0.2}" --auto-park --json "\$_cap_pid" >/dev/null 2>&1 &
-    wait "\$_cap_pid"
-    return \$?
-  fi
-  command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
-}
-alias $target=$fn
-EOF
-  else
-    cat << EOF
-# caproom: auto-cap '$target' — added by 'caproom init $target'
-# override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
-$fn() {
-  if [ "\${CAPROOM_BYPASS_TTY:-0}" = "1" ]; then
-    command caproom --no-intercept-tty --limit "\${CAPROOM_LIMIT_MB:-$limit}" --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
-    return \$?
-  fi
-  command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
-}
-alias $target=$fn
-EOF
-  fi
-}
-
-cmd_park() {
-  local pid="${1:-}"
-  [[ -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) — 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() {
-  local pid="${1:-}"
-  [[ -z "$pid" ]] && { echo "usage: caproom wake <pid>" >&2; exit 1; }
-  kill -0 "$pid" 2>/dev/null || { echo "caproom: no such pid $pid" >&2; exit 1; }
-  kill -CONT "$pid"
-  echo "caproom: pid $pid woken (SIGCONT)" >&2
-}
-
-cmd_status() {
-  local pid="${1:-}"
-  [[ -z "$pid" ]] && { echo "usage: caproom status <pid>" >&2; exit 1; }
-  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
-}
-
-# ---- terminal bind: setup / unbind ------------------------------------
-# Binds headroom management to every interactive shell in ANY terminal
-# (Terminal.app, iTerm2, Ghostty, ...) by writing ONE integration file
-# per shell under ~/.caproom/ and marker-patching the rc files. Idempotent,
-# backed up, reversible with `caproom unbind`. Never runs automatically:
-# npm postinstall only prints a hint.
-
-CAPROOM_DIR="${CAPROOM_DIR:-$HOME/.caproom}"
-
-setup_shell_sh() {
-  cat > "$CAPROOM_DIR/shell.sh" << 'EOF'
-# caproom shell integration — regenerated by `caproom setup`; edits here
-# are overwritten. Source of truth: bin/caproom (setup_shell_sh).
-
-caproom_freemem_pct() { command caproom freemem 2>/dev/null; }
-
-caproom_headroom_check() {
-  local pct last now
-  pct=$(caproom_freemem_pct) || return 0
-  [ -n "$pct" ] || return 0
-  [ "$pct" -lt "${CAPROOM_HEADROOM_WARN:-20}" ] || return 0
-  last=$(cat "${TMPDIR:-/tmp}/caproom-headroom-last" 2>/dev/null || echo 0)
-  now=$(date +%s)
-  [ $(( now - ${last:-0} )) -ge 60 ] || return 0
-  echo "$now" > "${TMPDIR:-/tmp}/caproom-headroom-last" 2>/dev/null
-  echo "caproom: headroom low (${pct}% free) — check 'caproom top' before launching heavy work"
-}
-
-if [ -n "$ZSH_VERSION" ]; then
-  autoload -Uz add-zsh-hook
-  add-zsh-hook precmd caproom_headroom_check
-elif [ -n "$BASH_VERSION" ]; then
-  case ";$PROMPT_COMMAND;" in
-    *caproom_headroom_check*) ;;
-    *) PROMPT_COMMAND="caproom_headroom_check${PROMPT_COMMAND:+;$PROMPT_COMMAND}" ;;
-  esac
-fi
-
-# Opt-in auto-wrap: CAPROOM_AUTO_WRAP="claude,codex,opencode" gives every
-# listed command a <name>_capped twin running under $CAPROOM_LIMIT_MB.
-# The bare name is aliased ONLY with CAPROOM_AUTO_ALIAS=1 — never hijack a
-# command the user did not consent to wrap.
-if [ -n "${CAPROOM_AUTO_WRAP:-}" ]; then
-  for _cr_cmd in $(echo "${CAPROOM_AUTO_WRAP}" | tr ',' ' '); do
-    _cr_fn="$(printf '%s' "$_cr_cmd" | sed 's/[-.]/_/g')_capped"
-    eval "$(printf "%s() { command caproom --limit \"\${CAPROOM_LIMIT_MB:-4096}\" --grace \"\${CAPROOM_GRACE:-5}\" -- '%s' \"\$@\"; }" "$_cr_fn" "$(printf '%s' "$_cr_cmd" | sed "s/'/'\\\\''/g")")"
-    if [ "${CAPROOM_AUTO_ALIAS:-0}" = "1" ]; then
-      alias "$_cr_cmd=$_cr_fn"
-    fi
-  done
-  unset _cr_cmd _cr_fn
-fi
-EOF
-}
-
-setup_shell_fish() {
-  cat > "$CAPROOM_DIR/shell.fish" << 'EOF'
-# caproom fish integration — regenerated by `caproom setup`.
-function __caproom_freemem
-    command caproom freemem 2>/dev/null
-end
-
-function __caproom_headroom_check --on-event fish_prompt
-    set -l pct (__caproom_freemem)
-    or return
-    test -n "$pct"; or return
-    set -l warn 20
-    if set -q CAPROOM_HEADROOM_WARN
-        set warn $CAPROOM_HEADROOM_WARN
-    end
-    if test "$pct" -lt "$warn"
-        set -l stamp /tmp/caproom-headroom-last
-        set -l now (date +%s)
-        set -l last 0
-        if test -f $stamp
-            set last (cat $stamp)
-        end
-        if test (math "$now - $last") -ge 60
-            echo $now > $stamp
-            echo "caproom: headroom low ($pct% free) — check 'caproom top' before launching heavy work"
-        end
-    end
-end
-EOF
-}
-
-setup_shell_ps1() {
-  cat > "$CAPROOM_DIR/shell.ps1" << 'EOF'
-# caproom PowerShell integration — regenerated by `caproom setup` (Windows).
-function global:caproom_freemem_pct {
-    $os = Get-CimInstance Win32_OperatingSystem
-    [int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize)
-}
-$global:__caproomLastWarn = 0
-function global:prompt {
-    $pct = caproom_freemem_pct
-    $now = [DateTimeOffset]::Now.ToUnixTimeSeconds()
-    if ($pct -lt (${CAPROOM_HEADROOM_WARN:-20}) -and ($now - $script:__caproomLastWarn) -ge 60) {
-        $script:__caproomLastWarn = $now
-        Write-Host "caproom: headroom low ($pct% free) — check 'caproom top' before launching heavy work" -ForegroundColor Yellow
-    }
-    "PS $($executionContext.SessionState.Path.CurrentLocation)> "
-}
-EOF
-}
-
-rc_targets() {
-  # Prints "path<TAB>required" pairs for every rc we manage. Only rcs that
-  # already exist are patched, EXCEPT the login shell's own rc which is
-  # created if missing — never invent configs for shells you don't use.
-  local zshrc="${ZDOTDIR:-$HOME/.zshrc}"
-  printf '%s\t%s\n' "$zshrc" "shell"
-  [[ -f "$HOME/.bashrc" ]] && printf '%s\t%s\n' "$HOME/.bashrc" "optional"
-}
-
-patch_rc_file() {
-  local rc="$1"
-  [[ -f "$rc" ]] || touch "$rc"
-  grep -q "# >>> caproom >>>" "$rc" && return 0
-  cp "$rc" "$rc.caproom.bak.$(date +%Y%m%d%H%M%S)"
-  {
-    echo ""
-    echo "# >>> caproom >>>"
-    echo '[ -f ~/.caproom/shell.sh ] && source ~/.caproom/shell.sh'
-    echo "# <<< caproom <<<"
-  } >> "$rc"
-}
-
-patch_rc_file_fish() {
-  local rc="$HOME/.config/fish/config.fish"
-  mkdir -p "$(dirname "$rc")" 2>/dev/null
-  [[ -f "$rc" ]] || return 0   # don't invent fish config unless it exists
-  grep -q "# caproom (fish)" "$rc" && return 0
-  cp "$rc" "$rc.caproom.bak.$(date +%Y%m%d%H%M%S)"
-  {
-    echo ""
-    echo "# caproom (fish)"
-    echo '[ -f ~/.caproom/shell.fish ] && source ~/.caproom/shell.fish'
-  } >> "$rc"
-}
-
-install_guard_daemon() {
-  local threshold="$1"
-  local bin_path
-  bin_path=$(command -v caproom || true)
-  [[ -n "$bin_path" ]] || { echo "caproom setup: cannot resolve caproom binary for daemon" >&2; return 1; }
-  if [[ "$(uname)" == "Darwin" ]]; then
-    local plist="$HOME/Library/LaunchAgents/com.caproom.guard.plist"
-    mkdir -p "$HOME/Library/LaunchAgents"
-    cat > "$plist" << EOF
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0"><dict>
-  <key>Label</key><string>com.caproom.guard</string>
-  <key>ProgramArguments</key><array>
-    <string>/usr/bin/env</string><string>bash</string><string>$bin_path</string>
-    <string>guard</string><string>--threshold</string><string>$threshold</string><string>--interval</string><string>15</string>
-  </array>
-  <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
-</dict></plist>
-EOF
-    echo "caproom setup: guard daemon installed -> $plist"
-    echo "  load now:  launchctl load $plist"
-    echo "  unload:    launchctl unload $plist"
-  else
-    local unit="$HOME/.config/systemd/user/caproom-guard.service"
-    mkdir -p "$HOME/.config/systemd/user"
-    cat > "$unit" << EOF
-[Unit]
-Description=caproom memory guard
-
-[Service]
-ExecStart=/usr/bin/env bash $bin_path guard --threshold $threshold --interval 15
-Restart=on-failure
-
-[Install]
-WantedBy=default.target
-EOF
-    echo "caproom setup: guard service installed -> $unit"
-    echo "  start now: systemctl --user enable --now caproom-guard.service"
-    echo "  stop:      systemctl --user disable --now caproom-guard.service"
-  fi
-}
-
-cmd_setup() {
-  local guard="" threshold=10 do_unbind=0
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --guard) guard="$threshold"; shift ;;
-      --threshold) threshold="$2"; shift 2 ;;
-      --uninstall|--unbind) do_unbind=1; shift ;;
-      *) echo "caproom setup: unknown option $1" >&2; exit 1 ;;
-    esac
-  done
-
-  if [[ "$do_unbind" -eq 1 ]]; then
-    local rc removed=0
-    while IFS=$'\t' read -r rc _req; do
-      [[ -f "$rc" ]] || continue
-      if grep -q "# >>> caproom >>>" "$rc"; then
-        awk '/^# >>> caproom >>>$/{skip=1;next} /^# <<< caproom <<<$/{skip=0;next} !skip' "$rc" > "$rc.cr.tmp" && mv "$rc.cr.tmp" "$rc"
-        removed=$(( removed + 1 ))
-      fi
-    done < <(rc_targets)
-    if grep -q "# caproom (fish)" "$HOME/.config/fish/config.fish" 2>/dev/null; then
-      awk '/^# caproom \(fish\)$/{getline; skip=1; next} !skip' "$HOME/.config/fish/config.fish" > /tmp/cr-fish.tmp 2>/dev/null \
-        && mv /tmp/cr-fish.tmp "$HOME/.config/fish/config.fish"
-      removed=$(( removed + 1 ))
-    fi
-    echo "caproom unbind: markers removed from $removed file(s); backups kept as *.caproom.bak.*"
-    echo "  integration files left in $CAPROOM_DIR (rm -rf to purge)"
-    return 0
-  fi
-
-  mkdir -p "$CAPROOM_DIR"
-  setup_shell_sh
-  setup_shell_fish
-  [[ "$(uname)" != "Darwin" ]] || setup_shell_ps1
-
-  local rc req patched=0
-  while IFS=$'\t' read -r rc req; do
-    if patch_rc_file "$rc"; then patched=$(( patched + 1 )); fi
-  done < <(rc_targets)
-  patch_rc_file_fish
-
-  echo "caproom setup: bound to your shells via $CAPROOM_DIR/"
-  echo "  shell.sh  zsh + bash (headroom warning on every prompt, opt-in auto-wrap)"
-  echo "  shell.fish  fish equivalent"
-  echo "  patched rc files: $patched (backups alongside as *.caproom.bak.*)"
-  echo ""
-  echo "auto-wrap usage:"
-  echo '  export CAPROOM_AUTO_WRAP="claude,codex,opencode"   # creates <cmd>_capped twins'
-  echo '  export CAPROOM_AUTO_ALIAS=1                        # ALSO shadow bare names (explicit consent)'
-  echo "  export CAPROOM_LIMIT_MB=8192                       # per-shell budget"
-  echo ""
-  echo "new terminals pick this up immediately; current ones: source ~/.caproom/shell.sh"
-
-  if [[ -n "$guard" ]]; then
-    echo ""
-    install_guard_daemon "$threshold"
-  fi
-}
-case "${1:-}" in
-  park) shift; cmd_park "$@"; exit 0 ;;
-  wake) shift; cmd_wake "$@"; exit 0 ;;
-  freemem) mem_free_pct; exit 0 ;;
-  setup|bind|unbind) shift; cmd_setup "$@"; 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
-
-LIMIT_MB="${CAPROOM_LIMIT_MB:-4096}"
-IMAGE="${CAPROOM_IMAGE:-node:22-slim}"
-INTERVAL="${CAPROOM_INTERVAL:-0.2}"
-GRACE="${CAPROOM_GRACE:-5}"
-USE_DOCKER=0
-BYPASS_TTY=0
-USE_PTY=0
-[[ "${CAPROOM_BYPASS_TTY:-0}" == "1" ]] && BYPASS_TTY=1
-[[ "${CAPROOM_PTY:-0}" == "1" ]] && USE_PTY=1
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --limit) LIMIT_MB="$2"; shift 2 ;;
-    --image) IMAGE="$2"; shift 2 ;;
-    --interval) INTERVAL="$2"; shift 2 ;;
-    --grace) GRACE="$2"; shift 2 ;;
-    --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 ;;
-    --no-intercept-tty) BYPASS_TTY=1; shift ;;
-    --pty) USE_PTY=1; shift ;;
-    --no-pty) USE_PTY=0; shift ;;
-    --) shift; break ;;
-    -h|--help) usage help ;;
-    *) break ;;
-  esac
-done
-
-[[ $# -eq 0 ]] && usage
-
-run_docker() {
-  echo "caproom: docker cgroup backend, limit=${LIMIT_MB}m image=${IMAGE}" >&2
-  exec docker run --rm -i \
-    --memory="${LIMIT_MB}m" --memory-swap="${LIMIT_MB}m" \
-    -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"
-}
-
-is_known_tui() {
-  case "${1##*/}" in
-    opencode|claude|codex|vim|nvim|htop|less|fzf|nano|emacs) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-SPAWN_PID=""
-spawn_with_pty() {
-  # Try python3 pty_wrapper.py, then script fallback. Sets SPAWN_PID on success.
-  local wrapper
-  wrapper="$(dirname "${BASH_SOURCE[0]:-$0}")/../scripts/pty_wrapper.py"
-  if [[ ! -f "$wrapper" ]]; then
-    local cap_path
-    cap_path="$(command -v caproom 2>/dev/null || echo "")"
-    if [[ -n "$cap_path" ]]; then
-      wrapper="$(dirname "$cap_path")/../scripts/pty_wrapper.py"
-      [[ ! -f "$wrapper" ]] && wrapper="$(dirname "$(dirname "$cap_path")")/scripts/pty_wrapper.py"
-    fi
-  fi
-  [[ ! -f "$wrapper" ]] && wrapper="$HOME/Developer/caproom/scripts/pty_wrapper.py"
-  if [[ -f "$wrapper" ]] && command -v python3 >/dev/null 2>&1 && python3 -c "import pty" 2>/dev/null; then
-    # Avoid stdout capture issue: run in a way that doesn't hold the caller's command-substitution pipe.
-    # Use a temp file to pass pid back if needed, but we set global.
-    python3 "$wrapper" "$@" &
-    SPAWN_PID=$!
-    return 0
-  fi
-  if command -v script >/dev/null 2>&1; then
-    if [[ "$(uname)" == "Darwin" ]]; then
-      script -q /dev/null "$@" &
-      SPAWN_PID=$!
-      return 0
-    else
-      local cmd
-      cmd=$(printf '%q ' "$@")
-      script -q -c "$cmd" /dev/null &
-      SPAWN_PID=$!
-      return 0
-    fi
-  fi
-  return 1
-}
-
-run_watchdog() {
-  # PTY mode: allocate a real pty (forkpty) and forward bytes verbatim.
-  # Full terminal fidelity — OSC 10/11, DSR CPR, mouse DEC 1003 all work
-  # because the TUI talks to a real pty, not a pipe. Watchdog still enforces
-  # the cap on the pty tree (same kill logic as normal).
-  if [[ "$USE_PTY" -eq 1 ]]; then
-    echo "caproom: pty mode — allocating pty via forkpty for '${1##*/}' (limit ${LIMIT_MB}m, verbatim forwarding)" >&2
-    stty -tostop 2>/dev/null || true
-    printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
-    local saved_stty=""
-    if [[ -t 0 ]]; then
-      saved_stty=$(stty -g </dev/tty 2>/dev/null || true)
-    fi
-    restore_pty() {
-      [[ -n "$saved_stty" ]] && stty "$saved_stty" </dev/tty 2>/dev/null \
-        || { [[ -t 0 ]] && stty sane </dev/tty 2>/dev/null || true; }
-      printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
-    }
-    local pty_pid
-    if spawn_with_pty "$@"; then
-      pty_pid=$SPAWN_PID
-      echo "caproom: pty allocated, pid $pty_pid — monitoring tree RSS" >&2
-      local limit_kb=$(( LIMIT_MB * 1024 ))
-      local exit_code=0
-      while kill -0 "$pty_pid" 2>/dev/null; do
-        collect_tree "$pty_pid"
-        if [[ "${#TREE_PIDS[@]}" -gt 0 && "$TREE_RSS_KB" -gt "$limit_kb" ]]; then
-          local overshoot=$(( TREE_RSS_KB * 100 / limit_kb ))
-          echo "caproom: pid $pty_pid tree RSS ${TREE_RSS_KB}KB exceeded ${limit_kb}KB cap (+${overshoot}%) — killing pty tree (grace ${GRACE}s)" >&2
-          kill -TERM "${TREE_PIDS[@]}" 2>/dev/null || true
-          local -a breach_pids=("${TREE_PIDS[@]}")
-          local waited=0
-          while kill -0 "$pty_pid" 2>/dev/null && [[ "$waited" -lt "$GRACE" ]]; do
-            sleep 1
-            waited=$(( waited + 1 ))
-          done
-          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 "$pty_pid" 2>/dev/null || true
-            restore_pty
-            exit 137
-          fi
-          wait "$pty_pid" 2>/dev/null || exit_code=$?
-          echo "caproom: pid $pty_pid exited cleanly (code $exit_code) during grace period" >&2
-          restore_pty
-          exit "$exit_code"
-        fi
-        sleep "$INTERVAL"
-      done
-      wait "$pty_pid" 2>/dev/null || exit_code=$?
-      restore_pty 2>/dev/null || true
-      exit "$exit_code"
-    else
-      echo "caproom: pty alloc failed — falling back to bypass/watchdog" >&2
-      restore_pty 2>/dev/null || true
-    fi
-  fi
-  # TUI bypass: if stdio is a tty and target is a known TUI (or bypass flag),
-  # don't sit on stdio — exec directly and monitor via detached watch.
-  # This preserves pty semantics (OSC 10/11, DSR CPR, DEC 1003 mouse) that
-  # break when a wrapper backgrounds the TUI and steals foreground pgrp.
-  if [[ "$BYPASS_TTY" -eq 1 ]] || { [[ -t 0 && -t 1 ]] && is_known_tui "${1:-}"; }; then
-    if [[ "$BYPASS_TTY" -eq 1 ]]; then
-      echo "caproom: bypass-tty active — exec directly, no stdio interposition (limit ${LIMIT_MB}m advisory via detached watch)" >&2
-    else
-      echo "caproom: tty TUI detected ('${1##*/}') — bypassing stdio interposition, monitoring via detached watch (limit ${LIMIT_MB}m)" >&2
-    fi
-    # Clean stale tty modes before handing off, same snapshot hygiene as
-    # the normal watchdog path but without taking foreground away.
-    stty -tostop 2>/dev/null || true
-    printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
-    # Detached watchdog monitors the TUI's pid tree without owning stdio.
-    # Resolve our own path (works via shim and direct invocation).
-    local _cap_bin="${BASH_SOURCE[0]:-$0}"
-    [[ "$_cap_bin" != /* ]] && _cap_bin="$PWD/$_cap_bin"
-    if [[ ! -f "$_cap_bin" ]]; then
-      _cap_bin="$(command -v caproom 2>/dev/null || echo "$_cap_bin")"
-    fi
-    set +m 2>/dev/null || true
-    "$@" &
-    local _tui_pid=$!
-    # Fire-and-forget watch; it exits when _tui_pid exits. Suppressed so it
-    # never leaks into the TUI's stdout. Threshold is the cap itself.
-    bash "$_cap_bin" watch --threshold-mb "$LIMIT_MB" --interval "$INTERVAL" --auto-park --json "$_tui_pid" >/dev/null 2>&1 &
-    local _watch_pid=$!
-    wait "$_tui_pid"
-    set -m 2>/dev/null || true
-    local _rc=$?
-    # Best-effort cleanup of the detached watcher (it should already exit
-    # via all-exited, but kill is cheap if TUI exited fast).
-    kill "$_watch_pid" 2>/dev/null || true
-    wait "$_watch_pid" 2>/dev/null || true
-    exit "$_rc"
-  fi
-  echo "caproom: watchdog backend (host-native), limit=${LIMIT_MB}m poll=${INTERVAL}s (process-tree RSS)" >&2
-  local limit_kb=$(( LIMIT_MB * 1024 ))
-  # Terminal hygiene: a TUI child (opencode, claude, ...) puts the tty in
-  # raw + mouse-tracking mode. If WE kill it, it never restores, and the
-  # user's shell then prints mouse reports like [[<35;25;15M as garbage.
-  # Clear stale state before snapshot — disable tostop to avoid SIGTTOU suspend
-  # when caproom backgrounds the TUI (ghostty reports [[<... as suspended tty output).
-  stty -tostop 2>/dev/null || true
-  printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
-  local saved_stty=""
-  if [[ -t 0 ]]; then
-    saved_stty=$(stty -g </dev/tty 2>/dev/null || true)
-  fi
-  restore_tty() {
-    # Only on OUR kill — a clean exit already restored its own state, and
-    # re-emitting resets there could clobber whatever the NEXT program drew.
-    [[ -n "$saved_stty" ]] && stty "$saved_stty" </dev/tty 2>/dev/null \
-      || { [[ -t 0 ]] && stty sane </dev/tty 2>/dev/null || true; }
-    printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
-  }
-  set +m 2>/dev/null || true
-  "$@" &
-  local pid=$!
-  local exit_code=0
-  while kill -0 "$pid" 2>/dev/null; do
-    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
-      # 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
-        restore_tty
-        exit 137
-      fi
-      wait "$pid" 2>/dev/null || exit_code=$?
-      echo "caproom: pid $pid exited cleanly (code $exit_code) during grace period" >&2
-      restore_tty
-      exit "$exit_code"
-    fi
-    sleep "$INTERVAL"
-  done
-  wait "$pid" || exit_code=$?
-  set -m 2>/dev/null || true
-  exit "$exit_code"
-}
-
-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