caproom 0.7.3 → 0.7.5

package/README.md

@@ -52,8 +52,10 @@ caproom --limit 4096 --docker --image python:3.12-slim -- python train.py
 | `--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, same as `--no-intercept-tty`).
+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).
 
@@ -95,7 +97,7 @@ 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.
+**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
 

package/bin/caproom

@@ -37,6 +37,11 @@ usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <co
   --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
+  --pty            allocate a pty (forkpty) and forward bytes verbatim — full
+                    terminal fidelity for TUI (requires python3 or script)
+                    implies --no-intercept-tty + pty watchdog on the pty
+                    tree; fallback to bypass if pty alloc fails
+  --no-pty         disable pty allocation (use bypass or watchdog)
 
 park / wake — freeze an idle process so the kernel CAN reclaim/compress its
 memory without killing it. Honest semantics: SIGSTOP only makes the pages
@@ -64,12 +69,14 @@ 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, CAPROOM_BYPASS_TTY=1
+env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL, CAPROOM_GRACE, CAPROOM_BYPASS_TTY=1, CAPROOM_PTY=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.
+'caproom watch --auto-park' monitor, or via '--pty' which allocates a real pty (forkpty)
+and forwards bytes verbatim (python3 or script). Piped/batch 'caproom -- opencode run "task"'
+stays fully capped. Use --no-intercept-tty / CAPROOM_BYPASS_TTY=1 to force bypass, --pty /
+CAPROOM_PTY=1 to force pty.
 
 examples:
   caproom --limit 2048 -- npm run build
@@ -749,7 +756,9 @@ INTERVAL="${CAPROOM_INTERVAL:-0.2}"
 GRACE="${CAPROOM_GRACE:-5}"
 USE_DOCKER=0
 BYPASS_TTY=0
+USE_PTY=0
 [[ "${CAPROOM_BYPASS_TTY:-0}" == "1" ]] && BYPASS_TTY=1
+[[ "${CAPROOM_PTY:-0}" == "1" ]] && USE_PTY=1
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -762,6 +771,8 @@ while [[ $# -gt 0 ]]; do
     # scripts and init snippets keep working
     --force-watchdog) shift ;;
     --no-intercept-tty) BYPASS_TTY=1; shift ;;
+    --pty) USE_PTY=1; shift ;;
+    --no-pty) USE_PTY=0; shift ;;
     --) shift; break ;;
     -h|--help) usage help ;;
     *) break ;;
@@ -792,7 +803,107 @@ is_known_tui() {
   esac
 }
 
+SPAWN_PID=""
+spawn_with_pty() {
+  # Try python3 pty_wrapper.py, then script fallback. Sets SPAWN_PID on success.
+  local wrapper
+  wrapper="$(dirname "${BASH_SOURCE[0]:-$0}")/../scripts/pty_wrapper.py"
+  if [[ ! -f "$wrapper" ]]; then
+    local cap_path
+    cap_path="$(command -v caproom 2>/dev/null || echo "")"
+    if [[ -n "$cap_path" ]]; then
+      wrapper="$(dirname "$cap_path")/../scripts/pty_wrapper.py"
+      [[ ! -f "$wrapper" ]] && wrapper="$(dirname "$(dirname "$cap_path")")/scripts/pty_wrapper.py"
+    fi
+  fi
+  [[ ! -f "$wrapper" ]] && wrapper="$HOME/Developer/caproom/scripts/pty_wrapper.py"
+  if [[ -f "$wrapper" ]] && command -v python3 >/dev/null 2>&1 && python3 -c "import pty" 2>/dev/null; then
+    # Avoid stdout capture issue: run in a way that doesn't hold the caller's command-substitution pipe.
+    # Use a temp file to pass pid back if needed, but we set global.
+    python3 "$wrapper" "$@" &
+    SPAWN_PID=$!
+    return 0
+  fi
+  if command -v script >/dev/null 2>&1; then
+    if [[ "$(uname)" == "Darwin" ]]; then
+      script -q /dev/null "$@" &
+      SPAWN_PID=$!
+      return 0
+    else
+      local cmd
+      cmd=$(printf '%q ' "$@")
+      script -q -c "$cmd" /dev/null &
+      SPAWN_PID=$!
+      return 0
+    fi
+  fi
+  return 1
+}
+
 run_watchdog() {
+  # PTY mode: allocate a real pty (forkpty) and forward bytes verbatim.
+  # Full terminal fidelity — OSC 10/11, DSR CPR, mouse DEC 1003 all work
+  # because the TUI talks to a real pty, not a pipe. Watchdog still enforces
+  # the cap on the pty tree (same kill logic as normal).
+  if [[ "$USE_PTY" -eq 1 ]]; then
+    echo "caproom: pty mode — allocating pty via forkpty for '${1##*/}' (limit ${LIMIT_MB}m, verbatim forwarding)" >&2
+    stty -tostop 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 saved_stty=""
+    if [[ -t 0 ]]; then
+      saved_stty=$(stty -g </dev/tty 2>/dev/null || true)
+    fi
+    restore_pty() {
+      [[ -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 pty_pid
+    if spawn_with_pty "$@"; then
+      pty_pid=$SPAWN_PID
+      echo "caproom: pty allocated, pid $pty_pid — monitoring tree RSS" >&2
+      local limit_kb=$(( LIMIT_MB * 1024 ))
+      local exit_code=0
+      while kill -0 "$pty_pid" 2>/dev/null; do
+        collect_tree "$pty_pid"
+        if [[ "${#TREE_PIDS[@]}" -gt 0 && "$TREE_RSS_KB" -gt "$limit_kb" ]]; then
+          local overshoot=$(( TREE_RSS_KB * 100 / limit_kb ))
+          echo "caproom: pid $pty_pid tree RSS ${TREE_RSS_KB}KB exceeded ${limit_kb}KB cap (+${overshoot}%) — killing pty tree (grace ${GRACE}s)" >&2
+          kill -TERM "${TREE_PIDS[@]}" 2>/dev/null || true
+          local -a breach_pids=("${TREE_PIDS[@]}")
+          local waited=0
+          while kill -0 "$pty_pid" 2>/dev/null && [[ "$waited" -lt "$GRACE" ]]; do
+            sleep 1
+            waited=$(( waited + 1 ))
+          done
+          local sp sweep=0
+          for sp in "${breach_pids[@]}"; do
+            if kill -0 "$sp" 2>/dev/null; then
+              kill -9 "$sp" 2>/dev/null || true
+              sweep=$(( sweep + 1 ))
+            fi
+          done
+          if [[ "$sweep" -gt 0 ]]; then
+            echo "caproom: SIGKILLed ${sweep} survivor(s) after grace — exit 137" >&2
+            wait "$pty_pid" 2>/dev/null || true
+            restore_pty
+            exit 137
+          fi
+          wait "$pty_pid" 2>/dev/null || exit_code=$?
+          echo "caproom: pid $pty_pid exited cleanly (code $exit_code) during grace period" >&2
+          restore_pty
+          exit "$exit_code"
+        fi
+        sleep "$INTERVAL"
+      done
+      wait "$pty_pid" 2>/dev/null || exit_code=$?
+      restore_pty 2>/dev/null || true
+      exit "$exit_code"
+    else
+      echo "caproom: pty alloc failed — falling back to bypass/watchdog" >&2
+      restore_pty 2>/dev/null || true
+    fi
+  fi
   # 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
@@ -805,6 +916,7 @@ run_watchdog() {
     fi
     # Clean stale tty modes before handing off, same snapshot hygiene as
     # the normal watchdog path but without taking foreground away.
+    stty -tostop 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
     # Detached watchdog monitors the TUI's pid tree without owning stdio.
     # Resolve our own path (works via shim and direct invocation).
@@ -832,8 +944,9 @@ run_watchdog() {
   # 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.
+  # Clear stale state before snapshot — disable tostop to avoid SIGTTOU suspend
+  # when caproom backgrounds the TUI (ghostty reports [[<... as suspended tty output).
+  stty -tostop 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 saved_stty=""
   if [[ -t 0 ]]; then

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "caproom",
-  "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.",
+  "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.",
   "bin": {
     "caproom": "bin/caproom.js",
     "caproom-mcp": "bin/caproom-mcp.js"
@@ -11,7 +11,8 @@
     "bin/caproom.js",
     "bin/caproom.ps1",
     "bin/caproom-mcp.js",
-    "scripts/postinstall.js"
+    "scripts/postinstall.js",
+    "scripts/pty_wrapper.py"
   ],
   "keywords": [
     "memory",

package/scripts/pty_wrapper.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""pty_wrapper — allocate a pty and run command with verbatim forwarding, propagating exit code.
+
+Usage: pty_wrapper.py <command> [args...]
+"""
+import os, sys, pty, select, signal, struct, fcntl, termios
+
+def copy_winsize():
+    try:
+        s = struct.pack("HHHH", 0, 0, 0, 0)
+        a = struct.unpack('hhhh', fcntl.ioctl(sys.stdout.fileno(), termios.TIOCGWINSZ, s))
+        fcntl.ioctl(master_fd, termios.TIOCSWINSZ, struct.pack("HHHH", a[0], a[1], a[2], a[3]))
+    except Exception:
+        pass
+
+if len(sys.argv) < 2:
+    print("usage: pty_wrapper.py <command> [args...]", file=sys.stderr)
+    sys.exit(1)
+
+pid, master_fd = pty.fork()
+if pid == 0:
+    # child
+    try:
+        os.execvp(sys.argv[1], sys.argv[1:])
+    except Exception as e:
+        print(f"pty_wrapper: exec failed: {e}", file=sys.stderr)
+        os._exit(127)
+
+# parent: forward
+# handle window resize
+def handle_winch(sig, frame):
+    copy_winsize()
+try:
+    signal.signal(signal.SIGWINCH, handle_winch)
+except Exception:
+    pass
+copy_winsize()
+
+# make stdin non-blocking if it's a tty
+stdin_fd = sys.stdin.fileno()
+stdout_fd = sys.stdout.fileno()
+is_tty = os.isatty(stdin_fd)
+
+# set master to non-blocking? select handles
+import errno
+
+exit_code = 127
+try:
+    while True:
+        r, _, _ = select.select([master_fd] + ([stdin_fd] if is_tty else []), [], [], 0.1)
+        if master_fd in r:
+            try:
+                data = os.read(master_fd, 1024)
+            except OSError as e:
+                if e.errno == errno.EIO:
+                    data = b''
+                else:
+                    raise
+            if not data:
+                # EOF — child may have exited
+                pass
+            else:
+                os.write(stdout_fd, data)
+        if is_tty and stdin_fd in r:
+            try:
+                data = os.read(stdin_fd, 1024)
+            except OSError:
+                data = b''
+            if data:
+                os.write(master_fd, data)
+            else:
+                # stdin EOF
+                pass
+        # check if child exited
+        try:
+            pid2, status = os.waitpid(pid, os.WNOHANG)
+            if pid2 != 0:
+                if os.WIFEXITED(status):
+                    exit_code = os.WEXITSTATUS(status)
+                elif os.WIFSIGNALED(status):
+                    exit_code = 128 + os.WTERMSIG(status)
+                else:
+                    exit_code = 1
+                # drain remaining master data
+                try:
+                    while True:
+                        r2, _, _ = select.select([master_fd], [], [], 0.1)
+                        if not r2:
+                            break
+                        d = os.read(master_fd, 1024)
+                        if not d:
+                            break
+                        os.write(stdout_fd, d)
+                except Exception:
+                    pass
+                break
+        except ChildProcessError:
+            break
+finally:
+    try:
+        os.close(master_fd)
+    except Exception:
+        pass
+sys.exit(exit_code)