claude-bulkhead 0.2.2 → 0.3.0

package/src/doctor-enforcement.js

@@ -0,0 +1,273 @@
+'use strict'
+// bulkhead doctor, "Enforcement": proves the guards would block, not only that files exist.
+// What Claude Code does with settings and hooks is taken from its docs:
+//   hooks   https://code.claude.com/docs/en/hooks   (exec form, timeouts, exit code 2, async, onFailure)
+//   settings https://code.claude.com/docs/en/settings-reference (disableAllHooks, allowManagedHooksOnly, enabledPlugins)
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const config = require('./config')
+const { claudeDir } = require('./sessions')
+const { shortPath } = require('./cli-util')
+
+const ROOT = path.resolve(__dirname, '..')
+const SECTION = 'Enforcement'
+const PLUGIN = 'bulkhead'
+const INSTALL = '/plugin install bulkhead@bulkhead'
+const DOCS = 'https://code.claude.com/docs/en'
+
+const mk = status => (id, summary) => ({ id, status, summary, section: SECTION })
+const ok = mk('OK')
+const warn = mk('WARN')
+const fail = mk('FAIL')
+
+// A harmless command each guard must block. Nothing is executed: the hook only reads the text.
+const CANARIES = {
+  'kill-guard.js': { guard: 'kill-guard', command: 'pkill node', stderr: /kill-guard/ },
+  'wait-guard.js': { guard: 'wait-guard', command: 'sleep 100000', extra: { timeout: 3600000 }, stderr: /wait-guard/ },
+  'disk-guard.js': { guard: 'disk-guard', command: 'du -sh /', stderr: /disk-guard/ },
+  'basics.js': { guard: 'basics', command: 'rm -rf /', stderr: /basics/, rule: 'basics.rmRoot' },
+}
+const HOOK_DEFAULT_TIMEOUT_S = 600
+const DOCTOR_MAX_TIMEOUT_S = 60
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+}
+
+function managedFile(platform, env) {
+  if (env.BULKHEAD_MANAGED_SETTINGS) return env.BULKHEAD_MANAGED_SETTINGS
+  if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode\\managed-settings.json'
+  if (platform === 'darwin') return '/Library/Application Support/ClaudeCode/managed-settings.json'
+  return '/etc/claude-code/managed-settings.json'
+}
+
+// Lowest to highest precedence: user, project, local, managed.
+function settingsFiles({ configDir, cwd, platform, env }) {
+  return [
+    { scope: 'user', file: path.join(configDir, 'settings.json') },
+    { scope: 'project', file: path.join(cwd, '.claude', 'settings.json') },
+    { scope: 'local', file: path.join(cwd, '.claude', 'settings.local.json') },
+    { scope: 'managed', file: managedFile(platform, env) },
+  ].map(s => ({ ...s, json: readJson(s.file) })).filter(s => s.json && typeof s.json === 'object')
+}
+
+// The last scope that sets a key wins.
+function effective(files, key) {
+  let found = null
+  for (const s of files) if (s.json[key] !== undefined) found = { scope: s.scope, file: s.file, value: s.json[key] }
+  return found
+}
+
+function enabledEntry(files) {
+  let found = null
+  for (const s of files) {
+    const e = s.json.enabledPlugins
+    if (!e || typeof e !== 'object') continue
+    for (const [id, v] of Object.entries(e)) if (id.split('@')[0] === PLUGIN) found = { id, value: v, scope: s.scope, file: s.file }
+  }
+  return found
+}
+
+function installs(configDir) {
+  const j = readJson(path.join(configDir, 'plugins', 'installed_plugins.json'))
+  const out = []
+  for (const [id, list] of Object.entries((j && j.plugins) || {})) {
+    if (id.split('@')[0] !== PLUGIN) continue
+    for (const e of Array.isArray(list) ? list : []) out.push({ id, scope: e.scope, installPath: e.installPath, version: e.version })
+  }
+  return out
+}
+
+function hasMarketplace(configDir) {
+  const j = readJson(path.join(configDir, 'plugins', 'known_marketplaces.json'))
+  return Object.entries(j || {}).some(([name, v]) => name === PLUGIN || /claude-bulkhead/.test(JSON.stringify(v)))
+}
+
+// Hooks written by hand into a settings file: not the plugin's own.
+function manualHooks(files) {
+  const out = []
+  for (const s of files) {
+    for (const groups of Object.values(s.json.hooks || {})) {
+      for (const g of Array.isArray(groups) ? groups : []) {
+        for (const h of g.hooks || []) {
+          if (/bulkhead|(kill|wait|port|checkout|disk|memory)-guard\.js|bash-guards\.js/.test([h.command, ...(h.args || [])].join(' '))) out.push(s)
+        }
+      }
+    }
+  }
+  return [...new Set(out)]
+}
+
+function checkInstall(ctx) {
+  const { files, configDir } = ctx
+  const list = installs(configDir)
+  const entry = enabledEntry(files)
+  const manual = manualHooks(files)
+  const out = []
+  const live = list.filter(i => i.installPath && fs.existsSync(path.join(i.installPath, 'hooks', 'hooks.json')))
+  if (!list.length && !(entry && entry.value === true)) {
+    if (manual.length) out.push(ok('install', `by hand: bulkhead hooks in ${manual.map(m => shortPath(m.file)).join(', ')}`))
+    else out.push(warn('install', `not installed in Claude Code; run ${hasMarketplace(configDir) ? '' : '/plugin marketplace add dooly6276/claude-bulkhead, then '}${INSTALL}`))
+    return { checks: out, installed: null }
+  }
+  if (entry && entry.value === false) {
+    out.push(fail('install', `${entry.id} is turned off in ${entry.scope} settings (${shortPath(entry.file)}); run /plugin enable ${entry.id}`))
+    return { checks: out, installed: live[0] || null }
+  }
+  if (!live.length) {
+    out.push(fail('install', `${list[0] ? `${shortPath(list[0].installPath || '?')} has no hooks/hooks.json` : `${entry.id} is enabled but not installed`}; reinstall with ${INSTALL}`))
+    return { checks: out, installed: null }
+  }
+  const i = live[0]
+  const state = entry ? `enabled in ${entry.scope} settings` : 'no enabledPlugins entry, so Claude Code uses the plugin default'
+  const text = `${i.id}${i.version ? ` ${i.version}` : ''} at ${shortPath(i.installPath)}, ${state}`
+  out.push(entry ? ok('install', text) : warn('install', `${text}; run /plugin enable ${i.id}`))
+  const roots = [...new Set(live.map(l => l.installPath))]
+  if (roots.length > 1) out.push(warn('duplicates', `${roots.length} installed copies (${live.map(l => l.scope || '?').join(', ')}); every guard may run once per copy. Keep one: /plugin uninstall for the extra scope`))
+  if (manual.length) out.push(warn('duplicates', `bulkhead hooks are in ${manual.map(m => shortPath(m.file)).join(', ')} and in the plugin, so each call runs the guards twice; delete the hooks from the settings file`))
+  return { checks: out, installed: i }
+}
+
+// Settings that make Claude Code skip hooks, as the settings reference documents them.
+function checkSettings(ctx) {
+  const { files, installed } = ctx
+  const out = []
+  const off = effective(files, 'disableAllHooks')
+  if (off && off.value === true) {
+    out.push(off.scope === 'managed'
+      ? fail('hooks off', `disableAllHooks is true in managed settings (${shortPath(off.file)}); no hook runs. Ask your administrator (${DOCS}/settings-reference#disableallhooks)`)
+      : fail('hooks off', `disableAllHooks is true in ${off.scope} settings (${shortPath(off.file)}): Claude Code turns off plugin hooks. Remove it or set it to false (${DOCS}/settings-reference#disableallhooks)`))
+  }
+  const managed = effective(files, 'allowManagedHooksOnly')
+  if (managed && managed.scope === 'managed' && managed.value === true) {
+    const forced = files.some(s => s.scope === 'managed' && s.json.enabledPlugins && Object.entries(s.json.enabledPlugins).some(([id, v]) => id.split('@')[0] === PLUGIN && v === true))
+    out.push(forced
+      ? ok('managed hooks', 'allowManagedHooksOnly is on, and managed settings force-enable the plugin')
+      : fail('managed hooks', `allowManagedHooksOnly is true in managed settings, so plugin hooks do not run unless managed enabledPlugins force-enables ${PLUGIN}@... (${DOCS}/settings-reference#what-runs-under-allowmanagedhooksonly)`))
+  }
+  const blocked = files.find(s => s.scope === 'managed' && s.json.enabledPlugins && Object.entries(s.json.enabledPlugins).some(([id, v]) => id.split('@')[0] === PLUGIN && v === false))
+  if (blocked) out.push(fail('managed plugin', `managed settings turn ${PLUGIN} off and block its installation (${DOCS}/settings-reference#enabledplugins)`))
+  if (!out.length && installed) out.push(ok('hooks on', 'no disableAllHooks or allowManagedHooksOnly in user, project, local or managed settings'))
+  return out
+}
+
+function substitute(text, vars) {
+  return String(text).replace(/\$\{(CLAUDE_PLUGIN_ROOT|CLAUDE_PROJECT_DIR|CLAUDE_PLUGIN_DATA)\}/g, (_, k) => vars[k])
+}
+
+function hookDeclarations(root) {
+  const file = path.join(root, 'hooks', 'hooks.json')
+  let json
+  try { json = JSON.parse(fs.readFileSync(file, 'utf8')) } catch (e) { return { file, error: e.code === 'ENOENT' ? 'is missing' : `cannot be read (${e.message})` } }
+  const list = []
+  for (const g of (json.hooks && json.hooks.PreToolUse) || []) for (const h of g.hooks || []) list.push({ matcher: g.matcher || '', ...h })
+  return { file, list }
+}
+
+function findOnPath(name, env, platform) {
+  const sep = platform === 'win32' ? ';' : ':'
+  const exts = platform === 'win32' ? ['', ...String(env.PATHEXT || '.EXE;.CMD').split(';')] : ['']
+  for (const dir of String(env.PATH || env.Path || '').split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const p = path.join(dir, name + ext)
+      try { if (fs.statSync(p).isFile()) return p } catch {}
+    }
+  }
+  return null
+}
+
+// Starts the hook the way Claude Code does: exec form (args present) spawns command directly on PATH,
+// shell form goes through bash, or PowerShell when the hook asks for it. Same placeholders, same timeout.
+function runHook(h, vars, { env, platform, spawn, input, timeoutS }) {
+  const hookEnv = { ...env, CLAUDE_PLUGIN_ROOT: vars.CLAUDE_PLUGIN_ROOT, CLAUDE_PROJECT_DIR: vars.CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_DATA: vars.CLAUDE_PLUGIN_DATA }
+  const opts = { input, encoding: 'utf8', timeout: timeoutS * 1000, env: hookEnv, windowsHide: true, killSignal: 'SIGKILL' }
+  if (Array.isArray(h.args)) return spawn(substitute(h.command, vars), h.args.map(a => substitute(a, vars)), opts)
+  const cmd = substitute(h.command, vars)
+  if (h.shell === 'powershell') return spawn('powershell', ['-NoProfile', '-Command', cmd], opts)
+  const bash = platform === 'win32' ? findOnPath('bash', env, platform) : '/bin/bash'
+  return bash ? spawn(bash, ['-c', cmd], opts) : spawn('powershell', ['-NoProfile', '-Command', cmd], opts)
+}
+
+// The canaries a hook entry must block: one for a single guard's script, all of them for
+// bash-guards.js, which runs every Bash guard in one process.
+function canariesOf(h) {
+  const script = [h.command, ...(h.args || [])].map(String).find(a => /\.js$/.test(a))
+  if (!script) return []
+  if (path.basename(script) === 'bash-guards.js') return Object.values(CANARIES)
+  return CANARIES[path.basename(script)] ? [CANARIES[path.basename(script)]] : []
+}
+
+function checkHooks(ctx) {
+  const { root, installed, env, platform, spawn, cfg } = ctx
+  const out = []
+  const where = installed ? 'installed copy' : 'this copy (not installed)'
+  const decl = hookDeclarations(root)
+  if (decl.error) return [fail('hooks.json', `${shortPath(decl.file)} ${decl.error}; reinstall with ${INSTALL}`)]
+  const asyncHooks = decl.list.filter(h => h.async === true || h.asyncRewake === true)
+  if (asyncHooks.length) out.push(fail('hooks.json', `${asyncHooks.length} PreToolUse hook${asyncHooks.length === 1 ? ' is' : 's are'} async, and an async hook cannot block (${DOCS}/hooks#run-hooks-in-the-background)`))
+  else out.push(ok('hooks.json', `${where}: ${decl.list.length} PreToolUse hooks, all synchronous`))
+
+  // node must resolve on the PATH the hook gets
+  const first = decl.list.find(h => Array.isArray(h.args))
+  if (first) {
+    const resolved = findOnPath(first.command, env, platform)
+    if (!resolved) out.push(fail('hook node', `"${first.command}" is not on the PATH hooks get, so every hook fails to start and Claude Code lets the call through; put Node 18+ on PATH for the shell that starts Claude Code`))
+    else {
+      const v = spawn(resolved, ['-p', 'process.versions.node'], { encoding: 'utf8', timeout: 10000, windowsHide: true })
+      const ver = String(v.stdout || '').trim()
+      const major = Number(ver.split('.')[0])
+      out.push(major >= 18 ? ok('hook node', `${shortPath(resolved)} v${ver}`) : fail('hook node', `${shortPath(resolved)} ${ver ? `is v${ver}` : 'does not run'}; hooks need Node 18 or later first on PATH`))
+    }
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bulkhead-doctor-'))
+  const vars = { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PROJECT_DIR: tmp, CLAUDE_PLUGIN_DATA: path.join(tmp, 'data') }
+  try {
+    for (const h of decl.list) for (const canary of canariesOf(h)) {
+      const rule = canary.rule
+      if (cfg && (cfg.values[`${config.GUARDS[canary.guard]}.enabled`] === false || (rule && cfg.values[rule] === false))) {
+        out.push(ok(`hook ${canary.guard}`, 'off in your config, not run'))
+        continue
+      }
+      if (h.matcher && !new RegExp(`^(?:${h.matcher})$`).test('Bash')) {
+        out.push(fail(`hook ${canary.guard}`, `its matcher "${h.matcher}" does not match the Bash tool`))
+        continue
+      }
+      const timeoutS = Math.min(h.timeout || HOOK_DEFAULT_TIMEOUT_S, DOCTOR_MAX_TIMEOUT_S)
+      const input = JSON.stringify({ hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: canary.command, ...canary.extra }, session_id: 'bulkhead-doctor', cwd: tmp, permission_mode: 'default' })
+      const t0 = Date.now()
+      const r = runHook(h, vars, {
+        env: { ...env, BULKHEAD_STATE_DIR: tmp, BULKHEAD_DISABLE: '', BULKHEAD_NO_LOG: '1' }, platform, spawn, input, timeoutS,
+      })
+      const ms = Date.now() - t0
+      const id = `hook ${canary.guard}`
+      if (r.error && r.error.code === 'ENOENT') out.push(fail(id, `could not start "${h.command}" (not found); no call is blocked. Put Node 18+ on PATH`))
+      else if (r.error && (r.error.code === 'ETIMEDOUT' || r.signal)) out.push(fail(id, `timed out after ${timeoutS}s; Claude Code lets the call through when a PreToolUse hook times out (${DOCS}/hooks#timeouts). Run bulkhead doctor again, then report it`))
+      else if (r.status === 2 && canary.stderr.test(r.stderr || '')) out.push(ok(id, `blocked "${canary.command}" (exit 2, message shown to Claude) in ${ms} ms`))
+      else if (r.status === 2) out.push(fail(id, `exit 2 but the message is missing, Claude would not see why: ${String(r.stderr || '').trim().slice(0, 80) || '(empty)'}`))
+      else out.push(fail(id, `did not block "${canary.command}" (exit ${r.status}${r.stderr ? `: ${String(r.stderr).trim().split('\n')[0].slice(0, 80)}` : ''}); reinstall with ${INSTALL}`))
+    }
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }) } catch {}
+  }
+  return out
+}
+
+function checkEnforcement({
+  root = ROOT, env = process.env, cwd = process.cwd(), platform = process.platform, spawn = spawnSync, cfg = null,
+  configDir = env.CLAUDE_CONFIG_DIR || claudeDir(),
+} = {}) {
+  const files = settingsFiles({ configDir, cwd, platform, env })
+  const ctx = { root, env, platform, spawn, cfg, files, configDir, cwd }
+  let inst
+  try { inst = checkInstall(ctx) } catch (e) { return [fail('install', `could not read the Claude Code install: ${e.message}`)] }
+  // the hooks.json Claude Code runs is the installed copy's; without an install, test this copy
+  const runRoot = inst.installed && inst.installed.installPath ? inst.installed.installPath : root
+  const out = [...inst.checks, ...checkSettings({ files, installed: inst.installed })]
+  out.push(...checkHooks({ ...ctx, root: runRoot, installed: inst.installed && inst.installed.installPath ? inst.installed : null }))
+  return out
+}
+
+module.exports = { checkEnforcement, SECTION, CANARIES, findOnPath, managedFile }

