caproom 0.1.0 → 0.3.1

package/README.md

@@ -1,15 +1,13 @@
 # caproom
 
-Memory-cap any command — AI coding agents, builds, background jobs — on macOS/Linux.
+[![npm](https://img.shields.io/npm/v/caproom.svg)](https://www.npmjs.com/package/caproom)
+[![license](https://img.shields.io/npm/l/caproom.svg)](LICENSE)
 
-## Why
-
-macOS has no working per-process memory limit in userspace. Verified empirically:
+Prevent RAM OOM for long-running terminal coding agents, builds, and background jobs — memory caps plus idle-process parking, for macOS/Linux.
 
-- `setrlimit(RLIMIT_AS, ...)`, `RLIMIT_DATA`, `RLIMIT_RSS` all return `EINVAL` on modern macOS — the kernel rejects them outright, `ulimit -v` included.
-- launchd's own `HardResourceLimits.ResidentSetSize` is a no-op — a job capped at 100MB was observed running past 590MB, still `state = active`.
+## Why
 
-So a runaway process — a leaking build tool, an AI agent that gets stuck in a loop, a stray `find /` — has nothing standing between it and system OOM on macOS. `caproom` fills that gap with the two mechanisms that actually work.
+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.
 
 ## What it does
 
@@ -22,11 +20,9 @@ Two backends, auto-selected:
 1. **Docker cgroup** (`--memory`) — used when Docker is installed and running. Hard cap, real kernel enforcement, zero race window.
 2. **Polling watchdog** (`ps` RSS + `SIGKILL`) — fallback when Docker isn't available. No dependencies, works anywhere `ps` exists. Has a small race window bounded by `--interval` (default 200ms) — a process can spike briefly past the cap between polls before being killed.
 
-Both are honest about their mechanism: neither claims kernel-enforced rlimit, because that doesn't exist on macOS for arbitrary processes.
-
 ## Install
 
-```
+```bash
 npm install -g caproom
 ```
 
@@ -48,9 +44,52 @@ caproom --limit 1024 --force-watchdog -- ./some-script.sh
 caproom --limit 4096 --image python:3.12-slim -- python train.py
 ```
 
-Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`.
+### Flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--limit <mb>` | `4096` | memory cap in MB |
+| `--image <name>` | `node:22-slim` | docker image used by the docker backend |
+| `--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 |
+| `--force-watchdog` | off | use the polling watchdog even if Docker is available |
+
+Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`, `CAPROOM_GRACE`.
+
+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).
+
+## 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.
+
+## 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
+```
 
-On cap breach, `caproom` kills the process and exits `137` (same convention as Docker's own OOM-kill exit code).
+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.
+
+## What it never touches
+
+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.
 
 ## Limitations
 
@@ -58,6 +97,10 @@ On cap breach, `caproom` kills the process and exits `137` (same convention as D
 - Watchdog backend has a real (if small) race window; for a hard guarantee, use the Docker backend.
 - Neither backend can cap a process that immediately forks and hides children under a different watched PID tree in unusual ways — the watchdog only tracks the direct child.
 
+## Contributing
+
+Issues and PRs welcome at [github.com/intelogroup/caproom](https://github.com/intelogroup/caproom).
+
 ## License
 
 MIT

package/bin/caproom

@@ -10,28 +10,111 @@
 set -euo pipefail
 
 usage() {
-  cat >&2 << 'EOF'
+  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 init <command> [--limit <mb>] [--grace <sec>]
 
   --limit <mb>     memory cap in MB (default: 4096)
   --image <name>   docker image to run the command in, when using the docker
                     backend (default: node:22-slim)
   --interval <sec> watchdog poll interval in seconds, fallback backend only
                     (default: 0.2)
+  --grace <sec>    seconds to wait after SIGTERM before SIGKILL, watchdog
+                    backend only (default: 5) — gives the process a chance
+                    to flush/save state before a hard kill
   --force-watchdog force the polling watchdog even if Docker is available
 
-env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL
+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
+<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.
+
+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
 
 examples:
   caproom --limit 2048 -- npm run build
   caproom --limit 512 -- claude --dangerously-skip-permissions -p "task"
+  caproom park 12345
+  caproom wake 12345
+  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"
+  cat << EOF
+# caproom: auto-cap '$target' — added by 'caproom init $target'
+# override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
+$fn() {
+  command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
+}
+alias $target=$fn
 EOF
-  exit 1
 }
 
+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) — memory now eligible for kernel reclaim under pressure. 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; }
+}
+
+case "${1:-}" in
+  park) shift; cmd_park "$@"; exit 0 ;;
+  wake) shift; cmd_wake "$@"; exit 0 ;;
+  status) shift; cmd_status "$@"; 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}"
 FORCE_WATCHDOG=0
 
 while [[ $# -gt 0 ]]; do
@@ -39,9 +122,10 @@ while [[ $# -gt 0 ]]; do
     --limit) LIMIT_MB="$2"; shift 2 ;;
     --image) IMAGE="$2"; shift 2 ;;
     --interval) INTERVAL="$2"; shift 2 ;;
+    --grace) GRACE="$2"; shift 2 ;;
     --force-watchdog) FORCE_WATCHDOG=1; shift ;;
     --) shift; break ;;
-    -h|--help) usage ;;
+    -h|--help) usage help ;;
     *) break ;;
   esac
 done
@@ -69,9 +153,21 @@ run_watchdog() {
     local rss_kb
     rss_kb=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ')
     if [[ -n "$rss_kb" && "$rss_kb" -gt "$limit_kb" ]]; then
-      echo "caproom: pid $pid RSS ${rss_kb}KB exceeded ${limit_kb}KB cap — killing" >&2
-      kill -9 "$pid" 2>/dev/null || true
-      exit 137
+      echo "caproom: pid $pid RSS ${rss_kb}KB exceeded ${limit_kb}KB cap — sending SIGTERM (grace ${GRACE}s)" >&2
+      kill -TERM "$pid" 2>/dev/null || true
+      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
+        exit 137
+      fi
+      wait "$pid" 2>/dev/null || exit_code=$?
+      echo "caproom: pid $pid exited cleanly (code $exit_code) during grace period" >&2
+      exit "$exit_code"
     fi
     sleep "$INTERVAL"
   done

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "caproom",
-  "version": "0.1.0",
-  "description": "Memory-cap any command (AI coding agents, builds, background jobs) on macOS/Linux — real enforcement via Docker cgroups or a polling watchdog, since macOS has no working per-process memory rlimit.",
+  "version": "0.3.1",
+  "description": "Memory-cap any command (AI coding agents, builds, background jobs) on macOS/Linux — real enforcement via Docker cgroups or a polling watchdog, plus park/wake to reclaim idle process memory without killing.",
   "bin": {
     "caproom": "bin/caproom"
   },
@@ -12,11 +12,12 @@
     "memory",
     "oom",
     "cgroup",
-    "rlimit",
     "macos",
     "watchdog",
     "ai-agent",
-    "process-limit"
+    "process-limit",
+    "park",
+    "idle-memory"
   ],
   "os": [
     "darwin",