caproom 0.5.0 → 0.6.0

package/bin/caproom

@@ -71,6 +71,8 @@ examples:
   caproom wake 12345
   caproom top --json [--pid <pid>] [--park-min-mb <mb>]
   caproom watch [--threshold-mb <mb>] [--auto-park] [--auto-wake-free-pct <pct>] [--json] <pid...>
+  caproom setup [--guard] [--threshold <pct>] [--uninstall]
+  caproom freemem
   caproom init claude --limit 6144 --grace 10
 EOF
   exit "$code"
@@ -443,9 +445,254 @@ cmd_guard() {
   done
 }
 
+# ---- terminal bind: setup / unbind ------------------------------------
+# Binds headroom management to every interactive shell in ANY terminal
+# (Terminal.app, iTerm2, Ghostty, ...) by writing ONE integration file
+# per shell under ~/.caproom/ and marker-patching the rc files. Idempotent,
+# backed up, reversible with `caproom unbind`. Never runs automatically:
+# npm postinstall only prints a hint.
+
+CAPROOM_DIR="${CAPROOM_DIR:-$HOME/.caproom}"
+
+setup_shell_sh() {
+  cat > "$CAPROOM_DIR/shell.sh" << 'EOF'
+# caproom shell integration — regenerated by `caproom setup`; edits here
+# are overwritten. Source of truth: bin/caproom (setup_shell_sh).
+
+caproom_freemem_pct() { command caproom freemem 2>/dev/null; }
+
+caproom_headroom_check() {
+  local pct last now
+  pct=$(caproom_freemem_pct) || return 0
+  [ -n "$pct" ] || return 0
+  [ "$pct" -lt "${CAPROOM_HEADROOM_WARN:-20}" ] || return 0
+  last=$(cat "${TMPDIR:-/tmp}/caproom-headroom-last" 2>/dev/null || echo 0)
+  now=$(date +%s)
+  [ $(( now - ${last:-0} )) -ge 60 ] || return 0
+  echo "$now" > "${TMPDIR:-/tmp}/caproom-headroom-last" 2>/dev/null
+  echo "caproom: headroom low (${pct}% free) — check 'caproom top' before launching heavy work"
+}
+
+if [ -n "$ZSH_VERSION" ]; then
+  autoload -Uz add-zsh-hook
+  add-zsh-hook precmd caproom_headroom_check
+elif [ -n "$BASH_VERSION" ]; then
+  case ";$PROMPT_COMMAND;" in
+    *caproom_headroom_check*) ;;
+    *) PROMPT_COMMAND="caproom_headroom_check${PROMPT_COMMAND:+;$PROMPT_COMMAND}" ;;
+  esac
+fi
+
+# Opt-in auto-wrap: CAPROOM_AUTO_WRAP="claude,codex,opencode" gives every
+# listed command a <name>_capped twin running under $CAPROOM_LIMIT_MB.
+# The bare name is aliased ONLY with CAPROOM_AUTO_ALIAS=1 — never hijack a
+# command the user did not consent to wrap.
+if [ -n "${CAPROOM_AUTO_WRAP:-}" ]; then
+  for _cr_cmd in $(echo "${CAPROOM_AUTO_WRAP}" | tr ',' ' '); do
+    _cr_fn="$(printf '%s' "$_cr_cmd" | sed 's/[-.]/_/g')_capped"
+    eval "$(printf "%s() { command caproom --limit \"\${CAPROOM_LIMIT_MB:-4096}\" --grace \"\${CAPROOM_GRACE:-5}\" -- '%s' \"\$@\"; }" "$_cr_fn" "$(printf '%s' "$_cr_cmd" | sed "s/'/'\\\\''/g")")"
+    if [ "${CAPROOM_AUTO_ALIAS:-0}" = "1" ]; then
+      alias "$_cr_cmd=$_cr_fn"
+    fi
+  done
+  unset _cr_cmd _cr_fn
+fi
+EOF
+}
+
+setup_shell_fish() {
+  cat > "$CAPROOM_DIR/shell.fish" << 'EOF'
+# caproom fish integration — regenerated by `caproom setup`.
+function __caproom_freemem
+    command caproom freemem 2>/dev/null
+end
+
+function __caproom_headroom_check --on-event fish_prompt
+    set -l pct (__caproom_freemem)
+    or return
+    test -n "$pct"; or return
+    set -l warn 20
+    if set -q CAPROOM_HEADROOM_WARN
+        set warn $CAPROOM_HEADROOM_WARN
+    end
+    if test "$pct" -lt "$warn"
+        set -l stamp /tmp/caproom-headroom-last
+        set -l now (date +%s)
+        set -l last 0
+        if test -f $stamp
+            set last (cat $stamp)
+        end
+        if test (math "$now - $last") -ge 60
+            echo $now > $stamp
+            echo "caproom: headroom low ($pct% free) — check 'caproom top' before launching heavy work"
+        end
+    end
+end
+EOF
+}
+
+setup_shell_ps1() {
+  cat > "$CAPROOM_DIR/shell.ps1" << 'EOF'
+# caproom PowerShell integration — regenerated by `caproom setup` (Windows).
+function global:caproom_freemem_pct {
+    $os = Get-CimInstance Win32_OperatingSystem
+    [int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize)
+}
+$global:__caproomLastWarn = 0
+function global:prompt {
+    $pct = caproom_freemem_pct
+    $now = [DateTimeOffset]::Now.ToUnixTimeSeconds()
+    if ($pct -lt (${CAPROOM_HEADROOM_WARN:-20}) -and ($now - $script:__caproomLastWarn) -ge 60) {
+        $script:__caproomLastWarn = $now
+        Write-Host "caproom: headroom low ($pct% free) — check 'caproom top' before launching heavy work" -ForegroundColor Yellow
+    }
+    "PS $($executionContext.SessionState.Path.CurrentLocation)> "
+}
+EOF
+}
+
+rc_targets() {
+  # Prints "path<TAB>required" pairs for every rc we manage. Only rcs that
+  # already exist are patched, EXCEPT the login shell's own rc which is
+  # created if missing — never invent configs for shells you don't use.
+  local zshrc="${ZDOTDIR:-$HOME/.zshrc}"
+  printf '%s\t%s\n' "$zshrc" "shell"
+  [[ -f "$HOME/.bashrc" ]] && printf '%s\t%s\n' "$HOME/.bashrc" "optional"
+}
+
+patch_rc_file() {
+  local rc="$1"
+  [[ -f "$rc" ]] || touch "$rc"
+  grep -q "# >>> caproom >>>" "$rc" && return 0
+  cp "$rc" "$rc.caproom.bak.$(date +%Y%m%d%H%M%S)"
+  {
+    echo ""
+    echo "# >>> caproom >>>"
+    echo '[ -f ~/.caproom/shell.sh ] && source ~/.caproom/shell.sh'
+    echo "# <<< caproom <<<"
+  } >> "$rc"
+}
+
+patch_rc_file_fish() {
+  local rc="$HOME/.config/fish/config.fish"
+  mkdir -p "$(dirname "$rc")" 2>/dev/null
+  [[ -f "$rc" ]] || return 0   # don't invent fish config unless it exists
+  grep -q "# caproom (fish)" "$rc" && return 0
+  cp "$rc" "$rc.caproom.bak.$(date +%Y%m%d%H%M%S)"
+  {
+    echo ""
+    echo "# caproom (fish)"
+    echo '[ -f ~/.caproom/shell.fish ] && source ~/.caproom/shell.fish'
+  } >> "$rc"
+}
+
+install_guard_daemon() {
+  local threshold="$1"
+  local bin_path
+  bin_path=$(command -v caproom || true)
+  [[ -n "$bin_path" ]] || { echo "caproom setup: cannot resolve caproom binary for daemon" >&2; return 1; }
+  if [[ "$(uname)" == "Darwin" ]]; then
+    local plist="$HOME/Library/LaunchAgents/com.caproom.guard.plist"
+    mkdir -p "$HOME/Library/LaunchAgents"
+    cat > "$plist" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.caproom.guard</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/bin/env</string><string>bash</string><string>$bin_path</string>
+    <string>guard</string><string>--threshold</string><string>$threshold</string><string>--interval</string><string>15</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict></plist>
+EOF
+    echo "caproom setup: guard daemon installed -> $plist"
+    echo "  load now:  launchctl load $plist"
+    echo "  unload:    launchctl unload $plist"
+  else
+    local unit="$HOME/.config/systemd/user/caproom-guard.service"
+    mkdir -p "$HOME/.config/systemd/user"
+    cat > "$unit" << EOF
+[Unit]
+Description=caproom memory guard
+
+[Service]
+ExecStart=/usr/bin/env bash $bin_path guard --threshold $threshold --interval 15
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+EOF
+    echo "caproom setup: guard service installed -> $unit"
+    echo "  start now: systemctl --user enable --now caproom-guard.service"
+    echo "  stop:      systemctl --user disable --now caproom-guard.service"
+  fi
+}
+
+cmd_setup() {
+  local guard="" threshold=10 do_unbind=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --guard) guard="$threshold"; shift ;;
+      --threshold) threshold="$2"; shift 2 ;;
+      --uninstall|--unbind) do_unbind=1; shift ;;
+      *) echo "caproom setup: unknown option $1" >&2; exit 1 ;;
+    esac
+  done
+
+  if [[ "$do_unbind" -eq 1 ]]; then
+    local rc removed=0
+    while IFS=$'\t' read -r rc _req; do
+      [[ -f "$rc" ]] || continue
+      if grep -q "# >>> caproom >>>" "$rc"; then
+        awk '/^# >>> caproom >>>$/{skip=1;next} /^# <<< caproom <<<$/{skip=0;next} !skip' "$rc" > "$rc.cr.tmp" && mv "$rc.cr.tmp" "$rc"
+        removed=$(( removed + 1 ))
+      fi
+    done < <(rc_targets)
+    if grep -q "# caproom (fish)" "$HOME/.config/fish/config.fish" 2>/dev/null; then
+      awk '/^# caproom \(fish\)$/{getline; skip=1; next} !skip' "$HOME/.config/fish/config.fish" > /tmp/cr-fish.tmp 2>/dev/null \
+        && mv /tmp/cr-fish.tmp "$HOME/.config/fish/config.fish"
+      removed=$(( removed + 1 ))
+    fi
+    echo "caproom unbind: markers removed from $removed file(s); backups kept as *.caproom.bak.*"
+    echo "  integration files left in $CAPROOM_DIR (rm -rf to purge)"
+    return 0
+  fi
+
+  mkdir -p "$CAPROOM_DIR"
+  setup_shell_sh
+  setup_shell_fish
+  [[ "$(uname)" != "Darwin" ]] || setup_shell_ps1
+
+  local rc req patched=0
+  while IFS=$'\t' read -r rc req; do
+    if patch_rc_file "$rc"; then patched=$(( patched + 1 )); fi
+  done < <(rc_targets)
+  patch_rc_file_fish
+
+  echo "caproom setup: bound to your shells via $CAPROOM_DIR/"
+  echo "  shell.sh  zsh + bash (headroom warning on every prompt, opt-in auto-wrap)"
+  echo "  shell.fish  fish equivalent"
+  echo "  patched rc files: $patched (backups alongside as *.caproom.bak.*)"
+  echo ""
+  echo "auto-wrap usage:"
+  echo '  export CAPROOM_AUTO_WRAP="claude,codex,opencode"   # creates <cmd>_capped twins'
+  echo '  export CAPROOM_AUTO_ALIAS=1                        # ALSO shadow bare names (explicit consent)'
+  echo "  export CAPROOM_LIMIT_MB=8192                       # per-shell budget"
+  echo ""
+  echo "new terminals pick this up immediately; current ones: source ~/.caproom/shell.sh"
+
+  if [[ -n "$guard" ]]; then
+    echo ""
+    install_guard_daemon "$threshold"
+  fi
+}
 case "${1:-}" in
   park) shift; cmd_park "$@"; exit 0 ;;
   wake) shift; cmd_wake "$@"; exit 0 ;;
