claude-bulkhead 0.0.0-stage → 0.2.2

package/src/basics.js

@@ -0,0 +1,236 @@
+'use strict'
+const os = require('os')
+const path = require('path')
+const { execFileSync } = require('child_process')
+const { runHook, enabled, setting, blocked, oneLine, ASK_USER } = require('./hook')
+const shell = require('./shell')
+const { realPath } = require('./paths')
+
+// Narrow rules for mistakes that cannot be undone. Each can be turned off on its own:
+// rm-root, force-push-main, discard-changes, agent-author.
+
+// ~, $HOME and %USERPROFILE% become the home directory; /c/... becomes C:/... on Windows.
+// Returns null for anything with a variable we cannot expand.
+function expand(arg, home, platform) {
+  let a = arg
+    .replace(/^~(?=[\\/]|$)/, home)
+    .replace(/^(?:\$HOME|\$\{HOME\}|\$env:USERPROFILE|\$env:HOME|%USERPROFILE%|\$USERPROFILE)(?=[\\/]|$)/i, home)
+  if (/[$%]/.test(a)) return null
+  if (platform === 'win32') a = a.replace(/^\/([a-z])(?=\/|$)/i, '$1:')
+  return a
+}
+
+const pathFor = platform => (platform === 'win32' ? path.win32 : path.posix)
+
+const norm = (p, platform) => {
+  const n = pathFor(platform).resolve(p).replace(/\\/g, '/').replace(/\/+$/, '') || '/'
+  return platform === 'win32' ? n.toLowerCase() : n
+}
+// git prints the repository's real path; the cwd and home may be spelled through a link or a
+// Windows short name (C:\Users\RUNNER~1). Only those two folders are resolved, never a target:
+// a target can be on an automounted or network path, and a hook must not wait on it. A hook
+// process asks for the same two folders again and again, so the answers are kept.
+const realCache = new Map()
+function realOnce(p) {
+  if (!realCache.has(p)) {
+    if (realCache.size > 64) realCache.clear()
+    realCache.set(p, realPath(p))
+  }
+  return realCache.get(p)
+}
+const isAncestorOrSame = (a, b) => b === a || b.startsWith(a.endsWith('/') ? a : a + '/')
+
+function rmTargets(t) {
+  const cmd = path.basename(t[0] || '').replace(/\.exe$/i, '').toLowerCase()
+  const args = t.slice(1)
+  if (cmd === 'rm') {
+    // options end at `--`; everything after it is a path, even one that starts with a dash
+    const dash = args.indexOf('--')
+    const opts = (dash < 0 ? args : args.slice(0, dash)).filter(a => a.startsWith('-'))
+    const operands = dash < 0 ? args.filter(a => !a.startsWith('-')) : [...args.slice(0, dash).filter(a => !a.startsWith('-')), ...args.slice(dash + 1)]
+    const recursive = opts.some(a => /^-[a-zA-Z]*[rR]/.test(a) || a === '--recursive')
+    const force = opts.some(a => /^-[a-zA-Z]*f/.test(a) || a === '--force')
+    return recursive && force ? operands : []
+  }
+  if (/^(?:remove-item|ri|rmdir|rd|del|erase)$/.test(cmd) && args.some(a => /^-r(?:ecurse)?$/i.test(a)) && args.some(a => /^-fo(?:rce)?$/i.test(a))) {
+    return args.filter(a => !a.startsWith('-'))
+  }
+  if (/^(?:rd|rmdir)$/.test(cmd) && args.some(a => /^\/s$/i.test(a))) return args.filter(a => !/^\/[sq]$/i.test(a))
+  return []
+}
+
+// Folders directly in the home directory that are only caches and can always be rebuilt.
+const HOME_CACHES = /^\.?(?:cache|caches|tmp|temp|npm|pnpm-store|yarn|bun|gradle|m2|nuget|cargo|rustup|deno|expo|Trash|node-gyp|pyenv|bundle|cocoapods)$/i
+
+// The dangerous targets: a filesystem or drive root, a top-level folder such as /usr or /srv,
+// the home directory or anything above it, a folder directly in it (~/Documents, ~/backups;
+// caches excepted), and any directory above the repository the command runs in.
+function dangerousTarget(arg, { cwd, home, platform, repoRoot }) {
+  const expanded = expand(arg, home, platform)
+  if (expanded === null) return null
+  const dir = expanded.replace(/[\\/]\*$/, '') || '/'
+  const rel = expanded === '*' ? '.' : dir
+  // as written, and on this machine also from the real cwd and home: rm resolves .. from the
+  // folder the cwd really is, not from the link it was entered through
+  const views = [{ cwd, home }]
+  if (platform === process.platform) views.push({ cwd: realOnce(cwd), home: realOnce(home) })
+  for (const v of views) {
+    const abs = norm(pathFor(platform).resolve(v.cwd, rel), platform)
+    if (/^(?:\/|[a-z]:\/?)$/i.test(abs) || /^[a-z]:$/i.test(abs)) return 'a filesystem root'
+    const homeKey = norm(v.home, platform)
+    if (isAncestorOrSame(abs, homeKey)) return 'your home directory or a folder above it'
+    const parent = pathFor('linux').dirname(abs)
+    if (parent === homeKey && !HOME_CACHES.test(pathFor('linux').basename(abs))) return 'a folder directly in your home directory'
+    if ((parent === '/' || /^[a-z]:\/?$/i.test(parent)) && !isAncestorOrSame(abs, norm(v.cwd, platform))) return 'a top-level folder of the drive'
+    // a folder inside the current directory cannot be above the repository
+    if (abs !== norm(v.cwd, platform) && isAncestorOrSame(norm(v.cwd, platform), abs)) continue
+    const root = repoRoot()
+    if (root && abs !== norm(root, platform) && isAncestorOrSame(abs, norm(root, platform))) return 'a folder above this repository'
+  }
+  return null
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+}
+
+function gitCwd(t, cwd) {
+  const i = t.indexOf('-C')
+  return i > 0 && t[i + 1] ? path.resolve(cwd, t[i + 1]) : cwd
+}
+
+function gitSub(t) {
+  const rest = []
+  for (let i = 1; i < t.length; i++) {
+    if (t[i] === '-C' || t[i] === '-c') i++
+    else rest.push(t[i])
+  }
+  return rest
+}
+
+function forcePushToMain(rest, branch, protectedBranches = ['main', 'master']) {
+  if (rest[0] !== 'push') return false
+  const args = rest.slice(1)
+  // --force-with-lease and --force-if-includes are the safe forms and do not count
+  const force = args.some(a => a === '--force' || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(a) || a.startsWith('+'))
+  if (!force) return false
+  const refs = args.filter(a => !a.startsWith('-')).slice(1).map(r => r.replace(/^\+/, '').split(':').pop())
+  const targets = refs.length ? refs.map(r => (r === 'HEAD' ? branch() : r)) : [branch()]
+  return targets.some(r => protectedBranches.includes(String(r || '').replace(/^refs\/heads\//, '')))
+}
+
+// An identity that is the agent, not the person: Claude <noreply@anthropic.com> and the like.
+const AGENT_ID = /\bclaude\b|anthropic/i
+
+// The --author value of git commit, the value git config sets for user.name or user.email, or a
+// -c user.name=... before the subcommand.
+function agentAuthor(t, rest) {
+  for (let i = 1; i < t.length; i++) {
+    if (t[i] === '-c' && /^user\.(?:name|email)=/i.test(t[i + 1] || '') && AGENT_ID.test(t[i + 1].split('=').slice(1).join('='))) return t[i + 1]
+  }
+  if (rest[0] === 'commit' || rest[0] === 'merge' || rest[0] === 'cherry-pick' || rest[0] === 'revert') {
+    for (let i = 1; i < rest.length; i++) {
+      const a = rest[i]
+      const v = a.startsWith('--author=') ? a.slice(9) : a === '--author' ? rest[i + 1] : null
+      if (v && AGENT_ID.test(v)) return `--author ${v}`
+    }
+  }
+  if (rest[0] === 'config') {
+    const args = rest.slice(1).filter(a => !/^--(?:global|local|system|worktree|replace-all|add)$/.test(a))
+    if (/^user\.(?:name|email)$/i.test(args[0] || '') && args[1] && AGENT_ID.test(args[1])) return `${args[0]} ${args[1]}`
+  }
+  return null
+}
+
+// GIT_AUTHOR_NAME=Claude git commit, export GIT_COMMITTER_EMAIL=noreply@anthropic.com, $env:GIT_AUTHOR_NAME = "Claude"
+const AGENT_ENV = /\bGIT_(?:AUTHOR|COMMITTER)_(?:NAME|EMAIL)\s*=\s*["']?([^"'\s;&|]*)/gi
+function agentEnv(text) {
+  for (const m of text.matchAll(AGENT_ENV)) if (AGENT_ID.test(m[1])) return m[0]
+  return null
+}
+
+function agentMessage(what) {
+  return `[bulkhead] basics: \`${oneLine(what, 120)}\` makes the agent the author of the commit.\n` +
+    'Commits authored as Claude or Anthropic do not count as the user\'s work on GitHub (contribution graph, achievements), and later blame points at a bot.\n' +
+    'Commit with the git identity already configured: leave user.name and user.email alone and drop --author. A Co-Authored-By line in the message is fine.'
+}
+
+function check(cmd, {
+  cwd = process.cwd(), home = os.homedir(), platform = process.platform, run = git,
+  protectedBranches = setting('basics.protectedBranches', ['main', 'master']), mode = 'sh',
+} = {}) {
+  // each rule's switch and the repository root are read once, however many commands the line has
+  const once = fn => { let v; let done = false; return () => (done ? v : ((done = true), (v = fn()))) }
+  const rmRoot = once(() => enabled('rm-root'))
+  const forcePush = once(() => enabled('force-push-main'))
+  const discard = once(() => enabled('discard-changes'))
+  const author = once(() => enabled('agent-author'))
+  const prepared = shell.prepare(String(cmd || ''), mode)
+  const cmds = shell.commands(prepared, mode).filter(x => !x.remote)
+  if (author() && /GIT_(?:AUTHOR|COMMITTER)_/i.test(prepared)) {
+    // only the shell's own words: a heredoc body handed to python or node is code, not a variable
+    const runsGit = cmds.some(c => shell.bin(c.argv[0]) === 'git')
+    for (const c of cmds) {
+      const own = c.depth === 0 ? prepared.slice(c.s, c.e) : c.argv.join(' ')
+      const env = agentEnv(own)
+      if (env && (runsGit || /^(?:export|set|setx|\$env:)/i.test(own.trim()))) return agentMessage(env)
+    }
+  }
+  const repoRoot = once(() => { try { return run(['rev-parse', '--show-toplevel'], cwd) } catch { return null } })
+  for (const c of cmds) {
+    const t = c.argv
+    if (!t.length) continue
+    const seg = t.join(' ')
+    const targets = rmTargets(t)
+    if (targets.length && rmRoot()) {
+      for (const target of targets) {
+        const what = dangerousTarget(target, { cwd, home, platform, repoRoot })
+        if (what) {
+          return `[bulkhead] basics: \`${oneLine(seg, 120)}\` deletes ${what} (${target}).\n` +
+            'Name the folder you mean inside the project instead, for example rm -rf ./dist.'
+        }
+      }
+    }
+    if (path.basename(t[0]).replace(/\.exe$/i, '') !== 'git') continue
+    const dir = gitCwd(t, cwd)
+    const rest = gitSub(t)
+    const who = author() && agentAuthor(t, rest)
+    if (who) return agentMessage(who)
+    if (rest[0] === 'push' && forcePush() && forcePushToMain(rest, () => { try { return run(['rev-parse', '--abbrev-ref', 'HEAD'], dir) } catch { return '' } }, protectedBranches)) {
+      return `[bulkhead] basics: force-pushing to ${protectedBranches.join(' or ')} rewrites history other people and sessions have pulled.\n` +
+        'Push to a branch, or use --force-with-lease if you are sure.'
+    }
+    const reset = rest[0] === 'reset' && rest.includes('--hard')
+    const clean = rest[0] === 'clean' && rest.some(a => /^-[a-z]*f/.test(a) || a === '--force') && rest.some(a => /^-[a-z]*[dx]/.test(a))
+    if ((reset || clean) && discard()) {
+      let status
+      try { status = run(['status', '--porcelain'], dir) } catch { continue }
+      const lines = status.split('\n').filter(Boolean)
+      const lost = reset ? lines.filter(l => !l.startsWith('??')) : lines.filter(l => l.startsWith('??'))
+      if (lost.length) {
+        return `[bulkhead] basics: \`${oneLine(seg, 120)}\` would throw away ${lost.length} ${reset ? 'uncommitted change' : 'untracked file'}${lost.length === 1 ? '' : 's'}` +
+          ` (${lost.slice(0, 3).map(l => l.slice(3)).join(', ')}${lost.length > 3 ? ', ...' : ''}).\n` +
+          'Commit them or run `git stash push -u` first, so they can be brought back.'
+      }
+    }
+  }
+  return null
+}
+
+if (require.main === module) {
+  runHook('basics', input => {
+    const cmd = input.tool_input && input.tool_input.command
+    const why = typeof cmd === 'string' && cmd && check(cmd, { cwd: input.cwd || process.cwd(), mode: shell.modeFor(input) })
+    if (!why) return
+    return blocked('basics', ruleOf(why), input, `${why}\n${ASK_USER}`)
+  })
+}
+
+function ruleOf(message) {
+  if (/makes the agent the author/.test(message)) return 'agent-author'
+  if (/force-pushing/.test(message)) return 'force-push-main'
+  if (/would throw away/.test(message)) return 'discard-changes'
+  return 'rm-root'
+}
+
+module.exports = { check, rmTargets, dangerousTarget, forcePushToMain, ruleOf, agentAuthor }

package/src/checkout-guard.js

@@ -0,0 +1,296 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { execFileSync } = require('child_process')
+const os = require('os')
+const { runHook, blocked, oneLine, enabled, ASK_USER } = require('./hook')
+const { readSessionFiles } = require('./sessions')
+const shell = require('./shell')
+const { rmTargets } = require('./basics')
+
+// The git commands a line runs on this machine, wrappers (bash -c, env, VAR=value) opened.
+function gitCommands(cmd, mode = 'sh') {
+  return shell.commands(shell.prepare(String(cmd || ''), mode), mode).filter(c => !c.remote && shell.bin(c.argv[0]) === 'git')
+}
+
+// git <sub> args, with -C <dir> pulled out. Returns null for anything that is not git.
+// Takes the words of one command, or a command line (read as its first command).
+function gitCall(seg, cwd) {
+  const t = Array.isArray(seg) ? seg : ((shell.commands(seg)[0] || {}).argv || [])
+  if (shell.bin(t[0] || '') !== 'git') return null
+  let dir = cwd
+  const rest = []
+  for (let i = 1; i < t.length; i++) {
+    if (t[i] === '-C' && t[i + 1]) dir = path.resolve(dir, t[++i])
+    else if (t[i] === '-c') i++
+    else rest.push(t[i])
+  }
+  return { dir, sub: rest[0], args: rest.slice(1) }
+}
+
+const DONE = /^--(?:abort|continue|skip|quit)$/
+
+// What the command does to a shared working tree, or null when it leaves it alone.
+// 'dirty-only' means it matters only when there are uncommitted changes.
+function changesTree({ sub, args, dir = '.' }, exists = fs.existsSync) {
+  const paths = args.indexOf('--') >= 0 ? args.slice(args.indexOf('--') + 1) : []
+  switch (sub) {
+    case 'checkout': {
+      if (paths.length) return paths.includes('.') ? 'restores every file' : null
+      if (args.includes('-')) return 'switches the branch'
+      const names = args.filter(a => !a.startsWith('-'))
+      if (names.includes('.')) return 'restores every file'
+      // git checkout src/app.js restores a file; only a branch or commit moves the tree
+      if (!args.some(a => /^-[bB]$/.test(a)) && names.length && names.every(n => exists(path.resolve(dir, n)))) return null
+      return names.length ? 'switches the branch' : null
+    }
+    case 'switch':
+      return 'switches the branch'
+    case 'restore': {
+      // --staged alone only unstages; the files on disk stay as they are
+      const staged = args.some(a => a === '--staged' || /^-[a-zA-Z]*S/.test(a))
+      const worktree = args.some(a => a === '--worktree' || /^-[a-zA-Z]*W/.test(a))
+      if (staged && !worktree) return null
+      return args.includes('.') ? 'restores every file' : null
+    }
+    case 'stash':
+      return !args[0] || /^(?:push|save|pop|apply|-u|--include-untracked|-k|--keep-index|-m)$/.test(args[0]) ? 'stashes or unstashes changes' : null
+    case 'reset':
+      return args.includes('--hard') ? 'resets the files' : null
+    case 'clean':
+      if (args.some(a => /^-[a-z]*n/.test(a) || a === '--dry-run')) return null
+      return args.some(a => /^-[a-z]*f/.test(a) || a === '--force') ? 'deletes untracked files' : null
+    case 'rebase':
+      return args.some(a => DONE.test(a)) ? null : 'rebases the branch'
+    case 'merge':
+      return args.some(a => DONE.test(a)) ? null : 'merges into the branch'
+    case 'pull':
+      return 'dirty-only'
+    // git add -A, git add ., git commit -a: everything changed in the tree goes into one commit,
+    // including the files the other session is in the middle of editing
+    case 'add':
+      return args.some(a => /^(?:-A|--all|-u|--update|\.|:\/|:)$/.test(a) || /^-[a-zA-Z]*[Au]$/.test(a) || a === './') ? 'stage-all' : null
+    case 'commit':
+      return args.some(a => a === '--all' || /^-[a-zA-Z]*a[a-zA-Z]*$/.test(a)) ? 'stage-all' : null
+    default:
+      return null
+  }
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e.code === 'EPERM'
+  }
+}
+
+// git prints the real path of the tree; a session may have started through a symlink, a junction
+// or a Windows short name (C:\Users\RUNNER~1), so both sides are resolved before comparing.
+const real = p => { try { return fs.realpathSync.native(p) } catch { return path.resolve(p) } }
+const key = (p, platform) => {
+  const n = real(p).replace(/\\/g, '/').replace(/\/+$/, '')
+  return platform === 'win32' ? n.toLowerCase() : n
+}
+const inside = (child, parent) => child === parent || child.startsWith(parent + '/')
+
+// Other live sessions whose project directory is in the same working tree. A session started in
+// a subfolder of this tree could still be in a nested worktree or submodule, so git decides those.
+function sharers(top, sessionId, { files, isAlive, run, platform }) {
+  const topKey = key(top, platform)
+  const out = []
+  for (const [pid, f] of files) {
+    if (!f.cwd || f.sessionId === sessionId || !isAlive(pid)) continue
+    const cwdKey = key(f.cwd, platform)
+    if (!inside(cwdKey, topKey)) continue
+    if (cwdKey !== topKey) {
+      let theirs
+      try { theirs = run(['rev-parse', '--show-toplevel'], f.cwd) } catch { continue }
+      if (key(theirs, platform) !== topKey) continue
+    }
+    out.push({ pid, ...f })
+  }
+  return out
+}
+
+function when(ms) {
+  if (!ms) return 'unknown time'
+  const d = new Date(ms)
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')} ` +
+    `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+}
+
+// git worktree remove <path> and rm -rf <path>: the folders the command deletes.
+function removedDirs(c, cwd, home) {
+  const call = gitCall(c.argv, cwd)
+  if (call && call.sub === 'worktree' && call.args[0] === 'remove') {
+    const rest = call.args.slice(1)
+    const target = rest.find(a => !a.startsWith('-'))
+    return target ? [{ dir: path.resolve(call.dir, expandHome(target, home)), how: 'git worktree remove', force: rest.some(a => a === '-f' || a === '--force') }] : []
+  }
+  return rmTargets(c.argv)
+    .map(t => expandHome(t, home))
+    .map(t => expandPwd(t, cwd))
+    .filter(t => t && !/[$%*?`]/.test(t))
+    .map(t => ({ dir: path.resolve(cwd, t), how: 'deleting', force: true }))
+}
+
+// $PWD, ${PWD}, $(pwd) and `pwd` are the folder the command runs in.
+function expandPwd(arg, cwd) {
+  return String(arg).replace(/^(?:\$PWD|\$\{PWD\}|\$\(\s*pwd\s*\)|`\s*pwd\s*`)(?=[\\/]|$)/, cwd.replace(/\\/g, '/'))
+}
+
+function expandHome(arg, home) {
+  return String(arg)
+    .replace(/^~(?=[\\/]|$)/, home)
+    .replace(/^(?:\$HOME|\$\{HOME\}|\$env:USERPROFILE|%USERPROFILE%)(?=[\\/]|$)/i, home)
+}
+
+// Links in the first two levels of a folder (node_modules linked to the main checkout is the
+// usual one). On Windows, git worktree remove --force has followed a junction and deleted what
+// it pointed to.
+function linksIn(dir) {
+  const out = []
+  const walk = (d, depth) => {
+    let entries
+    try { entries = fs.readdirSync(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.name === '.git') continue
+      const p = path.join(d, e.name)
+      if (e.isSymbolicLink()) out.push(p)
+      else if (e.isDirectory() && depth < 2) walk(p, depth + 1)
+      if (out.length >= 3) return
+    }
+  }
+  walk(dir, 1)
+  return out
+}
+
+function classify(cmd, {
+  cwd = process.cwd(), sessionId = null, files = () => readSessionFiles(), isAlive = alive, run = git, platform = process.platform, mode = 'sh',
+  home = os.homedir(), links = linksIn, removeRule = () => enabled('remove-session-dir'), stageRule = () => enabled('stage-all'),
+} = {}) {
+  const text = shell.prepare(String(cmd || ''), mode)
+  const all = shell.commands(text, mode).filter(c => !c.remote)
+  let live = null
+  const liveOthers = () => live || (live = new Map([...files()].filter(([pid, f]) => f.cwd && f.sessionId !== sessionId && isAlive(pid))))
+
+  for (const c of all) {
+    const removals = removedDirs(c, cwd, home)
+    if (!removals.length) continue
+    const seg = oneLine(c.argv.join(' '), 120)
+    for (const r of removals) {
+      if (r.how === 'git worktree remove' && r.force && platform === 'win32') {
+        const found = links(r.dir)
+        if (found.length) {
+          return {
+            rule: 'worktree-force-links',
+            why: `[bulkhead] checkout-guard: \`${seg}\` force-removes a worktree that holds links (${found.map(f => path.relative(r.dir, f)).join(', ')}).\n` +
+              'On Windows, git worktree remove --force can follow a junction and delete what it points to, such as the main checkout\'s node_modules.\n' +
+              'Remove the links first (rmdir <link> removes a junction, not its target), check none are left, then run git worktree remove without --force.',
+          }
+        }
+      }
+      if (!sessionId || !removeRule()) continue
+      const others = liveOthers()
+      if (!others.size) continue
+      const target = key(r.dir, platform)
+      // a deletion of the folder a session works in, or of a folder above it
+      const hit = [...others].find(([, f]) => inside(key(f.cwd, platform), target))
+      if (hit) {
+        const [pid, f] = hit
+        return {
+          rule: 'remove-session-dir',
+          why: `[bulkhead] checkout-guard: \`${seg}\` removes ${r.dir}, and another Claude session works in it (pid ${pid}, started ${when(f.startedAt)}, in ${f.cwd}).\n` +
+            'Its files, its dev server and its next commit would disappear under it.\n' +
+            'Leave this folder to that session. If it is really finished, wait until it exits (`bulkhead status` lists the live sessions), then remove it.',
+        }
+      }
+    }
+  }
+
+  if (!sessionId) return null
+  for (const c of all) {
+    if (shell.bin(c.argv[0]) !== 'git') continue
+    const call = gitCall(c.argv, cwd)
+    const seg = c.argv.join(' ')
+    if (!call) continue
+    let what = changesTree(call)
+    if (!what || (what === 'stage-all' && !stageRule())) continue
+    if (!liveOthers().size) continue
+    let top
+    try { top = run(['rev-parse', '--show-toplevel'], call.dir) } catch { continue }
+    const others = sharers(top, sessionId, { files: liveOthers(), isAlive, run, platform })
+    if (!others.length) continue
+    const o = others[0]
+    const who = `another Claude session works in the same tree (pid ${o.pid}, started ${when(o.startedAt)}` +
+      (others.length > 1 ? `, and ${others.length - 1} more` : '') + ')'
+    if (what === 'stage-all') {
+      let status = ''
+      try { status = run(['status', '--porcelain'], call.dir) } catch { continue }
+      const changed = status.split('\n').filter(Boolean)
+      if (!changed.length) continue
+      return {
+        rule: 'stage-all',
+        why: `[bulkhead] checkout-guard: \`${oneLine(seg, 120)}\` stages every change in ${top} (${changed.length} file${changed.length === 1 ? '' : 's'}), ` +
+          `and ${who}.\n` +
+          'Some of those changes are probably its half-finished work, and they would go into your commit.\n' +
+          'Stage only the files you changed, by name: git add src/a.ts src/b.ts, or commit them directly with git commit -m "..." -- src/a.ts src/b.ts.',
+      }
+    }
+    if (what === 'dirty-only') {
+      let status = ''
+      try { status = run(['status', '--porcelain', '--untracked-files=no'], call.dir) } catch { continue }
+      if (!status) continue
+      what = 'merges into a tree with uncommitted changes'
+    }
+    const name = path.basename(top)
+    if (call.sub === 'pull') {
+      return {
+        rule: 'git-pull',
+        why: `[bulkhead] checkout-guard: \`${oneLine(seg, 120)}\` ${what} in ${top}, and ${who}.\n` +
+          'A pull rewrites the files that session has open, and a conflict would stop halfway through its edits.\n' +
+          'Wait until it has committed or stashed its changes, or pull from a clone no other session is using.',
+      }
+    }
+    return {
+      rule: `git-${call.sub}`,
+      why: `[bulkhead] checkout-guard: \`${oneLine(seg, 120)}\` ${what} in ${top}, and ${who}.\n` +
+        'Its files and branch would change under it. Work in your own worktree instead:\n' +
+        `  git worktree add ../${name}-<task> -b <branch>`,
+    }
+  }
+  return null
+}
+
+function check(cmd, opts) {
+  const hit = classify(cmd, opts)
+  return hit ? hit.why : null
+}
+
+if (require.main === module) {
+  runHook('checkout-guard', input => {
+    const cmd = input.tool_input && input.tool_input.command
+    if (!cmd) return
+    const hit = classify(cmd, { cwd: input.cwd || process.cwd(), sessionId: input.session_id || null, mode: shell.modeFor(input) })
+    if (!hit) return
+    return blocked('checkout-guard', hit.rule, input, `${hit.why}\n${ASK_USER}`)
+  })
+}
+
+// `git-checkout`, `git-stash` and so on: the first git command that moves the tree.
+function ruleOf(cmd, cwd = '.', mode = 'sh') {
+  for (const c of gitCommands(cmd, mode)) {
+    const call = gitCall(c.argv, cwd)
+    const what = call && changesTree(call)
+    if (what) return what === 'stage-all' ? 'stage-all' : `git-${call.sub}`
+  }
+  return 'git'
+}
+
+module.exports = { check, classify, changesTree, gitCall, ruleOf, linksIn }

package/src/cli-util.js

@@ -0,0 +1,79 @@
+'use strict'
+const os = require('os')
+
+// Small helpers shared by the bulkhead subcommands.
+
+function useColor(stream = process.stdout, env = process.env) {
+  return Boolean(stream && stream.isTTY) && !('NO_COLOR' in env) && env.TERM !== 'dumb'
+}
+
+const CODES = { bold: 1, dim: 2, red: 31, green: 32, yellow: 33, blue: 34, cyan: 36, gray: 90 }
+function paint(on, style, s) {
+  return on ? `\x1b[${CODES[style]}m${s}\x1b[0m` : String(s)
+}
+
+function shortPath(p, home = os.homedir()) {
+  if (!p) return '?'
+  const s = String(p)
+  return home && s.toLowerCase().startsWith(home.toLowerCase()) ? '~' + s.slice(home.length).replace(/\\/g, '/') : s.replace(/\\/g, '/')
+}
+
+// --name value or --name=value. Returns undefined when absent, true for a bare flag at the end.
+function option(args, name) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === `--${name}`) return args[i + 1] !== undefined && !args[i + 1].startsWith('--') ? args[i + 1] : true
+    if (args[i].startsWith(`--${name}=`)) return args[i].slice(name.length + 3)
+  }
+  return undefined
+}
+
+// Cut to `width` visible characters, ending in … when anything was dropped.
+function fit(s, width) {
+  s = String(s == null ? '' : s)
+  if (width <= 0) return ''
+  return s.length > width ? s.slice(0, Math.max(0, width - 1)) + '…' : s
+}
+
+// Columns padded to their widest cell; the last column is not padded.
+function table(rows, gap = '  ') {
+  const widths = []
+  for (const r of rows) r.forEach((c, i) => (widths[i] = Math.max(widths[i] || 0, String(c).length)))
+  return rows.map(r => r.map((c, i) => (i === r.length - 1 ? String(c) : String(c).padEnd(widths[i]))).join(gap).trimEnd())
+}
+
+function bytes(n) {
+  if (n >= 2 ** 30) return `${(n / 2 ** 30).toFixed(1)} GB`
+  if (n >= 2 ** 20) return `${Math.round(n / 2 ** 20)} MB`
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`
+  return `${n} B`
+}
+
+// The first argument a subcommand does not know, as a message, or null. flags take no value,
+// valued ones take `--name value` or `--name=value`, shorts are like { n: true } for `-n 5`.
+function unknownArg(args, { flags = [], valued = [], shorts = [] } = {}) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') continue
+    if (a.startsWith('--')) {
+      const name = a.slice(2).split('=')[0]
+      if (flags.includes(name)) continue
+      if (valued.includes(name)) { if (!a.includes('=') && args[i + 1] !== undefined && !args[i + 1].startsWith('--')) i++; continue }
+      return `unknown option ${a}`
+    }
+    if (a.length === 2 && a[0] === '-' && shorts.includes(a[1])) { i++; continue }
+    return a.startsWith('-') ? `unknown option ${a}` : `unexpected argument ${a}`
+  }
+  return null
+}
+
+// Writes the complaint and the usage text and sets the exit code; true when args were rejected.
+function rejectArgs(cmd, args, spec, stderr, usage) {
+  const bad = unknownArg(args, spec)
+  if (!bad) return false
+  const line = usage || `usage: bulkhead ${cmd} ${[...spec.flags, ...spec.valued].map(f => `[--${f}${spec.valued.includes(f) ? ' X' : ''}]`).join(' ')}`
+  stderr.write(`bulkhead ${cmd}: ${bad}\n${line}\n`)
+  process.exitCode = 1
+  return true
+}
+
+module.exports = { unknownArg, rejectArgs, useColor, paint, shortPath, option, fit, table, bytes }

package/src/cli.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const USAGE = `usage:
+  bulkhead status [--json]              sessions, their ports and memory, slots, free RAM
+  bulkhead top [--interval=SECONDS]     the same, live, full screen (q quits, r refreshes)
+  bulkhead log [-n N] [--since 7d] [--guard NAME] [--summary] [--json]
+                                        what the guards blocked
+  bulkhead scan [--since 30d] [--project TEXT] [-n N] [--json]
+                                        replay your Claude Code transcripts against the guards
+  bulkhead doctor [--json] [--no-remote] check the install, settings and this machine
+  bulkhead config [--json]              effective settings and where each one came from
+  bulkhead port [--near PORT] [--json]  a port no process is listening on
+  bulkhead reap [--dry-run] [--json]    stop what exited sessions left running
+  bulkhead slot run [--gb=N] [--wait=MINUTES] [--label=TEXT] -- <command...>
+  bulkhead slot status [--gb=N]         same as bulkhead-slot
+  bulkhead remote run [--remote=NAME] [--gb=N] [--tail=N] -- <command...>
+                                        run a heavy command on another machine over ssh
+  bulkhead remote status|list|add|remove|fetch   see bulkhead remote --help`
+
+const COMMANDS = {
+  status: './status',
+  top: './top',
+  log: './log-cli',
+  scan: './scan',
+  doctor: './doctor',
+  config: './config-cli',
+  port: './port-cli',
+  reap: './reap-cli',
+  slot: './slot-cli',
+  remote: './remote',
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv
+  if (COMMANDS[cmd]) return require(COMMANDS[cmd]).main(rest)
+  const help = cmd === '--help' || cmd === '-h' || cmd === 'help'
+  ;(help ? console.log : console.error)(USAGE)
+  process.exit(help ? 0 : 1)
+}
+
+module.exports = { main, USAGE }