caproom 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-Prevent RAM OOM for long-running terminal coding agents, builds, and background jobs — memory caps plus idle-process parking, for macOS/Linux.
+Prevent RAM OOM for long-running terminal coding agents, builds, and background jobs — memory caps plus idle-process parking, for macOS, Linux, and Windows.
 
 ## Why
 
@@ -15,10 +15,10 @@ macOS has no reliable way to cap a process's memory from userspace. A runaway pr
 caproom --limit <mb> -- <command> [args...]
 ```
 
-Two backends, auto-selected:
+Two backends:
 
-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.
+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.
 
 ## Install
 
@@ -31,17 +31,14 @@ or clone and symlink `bin/caproom` onto your `PATH`.
 ## Usage
 
 ```bash
-# cap a build at 2GB
+# cap a build at 2GB (host-native watchdog, the default)
 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
+# 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
 ```
 
 ### Flags
@@ -49,15 +46,52 @@ caproom --limit 4096 --image python:3.12-slim -- python train.py
 | 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 |
+| `--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 |
 
 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).
 
+## 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:
+
+| | 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) |
+
+**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.
+
+### Docker backend caveats
+
+Opt in with `--docker`. The command then runs inside `node:22-slim` with `$PWD` mounted at `/work` — a Linux container, not your host shell:
+
+- 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.
+
+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.
+
+
+## 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:
@@ -77,11 +111,39 @@ No daemon, no tracking file, no dependency — just `SIGSTOP`/`SIGCONT` wrapped
 
 **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.
+
+## 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.
+
+**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.
+
+**`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.
+
 ## 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.
+- 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.
+- 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
 

package/bin/caproom

@@ -3,28 +3,37 @@
 # 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).
+#   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() {
-  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 guard [--threshold <pct>] [--interval <sec>] <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)
+  --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
-  --force-watchdog force the polling watchdog even if Docker is available
+  --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
 
 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
@@ -35,15 +44,57 @@ becomes eligible for compression under system memory pressure. `caproom wake
 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
 
 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 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() {
@@ -68,17 +119,77 @@ 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
+    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
+}
+
 case "${1:-}" in
   park) shift; cmd_park "$@"; exit 0 ;;
   wake) shift; cmd_wake "$@"; exit 0 ;;
   status) shift; cmd_status "$@"; 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}"
-FORCE_WATCHDOG=0
+USE_DOCKER=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -86,19 +197,18 @@ while [[ $# -gt 0 ]]; do
     --image) IMAGE="$2"; shift 2 ;;
     --interval) INTERVAL="$2"; shift 2 ;;
     --grace) GRACE="$2"; shift 2 ;;
-    --force-watchdog) FORCE_WATCHDOG=1; shift ;;
+    --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 ;;
     --) shift; break ;;
-    -h|--help) usage ;;
+    -h|--help) usage help ;;
     *) 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 \
