claude-bulkhead 0.2.2 → 0.3.0

package/src/mcp.js

@@ -0,0 +1,131 @@
+'use strict'
+const path = require('path')
+
+// Stdio MCP servers are child processes of a session, one copy per session. Several sessions
+// with the same server are N identical copies, each with its own memory. This finds them from
+// command lines alone (heuristic, see docs/commands.md):
+//  - the program is a launcher (npx, npm exec, pnpm dlx, yarn dlx, bunx, uvx, uv run, pipx, node,
+//    bun, deno, python) or the program's own name looks like an MCP server;
+//  - and one argument names an MCP package or path: @modelcontextprotocol/..., a package ending in
+//    "mcp" or containing "mcp-" / "-mcp" / "mcp-server", or a path whose last two segments do.
+// Options (--mcp-config and the like) never count.
+
+const LAUNCHERS = /^(?:npx|npm|pnpm|pnpx|yarn|bunx|bun|uvx|uv|pipx|node|deno|python|python3|python3\.\d+|py|tsx|ts-node|docker)(?:\.exe|\.cmd)?$/i
+const MCP_WORD = /(?:^|[\\/@_.-])mcp(?:$|[\\/@_.-])|mcp-?server|@modelcontextprotocol[\\/]/i
+
+function tokens(cmd) {
+  return String(cmd || '').match(/"[^"]*"|'[^']*'|\S+/g)?.map(t => t.replace(/^["']|["']$/g, '')) || []
+}
+
+function programOf(tok) {
+  return path.basename(String(tok || '').replace(/\\/g, '/'))
+}
+
+// A path or package name reads as MCP: the last two segments only, so a project folder that
+// happens to be called mcp-something does not make every command under it an MCP server.
+function mentionsMcp(arg) {
+  if (!arg || arg.startsWith('-')) return false
+  const parts = arg.replace(/\\/g, '/').split('/').filter(Boolean)
+  const tail = arg.startsWith('@') && parts.length === 2 ? parts.join('/') : parts.slice(-2).join('/')
+  if (MCP_WORD.test(tail)) return true
+  // a script deep inside an installed package: the package name decides
+  const pkg = /node_modules\/((?:@[\w.-]+\/)?[\w.-]+)/.exec(parts.join('/') + '/')
+  return Boolean(pkg && MCP_WORD.test(pkg[1]))
+}
+
+function isMcpCommand(cmd) {
+  const t = tokens(cmd)
+  if (!t.length) return false
+  const prog = programOf(t[0])
+  if (LAUNCHERS.test(prog)) return t.slice(1).some(mentionsMcp)
+  return /(?:^|[-_.])mcp(?:$|[-_.])|mcp-?server/i.test(prog) && !/^(?:claude|node|sh|bash|zsh)(?:\.exe)?$/i.test(prog)
+}
+
+// Package name for display: @scope/pkg without its version, else the program or script.
+function serverName(cmd) {
+  const t = tokens(cmd).slice(1)
+  const arg = t.find(mentionsMcp)
+  if (!arg) return programOf(tokens(cmd)[0])
+  const scoped = /^(@[\w.-]+\/[\w.-]+?)(?:@[^/\s]*)?$/.exec(arg)
+  if (scoped) return scoped[1]
+  const bare = /^([\w.-]+?)@(?:latest|next|\d[^/\s]*)$/.exec(arg)
+  if (bare) return bare[1]
+  const parts = arg.replace(/\\/g, '/').split('/').filter(Boolean)
+  const m = /node_modules\/((?:@[\w.-]+\/)?[\w.-]+)/.exec(arg.replace(/\\/g, '/'))
+  return m ? m[1] : parts.slice(-2).join('/')
+}
+
+// The command line with what differs between sessions removed, so two sessions' copies compare
+// equal: the session's folder, package versions, numbers (ports, pids), ids and temp paths.
+function signature(cmd, cwd) {
+  let s = String(cmd || '')
+  if (cwd) s = s.split(cwd).join('<cwd>')
+  return tokens(s).map((tok, i) => {
+    if (i === 0) return programOf(tok).replace(/\.(?:exe|cmd)$/i, '')
+    if (/^-{0,2}\d+$/.test(tok) || /^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(tok) || /^[0-9a-f]{12,}$/i.test(tok)) return '#'
+    if (/^(?:\/private)?\/(?:tmp|var\/folders)\//.test(tok) || /[\\/]Temp[\\/]/i.test(tok)) return '<tmp>'
+    const eq = /^(--?[\w-]+)=(.*)$/.exec(tok)
+    if (eq && /^\d+$/.test(eq[2])) return `${eq[1]}=#`
+    return tok.replace(/(@[\w.-]+\/[\w.-]+|[\w.-]*mcp[\w.-]*)@(?:latest|next|\d[\w.+-]*)$/i, '$1')
+  }).join(' ')
+}
+
+// owner: Map pid -> session pid (assignOwners). Returns
+// { instances: [{ session, pid, name, signature, rss, procs }], groups: [{ name, copies, sessions, rss, duplicate }] }
+// An instance is the whole tree of one server (npx, its shell and the node process count once).
+function findMcp(procs, owner, sessions) {
+  const byPid = new Map(procs.map(p => [p.pid, p]))
+  const kids = new Map()
+  for (const p of procs) {
+    if (!kids.has(p.ppid)) kids.set(p.ppid, [])
+    kids.get(p.ppid).push(p)
+  }
+  const roots = new Set(sessions.map(s => s.pid))
+  const candidate = p => owner.get(p.pid) !== undefined && !roots.has(p.pid) && isMcpCommand(p.cmd)
+  const cwdOf = new Map(sessions.map(s => [s.pid, s.cwd]))
+  // a server started through npx is a chain (npm exec, sh, node): only its top counts as the instance
+  const hasCandidateAncestor = p => {
+    let cur = byPid.get(p.ppid)
+    for (let i = 0; cur && i < 20 && owner.get(cur.pid) === owner.get(p.pid) && !roots.has(cur.pid); i++) {
+      if (candidate(cur)) return true
+      cur = byPid.get(cur.ppid)
+    }
+    return false
+  }
+  const instances = []
+  for (const p of procs) {
+    if (!candidate(p)) continue
+    if (hasCandidateAncestor(p)) continue
+    const stack = [p]
+    const seen = new Set()
+    let rss = 0
+    while (stack.length) {
+      const q = stack.pop()
+      if (seen.has(q.pid)) continue
+      seen.add(q.pid)
+      rss += q.rss || 0
+      for (const k of kids.get(q.pid) || []) if (owner.get(k.pid) === owner.get(p.pid)) stack.push(k)
+    }
+    const session = owner.get(p.pid)
+    instances.push({ session, pid: p.pid, name: serverName(p.cmd), signature: signature(p.cmd, cwdOf.get(session)), rss, procs: seen.size })
+  }
+  const bySig = new Map()
+  for (const i of instances) {
+    if (!bySig.has(i.signature)) bySig.set(i.signature, [])
+    bySig.get(i.signature).push(i)
+  }
+  const groups = [...bySig.values()].map(list => {
+    const sessionPids = [...new Set(list.map(i => i.session))].sort((a, b) => a - b)
+    return {
+      name: list[0].name,
+      signature: list[0].signature,
+      copies: list.length,
+      sessions: sessionPids,
+      rss: list.reduce((n, i) => n + i.rss, 0),
+      duplicate: list.length >= 2 && sessionPids.length >= 2,
+    }
+  }).sort((a, b) => b.rss - a.rss)
+  return { instances, groups }
+}
+
+module.exports = { isMcpCommand, serverName, signature, findMcp, mentionsMcp }

package/src/memory-guard.js

@@ -1,8 +1,9 @@
 'use strict'
-const { runHook, blocked } = require('./hook')
+const { runHook, blocked, setting } = require('./hook')
 const { readMemory } = require('./memory')
 const { limits } = require('./slots')
 const shell = require('./shell')
+const queue = require('./auto-queue')
 
 // Commands that commonly take several GB of RAM: test runners with workers, full builds,
 // bundlers, emulators and browsers. Each test gets the command's words with wrappers taken off.
@@ -32,13 +33,16 @@ const HEAVY_BINS = {
   webpack: argv => !quiet(argv) && sub(argv) !== 'serve',
   ffmpeg: argv => !quiet(argv) && argv.length > 1,
   cargo: argv => /^(?:build|b|test|t|bench)$/.test(sub(argv)),
-  go: argv => sub(argv) === 'test' && has(argv, /\/\.\.\.$|^\.\.\.$/),
+  go: argv => /^(?:test|build)$/.test(sub(argv)) && has(argv, /\/\.\.\.$|^\.\.\.$|^-race$/),
+  xcodebuild: argv => has(argv, /^(?:-project|-workspace|-scheme|build|test|archive|build-for-testing|test-without-building)$/),
+  swift: argv => /^(?:build|test)$/.test(sub(argv)),
+  fastlane: argv => !quiet(argv) && !/^(?:lanes|env|help|actions|action|new_action|init)$/.test(sub(argv)) && argv.length > 1,
   pytest: argv => has(argv, /^(?:-n\d*|--numprocesses(?:=.*)?)$/),
   docker: argv => /^(?:build|buildx)$/.test(sub(argv)) || (sub(argv) === 'compose' && has(argv, /^(?:up|build)$/)),
   'docker-compose': argv => has(argv, /^(?:up|build)$/),
   bazel: argv => /^(?:build|test|run)$/.test(sub(argv)),
   turbo: argv => has(argv, /^(?:build|test)$/),
-  nx: argv => /^(?:build|test|run-many|affected)$/.test(sub(argv)),
+  nx: argv => /^(?:build|test|e2e|run|run-many|affected)$/.test(sub(argv)),
 }
 const RUNNERS = /^(?:npm|pnpm|yarn|bun)$/
 // npx vitest, pnpm exec jest, yarn dlx, bunx, python -m pytest, node node_modules/.bin/jest
@@ -49,6 +53,7 @@ function realCommand(argv) {
       const at = argv.findIndex((a, k) => k > 0 && !a.startsWith('-'))
       argv = at > 0 ? argv.slice(at) : []
     } else if (RUNNERS.test(b) && /^(?:exec|dlx|x)$/.test(argv[1])) argv = argv.slice(2)
+    else if (b === 'bundle' && argv[1] === 'exec') argv = argv.slice(2)
     else if (/^python[\d.]*$|^py$/.test(b) && argv[1] === '-m' && argv[2]) argv = argv.slice(2)
     else if (b === 'node' && argv[1] && /node_modules[\\/]/.test(argv[1])) argv = argv.slice(1)
     else break
@@ -78,18 +83,41 @@ const LAUNCH = /\b(?:chromium|firefox|webkit|puppeteer)\.launch\b|\blaunchPersis
 // Commands that only read or search text: grep -rn vitest package.json
 const INERT = /^(?:git|grep|egrep|rg|ag|echo|printf|cat|less|head|tail|ls|find|which|where|type|select-string|get-content|gc|write-host|write-output)$/i
 
-function isHeavy(cmd, mode = 'sh') {
+// Heavy commands that stay up until stopped: a slot would be held for as long as they run.
+const LONG_RUNNING = {
+  next: argv => sub(argv) === 'dev',
+  emulator: () => true,
+  karma: () => true,
+  docker: argv => !has(argv, /^(?:-d|--detach)$/),
+  'docker-compose': argv => !has(argv, /^(?:-d|--detach)$/),
+}
+const isLong = argv => {
+  const real = realCommand(argv)
+  const f = real.length && LONG_RUNNING[shell.bin(real[0])]
+  return Boolean(f && f(real) && (shell.bin(real[0]) !== 'docker' || sub(real) === 'compose'))
+}
+
+// The first heavy command in the line: { name, argv, long }, plus remote: true when any part of
+// the line runs on another machine. null when nothing is heavy. name keys the GB estimate.
+function findHeavy(cmd, mode = 'sh') {
   const text = shell.prepare(String(cmd || ''), mode)
+  let found = null
+  let remote = false
   for (const c of shell.commands(text, mode)) {
     const b = shell.bin(c.argv[0])
-    if (INERT.test(b) || c.remote) continue
+    if (c.remote) remote = true
+    if (found || INERT.test(b) || c.remote) continue
     if (/^bulkhead(?:-slot)?$/.test(b)) continue
-    if (heavyArgv(c.argv)) return true
-    if (LAUNCH.test(c.argv.join(' '))) return true
+    if (heavyArgv(c.argv)) {
+      const real = realCommand(c.argv)
+      found = { name: shell.bin(real[0]), argv: real, long: isLong(c.argv) }
+    } else if (LAUNCH.test(c.argv.join(' '))) found = { name: 'browser', argv: ['browser'], long: false }
   }
-  return false
+  return found && { ...found, remote }
 }
 
+const isHeavy = (cmd, mode = 'sh') => Boolean(findHeavy(cmd, mode))
+
 const SLOT_FILE = /bulkhead[\\/]+slots|slot-\d+\.json/i
 const WRITES = /(?:>{1,2}\|?|\b(?:touch|rm|del|unlink|mv|cp|Remove-Item|Set-Content|Add-Content|Out-File|New-Item|Clear-Content|Move-Item|Copy-Item|writeFileSync|unlinkSync|rmSync|utimesSync)\b)/i
 
@@ -114,32 +142,106 @@ function hasRemote() {
   }
 }
 
-function check(cmd, memory = () => readMemory(), minFreeGb, mode = 'sh', remote = hasRemote) {
+// Claude sessions that are running now, this one included; null when the session files cannot be read.
+function liveSessions() {
+  try {
+    const { readSessionFiles } = require('./sessions')
+    const { staleReason } = require('./slots')
+    return [...readSessionFiles().keys()].filter(pid => !staleReason({ pid, at: Date.now() })).length
+  } catch {
+    return null
+  }
+}
+
+// Where the minimum comes from, in a few words.
+function minimumSource(minFreeGb, totalGb) {
+  if (setting('memory.minFreeGb', null) != null) return 'set in your config'
+  if (minFreeGb >= 3) return 'the 3 GB default'
+  return `15% of this machine's ${Math.round(totalGb)} GB`
+}
+
+function slotLine(cmd, mode, overrides) {
+  const found = findHeavy(cmd, mode)
+  const gb = queue.estimateGb(found ? found.name : '', overrides)
+  const text = String(cmd).trim()
+  const arg = text.length <= 160 && !/[\r\n]/.test(text) && mode === 'sh' ? queue.quoters.sh(text) : '<command>'
+  return `bulkhead-slot run --gb=${gb} -- ${arg}`
+}
+
+function check(cmd, memory = () => readMemory(), minFreeGb, mode = 'sh', remote = hasRemote, sessions = liveSessions) {
   if (!cmd) return null
   if (touchesSlotFiles(cmd)) {
     return '[bulkhead] memory-guard: slot files are managed by bulkhead-slot. Do not write, touch or delete them by hand; ' +
       'use `bulkhead-slot run --gb=N -- <command>`, which releases its slot when the command exits. `bulkhead-slot status` shows the holders.'
   }
   if (queued(cmd) || !isHeavy(cmd, mode)) return null
-  const { freeGb, totalGb } = memory()
+  const { freeGb, totalGb, pressure } = memory()
   if (minFreeGb == null) minFreeGb = limits(totalGb).minFreeGb
-  if (freeGb >= minFreeGb) return null
-  return `[bulkhead] memory-guard: only ${freeGb.toFixed(1)} GB of RAM is free (minimum ${minFreeGb} GB) and this looks like a heavy command.\n` +
-    'Other sessions are probably building or testing right now. Starting more work at this point is how machines freeze.\n' +
-    'Either wait a minute and retry with fewer workers (for example --maxWorkers=2), or queue it:\n' +
-    '  bulkhead-slot run --gb=3 -- <command>\n' +
+  // macOS says outright how stressed memory is; a low estimate with normal pressure is not a reason to block
+  if (freeGb >= minFreeGb && !(pressure >= 2)) return null
+  const n = sessions()
+  const who = n > 1 ? `${n} Claude sessions are running and may be building or testing too.`
+    : n === 1 ? 'Only this session is running, so other programs are using the RAM.' : ''
+  const why = pressure >= 2 ? `memory pressure is ${pressure >= 4 ? 'critical' : 'warning'}`
+    : `only ${freeGb.toFixed(1)} GB of RAM is free (minimum ${minFreeGb} GB: ${minimumSource(minFreeGb, totalGb)})`
+  return `[bulkhead] memory-guard: ${why} and this looks like a heavy command.\n` +
+    (who ? who + '\n' : '') +
+    'Starting more work at this point is how machines freeze. Wait a minute, use fewer workers (for example --maxWorkers=2), or queue it:\n' +
+    `  ${slotLine(cmd, mode, setting('memoryGuard.estimatesGb', null))}\n` +
     'bulkhead-slot waits until there is room, runs the command, and frees the slot when it exits.' +
     (remote() ? '\nOr run it on another machine, so it uses that machine\'s RAM:\n  bulkhead remote run -- <command>' : '')
 }
 
-if (require.main === module) {
-  runHook('memory-guard', input => {
-    const cmd = input.tool_input && input.tool_input.command
-    if (typeof cmd !== 'string') return
-    const why = check(cmd, undefined, undefined, shell.modeFor(input))
-    if (!why) return
-    return blocked('memory-guard', touchesSlotFiles(cmd) ? 'slot-files' : 'low-memory', input, why)
-  })
+// { rule, message } with the rule name the hook logs, or null.
+function decide(cmd, memory, minFreeGb, mode, remote) {
+  const message = check(cmd, memory, minFreeGb, mode, remote)
+  return message ? { rule: touchesSlotFiles(cmd) ? 'slot-files' : 'low-memory', message } : null
+}
+
+// With memoryGuard.autoQueue on, a heavy command is not blocked: the hook rewrites it to run through
+// bulkhead-slot, whatever the free RAM is, so every session waits in the same line. Returns
+// { command, gb, label } or null when the command stays as it is (not heavy, already queued, in
+// the background, on another machine, long-running, or the slot script cannot be found).
+function autoQueue(input, o = {}) {
+  const ti = (input && input.tool_input) || {}
+  const cmd = ti.command
+  if (typeof cmd !== 'string' || !cmd.trim() || ti.run_in_background === true) return null
+  const mode = shell.modeFor(input)
+  if (queue.wrapped(cmd) || touchesSlotFiles(cmd) || queue.backgrounded(cmd, mode)) return null
+  const found = findHeavy(cmd, mode)
+  if (!found || found.long || found.remote) return null
+  const script = o.script !== undefined ? o.script : queue.slotScript()
+  if (!script) return null
+  const gb = queue.estimateGb(found.name, o.estimates)
+  const label = queue.labelFor(found.argv)
+  const command = queue.wrap(cmd, { shell: mode, script, gb, label, wait: o.wait, node: o.node, env: o.env, exists: o.exists, platform: o.platform })
+  return command ? { command, gb, label } : null
 }
 
-module.exports = { check, isHeavy, touchesSlotFiles }
+function queueOutput(input, q) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      updatedInput: { ...input.tool_input, command: q.command },
+      additionalContext: `bulkhead queued this command (${q.label}, about ${q.gb} GB): it starts when the machine has room and prints its position every 30 s.`,
+    },
+  }
+}
+
+function handle(input) {
+  const cmd = input.tool_input && input.tool_input.command
+  if (typeof cmd !== 'string') return
+  // other agents' hooks cannot rewrite a command (bulkhead hook --agent), so they get the plain check
+  if (setting('memoryGuard.autoQueue', false) === true && !process.env.BULKHEAD_AGENT && !touchesSlotFiles(cmd)) {
+    const q = autoQueue(input, { estimates: setting('memoryGuard.estimatesGb', null), wait: setting('memoryGuard.waitMinutes', 10) })
+    // no permissionDecision: the user's permission settings still apply to the rewritten command
+    if (q) return { output: queueOutput(input, q) }
+  }
+  const hit = decide(cmd, undefined, undefined, shell.modeFor(input))
+  if (!hit) return
+  return blocked('memory-guard', hit.rule, input, hit.message)
+}
+
+if (require.main === module) runHook('memory-guard', handle)
+
+module.exports = { handle, check, decide, isHeavy, findHeavy, touchesSlotFiles, autoQueue, queueOutput }

