claude-bulkhead 0.0.0-stage → 0.2.2

package/src/disk-guard.js

@@ -0,0 +1,200 @@
+'use strict'
+const os = require('os')
+const { runHook, blocked, oneLine, ASK_USER } = require('./hook')
+const shell = require('./shell')
+
+// Disk scans that walk a whole drive or home folder, or several folders at once. The disk is
+// shared by every session on the machine: one `du` over the home folder, or ten of them through
+// xargs -P, keeps it busy for minutes, and every other session's builds, tests and git commands
+// crawl until the scans end.
+
+// Programs that read every file under the folders they are given.
+const SIZERS = new Set(['du', 'ncdu', 'dust', 'gdu', 'diskus', 'dua', 'duf'])
+const PS_WALKERS = new Set(['get-childitem', 'gci', 'ls', 'dir'])
+
+// ~, $HOME and %USERPROFILE% become the home directory. Returns null for anything with a variable
+// we cannot expand, so `du -sh "$DIR"` is not guessed at.
+function expand(arg, home) {
+  const a = String(arg)
+    .replace(/^~(?=[\\/]|$)/, home)
+    .replace(/^(?:\$HOME|\$\{HOME\}|\$env:USERPROFILE|\$env:HOME|%USERPROFILE%|\$USERPROFILE)(?=[\\/]|$)/i, home)
+  return /[$%]/.test(a) ? null : a
+}
+
+const clean = p => p.replace(/\\/g, '/').replace(/\/\*$/, '').replace(/\/+$/, '') || '/'
+
+// What a folder argument covers when it is the whole drive, the home folder or every user's home.
+function wholeDisk(arg, home) {
+  const a = expand(arg, home)
+  if (a === null) return null
+  const p = clean(a)
+  const h = clean(home)
+  const lower = p.toLowerCase()
+  if (p === '/' || /^[a-z]:\/?$/i.test(p) || /^\/(?:mnt\/)?[a-z]$/i.test(p) || lower === '/system/volumes/data') return 'the whole drive'
+  if (p === h || lower === h.toLowerCase()) return 'your whole home folder'
+  if (/^(?:\/users|\/home|[a-z]:\/users|\/(?:mnt\/)?[a-z]\/users)$/i.test(p)) return 'every home folder on the machine'
+  return null
+}
+
+// Folder operands of a sizer or a recursive listing; options and their values are skipped.
+function operands(argv) {
+  const dir = shell.bin(argv[0]) === 'dir'
+  const out = []
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') { out.push(...argv.slice(i + 1)); break }
+    if (/^-(?:d|-max-depth|-exclude|X|-exclude-from|B|-block-size|t|-threshold|Depth|Filter|Include|Exclude|Path|LiteralPath)$/i.test(a)) {
+      if (/^-(?:Path|LiteralPath)$/i.test(a) && argv[i + 1]) out.push(argv[i + 1])
+      i++
+      continue
+    }
+    // cmd's dir takes /s and /a; elsewhere /c is a Git Bash drive and stays an operand
+    if (a.startsWith('-') || (dir && /^\/[a-z]$/i.test(a))) continue
+    out.push(a)
+  }
+  return out.length ? out : ['.']
+}
+
+// Get-ChildItem -Recurse, ls -R (in sh, where ls -r only sorts), and cmd's dir /s.
+function recursiveListing(argv, mode) {
+  const b = shell.bin(argv[0])
+  const args = argv.slice(1)
+  if (b === 'get-childitem' || b === 'gci' || (mode === 'ps' && PS_WALKERS.has(b))) return args.some(a => /^-r(?:ecurse)?$/i.test(a))
+  if (b === 'ls') return args.some(a => /^-[a-zA-Z]*R/.test(a))
+  return b === 'dir' && args.some(a => /^\/s$/i.test(a))
+}
+
+function isScan(argv, mode = 'sh') {
+  const b = shell.bin(argv[0])
+  if (SIZERS.has(b)) return !argv.slice(1).some(a => /^(?:--version|--help)$/.test(a))
+  return recursiveListing(argv, mode)
+}
+
+// find / and find ~ without -maxdepth walk every file on the drive.
+function wideFind(argv, home) {
+  if (shell.bin(argv[0]) !== 'find') return null
+  if (argv.some(a => /^-maxdepth(?:=|$)/.test(a))) return null
+  const starts = []
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (/^-[HLP]$/.test(a)) continue
+    if (a.startsWith('-') || a === '(' || a === '!') break
+    starts.push(a)
+  }
+  for (const s of starts) {
+    const what = wholeDisk(s, home)
+    if (what) return { what, target: s }
+  }
+  return null
+}
+
+// xargs -P N in front of the command (the parser takes the wrapper off its words): N > 1, or 0,
+// which means as many as possible. Reads only the command's own prefix, word by word.
+function xargsParallel(text, c) {
+  const first = c.words && c.words[0]
+  if (!first || first.s <= c.s) return false
+  const words = text.slice(c.s, first.s).split(/\s+/).filter(Boolean)
+  for (let i = 0; i < words.length; i++) {
+    if (shell.bin(words[i]) !== 'xargs') continue
+    for (let k = i + 1; k < words.length; k++) {
+      const w = words[k]
+      let n = null
+      if (w === '-P' || w === '--max-procs') n = words[k + 1]
+      else if (/^-P\d+$/.test(w)) n = w.slice(2)
+      else if (w.startsWith('--max-procs=')) n = w.slice(12)
+      if (n != null && /^\d+$/.test(n) && Number(n) !== 1) return true
+    }
+  }
+  return false
+}
+
+// parallel du -sh, rush 'du -sh {}', ForEach-Object -Parallel { Get-ChildItem $_ -Recurse }:
+// the scan is an argument of a command that runs it many times at once.
+function fanOut(argv, mode) {
+  const b = shell.bin(argv[0])
+  const runner = /^(?:parallel|rush|xjobs)$/.test(b) ||
+    ((b === 'foreach-object' || b === '%') && argv.some(a => /^-parallel$/i.test(a)))
+  if (!runner) return false
+  for (let i = 1; i < argv.length; i++) {
+    const words = argv.slice(i).join(' ').replace(/[{}'"]/g, ' ').trim().split(/\s+/)
+    if (isScan(words, mode === 'ps' ? 'ps' : mode)) return true
+  }
+  return false
+}
+
+// The scan runs in parallel: through xargs -P N (N > 1), GNU parallel, ForEach-Object -Parallel,
+// Start-Job, or as one of several scans sent to the background with &.
+function parallel(text, scans, mode) {
+  for (const c of scans) if (xargsParallel(text, c)) return 'through xargs -P'
+  if (mode === 'ps' && /\bStart-(?:Thread)?Job\b/i.test(text)) return 'as parallel PowerShell jobs'
+  const bg = scans.filter(c => /^[ \t]*&(?!&)/.test(text.slice(c.e)))
+  if (bg.length >= 2 || (bg.length === 1 && scans.length >= 2)) return 'as several background jobs'
+  // for d in */; do du -sh "$d" & done: one command in the text, many processes
+  if (bg.length === 1) {
+    const head = text.slice(0, bg[0].e)
+    const loop = head.search(/\b(?:for|while|until)\b/)
+    if (loop >= 0 && /\bdo\b/.test(head.slice(loop))) return 'as a background job in a loop'
+  }
+  return null
+}
+
+function check(cmd, { home = os.homedir(), mode = 'sh' } = {}) {
+  if (typeof cmd !== 'string' || !cmd) return null
+  const text = shell.prepare(cmd, mode)
+  const cmds = shell.commands(text, mode).filter(c => !c.remote)
+  // offsets of commands inside bash -c '...' point into the inner text, so only top-level
+  // commands are checked for being run in parallel
+  const scans = []
+  for (const c of cmds) {
+    const seg = oneLine(c.argv.join(' '), 120)
+    const found = wideFind(c.argv, home)
+    if (found) {
+      return {
+        rule: 'disk-wide-find',
+        why: `[bulkhead] disk-guard: \`${seg}\` walks ${found.what} (${found.target}) with no depth limit.\n` +
+          'Other sessions share this disk; a walk over millions of files slows their builds, tests and git for minutes.\n' +
+          'Search the folder you mean (find ./src -name ...), or add -maxdepth 3. To find a file by name, try `mdfind`, `locate` or `git ls-files` first.',
+      }
+    }
+    if (c.depth === 0 && fanOut(c.argv, mode)) {
+      return {
+        rule: 'parallel-disk-scan',
+        why: parallelMessage(cmd, 'several at a time'),
+      }
+    }
+    if (!isScan(c.argv, mode)) continue
+    if (c.depth === 0) scans.push(c)
+    for (const op of operands(c.argv)) {
+      const what = wholeDisk(op, home)
+      if (what) {
+        return {
+          rule: 'disk-wide-scan',
+          why: `[bulkhead] disk-guard: \`${seg}\` reads ${what} (${op}).\n` +
+            'Other sessions share this disk; sizing everything keeps it busy for minutes and slows their work.\n' +
+            'Measure one folder at a time, in the foreground: du -sh ./node_modules, or du -sh ~/Library/Caches. Start from the folders you already suspect.',
+        }
+      }
+    }
+  }
+  if (!scans.length) return null
+  const how = parallel(text, scans, mode)
+  if (!how) return null
+  return { rule: 'parallel-disk-scan', why: parallelMessage(cmd, how) }
+}
+
+function parallelMessage(cmd, how) {
+  return `[bulkhead] disk-guard: \`${oneLine(cmd, 120)}\` runs disk scans ${how}.\n` +
+    'Several scans at once keep the disk at 100% and freeze the other sessions, and they finish no sooner than one at a time.\n' +
+    'Run one du at a time, in the foreground: du -sh <one folder>.'
+}
+
+if (require.main === module) {
+  runHook('disk-guard', input => {
+    const cmd = input.tool_input && input.tool_input.command
+    const hit = check(cmd, { mode: shell.modeFor(input) })
+    if (!hit) return
+    return blocked('disk-guard', hit.rule, input, `${hit.why}\n${ASK_USER}`)
+  })
+}
+
+module.exports = { check, wholeDisk, isScan }

package/src/doctor.js

@@ -0,0 +1,255 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync, execFileSync } = require('child_process')
+const { stateDir } = require('./hook')
+const config = require('./config')
+const { logSize, readEvents } = require('./events')
+const { readMemory } = require('./memory')
+const { readProcesses } = require('./processes')
+const { readSessionFiles, findSessions, claudeDir } = require('./sessions')
+const { limits, readSlots, slotDir, staleReason } = require('./slots')
+const { useColor, paint, shortPath, bytes, rejectArgs } = require('./cli-util')
+const remote = require('./remote')
+
+const ROOT = path.resolve(__dirname, '..')
+const SMALL_MACHINE_GB = 24
+
+const ok = (id, summary) => ({ id, status: 'OK', summary })
+const warn = (id, summary) => ({ id, status: 'WARN', summary })
+const fail = (id, summary) => ({ id, status: 'FAIL', summary })
+
+function checkNode(version = process.versions.node) {
+  const major = Number(version.split('.')[0])
+  return major >= 18 ? ok('node', `v${version}`) : fail('node', `v${version}; bulkhead needs Node 18 or later on PATH`)
+}
+
+function checkPlugin(root = ROOT) {
+  const file = path.join(root, 'hooks', 'hooks.json')
+  let hooks
+  try {
+    hooks = JSON.parse(fs.readFileSync(file, 'utf8')).hooks
+  } catch (e) {
+    return fail('plugin', `${shortPath(file)} cannot be read: ${e.message}`)
+  }
+  const missing = []
+  const counts = []
+  for (const [event, groups] of Object.entries(hooks || {})) {
+    let n = 0
+    for (const g of groups) {
+      for (const h of g.hooks || []) {
+        n++
+        for (const a of h.args || []) {
+          const script = String(a).replace('${CLAUDE_PLUGIN_ROOT}', root)
+          if (/\.js$/.test(script) && !fs.existsSync(script)) missing.push(path.relative(root, script))
+        }
+      }
+    }
+    counts.push(`${n} ${event}`)
+  }
+  if (missing.length) return fail('plugin', `hooks.json names scripts that are missing: ${missing.join(', ')}`)
+  return ok('plugin', `${shortPath(root)}, hooks: ${counts.join(', ')}`)
+}
+
+function checkStateDir(dir = stateDir()) {
+  const probe = path.join(dir, `.doctor-${process.pid}`)
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(probe, 'ok')
+    fs.unlinkSync(probe)
+    return ok('state dir', `${shortPath(dir)} is writable`)
+  } catch (e) {
+    return fail('state dir', `${shortPath(dir)} is not writable (${e.code || e.message}); slots and the event log cannot work`)
+  }
+}
+
+function checkConfig(cfg) {
+  const files = [cfg.files.global, cfg.files.project].filter(f => f && fs.existsSync(f))
+  const out = []
+  if (!cfg.warnings.length) out.push(ok('config', files.length ? `loaded ${files.map(f => shortPath(f)).join(', ')}` : 'no config files, defaults in use'))
+  for (const w of cfg.warnings) out.push(warn('config', w.replace(/^(\S+)/, m => shortPath(m))))
+  return out
+}
+
+function why(source) {
+  if (source === 'default') return 'default'
+  if (source.startsWith('env ')) return source
+  return shortPath(source)
+}
+
+function checkGuards(cfg, platform = process.platform) {
+  const out = []
+  for (const [name, section] of Object.entries(config.GUARDS)) {
+    const key = `${section}.enabled`
+    const on = cfg.values[key] !== false
+    if (!on) {
+      out.push(ok(name, `off (${why(cfg.sources[key])})`))
+      continue
+    }
+    if (name === 'orphan-reaper' && !['win32', 'linux', 'darwin'].includes(platform)) {
+      out.push(warn(name, `on, but ${platform} is not supported, so it does nothing`))
+      continue
+    }
+    let note = 'on'
+    const offRules = Object.entries(config.RULES)
+      .filter(([, k]) => k.startsWith(section + '.') && cfg.values[k] === false)
+      .map(([r, k]) => `${r} off (${why(cfg.sources[k])})`)
+    if (offRules.length) note += `, ${offRules.join(', ')}`
+    if (name === 'basics') note += `, protected branches: ${cfg.values['basics.protectedBranches'].join(', ')}`
+    if (name === 'wait-guard') note += `, limit ${cfg.values['waitGuard.limitSeconds']}s`
+    if (name === 'kill-guard') {
+      const allow = cfg.values['killGuard.allowNames']
+      const extra = cfg.values['killGuard.extraSharedNames']
+      if (allow.length) note += `, allowed by name: ${allow.join(', ')}`
+      if (extra.length) note += `, also protected: ${extra.join(', ')}`
+    }
+    if (name === 'orphan-reaper') {
+      note += cfg.values['orphanReaper.onSessionEnd'] === false ? ', at session start only' : ', at session start and after each session ends'
+      if (cfg.values['orphanReaper.extraNames'].length) note += `, also stops: ${cfg.values['orphanReaper.extraNames'].join(', ')}`
+      if (cfg.values['orphanReaper.keepNames'].length) note += `, never stops: ${cfg.values['orphanReaper.keepNames'].join(', ')}`
+    }
+    if (name === 'port-guard' && cfg.values['portGuard.ignorePorts'].length) note += `, ignoring ports ${cfg.values['portGuard.ignorePorts'].join(', ')}`
+    out.push(ok(name, note))
+  }
+  return out
+}
+
+function checkProcesses({ read = () => readProcesses(), files = () => readSessionFiles(), now = () => Date.now(), platform = process.platform } = {}) {
+  const t0 = now()
+  let snap
+  try {
+    snap = read()
+  } catch (e) {
+    return fail('processes', `the process reader failed on ${platform}: ${String(e.message).split('\n')[0]}. port-guard and status cannot see other sessions`)
+  }
+  const ms = now() - t0
+  if (!snap) return warn('processes', `no process reader for ${platform}; port-guard, top and status see no sessions`)
+  const sessions = findSessions(snap, files())
+  const text = `${snap.procs.length} processes, ${snap.ports.length} listening ports, ${sessions.length} Claude session${sessions.length === 1 ? '' : 's'} in ${(ms / 1000).toFixed(1)}s`
+  return ms > 8000 ? warn('processes', `${text}; slow, so port-guard may hit its 20s timeout on a busy machine`) : ok('processes', text)
+}
+
+function checkSessionsDir(dir = path.join(claudeDir(), 'sessions')) {
+  return fs.existsSync(dir)
+    ? ok('sessions', `${shortPath(dir)} (${readSessionFiles(dir).size} session files)`)
+    : warn('sessions', `${shortPath(dir)} does not exist; checkout-guard cannot see other sessions and project names show as ?`)
+}
+
+function checkMemory(mem = readMemory({ withCommit: true })) {
+  const lim = limits(mem.totalGb)
+  const parts = [
+    `${mem.freeGb.toFixed(1)} of ${mem.totalGb.toFixed(1)} GB free`,
+    mem.commitPct != null ? `commit ${mem.commitPct}%` : null,
+    `memory-guard blocks heavy commands below ${lim.minFreeGb} GB`,
+    mem.totalGb < SMALL_MACHINE_GB ? 'bulkhead-slot runs one heavy job at a time' : `bulkhead-slot keeps ${lim.floorGb} GB free for a second job`,
+    mem.commitPct != null ? `and waits while commit is above ${lim.maxCommitPct}%` : null,
+  ].filter(Boolean)
+  return mem.freeGb < lim.minFreeGb ? warn('memory', `${parts.join(', ')}; free RAM is below the minimum right now`) : ok('memory', parts.join(', '))
+}
+
+function checkSlots(dir = slotDir(stateDir())) {
+  const held = readSlots(dir)
+  const stale = held.filter(s => staleReason(s))
+  if (stale.length) return warn('slots', `${held.length} held, ${stale.length} stale (${stale.map(s => `${s.label}: ${staleReason(s)}`).join('; ')}); the next bulkhead-slot run reclaims them`)
+  return ok('slots', held.length ? `${held.length} held` : 'none held')
+}
+
+function checkLog(cfg, dir = stateDir()) {
+  const key = 'log.enabled'
+  if (cfg.values[key] === false) return ok('event log', `off (${why(cfg.sources[key])})`)
+  const { bytes: size, files } = logSize(dir)
+  if (!files) return ok('event log', `${shortPath(path.join(dir, 'events.jsonl'))}, empty so far`)
+  const n = readEvents(dir).length
+  return ok('event log', `${shortPath(path.join(dir, 'events.jsonl'))}, ${n} events, ${bytes(size)} (rotates at 1 MB)`)
+}
+
+// Runs kill-guard the way Claude Code does, in a clean state dir, to prove hooks start and block.
+function checkHookRun(root = ROOT) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bulkhead-doctor-'))
+  try {
+    const t0 = Date.now()
+    const r = spawnSync(process.execPath, [path.join(root, 'src', 'kill-guard.js')], {
+      input: JSON.stringify({ tool_name: 'Bash', tool_input: { command: 'pkill node' } }),
+      encoding: 'utf8',
+      timeout: 10000,
+      env: { ...process.env, BULKHEAD_STATE_DIR: tmp, CLAUDE_PROJECT_DIR: tmp, BULKHEAD_DISABLE: '', BULKHEAD_NO_LOG: '1' },
+    })
+    const ms = Date.now() - t0
+    if (r.status === 2 && /kill-guard/.test(r.stderr)) return ok('hook run', `kill-guard blocked a test command in ${ms} ms`)
+    return fail('hook run', `kill-guard did not block a test command (exit ${r.status}${r.error ? `, ${r.error.message}` : ''})`)
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }) } catch {}
+  }
+}
+
+function checkGit() {
+  try {
+    const v = execFileSync('git', ['--version'], { encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    return ok('git', v.replace(/^git version /, ''))
+  } catch {
+    return warn('git', 'git is not on PATH; checkout-guard and the git rules in basics pass everything')
+  }
+}
+
+// One line per configured remote: reachable, bash, git and tar there, its folder writable.
+// Nothing runs when no remote is configured, so doctor stays fast.
+function checkRemotes(cfg, { env = process.env, probe = (r, ssh) => remote.probeSync(r, { ssh }) } = {}) {
+  const all = Object.values(cfg.values.remotes || {})
+  if (!all.length) return []
+  const tools = remote.localTools(env)
+  const out = []
+  const missing = ['ssh', 'tar', 'git'].filter(t => !tools[t])
+  if (missing.length) out.push(fail('remote tools', `${missing.join(', ')} not on PATH on this machine; bulkhead remote needs them`))
+  else out.push(ok('remote tools', `ssh ${shortPath(tools.ssh.join(' '))}, tar ${shortPath(tools.tar)}`))
+  if (!tools.ssh) return out
+  for (const r of all) {
+    const d = remote.describeProbe(r, probe(r, tools.ssh))
+    out.push({ id: `remote ${r.name}`, status: d.status, summary: d.line.slice(r.name.length + 2) })
+  }
+  return out
+}
+
+function runAll({ remotes = true } = {}) {
+  const cfg = config.load()
+  return [
+    checkNode(),
+    checkPlugin(),
+    checkStateDir(),
+    ...checkConfig(cfg),
+    ...checkGuards(cfg),
+    checkHookRun(),
+    checkProcesses(),
+    checkSessionsDir(),
+    checkMemory(),
+    checkSlots(),
+    checkLog(cfg),
+    checkGit(),
+    ...(remotes ? checkRemotes(cfg) : []),
+  ]
+}
+
+function render(checks, { color = false } = {}) {
+  const style = { OK: 'green', WARN: 'yellow', FAIL: 'red' }
+  const width = Math.max(...checks.map(c => c.id.length))
+  const lines = checks.map(c => `${paint(color, style[c.status], c.status.padEnd(4))}  ${c.id.padEnd(width)}  ${c.summary}`)
+  const count = s => checks.filter(c => c.status === s).length
+  lines.push('', `${count('OK')} OK, ${count('WARN')} WARN, ${count('FAIL')} FAIL`)
+  return lines.join('\n')
+}
+
+function main(args, { stdout = process.stdout, env = process.env, checks = () => runAll({ remotes: !args.includes('--no-remote') }) } = {}) {
+  if (rejectArgs('doctor', args, { flags: ['json', 'no-remote'], valued: [] }, process.stderr, null)) return
+  const list = checks()
+  if (args.includes('--json')) {
+    stdout.write(JSON.stringify({ ok: !list.some(c => c.status === 'FAIL'), checks: list }, null, 2) + '\n')
+  } else {
+    stdout.write(render(list, { color: useColor(stdout, env) }) + '\n')
+  }
+  if (list.some(c => c.status === 'FAIL')) process.exitCode = 1
+}
+
+module.exports = {
+  main, render, runAll, checkNode, checkPlugin, checkStateDir, checkConfig, checkGuards, checkProcesses, checkSessionsDir,
+  checkMemory, checkSlots, checkLog, checkHookRun, checkGit, checkRemotes,
+}

package/src/events.js

@@ -0,0 +1,108 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+
+// One JSON line per block in <state dir>/events.jsonl. Writing happens only on the block
+// path, costs one stat and one append, and never throws.
+const MAX_BYTES = 1024 * 1024
+const MAX_COMMAND = 200
+
+function eventsFile(dir) {
+  return path.join(dir, 'events.jsonl')
+}
+
+function loggingOff(env = process.env) {
+  return /^(?:1|true|yes)$/i.test(String(env.BULKHEAD_NO_LOG || '').trim())
+}
+
+function truncate(s, max = MAX_COMMAND) {
+  if (s == null) return null
+  const one = String(s).replace(/\s+/g, ' ').trim()
+  return one.length > max ? one.slice(0, max - 1) + '…' : one
+}
+
+// event: { guard, rule, session, project, command, ...extra }. Returns true when written.
+function record(dir, event, { env = process.env, now = Date.now(), maxBytes = MAX_BYTES } = {}) {
+  if (loggingOff(env)) return false
+  try {
+    const { guard, rule, session, project, command, ...extra } = event
+    const line = JSON.stringify({
+      time: new Date(now).toISOString(),
+      guard,
+      rule: rule || null,
+      session: session || null,
+      project: project || null,
+      command: truncate(command),
+      ...extra,
+    }) + '\n'
+    const file = eventsFile(dir)
+    let size = -1
+    try { size = fs.statSync(file).size } catch {}
+    if (size < 0) fs.mkdirSync(dir, { recursive: true })
+    else if (size + line.length > maxBytes) {
+      // two hooks may rotate at once; the loser's rename fails and it appends to the new file
+      try { fs.renameSync(file, file + '.1') } catch {}
+    }
+    fs.appendFileSync(file, line)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function parseLines(text) {
+  const out = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const e = JSON.parse(line)
+      if (e && e.time && e.guard) out.push(e)
+    } catch {}
+  }
+  return out
+}
+
+// All events from the rotated file and the current one, oldest first.
+function readEvents(dir) {
+  const file = eventsFile(dir)
+  const out = []
+  for (const f of [file + '.1', file]) {
+    try { for (const e of parseLines(fs.readFileSync(f, 'utf8'))) out.push(e) } catch {}
+  }
+  return out.sort((a, b) => (a.time < b.time ? -1 : a.time > b.time ? 1 : 0))
+}
+
+// The last `n` events without reading the whole file, for `bulkhead top`.
+function tailEvents(dir, n = 5, bytes = 64 * 1024) {
+  const file = eventsFile(dir)
+  let fd
+  try {
+    fd = fs.openSync(file, 'r')
+    const size = fs.fstatSync(fd).size
+    const start = Math.max(0, size - bytes)
+    const buf = Buffer.alloc(size - start)
+    fs.readSync(fd, buf, 0, buf.length, start)
+    const lines = buf.toString('utf8').split('\n')
+    if (start > 0) lines.shift()
+    const events = parseLines(lines.join('\n'))
+    if (events.length >= n || start > 0) return events.slice(-n)
+  } catch {
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd) } catch {}
+  }
+  return readEvents(dir).slice(-n)
+}
+
+function logSize(dir) {
+  let bytes = 0
+  let files = 0
+  for (const f of [eventsFile(dir), eventsFile(dir) + '.1']) {
+    try {
+      bytes += fs.statSync(f).size
+      files++
+    } catch {}
+  }
+  return { bytes, files }
+}
+
+module.exports = { record, readEvents, tailEvents, logSize, eventsFile, loggingOff, truncate, MAX_BYTES }

