claude-bulkhead 0.0.0-stage → 0.2.2

package/src/port-guard.js

@@ -0,0 +1,142 @@
+'use strict'
+const net = require('net')
+const os = require('os')
+const { runHook, blocked, setting, oneLine } = require('./hook')
+const { detect } = require('./dev-servers')
+const { readProcesses } = require('./processes')
+const { readSessionFiles, findSessions, ownSession } = require('./sessions')
+const shell = require('./shell')
+
+// The command with heredoc bodies, commit messages and shell wrappers (bash -c "...") resolved.
+const opened = (cmd, mode = 'sh') => shell.unwrap(shell.prepare(String(cmd || ''), mode), mode)
+
+function freePort(port, taken) {
+  for (let p = port + 1; p < port + 200 && p < 65536; p++) if (!taken.has(p)) return p
+  return null
+}
+
+function shortPath(p) {
+  const home = os.homedir()
+  return p && p.toLowerCase().startsWith(home.toLowerCase()) ? '~' + p.slice(home.length).replace(/\\/g, '/') : p || 'unknown directory'
+}
+
+// A connect attempt takes a few milliseconds; reading the process list takes a second or two
+// on Windows, so we only read it when something answers on the port.
+function listening(port, timeoutMs = 300) {
+  const one = host => new Promise(resolve => {
+    const sock = net.connect({ host, port })
+    const done = ok => { sock.destroy(); resolve(ok) }
+    sock.setTimeout(timeoutMs, () => done(false))
+    sock.once('connect', () => done(true))
+    sock.once('error', () => done(false))
+  })
+  return Promise.all([one('127.0.0.1'), one('::1')]).then(r => r.some(Boolean))
+}
+
+// Resolves to a block message, or null. Anything we cannot pin down is allowed.
+async function check(cmd, {
+  cwd, probe = listening, snapshot = () => readProcesses(), files = () => readSessionFiles(), self = ownSession, ignore = setting('portGuard.ignorePorts', []), mode = 'sh',
+} = {}) {
+  const server = detect(opened(cmd, mode), { cwd })
+  if (!server || !server.port || ignore.includes(server.port)) return null
+  if (!(await probe(server.port))) return null
+  const snap = snapshot()
+  if (!snap) return null
+  const holder = snap.ports.find(l => l.port === server.port)
+  if (!holder) return null
+  const owner = findSessions(snap, files()).find(s => s.ports.some(l => l.pid === holder.pid))
+  if (!owner) return null
+  const me = self(snap.procs)
+  if (!me || me === owner.pid) return null
+  const name = (snap.procs.find(p => p.pid === holder.pid) || {}).name || 'a process'
+  const free = freePort(server.port, new Set(snap.ports.map(l => l.port)))
+  return `[bulkhead] port-guard: port ${server.port} is already used by another Claude session ` +
+    `(session pid ${owner.pid}, ${shortPath(owner.cwd)}): ${name} pid ${holder.pid}.\n` +
+    'Leave that server alone; it is the other session\'s work. If you start yours anyway, it either fails or moves to the ' +
+    `next port, and requests to localhost:${server.port} reach the other project.\n` +
+    (free ? `Port ${free} is free:\n  ${server.hint(free)}` : `Pick a free port and pass it explicitly; \`bulkhead port --near ${server.port}\` prints one.`)
+}
+
+const numbers = s => (String(s).match(/\d+/g) || []).map(Number).filter(n => n > 0 && n < 65536)
+const KILLS = /\b(?:kill|taskkill|Stop-Process|spps)\b(?!-port)/i
+
+// Ports a kill-by-port command aims at, or [] when the command does not kill by port.
+// Statements are split on ; && || and newlines, but not on pipes, which carry the PID along.
+function killPorts(cmd) {
+  const ports = new Set()
+  const add = list => list.forEach(p => ports.add(p))
+  for (const st of String(cmd || '').split(/\n|;|&&|\|\|/)) {
+    // npx kill-port 3000 3001, npx kill-port --port 3000,3001
+    const kp = /\bkill-port\b((?:\s+(?:--port\b|-p\b|[\d,]+)(?:[=\s]+[\d,]+)?)+)/i.exec(st)
+    if (kp) add(numbers(kp[1]))
+    // fuser -k 3000/tcp, fuser -k -n tcp 3000
+    if (/\bfuser\b/.test(st) && /(?:^|\s)-[a-zA-Z]*k/.test(st)) {
+      add([...st.matchAll(/\b(\d+)\/tcp\b/gi)].map(m => Number(m[1])))
+      const n = /-n\s+tcp\s+(\d+)/i.exec(st)
+      if (n) add([Number(n[1])])
+    }
+    // lsof -ti :3000 | xargs kill -9, kill $(lsof -t -i:3000)
+    if (/\blsof\b/.test(st) && /\blsof\b[^|)`]*\s-[a-zA-Z]*t/.test(st) && KILLS.test(st.replace(/\blsof\b[^|)`]*/g, ' '))) {
+      add([...st.matchAll(/-[a-zA-Z]*i\s*(?:tcp|TCP)?:(\d+)/g)].map(m => Number(m[1])))
+    }
+    // Stop-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess
+    if (/Get-NetTCPConnection/i.test(st) && KILLS.test(st)) {
+      const lp = /-LocalPort\s+((?:\d+\s*,\s*)*\d+)/i.exec(st)
+      if (lp) add(numbers(lp[1]))
+    }
+    // netstat -ano | findstr :3000 ... taskkill /PID, for /f ... in ('netstat -aon ^| findstr :3000') do taskkill
+    if (/\bnetstat\b/i.test(st) && KILLS.test(st)) {
+      const f = /\b(?:findstr|grep|Select-String)\b[^|]*?:(\d+)/i.exec(st)
+      if (f) add([Number(f[1])])
+    }
+  }
+  return [...ports].filter(p => p > 0 && p < 65536)
+}
+
+// Resolves to a block message when a kill by port would hit another live session's server.
+async function checkKill(cmd, {
+  probe = listening, snapshot = () => readProcesses(), files = () => readSessionFiles(), self = ownSession, ignore = setting('portGuard.ignorePorts', []), mode = 'sh',
+} = {}) {
+  const ports = killPorts(opened(cmd, mode)).filter(p => !ignore.includes(p))
+  if (!ports.length) return null
+  const live = []
+  for (const p of ports) if (await probe(p)) live.push(p)
+  if (!live.length) return null
+  const snap = snapshot()
+  if (!snap) return null
+  const sessions = findSessions(snap, files())
+  const me = self(snap.procs)
+  if (!me) return null
+  for (const port of live) {
+    for (const holder of snap.ports.filter(l => l.port === port)) {
+      const owner = sessions.find(s => s.ports.some(l => l.pid === holder.pid))
+      if (!owner || owner.pid === me) continue
+      const name = (snap.procs.find(p => p.pid === holder.pid) || {}).name || 'a process'
+      const free = freePort(port, new Set(snap.ports.map(l => l.port)))
+      return {
+        port,
+        message: `[bulkhead] port-guard: \`${oneLine(cmd, 120)}\` would stop ${name} pid ${holder.pid}, the server another Claude session ` +
+          `runs on port ${port} (session pid ${owner.pid}, ${shortPath(owner.cwd)}).\n` +
+          'That server is the other session\'s work. Stopping it breaks whatever that session is running or testing.\n' +
+          (free ? `If you need a server of your own, start it on a free port instead: ${free} is free.\n` : 'If you need a server of your own, start it on another port.\n') +
+          `\`bulkhead port --near ${port}\` prints a port no session holds.\n` +
+          'To stop a process you started yourself, stop it by its PID.',
+      }
+    }
+  }
+  return null
+}
+
+if (require.main === module) {
+  runHook('port-guard', async input => {
+    const cmd = input.tool_input && input.tool_input.command
+    if (typeof cmd !== 'string' || !cmd) return
+    const mode = shell.modeFor(input)
+    const why = await check(cmd, { cwd: input.cwd, mode })
+    if (why) return blocked('port-guard', 'port-in-use', input, why)
+    const kill = await checkKill(cmd, { mode })
+    if (kill) return blocked('port-guard', 'kill-by-port', input, kill.message)
+  })
+}
+
+module.exports = { check, checkKill, killPorts, freePort, listening }

