claude-bulkhead 0.2.2 → 0.3.0

package/src/sessions.js

@@ -2,18 +2,26 @@
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const { execFileSync } = require('child_process')
+const { agentOf, installedAgents } = require('./agents')
 
 // On Windows the desktop app and the CLI are both claude.exe. The app's processes run from
-// ...\app\Claude.exe (or Claude.app on macOS) and its helpers carry --type=.
-const DESKTOP_APP = /[\\/]app[\\/]Claude\.exe|Claude\.app[\\/]Contents[\\/]MacOS[\\/]Claude(?:["\s]|$)/i
+// ...\app\Claude.exe (or Claude.app on macOS) and its helpers carry --type=. On macOS the
+// app's own Claude Code sessions run from .../claude-code/<x.y.z>/<hash>/claude.app/Contents/
+// MacOS/claude, so the macOS match is case-sensitive: Claude.app/.../Claude is the app,
+// claude.app/.../claude is the CLI. The app starts each one through Contents/Helpers/disclaimer,
+// whose command line names the CLI too; that wrapper is not a session.
+const DESKTOP_APP = /[\\/]app[\\/]Claude\.exe/i
+const DESKTOP_APP_MAC = /Claude\.app\/Contents\/(?:MacOS\/Claude(?:["\s]|$)|Helpers\/)/
+const BUNDLED_CLI_MAC = /\/claude\.app\/Contents\/MacOS\/claude(?:["\s]|$)/
 const PID_REUSE_SLACK_MS = 120 * 1000
 
 // The native installer runs versions/<x.y.z> through a `claude` link, so the process name can be
 // the version; the command line still starts with claude or names that folder.
 function isClaudeCli(p) {
   if (!p) return false
-  if (/--type=/.test(p.cmd) || DESKTOP_APP.test(p.cmd)) return false
-  if (/^claude(?:\.exe)?$/i.test(p.name)) return true
+  if (/--type=/.test(p.cmd) || DESKTOP_APP.test(p.cmd) || DESKTOP_APP_MAC.test(p.cmd)) return false
+  if (/^claude(?:\.exe)?$/i.test(p.name) || BUNDLED_CLI_MAC.test(p.cmd)) return true
   if (/^["']?(?:\S*[\\/])?claude(?:\.exe)?["']?(?:\s|$)|[\\/]claude[\\/]versions[\\/]/i.test(p.cmd)) return true
   return /^(?:node|bun)(?:\.exe)?$/i.test(p.name) && /claude-code[\\/]cli\.js|@anthropic-ai[\\/]claude-code/i.test(p.cmd)
 }
@@ -36,10 +44,6 @@ function readSessionFiles(dir = path.join(claudeDir(), 'sessions')) {
   return files
 }
 
-function linuxCwd(pid) {
-  try { return fs.readlinkSync(`/proc/${pid}/cwd`) } catch { return null }
-}
-
 // Maps every process to the session whose tree it is in. A child must be younger than its
 // parent, which skips Windows children whose parent PID was reused. On Linux a server that
 // outlived its shell is still matched through CLAUDE_PID.
@@ -106,14 +110,70 @@ function snapshotOwner(p, byPid, sessionPids, known = new Map()) {
   return fits.length === 1 ? fits[0] : null
 }
 
-// [{ pid, start, cwd, rss, ports: [{ port, pid, name }] }], oldest first.
-function findSessions({ procs, ports = [] }, files = new Map(), cwdOf = process.platform === 'linux' ? linuxCwd : () => null) {
+function linuxCwd(pid) {
+  try { return fs.readlinkSync(`/proc/${pid}/cwd`) } catch { return null }
+}
+
+// The working directories of several processes at once. macOS has no /proc: one lsof call
+// answers for all of them. Windows has no cheap way, so those sessions have no cwd and the
+// checks that need a folder skip them.
+function readCwds(pids, platform = process.platform, run = execFileSync) {
+  const out = new Map()
+  if (!pids.length) return out
+  if (platform === 'linux') {
+    for (const pid of pids) out.set(pid, linuxCwd(pid))
+  } else if (platform === 'darwin') {
+    let text = ''
+    try {
+      text = run('lsof', ['-a', '-p', pids.join(','), '-d', 'cwd', '-Fn'], { encoding: 'utf8', timeout: 5000, env: { ...process.env, LC_ALL: 'C' } })
+    } catch (e) { text = String(e.stdout || '') } // lsof exits 1 when one of the processes is gone
+    let pid = 0
+    for (const line of text.split('\n')) {
+      if (line[0] === 'p') pid = Number(line.slice(1))
+      else if (line[0] === 'n' && pid) out.set(pid, line.slice(1))
+    }
+  }
+  return out
+}
+
+// Claude Code sessions first, as before. Another agent's tree is one session at its outermost
+// process: the npm launchers of Codex and Gemini start the real program as a child.
+function sessionRoots(procs) {
   const byPid = new Map(procs.map(p => [p.pid, p]))
-  const roots = procs.filter(isClaudeCli)
-  const owner = assignOwners(procs, new Set(roots.map(p => p.pid)))
-  return roots.sort((a, b) => a.start - b.start).map(p => {
-    const f = files.get(p.pid)
-    const fileMatches = f && (!f.startedAt || !p.start || Math.abs(f.startedAt - p.start) < PID_REUSE_SLACK_MS)
+  const roots = []
+  for (const p of procs) {
+    if (isClaudeCli(p)) {
+      roots.push({ proc: p, agent: 'claude' })
+      continue
+    }
+    const agent = agentOf(p)
+    if (!agent) continue
+    let cur = byPid.get(p.ppid)
+    let nested = false
+    for (let i = 0; cur && i < 40 && !nested; i++) {
+      nested = cur.start <= p.start && !isClaudeCli(cur) && agentOf(cur) === agent
+      cur = byPid.get(cur.ppid)
+    }
+    if (!nested) roots.push({ proc: p, agent })
+  }
+  return roots
+}
+
+// [{ pid, agent, start, cwd, rss, ports: [{ port, pid, name }] }], oldest first.
+function findSessions({ procs, ports = [] }, files = new Map(), cwdOf = null, platform = process.platform, run = execFileSync) {
+  const byPid = new Map(procs.map(p => [p.pid, p]))
+  const roots = sessionRoots(procs)
+  const owner = assignOwners(procs, new Set(roots.map(r => r.proc.pid)))
+  const fileCwd = r => {
+    const f = files.get(r.proc.pid)
+    const fileMatches = f && (!f.startedAt || !r.proc.start || Math.abs(f.startedAt - r.proc.start) < PID_REUSE_SLACK_MS)
+    return (fileMatches && f.cwd) || null
+  }
+  // Claude Code names its folder in a session file; the others are asked once, together
+  const others = roots.filter(r => r.agent !== 'claude').map(r => r.proc.pid)
+  const asked = cwdOf ? new Map() : readCwds(others, platform, run)
+  return roots.sort((a, b) => a.proc.start - b.proc.start).map(r => {
+    const p = r.proc
     let rss = 0
     let children = 0
     for (const [pid, root] of owner) {
@@ -121,10 +181,12 @@ function findSessions({ procs, ports = [] }, files = new Map(), cwdOf = process.
       rss += byPid.get(pid).rss || 0
       if (pid !== p.pid) children++
     }
+    const fallback = cwdOf ? cwdOf(p.pid) : r.agent === 'claude' ? (platform === 'linux' ? linuxCwd(p.pid) : null) : asked.get(p.pid)
     return {
       pid: p.pid,
+      agent: r.agent,
       start: p.start,
-      cwd: (fileMatches && f.cwd) || cwdOf(p.pid),
+      cwd: fileCwd(r) || fallback || null,
       rss,
       children,
       ports: ports.filter(l => owner.get(l.pid) === p.pid).map(l => ({ ...l, name: byPid.get(l.pid).name })),
@@ -132,16 +194,43 @@ function findSessions({ procs, ports = [] }, files = new Map(), cwdOf = process.
   })
 }
 
-// The session a process runs under: its nearest Claude ancestor, or CLAUDE_PID.
+// The session a process runs under: its nearest Claude ancestor, else the outermost process of
+// the nearest other agent, else CLAUDE_PID.
 function ownSession(procs, pid = process.pid, env = process.env) {
   const byPid = new Map(procs.map(p => [p.pid, p]))
   let cur = byPid.get(pid)
+  let found = null
   for (let i = 0; cur && i < 40; i++) {
-    if (isClaudeCli(cur)) return cur.pid
+    if (isClaudeCli(cur)) return found ? found.pid : cur.pid
+    const agent = agentOf(cur)
+    if (agent && (!found || found.agent === agent)) found = { pid: cur.pid, agent }
     const par = byPid.get(cur.ppid)
     cur = par && par.start <= cur.start ? par : null
   }
-  return Number(env.CLAUDE_PID) || null
+  return found ? found.pid : Number(env.CLAUDE_PID) || null
+}
+
+// Session files for the checks that need each live session's folder (checkout-guard): Claude
+// Code's own files plus a cwd for every other agent's process. The process table is only read
+// when one of the other agents has left a folder in the home directory, and never for the agent
+// the caller runs under.
+function readLiveSessionFiles({
+  files = readSessionFiles(), installed = installedAgents, read = () => require('./processes').readProcesses(process.platform, { ports: false }),
+  platform = process.platform, run = execFileSync, self = process.pid,
+} = {}) {
+  const merged = new Map(files)
+  try {
+    if (!installed().length) return merged
+    const snap = read()
+    if (!snap) return merged
+    const mine = new Set()
+    const byPid = new Map(snap.procs.map(p => [p.pid, p]))
+    for (let cur = byPid.get(self), i = 0; cur && i < 40; cur = byPid.get(cur.ppid), i++) mine.add(cur.pid)
+    const roots = sessionRoots(snap.procs).filter(r => r.agent !== 'claude' && !mine.has(r.proc.pid))
+    const cwds = readCwds(roots.map(r => r.proc.pid), platform, run)
+    for (const r of roots) merged.set(r.proc.pid, { cwd: cwds.get(r.proc.pid) || null, startedAt: r.proc.start, status: null, sessionId: null, agent: r.agent })
+  } catch {}
+  return merged
 }
 
-module.exports = { isClaudeCli, readSessionFiles, findSessions, assignOwners, ownSession, claudeDir }
+module.exports = { PID_REUSE_SLACK_MS, isClaudeCli, readSessionFiles, readLiveSessionFiles, readCwds, sessionRoots, findSessions, assignOwners, ownSession, claudeDir }

package/src/shell.js

@@ -13,6 +13,8 @@
 // mode is 'sh' (Bash tool), 'ps' (PowerShell tool) or 'cmd' (inside cmd /c). Every function is
 // linear in the length of its input: no regular expression here can backtrack across the text.
 
+const os = require('os')
+
 const MAX_DEPTH = 3
 
 // The program name of a command word: no directory, no Windows extension, lower case. Guards ask
@@ -252,7 +254,8 @@ function skipOptions(words, k, valued = new Set()) {
 // delete guards look after this machine only.
 function isRemote(argv) {
   const b = bin(argv[0].v)
-  if (b === 'ssh' || b === 'autossh' || b === 'mosh') return true
+  if (b === 'ssh') return !sshToThisMachine(argv)
+  if (b === 'autossh' || b === 'mosh') return true
   // bulkhead remote run sends its command to another machine
   if (b === 'bulkhead' && argv[1] && argv[1].v === 'remote') return true
   const sub = argv.slice(1, 5).map(w => w.v)
@@ -262,6 +265,16 @@ function isRemote(argv) {
   return false
 }
 
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0', os.hostname().toLowerCase()])
+
+// ssh localhost runs its command on this machine, so the guards read it like a local shell.
+function sshToThisMachine(argv) {
+  const at = skipOptions(argv, 1, SSH_VALUE)
+  if (at >= argv.length) return false
+  const host = argv[at].v.replace(/^.*@/, '').toLowerCase()
+  return LOCAL_HOSTS.has(host) || /^127\.\d+\.\d+\.\d+$/.test(host)
+}
+
 // UTF-16LE base64, as powershell -EncodedCommand takes it.
 function decodeEncoded(s) {
   try {
@@ -318,7 +331,11 @@ function innerOf(src, argv, mode) {
       else if (v === '--command') c = true
       k += SHELL_VALUE.has(v) ? 2 : 1
     }
-    return c && k < argv.length ? { text: vals[k], mode: 'sh' } : null
+    if (c && k < argv.length) return { text: vals[k], mode: 'sh' }
+    // bash <(echo "...") runs what the substitution prints
+    const sub = vals.find((v, j) => j >= k && /^<\(.*\)$/s.test(v))
+    const printed = sub && printedBy(sub.slice(2, -1), mode)
+    return printed ? { text: printed, mode: 'sh' } : null
   }
   if (b === 'powershell' || b === 'pwsh' || b === 'powershell_ise') {
     for (let k = 1; k < argv.length; k++) {
@@ -353,7 +370,17 @@ function innerOf(src, argv, mode) {
     }
     return null
   }
-  if (b === 'eval' && argv.length > 1) return { text: vals.slice(1).join(' '), mode }
+  if (b === 'ssh') return remoteInner(src, argv)
+  if (b === 'eval' && argv.length > 1) return { text: fed(vals.slice(1).join(' ')), mode }
+  if (b === 'source' || (b === '.' && mode === 'sh')) {
+    const sub = vals.find((v, k) => k > 0 && /^<\(.*\)$/s.test(v))
+    const printed = sub && printedBy(sub.slice(2, -1), mode)
+    return printed ? { text: printed, mode } : null
+  }
+  if (b === 'tmux') return tmuxInner(vals)
+  if (b === 'screen') return screenInner(argv)
+  if (b === 'script') return scriptInner(vals)
+  if (b === 'parallel') return parallelInner(vals)
   if (b === 'trap' && argv.length > 1 && vals[1] !== '-' && !vals[1].startsWith('-')) return { text: vals[1], mode }
   if (b === 'watch') {
     const k = skipOptions(argv, 1, WATCH_VALUE)
@@ -388,6 +415,84 @@ function innerOf(src, argv, mode) {
   return null
 }
 
+// What echo or printf prints, when the text is that one command: the script a pipe, <( ) or
+// $( ) hands to a shell. Null for anything else.
+function printedBy(text, mode) {
+  const { cmds } = lex(String(text), mode)
+  if (cmds.length !== 1) return null
+  const ws = cmds[0].words.map(w => w.v)
+  const b = bin(ws[0] || '')
+  if (b !== 'echo' && b !== 'printf') return null
+  let k = 1
+  while (k < ws.length && /^-[neE]+$/.test(ws[k])) k++
+  const rest = ws.slice(k)
+  if (b === 'printf' && rest.length && !/%/.test(rest[0])) return rest[0]
+  return rest.join(' ') || null
+}
+
+// eval "$(echo ...)": the printed text is the code
+function fed(text) {
+  const m = /^\$\((.*)\)$|^`(.*)`$/s.exec(text.trim())
+  const printed = m && printedBy(m[1] || m[2], 'sh')
+  return printed || text
+}
+
+const TMUX_VALUE = new Set(['-s', '-n', '-t', '-c', '-x', '-y', '-e', '-f', '-F', '-l', '-L', '-S', '-T'])
+const TMUX_RUN = new Set(['new', 'new-session', 'new-window', 'neww', 'split-window', 'splitw', 'run-shell', 'run', 'respawn-pane', 'respawnp', 'respawn-window', 'respawnw', 'send-keys', 'send'])
+
+// tmux new -d 'cmd', tmux run-shell 'cmd', tmux send-keys 'cmd' Enter
+function tmuxInner(vals) {
+  let k = 1
+  while (k < vals.length && /^-/.test(vals[k])) k += TMUX_VALUE.has(vals[k]) ? 2 : 1
+  if (!TMUX_RUN.has(vals[k])) return null
+  const sub = vals[k]
+  const words = []
+  for (k++; k < vals.length; k++) {
+    const v = vals[k]
+    if (/^-/.test(v) && !words.length) { k += TMUX_VALUE.has(v) ? 1 : 0; continue }
+    if (/^send/.test(sub) && /^(?:Enter|C-m|C-j|KPEnter)$/.test(v)) continue
+    words.push(v)
+  }
+  return words.length ? { text: words.join(' '), mode: 'sh' } : null
+}
+
+// screen -dmS name cmd args
+function screenInner(argv) {
+  let k = 1
+  while (k < argv.length && /^-/.test(argv[k].v) && !argv[k].q) {
+    const v = argv[k].v
+    if (v === '--') { k++; break }
+    k += /^-[a-zA-Z]*[SsTtcpeXhLlQ]$/.test(v) && /[SsTtcpeXhLQ]$/.test(v) ? 2 : 1
+  }
+  return k < argv.length ? { text: argv.slice(k).map(w => w.v).join(' '), mode: 'sh' } : null
+}
+
+// script -q /dev/null cmd args (macOS), script -qc "cmd" /dev/null (Linux)
+function scriptInner(vals) {
+  let k = 1
+  let c = false
+  while (k < vals.length && /^-/.test(vals[k])) {
+    if (/^-[a-zA-Z]*c$/.test(vals[k]) || vals[k] === '--command') { c = true; k++; break }
+    k += /^-[tFTW]$/.test(vals[k]) ? 2 : 1
+  }
+  if (c) return vals[k] ? { text: vals[k], mode: 'sh' } : null
+  k++ // the typescript file
+  return k < vals.length ? { text: vals.slice(k).join(' '), mode: 'sh' } : null
+}
+
+// parallel pkill ::: node, parallel pkill {} ::: a b
+function parallelInner(vals) {
+  const at = vals.indexOf(':::')
+  if (at < 0) return null
+  let k = 1
+  while (k < vals.length && k < at && /^-/.test(vals[k])) k += /^-[jNnSaIlLsTtbCEiRrXx]$|^--(?:jobs|max-args|colsep|arg-file)$/.test(vals[k]) ? 2 : 1
+  const cmd = vals.slice(k, at)
+  const args = vals.slice(at + 1)
+  if (!cmd.length || !args.length) return null
+  const lines = args.slice(0, 50).map(a => cmd.some(w => w.includes('{}')) ? cmd.map(w => w.split('{}').join(a)).join(' ') : `${cmd.join(' ')} ${a}`)
+  return { text: lines.join('\n'), mode: 'sh' }
+}
+
 // Takes leading wrappers off a command's words. Returns { argv, inner, remote, at }.
 function strip(src, words, mode) {
   let k = 0
@@ -422,6 +527,13 @@ function strip(src, words, mode) {
       continue
     }
     if (b === 'xargs') { k = skipOptions(words, k + 1, XARGS_VALUE); continue }
+    if (b === 'busybox' && words[k + 1] && !SHELLS.has(bin(words[k + 1].v))) { k++; continue }
+    // function k() { ...; }  and  k() { ...; }: the body runs when the function is called
+    if (!w.q && v === 'function' && words[k + 1]) {
+      k += words[k + 2] && words[k + 2].v === '()' ? 3 : 2
+      continue
+    }
+    if (!w.q && /^[A-Za-z_][\w-]*\(\)$/.test(v) && k === 0 && words[1] && words[1].v === '{') { k++; continue }
     break
   }
   const argv = words.slice(k)
@@ -431,7 +543,7 @@ function strip(src, words, mode) {
 }
 
 // Quick test before lexing for wrappers: most commands have none.
-const WRAPPER_HINT = /(?:^|[^\w-])(?:bash|sh|zsh|dash|ksh|ash|mksh|fish|busybox|powershell|pwsh|powershell_ise|cmd|eval|trap|watch|su|env|Start-Process|saps|start)(?:\.exe)?(?![\w-])/i
+const WRAPPER_HINT = /(?:^|[^\w-])(?:bash|sh|zsh|dash|ksh|ash|mksh|fish|busybox|powershell|pwsh|powershell_ise|cmd|eval|trap|watch|su|env|Start-Process|saps|start|ssh|tmux|screen|script|parallel|source|\.)(?:\.exe)?(?![\w-])/i
 const REMOTE_HINT = /(?:^|[^\w-])(?:ssh|docker|podman|nerdctl|kubectl|oc|bulkhead)(?:\.exe)?(?![\w-])/i
 
 // Every simple command the text runs, with wrappers taken off and shell wrappers opened.
@@ -446,9 +558,27 @@ function commands(src, mode = 'sh', depth = 0, out = []) {
   return out
 }
 
+// The text an echo or printf feeds into the shell that follows it in a pipe (echo "..." | sh),
+// or null when cmd is not that shell. prev is the command before it.
+function pipedScript(src, prev, c, s, mode) {
+  if (!prev || prev.seg !== c.seg || prev.sub !== c.sub || !s.argv.length || s.inner) return null
+  const b = bin(s.argv[0].v)
+  if (!SHELLS.has(b) && !(b === 'busybox' && SHELLS.has(bin((s.argv[1] || {}).v || '')))) return null
+  if (!/^\s*\|&?\s*$/.test(src.slice(prev.e, c.s))) return null
+  const text = printedBy(src.slice(prev.s, prev.e), mode)
+  return text
+}
+
 function collect(src, cmds, mode, depth, out) {
+  let prev = null
   for (const c of cmds) {
     const s = strip(src, c.words, mode)
+    const piped = depth < MAX_DEPTH && pipedScript(src, prev, c, s, mode)
+    prev = c
+    if (piped) {
+      commands(piped, mode, depth + 1, out)
+      continue
+    }
     if (s.inner && depth < MAX_DEPTH) {
       commands(s.inner.text, s.inner.mode, depth + 1, out)
       continue
@@ -468,9 +598,18 @@ function unwrap(src, mode = 'sh', depth = 0, { remote = false } = {}) {
   const cmds = lex(src, mode).cmds.sort((a, b) => a.s - b.s)
   const parts = []
   let last = 0
+  let prev = null
   for (const c of cmds) {
+    const before = prev
+    prev = c
     if (c.s < last) continue
     const s = strip(src, c.words, mode)
+    const piped = pipedScript(src, before, c, s, mode)
+    if (piped && before.s >= last) {
+      parts.push(src.slice(last, before.s), `( ${unwrap(piped, mode, depth + 1, { remote })} )`)
+      last = c.e
+      continue
+    }
     const inner = s.inner || (remote && s.remote ? remoteInner(src, s.argv) : null)
     if (!inner) continue
     const from = s.argv[0].s
@@ -485,17 +624,82 @@ function unwrap(src, mode = 'sh', depth = 0, { remote = false } = {}) {
 // ---------------------------------------------------------------------------------------------
 // Text that is never executed
 
-const EXEC_WORDS = /(?:^|[\s;&|(`"$])(?:bash|sh|zsh|eval|source|pwsh|powershell|python[\d.]*|py|node|deno|bun|ruby|perl|php|osascript)(?:\.exe)?(?=[\s"')]|$)/
 const MESSAGE_TOOLS = new Set(['git', 'gh', 'glab', 'hub', 'hg', 'svn', 'jj', 'tea'])
 const MESSAGE_FLAGS = /^(?:-m|--message|--title|--body|--notes|--description|--subject|--comment|-[a-z]*m)$/
 const GH_SHORT = /^-[tbd]$/
 
-// Heredocs whose body is never run: written to a file by cat or tee, printed by cat, or handed
-// to git and gh as a message (git commit -F -, gh pr create --body-file -). The opener line
-// stays; the body and terminator go. A tag is searched for once, so missing terminators cost
-// one pass in total.
-function stripHeredocs(src) {
-  const docs = heredocs(src, heredocNotRun)
+// What reads a heredoc decides what its body is. A shell (or eval, source, ssh to this machine)
+// runs it as shell code. An interpreter (python, node, ...) runs it as code in its own language,
+// and ssh, docker exec and the like run it on another machine. Anything else, cat, tee, read,
+// git, a loop, wc, a program with its own input, only reads it as data.
+const INTERPRETERS = /^(?:python[\d.]*|pythonw|py|node|nodejs|deno|bun|ruby|perl|php|lua|osascript)$/
+const KIND_RANK = { data: 0, interp: 1, remote: 2, shell: 3 }
+
+// python3 - <<E and node <<E run what is on stdin; python3 script.py <<E, node -e 'code' <<E and
+// python3 -m module <<E give stdin to a program as input.
+function readsScriptFromStdin(argv) {
+  for (let k = 1; k < argv.length; k++) {
+    const v = argv[k].v
+    if (v === '-') return true
+    if (/^-(?:c|e|E|m|p|r|-eval|-print)$/.test(v) || !/^-/.test(v) || argv[k].q) return false
+  }
+  return true
+}
+
+function stageKind(text, mode) {
+  let kind = 'data'
+  for (const c of lex(text, mode).cmds) {
+    const s = strip(text, c.words, mode)
+    if (!s.argv.length) continue
+    const b = bin(s.argv[0].v)
+    let k = 'data'
+    if (s.remote) k = 'remote'
+    else if (s.inner || SHELLS.has(b) || b === 'eval' || b === 'source' || (b === '.' && s.argv.length > 1) || /^(?:powershell|pwsh|cmd)$/.test(b)) k = 'shell'
+    else if (INTERPRETERS.test(b) && readsScriptFromStdin(s.argv)) k = 'interp'
+    if (KIND_RANK[k] > KIND_RANK[kind]) { kind = k; if (k !== 'data') kind = k }
+  }
+  return kind
+}
+
+// The statement the heredoc belongs to starts after the last ; && || & ( { `do` or `then`.
+function lastStage(prefix) {
+  let cut = 0
+  for (const m of prefix.matchAll(/;|&&|\|\||(?<![<>|&])&(?![>&])|(?<![$<>])\(|(?<!\$)\{|(?:^|\s)(?:do|then|else)\s/g)) cut = m.index + m[0].length
+  const stmt = prefix.slice(cut)
+  return stmt.slice(stmt.lastIndexOf('|') + 1)
+}
+
+// The pipeline after the opener: <<E | ssh host bash
+function pipeStages(after) {
+  const end = after.search(/;|&&|\|\||(?<![<>|&])&(?![>&])|\n/)
+  const line = end < 0 ? after : after.slice(0, end)
+  return line.includes('|') ? line.split('|').slice(1) : []
+}
+
+// 'shell', 'remote', 'interp' or 'data', and the program that reads it.
+function consumerOf(prefix, after, mode = 'sh') {
+  let kind = 'data'
+  for (const st of [lastStage(prefix), ...pipeStages(after)]) {
+    const k = stageKind(st, mode)
+    if (KIND_RANK[k] > KIND_RANK[kind]) kind = k
+  }
+  let name = ''
+  if (kind === 'interp') {
+    for (const st of [lastStage(prefix), ...pipeStages(after)]) {
+      const c = lex(st, mode).cmds.map(x => strip(st, x.words, mode).argv[0]).find(w => w && INTERPRETERS.test(bin(w.v)))
+      if (c) name = bin(c.v)
+    }
+  }
+  return { kind, bin: name }
+}
+
+// Heredocs whose body is not shell code are data and go: written to a file by cat or tee,
+// counted by wc, read by a loop, handed to git or gh as a message, read by python or node (code in
+// their own language, not shell). The opener line stays; the body and terminator go. keep lists
+// the kinds that stay: ['shell'] by default, which is what a guard that reads shell text wants.
+// A tag is searched for once, so missing terminators cost one pass in total.
+function stripHeredocs(src, keep = ['shell'], mode = 'sh') {
+  const docs = heredocs(src, (prefix, after) => !keep.includes(consumerOf(prefix, after, mode).kind))
   if (!docs.length) return src
   let out = ''
   let last = 0
@@ -544,11 +748,67 @@ function heredocs(src, want) {
   return out
 }
 
-function heredocNotRun(prefix, after) {
-  if (EXEC_WORDS.test(prefix)) return false
-  const piped = after.indexOf('|') >= 0 && !/\|\s*(?:gh|git|glab|tee|cat)\b/.test(after)
-  if (/(?:^|[\s;&|(`"])(?:cat|tee)\b[^|]*$/.test(prefix)) return !piped
-  return /(?:^|[\s;&|(`"$])(?:git|gh|glab)\b/.test(prefix)
+// Shell commands that interpreter code runs from string literals: os.system('pkill node'),
+// subprocess.run(['pkill', 'node']), execSync("pkill node"), spawn('pkill', ['node']),
+// system("pkill node"). Only literals are read; a command built at run time is not seen.
+const SHELL_CALL = /(?:\b(?:os\.system|os\.popen|subprocess\.\w+|(?:child_process\.)?(?:exec|execSync|spawn|spawnSync|execFile|execFileSync)|system|popen|shell_exec|passthru|proc_open))\s*[({]\s*/g
+const LITERAL = /^[rRbBfFuU]{0,2}(?:"((?:[^"\\\n]|\\.)*)"|'((?:[^'\\\n]|\\.)*)')/
+
+// The code with string literals and comments blanked to spaces, same length: a call is found only
+// where the code makes it, not inside text the code edits or prints (a python script that rewrites
+// a markdown file holds os.system('...') as plain text).
+function maskLiterals(code) {
+  const n = code.length
+  const out = code.split('')
+  const blank = (from, to) => { for (let k = from; k < to && k < n; k++) if (out[k] !== '\n') out[k] = ' ' }
+  let i = 0
+  while (i < n) {
+    const c = code[i]
+    const spaceBefore = i === 0 || /[\s;]/.test(code[i - 1])
+    if ((c === '#' || (c === '/' && code[i + 1] === '/')) && spaceBefore) {
+      const nl = code.indexOf('\n', i)
+      const end = nl < 0 ? n : nl
+      blank(i, end)
+      i = end
+    } else if (c === '/' && code[i + 1] === '*') {
+      const close = code.indexOf('*/', i + 2)
+      const end = close < 0 ? n : close + 2
+      blank(i, end)
+      i = end
+    } else if (c === '"' || c === "'" || c === '`') {
+      const q = (c !== '`' && code.startsWith(c.repeat(3), i)) ? c.repeat(3) : c
+      let k = i + q.length
+      while (k < n && !code.startsWith(q, k)) {
+        if (code[k] === '\\') k++
+        else if (q.length === 1 && c !== '`' && code[k] === '\n') break
+        k++
+      }
+      blank(i + q.length, k)
+      i = k + q.length
+    } else i++
+  }
+  return out.join('')
+}
+
+function embeddedShell(code) {
+  const out = []
+  code = String(code || '').slice(0, 200000)
+  const masked = maskLiterals(code)
+  for (const m of masked.matchAll(SHELL_CALL)) {
+    if (out.length >= 20) break
+    const words = []
+    let at = m.index + m[0].length
+    for (let n = 0; n < 40; n++) {
+      const rest = code.slice(at, at + 2000)
+      const lead = /^[\s[,]*/.exec(rest)[0]
+      const lit = LITERAL.exec(rest.slice(lead.length))
+      if (!lit) break
+      words.push((lit[1] !== undefined ? lit[1] : lit[2]).replace(/\\(["'\\])/g, '$1'))
+      at += lead.length + lit[0].length
+    }
+    if (words.length) out.push(words.join(' '))
+  }
+  return out
 }
 
 // The quoted text after -m, --message, --title, --body, --notes in git, gh and similar commands
@@ -584,8 +844,8 @@ function stripMessages(src, mode) {
   return out + src.slice(last)
 }
 
-function prepare(src, mode = 'sh') {
-  return stripMessages(stripHeredocs(String(src || '')), mode)
+function prepare(src, mode = 'sh', keep = ['shell']) {
+  return stripMessages(stripHeredocs(String(src || ''), keep, mode), mode)
 }
 
 // The lexer mode for a hook payload's tool.
@@ -594,4 +854,4 @@ function modeFor(input) {
   return /powershell/i.test(String(tool || '')) ? 'ps' : 'sh'
 }
 
-module.exports = { lex, commands, unwrap, prepare, stripHeredocs, stripMessages, heredocs, strip, bin, modeFor, skipOptions, MAX_DEPTH }
+module.exports = { lex, commands, unwrap, prepare, stripHeredocs, stripMessages, heredocs, consumerOf, embeddedShell, strip, bin, modeFor, skipOptions, MAX_DEPTH }