+  freemem) mem_free_pct; exit 0 ;;
+  setup|bind|unbind) shift; cmd_setup "$@"; exit 0 ;;
   status) shift; cmd_status "$@"; exit 0 ;;
   top) shift; cmd_top "$@"; exit 0 ;;
   watch) shift; cmd_watch "$@"; exit 0 ;;

package/bin/caproom-mcp.js

@@ -131,11 +131,14 @@ function callTool(name, args) {
       if (args.docker) { a.push('--docker'); if (args.image) a.push('--image', String(args.image)); }
       a.push('--');
       const r = caproom(a.concat(cmd), { timeout: Math.max(60000, (args.timeout_ms || 300000)) });
-      let verdict = '';
+      const errText = (r.stderr || '');
+      const capped = /exceeded .* cap/.test(errText);
+      let verdict;
       if (r.status === 137 || r.signal === 'SIGKILL') verdict = 'RESULT: KILLED BY CAP (exit 137)';
+      else if (capped && (r.status === 143 || r.signal === 'SIGTERM')) verdict = 'RESULT: CAPPED — tree killed during grace (SIGTERM honored, exit 143)';
       else if (r.status === 143 || r.signal === 'SIGTERM') verdict = 'RESULT: terminated during grace (SIGTERM honored)';
       else verdict = 'RESULT: exit=' + r.status;
-      return text(verdict + '\n--- stderr ---\n' + ((r.stderr || '').slice(-4000) || '(empty)'));
+      return text(verdict + '\n--- stderr ---\n' + (errText.slice(-4000) || '(empty)'));
     }
     default:
       throw new Error('unknown tool: ' + name);