package/src/memory.js

@@ -41,6 +41,17 @@ function parseVmStat(text, totalBytes) {
   return { totalGb: totalBytes / GB, freeGb: Math.max(0, freeBytes) / GB, commitPct: null }
 }
 
+// macOS: kern.memorystatus_level is the percentage of memory the system counts as free,
+// reclaimable file cache and compressed pages included (what `memory_pressure` prints as
+// "System-wide memory free percentage"). The vm_stat estimate above misses the reclaimable
+// cache and read 7.7 GB free on a 48 GB Mac that `memory_pressure` called 62% free.
+// pressure is kern.memorystatus_vm_pressure_level: 1 normal, 2 warning, 4 critical.
+function parseDarwinLevel(text, totalBytes) {
+  const [level, pressure] = String(text).trim().split(/\s+/).map(Number)
+  if (!(level >= 0 && level <= 100)) return null
+  return { totalGb: totalBytes / GB, freeGb: (totalBytes / GB) * (level / 100), commitPct: null, pressure: [1, 2, 4].includes(pressure) ? pressure : null }
+}
+
 // Windows: commit charge can run out while RAM still looks "free", and the machine stalls when it does.
 function parseWindowsCommit(text) {
   const [total, free] = String(text).trim().split(/\s+/).map(Number)
@@ -57,7 +68,8 @@ function windowsCommitPct(run) {
   }
 }
 
