caproom 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jimkalinov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# caproom
+
+Memory-cap any command — AI coding agents, builds, background jobs — on macOS/Linux.
+
+## Why
+
+macOS has no working per-process memory limit in userspace. Verified empirically:
+
+- `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`.
+
+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.
+
+## What it does
+
+```
+caproom --limit <mb> -- <command> [args...]
+```
+
+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
+
+```
+npm install -g caproom
+```
+
+or clone and symlink `bin/caproom` onto your `PATH`.
+
+## Usage
+
+```bash
+# cap a build at 2GB
+caproom --limit 2048 -- npm run build
+
+# cap an AI coding agent run at 512MB
+caproom --limit 512 -- claude -p "refactor this module"
+
+# force the watchdog even if Docker is available
+caproom --limit 1024 --force-watchdog -- ./some-script.sh
+
+# use a different docker image for the docker backend (default: node:22-slim)
+caproom --limit 4096 --image python:3.12-slim -- python train.py
+```
+
+Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`.
+
+On cap breach, `caproom` kills the process and exits `137` (same convention as Docker's own OOM-kill exit code).
+
+## Limitations
+
+- Docker backend mounts `$PWD` into the container at `/work` and runs there — paths outside `$PWD` aren't visible to the command.
+- 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.
+
+## License
+
+MIT

package/bin/caproom

@@ -0,0 +1,86 @@
+#!/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. Docker cgroup (--memory) — hard cap, zero race window. Used when
+#      `docker` is installed and the daemon is running.
+#   2. Polling watchdog (ps RSS + SIGKILL) — fallback, no dependencies,
+#      works everywhere, has a small race window (poll interval).
+set -euo pipefail
+
+usage() {
+  cat >&2 << 'EOF'
+usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <command> [args...]
+
+  --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)
+  --force-watchdog force the polling watchdog even if Docker is available
+
+env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL
+
+examples:
+  caproom --limit 2048 -- npm run build
+  caproom --limit 512 -- claude --dangerously-skip-permissions -p "task"
+EOF
+  exit 1
+}
+
+LIMIT_MB="${CAPROOM_LIMIT_MB:-4096}"
+IMAGE="${CAPROOM_IMAGE:-node:22-slim}"
+INTERVAL="${CAPROOM_INTERVAL:-0.2}"
+FORCE_WATCHDOG=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --limit) LIMIT_MB="$2"; shift 2 ;;
+    --image) IMAGE="$2"; shift 2 ;;
+    --interval) INTERVAL="$2"; shift 2 ;;
+    --force-watchdog) FORCE_WATCHDOG=1; shift ;;
+    --) shift; break ;;
+    -h|--help) usage ;;
+    *) break ;;
+  esac
+done
+
+[[ $# -eq 0 ]] && usage
+
+docker_available() {
+  [[ "$FORCE_WATCHDOG" -eq 0 ]] && command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
+}
+
+run_docker() {
+  echo "caproom: docker cgroup backend, limit=${LIMIT_MB}m image=${IMAGE}" >&2
+  exec docker run --rm -i \
+    --memory="${LIMIT_MB}m" --memory-swap="${LIMIT_MB}m" \
+    -v "$PWD:/work" -w /work "$IMAGE" "$@"
+}
+
+run_watchdog() {
+  echo "caproom: watchdog backend (docker unavailable), limit=${LIMIT_MB}m poll=${INTERVAL}s" >&2
+  local limit_kb=$(( LIMIT_MB * 1024 ))
+  "$@" &
+  local pid=$!
+  local exit_code=0
+  while kill -0 "$pid" 2>/dev/null; do
+    local rss_kb
+    rss_kb=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ')
+    if [[ -n "$rss_kb" && "$rss_kb" -gt "$limit_kb" ]]; then
+      echo "caproom: pid $pid RSS ${rss_kb}KB exceeded ${limit_kb}KB cap — killing" >&2
+      kill -9 "$pid" 2>/dev/null || true
+      exit 137
+    fi
+    sleep "$INTERVAL"
+  done
+  wait "$pid" || exit_code=$?
+  exit "$exit_code"
+}
+
+if docker_available; then
+  run_docker "$@"
+else
+  run_watchdog "$@"
+fi

package/package.json

@@ -0,0 +1,30 @@
+{
+  "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.",
+  "bin": {
+    "caproom": "bin/caproom"
+  },
+  "files": [
+    "bin/caproom"
+  ],
+  "keywords": [
+    "memory",
+    "oom",
+    "cgroup",
+    "rlimit",
+    "macos",
+    "watchdog",
+    "ai-agent",
+    "process-limit"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intelogroup/caproom.git"
+  }
+}