claude-bulkhead 0.2.2 → 0.3.0

package/src/port-cli.js

@@ -1,12 +1,19 @@
 'use strict'
 const net = require('net')
+const { sequence, keyFor, parseRange, DEFAULT_RANGE } = require('./stable-port')
 const { option, rejectArgs } = require('./cli-util')
 
 const USAGE = `usage: bulkhead port [--near PORT] [--json]
+       bulkhead port --stable [--name NAME] [--range 3000-3999] [--json]
 
 Prints the first port at or above PORT (default 3000) that nothing is listening on,
 so a dev server can start there without taking another session's port:
-  npm run dev -- --port $(bulkhead port --near 3000)`
+  npm run dev -- --port $(bulkhead port --near 3000)
+
+--stable gives this git worktree its own port, the same every time: it is picked from a hash of
+the worktree's root folder (or of --name), and moves on to the next port in a fixed order only
+when something else is listening there. It says which session holds a port it skipped.
+  npm run dev -- --port $(bulkhead port --stable)`
 
 // Ports browsers refuse to open (the fetch spec's "bad ports"), so a dev server there is useless.
 const BROWSER_BLOCKED = new Set([1719, 1720, 1723, 2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6697, 10080])
@@ -37,9 +44,77 @@ async function findFree(near = 3000, { bind = canBind, span = 1000 } = {}) {
   return null
 }
 
+// The key a worktree's stable port comes from: --name, else the root of the git worktree, else the folder.
+function stableKey(name, cwd = process.cwd()) {
+  if (name) return { key: `name:${name}`, root: null, name }
+  const { gitInfo } = require('./git-info')
+  const g = gitInfo(cwd)
+  const root = g ? g.root : cwd
+  return { key: keyFor(root), root, name: null }
+}
+
+// Who listens on each busy port: { port: { pid, name, session: text|null } }, one process scan.
+function defaultOwners(ports) {
+  const out = {}
+  try {
+    const { readProcesses } = require('./processes')
+    const { readSessionFiles, findSessions } = require('./sessions')
+    const { describeSession } = require('./session-info')
+    const snap = readProcesses()
+    if (!snap) return out
+    const sessions = findSessions(snap, readSessionFiles())
+    for (const port of ports) {
+      const l = snap.ports.find(x => x.port === port)
+      if (!l) continue
+      const owner = sessions.find(s => s.ports.some(x => x.pid === l.pid))
+      const proc = snap.procs.find(x => x.pid === l.pid)
+      out[port] = { pid: l.pid, name: proc ? proc.name : null, session: owner ? describeSession(owner) : null }
+    }
+  } catch {}
+  return out
+}
+
+// { port, preferred, skipped: [{ port, pid, name, session }] }; port is null when the range is full.
+async function findStable(key, range = DEFAULT_RANGE, { bind = canBind, owners = defaultOwners } = {}) {
+  const busy = []
+  let port = null
+  for (const p of sequence(key, range)) {
+    if (await isFree(p, bind)) { port = p; break }
+    busy.push(p)
+  }
+  const who = busy.length ? owners(busy.slice(0, 5)) : {}
+  return { port, preferred: sequence(key, range)[0], skipped: busy.slice(0, 5).map(p => ({ port: p, pid: null, name: null, session: null, ...who[p] })) }
+}
+
+async function stable(args, { stdout, stderr }) {
+  const rangeArg = option(args, 'range')
+  const range = rangeArg === undefined ? DEFAULT_RANGE : parseRange(rangeArg)
+  if (!range) {
+    stderr.write(`bulkhead port: --range needs LOW-HIGH between 1024 and 65535, got ${rangeArg}\n`)
+    process.exitCode = 1
+    return
+  }
+  const name = option(args, 'name')
+  const k = stableKey(typeof name === 'string' ? name : null)
+  const r = await findStable(k.key, range)
+  if (args.includes('--json')) {
+    stdout.write(JSON.stringify({ port: r.port, preferred: r.preferred, range, root: k.root, name: k.name, skipped: r.skipped }) + '\n')
+  } else {
+    if (r.port) stdout.write(`${r.port}\n`)
+    for (const s of r.skipped) {
+      stderr.write(`bulkhead port: ${s.port} is in use by ${s.session || (s.name ? `${s.name} pid ${s.pid}` : 'another process')}` + (s.port === r.skipped[r.skipped.length - 1].port && r.port ? `; using ${r.port}\n` : '\n'))
+    }
+  }
+  if (!r.port) {
+    if (!args.includes('--json')) stderr.write(`bulkhead port: no free port between ${range.min} and ${range.max}\n`)
+    process.exitCode = 1
+  }
+}
+
 async function main(args, { stdout = process.stdout, stderr = process.stderr } = {}) {
   if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
-  if (rejectArgs('port', args, { flags: ['json'], valued: ['near'] }, stderr, USAGE)) return
+  if (rejectArgs('port', args, { flags: ['json', 'stable'], valued: ['near', 'name', 'range'] }, stderr, USAGE)) return
+  if (args.includes('--stable')) return stable(args, { stdout, stderr })
   const nearArg = option(args, 'near')
   const near = nearArg === undefined ? 3000 : Number(nearArg)
   if (!Number.isInteger(near) || near < 1 || near > 65535) {
@@ -56,4 +131,4 @@ async function main(args, { stdout = process.stdout, stderr = process.stderr } =
   }
 }
 
-module.exports = { main, findFree, isFree, canBind, BROWSER_BLOCKED }
+module.exports = { main, findStable, stableKey, findFree, isFree, canBind, BROWSER_BLOCKED, USAGE }

package/src/port-guard.js

@@ -1,25 +1,54 @@
 'use strict'
 const net = require('net')
-const os = require('os')
 const { runHook, blocked, setting, oneLine } = require('./hook')
 const { detect } = require('./dev-servers')
+const { killPorts } = require('./port-kills')
 const { readProcesses } = require('./processes')
 const { readSessionFiles, findSessions, ownSession } = require('./sessions')
+const { agentLabel } = require('./agents')
 const shell = require('./shell')
 
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'ash', 'fish', 'eval', 'source', 'xargs'])
+
+// A heredoc is code for the shell only when a shell (or eval, source) reads it; python, node, cat,
+// a while loop and the like get it as data, and a command inside that text is not run.
+function readsShell(prefix) {
+  return prefix.split(/[;&|(]/).pop().trim().split(/\s+/).some(w => SHELLS.has(shell.bin(w)))
+}
+
+function withoutDataHeredocs(src) {
+  const docs = shell.heredocs(src, (prefix, after) => !readsShell(prefix) && !/\|\s*(?:[\w.-]+\s+)*(?:sh|bash|zsh|dash|ksh|fish|source|xargs)\b/.test(after))
+  if (!docs.length) return src
+  let out = ''
+  let last = 0
+  for (const d of docs) {
+    out += src.slice(last, d.start) + ' ' + d.rest
+    last = d.end
+  }
+  return out + src.slice(last)
+}
+
 // 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)
+const opened = (cmd, mode = 'sh') => shell.unwrap(withoutDataHeredocs(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'
+// The port this worktree always gets (see bulkhead port --stable), when it is free; only called after a block.
+function preferredPort(cwd, taken) {
+  try {
+    const { pickFree, keyFor } = require('./stable-port')
+    const { gitInfo } = require('./git-info')
+    const g = gitInfo(cwd)
+    return g ? pickFree(keyFor(g.root), taken) : null
+  } catch { return null }
 }
 
+// Loaded only on the block path, which keeps the allow path as fast as it was.
+const describeSession = (...a) => require('./session-info').describeSession(...a)
+
 // 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) {
@@ -34,63 +63,42 @@ function listening(port, timeoutMs = 300) {
 }
 
 // Resolves to a block message, or null. Anything we cannot pin down is allowed.
-async function check(cmd, {
+async function check(cmd, opts) {
+  const hit = await inspect(cmd, opts)
+  return hit ? hit.message : null
+}
+
+// The same decision with its evidence: { rule, message, port, pid, name, owner: { pid, cwd } }.
+async function inspect(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 ports = server ? (server.ports || [server.port]).filter(p => 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 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 sessions = findSessions(snap, files())
   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])])
-    }
+  if (!me) return null
+  for (const port of live) {
+    const holder = snap.ports.find(l => l.port === port)
+    const owner = holder && sessions.find(s => s.ports.some(l => l.pid === holder.pid))
+    if (!owner || me === owner.pid) continue
+    const name = (snap.procs.find(p => p.pid === holder.pid) || {}).name || 'a process'
+    const taken = new Set(snap.ports.map(l => l.port))
+    const stable = preferredPort(cwd, taken)
+    const free = stable || freePort(port, taken)
+    const message = `[bulkhead] port-guard: port ${port} is already used by another ${agentLabel(owner.agent)} session ` +
+      `(${describeSession(owner)}): ${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:${port} reach the other project.\n` +
+      (free ? `Port ${free} is free${stable ? ' (this worktree\'s own port)' : ''}:\n  ${server.hint(free)}` : `Pick a free port and pass it explicitly; \`bulkhead port --near ${port}\` prints one.`)
+    return { rule: 'port-in-use', message, port, pid: holder.pid, name, owner: { pid: owner.pid, cwd: owner.cwd } }
   }
