caproom 0.5.0 → 0.7.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

@@ -21,6 +21,9 @@ usage: caproom [--limit <mb>] [--interval <sec>] -- <command> [args...]
        caproom status <pid>
        caproom guard [--threshold <pct>] [--interval <sec>] <pid...>
        caproom init <command> [--limit <mb>]
+       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 / freemem
 
   --limit <mb>     memory cap in MB (default: 4096). On Windows this caps
                     committed virtual memory (Job Object ProcessMemoryLimit);
@@ -406,10 +409,283 @@ function Invoke-Capped {
 
 if ($args.Count -eq 0) { Show-Usage }
 
+$script:CaproomNtLoaded = $false
+function Ensure-NtSuspend {
+    # Whole-tree park needs NtSuspendProcess/NtResumeProcess (ntdll) —
+    # the Windows analogue of kill -STOP/-CONT. Loaded lazily, once.
+    if ($script:CaproomNtLoaded) { return }
+    try {
+        Add-Type -Namespace Caproom -Name Nt -MemberDefinition @'
+[DllImport("ntdll.dll")] public static extern int NtSuspendProcess(IntPtr processHandle);
+[DllImport("ntdll.dll")] public static extern int NtResumeProcess(IntPtr processHandle);
+[DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(int desiredAccess, bool inheritHandle, int processId);
+[DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
+'@
+        $script:CaproomNtLoaded = $true
+    } catch {
+        [Console]::Error.WriteLine('caproom watch: cannot load ntdll suspend/resume — --auto-park unavailable')
+        throw
+    }
+}
+
+function Get-CaproomSnapshot {
+    # One CIM query -> ByPid map, Children map (only live parents), Roots
+    # (pids whose parent is not in the snapshot). Mirrors posix read_snapshot.
+    $procs = @(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,Name,CommandLine,WorkingSetSize)
+    $byPid = @{}
+    foreach ($p in $procs) { $byPid[[int]$p.ProcessId] = $p }
+    $children = @{}
+    foreach ($p in $procs) {
+        $ppid = [int]$p.ParentProcessId
+        if ($byPid.ContainsKey($ppid)) {
+            if (-not $children.ContainsKey($ppid)) { $children[$ppid] = New-Object System.Collections.Generic.List[int] }
+            $children[$ppid].Add([int]$p.ProcessId)
+        }
+    }
+    $roots = @($procs | Where-Object { -not $byPid.ContainsKey([int]$_.ParentProcessId) } | ForEach-Object { [int]$_.ProcessId })
+    return @{ ByPid=$byPid; Children=$children; Roots=$roots }
+}
+
+function Get-TreeStats {
+    param([hashtable]$Snap, [int]$RootPid)
+    $rss = [long]0
+    $pids = New-Object System.Collections.Generic.List[int]
+    $stack = New-Object System.Collections.Generic.Stack[int]
+    $seen = @{}
+    $stack.Push($RootPid)
+    while ($stack.Count -gt 0) {
+        $cur = $stack.Pop()
+        if ($seen.ContainsKey($cur)) { continue }
+        $seen[$cur] = $true
+        if (-not $Snap.ByPid.ContainsKey($cur)) { continue }
+        $proc = $Snap.ByPid[$cur]
+        if ($proc.WorkingSetSize) { $rss += [long]$proc.WorkingSetSize }
+        $pids.Add($cur)
+        if ($Snap.Children.ContainsKey($cur)) { foreach ($c in $Snap.Children[$cur]) { $stack.Push($c) } }
+    }
+    return @{ RssKb = [long]($rss / 1KB); Pids = $pids }
+}
+
+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
+    # string says so instead of pretending a sleep check happened.
+    param([int]$FilterPid = 0, [int]$ParkMinMb = 512)
+    $snap = Get-CaproomSnapshot
+    $ts = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    $limitMb = 4096; if ($env:CAPROOM_LIMIT_MB) { $limitMb = [int]$env:CAPROOM_LIMIT_MB }
+    $parkMinKb = [long]$ParkMinMb * 1024
+    $rows = New-Object System.Collections.Generic.List[object]
+    foreach ($root in $snap.Roots) {
+        if ($FilterPid -ne 0 -and $root -ne $FilterPid) { continue }
+        $st = Get-TreeStats -Snap $snap -RootPid $root
+        $cmd = ''
+        if ($snap.ByPid.ContainsKey($root)) {
+            $procRow = $snap.ByPid[$root]
+            if ($procRow.CommandLine) { $cmd = [string]$procRow.CommandLine } else { $cmd = [string]$procRow.Name }
+        }
+        $cand = $false; $reason = ''
+        if ([long]$st.RssKb -ge $parkMinKb) {
+            $cand = $true
+            $reason = "tree_rss $($st.RssKb)KB >= ${parkMinKb}KB park threshold (win32: no sleep-state check)"
+        }
+        $rows.Add([pscustomobject]@{
+            pid = $root; cmd = $cmd; tree_rss_kb = $st.RssKb
+            tree_pids = @($st.Pids.ToArray()); state = 'running'
+            park_candidate = $cand; reason = $reason
+        })
+    }
+    $envelope = [pscustomobject]@{ schema = 1; ts = $ts; limit_mb_default = $limitMb; processes = @($rows.ToArray()) }
+    ConvertTo-Json -Compress -Depth 6 -InputObject $envelope
+}
+
+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.
+    $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++ }
+            '--auto-park'           { $auto = $true }
+            '--auto-wake-free-pct'  { $wake = [double]$args[$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 }
+            }
+        }
+    }
+    if ($targets.Count -eq 0) {
+        [Console]::Error.WriteLine('usage: caproom watch [--threshold-mb <mb>] [--interval <sec>] [--auto-park] [--auto-wake-free-pct <pct>] [--json] <pid...>')
+        exit 1
+    }
+
+    function Emit([object]$Ev) {
+        [Console]::Out.WriteLine((ConvertTo-Json -Compress -Depth 6 -InputObject $Ev))
+    }
+
+    $mode = 'watch'; if ($auto) { $mode = 'auto-park' }
+    $ts0 = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    if ($json) {
+        Emit ([pscustomobject]@{ schema = 1; event = 'started'; ts = $ts0; mode = $mode; threshold_kb = ($thresholdMb * 1024); pids = @($targets.ToArray()) })
+    } else {
+        $armed = ''; if ($auto) { $armed = ', AUTO-PARK ARMED' }
+        [Console]::Error.WriteLine("caproom: watching $($targets.Count) pid(s), tree threshold ${thresholdMb}MB, poll ${intervalSec}s$armed")
+    }
+
+    $parkedByUs = New-Object System.Collections.Generic.List[int]
+    $breaching = @{}
+    while ($true) {
+        $liveSet = @{}
+        foreach ($q in @(Get-CimInstance Win32_Process -Property ProcessId)) { $liveSet[[int]$q.ProcessId] = $true }
+        $alive = New-Object System.Collections.Generic.List[int]
+        foreach ($tpid in $targets) { if ($liveSet.ContainsKey($tpid)) { $alive.Add($tpid) } }
+        if ($alive.Count -eq 0) {
+            if ($json) { Emit ([pscustomobject]@{ schema = 1; event = 'all-exited'; ts = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds() }) }
+            [Console]::Error.WriteLine('caproom: watch: all watched pids exited')
+            exit 0
+        }
+        $targets = $alive
+
+        if ($wake -ge 0 -and $parkedByUs.Count -gt 0) {
+            $os = Get-CimInstance Win32_OperatingSystem
+            $pct = [int]($os.FreePhysicalMemory * 100 / $os.TotalVisibleMemorySize)
+            if ($pct -ge $wake) {
+                Ensure-NtSuspend
+                foreach ($wpid in @($parkedByUs.ToArray())) {
+                    if (-not $liveSet.ContainsKey($wpid)) { continue }
+                    $h = [Caproom.Nt]::OpenProcess(0x0800, $false, $wpid)
+                    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") }
+                    }
+                }
+                $parkedByUs.Clear()
+            }
+        }
+
+        $snap = Get-CaproomSnapshot
+        $threshKb = [long]$thresholdMb * 1024
+        foreach ($tpid in $targets) {
+            if (-not $snap.ByPid.ContainsKey($tpid)) { continue }
+            $st = Get-TreeStats -Snap $snap -RootPid $tpid
+            if ([long]$st.RssKb -ge $threshKb) {
+                if ($breaching.ContainsKey($tpid)) { continue }
+                $breaching[$tpid] = $true
+                $now = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+                if ($auto) {
+                    Ensure-NtSuspend
+                    $stopped = 0
+                    foreach ($cp in $st.Pids) {
+                        $h = [Caproom.Nt]::OpenProcess(0x0800, $false, $cp)
+                        if ($h -ne [IntPtr]::Zero) {
+                            [void][Caproom.Nt]::NtSuspendProcess($h); [void][Caproom.Nt]::CloseHandle($h)
+                            $parkedByUs.Add($cp); $stopped++
+                        }
+                    }
+                    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 {
+                    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 {
+                if ($breaching.ContainsKey($tpid)) {
+                    $breaching.Remove($tpid)
+                    $now2 = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+                    if ($json) { Emit ([pscustomobject]@{ schema = 1; event = 'recovered'; ts = $now2; pid = $tpid; tree_rss_kb = $st.RssKb }) }
+                    else { [Console]::Error.WriteLine("caproom: watch: pid $tpid back under threshold ($($st.RssKb)KB)") }
+                }
+            }
+        }
+        Start-Sleep -Seconds $intervalSec
+    }
+}
+
+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
+    }
+    'top' {
+        $fpid = 0; $parkMin = 512
+        for ($i = 1; $i -lt $args.Count; $i++) {
+            switch ($args[$i]) {
+                '--json'         { }
+                '--pid'          { $fpid = [int]$args[$i + 1]; $i++ }
+                '--park-min-mb'  { $parkMin = [int]$args[$i + 1]; $i++ }
+                default { [Console]::Error.WriteLine("caproom: unknown top flag $($args[$i])"); exit 1 }
+            }
+        }
+        Invoke-Top -FilterPid $fpid -ParkMinMb $parkMin
+        exit 0
+    }
+    'watch' {
+        Invoke-Watch @($args | Select-Object -Skip 1)
+        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.7.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",