package/src/doctor.js

@@ -12,6 +12,7 @@ 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 { checkEnforcement } = require('./doctor-enforcement')
 
 const ROOT = path.resolve(__dirname, '..')
 const SMALL_MACHINE_GB = 24
@@ -31,7 +32,7 @@ function checkPlugin(root = ROOT) {
   try {
     hooks = JSON.parse(fs.readFileSync(file, 'utf8')).hooks
   } catch (e) {
-    return fail('plugin', `${shortPath(file)} cannot be read: ${e.message}`)
+    return fail('package', `${shortPath(file)} cannot be read: ${e.message}`)
   }
   const missing = []
   const counts = []
@@ -48,8 +49,8 @@ function checkPlugin(root = ROOT) {
     }
     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(', ')}`)
+  if (missing.length) return fail('package', `hooks.json names scripts that are missing: ${missing.join(', ')}`)
+  return ok('package', `this copy ${shortPath(root)}, hooks: ${counts.join(', ')}`)
 }
 
 function checkStateDir(dir = stateDir()) {
@@ -69,12 +70,13 @@ function checkConfig(cfg) {
   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))))
+  out.push(ok('preset', `${cfg.preset} (${why(cfg.presetFrom)})`))
   return out
 }
 
 function why(source) {
   if (source === 'default') return 'default'
-  if (source.startsWith('env ')) return source
+  if (source.startsWith('env ') || source.startsWith('preset ')) return source
   return shortPath(source)
 }
 
@@ -125,14 +127,16 @@ function checkProcesses({ read = () => readProcesses(), files = () => readSessio
   }
   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`
