caproom 0.7.1 → 0.7.3

package/README.md

@@ -51,8 +51,9 @@ caproom --limit 4096 --docker --image python:3.12-slim -- python train.py
 | `--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`) |
 
-Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`, `CAPROOM_GRACE`.
+Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`, `CAPROOM_GRACE`, `CAPROOM_BYPASS_TTY=1` (force bypass, same as `--no-intercept-tty`).
 
 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).
 
@@ -94,6 +95,26 @@ 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). Piped/batch `caproom -- opencode run "task"` stays fully capped via the watchdog. Override: `CAPROOM_BYPASS_TTY=1` / `--no-intercept-tty` forces bypass for any command; `CAPROOM_BYPASS_TTY=0` forces legacy pipe mode. `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.

package/bin/caproom

@@ -34,6 +34,9 @@ usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <co
                     (default: node:22-slim)
   --force-watchdog no-op; the host-native watchdog IS the default — kept so
                     existing scripts and 'init' snippets keep working
+  --no-intercept-tty bypass stdio interposition for TUI/pty apps (OSC 10/11,
+                    DSR CPR, mouse DEC 1003) — exec directly and monitor via
+                    detached 'caproom watch --auto-park' instead
 
 park / wake — freeze an idle process so the kernel CAN reclaim/compress its
 memory without killing it. Honest semantics: SIGSTOP only makes the pages
@@ -61,7 +64,12 @@ 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
+env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL, CAPROOM_GRACE, CAPROOM_BYPASS_TTY=1
+
+TUI note: 'caproom -- <TUI>' (opencode, vim, htop, ...) bypasses stdio when [ -t 0 ] && [ -t 1 ]
+so terminal queries (OSC, mouse) stay on the pty. The cap is then advisory via a detached
+'caproom watch --auto-park' monitor. Piped/batch 'caproom -- opencode run "task"' stays fully capped.
+Use --no-intercept-tty / CAPROOM_BYPASS_TTY=1 to force bypass for any command.
 
 examples:
   caproom --limit 2048 -- npm run build
@@ -92,14 +100,48 @@ cmd_init() {
     esac
   done
   local fn="${target}_capped"
-  cat << EOF
+  local is_tui=0
+  case "$target" in
+    opencode|claude|codex|vim|nvim|htop|less|fzf|nano|emacs) is_tui=1 ;;
+  esac
+  if [[ $is_tui -eq 1 ]]; then
+    echo "caproom: warning: '$target' is a TUI — interactive tty runs will bypass stdio and use a detached 'caproom watch --auto-park' monitor to preserve pty (OSC 10/11, DSR CPR, mouse DEC 1003). Batch 'caproom -- $target run' stays fully capped. Set CAPROOM_BYPASS_TTY=1 to always bypass, or CAPROOM_BYPASS_TTY=0 + re-init to force legacy pipe mode." >&2
+    cat << EOF
 # caproom: auto-cap '$target' — added by 'caproom init $target'
 # override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
+# TUI note: when [ -t 0 ] && [ -t 1 ], '$target' runs directly and a detached 'caproom watch --auto-park' monitors it
+# (preserves OSC 10/11, DSR CPR, mouse DEC 1003). Batch/headless (piped) still goes through the watchdog.
+# Set CAPROOM_BYPASS_TTY=1 to always bypass, 0 to force legacy mode.
 $fn() {
+  if [ "\${CAPROOM_BYPASS_TTY:-0}" = "1" ]; then
+    command caproom --no-intercept-tty --limit "\${CAPROOM_LIMIT_MB:-$limit}" --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
+    return \$?
+  fi
+  if [ -t 0 ] && [ -t 1 ]; then
+    command $target "\$@" &
+    local _cap_pid=\$!
+    command caproom watch --threshold-mb "\${CAPROOM_LIMIT_MB:-$limit}" --interval "\${CAPROOM_INTERVAL:-0.2}" --auto-park --json "\$_cap_pid" >/dev/null 2>&1 &
+    wait "\$_cap_pid"
+    return \$?
+  fi
   command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
 }
 alias $target=$fn
 EOF
+  else
+    cat << EOF
+# caproom: auto-cap '$target' — added by 'caproom init $target'
+# override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
+$fn() {
+  if [ "\${CAPROOM_BYPASS_TTY:-0}" = "1" ]; then
+    command caproom --no-intercept-tty --limit "\${CAPROOM_LIMIT_MB:-$limit}" --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
+    return \$?
+  fi
+  command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
+}
+alias $target=$fn
+EOF
+  fi
 }
 
 cmd_park() {
@@ -706,6 +748,8 @@ IMAGE="${CAPROOM_IMAGE:-node:22-slim}"
 INTERVAL="${CAPROOM_INTERVAL:-0.2}"
 GRACE="${CAPROOM_GRACE:-5}"
 USE_DOCKER=0
+BYPASS_TTY=0
+[[ "${CAPROOM_BYPASS_TTY:-0}" == "1" ]] && BYPASS_TTY=1
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -717,6 +761,7 @@ while [[ $# -gt 0 ]]; do
     # legacy no-op: the watchdog IS the default now; accepted so old
     # scripts and init snippets keep working
     --force-watchdog) shift ;;
+    --no-intercept-tty) BYPASS_TTY=1; shift ;;
     --) shift; break ;;
     -h|--help) usage help ;;
     *) break ;;
@@ -740,9 +785,67 @@ collect_tree() {
   walk_tree "$1"
 }
 
+is_known_tui() {
+  case "${1##*/}" in
+    opencode|claude|codex|vim|nvim|htop|less|fzf|nano|emacs) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 run_watchdog() {
+  # TUI bypass: if stdio is a tty and target is a known TUI (or bypass flag),
+  # don't sit on stdio — exec directly and monitor via detached watch.
+  # This preserves pty semantics (OSC 10/11, DSR CPR, DEC 1003 mouse) that
+  # break when a wrapper backgrounds the TUI and steals foreground pgrp.
+  if [[ "$BYPASS_TTY" -eq 1 ]] || { [[ -t 0 && -t 1 ]] && is_known_tui "${1:-}"; }; then
+    if [[ "$BYPASS_TTY" -eq 1 ]]; then
+      echo "caproom: bypass-tty active — exec directly, no stdio interposition (limit ${LIMIT_MB}m advisory via detached watch)" >&2
+    else
+      echo "caproom: tty TUI detected ('${1##*/}') — bypassing stdio interposition, monitoring via detached watch (limit ${LIMIT_MB}m)" >&2
+    fi
+    # Clean stale tty modes before handing off, same snapshot hygiene as
+    # the normal watchdog path but without taking foreground away.
+    printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
+    # Detached watchdog monitors the TUI's pid tree without owning stdio.
+    # Resolve our own path (works via shim and direct invocation).
+    local _cap_bin="${BASH_SOURCE[0]:-$0}"
+    [[ "$_cap_bin" != /* ]] && _cap_bin="$PWD/$_cap_bin"
+    if [[ ! -f "$_cap_bin" ]]; then
+      _cap_bin="$(command -v caproom 2>/dev/null || echo "$_cap_bin")"
+    fi
+    "$@" &
+    local _tui_pid=$!
+    # Fire-and-forget watch; it exits when _tui_pid exits. Suppressed so it
+    # never leaks into the TUI's stdout. Threshold is the cap itself.
+    bash "$_cap_bin" watch --threshold-mb "$LIMIT_MB" --interval "$INTERVAL" --auto-park --json "$_tui_pid" >/dev/null 2>&1 &
+    local _watch_pid=$!
+    wait "$_tui_pid"
+    local _rc=$?
+    # Best-effort cleanup of the detached watcher (it should already exit
+    # via all-exited, but kill is cheap if TUI exited fast).
+    kill "$_watch_pid" 2>/dev/null || true
+    wait "$_watch_pid" 2>/dev/null || true
+    exit "$_rc"
+  fi
   echo "caproom: watchdog backend (host-native), limit=${LIMIT_MB}m poll=${INTERVAL}s (process-tree RSS)" >&2
   local limit_kb=$(( LIMIT_MB * 1024 ))
+  # Terminal hygiene: a TUI child (opencode, claude, ...) puts the tty in
+  # raw + mouse-tracking mode. If WE kill it, it never restores, and the
+  # user's shell then prints mouse reports like [[<35;25;15M as garbage.
+  # Clear any stale mode from a previous kill BEFORE snapshot, then snapshot
+  # the clean state so restore goes to sane, not back to garbage.
+  printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
+  local saved_stty=""
+  if [[ -t 0 ]]; then
+    saved_stty=$(stty -g </dev/tty 2>/dev/null || true)
+  fi
+  restore_tty() {
+    # Only on OUR kill — a clean exit already restored its own state, and
+    # re-emitting resets there could clobber whatever the NEXT program drew.
+    [[ -n "$saved_stty" ]] && stty "$saved_stty" </dev/tty 2>/dev/null \
+      || { [[ -t 0 ]] && stty sane </dev/tty 2>/dev/null || true; }
+    printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?25h' >/dev/tty 2>/dev/null || true
+  }
   "$@" &
   local pid=$!
   local exit_code=0
@@ -776,10 +879,12 @@ run_watchdog() {
       if [[ "$sweep" -gt 0 ]]; then
         echo "caproom: SIGKILLed ${sweep} survivor(s) after grace — exit 137" >&2
         wait "$pid" 2>/dev/null || true
+        restore_tty
         exit 137
       fi
       wait "$pid" 2>/dev/null || exit_code=$?
       echo "caproom: pid $pid exited cleanly (code $exit_code) during grace period" >&2
+      restore_tty
       exit "$exit_code"
     fi
     sleep "$INTERVAL"

package/bin/caproom.ps1

@@ -504,18 +504,23 @@ function Invoke-Watch {
     # Same NDJSON contract as the POSIX watcher (schema:1 events on stdout
     # under --json). Explicit pids only; naming the pid IS the opt-in for
     # --auto-park, same rule as POSIX.
+    # NOTE: args arrive via the named -Rest parameter, NOT $args — splatting
+    # into $args proved unreliable here (every element read back as null,
+    # yielding pids [0,0,0,0] and a busy-spinning interval-0 loop).
+    param([string[]]$Rest)
     $thresholdMb = 2048; $intervalSec = 5.0; $auto = $false; $wake = -1.0; $json = $false
     $targets = New-Object System.Collections.Generic.List[int]
-    for ($i = 0; $i -lt $args.Count; $i++) {
-        switch ($args[$i]) {
-            '--threshold-mb'        { $thresholdMb = [int]$args[$i + 1]; $i++ }
-            '--interval'            { $intervalSec = [double]$args[$i + 1]; $i++ }
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--threshold-mb'        { $thresholdMb = [int]$Rest[$i + 1]; $i++ }
+            '--interval'            { $intervalSec = [double]$Rest[$i + 1]; $i++ }
             '--auto-park'           { $auto = $true }
-            '--auto-wake-free-pct'  { $wake = [double]$args[$i + 1]; $i++ }
+            '--auto-wake-free-pct'  { $wake = [double]$Rest[$i + 1]; $i++ }
             '--json'                { $json = $true }
+            '--'                    { }
             default {
-                try { $targets.Add([int]$args[$i]) }
-                catch { [Console]::Error.WriteLine("caproom: unknown watch arg $($args[$i])"); exit 1 }
+                try { $targets.Add([int]$Rest[$i]) }
+                catch { [Console]::Error.WriteLine("caproom: unknown watch arg $($Rest[$i])"); exit 1 }
             }
         }
     }
@@ -523,6 +528,7 @@ function Invoke-Watch {
         [Console]::Error.WriteLine('usage: caproom watch [--threshold-mb <mb>] [--interval <sec>] [--auto-park] [--auto-wake-free-pct <pct>] [--json] <pid...>')
         exit 1
     }
+    if ($intervalSec -lt 0.5) { $intervalSec = 0.5 }
 
     function Emit([object]$Ev) {
         [Console]::Out.WriteLine((ConvertTo-Json -Compress -Depth 6 -InputObject $Ev))
@@ -683,7 +689,7 @@ switch ($args[0]) {
         exit 0
     }
     'watch' {
-        Invoke-Watch @($args | Select-Object -Skip 1)
+        Invoke-Watch -Rest @($args | Select-Object -Skip 1)
         exit 0
     }
     'park'   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caproom",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "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",