caproom 0.7.5 → 0.9.2

package/README.md

@@ -7,226 +7,152 @@ Prevent RAM OOM for long-running terminal coding agents, builds, and background
 
 ## Why
 
-macOS has no reliable way to cap a process's memory from userspace. A runaway process — a leaking build tool, an AI agent stuck in a loop, a stray `find /` — has nothing standing between it and system OOM. `caproom` fills that gap with mechanisms that actually enforce a limit.
+macOS has no reliable way to cap a process's memory from userspace. A runaway process — a leaking build tool, an AI agent stuck in a loop, a stray `find /` — has nothing standing between it and system OOM. `caproom` fills that gap with a host-native polling watchdog that actually enforces a limit on the whole process tree.
 
-## What it does
+## What it does (Rust-only v0.9.0)
 
 ```
 caproom --limit <mb> -- <command> [args...]
+# or explicit subcommand
+caproom run --limit 2048 -- npm run build
 ```
 
-Two backends:
+Single binary `bin/caproom-rs` (`1.2M`, `target/release/caproom` copy) — no bash, no JS wrapper, no PowerShell shim. The 1K-line bash watchdog (`bin/caproom`), `bin/caproom.js`, `bin/caproom-mcp.js`, `bin/caproom.ps1`, `scripts/postinstall.js` were removed in `f017051` (0.8.1). Install via `cargo`, `brew`, or `npm` (npm unpacks prebuilt `caproom-darwin-arm64/x64`, `caproom-linux-x64`, `caproom-win32-x64.exe`).
 