-const defaultRun = (file, args) => execFileSync(file, args, { encoding: 'utf8', timeout: 8000, windowsHide: true })
+// vm_stat and sysctl answer in milliseconds; only PowerShell is slow, so only it gets the long wait.
+const defaultRun = (file, args) => execFileSync(file, args, { encoding: 'utf8', timeout: /powershell/i.test(file) ? 8000 : 1500, windowsHide: true })
 
 // { totalGb, freeGb, commitPct } where commitPct is measured only on Windows and only on request.
 function readMemory({ platform = process.platform, withCommit = false, run = defaultRun, readFile = fs.readFileSync } = {}) {
@@ -66,11 +78,18 @@ function readMemory({ platform = process.platform, withCommit = false, run = def
     try { return parseMeminfo(readFile('/proc/meminfo', 'utf8')) } catch {}
   }
   if (platform === 'darwin') {
+    try {
+      const m = parseDarwinLevel(run('sysctl', ['-n', 'kern.memorystatus_level', 'kern.memorystatus_vm_pressure_level']), os.totalmem())
+      if (m) return m
+    } catch {}
     try { return parseVmStat(run('vm_stat', []), os.totalmem()) } catch {}
+    // os.freemem() counts only never-used pages, near zero on a healthy Mac: with no usable
+    // reading, say everything is free so a guard allows the command instead of blocking it.
+    return { totalGb: os.totalmem() / GB, freeGb: os.totalmem() / GB, commitPct: null, pressure: null, unknown: true }
   }
   const mem = { totalGb: os.totalmem() / GB, freeGb: os.freemem() / GB, commitPct: null }
   if (platform === 'win32' && withCommit) mem.commitPct = windowsCommitPct(run)
   return mem
 }
 
-module.exports = { readMemory, parseMeminfo, parseVmStat, parseWindowsCommit }
+module.exports = { readMemory, parseMeminfo, parseVmStat, parseDarwinLevel, parseWindowsCommit }

package/src/notices.js

@@ -0,0 +1,95 @@
+'use strict'
+// What the user sees at SessionStart: what orphan-reaper stopped since the last notice, and one
+// line the first time bulkhead runs. Both live as small files in the state dir. Every function
+// fails open and returns nothing on any error.
+const fs = require('fs')
+const path = require('path')
+const { shortPath } = require('./cli-util')
+
+const PENDING = 'reaped-pending.jsonl'
+const FIRST_RUN = 'first-run'
+const MAX_SHOWN = 3
+const MAX_PENDING_BYTES = 64 * 1024
+
+const FIRST_RUN_TEXT = 'bulkhead is on: it blocks commands that would hit other Claude Code sessions. See what it did: bulkhead log. Check your setup: bulkhead doctor.'
+
+// "vite", "node srv.js", "python3 app.py": the program and the script it runs, not the whole line.
+function label(cmd, name) {
+  const words = String(cmd || name || '').trim().match(/"[^"]*"|'[^']*'|\S+/g) || []
+  const base = w => String(w).replace(/^["']|["']$/g, '').split(/[\\/]/).pop().replace(/\.exe$/i, '')
+  const prog = base(words[0]) || base(name) || 'process'
+  const arg = words.slice(1).find(w => !w.startsWith('-'))
+  if (!arg) return prog
+  const bin = /node_modules[\\/](?:\.bin|[^\\/]+[\\/]bin)[\\/]/.test(arg) ? base(arg).replace(/\.m?js$/, '') : null
+  if (bin) return bin
+  return `${prog} ${base(arg)}`
+}
+
+// done: the { orphan, pids } list run() stops; ports: [{ port, pid }] from the same process table.
+function items(done, ports = [], projectOf = () => null) {
+  return done.map(({ orphan: o, pids }) => {
+    const hit = ports.find(l => pids.includes(l.pid))
+    return { label: label(o.cmd, o.name), port: hit ? hit.port : null, project: projectOf(o) }
+  })
+}
+
+function append(dir, list, now = Date.now()) {
+  if (!list.length) return false
+  try {
+    const file = path.join(dir, PENDING)
+    let size = 0
+    try { size = fs.statSync(file).size } catch {}
+    if (size > MAX_PENDING_BYTES) return false
+    fs.mkdirSync(dir, { recursive: true })
+    fs.appendFileSync(file, list.map(i => JSON.stringify({ time: now, ...i })).join('\n') + '\n')
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Takes the pending list: renaming first means two sessions starting together never both print it.
+function claim(dir) {
+  const file = path.join(dir, PENDING)
+  const mine = `${file}.${process.pid}`
+  try {
+    fs.renameSync(file, mine)
+  } catch {
+    return []
+  }
+  try {
+    return fs.readFileSync(mine, 'utf8').split('\n').flatMap(l => {
+      try { return [JSON.parse(l)] } catch { return [] }
+    })
+  } catch {
+    return []
+  } finally {
+    try { fs.unlinkSync(mine) } catch {}
+  }
+}
+
+function format(list, home) {
+  if (!list.length) return null
+  const shown = list.slice(0, MAX_SHOWN).map(i => {
+    const where = i.project ? ` (${shortPath(i.project, home)})` : ''
+    return `${i.label}${i.port ? ` :${i.port}` : ''}${where}`
+  })
+  const more = list.length > MAX_SHOWN ? `, and ${list.length - MAX_SHOWN} more` : ''
+  const n = list.length
+  return `bulkhead stopped ${n} leftover${n === 1 ? '' : 's'} from ended sessions: ${shown.join(', ')}${more}. Keep one next time with BULKHEAD_KEEP=1. Details: bulkhead log --guard orphan-reaper`
+}
+
+// The first-run line once, and only once: the marker is created before anything is printed. A state
+// dir that already has a log belongs to an install from before this notice, and gets no line.
+function firstRun(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const used = ['guards.log', 'events.jsonl'].some(n => fs.existsSync(path.join(dir, n)))
+    fs.writeFileSync(path.join(dir, FIRST_RUN), `${new Date().toISOString()}\n`, { flag: 'wx' })
+    return used ? null : FIRST_RUN_TEXT
+  } catch {
+    return null
+  }
+}
+
+module.exports = { label, items, append, claim, format, firstRun, FIRST_RUN_TEXT, PENDING, FIRST_RUN }

package/src/orphan-reaper.js

@@ -3,7 +3,8 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 const { execFileSync, spawn } = require('child_process')
-const { enabled, setting, log, oneLine, recordEvent } = require('./hook')
+const { enabled, setting, log, oneLine, recordEvent, stateDir } = require('./hook')
+const notices = require('./notices')
 const { readSessionFiles, claudeDir } = require('./sessions')
 const { readProcesses } = require('./processes')
 
@@ -64,6 +65,32 @@ const RULES = [
 
 // Never stopped, nor anything they started, even under an orphaned shell: programs meant to
 // outlive the session, and daemons that other sessions share.
+const KEEP_TOKEN = /(?:^|[\s"'])BULKHEAD_KEEP=(?:1|true|yes)(?=["'\s]|$)/i
+
+// ssh options that take a value (in the next word, or the rest of the same word) and the ones that
+// open a forward or a tunnel only
+const SSH_VALUE_OPTS = new Set('BbcDEeFIiJLlmOopQRSWw')
+const SSH_FORWARD_OPTS = new Set('DLRN')
+
+// true when an ssh command line opens a port forward or a tunnel only (-L, -R, -D, -N). The value
+// of an option such as `-o StrictHostKeyChecking=no` is skipped, not read as flags.
+function sshForwards(cmd) {
+  const words = String(cmd).trim().split(/\s+/).slice(1)
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]
+    if (!w.startsWith('-')) break
+    if (w.startsWith('--')) continue
+    for (let j = 1; j < w.length; j++) {
+      if (SSH_FORWARD_OPTS.has(w[j])) return true
+      if (SSH_VALUE_OPTS.has(w[j])) {
+        if (j === w.length - 1) i++
+        break
+      }
+    }
+  }
+  return false
+}
+
 const KEEP = [
   { what: 'Claude Code itself', test: p => isClaude(p), reason: 'A session started from a tool shell is a live session of its own.' },
   { what: 'orphan-reaper itself', cmd: /orphan-reaper\.js/, reason: 'The reaper and its waiters.' },
@@ -79,6 +106,18 @@ const KEEP = [
     test: (p, name) => /^(?:vbcscompiler|bazel|buck2d|sccache)$/i.test(name) ||
       /org\.gradle\.launcher\.daemon|GradleDaemon|KotlinCompileDaemon|org\.jetbrains\.kotlin\.daemon|[\\/]nx[\\/]src[\\/]daemon[\\/]|\bturbo(?:\.exe)?["']?\s+daemon\b|MSBuild\.(?:dll|exe)["']?\s.*\/nodemode/i.test(p.cmd),
     reason: 'Builds in every session connect to the same daemon; stopping it breaks theirs.' },
+  { what: 'Anything started with `BULKHEAD_KEEP=1`', test: p => p.keep === true || KEEP_TOKEN.test(p.cmd),
+    reason: 'You marked it as meant to outlive the session.' },
+  { what: 'ssh tunnels and port forwards (`ssh -L`, `-R`, `-D`, `-N`), autossh, cloudflared, ngrok, Tailscale, frp',
+    test: (p, name) => (/^ssh$/i.test(name) && sshForwards(p.cmd)) || /^(?:autossh|cloudflared|ngrok|tailscale|tailscaled|frpc|frps)$/i.test(name),
+    reason: 'A tunnel is opened on purpose and nothing else reconnects it.' },
+  { what: 'Databases and local services (Postgres, MySQL, MariaDB, MongoDB, Redis, Valkey, Memcached, Jupyter, code-server, Syncthing)',
+    test: (p, name) => /^(?:postgres|postmaster|mysqld|mysqld_safe|mariadbd|mongod|mongos|redis-server|redis-sentinel|valkey-server|memcached|code-server|syncthing)$/i.test(name) ||
+      /(?:^|[\s\\/])jupyter(?:-lab|-notebook|-server|lab)?(?=["'\s]|$)/i.test(p.cmd),
+    reason: 'Local services that other projects and sessions use.' },
+  { what: 'Container runtimes (Colima, Lima, OrbStack, Podman)',
+    name: /^(?:colima|limactl|lima|orbstack|orbstack helper|podman|vfkit|krunkit)$/i,
+    reason: 'One runtime serves every session on the machine.' },
   { what: 'Shared machine services (adb, the Android emulator, Docker, Ollama, watchman, ssh-agent, gpg-agent)',
     name: /^(?:adb|emulator|emulator64-\w+|qemu-system-[\w-]+|dockerd|docker|containerd|com\.docker\.[\w.-]+|ollama|watchman|ssh-agent|gpg-agent)$/i,
     reason: 'One instance serves every session on the machine.' },
@@ -111,13 +150,16 @@ function matchesSpec(spec, p, name) {
   return Boolean(spec.test)
 }
 
-function keeper(keepNames = []) {
+// keepNames: program names; keepPatterns: text that, found in a command line, keeps the process.
+function keeper(keepNames = [], keepPatterns = []) {
   const extra = new Set(keepNames.map(n => baseName(n).toLowerCase()))
+  const patterns = keepPatterns.map(x => String(x).toLowerCase()).filter(Boolean)
   const cache = new Map()
   return p => {
     if (!cache.has(p.pid)) {
       const name = baseName(p.name)
-      cache.set(p.pid, extra.has(name.toLowerCase()) || KEEP.some(k => matchesSpec(k, p, name)))
+      const cmd = String(p.cmd || '').toLowerCase()
+      cache.set(p.pid, extra.has(name.toLowerCase()) || patterns.some(x => cmd.includes(x)) || KEEP.some(k => matchesSpec(k, p, name)))
     }
     return cache.get(p.pid)
   }
@@ -264,7 +306,7 @@ function findOrphans({ procs, listening = new Set() }, now = Date.now(), opts =
     now,
     session: opts.session || null,
     platform: opts.platform || process.platform,
-    isKept: keeper(opts.keepNames),
+    isKept: keeper(opts.keepNames, opts.keepPatterns),
     snapshotExists: opts.snapshotExists || snapshotExists,
     liveClaudeStarts: procs.filter(isClaude).map(p => p.start),
     live: liveSnapshots(procs, byPid),
@@ -344,8 +386,8 @@ function killPids(pids, platform = process.platform) {
 // Stops every orphan's tree and returns { orphan, pids } for each. On Windows a second look stops
 // children that a dying process started after the first snapshot; elsewhere they are reparented
 // and the next pass finds them through CLAUDE_PID.
-function reapAll(orphans, procs, { platform = process.platform, keepNames = [], reread = null } = {}) {
-  const isKept = keeper(keepNames)
+function reapAll(orphans, procs, { platform = process.platform, keepNames = [], keepPatterns = [], reread = null } = {}) {
+  const isKept = keeper(keepNames, keepPatterns)
   const byPid = new Map(procs.map(p => [p.pid, p]))
   const done = []
   const killed = new Map()
@@ -381,6 +423,7 @@ function settings() {
   return {
     extraNames: setting('orphanReaper.extraNames', []),
     keepNames: setting('orphanReaper.keepNames', []),
+    keepPatterns: setting('orphanReaper.keepPatterns', []),
   }
 }
 
@@ -394,19 +437,23 @@ function run({ platform = process.platform, dryRun = false, session = null, trig
   const snapshot = snap || snapshotNow(platform)
   const orphans = findOrphans(snapshot, Date.now(), { ...opts, session, platform })
   if (dryRun) {
-    const isKept = keeper(opts.keepNames)
+    const isKept = keeper(opts.keepNames, opts.keepPatterns)
     return orphans.map(o => ({ orphan: o, pids: [...new Set([...descendants(o.top, snapshot.procs, isKept), o.pid])] }))
   }
-  const done = reapAll(orphans, snapshot.procs, { platform, keepNames: opts.keepNames, reread: () => snapshotNow(platform) })
+  const done = reapAll(orphans, snapshot.procs, { platform, keepNames: opts.keepNames, keepPatterns: opts.keepPatterns, reread: () => snapshotNow(platform) })
   const files = done.length && !project ? readSessionFiles() : new Map()
-  for (const { orphan: o, pids } of done) {
+  const projectFor = o => project || projectOf(o.owner, files)
+  const shown = notices.items(done, snapshot.ports, projectFor)
+  done.forEach(({ orphan: o, pids }, i) => {
     log('orphan-reaper', `stopped ${o.rule} pid ${o.pid} (tree ${o.top}, ${pids.length} processes; ${o.why}) ${oneLine(o.cmd || o.name, 160)}`)
     recordEvent('orphan-reaper', o.rule, { session_id: sessionId }, o.cmd || o.name, {
-      project: project || projectOf(o.owner, files),
+      project: projectFor(o),
       pid: o.pid,
+      port: shown[i].port,
       trigger,
     })
-  }
+  })
+  if (trigger !== 'manual') notices.append(stateDir(), shown)
   return done
 }