caproom 0.4.0 → 0.5.0

package/README.md

@@ -81,6 +81,8 @@ Opt in with `--docker`. The command then runs inside `node:22-slim` with `$PWD`
 
 For capping an AI agent session you want to *interact* with, use the default watchdog: same host environment, streaming output, no container drift. Reach for `--docker` when you need the zero-race kernel guarantee and the command is container-safe.
 
+Orphan safety differs too. The watchdog TERMs the whole measured tree and SIGKILLs grace-period survivors from a breach-time snapshot — but a process that detaches before being observed escapes. Inside the Docker backend, the kernel's cgroup OOM handling acts on every task in the container: nothing outlives it, though the OOM killer picks victims by badness (it may kill your hog rather than the whole container — either way the capped workload ends and `caproom` exits non-zero). The Windows Job Object kills the whole job atomically on breach.
+
 
 ## init — auto-cap a command on every launch
 
@@ -92,6 +94,31 @@ caproom init claude --limit 6144 --grace 10 >> ~/.zshrc && source ~/.zshrc
 
 This appends a shell function that wraps `claude` through the watchdog backend (host-native — no Docker isolation, so the wrapped command keeps its normal filesystem/auth/PATH access) and an alias so plain `claude` picks it up. Per-shell override without editing the rc file: `CAPROOM_LIMIT_MB=8192 claude ...`. Works for any command, not just `claude` — `caproom init npm --limit 2048` wraps `npm` the same way.
 
+### `caproom top` — process-tree inventory for agents
+
+Read-only snapshot of every process tree you own, sorted by tree RSS. `--json` output is a **stable contract**: `schema` version field, additive changes only.
+
+```bash
+caproom top                       # human table
+caproom top --json                # machine output
+caproom top --json --pid 45057    # one subtree only
+caproom top --json --park-min-mb 1024   # park-candidate threshold (default 512MB)
+```
+
+```json
+{ "schema": 1, "ts": 1755950000, "limit_mb_default": 4096,
+  "processes": [
+    { "pid": 45057,
+      "cmd": "node /tmp/hog.mjs",
+      "tree_rss_kb": 455136,
+      "tree_pids": [45057, 45060],
+      "state": "running" | "parked" | "zombie",
+      "park_candidate": true,
+      "reason": "root sleeping + tree_rss 455136KB >= 524288KB park threshold" } ] }
+```
+
+One row per **tree root**; members are listed in `tree_pids`. `park_candidate` is a heuristic (`state == running`, root sleeping/idle, tree RSS ≥ threshold) with the rule spelled out in `reason` so the agent never re-derives it — override freely using the raw fields. The intended loop: poll `top --json` → decide → `park <pid>` / `wake <pid>`. Note `park` makes pages *eligible* for reclaim; see the caveat under park/wake below before treating it as freed RAM.
+
 ## park / wake — reclaim idle memory without killing
 
 Long-running agent sessions accumulate subprocesses that go idle but stay resident — old file watchers, finished tool-call children, stale servers. Killing them loses state; leaving them wastes RAM. `caproom park` freezes instead:
@@ -109,7 +136,36 @@ Verified empirically on macOS: a parked process's RSS dropped ~90% (345MB → 37
 
 No daemon, no tracking file, no dependency — just `SIGSTOP`/`SIGCONT` wrapped in a CLI. Any script or agent can call `caproom park <pid>` / `caproom wake <pid>` directly.
 