package/src/processes.js

@@ -0,0 +1,181 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { execFileSync } = require('child_process')
+
+// Every reader returns { procs: [{ pid, ppid, name, cmd, start, rss, claudePid }], listening: Set<pid>,
+// ports: [{ port, pid }] }. start is milliseconds since the epoch, rss is bytes, and claudePid is null
+// when the environment is unreadable.
+
+const WINDOWS_QUERY = `
+$procs = Get-CimInstance Win32_Process | ForEach-Object {
+  $t = 0; if ($_.CreationDate) { $t = ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() }
+  [pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId; name = $_.Name; cmd = $_.CommandLine; start = $t; rss = $_.WorkingSetSize }
+}
+$listen = @(Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue | ForEach-Object { [pscustomobject]@{ pid = $_.OwningProcess; port = $_.LocalPort } })
+[pscustomobject]@{ procs = @($procs); listen = $listen } | ConvertTo-Json -Compress -Depth 3
+`
+
+// IPv4 and IPv6 sockets on the same port show up twice.
+function uniquePorts(list) {
+  const seen = new Map()
+  for (const l of list) seen.set(`${l.pid}:${l.port}`, { port: Number(l.port), pid: Number(l.pid) })
+  return [...seen.values()].sort((a, b) => a.port - b.port)
+}
+
+function parseWindows(json) {
+  const data = JSON.parse(json)
+  const procs = [].concat(data.procs || []).map(p => ({
+    pid: p.pid, ppid: p.ppid, name: p.name || '', cmd: p.cmd || '', start: Number(p.start) || 0, rss: Number(p.rss) || 0, claudePid: null,
+  }))
+  const ports = uniquePorts([].concat(data.listen || []))
+  return { procs, listening: new Set(ports.map(l => l.pid)), ports }
+}
+
+function readWindows(run = execFileSync) {
+  const out = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_QUERY],
+    { encoding: 'utf8', windowsHide: true, timeout: 60000, maxBuffer: 64 * 1024 * 1024 })
+  return parseWindows(out)
+}
+
+// /proc/<pid>/stat: "pid (comm) state ppid ... starttime(22nd field) vsize rss(24th, in pages)".
+// comm may contain spaces and parens.
+function parseProcStat(text) {
+  const close = text.lastIndexOf(')')
+  const name = text.slice(text.indexOf('(') + 1, close)
+  const rest = text.slice(close + 2).split(' ')
+  return { name, ppid: Number(rest[1]), startTicks: Number(rest[19]), rssPages: Number(rest[21]) || 0 }
+}
+
+// Socket inode -> local port for sockets in LISTEN state (0A) from /proc/net/tcp and tcp6.
+function parseNetTcp(text) {
+  const inodes = new Map()
+  for (const line of text.split('\n').slice(1)) {
+    const f = line.trim().split(/\s+/)
+    if (f.length > 9 && f[3] === '0A') inodes.set(f[9], parseInt(f[1].split(':').pop(), 16))
+  }
+  return inodes
+}
+
+function envValue(environ, key) {
+  for (const kv of environ.split('\0')) if (kv.startsWith(key + '=')) return kv.slice(key.length + 1)
+  return null
+}
+
+const realFs = {
+  read: p => fs.readFileSync(p, 'utf8'),
+  list: p => fs.readdirSync(p),
+  link: p => fs.readlinkSync(p),
+}
+
+function readLinux(io = realFs, clockTicks = 100, pageSize = 4096) {
+  const bootMs = Number(io.read('/proc/stat').match(/^btime (\d+)/m)[1]) * 1000
+  const tryRead = p => { try { return io.read(p) } catch { return null } }
+  const listenInodes = new Map()
+  for (const f of ['/proc/net/tcp', '/proc/net/tcp6']) {
+    const t = tryRead(f)
+    if (t) for (const [inode, port] of parseNetTcp(t)) listenInodes.set(inode, port)
+  }
+  const procs = []
+  const ports = []
+  for (const entry of io.list('/proc').filter(e => /^\d+$/.test(e))) {
+    const stat = tryRead(`/proc/${entry}/stat`)
+    if (!stat) continue
+    const pid = Number(entry)
+    const s = parseProcStat(stat)
+    const argv = (tryRead(`/proc/${entry}/cmdline`) || '').split('\0')
+    const cmd = argv.join(' ').trim()
+    // comm is the main thread's name, and Node 24 names its main thread "MainThread": a node
+    // process, Claude Code's included, would no longer read as node. argv[0] names the program.
+    if (s.name === 'MainThread' && argv[0]) s.name = path.posix.basename(argv[0])
+    const environ = tryRead(`/proc/${entry}/environ`)
+    const claudePid = environ && Number(envValue(environ, 'CLAUDE_PID'))
+    procs.push({
+      pid, ppid: s.ppid, name: s.name, cmd, start: bootMs + (s.startTicks / clockTicks) * 1000,
+      rss: s.rssPages * pageSize, claudePid: claudePid || null,
+    })
+    if (!listenInodes.size) continue
+    let fds = []
+    try { fds = io.list(`/proc/${entry}/fd`) } catch {}
+    for (const fd of fds) {
+      let target = ''
+      try { target = io.link(path.posix.join(`/proc/${entry}/fd`, fd)) } catch {}
+      const m = /^socket:\[(\d+)\]$/.exec(target)
+      if (m && listenInodes.has(m[1])) ports.push({ pid, port: listenInodes.get(m[1]) })
+    }
+  }
+  const unique = uniquePorts(ports)
+  return { procs, listening: new Set(unique.map(l => l.pid)), ports: unique }
+}
+
+// `ps -o pid=,ppid=,rss=,lstart=,args=`: lstart is always five words, e.g. "Mon Oct 13 09:12:01 2026".
+function parsePs(text, names = new Map()) {
+  const procs = []
+  for (const line of text.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\w+ +\w+ +\d+ +[\d:]+ +\d+)\s*(.*)$/.exec(line)
+    if (!m) continue
+    const pid = Number(m[1])
+    const cmd = m[5].trim()
+    procs.push({
+      pid, ppid: Number(m[2]), name: names.get(pid) || path.basename(cmd.split(' ')[0] || ''), cmd,
+      start: new Date(m[4].replace(/ +/g, ' ')).getTime() || 0, rss: Number(m[3]) * 1024, claudePid: null,
+    })
+  }
+  return procs
+}
+
+// `lsof -nP -iTCP -sTCP:LISTEN -Fn`: "p<pid>" starts a process, "n<addr>:<port>" names a socket.
+function parseLsof(text) {
+  const ports = []
+  let pid = 0
+  for (const line of text.split('\n')) {
+    if (line[0] === 'p') pid = Number(line.slice(1))
+    else if (line[0] === 'n') {
+      const port = Number(line.slice(line.lastIndexOf(':') + 1))
+      if (pid && port) ports.push({ pid, port })
+    }
+  }
+  return uniquePorts(ports)
+}
+
+// `ps -E` appends each process's environment to its command line. macOS shows it only for the
+// user's own processes, which are the only ones a Claude tool shell can start. A CLAUDE_PID that
+// is not a whole word (no space or end after the digits) is ignored.
+function parsePsEnv(text) {
+  const out = new Map()
+  for (const line of text.split('\n')) {
+    const m = /^\s*(\d+)\s.*\sCLAUDE_PID=(\d+)(?=\s|$)/.exec(line)
+    if (m) out.set(Number(m[1]), Number(m[2]))
+  }
+  return out
+}
+
+function readMac(run = execFileSync, { withEnv = false } = {}) {
+  const opts = { encoding: 'utf8', timeout: 15000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } }
+  const names = new Map()
+  for (const line of run('ps', ['-axo', 'pid=,ucomm='], opts).split('\n')) {
+    const m = /^\s*(\d+)\s+(.*)$/.exec(line)
+    if (m) names.set(Number(m[1]), m[2].trim())
+  }
+  const procs = parsePs(run('ps', ['-axww', '-o', 'pid=,ppid=,rss=,lstart=,args='], opts), names)
+  if (withEnv) {
+    let env = new Map()
+    try { env = parsePsEnv(run('ps', ['-axwwE', '-o', 'pid=,command='], opts)) } catch {}
+    for (const p of procs) p.claudePid = env.get(p.pid) || null
+  }
+  let ports = []
+  // lsof exits 1 when nothing is listening
+  try { ports = parseLsof(run('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn'], opts)) } catch (e) { ports = parseLsof(String(e.stdout || '')) }
+  return { procs, listening: new Set(ports.map(l => l.pid)), ports }
+}
+
+function readProcesses(platform = process.platform, { withEnv = false } = {}) {
+  if (platform === 'win32') return readWindows()
+  if (platform === 'linux') return readLinux()
+  if (platform === 'darwin') return readMac(execFileSync, { withEnv })
+  return null
+}
+
+module.exports = {
+  readProcesses, parseWindows, readWindows, parseProcStat, parseNetTcp, readLinux, envValue, parsePs, parseLsof, readMac, parsePsEnv,
+}