package/src/hook.js

@@ -0,0 +1,94 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+// Fixed, not CLAUDE_PLUGIN_DATA: the bulkhead-slot CLI runs from the Bash tool, which
+// does not receive that variable, and both sides must see the same slot files.
+function stateDir() {
+  return process.env.BULKHEAD_STATE_DIR || path.join(os.homedir(), '.claude', 'bulkhead')
+}
+
+// BULKHEAD_DISABLE first, then the config files. A broken config file never turns a guard off.
+function enabled(name) {
+  const off = (process.env.BULKHEAD_DISABLE || '').split(/[\s,]+/).filter(Boolean)
+  if (off.includes(name) || off.includes('all')) return false
+  try {
+    return require('./config').isEnabled(name)
+  } catch {
+    return true
+  }
+}
+
+// A value from the config files or its environment variable (see config.js).
+function setting(key, fallback) {
+  try {
+    const v = require('./config').get(key)
+    return v == null ? fallback : v
+  } catch {
+    return fallback
+  }
+}
+
+function envNumber(name, fallback) {
+  const n = Number(process.env[name])
+  return process.env[name] && Number.isFinite(n) ? n : fallback
+}
+
+function log(name, line) {
+  try {
+    const dir = stateDir()
+    fs.mkdirSync(dir, { recursive: true })
+    fs.appendFileSync(path.join(dir, 'guards.log'), `${new Date().toISOString()} ${name} ${line}\n`)
+  } catch {}
+}
+
+// Records a block in guards.log and events.jsonl and returns the hook result that stops the call.
+// One line for the agent and the person reading it: a block can be intentional, and the answer
+// to that is a question to the user, not a way around the guard.
+const ASK_USER = 'If the user wants this on purpose, ask them: they can allow it in .claude/bulkhead.json (see docs/configuration.md).'
+
+function blocked(name, rule, input, message, command = input && input.tool_input && input.tool_input.command) {
+  log(name, `blocked ${rule}: ${oneLine(command || '')}`)
+  recordEvent(name, rule, input, command)
+  return { block: message }
+}
+
+function recordEvent(name, rule, input = {}, command = null, extra = {}) {
+  if (setting('log.enabled', true) === false) return
+  require('./events').record(stateDir(), {
+    guard: name,
+    rule,
+    session: input.session_id || null,
+    project: process.env.CLAUDE_PROJECT_DIR || input.cwd || null,
+    command,
+    ...extra,
+  })
+}
+
+function oneLine(s, max = 300) {
+  return String(s).replace(/\s+/g, ' ').trim().slice(0, max)
+}
+
+// Reads the hook payload from stdin and hands it to `handler`. The handler returns
+// nothing to allow, { block: message } to stop the tool call (exit 2), or
+// { output: object } to print JSON, or a promise of either. Any error lets the call through.
+function runHook(name, handler) {
+  if (!enabled(name)) return
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', d => (raw += d))
+  process.stdin.on('end', () => {
+    Promise.resolve().then(() => handler(JSON.parse(raw || '{}'))).then(result => {
+      if (result && result.block) {
+        process.stderr.write(result.block.endsWith('\n') ? result.block : result.block + '\n')
+        process.exit(2)
+      }
+      if (result && result.output) process.stdout.write(JSON.stringify(result.output))
+      process.exit(0)
+    }, () => process.exit(0))
+  })
+}
+
+module.exports = {
+  ASK_USER, runHook, enabled, setting, envNumber, log, oneLine, stateDir, blocked, recordEvent }