claude-bulkhead 0.2.2 → 0.3.0

package/src/kill-guard.js

@@ -1,6 +1,8 @@
 'use strict'
-const { runHook, blocked, setting, ASK_USER } = require('./hook')
+const { runHook, blocked, setting, enabled, ASK_USER } = require('./hook')
 const shell = require('./shell')
+const owners = require('./kill-owners')
+const extras = require('./kill-extras')
 
 // Programs that other sessions, editors and the user are likely running too.
 const SHARED = [
@@ -13,6 +15,13 @@ const SHARED = [
   // apps and servers the user or another session has open
   'electron', 'simulator', 'xcode', 'postgres',
   'docker desktop', 'code helper', 'cursor', 'cursor helper',
+  // other coding agents, whose sessions are as shared as Claude's
+  'codex', 'gemini', 'copilot', 'opencode', 'cline', 'droid', 'cursor-agent',
+  // dev servers and their children, by the names they show in ps and Activity Monitor
+  'next-server', 'next-router-worker', 'next-render-worker', 'uvicorn', 'gunicorn', 'rails', 'puma', 'flask', 'expo', 'metro',
+  'storybook', 'turbo', 'tsc', 'nodemon', 'qemu', 'emulator', 'playwright', 'puppeteer', 'ms-playwright', 'php',
+  'headless_shell', 'headless-shell', 'chrome-headless', 'google chrome', 'google chrome helper', 'chrome helper', 'chromedriver',
+  'http.server',
 ]
 const bare = n => String(n).trim().replace(/^["']+|["']+$/g, '').toLowerCase().replace(/\.exe$/, '')
 
@@ -43,24 +52,61 @@ function scopedPattern(pattern) {
   return /[\\/]|\.(?:py|js|mjs|cjs|ts|mts|rb|php|sh|jar|ps1)\b/i.test(first) || /[\\/]|\.(?:py|js|mjs|cjs|ts|rb|php|sh|jar|ps1)\b/i.test(pattern)
 }
 
-// A pkill, pgrep or grep pattern. Without -f it is a regular expression matched against the
-// process name; with -f (and for grep over ps output) against the whole command line, where the
-// first word decides which program it hits. [n]ode is node.
-function patternHits(pattern, names, { full = false, exact = false } = {}) {
-  let p = String(pattern || '').trim()
-  if (!p || p.length > 500) return false
-  if (scopedPattern(p)) return false
-  if (full) p = p.split(/\s+/)[0]
-  if (!p) return false
-  // a plain word names one program: pkill node does not reach ts-node
-  if (!/[.*+?^${}()|[\]\\]/.test(p.replace(/\.exe$/i, ''))) return names.includes(bare(p))
+// pkill -f "ssh -N -L 9333": a program name followed by arguments that name one job (a flag, a
+// number, a path, a host). "next dev" and "node server" have none, so they still match every one.
+function specificPattern(pattern) {
+  return pattern.trim().split(/\s+/).slice(1).some(t => /^-|[\d:=/\\@~]|\.\w/.test(t))
+}
+
+const REGEX_CHARS = /[.*+?^${}()|[\]\\]/
+// pkill -f dev, -f server: words that stand for "whatever dev server is running"
+const DEV_WORDS = new Set(['dev', 'server', 'serve', 'start', 'runserver', 'http.server'])
+const DEV_TAIL = 'dev next server serve start run'
+
+// node22, nodejs and python3.11 are the shared name with a version
+function sharedWord(lw, names) {
+  if (names.includes(lw)) return true
+  const base = lw.replace(/^nodejs$/, 'node').replace(/^(node|python|ruby|java)[\d.]+$/, '$1')
+  return base !== lw && names.includes(base)
+}
+
+// One word of a pkill, killall or grep pattern against the shared names. Without -x the pattern
+// is a regular expression searched in the name, so a part of a name ("ode") reaches it too.
+function wordHits(w, names, { full, exact }) {
+  if (!w) return false
+  if (sharedWord(bare(w), names)) return true
+  if (!REGEX_CHARS.test(w.replace(/\.exe$/i, ''))) {
+    const lw = bare(w)
+    if (sharedWord(lw, names) || (full && DEV_WORDS.has(lw))) return true
+    // a name the user took off the list (allowNames) is not searched inside other names either
+    return !exact && lw.length >= 3 && !SHARED.includes(lw) && names.some(n => n.includes(lw))
+  }
   let re
   try {
-    re = new RegExp(exact ? `^(?:${p})$` : p, 'i')
+    re = new RegExp(exact ? `^(?:${w})$` : w, 'i')
   } catch {
-    return names.includes(bare(p))
+    return names.includes(bare(w))
   }
-  return names.some(n => re.test(n) || (!exact && re.test(n + '.exe')))
+  if (names.some(n => re.test(n) || (!exact && re.test(n + '.exe')))) return true
+  // pkill -f "node.*next": a name, then whatever a dev server's command line says
+  return full && !exact && names.some(n => re.test(`${n} ${DEV_TAIL}`))
+}
+
+// A pkill, pgrep or grep pattern. Without -f it is a regular expression matched against the
+// process name; with -f (and for grep over ps output) against the whole command line, where the
+// first word of each alternative decides which program it hits. [n]ode is node.
+function patternHits(pattern, names, { full = false, exact = false } = {}) {
+  const p = String(pattern || '').trim()
+  if (!p || p.length > 500) return false
+  if (!full) return !scopedPattern(p) && wordHits(p, names, { full, exact })
+  return p.split('|', 20).some(alt => {
+    alt = alt.trim()
+    if (!alt || scopedPattern(alt)) return false
+    // "Google Chrome Helper": a name of several words
+    if (/\s/.test(alt) && names.includes(bare(alt))) return true
+    if (specificPattern(alt)) return false
+    return wordHits(alt.split(/\s+/)[0], names, { full, exact }) || wordHits(alt, names, { full, exact })
+  })
 }
 
 const PKILL_VALUE = new Set(['-g', '-G', '-P', '-s', '-t', '-u', '-U', '-F', '--signal', '--pgroup', '--group', '--parent', '--session', '--terminal', '--euid', '--uid', '--pidfile', '--ns', '--nslist', '--env'])
@@ -101,26 +147,58 @@ function parseKillByName(argv, valued) {
 
 const zeroSignal = s => s != null && /^(?:0|SIG0)$/i.test(String(s))
 
-function checkPkill(argv, names) {
+const NAME_WHY = 'pkill/killall matches every process with that name.'
+const escapeRe = w => String(w).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// A name that is no shared program but belongs to an app or a service the other sessions may be
+// using: it counts only while another Claude session is alive.
+function softName(pattern, full) {
+  const words = full ? String(pattern).split('|', 20).map(a => a.trim()) : [String(pattern)]
+  for (const w of words) {
+    for (const cand of full ? [w, w.split(/\s+/)[0]] : [w]) {
+      if (extras.isApp(cand)) return { rule: 'app-quit', why: `Quitting ${cand} closes it for everyone.` }
+      if (extras.isService(cand)) return { rule: 'service-stop', why: `Stopping ${cand} takes it away from every session.` }
+    }
+  }
+  return null
+}
+
+// pkill, killall: [rule, why] to block now, [rule, why, check] to block when check(table) says so.
+function checkPkill(argv, names, { stdin = [], off = new Set() } = {}) {
   const b = shell.bin(argv[0])
   if (b === 'pkill') {
     const p = parseKillByName(argv, PKILL_VALUE)
     if (zeroSignal(p.signal) || p.opts.some(ov => PKILL_SCOPE.test(ov))) return null
-    if (p.operands.length && patternHits(p.operands[0], names, { full: /f/.test(p.flags) || p.opts.some(([o]) => o === '--full'), exact: /x/.test(p.flags) })) {
-      return ['pkill', 'pkill/killall matches every process with that name']
-    }
+    const operands = p.operands.length ? p.operands : stdin.slice(0, 1)
+    if (!operands.length) return null
+    const full = /f/.test(p.flags) || p.opts.some(([o]) => o === '--full')
+    const exact = /x/.test(p.flags)
+    return byName(operands[0], names, { full, exact }, off)
   }
   if (b === 'killall') {
     const p = parseKillByName(argv, KILLALL_VALUE)
     if (zeroSignal(p.signal)) return null
     const regex = /r/.test(p.flags) || p.opts.some(([o]) => o === '--regexp')
-    if (p.operands.slice(0, 100).some(o =>(regex ? patternHits(o, names, { exact: true }) : names.includes(bare(o))))) {
-      return ['pkill', 'pkill/killall matches every process with that name']
+    const operands = (p.operands.length ? p.operands : stdin).slice(0, 100)
+    let later = null
+    for (const o of operands) {
+      const hit = regex ? patternHits(o, names, { exact: true }) : sharedWord(bare(o), names)
+      if (hit) return ['pkill', NAME_WHY]
+      later = later || byName(regex ? o : escapeRe(o), names, { full: false, exact: true }, off, !regex && o)
     }
+    return later
   }
   return null
 }
 
+function byName(pattern, names, { full, exact }, off, plain) {
+  if (patternHits(pattern, names, { full, exact })) return ['pkill', NAME_WHY]
+  const soft = softName(plain || pattern, full)
+  if (soft && !off.has(soft.rule)) return [soft.rule, soft.why, t => owners.othersCheck(t)]
+  if (off.has('owner-check')) return null
+  return ['other-session-match', '', t => owners.patternCheck(t, pattern, { full, exact })]
+}
+
 // A comma list after a flag: -Name node,python or -Name node, python. Real lists are short; the
 // first 256 names are enough, and a longer list is not copied name by name.
 const MAX_LIST = 256
@@ -149,12 +227,12 @@ function checkTaskkill(argv, names) {
     else if (o === 'pid') { byPid = true; k++ } else if (o === 'fi') filters.push(argv[++k] || '')
   }
   const hit = images.find(i => nameHits(i, names))
-  if (hit) return ['taskkill-im', `taskkill /IM kills every process with that name: ${argv.join(' ')}`]
+  if (hit) return ['taskkill-im', `taskkill /IM kills every process with that name: ${argv.join(' ')}.`]
   for (const f of filters) {
     if (/\bpid\s+(?:eq|ne|gt|lt|ge|le)\b/i.test(f) || byPid) continue
     const img = /\bimagename\s+eq\s+(\S+)/i.exec(f)
     if (img && !nameHits(img[1], names)) continue
-    return ['taskkill-filter', `taskkill /FI picks processes by filter, not by PID: ${argv.join(' ')}`]
+    return ['taskkill-filter', `taskkill /FI picks processes by filter, not by PID: ${argv.join(' ')}.`]
   }
   return null
 }
@@ -169,7 +247,7 @@ function checkStopProcess(argv, names) {
     const m = NAME_FLAG.exec(argv[k])
     if (!m) continue
     const list = m[1] ? m[1].split(',') : listAfter(argv, k + 1)
-    if (list.some(n => nameHits(n, names))) return ['stop-process-name', 'Stop-Process -Name kills every process with that name']
+    if (list.some(n => nameHits(n, names))) return ['stop-process-name', 'Stop-Process -Name kills every process with that name.']
   }
   return null
 }
@@ -180,7 +258,7 @@ function checkWmic(argv, names) {
   const text = argv.slice(1).join(' ')
   if (!/\bprocess\b/i.test(text) || !/\b(?:delete|terminate)\b/i.test(text)) return null
   if (/\b(?:processid|commandline|executablepath|parentprocessid)\b/i.test(text)) return null
-  if (wmiNameHits(text, names)) return ['wmic-name', 'wmic process where name=... deletes every process with that name']
+  if (wmiNameHits(text, names)) return ['wmic-name', 'wmic process where name=... deletes every process with that name.']
   return null
 }
 
@@ -197,14 +275,14 @@ function wmiNameHits(text, names) {
 // narrows the selection to known processes (Id, CommandLine, Path).
 function whereFilter(text, names) {
   const scoped = /\b(?:Id|ProcessId|CommandLine|Path|ExecutablePath|ParentProcessId)\b/i.test(text)
-  let byName = false
+  let named = false
   for (const m of text.matchAll(/\b(?:Name|ProcessName|ImageName)\b['"]?\s*-[ic]?(eq|like|match|in|contains)\s+([^|}]{1,200})/gi)) {
     const op = m[1].toLowerCase()
     const values = m[2].split(/[\s,]+/).map(s => s.replace(/^[('"]+|[)'"]+$/g, '')).filter(Boolean)
-    if (op === 'match') byName = byName || values.slice(0, 1).some(v => patternHits(v, names))
-    else byName = byName || values.some(v => nameHits(v, names))
+    if (op === 'match') named = named || values.slice(0, 1).some(v => patternHits(v, names))
+    else named = named || values.some(v => nameHits(v, names))
   }
-  return { scoped, byName }
+  return { scoped, byName: named }
 }
 
 // Commands that only print or search text: their words are never a kill or a selection.
@@ -215,21 +293,31 @@ const PS_SINKS = /^(?:stop-process|spps|invoke-cimmethod|remove-ciminstance|remo
 // Does any of these commands select processes by a shared name, and does another one kill what
 // they select? Commands of one statement are judged together: a pipe, $( ) and a loop body all
 // carry the PIDs from one to the other.
-function judgeStatement(cmds, names, mode, vars) {
+function judgeStatement(cmds, names, mode, vars, cfg, deferred) {
   let selector = null
   let scoped = false
   let killer = false
   let usesVar = false
   let whereDepth = 0
   const listsProcesses = cmds.some(x => x.argv.length && /^(?:ps|tasklist|wmic|get-process|gps)$/i.test(shell.bin(x.argv[0])))
+  // echo node | xargs pkill, pkill <<< node: what the pipe or here-string supplies
+  const stdin = []
+  for (const c of cmds) {
+    const at = c.argv.indexOf('<<<')
+    if (at > 0) { stdin.push(...c.argv.slice(at + 1)); c.argv = c.argv.slice(0, at) }
+    else if (c.inert) stdin.push(...c.argv.slice(1).filter(a => !/^-[neE]+$/.test(a)))
+  }
   for (const c of cmds) {
     const argv = c.argv
-    if (!argv.length) continue
+    if (!argv.length || c.inert) continue
     const b = shell.bin(argv[0])
     // direct kills by name
-    const direct = checkPkill(argv, names) || checkTaskkill(argv, names) || checkStopProcess(argv, names) || checkWmic(argv, names)
-    if (direct) return direct
+    const direct = checkPkill(argv, names, { stdin, off: cfg.off }) || checkTaskkill(argv, names) || checkStopProcess(argv, names) || checkWmic(argv, names)
+    if (direct && !direct[2]) return direct
+    if (direct) deferred.push(direct)
     if (c.remote) continue
+    const more = extras.detect(argv, { mode, off: cfg.off, stmt: cmds, env: cfg.env || new Map() })
+    if (more && !direct) deferred.push(more)
     // killers
     if (isKiller(argv, mode)) killer = true
     for (const w of argv) {
@@ -286,10 +374,10 @@ function judgeStatement(cmds, names, mode, vars) {
 }
 
 const SELECTOR_WHY = {
-  'pgrep-kill': 'pgrep <name> feeding kill matches every process with that name',
-  'ps-grep-kill': 'ps | grep <name> | kill matches every process with that name',
-  'get-process-pipe': 'Get-Process <name> | Stop-Process kills every process with that name',
-  'win32-process-name': 'Win32_Process selected by Name alone is terminated',
+  'pgrep-kill': 'pgrep <name> feeding kill matches every process with that name.',
+  'ps-grep-kill': 'ps | grep <name> | kill matches every process with that name.',
+  'get-process-pipe': 'Get-Process <name> | Stop-Process kills every process with that name.',
+  'win32-process-name': 'Win32_Process selected by Name alone is terminated.',
 }
 
 function isKiller(argv, mode) {
@@ -338,35 +426,88 @@ function assignedVar(cmds) {
   return null
 }
 
-// { rule, why } for the first kill by name, or null.
-function classify(cmd, names = {}, mode = 'sh') {
+// Interpreter code that starts shell commands from string literals: python3 -c "...os.system('...')",
+// a python or node heredoc, perl -e. The strings are read as shell commands.
+const INTERPRETER_WORD = /\b(?:python[\d.]*|py|pythonw|node|nodejs|deno|bun|ruby|perl|php)\b/
+const SHELLING_OUT = /system|exec|spawn|popen|subprocess|passthru|`|%x/
+const CODE_FLAGS = /^(?:-c|-e|-E|-r|-p|--eval|--print)$/
+
+function embedded(cmd, mode) {
+  if (!INTERPRETER_WORD.test(cmd) || !SHELLING_OUT.test(cmd)) return []
+  const codes = []
+  for (const c of shell.commands(shell.prepare(cmd, mode, ['shell', 'interp']), mode)) {
+    if (!/^(?:python[\d.]*|py|pythonw|node|nodejs|deno|bun|ruby|perl|php)$/.test(shell.bin(c.argv[0]))) continue
+    const i = c.argv.findIndex((a, k) => k > 0 && CODE_FLAGS.test(a))
+    if (i > 0 && c.argv[i + 1]) codes.push(c.argv[i + 1])
+  }
+  if (cmd.includes('<<')) for (const d of shell.heredocs(cmd, (p, a) => shell.consumerOf(p, a, mode).kind === 'interp')) codes.push(d.body)
+  return codes.flatMap(shell.embeddedShell)
+}
+
+// Rules that stop only while another Claude session is alive, and the table checks, are settled
+// here: ctx.table() reads the process table once, and only now.
+function resolve(hit, ctx) {
+  if (!hit || !hit.deferred) return hit
+  if (!ctx) return null
+  const t = ctx.table()
+  if (!t) return null
+  for (const d of hit.deferred) {
+    const detail = d.check(t, ctx)
+    if (detail) return { rule: d.rule, why: [d.why, detail].filter(Boolean).join(' ') }
+  }
+  return null
+}
+
+// { rule, why } for the first kill, or null. ctx (see kill-owners makeContext) lets the checks
+// that need the process table run; without it only what the text alone shows is judged.
+function classify(cmd, names = {}, mode = 'sh', ctx = null) {
   const list = nameList(names)
+  const cfg = { off: ctx ? ctx.off : new Set() }
   const text = shell.unwrap(shell.prepare(String(cmd || ''), mode), mode)
-  return judge(text, list, mode)
+  let hit = judge(text, list, mode, cfg)
+  if (!hit || hit.deferred) {
+    for (const inner of embedded(String(cmd || ''), mode)) {
+      const more = judge(shell.unwrap(shell.prepare(inner, mode), mode), list, mode, cfg)
+      if (more && !more.deferred) { hit = more; break }
+      if (more) hit = { deferred: [...(hit ? hit.deferred : []), ...more.deferred] }
+    }
+  }
+  return resolve(hit, ctx)
 }
 
 // Every kill this guard knows names one of these words, so text without them needs no parsing.
-const KILL_WORD = /kill|stop-process|spps|terminate|remove-ciminstance|rcim|remove-wmiobject|rwmi|wmic/i
+const KILL_WORD = /kill|stop-process|spps|terminate|remove-ciminstance|rcim|remove-wmiobject|rwmi|wmic|docker|podman|nerdctl|pm2|simctl|osascript|brew|launchctl|systemctl|service|adb\b/i
 
-function judge(text, names, mode) {
+function judge(text, names, mode, cfg) {
   if (!KILL_WORD.test(text)) return null
   const { cmds, unterminated } = shell.lex(text, mode)
-  const hit = judgeLexed(text, cmds, names, mode)
+  const hit = judgeLexed(text, cmds, names, mode, cfg)
   if (hit || !unterminated) return hit
   // a quote that never closes: read the text again without quotes, as the shell never would
-  return judgeLexed(text, shell.lex(text.replace(/["'`]/g, ' '), mode).cmds, names, mode)
+  return judgeLexed(text, shell.lex(text.replace(/["'`]/g, ' '), mode).cmds, names, mode, cfg)
 }
 
-function judgeLexed(text, lexed, names, mode) {
+function judgeLexed(text, lexed, names, mode, cfg) {
   const bySeg = new Map()
   const add = (seg, x) => {
     if (!bySeg.has(seg)) bySeg.set(seg, [])
     bySeg.get(seg).push(x)
   }
   let forF = false
+  const assigned = new Map()
+  cfg.env = assigned
   for (const c of lexed) {
     const s = shell.strip(text, c.words, mode)
+    for (const w of c.words) {
+      if (/^(?:export|declare|typeset|local)$/.test(w.v)) continue
+      const m = /^([A-Za-z_]\w*)=([^$`]*)$/.exec(w.v)
+      if (m) assigned.set(m[1], m[2])
+      else break
+    }
     const argv = s.argv.map(w => w.v)
+    // cmd=pkill; $cmd node
+    const ref = argv.length && /^\$\{?(\w+)\}?$/.exec(argv[0])
+    if (ref && assigned.has(ref[1]) && assigned.get(ref[1])) argv.splice(0, 1, ...assigned.get(ref[1]).split(/\s+/).filter(Boolean))
     // cmd's for /f ... in ('tasklist ^| findstr node') do ...: the quoted command runs too
     if (forF && argv.length) {
       forF = false
@@ -380,19 +521,24 @@ function judgeLexed(text, lexed, names, mode) {
       }
     }
     if (/^for$/i.test(argv[0] || '') && /^\/f$/i.test(argv[1] || '') && /^in$/i.test(argv[argv.length - 1])) forF = true
-    if (argv.length && INERT.test(shell.bin(argv[0]))) continue
+    if (argv.length && INERT.test(shell.bin(argv[0]))) {
+      // echo node | xargs pkill: what an echo prints is what the next command reads
+      if (/^(?:echo|printf)$/.test(shell.bin(argv[0]))) add(c.seg, { argv, words: c.words, remote: false, sub: c.sub, inert: true })
+      continue
+    }
     add(c.seg, { argv, words: c.words, remote: s.remote, sub: c.sub })
   }
   const vars = new Set()
+  const deferred = []
   for (const cmds of bySeg.values()) {
-    const r = judgeStatement(cmds, names, mode, vars)
+    const r = judgeStatement(cmds, names, mode, vars, cfg, deferred)
     if (Array.isArray(r)) return { rule: r[0], why: r[1] }
     if (r && r.assign) {
       const v = assignedVar(cmds)
       if (v) vars.add(v)
     }
   }
-  return null
+  return deferred.length ? { deferred: deferred.map(([rule, why, fn]) => ({ rule, why, check: fn })) } : null
 }
 
 function check(cmd, names, mode) {
@@ -400,36 +546,41 @@ function check(cmd, names, mode) {
   return hit ? hit.why : null
 }
 
-function howToFindPid(platform) {
+// What to do instead, by what was blocked.
+const FIX = {
+  'docker-mass': 'Stop only your own containers, by name: docker stop <your container> (docker ps --filter name=<your project>).',
+  'device-kill': 'Target your own device: adb -s <your device> emu kill, xcrun simctl shutdown <your device UDID>.',
+  'app-quit': 'Close only what you opened: kill <your own pid>.',
+  'service-stop': 'Stop only a service you started yourself, by its PID: kill <your own pid>.',
+}
+
+function howToFix(platform, rule) {
+  if (FIX[rule]) return FIX[rule]
   if (platform === 'win32') {
-    return [
-      'By port: netstat -ano | findstr :<port>   (last column is the PID)',
-      "By project: Get-CimInstance Win32_Process | ? { $_.CommandLine -like '*<your project dir>*' } | select ProcessId, CommandLine",
-      'Then: taskkill /PID <pid> /T /F',
-    ].join('\n')
+    return 'Stop only what you started: taskkill /PID <your own pid> /T /F (netstat -ano | findstr :<port> finds a port owner; ' +
+      "Get-CimInstance Win32_Process | ? { $_.CommandLine -like '*<your project dir>*' } finds your project's processes)."
   }
-  return [
-    'By port: lsof -ti :<port>',
-    "By project: pgrep -af '<your project dir>'",
-    'Then: kill <pid>   (or kill -- -<pgid> for a process group you started)',
-  ].join('\n')
-}
-
-function message(why, platform = process.platform) {
-  return `[bulkhead] kill-guard: ${why}\n` +
-    'Other Claude sessions, subagents and the user run these programs on this machine too. ' +
-    'Killing by name takes down their dev servers, test runs and builds, and can end your own session.\n' +
-    'Stop only the processes you started, by PID:\n' + howToFindPid(platform)
-}
-
-if (require.main === module) {
-  runHook('kill-guard', input => {
-    const cmd = input.tool_input && input.tool_input.command
-    if (typeof cmd !== 'string' || !cmd) return
-    const hit = classify(cmd, { allowNames: setting('killGuard.allowNames', []), extraSharedNames: setting('killGuard.extraSharedNames', []) }, shell.modeFor(input))
-    if (!hit) return
-    return blocked('kill-guard', hit.rule, input, `${message(hit.why)}\n${ASK_USER}`)
-  })
+  return "Stop only what you started: kill <your own pid> (lsof -ti :<port> or pgrep -af '<your project dir>' finds it), or pkill -f '<your project dir>'."
+}
+
+function message(why, platform = process.platform, rule) {
+  const sentence = /[.!?]$/.test(why) ? why : why + '.'
+  return `[bulkhead] kill-guard: ${sentence}\n${howToFix(platform, rule)}`
 }
 
-module.exports = { check, classify, message, nameHits, patternHits }
+// Rules with their own switch (config keys killGuard.<name>), on inside a guard that is on.
+const RULES = ['mass-kill', 'docker-mass', 'device-kill', 'app-quit', 'service-stop', 'owner-check']
+
+function handle(input) {
+  const cmd = input.tool_input && input.tool_input.command
+  if (typeof cmd !== 'string' || !cmd) return
+  const off = RULES.filter(rule => !enabled(rule))
+  const ctx = owners.makeContext({ cwd: input.cwd || process.cwd(), off })
+  const hit = classify(cmd, { allowNames: setting('killGuard.allowNames', []), extraSharedNames: setting('killGuard.extraSharedNames', []) }, shell.modeFor(input), ctx)
+  if (!hit) return
+  return blocked('kill-guard', hit.rule, input, `${message(hit.why, process.platform, hit.rule)}\n${ASK_USER}`)
+}
+
+if (require.main === module) runHook('kill-guard', handle)
+
+module.exports = { handle, check, classify, message, nameHits, patternHits, nameList, RULES }

package/src/kill-owners.js

@@ -0,0 +1,116 @@
+'use strict'
+// Who owns what on this machine, for the kill checks that need to know. The process table is read
+// at most once per hook and only when a command asks for it: kill with literal PIDs, pkill -f with
+// a specific pattern, and the mass kills that matter only while another session is alive.
+const os = require('os')
+const path = require('path')
+const processes = require('./processes')
+const sessions = require('./sessions')
+
+function shortPath(p) {
+  const home = os.homedir()
+  const s = String(p || '')
+  return home && (s === home || s.startsWith(home + path.sep)) ? '~' + s.slice(home.length) : s
+}
+
+// A lazy view of the machine. Nothing is read until table() is called; a failed read gives null
+// and every check then lets the command through.
+function makeContext({ snapshot, files, self, cwd = process.cwd(), off = [] } = {}) {
+  let cached
+  return {
+    cwd,
+    off: new Set(off),
+    table() {
+      if (cached === undefined) {
+        try {
+          cached = loadTable({
+            snapshot: snapshot || (() => processes.readProcesses(process.platform, { withPorts: false })),
+            files: files || (() => sessions.readSessionFiles()),
+            self: self || (procs => sessions.ownSession(procs)),
+          })
+        } catch {
+          cached = null
+        }
+      }
+      return cached
+    },
+  }
+}
+
+function loadTable({ snapshot, files, self }) {
+  const snap = snapshot()
+  if (!snap || !Array.isArray(snap.procs)) return null
+  const list = sessions.findSessions(snap, files())
+  const roots = new Set(list.map(s => s.pid))
+  const me = self(snap.procs)
+  return {
+    procs: snap.procs,
+    byPid: new Map(snap.procs.map(p => [p.pid, p])),
+    owner: sessions.assignOwners(snap.procs, roots),
+    info: new Map(list.map(s => [s.pid, s])),
+    me,
+    // without knowing which session this is, no session can be called another one
+    others: me ? list.filter(s => s.pid !== me) : [],
+  }
+}
+
+function label(t, pid) {
+  const s = t.info.get(pid)
+  return s && s.cwd ? `${shortPath(s.cwd)} (pid ${pid})` : `pid ${pid}`
+}
+
+// The other session a process belongs to, or null.
+function otherOwner(t, pid) {
+  const o = t.owner.get(pid)
+  return o && o !== t.me && t.info.has(o) ? o : null
+}
+
+// Another live session exists: a sentence naming one, or null.
+function othersCheck(t) {
+  return t && t.others.length ? `Another Claude session is running here: ${label(t, t.others[0].pid)}.` : null
+}
+
+// A literal PID that is another session's process, or any Claude session's own process.
+function pidsCheck(t, pids) {
+  if (!t || !t.me) return null
+  for (const raw of pids) {
+    const pid = Math.abs(raw)
+    const p = t.byPid.get(pid)
+    if (!p) continue
+    if (pid === t.me) return `PID ${pid} is your own Claude session.`
+    const o = otherOwner(t, pid)
+    if (o) return `PID ${pid} (${p.name}) belongs to the Claude session ${label(t, o)}.`
+  }
+  return null
+}
+
+// A pkill or killall pattern that would reach another session's processes.
+function patternCheck(t, pattern, { full = false, exact = false } = {}) {
+  if (!t || !t.me || !pattern || String(pattern).length > 500) return null
+  let re
+  try {
+    re = new RegExp(exact ? `^(?:${pattern})$` : pattern, 'i')
+  } catch {
+    return null
+  }
+  for (const p of t.procs) {
+    const o = otherOwner(t, p.pid)
+    if (!o) continue
+    if (re.test(full ? p.cmd : p.name)) return `That pattern matches PID ${p.pid} (${p.name}) of the Claude session ${label(t, o)}.`
+  }
+  return null
+}
+
+// docker compose down in a folder another live session works in.
+function sameProjectCheck(t, dir) {
+  if (!t || !t.others.length) return null
+  const here = path.resolve(dir)
+  const hit = t.others.find(s => {
+    if (!s.cwd) return false
+    const there = path.resolve(s.cwd)
+    return there === here || there.startsWith(here + path.sep) || here.startsWith(there + path.sep)
+  })
+  return hit ? `Claude session ${label(t, hit.pid)} works in the same project.` : null
+}
+
+module.exports = { makeContext, loadTable, label, otherOwner, othersCheck, pidsCheck, patternCheck, sameProjectCheck, shortPath }

package/src/log-cli.js

@@ -1,9 +1,9 @@
 'use strict'
 const { stateDir } = require('./hook')
 const { readEvents, eventsFile } = require('./events')
-const { useColor, paint, shortPath, option, fit, table, rejectArgs } = require('./cli-util')
+const { useColor, paint, shortPath, option, numberOption, fit, table, rejectArgs } = require('./cli-util')
 
-const USAGE = `usage: bulkhead log [-n N] [--since 7d|24h|30m] [--guard NAME] [--summary] [--json]
+const USAGE = `usage: bulkhead log [SPAN] [-n N] [--since 7d|24h|30m] [--guard NAME] [--summary] [--json]
 
 Lists what the guards blocked and what orphan-reaper stopped, newest last.
   -n N           how many events to list (default 20; ignored with --summary)
@@ -110,23 +110,28 @@ function renderList(events, { color = false, home, width = 120, now = Date.now()
 
 function main(args, { env = process.env, stdout = process.stdout, stderr = process.stderr, now = Date.now(), dir = stateDir() } = {}) {
   if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
+  // `bulkhead log 24h` reads as `--since 24h`, the way /bulkhead:log takes its argument
+  if (args.length && /^(\d+[mhdw]|\d{4}-\d{2}-\d{2})$/.test(args[0])) args = ['--since', args[0], ...args.slice(1)]
   if (rejectArgs('log', args, { flags: ['json', 'summary'], valued: ['since', 'guard', 'limit'], shorts: ['n'] }, stderr, USAGE)) return
   const sinceArg = option(args, 'since')
   let since = null
   if (sinceArg !== undefined && sinceArg !== '') {
-    since = parseSince(sinceArg, now)
+    since = sinceArg === true ? NaN : parseSince(sinceArg, now)
     if (!Number.isFinite(since)) {
-      stderr.write(`bulkhead log: cannot read --since ${sinceArg}; use 30m, 24h, 7d, 2w or a date like 2026-10-01\n`)
+      stderr.write(`bulkhead log: ${sinceArg === true ? '--since needs a value' : `cannot read --since ${sinceArg}`}; use 30m, 24h, 7d, 2w or a date like 2026-10-01\n`)
       process.exitCode = 1
       return
     }
   }
   const guard = option(args, 'guard')
-  const nArg = (() => {
-    const i = args.indexOf('-n')
-    return i >= 0 ? args[i + 1] : option(args, 'limit')
-  })()
-  const n = Number(nArg) > 0 ? Math.floor(Number(nArg)) : 20
+  const i = args.indexOf('-n')
+  const count = numberOption(i >= 0 ? ['--n', args[i + 1]] : args, i >= 0 ? 'n' : 'limit', { fallback: 20 })
+  if (count.error) {
+    stderr.write(`bulkhead log: ${count.error.replace('--n ', '-n ')}\n`)
+    process.exitCode = 1
+    return
+  }
+  const n = Math.max(1, Math.floor(count.value))
   const events = filter(readEvents(dir), { since, guard: typeof guard === 'string' ? guard : null })
   const json = args.includes('--json')
   const color = useColor(stdout, env)
@@ -143,4 +148,4 @@ function main(args, { env = process.env, stdout = process.stdout, stderr = proce
   stdout.write(renderList(recent, { color, width: stdout.columns || 160, now }) + '\n')
 }
 
-module.exports = { main, parseSince, filter, summarize, renderSummary, renderList }
+module.exports = { main, parseSince, filter, summarize, renderSummary, renderList, USAGE }