@@ -106,17 +216,52 @@ 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"
+}
+
 run_watchdog() {
-  echo "caproom: watchdog backend (docker unavailable), limit=${LIMIT_MB}m poll=${INTERVAL}s" >&2
+  echo "caproom: watchdog backend (host-native), limit=${LIMIT_MB}m poll=${INTERVAL}s (process-tree RSS)" >&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 — sending SIGTERM (grace ${GRACE}s)" >&2
+    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
       local waited=0
       while kill -0 "$pid" 2>/dev/null && [[ "$waited" -lt "$GRACE" ]]; do
@@ -138,8 +283,16 @@ run_watchdog() {
   exit "$exit_code"
 }
 
-if docker_available; then
-  run_docker "$@"
+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

package/bin/caproom.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Platform dispatch: bash script on POSIX, PowerShell script on Windows.
+const { spawnSync } = require('child_process');
+const { join } = require('path');
+
+const args = process.argv.slice(2);
+const isWin = process.platform === 'win32';
+
+const result = isWin
+  ? spawnSync(
+      'powershell.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', join(__dirname, 'caproom.ps1'), ...args],
+      { stdio: 'inherit' }
+    )
+  : spawnSync('bash', [join(__dirname, 'caproom'), ...args], { stdio: 'inherit' });
+
+if (result.error) {
+  console.error(`caproom: failed to launch backend — ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/bin/caproom.ps1

@@ -0,0 +1,471 @@
+#Requires -Version 5.1
+# caproom -- Windows backend.
+#
+# Enforcement uses a Job Object with JOB_OBJECT_LIMIT_PROCESS_MEMORY, which is a
+# real kernel-enforced cap (no polling race) and automatically covers child
+# processes. Note this limits *committed virtual memory*, not resident set -- the
+# POSIX backend caps RSS, so the same --limit value can bite at a different point.
+#
+# park uses EmptyWorkingSet, which trims a process's working set to the pagefile
+# on demand without suspending it -- unlike the POSIX backend's SIGSTOP, the
+# process keeps running, so wake is a no-op here.
+
+$ErrorActionPreference = 'Stop'
+
+function Show-Usage {
+    param([switch]$AsHelp)
+    $text = @'
+usage: caproom [--limit <mb>] [--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>]
+
+  --limit <mb>     memory cap in MB (default: 4096). On Windows this caps
+                    committed virtual memory (Job Object ProcessMemoryLimit);
+                    on macOS/Linux it caps RSS. Same flag, different quantity.
+  --interval <sec> poll interval for the fallback watchdog (default: 0.2)
+  --force-watchdog use the polling watchdog instead of the Job Object backend
+
+Windows differences from macOS/Linux:
+  * No SIGTERM grace period. Windows console apps have no signal equivalent,
+    so a watchdog breach is a hard kill. The Job Object backend does not kill
+    at all -- the allocation simply fails inside the process.
+  * park <pid> uses EmptyWorkingSet: memory is trimmed to the pagefile
+    immediately, on demand, and the process KEEPS RUNNING. There is no
+    suspension, so it cannot hang a process that something is waiting on.
+  * wake <pid> is a no-op -- nothing was suspended. Trimmed pages fault back
+    in by themselves on next access.
+
+guard watches SYSTEM-WIDE free memory (not any single process) and auto-parks
+tracked pids (EmptyWorkingSet) once free mem drops below --threshold percent,
+before the OS has to fail an allocation itself. Use it when unrelated heavy
+processes (e.g. a GPU inference job and a TTS job in separate terminals)
+share a box and neither individually breaches any --limit cap. Foreground,
+blocking; exits once all watched pids have exited. There is no unpark step --
+park just trims the working set, pages fault back in on next access.
+
+env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_INTERVAL
+
+examples:
+  caproom --limit 2048 -- npm run build
+  caproom park 12345
+  caproom guard --threshold 10 --interval 5 -- 12345 12346
+  caproom init claude --limit 6144
+'@
+    if ($AsHelp) { Write-Output $text; exit 0 }
+    [Console]::Error.WriteLine($text)
+    exit 1
+}
+
+$NativeMethods = @'
+using System;
+using System.Runtime.InteropServices;
+
+public static class Caproom {
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    public static extern IntPtr CreateJobObject(IntPtr a, string lpName);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern bool SetInformationJobObject(IntPtr hJob, int infoClass, IntPtr lpInfo, uint cbInfo);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern bool AssignProcessToJobObject(IntPtr hJob, IntPtr hProcess);
+
+    [DllImport("psapi.dll", SetLastError = true)]
+    public static extern bool EmptyWorkingSet(IntPtr hProcess);
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct JOBOBJECT_BASIC_LIMIT_INFORMATION {
+        public Int64 PerProcessUserTimeLimit;
+        public Int64 PerJobUserTimeLimit;
+        public UInt32 LimitFlags;
+        public UIntPtr MinimumWorkingSetSize;
+        public UIntPtr MaximumWorkingSetSize;
+        public UInt32 ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public UInt32 PriorityClass;
+        public UInt32 SchedulingClass;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct IO_COUNTERS {
+        public UInt64 ReadOperationCount;
+        public UInt64 WriteOperationCount;
+        public UInt64 OtherOperationCount;
+        public UInt64 ReadTransferCount;
+        public UInt64 WriteTransferCount;
+        public UInt64 OtherTransferCount;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct JOBOBJECT_EXTENDED_LIMIT_INFORMATION {
+        public JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation;
+        public IO_COUNTERS IoInfo;
+        public UIntPtr ProcessMemoryLimit;
+        public UIntPtr JobMemoryLimit;
+        public UIntPtr PeakProcessMemoryUsed;
+        public UIntPtr PeakJobMemoryUsed;
+    }
+
+    public const int ExtendedLimitInformation = 9;
+    public const uint LIMIT_PROCESS_MEMORY = 0x00000100;
+    public const uint LIMIT_KILL_ON_JOB_CLOSE = 0x00002000;
+}
+'@
+
+function Import-Native {
+    if (-not ('Caproom' -as [type])) { Add-Type -TypeDefinition $script:NativeMethods }
+}
+
+function Invoke-Park {
+    param([int]$TargetPid)
+    Import-Native
+    $proc = Get-Process -Id $TargetPid -ErrorAction SilentlyContinue
+    if (-not $proc) { [Console]::Error.WriteLine("caproom: no such pid $TargetPid"); exit 1 }
+    $before = $proc.WorkingSet64
+    if (-not [Caproom]::EmptyWorkingSet($proc.Handle)) {
+        [Console]::Error.WriteLine("caproom: EmptyWorkingSet failed for pid $TargetPid (error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))")
+        exit 1
+    }
+    $after = (Get-Process -Id $TargetPid).WorkingSet64
+    [Console]::Error.WriteLine("caproom: pid $TargetPid parked -- working set trimmed $([math]::Round($before/1MB))MB -> $([math]::Round($after/1MB))MB. Process is STILL RUNNING (no suspension); pages fault back in on access.")
+}
+
+function Invoke-Wake {
+    param([int]$TargetPid)
+    if (-not (Get-Process -Id $TargetPid -ErrorAction SilentlyContinue)) {
+        [Console]::Error.WriteLine("caproom: no such pid $TargetPid"); exit 1
+    }
+    [Console]::Error.WriteLine("caproom: pid $TargetPid -- nothing to wake. On Windows park trims the working set without suspending, so the process never stopped running.")
+}
+
+function Invoke-Status {
+    param([int]$TargetPid)
+    $proc = Get-Process -Id $TargetPid -ErrorAction SilentlyContinue
+    if (-not $proc) { [Console]::Error.WriteLine("caproom: no such pid $TargetPid"); exit 1 }
+    [PSCustomObject]@{
+        Pid           = $proc.Id
+        WorkingSetMB  = [math]::Round($proc.WorkingSet64 / 1MB)
+        CommittedMB   = [math]::Round($proc.PagedMemorySize64 / 1MB)
+        Elapsed       = (Get-Date) - $proc.StartTime
+        Command       = $proc.ProcessName
+    } | Format-List
+}
+
+function Get-FreeMemPercent {
+    $os = Get-CimInstance Win32_OperatingSystem
+    return [math]::Floor(($os.FreePhysicalMemory * 100) / $os.TotalVisibleMemorySize)
+}
+
+function Invoke-Guard {
+    param([int]$Threshold, [double]$Interval, [int[]]$TargetPids)
+    Import-Native
+    [Console]::Error.WriteLine("caproom: guarding $($TargetPids.Count) pid(s), park when system free mem < ${Threshold}% (poll ${Interval}s)")
+    $parked = @{}
+    while ($true) {
+        $alive = @($TargetPids | Where-Object { Get-Process -Id $_ -ErrorAction SilentlyContinue })
+        if ($alive.Count -eq 0) {
+            [Console]::Error.WriteLine("caproom: guard: all watched pids exited")
+            exit 0
+        }
+        $TargetPids = $alive
+        $pct = Get-FreeMemPercent
+        if ($pct -lt $Threshold) {
+            foreach ($p in $TargetPids) {
+                if (-not $parked.ContainsKey($p)) {
+                    $proc = Get-Process -Id $p -ErrorAction SilentlyContinue
+                    if ($proc) {
+                        [Console]::Error.WriteLine("caproom: system free mem ${pct}% < ${Threshold}% threshold -- about to blow, parking pid $p (EmptyWorkingSet)")
+                        [void][Caproom]::EmptyWorkingSet($proc.Handle)
+                        $parked[$p] = $true
+                    }
+                }
+            }
+        }
+        Start-Sleep -Seconds $Interval
+    }
+}
+
+function Invoke-Init {
+    param([string]$Target, [int]$LimitMb)
+    @"
+# caproom: auto-cap '$Target' -- added by 'caproom init $Target'
+# override per-shell: `$env:CAPROOM_LIMIT_MB = 8192
+function ${Target}_capped {
+    `$limit = if (`$env:CAPROOM_LIMIT_MB) { `$env:CAPROOM_LIMIT_MB } else { $LimitMb }
+    caproom --force-watchdog --limit `$limit -- $Target @args
+}
+Set-Alias -Name $Target -Value ${Target}_capped -Force
+"@
+}
+
+# Start-Process -ArgumentList joins an array with spaces and does no quoting,
+# so an argument containing whitespace gets re-split into several arguments by
+# the callee. Build one command line with CommandLineToArgvW quoting instead.
+function ConvertTo-ArgString {
+    param([string[]]$Arguments)
+    $quoted = foreach ($a in $Arguments) {
+        if ($a -eq '') { '""' }
+        elseif ($a -notmatch '[\s"]') { $a }
+        else {
+            # Double any backslashes preceding a quote (and at end of string),
+            # then escape the quotes themselves.
+            $s = $a -replace '(\\*)"', '$1$1\"'
+            $s = $s -replace '(\\+)$', '$1$1'
+            '"' + $s + '"'
+        }
+    }
+    $quoted -join ' '
+}
+
+function New-CappedProcess {
+    # Every pipe-based capture (Process class + ReadToEndAsync, Process class
+    # + raw BaseStream, with and without stripping std-handle inheritance)
+    # returned zero bytes in CI despite a clean exit 0 -- caproom is invoked
+    # as powershell.exe -File caproom.ps1 from the Node shim, itself invoked
+    # from a pwsh.EXE step that captures via a pipe (`| Out-String`), and
+    # something in that nesting swallows anonymous-pipe output every time.
+    # File-based redirection (Start-Process -RedirectStandardOutput <file>)
+    # was the one capture method that survived an isolated repro under the
+    # exact same nesting in the same CI job, so route through temp files
+    # instead of pipes entirely.
+    param([string]$Exe, [string]$ArgLine)
+    $resolvedExe = $Exe
+    $cmd = Get-Command $Exe -ErrorAction SilentlyContinue
+    if ($cmd) { $resolvedExe = $cmd.Source }
+
+    $outFile = [IO.Path]::GetTempFileName()
+    $errFile = [IO.Path]::GetTempFileName()
+    $proc = Start-Process -FilePath $resolvedExe -ArgumentList $ArgLine -NoNewWindow `
+        -RedirectStandardOutput $outFile -RedirectStandardError $errFile -PassThru
+
+    # Start-Process's PassThru object opens a limited-rights handle lazily --
+    # if .Handle is never touched while the process is still alive, .ExitCode
+    # silently reads back 0 for an already-exited process instead of the real
+    # code. Force the full-access handle open now, before it can exit.
+    $null = $proc.Handle
+
+    $proc | Add-Member -NotePropertyName StdoutFile -NotePropertyValue $outFile
+    $proc | Add-Member -NotePropertyName StderrFile -NotePropertyValue $errFile
+    return $proc
+}
+
+function Read-NewOutput {
+    # Tail-follow one capture file from its recorded byte offset, writing new
+    # bytes to the given console stream as they land so output streams live.
+    # Byte-level writes pass the child's bytes through un-re-encoded.
+    param([string]$Path, $Offsets, $Stream)
+    if (-not (Test-Path -LiteralPath $Path)) { return }
+    $fs = [IO.File]::Open($Path, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::ReadWrite)
+    try {
+        if ($fs.Length -lt $Offsets[$Path]) { $Offsets[$Path] = 0 }   # file truncated/recreated under us
+        if ($fs.Length -gt $Offsets[$Path]) {
+            $fs.Position = $Offsets[$Path]
+            $len = [int]($fs.Length - $fs.Position)
+            $buf = New-Object byte[] $len
+            $read = 0
+            while ($read -lt $len) {
+                $n = $fs.Read($buf, $read, $len - $read)
+                if ($n -le 0) { break }
+                $read += $n
+            }
+            if ($read -gt 0) {
+                $Offsets[$Path] += $read
+                $Stream.Write($buf, 0, $read)
+                $Stream.Flush()
+            }
+        }
+    } finally { $fs.Close() }
+}
+
+function Wait-CappedProcess {
+    # Drains remaining output, cleans up the temp capture files, returns the
+    # exit code. If the caller streamed while polling (watchdog path), pass
+    # the SAME offsets table so only the unread tail is relayed here; the
+    # job-object path streams internally on a 50ms cadence.
+    param($Proc, $Offsets = @{ ($Proc.StdoutFile) = 0; ($Proc.StderrFile) = 0 })
+    try {
+        while (-not $Proc.HasExited) {
+            Read-NewOutput -Path $Proc.StdoutFile -Offsets $Offsets -Stream ([Console]::Out)
+            Read-NewOutput -Path $Proc.StderrFile -Offsets $Offsets -Stream ([Console]::Error)
+            Start-Sleep -Milliseconds 50
+        }
+        Read-NewOutput -Path $Proc.StdoutFile -Offsets $Offsets -Stream ([Console]::Out)
+        Read-NewOutput -Path $Proc.StderrFile -Offsets $Offsets -Stream ([Console]::Error)
+        return $Proc.ExitCode
+    } finally {
+        Remove-Item -LiteralPath $Proc.StdoutFile, $Proc.StderrFile -ErrorAction SilentlyContinue
+    }
+}
+
+# The watchdog must see the WHOLE tree, not just the top pid: coding agents
+# keep their memory in children (MCP servers, bundler daemons, headless
+# browsers) while the parent's own working set stays flat. Walk the
+# parent->child edges of one Win32_Process snapshot and sum working sets.
+function Get-TreeWorkingSetBytes {
+    param([int]$RootPid)
+    $ws = @{}
+    $kids = @{}
+    foreach ($p in Get-CimInstance -ClassName Win32_Process -Property ProcessId, ParentProcessId, WorkingSetSize) {
+        $pidInt = [int]$p.ProcessId
+        $ppidInt = [int]$p.ParentProcessId
+        $ws[$pidInt] = [uint64]$p.WorkingSetSize
+        if (-not $kids.ContainsKey($ppidInt)) { $kids[$ppidInt] = @() }
+        $kids[$ppidInt] += $pidInt
+    }
+    if (-not $ws.ContainsKey($RootPid)) { return [uint64]0 }
+    $total = [uint64]0
+    $queue = New-Object System.Collections.Queue
+    $visited = @{}
+    $queue.Enqueue($RootPid)
+    while ($queue.Count -gt 0) {
+        $cur = [int]$queue.Dequeue()
+        if ($visited.ContainsKey($cur)) { continue }   # pid-reuse / cycle guard
+        $visited[$cur] = $true
+        $total += $ws[$cur]
+        if ($kids.ContainsKey($cur)) { foreach ($c in $kids[$cur]) { [void]$queue.Enqueue($c) } }
+    }
+    return $total
+}
+
+function Invoke-Capped {
+    param([int]$LimitMb, [double]$Interval, [bool]$ForceWatchdog, [string[]]$Command)
+
+    $exe = $Command[0]
+    $rest = if ($Command.Length -gt 1) { ConvertTo-ArgString $Command[1..($Command.Length - 1)] } else { '' }
+
+    if (-not $ForceWatchdog) {
+        try {
+            Import-Native
+            $job = [Caproom]::CreateJobObject([IntPtr]::Zero, $null)
+            if ($job -eq [IntPtr]::Zero) { throw 'CreateJobObject returned NULL' }
+
+            $info = New-Object Caproom+JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+            $info.BasicLimitInformation.LimitFlags = [Caproom]::LIMIT_PROCESS_MEMORY -bor [Caproom]::LIMIT_KILL_ON_JOB_CLOSE
+            $info.ProcessMemoryLimit = [UIntPtr]::new([uint64]$LimitMb * 1MB)
+
+            $size = [Runtime.InteropServices.Marshal]::SizeOf($info)
+            $ptr = [Runtime.InteropServices.Marshal]::AllocHGlobal($size)
+            try {
+                [Runtime.InteropServices.Marshal]::StructureToPtr($info, $ptr, $false)
+                if (-not [Caproom]::SetInformationJobObject($job, [Caproom]::ExtendedLimitInformation, $ptr, $size)) {
+                    throw "SetInformationJobObject failed (error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))"
+                }
+            } finally {
+                [Runtime.InteropServices.Marshal]::FreeHGlobal($ptr)
+            }
+
+            # Assign ONLY the child to the job, immediately after spawn --
+            # never caproom's own process. Putting the PowerShell runtime
+            # inside the job made its ~100MB+ commit eat the user's budget,
+            # and a PS spike could fail allocations inside THEIR command.
+            # Policy: prefer under-counting over impeding. Cost is a
+            # millisecond-scale window before assignment lands; the child's
+            # own descendants are still covered automatically (they inherit
+            # the association at CreateProcess).
+            [Console]::Error.WriteLine("caproom: job object backend, limit=${LimitMb}m (committed memory, kernel-enforced, covers the command and its descendants)")
+            $proc = New-CappedProcess -Exe $exe -ArgLine $rest
+            if (-not [Caproom]::AssignProcessToJobObject($job, $proc.Handle)) {
+                # Child is already running -- kill it before falling back,
+                # or the watchdog path below would launch a second instance.
+                & taskkill.exe /PID $proc.Id /T /F 2>$null | Out-Null
+                throw "AssignProcessToJobObject failed (error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))"
+            }
+            exit (Wait-CappedProcess $proc)
+        } catch {
+            [Console]::Error.WriteLine("caproom: job object backend unavailable ($($_.Exception.Message)) -- falling back to watchdog")
+        }
+    }
+
+    [Console]::Error.WriteLine("caproom: watchdog backend, limit=${LimitMb}m poll=${Interval}s (process-tree working set, hard kill on breach -- Windows has no SIGTERM equivalent)")
+    $limitBytes = [uint64]$LimitMb * 1MB
+    $proc = New-CappedProcess -Exe $exe -ArgLine $rest
+    # Stream output WHILE the breach-poll loop runs -- polling must not sit
+    # on the whole runtime and leave the tail-follow to drain everything at
+    # exit. Same offsets table flows into Wait-CappedProcess for the final
+    # drain so nothing is relayed twice.
+    $offsets = @{ ($proc.StdoutFile) = 0; ($proc.StderrFile) = 0 }
+    while (-not $proc.HasExited) {
+        Read-NewOutput -Path $proc.StdoutFile -Offsets $offsets -Stream ([Console]::Out)
+        Read-NewOutput -Path $proc.StderrFile -Offsets $offsets -Stream ([Console]::Error)
+        Start-Sleep -Seconds $Interval
+        if ($proc.HasExited) { break }
+        $treeBytes = Get-TreeWorkingSetBytes -RootPid $proc.Id
+        if ($treeBytes -gt $limitBytes) {
+            [Console]::Error.WriteLine("caproom: process tree of pid $($proc.Id) using $([math]::Round($treeBytes/1MB))MB exceeded ${LimitMb}MB cap -- killing tree")
+            & taskkill.exe /PID $proc.Id /T /F 2>$null | Out-Null
+            exit 137
+        }
+    }
+    exit (Wait-CappedProcess $proc -Offsets $offsets)
+}
+
+# ---- argument parsing ----
+
+if ($args.Count -eq 0) { Show-Usage }
+
+switch ($args[0]) {
+    'help'   { Show-Usage -AsHelp }
+    '-h'     { Show-Usage -AsHelp }
+    '--help' { Show-Usage -AsHelp }
+    'park'   {
+        if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom park <pid>'); exit 1 }
+        Invoke-Park -TargetPid ([int]$args[1]); exit 0
+    }
+    'wake'   {
+        if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom wake <pid>'); exit 1 }
+        Invoke-Wake -TargetPid ([int]$args[1]); exit 0
+    }
+    'status' {
+        if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom status <pid>'); exit 1 }
+        Invoke-Status -TargetPid ([int]$args[1]); exit 0
+    }
+    'guard'  {
+        if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom guard [--threshold <pct>] [--interval <sec>] <pid...>'); exit 1 }
+        $threshold = 10
+        $gInterval = 5
+        $gPids = @()
+        for ($i = 1; $i -lt $args.Count; $i++) {
+            if ($args[$i] -eq '--threshold') { $threshold = [int]$args[$i + 1]; $i++ }
+            elseif ($args[$i] -eq '--interval') { $gInterval = [double]$args[$i + 1]; $i++ }
+            elseif ($args[$i] -eq '--') { continue }
+            else { $gPids += [int]$args[$i] }
+        }
+        if ($gPids.Count -eq 0) { [Console]::Error.WriteLine('usage: caproom guard [--threshold <pct>] [--interval <sec>] <pid...>'); exit 1 }
+        Invoke-Guard -Threshold $threshold -Interval $gInterval -TargetPids $gPids
+        exit 0
+    }
+    'init'   {
+        if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom init <command> [--limit <mb>]'); exit 1 }
+        $target = $args[1]
+        $limit = 4096
+        for ($i = 2; $i -lt $args.Count; $i++) {
+            if ($args[$i] -eq '--limit') { $limit = [int]$args[$i + 1]; $i++ }
+            else { [Console]::Error.WriteLine("caproom: unknown init flag $($args[$i])"); exit 1 }
+        }
+        Invoke-Init -Target $target -LimitMb $limit
+        exit 0
+    }
+}
+
+$limitMb = if ($env:CAPROOM_LIMIT_MB) { [int]$env:CAPROOM_LIMIT_MB } else { 4096 }
+$interval = if ($env:CAPROOM_INTERVAL) { [double]$env:CAPROOM_INTERVAL } else { 0.2 }
+$forceWatchdog = $false
+$i = 0
+$parsing = $true
+while ($parsing -and $i -lt $args.Count) {
+    $a = $args[$i]
+    if ($a -eq '--limit')                { $limitMb = [int]$args[$i + 1]; $i += 2 }
+    elseif ($a -eq '--interval')         { $interval = [double]$args[$i + 1]; $i += 2 }
+    elseif ($a -eq '--force-watchdog')   { $forceWatchdog = $true; $i++ }
+    elseif ($a -eq '-h' -or $a -eq '--help') { Show-Usage -AsHelp }
+    elseif ($a -eq '--')                 { $i++; $parsing = $false }
+    else                                 { $parsing = $false }
+}
+
+if ($i -ge $args.Count) { Show-Usage }
+$command = @($args[$i..($args.Count - 1)])
+
+Invoke-Capped -LimitMb $limitMb -Interval $interval -ForceWatchdog $forceWatchdog -Command $command

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "caproom",
-  "version": "0.2.0",
-  "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.",
+  "version": "0.4.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"
+    "caproom": "bin/caproom.js"
   },
   "files": [
-    "bin/caproom"
+    "bin/caproom",
+    "bin/caproom.js",
+    "bin/caproom.ps1"
   ],
   "keywords": [
     "memory",
@@ -21,7 +23,8 @@
   ],
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "license": "MIT",
   "repository": {