+  const known = files()
+  const sessions = findSessions(snap, known)
+  const withFile = sessions.filter(s => known.has(s.pid)).length
+  const text = `${snap.procs.length} processes, ${snap.ports.length} listening ports, ${sessions.length} Claude session${sessions.length === 1 ? '' : 's'} (${withFile} with a session file) 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)`)
+    ? ok('sessions', `${shortPath(dir)} (${readSessionFiles(dir).size} session files; a running session without one is still found from the process list, but checkout-guard cannot tell which folder it works in)`)
     : warn('sessions', `${shortPath(dir)} does not exist; checkout-guard cannot see other sessions and project names show as ?`)
 }
 
@@ -218,13 +222,13 @@ function runAll({ remotes = true } = {}) {
     checkStateDir(),
     ...checkConfig(cfg),
     ...checkGuards(cfg),
-    checkHookRun(),
     checkProcesses(),
     checkSessionsDir(),
     checkMemory(),
     checkSlots(),
     checkLog(cfg),
     checkGit(),
+    ...checkEnforcement({ cfg }),
     ...(remotes ? checkRemotes(cfg) : []),
   ]
 }
@@ -232,7 +236,13 @@ function runAll({ remotes = true } = {}) {
 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 lines = []
+  let section = null
+  for (const c of checks) {
+    if (c.section && c.section !== section) lines.push('', paint(color, 'bold', c.section))
+    section = c.section || null
+    lines.push(`${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')

package/src/edit-guard.js

@@ -0,0 +1,196 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+const { runHook, blocked, setting, stateDir, ASK_USER } = require('./hook')
+const { readSessionFiles } = require('./sessions')
+const { realPath, pathKey } = require('./paths')
+
+// Advisory overlap detection without a server. After every edit, PostToolUse appends
+// { session, file, time } to a small file per repository in the state directory. Before an edit,
+// PreToolUse reads that file and, when another session that is still running edited the same
+// file recently (in this tree or in another worktree of the same repository), tells the agent.
+// Everything here is plain file reads: no process scan, no git, no network.
+
+const MAX_ENTRIES = 300
+const KEEP_MS = 2 * 60 * 60 * 1000
+const MODES = ['warn', 'ask', 'block']
+
+// The .git folder or file at or above `file`, read without running git. A linked worktree has a
+// .git file that points at <common>/worktrees/<name>, whose commondir file names <common>.
+function repoOf(file, read = fs) {
+  let dir = path.dirname(file)
+  for (let i = 0; i < 40; i++) {
+    const dotGit = path.join(dir, '.git')
+    let st = null
+    try { st = read.statSync(dotGit) } catch {}
+    if (st && st.isDirectory()) return { top: dir, gitdir: dotGit, common: dotGit }
+    if (st && st.isFile()) {
+      try {
+        const m = /^gitdir:\s*(.+)$/m.exec(read.readFileSync(dotGit, 'utf8'))
+        if (!m) return null
+        const gitdir = path.resolve(dir, m[1].trim())
+        let common = gitdir
+        try { common = path.resolve(gitdir, read.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim()) } catch {}
+        return { top: dir, gitdir, common }
+      } catch { return null }
+    }
+    const up = path.dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+  return null
+}
+
+function branchOf(top, read = fs) {
+  const repo = repoOf(path.join(top, 'x'), read)
+  if (!repo) return null
+  try {
+    const head = read.readFileSync(path.join(repo.gitdir, 'HEAD'), 'utf8').trim()
+    const m = /^ref:\s*refs\/heads\/(.+)$/.exec(head)
+    return m ? m[1] : head.slice(0, 8)
+  } catch { return null }
+}
+
+function filePathOf(input) {
+  const t = (input && input.tool_input) || {}
+  const p = t.file_path || t.notebook_path
+  return typeof p === 'string' && p ? p : null
+}
+
+// Where the file lives: the state file for its repository, and its name inside that repository.
+function locate(file, dir, platform = process.platform) {
+  const real = realPath(file)
+  const repo = repoOf(real)
+  if (!repo) return { real, key: pathKey(real, platform), top: null, stateFile: path.join(dir, 'edits', 'nogit.json') }
+  const top = realPath(repo.top)
+  const rel = pathKey(real, platform).slice(pathKey(top, platform).length + 1)
+  const id = crypto.createHash('sha1').update(pathKey(repo.common, platform)).digest('hex').slice(0, 16)
+  return { real, key: rel, top, stateFile: path.join(dir, 'edits', `${id}.json`) }
+}
+
+function readState(file) {
+  try {
+    const s = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (s && Array.isArray(s.entries)) {
+      return {
+        entries: s.entries.filter(e => e && typeof e.t === 'number' && e.s && e.k),
+        seen: s.seen && typeof s.seen === 'object' && !Array.isArray(s.seen) ? s.seen : {},
+      }
+    }
+  } catch {}
+  return { entries: [], seen: {} }
+}
+
+// Temp file and rename, so a reader never sees half a file. Two sessions writing at once can
+// lose one entry; this is advisory, so that is accepted.
+function writeState(file, state) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(state))
+  fs.renameSync(tmp, file)
+}
+
+function prune(state, now, keepMs) {
+  const entries = state.entries.filter(e => now - e.t <= keepMs).slice(-MAX_ENTRIES)
+  const seen = Object.entries(state.seen).filter(([, t]) => typeof t === 'number' && now - t <= keepMs).slice(-MAX_ENTRIES)
+  return { entries, seen: Object.fromEntries(seen) }
+}
+
+// PostToolUse: remember that this session edited the file.
+function record(input, { dir = stateDir(), now = Date.now(), platform = process.platform, keepMs = KEEP_MS } = {}) {
+  const file = filePathOf(input)
+  if (!file || !input.session_id) return false
+  const loc = locate(file, dir, platform)
+  const state = readState(loc.stateFile)
+  state.entries = state.entries.filter(e => !(e.s === input.session_id && e.k === loc.key))
+  state.entries.push({ s: input.session_id, k: loc.key, top: loc.top, t: now })
+  writeState(loc.stateFile, prune(state, now, keepMs))
+  return true
+}
+
+const short = (p, home = os.homedir()) => (p && (p === home || p.startsWith(home + path.sep)) ? '~' + p.slice(home.length) : p)
+
+function ago(ms) {
+  const min = Math.floor(ms / 60000)
+  return min < 1 ? 'less than a minute ago' : `${min} min ago`
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e.code === 'EPERM'
+  }
+}
+
+// PreToolUse: { message, mode, rule } when another live session edited this file lately, else null.
+// The session files are read only after a recent edit by someone else is found, so the usual
+// case costs one failed file read.
+function check(input, {
+  dir = stateDir(), now = Date.now(), platform = process.platform, windowMs = 30 * 60 * 1000, mode = 'warn',
+  sessions = () => readSessionFiles(), isAlive = alive,
+} = {}) {
+  const file = filePathOf(input)
+  const me = input && input.session_id
+  if (!file || !me) return null
+  const loc = locate(file, dir, platform)
+  const state = readState(loc.stateFile)
+  const recent = state.entries
+    .filter(e => e.s !== me && e.k === loc.key && now - e.t <= windowMs && e.t <= now + 60000)
+    .sort((a, b) => b.t - a.t)
+  if (!recent.length) return null
+  const files = sessions()
+  for (const e of recent) {
+    const live = [...files].find(([pid, f]) => f.sessionId === e.s && isAlive(pid))
+    if (!live) continue
+    const seenKey = `${me}|${e.s}|${e.k}`
+    // told once per edit of theirs; block mode keeps stopping until they stop editing
+    if (mode !== 'block' && state.seen[seenKey] >= e.t) continue
+    const [pid, f] = live
+    const sameTree = loc.top && e.top && pathKey(e.top, platform) === pathKey(loc.top, platform)
+    const branch = e.top ? branchOf(e.top) : null
+    const where = [short(sameTree ? f.cwd || e.top : e.top || f.cwd), branch && `branch ${branch}`].filter(Boolean).join(', ')
+    const message = sameTree || !e.top
+      ? `Note: session ${pid} (${where}) edited this file ${ago(now - e.t)}; re-read it before assuming its contents, and don't revert their change.`
+      : `Note: session ${pid} edited the same file in another worktree (${where}) ${ago(now - e.t)}; the two versions will conflict on merge, so look at its change before overwriting this one.`
+    if (mode !== 'block') {
+      try { writeState(loc.stateFile, prune({ entries: state.entries, seen: { ...state.seen, [seenKey]: e.t } }, now, KEEP_MS)) } catch {}
+    }
+    return { message, mode, rule: sameTree || !e.top ? 'same-tree' : 'other-worktree' }
+  }
+  return null
+}
+
+// The JSON Claude Code reads. additionalContext alone informs the model without approving the
+// call; "ask" puts the same text in front of the user.
+function output(hit) {
+  const hookSpecificOutput = { hookEventName: 'PreToolUse', additionalContext: hit.message }
+  if (hit.mode === 'ask') {
+    hookSpecificOutput.permissionDecision = 'ask'
+    hookSpecificOutput.permissionDecisionReason = hit.message
+  }
+  return { hookSpecificOutput }
+}
+
+if (require.main === module) {
+  runHook('edit-guard', input => {
+    if (input.hook_event_name === 'PostToolUse') {
+      record(input)
+      return
+    }
+    const configured = setting('editGuard.mode', 'warn')
+    const mode = MODES.includes(configured) ? configured : 'warn'
+    const minutes = Number(setting('editGuard.windowMinutes', 30))
+    const hit = check(input, { mode, windowMs: (Number.isFinite(minutes) ? minutes : 30) * 60000 })
+    if (!hit) return
+    if (hit.mode === 'block') {
+      return blocked('edit-guard', hit.rule, input, `[bulkhead] edit-guard: ${hit.message}\n${ASK_USER}`, filePathOf(input))
+    }
+    return { output: output(hit) }
+  })
+}
+
+module.exports = { check, record, output, repoOf, branchOf, locate }

package/src/events.js

@@ -22,6 +22,34 @@ function truncate(s, max = MAX_COMMAND) {
 }
 
 // event: { guard, rule, session, project, command, ...extra }. Returns true when written.
+// Moves file to file.1 once it is over `limit` bytes. Two hooks may try at once: a lock folder
+// lets one rotate, and it checks the size again under the lock, so a hook that saw the old big
+// file never moves the fresh small one over the history in file.1. A lock left by a crashed hook
+// is cleared after 10 seconds. Never throws.
+function rotate(file, limit, now = Date.now()) {
+  const lock = file + '.lock'
+  try {
+    try {
+      fs.mkdirSync(lock)
+    } catch {
+      if (now - fs.statSync(lock).mtimeMs < 10000) return false
+      fs.rmdirSync(lock)
+      fs.mkdirSync(lock)
+    }
+  } catch {
+    return false
+  }
+  try {
+    if (fs.statSync(file).size <= limit) return false
+    fs.renameSync(file, file + '.1')
+    return true
+  } catch {
+    return false
+  } finally {
+    try { fs.rmdirSync(lock) } catch {}
+  }
+}
+
 function record(dir, event, { env = process.env, now = Date.now(), maxBytes = MAX_BYTES } = {}) {
   if (loggingOff(env)) return false
   try {
@@ -39,10 +67,7 @@ function record(dir, event, { env = process.env, now = Date.now(), maxBytes = MA
     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 {}
-    }
+    else if (size + line.length > maxBytes) rotate(file, maxBytes - line.length)
     fs.appendFileSync(file, line)
     return true
   } catch {
@@ -105,4 +130,4 @@ function logSize(dir) {
   return { bytes, files }
 }
 
-module.exports = { record, readEvents, tailEvents, logSize, eventsFile, loggingOff, truncate, MAX_BYTES }
+module.exports = { rotate, record, readEvents, tailEvents, logSize, eventsFile, loggingOff, truncate, MAX_BYTES }