-**Caveat**: a parked process does zero work while stopped — no CPU, no I/O, no timers firing. Only park something actually idle (a background watcher, a finished subprocess kept around for reuse) — never park the process an agent is actively waiting on a response from, or you'll hang the agent, not save it memory.
+**Caveat**: a parked process does zero work while stopped — no CPU, no I/O, no timers firing. Only park something actually idle (a background watcher, a finished subprocess kept around for reuse) — never park the process an agent is actively waiting on a response from, or you'll hang the agent, not save it memory. Also: SIGSTOP only makes pages *eligible* for reclaim — the kernel compresses/evicts them lazily under real memory pressure. Park an idle 2GB agent on a quiet machine and it may stay ~2GB resident for hours. Park is insurance against OOM, not immediate RAM return.
+
+### `caproom top` / `caproom watch` — agent interface
+
+`caproom top --json` (above) is read-only discovery with a stable schema. `caproom watch` turns it into a daemon:
+
+```bash
+# observer: report tree-RSS breaches, touch nothing
+caproom watch --threshold-mb 2000 --json <pid>
+
+# arm auto-park: freeze breaching trees (SIGSTOP every pid in the snapshot)
+caproom watch --threshold-mb 2000 --auto-park --json <pid>
+
+# also restore automatically when system free memory recovers
+caproom watch --threshold-mb 2000 --auto-park --auto-wake-free-pct 15 <pid>
+```
+
+Naming the pid IS the per-process opt-in — there is no system-wide mode, since stopping an unchosen process risks freezing it mid-write. Events are NDJSON on stdout (`started`, `breach`/`parked`, `recovered`, `woke`, `all-exited`). Auto-park freezes the whole measured tree, tracks exactly what *it* stopped, never re-parks within one breach episode (woken trees stay awake unless RSS drops back under threshold), and `--auto-wake-free-pct` undoes only watch's own parks.
+
+Typical loop: `top --json` finds candidates → `watch --auto-park` babysits them during heavy builds → explicit or automatic wake restores them after.
+
+## MCP server — native agent access
+
+`npm i -g caproom` also installs `caproom-mcp`, a zero-dependency MCP server (stdio) exposing the agent interface as tools:
+
+```json
+{ "mcpServers": { "caproom": { "command": "caproom-mcp" } } }
+```
+
+Tools: `top` (tree inventory, stable schema), `park`/`wake`, `watch_start`/`watch_events`/`watch_stop` (daemon lifecycle, NDJSON events), and `run` (execute a command under a cap, returns a KILLED-BY-CAP verdict at exit 137). Same gating as the CLI: watch requires explicit pids; auto-park is opt-in per watcher.
 
 ## What it never touches
 
@@ -141,7 +197,7 @@ Docker backend is not wired up on Windows — the Job Object path already gives
 
 - Docker backend mounts `$PWD` into the container at `/work` and runs there — paths outside `$PWD` aren't visible to the command.
 - Watchdog backends have a real (if small) race window; for a hard guarantee, opt into the Docker backend (`--docker`) on POSIX, or use the Job Object backend on Windows.
-- The watchdog's tree walk follows live parent→child edges. A child that *daemonizes* (double-fork, reparented to init/launchd) leaves the tree and escapes the cap — as does any process spawned after its parent chain broke. The Windows Job Object backend does not have this gap. This is a deliberate trade: caproom prefers to **miss** memory outside the tracked lineage rather than risk interfering with processes the user didn't ask it to manage.
+- The watchdog's tree walk follows live parent→child edges. A child that *daemonizes* (double-fork, reparented to init/launchd) leaves the tree and escapes the cap — as does any process spawned after its parent chain broke, or during the kill grace window. On breach the watchdog signals every pid in the measured tree and SIGKILLs survivors of the grace period from a breach-time snapshot, so children cannot outlive the root — but processes that detach *before* being observed are missed by design. The Windows Job Object backend does not have this gap. This is a deliberate trade: caproom prefers to **miss** memory outside the tracked lineage rather than risk interfering with processes the user didn't ask it to manage.
 - On Windows, `Get-CimInstance` per poll makes the watchdog heavier than a plain RSS read; keep `--interval` at 0.2s or above there.
 - On Windows, the Job Object holds only the wrapped command and its descendants — never caproom itself — so the full `--limit` reaches your workload. (Cost: a millisecond-scale window after spawn before assignment lands, where the child is not yet counted.)
 

package/bin/caproom

@@ -35,11 +35,12 @@ usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <co
   --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.
@@ -68,6 +69,8 @@ examples:
   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"