package/src/reap-cli.js

@@ -0,0 +1,56 @@
+'use strict'
+const { useColor, paint, fit } = require('./cli-util')
+
+const USAGE = `usage: bulkhead reap [--dry-run] [--json]
+
+Stops what Claude Code sessions that have exited left running: dev servers and anything else
+listening, test runners and their workers, watchers, builders and automation browsers started
+from a Claude tool shell. orphan-reaper does the same in the background when a session starts
+and right after one ends; this runs it now.
+  --dry-run   list what would be stopped and why, stop nothing
+  --json      machine-readable output`
+
+function main(args, { stdout = process.stdout, stderr = process.stderr, platform = process.platform, run } = {}) {
+  if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
+  const unknown = args.filter(a => !['--dry-run', '--json'].includes(a))
+  if (unknown.length) {
+    stderr.write(`bulkhead reap: unknown option ${unknown[0]}\n${USAGE}\n`)
+    process.exitCode = 1
+    return
+  }
+  const reaper = require('./orphan-reaper')
+  const dryRun = args.includes('--dry-run')
+  const json = args.includes('--json')
+  if (!reaper.SUPPORTED.includes(platform)) {
+    if (json) stdout.write(JSON.stringify({ supported: false, platform, dryRun, orphans: [] }) + '\n')
+    else stderr.write(`bulkhead reap: ${platform} is not supported\n`)
+    process.exitCode = 1
+    return
+  }
+  let done
+  try {
+    done = (run || reaper.run)({ platform, dryRun, trigger: 'manual' })
+  } catch (e) {
+    stderr.write(`bulkhead reap: could not read the process table: ${String(e.message).split('\n')[0]}\n`)
+    process.exitCode = 1
+    return
+  }
+  if (json) {
+    const orphans = done.map(({ orphan: o, pids }) => ({ pid: o.pid, name: o.name, rule: o.rule, what: o.what, why: o.why, owner: o.owner, top: o.top, pids, command: o.cmd }))
+    stdout.write(JSON.stringify({ supported: true, dryRun, orphans }, null, 2) + '\n')
+    return
+  }
+  if (!done.length) return stdout.write('nothing to stop: no process left by an exited Claude session\n')
+  const color = useColor(stdout)
+  const width = Math.max(60, (stdout.columns || 120) - 4)
+  const lines = []
+  for (const { orphan: o, pids } of done) {
+    lines.push(`${paint(color, 'bold', dryRun ? 'would stop' : 'stopped')} ${o.pid}  ${paint(color, 'yellow', o.rule)}  ${fit(o.cmd || o.name, width - 30)}`)
+    lines.push(paint(color, 'dim', `  ${o.what}; ${o.why}; ${pids.length} process${pids.length === 1 ? '' : 'es'} from ${o.top}`))
+  }
+  const n = done.length
+  lines.push(dryRun ? `${n} tree${n === 1 ? '' : 's'} would be stopped. Run \`bulkhead reap\` to stop ${n === 1 ? 'it' : 'them'}.` : `${n} tree${n === 1 ? '' : 's'} stopped; see \`bulkhead log --guard orphan-reaper\`.`)
+  stdout.write(lines.join('\n') + '\n')
+}
+
+module.exports = { main, USAGE }