-1. **Host-native polling watchdog** (`ps` RSS + `SIGKILL`) — the **default** on macOS/Linux. Runs in your real environment: same PATH, auth, native binaries, tty. Measures the **whole process tree** each poll (agents keep their memory in children — MCP servers, bundler daemons, headless browsers — while the parent's own RSS stays flat). Has a small race window bounded by `--interval` (default 200ms).
-2. **Docker cgroup** (`--memory`) — opt-in with `--docker`. Hard cap, real kernel enforcement, zero race window — at the cost of running inside a Linux container (see caveats below). Fails loudly if the daemon isn't reachable rather than silently switching backends.
+Core mechanism:
+
+- **Collector:** `proc_listallpids` + `proc_pidinfo PROC_PIDTBSDINFO/TASKINFO` + `proc_pid_rusage ri_phys_footprint` (libproc, not `ps`). Measures **phys_footprint** (Mach `TASK_VM_INFO`, Jetsam/Activity Monitor truth) — not RSS. RSS overcounts shared libs. R/S state comes from TASKINFO `pti_numrunning`, because `pbi_status` reports SRUN for processes blocked in `time.sleep`.
+- **Tree walk:** whole process tree per poll (agents keep memory in children — MCP servers, bundler daemons, headless browsers — while parent RSS stays flat). Ancestry walk depth 64, reparented to `launchd`/`init` (ppid 1) escapes.
+- **Parking predicate `is_idle_subtree`:** `still_in_tree` + `footprint >=512KB` + `!is_session_leader` (`pid == sid` primary, `pgid == pid` fallback — foreground group never parks) + `cpu_delta <0.02` (2% over 500ms window via `CpuRing` from `ri_user_time+ri_system_time` delta). Dropped `pbi_status S|I` gate in 0.8.0 — multithreaded Python/Node reports `R` while sleeping in `time.sleep`.
+- **Escalation:** park idle subtrees (`SIGSTOP`) → resample after 1s → only `TERM` → grace `5s` → `KILL` if still over `effective_limit`. `effective_limit = limit * (80 + 20*free_pct/15)/100` (free_pct from `vm_stat`/`MemAvailable`), so low headroom lowers trigger but doesn't escalate without park.
+- **Polling-only v1:** `vm_stat`/`free_mem_pct` every `200ms`. `dispatch_source_memorypressure` event-driven (`0% idle`) is **not built** — `pressure::try_init_pressure_source() -> false` and logs `poll fallback 200ms (dispatch unavailable, v1.1 daemon will use GCD source)`. Deferred to daemon v1.1 single Mach source.
+- **Docker backend dropped:** no `--docker`/`--image` in Rust (native only). `--pty`/`--no-intercept-tty`/`--force-watchdog`/`init`/`setup`/`SAFE_RUN` also dropped — they were bash-only.
 
 ## Install
 
 ```bash
+# from source (requires Rust stable)
+cargo install --locked --path crates/cli
+# or
+cargo install caproom  # once published to crates.io
+
+# Homebrew (tap exists, formula builds from source)
+brew tap intelogroup/caproom
+brew install caproom
+
+# npm (unpacks prebuilt binaries, no wrapper)
 npm install -g caproom
+# clean up old global npm shim if you migrated from bash
+npm rm -g caproom; nvm use system; hash -r; which caproom # should be ~/.cargo/bin/caproom
 ```
 
-or clone and symlink `bin/caproom` onto your `PATH`.
+Binary: `~/.cargo/bin/caproom` `v0.9.0`, `caproom --help` prints `Memory-cap any command — Rust CLI-first v1`.
 
 ## Usage
 
 ```bash
-# cap a build at 2GB (host-native watchdog, the default)
+# cap a build at 2GB
 caproom --limit 2048 -- npm run build
+caproom run --limit 2048 -- npm run build
 
 # cap an AI coding agent run at 512MB
 caproom --limit 512 -- claude -p "refactor this module"
 
-# opt in to the Docker cgroup backend for a zero-race hard cap
-caproom --limit 4096 --docker --image python:3.12-slim -- python train.py
+# inspect trees
+caproom freemem                # prints free %
+caproom top                    # human table sorted by TREE_MB
+caproom top --json             # machine schema 1
+caproom top --json --pid 45057 # one subtree
+caproom top --json --park-min-mb 1024
+
+# park / wake
+caproom park <pid>   # SIGSTOP — pages eligible for reclaim under pressure
+caproom wake <pid>   # SIGCONT
+caproom status <pid> # ps stat/rss
+
+# calibrate limit from current footprint (24GB->14G, 8GB->4G clamp)
+caproom calibrate
+caproom calibrate --duration 30
 ```
 
 ### Flags
 
 | Flag | Default | Meaning |
 |---|---|---|
-| `--limit <mb>` | `4096` | memory cap in MB |
+| `--limit <mb>` | `4096` | memory cap in MB (phys_footprint) |
 | `--interval <sec>` | `0.2` | watchdog poll interval |
-| `--grace <sec>` | `5` | seconds to wait after `SIGTERM` before `SIGKILL`, watchdog backend only — gives the process a chance to flush/save state before a hard kill |
-| `--docker` | off | opt in to the Docker cgroup backend instead of the default host-native watchdog |
-| `--image <name>` | `node:22-slim` | docker image used by the `--docker` backend |
-| `--force-watchdog` | — | legacy no-op; the watchdog IS the default. Accepted so existing scripts and `init` snippets keep working |
-| `--no-intercept-tty` | off | bypass stdio interposition for TUI/pty apps — `exec` directly and monitor via detached `watch --auto-park` (preserves `OSC 10/11`, `DSR CPR`, mouse `DEC 1003`) |
-| `--pty` | off | allocate a real pty via `forkpty` (`scripts/pty_wrapper.py` python or `script`) and forward bytes verbatim — full terminal fidelity, watchdog enforces cap on pty tree |
-| `--no-pty` | — | disable pty allocation (fallback to bypass/watchdog) |
-
-Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`, `CAPROOM_GRACE`, `CAPROOM_BYPASS_TTY=1` (force bypass), `CAPROOM_PTY=1` (force pty, same as `--pty`).
-
-On cap breach, the watchdog backend sends `SIGTERM` first and waits `--grace` seconds before `SIGKILL`. If the process exits cleanly during the grace window, `caproom` propagates its real exit code; only a hard `SIGKILL` (process ignored `SIGTERM`, or grace ran out) reports `137` (same convention as Docker's own OOM-kill exit code, which the docker backend always uses on breach since Docker itself sends the kill).
-
-## Backends compared
-
-The three enforcement mechanisms measure different quantities and cover children differently. Read this before reusing a `--limit` number across platforms or backends. The watchdog is the POSIX default; Docker is opt-in — caproom prefers to run your command unmodified in its real environment and *miss* an exotic memory spike over breaking a working workflow with container drift:
+| `--grace <sec>` | `5` | seconds to wait after `SIGTERM` before `SIGKILL` |
 
-| | Docker cgroup | Windows Job Object | Watchdog (POSIX) | Watchdog (Windows) |
-|---|---|---|---|---|
-| Measures | cgroup memory | **committed virtual memory** | RSS of the process tree | working set of the process tree |
-| Children counted | yes — whole container | yes — auto-inherited at spawn | yes — tree walked each poll | yes — tree walked each poll |
-| Enforcement | kernel OOM-kill | allocation fails in-process | TERM → grace → KILL | hard kill (`taskkill /T /F`) |
-| Race window | none | none | bounded by `--interval` | bounded by `--interval` |
-| Interactive/streaming output | degraded — no TTY (`-i` only) | full — streamed live | full — child inherits the tty | streamed live via temp-file tail-follow (~50ms cadence) |
+On breach: `SIGTERM` whole tree → wait `grace` → `SIGKILL` grace survivors from breach snapshot. Exit `143` if TERM honored, `137` if KILL (same as Docker OOM convention, but now native).
 
-**Committed vs RSS**: Node/V8 runtimes commit far more virtual memory than they touch, so a limit tuned against RSS on macOS will bite much earlier under the Job Object backend. Tune per platform.
+## Backends compared (POSIX)
 
-### Docker backend caveats
+| | Watchdog (bash 0.7.6) | Watchdog (Rust v1) | Watchdog (Windows) |
+|---|---|---|---|
+| Measures | RSS of tree | **phys_footprint** (`ri_phys_footprint`) | working set |
+| Children | tree walked each poll | libproc tree walked each poll | tree walked |
+| Enforcement | TERM → grace → KILL | TERM → grace → KILL | `taskkill /T /F` |
+| Race window | bounded by `interval` | bounded by `interval` (polling-only; event-driven deferred) | bounded |
+| Interactive | full tty | full tty | temp-file tail-follow (~50ms) |
 
-Opt in with `--docker`. The command then runs inside `node:22-slim` with `$PWD` mounted at `/work` — a Linux container, not your host shell:
+Rust is a faster polling loop with better metrics, not yet event-driven.
 
-- Native modules built for macOS (`esbuild`, `swc`, `sharp`) fail with exec-format errors inside the container.
-- Host toolchain, env vars, git credentials, and `~/.ssh` are not present.
-- The image pins Node 22 regardless of your project's version (`--image` to override).
-- No TTY is allocated, so interactive/TUI programs degrade; Docker Desktop's file-share layer slows large builds on macOS.
+## `caproom top` — process-tree inventory
 
-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
-
-For a command you always want capped (e.g. an AI coding agent), don't type the wrapper every time — bake it into your shell so a new terminal tab is capped automatically:
-
-```bash
-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.
-
-**TUI / pty note:** `caproom -- <TUI>` (opencode, claude, vim, htop, …) would break the pty — `OSC 10/11` (`^[]10;rgb:...`), `DSR CPR` (`^[[5;1R`), and mouse `^[[<35;` reports leak as text. Since 0.7.3, `caproom` detects `[ -t 0 ] && [ -t 1 ]` for known TUIs and **bypasses stdio interposition**: the TUI `exec`s directly and a detached `caproom watch --auto-park` monitors its pid tree (same cap, no pty corruption). For full pty fidelity, use `--pty` / `CAPROOM_PTY=1` which allocates a real pty via `forkpty` (`python3` `scripts/pty_wrapper.py` or `script`) and forwards bytes verbatim while the watchdog still enforces the cap on the pty tree. Piped/batch `caproom -- opencode run "task"` stays fully capped via the watchdog. Override: `CAPROOM_BYPASS_TTY=1` / `--no-intercept-tty` forces bypass, `CAPROOM_PTY=1` / `--pty` forces pty for any command. `caproom init <TUI>` prints a warning and emits the tty-aware wrapper.
-
-## setup / bind — shell integration for every terminal
-
-`caproom setup` binds headroom management to your shells at the **shell layer**, so it works in any terminal (Terminal.app, iTerm2, Ghostty, Windows Terminal) without touching terminal-specific config:
-
-```bash
-caproom setup                # bind zsh/bash + fish (Windows: PowerShell $PROFILE)
-caproom setup --uninstall    # remove rc markers; backups and integration files stay
-```
-
-What it does:
-
-- Writes one integration file per shell under `~/.caproom/` (`shell.sh`, `shell.fish`, `shell.ps1`) and adds a 3-line marker block (`# >>> caproom >>>`) to your rc files. Idempotent; timestamped `.bak` backups are made before first patch.
-- Adds a **headroom warning on every prompt** — once per minute, only when free memory drops below `CAPROOM_HEADROOM_WARN` percent (default 20). Never blocks, never modifies your prompt text.
-- Optional **auto-wrap**: `export CAPROOM_AUTO_WRAP="claude,codex,opencode"` in your rc creates `<cmd>_capped` twins that run through the watchdog with `CAPROOM_LIMIT_MB`. Bare command names are shadowed **only** if you also set `CAPROOM_AUTO_ALIAS=1` — caproom never hijacks an unwrapped command by default.
-- Optional login daemon: `caproom setup --guard --threshold 15` installs a LaunchAgent (macOS) or systemd user unit (Linux) running `caproom guard` across all terminals.
-
-npm install never touches your rc files — postinstall prints a hint, binding is always explicit. Undo any time: `caproom setup --uninstall`.
-
-### `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)
-```
+Read-only snapshot of every tree you own, sorted by tree footprint.
 
 ```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,
+    { "pid": 45057, "cmd": "node /tmp/hog.mjs", "tree_rss_kb": 455136, "footprint_kb": 455136,
+      "tree_pids": [45057, 45060], "state": "running", "reason_code": "PARK_IDLE|GROWTH_RATE|PRESSURE|NONE",
+      "growth_kb_s": 0, "free_pct": 33, "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.
+One row per tree root; `park_candidate` is heuristic (`state running` + sleeping + footprint ≥ threshold) with `reason` spelled out.
 
 ## 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:
-
-```bash
-caproom park <pid>     # SIGSTOP — process stays alive, keeps its PID and state,
-                        # just isn't scheduled. Its memory becomes eligible for
-                        # the kernel's own compressor once real system memory
-                        # pressure shows up.
-caproom wake <pid>      # SIGCONT — resumes instantly, same state, no restart.
-caproom status <pid>    # pid, state (T = parked, S = running), RSS, elapsed
 ```
-
-Verified empirically on macOS: a parked process's RSS dropped ~90% (345MB → 37MB) once real memory pressure hit, and resumed correctly and stayed responsive after `SIGCONT`. No reclaim happens while the system is idle/unpressured — this rides the kernel's own compressor, it doesn't force anything.
-
-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. 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>
+caproom park <pid>        # SIGSTOP — single PID, pages eligible for kernel compressor
+caproom park-tree <pid>   # SIGSTOP whole tree (recursive Tree::build) — PID reuse guarded (pid,start)
+caproom wake <pid>        # SIGCONT single
+caproom wake-tree <pid>   # SIGCONT whole tree
 ```
 
-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.
+Verified on macOS: parked RSS dropped `~90%` (345MB → 37MB) once real pressure hit. No reclaim while system idle/unpressured — rides kernel compressor, doesn't force. **Caveat:** parked process does zero work while stopped — only park something actually idle (watcher, finished subprocess), never the process an agent is waiting on.
 
-Typical loop: `top --json` finds candidates → `watch --auto-park` babysits them during heavy builds → explicit or automatic wake restores them after.
+Predicate `is_idle_subtree` protects: `cpu_delta <0.02` (`CpuRing` 500ms window, first sample assumes busy `1.0` so active watcher not parked on first sight) and `is_session_leader` (`pid == sid` primary, `pgid == pid` fallback) never parks foreground. Tested with real `python3 -c "while True: pass"` busy vs `sleep` idle — `park_does_not_hang_active_watcher` proves.
 
-## MCP server — native agent access
+## `caproom calibrate` — suggest limit
 
-`npm i -g caproom` also installs `caproom-mcp`, a zero-dependency MCP server (stdio) exposing the agent interface as tools:
+Prints total RAM, free %, top 3 trees footprint, and `suggested --limit` (60% total, clamp 4G min / 80% max). Migration note `old RSS --limit 6144 ≈ footprint ~4.8G` (≈80% due shared overcount).
 
-```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
+## MCP — typed surface
 
-caproom only watches OS-level RSS and sends signals (`SIGTERM`/`SIGKILL`/`SIGSTOP`/`SIGCONT`). The watchdog backend runs the wrapped command as a direct child with stdin/stdout/stderr passed straight through — no pipe, no buffering, no interception. The Docker backend passes stdio through the same way (`docker run -i`). caproom never reads, modifies, or truncates anything the wrapped process reads or writes — including an AI agent's own conversation/context stream. It manages RAM headroom only, nothing else.
+`crates/caproom-mcp` is hand-rolled `serde` JSON with strictly typed enums (`state: parked|running|zombie`, `reason_code: PARK_IDLE|GROWTH_RATE|PRESSURE|NONE`), no `message` string. Tools v1 (8): `top`, `park`, `park_tree`, `wake`, `wake_tree`, `run`, `freemem`, `status`. Unknown tools return proper JSON-RPC error objects (`-32601`). `watch_*` + `rmcp` deferred to v1.1 with tokio isolated to MCP crate.
 
 ## Windows
 
-Windows uses a separate PowerShell backend, selected automatically. Same commands, but the semantics differ in three ways worth knowing before you reuse a `--limit` number across platforms.
-
-**The cap is a Job Object** (`JOB_OBJECT_LIMIT_PROCESS_MEMORY`), enforced by the kernel at allocation time. Two things it does better than the POSIX watchdog: there is no poll-interval race window, and child processes are covered automatically — a process associated with a job passes that association to anything it spawns, so the whole tree is capped, not just the direct child.
-
-**`--limit` means committed memory on Windows, RSS on macOS/Linux.** These are different quantities. The same number will bite at a different point, so tune it per platform rather than assuming it transfers.
-
-**No grace period.** Windows console apps have no `SIGTERM` equivalent. Under the Job Object backend nothing is killed at all — the allocation just fails inside the process. Under the watchdog fallback, a breach kills the whole tree (`taskkill /T /F`) with no chance to flush state. `--grace` is accepted and ignored.
+Same `run`/`top`/`park`/`wake` via `cfg(unix)`/`cfg(windows)` guards (`cargo check --target x86_64-pc-windows-msvc` passes). `park`/`wake` are stubs (`park not implemented on Windows`) — `EmptyWorkingSet` not wired in Rust v1. Windows watchdog `taskkill /T /F` for TERM/KILL, no grace, `--grace` ignored. No Job Object hard cap — Rust is watchdog-only.
 
-**Watchdog output streams, but through temp files.** stdout/stderr are captured to files and tail-followed (~50ms cadence) so logs and CI steps show progress live. Full-screen TUI redraws are not pixel-perfect over this path; plain streaming output (agents in non-interactive mode, builds) works normally.
+## Rust port status (current `main` 0.9.0)
 
-**`park` does not suspend on Windows.** It calls `EmptyWorkingSet`, which trims the process's working set to the pagefile immediately and on demand — no waiting for system memory pressure, and **the process keeps running**. The macOS caveat about never parking a process an agent is waiting on does not apply here. `caproom wake` is therefore a no-op on Windows; trimmed pages fault back in on next access.
-
-`init` emits a PowerShell function plus `Set-Alias` for your `$PROFILE`:
-
-```powershell
-caproom init claude --limit 6144 >> $PROFILE
-```
-
-Docker backend is not wired up on Windows — the Job Object path already gives kernel enforcement, so there is nothing for it to add.
+- ✅ `phys_footprint` via libproc, typed `top --json` with `growth_kb_s`/`reason_code`/`free_pct`
+- ✅ `is_idle_subtree` ancestry walk + `cpu_delta` (`CpuRing` first-sample busy) + `is_session_leader` (`pid==sid` + `pid==pgid` fallback) wired, `S|I` gate dropped, `28` tests incl. `park_does_not_hang_active_watcher`
+- ✅ R/S via TASKINFO `pti_numrunning` (`pbi_status` reports SRUN for sleepers); pid-list buffer grows past 8192 instead of silent truncation
+- ✅ `growth` contextual `should_enforce_growth` (70% + pressure + <5min breach, 600s for >1MB/s) not bare `>200 KB/s`; `pressure` cached `hw.memsize OnceLock` + `free 800ms/200ms`
+- ✅ `park-tree`/`wake-tree` tree-aware + `(pid,start_time)` reuse guard (`pbi_start` / `/proc/starttime` via `getsid`), `is_session_leader` fixes `Ghostty→tmux` conflation
+- ✅ MCP: 8 tools, invalid-pid guards (kill(0)/kill(1) rejected), park_tree reuse guard, JSON-RPC error objects, EPIPE-safe writes
+- ✅ `effective_limit = limit * (80 + 20*free_pct/15)/100` pressure-aware threshold
+- ❌ Not yet: `dispatch_source_memorypressure` event-driven (polling-only v1), `rmcp` port, daemon+arbiter. See `docs/plan-caproom-rust.md` for reality vs pitch.
 
 ## Limitations
 
-- 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, 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.)
-
-## Contributing
-
-Issues and PRs welcome at [github.com/intelogroup/caproom](https://github.com/intelogroup/caproom).
+- Watchdog has bounded `interval` race window; for hard guarantee use cgroups outside caproom (Docker dropped in Rust v1).
+- Tree walk follows live `ppid` edges. Daemonized double-fork reparented to 1 escapes by design — prefer missing outside lineage over interfering with user processes.
+- Parking only makes pages *eligible*; kernel compresses lazily under real pressure. Parking 2GB on idle machine may stay ~2GB for hours.
 
 ## License
 

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "caproom",
-  "version": "0.7.5",
-  "description": "Memory-cap any command (AI coding agents, builds, background jobs) on macOS, Linux, and Windows \u2014 real enforcement via Docker cgroups, Windows Job Objects, or a polling watchdog, plus park/wake to reclaim idle process memory without killing.",
+  "version": "0.9.2",
+  "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-mcp": "bin/caproom-mcp.js"
+    "caproom": "bin/caproom-rs",
+    "caproom-mcp": "bin/caproom-mcp"
   },
   "files": [
-    "bin/caproom",
-    "bin/caproom.js",
-    "bin/caproom.ps1",
-    "bin/caproom-mcp.js",
-    "scripts/postinstall.js",
-    "scripts/pty_wrapper.py"
+    "bin/caproom-rs",
+    "bin/caproom-rs.exe",
+    "prebuilt/*",
+    "scripts/pty_wrapper.py",
+    "bin/caproom-mcp",
+    "bin/caproom-mcp.exe"
   ],
   "keywords": [
     "memory",
@@ -30,9 +30,6 @@
     "linux",
     "win32"
   ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",