package/bin/caproom.ps1

@@ -406,10 +406,68 @@ function Invoke-Capped {
 
 if ($args.Count -eq 0) { Show-Usage }
 
+function Invoke-Setup {
+    # Bind headroom management to PowerShell sessions in ANY terminal:
+    # writes ~/.caproom/shell.ps1 (single source) and marker-patches
+    # $PROFILE. Idempotent, backs up the profile, reversible via
+    # `caproom setup --uninstall`. Never runs on npm install.
+    $dir = Join-Path $HOME '.caproom'
+    New-Item -ItemType Directory -Force -Path $dir | Out-Null
+
+    @'
+# caproom PowerShell integration — regenerated by `caproom setup`.
+function global:caproom_freemem_pct {
+    $os = Get-CimInstance Win32_OperatingSystem
+    [int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize)
+}
+$global:__caproomLastWarn = 0
+function global:prompt {
+    try {
+        $pct = caproom_freemem_pct
+        $now = [DateTimeOffset]::Now.ToUnixTimeSeconds()
+        $warn = if ($env:CAPROOM_HEADROOM_WARN) { [int]$env:CAPROOM_HEADROOM_WARN } else { 20 }
+        if ($pct -lt $warn -and ($now - $script:__caproomLastWarn) -ge 60) {
+            $script:__caproomLastWarn = $now
+            Write-Host "caproom: headroom low ($pct% free) - check 'caproom top' before launching heavy work" -ForegroundColor Yellow
+        }
+    } catch {}
+    "PS $($executionContext.SessionState.Path.CurrentLocation)> "
+}
+'@ | Set-Content -Encoding UTF8 (Join-Path $dir 'shell.ps1')
+
+    $profilePath = $PROFILE.CurrentUserAllHosts
+    if (-not (Test-Path $profilePath)) { New-Item -ItemType File -Force -Path $profilePath | Out-Null }
+    $content = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
+    if ($content -notmatch '# >>> caproom >>>') {
+        Copy-Item $profilePath "$profilePath.caproom.bak.$(Get-Date -Format yyyyMMddHHmmss)"
+        Add-Content $profilePath @'
+
+# >>> caproom >>>
+. "$HOME\.caproom\shell.ps1"
+# <<< caproom <<<
+'@
+        [Console]::Error.WriteLine("caproom setup: patched $profilePath (backup alongside)")
+    } 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')
+}
+
 switch ($args[0]) {
     'help'   { Show-Usage -AsHelp }
     '-h'     { Show-Usage -AsHelp }
     '--help' { Show-Usage -AsHelp }
+    'setup'  {
+        Invoke-Setup; exit 0
+    }
+    'bind'   {
+        Invoke-Setup; exit 0
+    }
+    'freemem' {
+        $os = Get-CimInstance Win32_OperatingSystem
+        Write-Output ([int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize))
+        exit 0
+    }
     'park'   {
         if ($args.Count -lt 2) { [Console]::Error.WriteLine('usage: caproom park <pid>'); exit 1 }
         Invoke-Park -TargetPid ([int]$args[1]); exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caproom",
-  "version": "0.5.0",
+  "version": "0.6.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.js",
@@ -28,6 +28,9 @@
     "linux",
     "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')\""
+  },
   "license": "MIT",
   "repository": {
     "type": "git",