caproom 0.7.0 → 0.7.2

package/README.md

@@ -94,6 +94,24 @@ 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.
 
+## 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

@@ -743,6 +743,21 @@ collect_tree() {
 run_watchdog() {
   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.
+  # Snapshot termios before spawn so we can put the tty back after a kill.
+  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 +791,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

@@ -411,7 +411,7 @@ if ($args.Count -eq 0) { Show-Usage }
 
 $script:CaproomNtLoaded = $false
 function Ensure-NtSuspend {
-    # Whole-tree park needs NtSuspendProcess/NtResumeProcess (ntdll) —
+    # Whole-tree park needs NtSuspendProcess/NtResumeProcess (ntdll) --
     # the Windows analogue of kill -STOP/-CONT. Loaded lazily, once.
     if ($script:CaproomNtLoaded) { return }
     try {
@@ -423,7 +423,7 @@ function Ensure-NtSuspend {
 '@
         $script:CaproomNtLoaded = $true
     } catch {
-        [Console]::Error.WriteLine('caproom watch: cannot load ntdll suspend/resume — --auto-park unavailable')
+        [Console]::Error.WriteLine('caproom watch: cannot load ntdll suspend/resume -- --auto-park unavailable')
         throw
     }
 }
@@ -469,7 +469,7 @@ function Get-TreeStats {
 function Invoke-Top {
     # schema:1 rows identical in shape to the POSIX build. One honest
     # divergence: Windows exposes no cheap sleep-state, so state is always
-    # 'running' and park_candidate keys off tree size alone — the reason
+    # 'running' and park_candidate keys off tree size alone -- the reason
     # string says so instead of pretending a sleep check happened.
     param([int]$FilterPid = 0, [int]$ParkMinMb = 512)
     $snap = Get-CaproomSnapshot
@@ -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))
@@ -562,7 +568,7 @@ function Invoke-Watch {
                     if ($h -ne [IntPtr]::Zero) {
                         [void][Caproom.Nt]::NtResumeProcess($h); [void][Caproom.Nt]::CloseHandle($h)
                         if ($json) { Emit ([pscustomobject]@{ schema = 1; event = 'woke'; ts = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds(); pid = $wpid; free_pct = $pct }) }
-                        else { [Console]::Error.WriteLine("caproom: watch: free mem ${pct}% >= ${wake}% — resuming pid $wpid") }
+                        else { [Console]::Error.WriteLine("caproom: watch: free mem ${pct}% >= ${wake}% -- resuming pid $wpid") }
                     }
                 }
                 $parkedByUs.Clear()
@@ -589,10 +595,10 @@ function Invoke-Watch {
                         }
                     }
                     if ($json) { Emit ([pscustomobject]@{ schema = 1; event = 'parked'; ts = $now; pid = $tpid; tree_rss_kb = $st.RssKb; tree_pids = @($st.Pids.ToArray()); stopped = $stopped }) }
-                    else { [Console]::Error.WriteLine("caproom: watch: tree of pid $tpid hit $($st.RssKb)KB (>= $([int]$threshKb)KB) — PARKED tree ($stopped pids)") }
+                    else { [Console]::Error.WriteLine("caproom: watch: tree of pid $tpid hit $($st.RssKb)KB (>= $([int]$threshKb)KB) -- PARKED tree ($stopped pids)") }
                 } else {
                     if ($json) { Emit ([pscustomobject]@{ schema = 1; event = 'breach'; ts = $now; pid = $tpid; tree_rss_kb = $st.RssKb }) }
-                    else { [Console]::Error.WriteLine("caproom: watch: tree of pid $tpid hit $($st.RssKb)KB (>= $([int]$threshKb)KB) — no --auto-park, reporting only") }
+                    else { [Console]::Error.WriteLine("caproom: watch: tree of pid $tpid hit $($st.RssKb)KB (>= $([int]$threshKb)KB) -- no --auto-park, reporting only") }
                 }
             } else {
                 if ($breaching.ContainsKey($tpid)) {
@@ -616,7 +622,7 @@ function Invoke-Setup {
     New-Item -ItemType Directory -Force -Path $dir | Out-Null
 
     @'
-# caproom PowerShell integration — regenerated by `caproom setup`.
+# caproom PowerShell integration -- regenerated by `caproom setup`.
 function global:caproom_freemem_pct {
     $os = Get-CimInstance Win32_OperatingSystem
     [int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize)
@@ -651,7 +657,7 @@ function global:prompt {
     } else {
         [Console]::Error.WriteLine('caproom setup: profile already bound')
     }
-    [Console]::Error.WriteLine('caproom setup: shell.ps1 written to ' + $dir + ' — new terminals pick it up automatically')
+    [Console]::Error.WriteLine('caproom setup: shell.ps1 written to ' + $dir + ' -- new terminals pick it up automatically')
 }
 
 switch ($args[0]) {
@@ -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.0",
+  "version": "0.7.2",
   "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",
@@ -10,7 +10,8 @@
     "bin/caproom",
     "bin/caproom.js",
     "bin/caproom.ps1",
-    "bin/caproom-mcp.js"
+    "bin/caproom-mcp.js",
+    "scripts/postinstall.js"
   ],
   "keywords": [
     "memory",
@@ -29,7 +30,7 @@
     "win32"
   ],
   "scripts": {
-    "postinstall": "node -e \"process.stdout.write('caproom: optional next step — run `caproom setup` to bind headroom management to your shells (never modifies rc files on install)\\n')\""
+    "postinstall": "node scripts/postinstall.js"
   },
   "license": "MIT",
   "repository": {

package/scripts/postinstall.js

@@ -0,0 +1,7 @@
+// Hint only — never touches rc files on install. Binding is explicit:
+//   caproom setup
+try {
+  process.stdout.write(
+    'caproom: optional next step — run "caproom setup" to bind headroom warnings to your shells (never modifies rc files on install)\n'
+  );
+} catch (_) { /* never block installs */ }