claude-bulkhead 0.2.2 → 0.3.0

package/src/secrets-guard.js

@@ -0,0 +1,301 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { runHook, blocked, setting, ASK_USER } = require('./hook')
+const shell = require('./shell')
+
+// Opt-in (secretsGuard.enabled). Stops the agent from reading secret files into the conversation:
+// the Read and Grep tools on them, and shell commands that print, encode or upload them or dump the
+// whole environment. Writing a secret file is fine, and so are ls, stat, test -f and git check-ignore.
+// This is a guard against careless reads, not a sandbox: a program that opens the file itself is not seen.
+
+const SAFE_ENV = /^\.env\.(?:example|sample|template|dist|defaults|tpl|schema)$/i
+const SSH_SAFE = /^(?:config|known_hosts(?:\.old)?|authorized_keys2?|allowed_signers|environment|rc)$|\.pub$/i
+const PUBLIC_PEM = /-----BEGIN (?:CERTIFICATE|TRUSTED CERTIFICATE|PUBLIC KEY|X509 CRL|CERTIFICATE REQUEST)-----/
+const NPM_TOKEN = /_authToken|_auth\b|_password|:_password/i
+// Files that hold a secret only some of the time: read, and block when they do.
+const CONTENT_RULES = [
+  [/(?:^|\/)\.npmrc$/i, NPM_TOKEN, 'an npm auth token'],
+  [/(?:^|\/)\.yarnrc\.yml$/i, /npmAuthToken|npmAuthIdent/i, 'an npm auth token'],
+  [/(?:^|\/)\.pypirc$/i, /password|token/i, 'a PyPI password or token'],
+  [/(?:^|\/)\.docker\/config\.json$/i, /"auth"\s*:|identitytoken|registrytoken/i, 'Docker registry credentials'],
+]
+// Names a shell glob such as .env* or ~/.ssh/* could expand to.
+const SAMPLES = ['.env', '.env.local', '.env.production', 'id_rsa', 'id_ed25519', 'server.pem', 'server.key', 'credentials',
+  'hosts.yml', '.netrc', 'config', 'config.json', 'credentials.db', 'access_tokens.db', 'application_default_credentials.json', '.npmrc']
+
+const SECRET_DIRS = /\/(?:\.ssh|\.aws|\.kube|\.azure|\.config\/gh|\.config\/gcloud)$/i
+const READERS = new Set(['cat', 'tac', 'less', 'more', 'most', 'head', 'tail', 'nl', 'bat', 'batcat', 'cut', 'sort', 'uniq', 'od', 'xxd',
+  'hexdump', 'strings', 'base64', 'base32', 'basenc', 'grep', 'egrep', 'fgrep', 'rg', 'ag', 'ack', 'sed', 'awk', 'gawk', 'mawk', 'nawk',
+  'jq', 'yq', 'diff', 'cmp', 'comm', 'paste', 'column', 'fold', 'rev', 'get-content', 'gc', 'type', 'select-string', 'sls',
+  'cp', 'scp', 'rsync', 'curl', 'wget'])
+// the first plain argument of these is a pattern or a program, not a file
+const PATTERN_FIRST = new Set(['grep', 'egrep', 'fgrep', 'rg', 'ag', 'ack', 'sed', 'awk', 'gawk', 'mawk', 'nawk', 'jq', 'yq', 'select-string', 'sls'])
+const COPIERS = new Set(['cp', 'scp', 'rsync'])
+// options of the copy tools that take a value which is not a file to copy (scp -i ~/.ssh/id_rsa names a key it uses)
+const VALUE_FLAGS = { cp: ['-t', '-S'], scp: ['-i', '-o', '-P', '-F', '-J', '-l', '-c', '-S'], rsync: ['-e', '--rsh', '--port', '--rsync-path', '--exclude', '--include'] }
+const UPLOAD_FLAG = /^(?:-T|--upload-file|--post-file|--body-file|-d|--data|--data-binary|--data-urlencode|-F|--form|--json)$/
+const CLI_PRINTERS = [
+  [/^gh auth token\b|^gh auth status\b.*(?:\s-t\b|--show-token)/, 'the GitHub CLI token'],
+  [/^gcloud auth (?:application-default )?print-(?:access|identity)-token\b/, 'a Google Cloud access token'],
+  [/^aws configure get\s+\S*(?:secret|token|key)/i, 'an AWS secret'],
+  [/^npm (?:config|c) get\s+\S*(?:_auth|token|password)/i, 'an npm auth token'],
+]
+
+function globRegex(pattern, { shellGlob = false } = {}) {
+  let re = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]
+    if (c === '*' && pattern[i + 1] === '*') { re += '.*'; i++ }
+    else if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp((shellGlob && !pattern.startsWith('.') ? '^(?!\\.)' : '^') + re + '$', 'i')
+}
+
+function expand(arg, cwd, home) {
+  let p = String(arg).replace(/\\/g, '/')
+  p = p.replace(/^~(?=\/|$)/, home).replace(/^(?:\$HOME|\$\{HOME\}|\$env:USERPROFILE|%USERPROFILE%)(?=\/|$)/i, home)
+  p = p.replace(/^(?:\$PWD|\$\{PWD\})(?=\/|$)/, cwd)
+  return path.posix.normalize(/^(?:\/|[a-zA-Z]:\/)/.test(p) ? p : `${cwd.replace(/\\/g, '/')}/${p}`)
+}
+
+// Whether `p` (absolute, forward slashes) matches a user pattern: a plain file name, or a path
+// pattern that may start with ~ and use * and **.
+function userMatch(p, patterns, home) {
+  return patterns.some(raw => {
+    const pat = raw.replace(/\\/g, '/').replace(/^~(?=\/|$)/, home)
+    if (!pat.includes('/')) return globRegex(pat).test(p.slice(p.lastIndexOf('/') + 1))
+    const re = globRegex(pat.replace(/^\*\*\//, ''))
+    return pat.startsWith('/') || /^[a-zA-Z]:/.test(pat) ? globRegex(pat).test(p) : new RegExp(`(?:^|/)${re.source.slice(1)}`, 'i').test(p)
+  })
+}
+
+function peek(file) {
+  try {
+    const fd = fs.openSync(file, 'r')
+    try {
+      const buf = Buffer.alloc(32768)
+      return buf.toString('utf8', 0, fs.readSync(fd, buf, 0, buf.length, 0))
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch { return null }
+}
+
+// The kind of secret the file is, or null. `p` is absolute with forward slashes.
+function classifyPath(p, { home = os.homedir().replace(/\\/g, '/'), extra = [], allow = [], read = peek } = {}) {
+  if (allow.length && userMatch(p, allow, home)) return null
+  const base = p.slice(p.lastIndexOf('/') + 1)
+  const lower = p.toLowerCase()
+  const parent = lower.split('/').slice(-2, -1)[0]
+  if (/^\.env(?:\..+)?$/i.test(base) && !SAFE_ENV.test(base)) return 'an environment file'
+  if (/\.(?:pem|key|p12|pfx)$/i.test(base)) {
+    const text = /\.(?:pem|key)$/i.test(base) ? read(p) : null
+    return text && PUBLIC_PEM.test(text) && !/PRIVATE KEY/.test(text) ? null : 'a private key file'
+  }
+  if (/^id_(?:rsa|dsa|ecdsa|ed25519)/i.test(base) && !/\.pub$/i.test(base)) return 'an SSH private key'
+  if (parent === '.ssh' && !SSH_SAFE.test(base)) return 'an SSH private key'
+  if (/^(?:\.netrc|_netrc)$/i.test(base)) return 'netrc credentials'
+  if (/^(?:\.git-credentials|\.pgpass|\.vault-token)$/i.test(base)) return 'stored credentials'
+  if (/\/\.aws\/credentials$/.test(lower) || /\/\.aws\/sso\/cache\//.test(lower)) return 'AWS credentials'
+  if (/\/\.config\/gh\/hosts\.yml$/.test(lower)) return 'the GitHub CLI token'
+  if (/\/\.kube\/config$/.test(lower)) return 'Kubernetes credentials'
+  if (/\/\.azure\/accesstokens\.json$/.test(lower)) return 'Azure tokens'
+  if (/\/gcloud\/(?:credentials\.db|access_tokens\.db|application_default_credentials\.json|legacy_credentials\/)/.test(lower)) return 'Google Cloud credentials'
+  if (/^\/proc\/[^/]+\/environ$/.test(lower)) return 'a process environment'
+  for (const [name, content, label] of CONTENT_RULES) {
+    if (!name.test(lower)) continue
+    const text = read(p)
+    return text && content.test(text) ? label : null
+  }
+  if (extra.length && userMatch(p, extra, home)) return 'a file you listed in secretsGuard.extraPatterns'
+  return null
+}
+
+// classifyPath for an argument: a literal path, or a glob that could expand to a secret.
+function classifyArg(arg, ctx, opts) {
+  if (!arg || typeof arg !== 'string') return null
+  const p = expand(arg, ctx.cwd, ctx.home)
+  const name = p.slice(p.lastIndexOf('/') + 1)
+  if (!/[*?[]/.test(name)) return classifyPath(p, opts)
+  const dir = p.slice(0, p.lastIndexOf('/'))
+  const likely = `${dir}/${name.replace(/[*?[\]]/g, 'x')}`
+  if (opts.extra && opts.extra.length && !(opts.allow && opts.allow.length && userMatch(likely, opts.allow, opts.home)) && userMatch(likely, opts.extra, opts.home)) {
+    return 'a file you listed in secretsGuard.extraPatterns'
+  }
+  // a bare * says nothing about which names it expands to; only a folder of secrets makes it a hit
+  if (/^[*?]+$/.test(p.slice(p.lastIndexOf('/') + 1)) && !SECRET_DIRS.test(dir)) return null
+  const re = globRegex(p.slice(p.lastIndexOf('/') + 1), { shellGlob: true })
+  for (const s of SAMPLES) {
+    if (!re.test(s)) continue
+    const found = classifyPath(`${dir}/${s}`, opts)
+    if (found) return found
+  }
+  return null
+}
+
+// A folder that holds secrets (~/.ssh, ~/.aws), for commands that read everything below it.
+function classifyDir(arg, ctx, opts) {
+  const p = expand(arg, ctx.cwd, ctx.home).replace(/\/+$/, '')
+  return SECRET_DIRS.test(p) ? classifyArg(`${p}/*`, ctx, opts) : null
+}
+
+// The files a reader command names, in the places a file can be named.
+function fileArgs(argv, b) {
+  const args = argv.slice(1)
+  if (b === 'sed' && args.some(a => /^-[a-zA-Z]*i/.test(a) || a.startsWith('--in-place'))) return []
+  const out = []
+  const takesPattern = PATTERN_FIRST.has(b) && !args.some(a => /^(?:-e|-f|--regexp|--file|--expression|-Pattern)(?:=|$)/i.test(a))
+  let seen = !takesPattern
+  const upload = b === 'curl' || b === 'wget'
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (/^(?:\d*>>?|&>>?|>\||\d*>&.*)$/.test(a) || a === '<<<' || a === '<<') { i++; continue }
+    if (/^\d*>/.test(a)) continue
+    if (a === '<') { if (args[i + 1]) out.push(args[++i]); continue }
+    if (/^<[^<(]/.test(a)) { out.push(a.slice(1)); continue }
+    if ((VALUE_FLAGS[b] || []).includes(a)) { i++; continue }
+    if (upload) {
+      const m = /^(-T|--upload-file|--post-file|--body-file|-d|--data|--data-binary|--data-urlencode|-F|--form|--json)(?:=(.*))?$/.exec(a) || /^(-[dFT])(.+)$/.exec(a)
+      if (m && UPLOAD_FLAG.test(m[1])) {
+        const v = m[2] !== undefined ? m[2] : args[++i]
+        if (v == null) continue
+        if (/^(?:-T|--upload-file|--post-file|--body-file)$/.test(m[1])) out.push(v)
+        else {
+          const f = /(?:^|=)[@<](.+)$/.exec(v) || /^[\w-]+@(.+)$/.exec(v) || /^@(.+)$/.exec(v)
+          if (f) out.push(f[1].split(';')[0])
+        }
+      }
+      continue
+    }
+    if (a.startsWith('-') && a !== '-') {
+      const eq = a.indexOf('=')
+      if (a.startsWith('--') && eq > 0) out.push(a.slice(eq + 1))
+      continue
+    }
+    if (!seen) { seen = true; continue }
+    out.push(a)
+  }
+  if (COPIERS.has(b)) out.pop()
+  return b === 'scp' || b === 'rsync' ? out.filter(a => !/^[^/\\]{2,}:/.test(a)) : out
+}
+
+// A pipe straight into something that only counts or tests keeps the values out of the output.
+function harmlessPipe(text, end) {
+  const m = /^\s*\|&?\s*([\w./-]+)((?:\s+-[\w-]+)*)/.exec(text.slice(end))
+  if (!m) return false
+  const b = shell.bin(m[1])
+  return b === 'wc' || (/^e?grep$/.test(b) && /(?:^|\s)-[a-zA-Z]*[qcl]/.test(m[2]))
+}
+
+function withoutRedirects(words) {
+  const out = []
+  for (let i = 0; i < words.length; i++) {
+    if (/^(?:\d*>>?|&>>?|>\||<)$/.test(words[i])) i++
+    else if (!/^\d*[<>]/.test(words[i])) out.push(words[i])
+  }
+  return out
+}
+
+// `env`, `printenv`, `export -p`, a bare `set`: the whole environment.
+function dumpsEnvironment(text, mode) {
+  const bare = rest => rest.every(a => /^-[a-zA-Z0-9-]*$/.test(a) && a !== '-S')
+  let unwrapped = text
+  try { unwrapped = shell.unwrap(text, mode) } catch {}
+  for (const c of shell.lex(unwrapped, mode).cmds) {
+    const i = c.words.findIndex(w => !/^(?:sudo|doas|command|exec|nohup|time|builtin)$/.test(shell.bin(w.v)) && !(w.v.startsWith('-') && !shell.bin(w.v)))
+    if (i < 0) continue
+    const b = shell.bin(c.words[i].v)
+    const rest = withoutRedirects(c.words.slice(i + 1).map(w => w.v))
+    const dump = ((b === 'env' || b === 'printenv') && bare(rest)) ||
+      ((b === 'export' || b === 'declare' || b === 'typeset') && rest.length && rest.every(a => /^-[pxf]+$/.test(a)) && !rest.includes('-f')) ||
+      ((b === 'export' || b === 'set') && !rest.length) ||
+      (b === 'compgen' && rest.join(' ') === '-e') ||
+      (/^(?:get-childitem|gci|dir|ls)$/.test(b) && rest.some(a => /^env:\\?\*?$/i.test(a)) && !rest.some(a => /^env:\\?\w/i.test(a)))
+    if (dump && !harmlessPipe(unwrapped, c.e)) return true
+  }
+  return false
+}
+
+function findHit(argv, ctx, opts) {
+  const args = argv.slice(1)
+  const exec = args.findIndex(a => /^-(?:exec|execdir|ok|okdir)$/.test(a))
+  if (exec < 0 || !READERS.has(shell.bin(args[exec + 1] || ''))) return null
+  const starts = []
+  for (const a of args) { if (a.startsWith('-') || a === '(' || a === '!') break; starts.push(a) }
+  for (const s of starts) {
+    const hit = classifyDir(s, ctx, opts)
+    if (hit) return { label: hit, what: s }
+  }
+  for (let i = 0; i < args.length - 1; i++) {
+    if (!/^-(?:i?name|i?path|i?wholename)$/.test(args[i])) continue
+    const hit = classifyArg(args[i + 1], { ...ctx, cwd: '/x' }, opts)
+    if (hit) return { label: hit, what: args[i + 1] }
+  }
+  return null
+}
+
+// { rule, label, what } for the first secret the command would show, or null.
+function classifyCommand(cmd, { cwd = process.cwd(), home = os.homedir().replace(/\\/g, '/'), extra = [], allow = [], read = peek, mode = 'sh' } = {}) {
+  const ctx = { cwd: cwd.replace(/\\/g, '/'), home }
+  const opts = { home, extra, allow, read }
+  const text = shell.prepare(String(cmd || ''), mode)
+  for (const c of shell.commands(text, mode)) {
+    if (c.remote) continue
+    const b = shell.bin(c.argv[0])
+    const joined = c.argv.join(' ')
+    if (b === 'find') {
+      const hit = findHit(c.argv, ctx, opts)
+      if (hit) return { rule: 'print-file', label: hit.label, what: hit.what }
+    }
+    for (const [re, label] of CLI_PRINTERS) if (re.test(joined)) return { rule: 'print-token', label, what: joined }
+    if (!READERS.has(b)) continue
+    for (const a of fileArgs(c.argv, b)) {
+      const label = classifyArg(a, ctx, opts) || (/^(?:grep|egrep|fgrep|rg|ag|ack|get-content|gc|type|cat|cp|scp|rsync)$/.test(b) ? classifyDir(a, ctx, opts) : null)
+      if (label) return { rule: b === 'cp' || b === 'scp' || b === 'rsync' || b === 'curl' || b === 'wget' ? 'copy-file' : 'print-file', label, what: a }
+    }
+  }
+  if (/\benv\b|printenv|export|declare|typeset|\bset\b|compgen|get-childitem|gci|\bdir\b|\bls\b/i.test(text) && dumpsEnvironment(text, mode)) {
+    return { rule: 'dump-env', label: 'every environment variable', what: 'the whole environment' }
+  }
+  return null
+}
+
+function classifyTool(input, opts) {
+  const t = input.tool_input || {}
+  const cwd = (input.cwd || process.cwd()).replace(/\\/g, '/')
+  const ctx = { cwd, home: opts.home }
+  if (input.tool_name === 'Read') {
+    const label = classifyArg(t.file_path, ctx, opts)
+    return label && { rule: 'read-file', label, what: t.file_path }
+  }
+  if (input.tool_name === 'Grep') {
+    const label = classifyArg(t.path, ctx, opts) || (t.glob ? classifyArg(`${t.path || '.'}/${t.glob}`, ctx, opts) : null)
+    return label && { rule: 'read-file', label, what: t.path || t.glob }
+  }
+  return null
+}
+
+function message(hit) {
+  return `[bulkhead] secrets-guard: this would show ${hit.label} (${hit.what}) to the model.\n` +
+    'Ask the user for the specific value you need, or use it by name (for example $API_KEY or --env-file .env) without printing it.\n' +
+    ASK_USER
+}
+
+function handle(input) {
+  const home = os.homedir().replace(/\\/g, '/')
+  const opts = { home, extra: setting('secretsGuard.extraPatterns', []), allow: setting('secretsGuard.allow', []) }
+  const cmd = input.tool_input && input.tool_input.command
+  const hit = cmd
+    ? classifyCommand(cmd, { ...opts, cwd: input.cwd || process.cwd(), mode: shell.modeFor(input) })
+    : classifyTool(input, opts)
+  if (!hit) return
+  return blocked('secrets-guard', hit.rule, input, message(hit), cmd || hit.what)
+}
+
+if (require.main === module) runHook('secrets-guard', handle)
+
+module.exports = { handle, classifyCommand, classifyTool, classifyPath, classifyArg, message, globRegex }

package/src/self-allow.js

@@ -0,0 +1,73 @@
+'use strict'
+const path = require('path')
+const shell = require('./shell')
+
+// The agent must not approve its own blocks. `bulkhead allow <code>` is for the user, in their
+// own terminal, so a Bash tool call that runs it, or that writes the allow state files by hand,
+// is blocked (basics, rule self-allow).
+
+const NAMES = /^(?:bulkhead|claude-bulkhead|bulkhead-cli)(?:\.(?:js|cjs|mjs|cmd|ps1|exe))?$/i
+const SCRIPT = /(?:^|[\\/])(?:bin[\\/](?:bulkhead|claude-bulkhead|bulkhead-cli)|src[\\/](?:cli|allow-cli|allow-once)\.js)$/i
+const NODE = /^(?:node|nodejs|bun|deno|tsx|ts-node)$/i
+const RUNNER = /^(?:npx|bunx|pnpx|pnpm|npm|yarn|bun|dlx|exec|x)$/i
+
+const base = a => path.basename(String(a).replace(/\\/g, '/')).replace(/@[\w.^~-]+$/, '')
+const isAllow = a => /^allow$/i.test(a)
+
+// Whether one simple command is a run of `bulkhead allow`.
+function runsAllow(argv) {
+  if (!argv.length) return false
+  const b = shell.bin(argv[0])
+  const rest = argv.slice(1)
+  if (NAMES.test(b)) return rest.slice(0, 4).some(isAllow)
+  if (NODE.test(b)) {
+    const i = rest.findIndex(a => SCRIPT.test(String(a).replace(/\\/g, '/')) || NAMES.test(base(a)))
+    return i >= 0 && rest.slice(i + 1, i + 4).some(isAllow)
+  }
+  if (RUNNER.test(b)) {
+    const i = rest.findIndex(a => NAMES.test(base(a)) || /^claude-bulkhead(?:@|$)/i.test(a))
+    return i >= 0 && rest.slice(i + 1, i + 4).some(isAllow)
+  }
+  // $BULKHEAD allow 7F3K, `which bulkhead` allow: a name that is only known at run time
+  return /^[$`]|^\$\(/.test(argv[0]) && rest.some(isAllow)
+}
+
+const READERS = /^(?:cat|ls|dir|type|head|tail|less|more|grep|egrep|rg|wc|stat|file|find|test|\[|get-content|gc|get-childitem|select-string|echo|printf)$/i
+const REDIRECT = />/
+
+// The folders that hold the allow state: the default one and the one BULKHEAD_STATE_DIR names.
+function stateRe(stateDir) {
+  const esc = s => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/[\\/]+/g, '[\\\\/]+')
+  const parts = ['bulkhead[\\\\/]+allow(?:[\\\\/]|\\b)']
+  if (stateDir) parts.push(`${esc(stateDir)}[\\\\/]+allow(?:[\\\\/]|\\b)`)
+  return new RegExp(parts.join('|'), 'i')
+}
+
+// Whether the text writes into (or runs anything but a plain read on) the allow state folder.
+function touchesAllowState(src, mode, stateDir) {
+  const re = stateRe(stateDir)
+  if (!re.test(src)) return false
+  const text = shell.prepare(src, mode)
+  for (const seg of text.split(/\n|;|&&|\|\|/)) {
+    if (!re.test(seg)) continue
+    const cmds = shell.commands(seg, mode)
+    const reads = cmds.length > 0 && cmds.every(c => READERS.test(shell.bin(c.argv[0])))
+    if (!reads || REDIRECT.test(seg.replace(/\d?>&\d|\d?>\s*(?:\/dev\/null|\$null|nul)\b/gi, ' '))) return true
+  }
+  return false
+}
+
+// A message when the command approves a block itself, or null.
+function check(cmd, { mode = 'sh', stateDir = process.env.BULKHEAD_STATE_DIR } = {}) {
+  const src = String(cmd || '')
+  if (!/allow/i.test(src)) return null
+  const prepared = shell.prepare(src, mode)
+  const hit = shell.commands(prepared, mode).find(c => runsAllow(c.argv))
+  if (hit || touchesAllowState(src, mode, stateDir)) {
+    return '[bulkhead] basics: the agent cannot approve its own blocks. `bulkhead allow <code>` and the allow state files are for the user.\n' +
+      'Do not run it or edit the files. Tell the user what was blocked and the code from the block message; they run `bulkhead allow <code>` in their own terminal, then you retry the same command.'
+  }
+  return null
+}
+
+module.exports = { check, runsAllow, touchesAllowState }

package/src/session-info.js

@@ -0,0 +1,121 @@
+'use strict'
+const os = require('os')
+const { execFileSync } = require('child_process')
+const { gitInfo } = require('./git-info')
+const { assignOwners } = require('./sessions')
+const { findMcp } = require('./mcp')
+const { readStates, stateOf } = require('./session-state')
+
+function homeShort(p, home = os.homedir()) {
+  if (!p) return null
+  const s = String(p)
+  return home && s.toLowerCase().startsWith(home.toLowerCase()) ? '~' + s.slice(home.length).replace(/\\/g, '/') : s.replace(/\\/g, '/')
+}
+
+// Cut from the start so the useful tail stays: "…/dev/api". Starts at a folder boundary when it can.
+function fitPath(s, width) {
+  s = String(s == null ? '' : s)
+  if (width <= 0) return ''
+  if (s.length <= width) return s
+  if (width === 1) return '…'
+  const tail = s.slice(s.length - (width - 1))
+  const cut = tail.indexOf('/')
+  return '…' + (cut > 0 && cut < tail.length - 1 ? tail.slice(cut) : tail)
+}
+
+// "session 83183 in ~/dev/api on branch feat-x": how guards name another session in their messages.
+// `s` needs pid and cwd; the branch is read from the folder unless the session already has one.
+function describeSession(s, { home = os.homedir(), git = gitInfo } = {}) {
+  let branch = s.branch
+  let worktree = s.worktree
+  if (branch === undefined && s.cwd) {
+    try {
+      const g = git(s.cwd)
+      branch = g ? g.branch : null
+      worktree = g ? g.worktree : false
+    } catch { branch = null }
+  }
+  return `session ${s.pid}` + (s.cwd ? ` in ${homeShort(s.cwd, home)}` : '') +
+    (branch ? ` on branch ${branch}${worktree ? ' (worktree)' : ''}` : '')
+}
+
+// pid -> cwd for sessions with no session file. macOS: one lsof for all of them; Linux reads
+// /proc in findSessions already; Windows has no cheap way, so those stay unknown.
+function lookupCwds(pids, { platform = process.platform, run = execFileSync } = {}) {
+  const out = new Map()
+  if (platform !== 'darwin' || !pids.length) return out
+  let text = ''
+  try {
+    text = run('lsof', ['-a', '-d', 'cwd', '-Fn', '-p', pids.join(',')], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, LC_ALL: 'C' } })
+  } catch (e) { text = String((e && e.stdout) || '') }
+  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
+}
+
+// Adds branch, worktree and the working/waiting state to each session, and the MCP report.
+// Everything here reads small files; the only subprocess is the optional cwd lookup.
+function enrich(sessions, snapshot, files, {
+  states = readStates(), git = gitInfo, cwds = lookupCwds,
+} = {}) {
+  const missing = sessions.filter(s => !s.cwd).map(s => s.pid)
+  const found = missing.length ? cwds(missing) : new Map()
+  const cache = new Map()
+  const gitOf = dir => {
+    if (!cache.has(dir)) {
+      let g = null
+      try { g = git(dir) } catch {}
+      cache.set(dir, g)
+    }
+    return cache.get(dir)
+  }
+  const out = sessions.map(s => {
+    const cwd = s.cwd || found.get(s.pid) || null
+    const g = cwd ? gitOf(cwd) : null
+    const rec = stateOf(states, s, files.get(s.pid))
+    return {
+      ...s,
+      cwd,
+      branch: g ? g.branch : null,
+      worktree: g ? g.worktree : false,
+      state: rec ? rec.state : null,
+      stateReason: rec ? rec.reason : null,
+      stateSince: rec ? rec.since : null,
+    }
+  })
+  const owner = assignOwners(snapshot.procs, new Set(out.map(s => s.pid)))
+  const mcp = findMcp(snapshot.procs, owner, out)
+  for (const s of out) s.mcp = mcp.instances.filter(i => i.session === s.pid).map(i => ({ name: i.name, pid: i.pid, rss: i.rss }))
+  return { sessions: out, mcp: mcp.groups }
+}
+
+// Human text for the STATE column.
+function stateLabel(s, now) {
+  if (!s.state) return '-'
+  const mins = Math.max(0, Math.floor((now - s.stateSince) / 60000))
+  const age = mins >= 1 ? ` ${mins >= 60 ? `${Math.floor(mins / 60)}h` : `${mins}m`}` : ''
+  if (s.state === 'working') return 'working'
+  if (s.state === 'permission') return (s.stateReason === 'input' ? 'needs input' : 'needs permission') + age
+  return 'waiting' + age
+}
+
+// Sessions that need you first (permission, then waiting the longest), then the rest in their order.
+function needsUserFirst(sessions) {
+  const rank = s => (s.state === 'permission' ? 0 : s.state === 'waiting' ? 1 : 2)
+  return sessions.map((s, i) => [s, i]).sort((a, b) => rank(a[0]) - rank(b[0]) ||
+    (rank(a[0]) < 2 ? a[0].stateSince - b[0].stateSince : 0) || a[1] - b[1]).map(x => x[0])
+}
+
+function branchLabel(s) {
+  return s.branch ? s.branch + (s.worktree ? ' (wt)' : '') : s.worktree ? '(wt)' : '-'
+}
+
+// "3 copies of @playwright/mcp, 1.2 GB"
+function mcpLine(g, size) {
+  return `${g.copies} copies of ${g.name}, ${size(g.rss)}`
+}
+
+module.exports = { homeShort, fitPath, describeSession, lookupCwds, enrich, stateLabel, needsUserFirst, branchLabel, mcpLine }

package/src/session-state.js

@@ -0,0 +1,176 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { spawn } = require('child_process')
+const { runHook, setting, stateDir } = require('./hook')
+
+// What each session is doing: working, waiting for you, or waiting on a permission prompt.
+// The hooks in hooks/hooks.json call this script; it writes one small JSON file per session in
+// <state dir>/session-state/ and reads nothing else (no process table, no git). `bulkhead status`
+// and `top` join those files to live sessions by session id, so a file left by a dead session
+// is never shown.
+//
+// Events (https://code.claude.com/docs/en/hooks):
+//   UserPromptSubmit, PostToolUse, PostToolUseFailure  the turn is running: working
+//   Stop                                               Claude finished its reply: waiting
+//   Notification permission_prompt                     a tool needs your approval: permission
+//   Notification elicitation_dialog, elicitation_url_dialog   Claude asks you a question: permission (reason input)
+//   Notification idle_prompt                           still waiting; keeps the state it has
+//   SessionStart (not source compact)                  a new prompt is open: waiting
+//   SessionEnd                                         the file is removed
+
+const WORKING = 'working'
+const WAITING = 'waiting'
+const PERMISSION = 'permission'
+// A PostToolUse hook runs async, so the last one of a turn can finish after Stop wrote "waiting".
+// It only takes a session out of "waiting" when that state is older than this.
+const WAITING_GRACE_MS = 3000
+const STALE_FILE_MS = 2 * 24 * 3600 * 1000
+
+function dirFor(base = stateDir()) {
+  return path.join(base, 'session-state')
+}
+
+// The session id becomes a file name, so only plain characters pass.
+function safeId(id) {
+  return typeof id === 'string' && /^[\w.-]{1,128}$/.test(id) && !/^\.+$/.test(id) ? id : null
+}
+
+// What a hook payload means: { remove: true }, { state, reason, notify, soft } or null to ignore.
+// `soft` means the event only confirms the state and must not replace a waiting one younger than the grace.
+function classify(input) {
+  switch (input && input.hook_event_name) {
+    case 'UserPromptSubmit': return { state: WORKING, reason: null }
+    case 'PostToolUse':
+    case 'PostToolUseFailure': return { state: WORKING, reason: null, soft: true }
+    case 'Stop': return { state: WAITING, reason: 'reply', notify: true }
+    case 'SessionStart': return input.source === 'compact' ? null : { state: WAITING, reason: 'idle' }
+    case 'SessionEnd': return { remove: true }
+    case 'Notification':
+      switch (input.notification_type) {
+        case 'permission_prompt': return { state: PERMISSION, reason: 'permission', notify: true }
+        case 'elicitation_dialog':
+        case 'elicitation_url_dialog': return { state: PERMISSION, reason: 'input', notify: true }
+        case 'idle_prompt': return { state: WAITING, reason: 'idle', keep: true }
+      }
+  }
+  return null
+}
+
+function readRecord(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+}
+
+function writeRecord(file, rec) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(rec))
+  fs.renameSync(tmp, file)
+}
+
+// Applies one event. Returns { wrote, notify } where notify says a notification should go out now.
+function apply(base, input, { now = Date.now(), minIntervalMs = 30000 } = {}) {
+  const id = safeId(input && input.session_id)
+  const c = classify(input)
+  if (!id || !c) return { wrote: false, notify: false }
+  const dir = dirFor(base)
+  const file = path.join(dir, `${id}.json`)
+  if (c.remove) {
+    try { fs.unlinkSync(file) } catch {}
+    return { wrote: false, notify: false }
+  }
+  const prev = readRecord(file)
+  const same = prev && prev.state === c.state
+  if (c.keep && prev && (prev.state === WAITING || prev.state === PERMISSION)) return { wrote: false, notify: false }
+  if (same && !c.notify && (prev.reason || null) === (c.reason || null)) return { wrote: false, notify: false }
+  if (c.soft && prev && prev.state === WAITING && now - prev.since < WAITING_GRACE_MS) return { wrote: false, notify: false }
+  if (same && c.notify && prev.reason === c.reason) return { wrote: false, notify: false }
+  const rec = {
+    v: 1,
+    session: id,
+    state: c.state,
+    reason: c.reason,
+    since: same ? prev.since : now,
+    at: now,
+    cwd: input.cwd || (prev && prev.cwd) || null,
+    ppid: process.ppid,
+    notifiedAt: (prev && prev.notifiedAt) || 0,
+  }
+  const notify = Boolean(c.notify) && now - rec.notifiedAt >= minIntervalMs
+  if (notify) rec.notifiedAt = now
+  writeRecord(file, rec)
+  return { wrote: true, notify, record: rec }
+}
+
+// Files of sessions that ended without a SessionEnd (crash, kill) are removed after two days.
+function prune(base, now = Date.now()) {
+  const dir = dirFor(base)
+  let names = []
+  try { names = fs.readdirSync(dir) } catch { return }
+  for (const n of names) {
+    try {
+      const f = path.join(dir, n)
+      if (now - fs.statSync(f).mtimeMs > STALE_FILE_MS) fs.unlinkSync(f)
+    } catch {}
+  }
+}
+
+// Map of session id -> record, for the join in status. Unreadable files are skipped.
+function readStates(base = stateDir()) {
+  const dir = dirFor(base)
+  const out = new Map()
+  let names = []
+  try { names = fs.readdirSync(dir) } catch { return out }
+  for (const n of names.filter(x => x.endsWith('.json'))) {
+    const rec = readRecord(path.join(dir, n))
+    if (rec && rec.session && [WORKING, WAITING, PERMISSION].includes(rec.state) && Number(rec.since) > 0) out.set(rec.session, rec)
+  }
+  return out
+}
+
+// The record of a live session: by session id, else by the parent pid the hook saw. A record
+// older than the process (the same id resumed in a new process) is ignored.
+function stateOf(states, session, file, slackMs = 5000) {
+  let rec = file && file.sessionId ? states.get(file.sessionId) : null
+  if (!rec) rec = [...states.values()].find(r => r.ppid === session.pid && r.at >= session.start) || null
+  if (!rec || (session.start && rec.at < session.start - slackMs)) return null
+  return rec
+}
+
+// Spawns the user's notify command detached; it never blocks or throws into the hook.
+function runNotify(command, env, spawnFn = spawn) {
+  if (typeof command !== 'string' || !command.trim()) return false
+  try {
+    const child = spawnFn(command, { shell: true, detached: true, stdio: 'ignore', windowsHide: true, env: { ...process.env, ...env } })
+    if (child && child.unref) child.unref()
+    if (child && child.on) child.on('error', () => {})
+    return true
+  } catch {
+    return false
+  }
+}
+
+function sessionPid(sessionId) {
+  try {
+    for (const [pid, f] of require('./sessions').readSessionFiles()) if (f.sessionId === sessionId) return pid
+  } catch {}
+  return process.ppid
+}
+
+function handle(input) {
+  const minIntervalMs = Math.max(0, Number(setting('notify.minIntervalSeconds', 30))) * 1000
+  const r = apply(stateDir(), input, { minIntervalMs })
+  if (input.hook_event_name === 'SessionStart') prune(stateDir())
+  const command = setting('notify.command', null)
+  if (r.notify && command) {
+    runNotify(command, {
+      BULKHEAD_SESSION_PROJECT: input.cwd || '',
+      BULKHEAD_SESSION_STATE: r.record.state,
+      BULKHEAD_SESSION_PID: String(sessionPid(input.session_id)),
+    })
+  }
+}
+
+if (require.main === module) runHook('session-state', handle)
+
+module.exports = { classify, apply, readStates, stateOf, runNotify, prune, safeId, dirFor, WORKING, WAITING, PERMISSION, WAITING_GRACE_MS }