@@ -102,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() {
@@ -119,8 +122,272 @@ cmd_status() {
   ps -o pid,stat,rss,etime,command -p "$pid" 2>/dev/null || { echo "caproom: no such pid $pid" >&2; exit 1; }
 }
 
-mem_free_pct() {
-  if [[ "$(uname)" == "Darwin" ]]; then
+# ---- 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}')
@@ -180,6 +447,8 @@ 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 ;;
@@ -216,39 +485,12 @@ run_docker() {
     -v "$PWD:/work" -w /work "$IMAGE" "$@"
 }
 
-sum_tree_rss_kb() {
-  # Sum RSS across the whole descendant tree of $1. Agents keep their memory
-  # in children (MCP servers, bundler daemons, headless browsers) while the
-  # parent's own RSS stays flat — a top-pid-only check never fires on them.
-  # One ps snapshot per poll; BFS over pid->ppid edges. Plain indexed arrays
-  # only (no declare -A) so macOS's stock bash 3.2 works.
-  local root="$1"
-  local -a pids=() ppids=() kb=() queue=()
-  local pid ppid k total=0 cur i j
-  while read -r pid ppid k; do
-    [[ -n "$pid" ]] || continue
-    pids+=("$pid"); ppids+=("$ppid"); kb+=("$k")
-  done < <(ps -eo pid=,ppid=,rss=)
-
-  queue=("$root")
-  while [[ ${#queue[@]} -gt 0 ]]; do
-    cur="${queue[0]}"
-    if [[ ${#queue[@]} -gt 1 ]]; then queue=("${queue[@]:1}"); else queue=(); fi
-    for ((i = 0; i < ${#pids[@]}; i++)); do
-      if [[ "${pids[$i]}" == "$cur" && -n "${kb[$i]}" ]]; then
-        total=$(( total + kb[$i] ))
-        kb[$i]=""
-        for ((j = 0; j < ${#ppids[@]}; j++)); do
-          if [[ "${ppids[$j]}" == "$cur" ]]; then
-            queue+=("${pids[$j]}")
-            ppids[$j]=""
-          fi
-        done
-        break
-      fi
-    done
-  done
-  echo "$total"
+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() {
@@ -258,19 +500,35 @@ run_watchdog() {
   local pid=$!
   local exit_code=0
   while kill -0 "$pid" 2>/dev/null; do
-    local tree_kb
-    tree_kb=$(sum_tree_rss_kb "$pid")
-    if [[ -n "$tree_kb" && "$tree_kb" -gt "$limit_kb" ]]; then
-      echo "caproom: pid $pid tree RSS ${tree_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=$?

package/bin/caproom-mcp.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// caproom-mcp — MCP server wrapping the caproom CLI so coding agents can
+// discover, freeze, and restore memory-heavy process trees natively.
+//
+// Tools:
+//   top    {pid?, park_min_mb?}     read-only tree inventory (stable schema)
+//   park   {pid}                    SIGSTOP an idle tree's root
+//   wake   {pid}                    SIGCONT it back
+//   watch_start  {pids[], threshold_mb?, auto_park?, auto_wake_free_pct?, interval?}
+//   watch_events {id}               drain NDJSON events from a running watcher
+//   watch_stop   {id}
+//   run    {command[], limit_mb?, grace?, image?, docker?}
+//                  cap a command end-to-end; returns exit code + stderr tail
+//
+// Hand-rolled MCP stdio transport (newline-delimited JSON-RPC 2.0): zero
+// dependencies, same rule as the CLI itself.
+
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
+const os = require('os');
+const path = require('path');
+
+const CAPROOM = path.join(__dirname, process.platform === 'win32' ? 'caproom.ps1' : 'caproom');
+if (process.platform !== 'win32') {
+  try { require('fs').chmodSync(CAPROOM, 0o755); } catch (_) { /* already exec */ }
+}
+
+const watchers = new Map();
+let watcherSeq = 0;
+
+function caproom(args, opts = {}) {
+  const exe = process.platform === 'win32' ? 'powershell.exe' : 'bash';
+  const argv = process.platform === 'win32' ? ['-NoProfile', '-File', CAPROOM].concat(args) : [CAPROOM].concat(args);
+  return spawnSync(exe, argv, { encoding: 'utf8', timeout: opts.timeout || 30000 });
+}
+
+function text(s) {
+  return { content: [{ type: 'text', text: String(s) }] };
+}
+
+function startWatcher(p) {
+  const id = 'w' + (++watcherSeq);
+  const args = ['watch', '--json'];
+  if (p.threshold_mb != null) args.push('--threshold-mb', String(p.threshold_mb));
+  if (p.interval != null) args.push('--interval', String(p.interval));
+  if (p.auto_park) args.push('--auto-park');
+  if (p.auto_wake_free_pct != null) args.push('--auto-wake-free-pct', String(p.auto_wake_free_pct));
+  const pids = Array.isArray(p.pids) ? p.pids : [];
+  if (!pids.length) throw new Error('pids[] required');
+  for (const x of pids) args.push(String(x));
+
+  const exe = process.platform === 'win32' ? 'powershell.exe' : 'bash';
+  const argv = process.platform === 'win32' ? ['-NoProfile', '-File', CAPROOM].concat(args) : [CAPROOM].concat(args);
+  const child = spawn(exe, argv, { stdio: ['ignore', 'pipe', 'pipe'], detached: false });
+  const rec = {
+    id, child, pids,
+    events: [], buf: '', stderr: [],
+  };
+  child.stdout.on('data', d => {
+    rec.buf += d.toString();
+    let i;
+    while ((i = rec.buf.indexOf('\n')) >= 0) {
+      const line = rec.buf.slice(0, i).trim();
+      rec.buf = rec.buf.slice(i + 1);
+      if (!line) continue;
+      try { rec.events.push(JSON.parse(line)); } catch (_) { /* partial */ }
+      if (rec.events.length > 1000) rec.events.splice(0, rec.events.length - 1000);
+    }
+  });
+  child.stderr.on('data', d => {
+    rec.stderr.push(d.toString());
+    if (rec.stderr.length > 50) rec.stderr.splice(0, rec.stderr.length - 50);
+  });
+  child.on('exit', () => { rec.exited = true; });
+  watchers.set(id, rec);
+  return { id, pids };
+}
+
+function drainWatcher(id, clear) {
+  const rec = watchers.get(id);
+  if (!rec) throw new Error('unknown watcher id: ' + id);
+  const out = rec.events.slice();
+  if (clear) rec.events = [];
+  return { events: out, exited: !!rec.exited, stderr_tail: rec.stderr.join('').slice(-2000) };
+}
+
+function stopWatcher(id) {
+  const rec = watchers.get(id);
+  if (!rec) throw new Error('unknown watcher id: ' + id);
+  if (!rec.exited) {
+    try { rec.child.kill(process.platform === 'win32' ? undefined : 'SIGTERM'); } catch (_) {}
+  }
+  const out = drainWatcher(id, true);
+  watchers.delete(id);
+  return out;
+}
+
+function callTool(name, args) {
+  switch (name) {
+    case 'top': {
+      const a = ['top', '--json'];
+      if (args.pid != null) a.push('--pid', String(args.pid));
+      if (args.park_min_mb != null) a.push('--park-min-mb', String(args.park_min_mb));
+      const r = caproom(a);
+      if (r.status !== 0) return text(r.stderr || 'top failed');
+      return text(r.stdout.trim());
+    }
+    case 'park':
+    case 'wake': {
+      if (args.pid == null) return text('pid required');
+      const r = caproom([name, String(args.pid)]);
+      return text((r.stderr || '').trim() + (r.status === 0 ? '' : `\nexit=${r.status}`));
+    }
+    case 'watch_start': {
+      const { id, pids } = startWatcher(args);
+      return text(JSON.stringify({ id, pids, note: 'poll watch_events{ id } to drain NDJSON events' }));
+    }
+    case 'watch_events': {
+      return text(JSON.stringify(drainWatcher(String(args.id), args.clear !== false)));
+    }
+    case 'watch_stop': {
+      return text(JSON.stringify(stopWatcher(String(args.id))));
+    }
+    case 'run': {
+      const cmd = Array.isArray(args.command) ? args.command : null;
+      if (!cmd || !cmd.length) return text('command[] required');
+      const a = [];
+      a.push('--limit', String(args.limit_mb != null ? args.limit_mb : 4096));
+      if (args.grace != null) a.push('--grace', String(args.grace));
+      if (args.docker) { a.push('--docker'); if (args.image) a.push('--image', String(args.image)); }
+      a.push('--');
+      const r = caproom(a.concat(cmd), { timeout: Math.max(60000, (args.timeout_ms || 300000)) });
+      let verdict = '';
+      if (r.status === 137 || r.signal === 'SIGKILL') verdict = 'RESULT: KILLED BY CAP (exit 137)';
+      else if (r.status === 143 || r.signal === 'SIGTERM') verdict = 'RESULT: terminated during grace (SIGTERM honored)';
+      else verdict = 'RESULT: exit=' + r.status;
+      return text(verdict + '\n--- stderr ---\n' + ((r.stderr || '').slice(-4000) || '(empty)'));
+    }
+    default:
+      throw new Error('unknown tool: ' + name);
+  }
+}
+
+const TOOLS = [
+  {
+    name: 'top',
+    description: 'Snapshot every process tree you own, sorted by tree RSS. Read-only. Returns caproom\'s stable schema-1 JSON: rows are tree roots with cmd, tree_rss_kb, tree_pids (blast radius), state (running|parked|zombie), park_candidate + reason heuristic.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pid: { type: 'number', description: 'restrict to one subtree' },
+        park_min_mb: { type: 'number', description: 'park-candidate threshold in MB (default 512)' },
+      },
+    },
+  },
+  {
+    name: 'park',
+    description: 'SIGSTOP an idle process (and only its root — use watch auto_park for whole trees). Pages become eligible for lazy kernel reclaim under pressure; not immediate RAM return. Only park genuinely idle processes — never one an agent awaits a reply from.',
+    inputSchema: { type: 'object', properties: { pid: { type: 'number' } }, required: ['pid'] },
+  },
+  {
+    name: 'wake',
+    description: 'SIGCONT a parked process back to life, same state, same PID.',
+    inputSchema: { type: 'object', properties: { pid: { type: 'number' } }, required: ['pid'] },
+  },
+  {
+    name: 'watch_start',
+    description: 'Start a caproom watch daemon on explicit pids. Naming pids is the opt-in; there is no system-wide mode. Emits NDJSON events (started/breach/parked/recovered/woke/all-exited). auto_park freezes whole breaching trees; auto_wake_free_pct restores its own parks when free memory recovers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pids: { type: 'array', items: { type: 'number' }, description: 'explicit pids to watch' },
+        threshold_mb: { type: 'number', description: 'per-tree breach threshold (default 2048)' },
+        auto_park: { type: 'boolean' },
+        auto_wake_free_pct: { type: 'number' },
+        interval: { type: 'number', description: 'poll seconds (default 5)' },
+      },
+      required: ['pids'],
+    },
+  },
+  {
+    name: 'watch_events',
+    description: 'Drain accumulated NDJSON events from a watcher (clears them unless clear=false). Also reports whether the watcher exited.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' }, clear: { type: 'boolean' } }, required: ['id'] },
+  },
+  {
+    name: 'watch_stop',
+    description: 'Stop a watcher and return its final drained events.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
+  {
+    name: 'run',
+    description: 'Run a command under a caproom memory cap (default watchdog backend; docker:true opts into the container cgroup backend). Kills the whole tree on breach. Returns verdict line (KILLED BY CAP at exit 137) plus captured stderr.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'array', items: { type: 'string' }, description: 'argv, e.g. ["npm","run","build"]' },
+        limit_mb: { type: 'number' },
+        grace: { type: 'number', description: 'seconds between SIGTERM and SIGKILL (default 5)' },
+        docker: { type: 'boolean' },
+        image: { type: 'string' },
+        timeout_ms: { type: 'number', description: 'default 300000' },
+      },
+      required: ['command'],
+    },
+  },
+];
+
+process.stdin.setEncoding('utf8');
+let inbuf = '';
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+function handle(msg) {
+  if (msg.method === 'initialize') {
+    send({
+      jsonrpc: '2.0', id: msg.id,
+      result: {
+        protocolVersion: msg.params && msg.params.protocolVersion || '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'caproom-mcp', version: require('../package.json').version },
+      },
+    });
+  } else if (msg.method === 'tools/list') {
+    send({ jsonrpc: '2.0', id: msg.id, result: { tools: TOOLS } });
+  } else if (msg.method === 'tools/call') {
+    const { name, arguments: args } = msg.params || {};
+    try {
+      const res = callTool(name, args || {});
+      send({ jsonrpc: '2.0', id: msg.id, result: res });
+    } catch (e) {
+      send({ jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: 'error: ' + e.message }], isError: true } });
+    }
+  } else if (msg.method === 'ping') {
+    send({ jsonrpc: '2.0', id: msg.id, result: {} });
+  } else if (msg.id !== undefined) {
+    send({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'method not found: ' + msg.method } });
+  }
+  // notifications (initialized, etc.) get no reply
+}
+
+process.stdin.on('data', chunk => {
+  inbuf += chunk;
+  let i;
+  while ((i = inbuf.indexOf('\n')) >= 0) {
+    const line = inbuf.slice(0, i).trim();
+    inbuf = inbuf.slice(i + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    try { handle(msg); } catch (e) {
+      if (msg && msg.id !== undefined) {
+        send({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e.message || e) } });
+      }
+    }
+  }
+});
+
+process.on('disconnect', () => {
+  for (const id of Array.from(watchers.keys())) stopWatcher(id);
+});

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "caproom",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Memory-cap any command (AI coding agents, builds, background jobs) on macOS, Linux, and Windows — real enforcement via Docker cgroups, Windows Job Objects, or a polling watchdog, plus park/wake to reclaim idle process memory without killing.",
   "bin": {
-    "caproom": "bin/caproom.js"
+    "caproom": "bin/caproom.js",
+    "caproom-mcp": "bin/caproom-mcp.js"
   },
   "files": [
     "bin/caproom",
     "bin/caproom.js",
-    "bin/caproom.ps1"
+    "bin/caproom.ps1",
+    "bin/caproom-mcp.js"
   ],
   "keywords": [
     "memory",