-  return [...ports].filter(p => p > 0 && p < 65536)
+  return null
 }
 
 // Resolves to a block message when a kill by port would hit another live session's server.
@@ -114,9 +122,13 @@ async function checkKill(cmd, {
       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 {
+        rule: 'kill-by-port',
         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` +
+        pid: holder.pid,
+        name,
+        owner: { pid: owner.pid, cwd: owner.cwd },
+        message: `[bulkhead] port-guard: \`${oneLine(cmd, 120)}\` would stop ${name} pid ${holder.pid}, the server another ${agentLabel(owner.agent)} session ` +
+          `runs on port ${port} (${describeSession(owner)}).\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` +
@@ -127,16 +139,16 @@ async function checkKill(cmd, {
   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)
-  })
+async function handle(input) {
+  const cmd = input.tool_input && input.tool_input.command
+  if (typeof cmd !== 'string' || !cmd) return
+  const mode = shell.modeFor(input)
+  const why = await inspect(cmd, { cwd: input.cwd, mode })
+  if (why) return blocked('port-guard', why.rule, input, why.message)
+  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 }
+if (require.main === module) runHook('port-guard', handle)
+
+module.exports = { handle, check, inspect, checkKill, killPorts, freePort, listening }

package/src/port-kills.js

@@ -0,0 +1,198 @@
+'use strict'
+// Finds the ports a command stops: `npx kill-port 3000`, `fuser -k 3000/tcp`, `fkill :3000`, and a
+// lookup of the PID by port that feeds a kill, however the shell joins the two:
+//   lsof -ti :3000 | xargs kill -9
+//   lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill
+//   kill -9 $(lsof -i :3000 | awk 'NR>1{print $2}')
+//   for p in $(lsof -ti :3000); do kill $p; done
+//   PID=$(lsof -ti :3000); kill $PID
+//   netstat -anv | grep '\.3000 ' | awk '{print $9}' | xargs kill
+//   ss -ltnp 'sport = :3000' | ... | xargs kill
+// The text is read with the quote-aware lexer in shell.js, so a port in an echo or a grep pattern is not a kill.
+const shell = require('./shell')
+
+const numbers = s => (String(s).match(/\d+/g) || []).map(Number).filter(n => n > 0 && n < 65536)
+const validPort = n => Number.isInteger(n) && n > 0 && n < 65536
+const KILLS = /\b(?:kill|taskkill|Stop-Process|spps)\b(?!-port)/i
+const KILL_HINT = /kill|fuser|Stop-Process|spps/i
+const KILLERS = new Set(['kill', 'taskkill', 'stop-process', 'spps'])
+const GREPS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'ag', 'awk', 'gawk', 'sed', 'findstr', 'select-string'])
+const PORT_KILLERS = /^(?:kill-port|fkill)$/
+
+// Windows forms: Stop-Process on Get-NetTCPConnection, netstat | findstr :N, for /f ... taskkill.
+// Statements are split on ; && || and newlines, but not on pipes, which carry the PID along.
+function windowsKillPorts(cmd) {
+  const ports = []
+  for (const st of String(cmd || '').split(/\n|;|&&|\|\|/)) {
+    if (/Get-NetTCPConnection/i.test(st) && KILLS.test(st)) {
+      const lp = /-LocalPort\s+((?:\d+\s*,\s*)*\d+)/i.exec(st)
+      if (lp) ports.push(...numbers(lp[1]))
+    }
+    if (/\bnetstat\b/i.test(st) && KILLS.test(st)) {
+      const f = /\b(?:findstr|grep|Select-String)\b[^|]*?:(\d+)/i.exec(st)
+      if (f) ports.push(Number(f[1]))
+    }
+  }
+  return ports
+}
+
+// Values a shell variable can have here: NAME=3000, for NAME in 3000 3001. Unknown names stay as written.
+function knownVars(lexed) {
+  const vars = new Map()
+  for (const c of lexed) {
+    if (c.sub) continue
+    const w = c.words.map(x => x.v)
+    const at = /^(?:export|declare|local|readonly)$/.test(w[0]) ? 1 : 0
+    const m = /^(\w+)=([\w.:/-]*)$/.exec(w[at] || '')
+    if (m) vars.set(m[1], [m[2]])
+    if (w[0] === 'for' && w[2] === 'in' && /^\w+$/.test(w[1])) vars.set(w[1], w.slice(3).filter(x => !/[$`]/.test(x)))
+  }
+  return vars
+}
+
+function expand(word, vars, depth = 0) {
+  const m = /\$(?:\{(\w+)\}|(\w+))/.exec(word)
+  if (!m || depth > 3) return [word]
+  const values = vars.get(m[1] || m[2])
+  if (!values || !values.length) return [word]
+  return values.slice(0, 8).flatMap(v => expand(word.slice(0, m.index) + v + word.slice(m.index + m[0].length), vars, depth + 1))
+}
+
+// lsof -i :3000, -iTCP:3000, -i tcp:3000, -ti:3000, -i @host:3000, -i :3000,3001
+function lsofPorts(args, vars) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const m = /^-[a-zA-Z]*?i(.*)$/.exec(args[i])
+    if (!m) continue
+    for (const w of expand(m[1] !== '' ? m[1] : args[i + 1] || '', vars)) {
+      const hit = /:([\d,-]+)$/.exec(w)
+      if (hit) out.push(...numbers(hit[1]))
+    }
+  }
+  return out.filter(validPort)
+}
+
+// ss -ltnp 'sport = :3000': any :N or sport N in the words
+function socketPorts(args, vars) {
+  const out = []
+  for (const w of args.flatMap(a => expand(a, vars))) {
+    for (const m of w.matchAll(/:(\d{1,5})(?!\d)/g)) out.push(Number(m[1]))
+    const sp = /\b[sd]?port\s*(?:==?|eq)?\s*:?(\d{1,5})(?!\d)/.exec(w)
+    if (sp) out.push(Number(sp[1]))
+  }
+  return out.filter(validPort)
+}
+
+// A port number in a grep, awk or findstr pattern: ':3000', '\.3000 ' (macOS netstat), 3000. Not part of an IP address.
+function patternPorts(args, vars) {
+  const out = []
+  for (const raw of args.filter(a => !a.startsWith('-')).flatMap(a => expand(a, vars))) {
+    const w = raw.replace(/\\/g, '')
+    for (const m of w.matchAll(/\d{2,5}/g)) {
+      const before = w[m.index - 1] || ''
+      const after = w[m.index + m[0].length] || ''
+      const afterDot = after === '.' && /\d/.test(w[m.index + m[0].length + 1] || '')
+      const beforeDot = before === '.' && /\d/.test(w[m.index - 2] || '')
+      if (/\d/.test(before) || /\d/.test(after) || afterDot || beforeDot) continue
+      out.push(Number(m[0]))
+    }
+  }
+  return out.filter(validPort)
+}
+
+function fuserPorts(args, vars) {
+  if (!args.some(a => /^-[a-zA-Z]*k[a-zA-Z]*$/.test(a) || a === '--kill')) return []
+  const tcp = args.some((a, i) => /^(?:-n|--namespace)$/.test(a) && /^tcp$/i.test(args[i + 1] || ''))
+  const out = []
+  for (const a of args.flatMap(x => expand(x, vars))) {
+    const m = /^(\d+)\/tcp$/i.exec(a)
+    if (m) out.push(Number(m[1]))
+    else if (tcp && /^\d+$/.test(a)) out.push(Number(a))
+  }
+  return out.filter(validPort)
+}
+
+// npx kill-port 3000 3001, kill-port --port 3000,3001
+function killPortPorts(args, vars) {
+  const out = []
+  for (const a of args.flatMap(x => expand(x, vars))) {
+    if (/^(?:--port=)?[\d,]+$/.test(a)) out.push(...numbers(a))
+  }
+  return out.filter(validPort)
+}
+
+// fkill :3000 (a bare number is a PID)
+const fkillPorts = (args, vars) => args.flatMap(a => expand(a, vars)).map(a => /^:(\d+)$/.exec(a)).filter(Boolean).map(m => Number(m[1])).filter(validPort)
+
+// What one statement (a pipeline, a $( ), a loop) says: the ports it kills outright (fuser -k,
+// kill-port, fkill), the ports it looks up, and whether it kills a PID.
+function statementPorts(list, vars) {
+  const direct = []
+  const explicit = []
+  const patterns = []
+  let lookup = false
+  let kills = false
+  for (const argv of list) {
+    const b = shell.bin(argv[0])
+    const args = argv.slice(1)
+    const at = PORT_KILLERS.test(b) ? 0 : argv.findIndex((a, i) => i > 0 && i < 6 && PORT_KILLERS.test(shell.bin(a)))
+    if (b === 'lsof') { lookup = true; explicit.push(...lsofPorts(args, vars)) } else if (b === 'netstat' || b === 'ss') { lookup = true; explicit.push(...socketPorts(args, vars)) } else if (GREPS.has(b)) patterns.push(...patternPorts(args, vars))
+    else if (b === 'fuser') direct.push(...fuserPorts(args, vars))
+    else if (at >= 0 && /^(?:kill-port|fkill|npx|bunx|pnpx|pnpm|yarn|npm|bun)$/.test(b)) {
+      const rest = argv.slice(at + 1)
+      direct.push(...(shell.bin(argv[at]) === 'fkill' ? fkillPorts(rest, vars) : killPortPorts(rest, vars)))
+    } else if (KILLERS.has(b) && !args.some(a => /^-(?:0|l|L)$/.test(a))) kills = true
+  }
+  // lsof with no port of its own and netstat are narrowed by a later grep or awk
+  const looked = explicit.length ? explicit : lookup ? patterns : []
+  return { direct, looked: [...new Set(looked)], kills }
+}
+
+function shellKillPorts(text) {
+  const lexed = shell.lex(text).cmds
+  const vars = knownVars(lexed)
+  const segs = new Map()
+  for (const c of shell.commands(text)) {
+    if (!segs.has(c.seg)) segs.set(c.seg, [])
+    segs.get(c.seg).push(c.argv)
+  }
+  // variables a statement fills from a command: PID=$(lsof -ti :3000)
+  const assigned = new Map()
+  for (const c of lexed) {
+    if (c.sub) continue
+    const m = /^(?:\w+\s+)?(\w+)=(?:\$\(|`)/.exec(c.words.slice(0, 2).map(w => w.v).join(' '))
+    if (m) assigned.set(c.seg, (assigned.get(c.seg) || []).concat(m[1]))
+  }
+  const found = new Set()
+  const add = list => { for (const p of list) found.add(p) }
+  const carried = new Map() // variable -> ports it came from
+  for (const seg of [...segs.keys()].sort((a, b) => a - b)) {
+    const list = segs.get(seg)
+    const info = statementPorts(list, vars)
+    add(info.direct)
+    if (info.kills) {
+      add(info.looked)
+      if (carried.size) {
+        for (const argv of list) {
+          for (const w of argv) for (const m of w.matchAll(/\$\{?(\w+)/g)) if (carried.has(m[1])) add(carried.get(m[1]))
+        }
+      }
+    }
+    if (info.looked.length) for (const name of assigned.get(seg) || []) carried.set(name, info.looked)
+  }
+  return [...found]
+}
+
+// Ports a kill-by-port command aims at, or [] when the command does not kill by port.
+function killPorts(cmd) {
+  const text = String(cmd || '')
+  const ports = new Set(windowsKillPorts(text))
+  if (KILL_HINT.test(text)) {
+    try {
+      for (const p of shellKillPorts(text)) ports.add(p)
+    } catch { /* a command we cannot read is not a kill we can name */ }
+  }
+  return [...ports].filter(validPort)
+}
+
+module.exports = { killPorts }

package/src/pressure.js

@@ -0,0 +1,75 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { execFileSync } = require('child_process')
+
+// Is the machine under critical memory pressure right now? Cheap, and cached for a few seconds
+// because every subagent spawn asks.
+//   macOS    kern.memorystatus_vm_pressure_level 4 (1 normal, 2 warning, 4 critical)
+//   Linux    /proc/pressure/memory: processes stalled on memory (full avg10 >= 10, or some avg10 >= 50);
+//            without PSI, MemAvailable under 5% of RAM
+//   Windows  available physical memory under 8%
+const CACHE_MS = 5000
+const LINUX_FULL = 10
+const LINUX_SOME = 50
+const WINDOWS_FREE_PCT = 8
+const LOW_FREE_PCT = 5
+
+const sysctl = () => execFileSync('sysctl', ['-n', 'kern.memorystatus_vm_pressure_level'], { encoding: 'utf8', timeout: 1500 })
+
+function parsePsi(text) {
+  const avg = kind => {
+    const m = String(text).match(new RegExp(`^${kind} .*?avg10=([\\d.]+)`, 'm'))
+    return m ? Number(m[1]) : null
+  }
+  return { some: avg('some'), full: avg('full') }
+}
+
+function freePct(mem) {
+  return mem.totalGb > 0 ? (100 * mem.freeGb) / mem.totalGb : 100
+}
+
+// { critical, detail } from one reading, or null when nothing could be read (then nothing is blocked).
+function measure({ platform = process.platform, run = sysctl, readFile = fs.readFileSync, readMem = () => require('./memory').readMemory() } = {}) {
+  try {
+    if (process.env.BULKHEAD_TEST_PRESSURE) return JSON.parse(process.env.BULKHEAD_TEST_PRESSURE)
+    if (platform === 'darwin') {
+      const level = Number(String(run()).trim())
+      if (!Number.isFinite(level)) return null
+      return { critical: level >= 4, detail: `macOS memory pressure level ${level}` }
+    }
+    if (platform === 'linux') {
+      let psi = null
+      try { psi = parsePsi(readFile('/proc/pressure/memory', 'utf8')) } catch {}
+      if (psi && psi.some !== null) {
+        const critical = (psi.full || 0) >= LINUX_FULL || psi.some >= LINUX_SOME
+        return { critical, detail: `memory stall avg10 some ${psi.some}% full ${psi.full || 0}%` }
+      }
+      const mem = readMem()
+      return { critical: freePct(mem) < LOW_FREE_PCT, detail: `${mem.freeGb.toFixed(1)} GB free` }
+    }
+    const mem = readMem()
+    return { critical: freePct(mem) < (platform === 'win32' ? WINDOWS_FREE_PCT : LOW_FREE_PCT), detail: `${mem.freeGb.toFixed(1)} GB of ${mem.totalGb.toFixed(1)} GB free` }
+  } catch {
+    return null
+  }
+}
+
+// measure() with the answer kept in <state dir>/pressure.json for CACHE_MS.
+function current({ stateDir, now = Date.now(), ...readers } = {}) {
+  const file = stateDir && path.join(stateDir, 'pressure.json')
+  try {
+    const c = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (now - c.at >= 0 && now - c.at < CACHE_MS) return c.value
+  } catch {}
+  const value = measure(readers)
+  if (file && value) {
+    try {
+      fs.mkdirSync(stateDir, { recursive: true })
+      fs.writeFileSync(file, JSON.stringify({ at: now, value }))
+    } catch {}
+  }
+  return value
+}
+
+module.exports = { measure, current, parsePsi, CACHE_MS }