claude-bulkhead 0.2.2 → 0.3.0

package/src/cli.js

@@ -3,19 +3,32 @@
 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]
+  bulkhead log [SPAN] [-n N] [--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 scan --share [--markdown]    paste-ready summary of those numbers, counts only
+  bulkhead doctor [--json] [--no-remote] check the install, enforcement and this machine
   bulkhead config [--json]              effective settings and where each one came from
+  bulkhead config --preset quiet|normal|strict [--project]
+                                        fewer or more guards at once
+  bulkhead explain [--cwd DIR] [--session-id ID] [--json] -- <command...>
+                                        what every guard would say about a command, nothing runs
+  bulkhead allow <code> | --list        allow one blocked command once (you run this, not the agent)
   bulkhead port [--near PORT] [--json]  a port no process is listening on
+  bulkhead port --stable [--name NAME] [--range 3000-3999]
+                                        this worktree's own port, the same every time
+  bulkhead worktree add|list|prune      one-step worktrees: env files, install, stable port, safe cleanup
   bulkhead reap [--dry-run] [--json]    stop what exited sessions left running
+  bulkhead hook --agent NAME            the guards for Codex, Gemini, Copilot, Cursor and other agents (reads the pre-tool payload on stdin)
+  bulkhead setup AGENT [--print|--write] the hook config for that agent: print it, or merge it into the agent's config file
   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`
+  bulkhead remote status|list|add|remove|fetch   see bulkhead remote --help
+  bulkhead version                      print the version
+  bulkhead help <command>               usage of one command`
 
 const COMMANDS = {
   status: './status',
@@ -24,18 +37,41 @@ const COMMANDS = {
   scan: './scan',
   doctor: './doctor',
   config: './config-cli',
+  explain: './explain',
+  allow: './allow-cli',
   port: './port-cli',
   reap: './reap-cli',
+  worktree: './worktree-cli',
+  hook: './agent-hook',
+  setup: './agent-setup',
   slot: './slot-cli',
   remote: './remote',
 }
 
+// The USAGE lines of one command: its own text when its module has one, else its block of the list above.
+function usageOf(cmd) {
+  const own = COMMANDS[cmd] && require(COMMANDS[cmd]).USAGE
+  if (own) return own
+  const out = []
+  let on = false
+  for (const line of USAGE.split('\n').slice(1)) {
+    if (/^ {2}bulkhead \S/.test(line)) on = line.startsWith(`  bulkhead ${cmd}`)
+    if (on) out.push(line)
+  }
+  return out.length ? `usage:\n${out.join('\n')}` : null
+}
+
 function main(argv) {
   const [cmd, ...rest] = argv
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') return console.log(require('../package.json').version)
+  if (cmd === 'help' && rest[0] && COMMANDS[rest[0]]) return console.log(usageOf(rest[0]) || USAGE)
+  // remote has its own --help with subcommands
+  if (COMMANDS[cmd] && cmd !== 'remote' && (rest.includes('-h') || rest.includes('--help'))) return console.log(usageOf(cmd) || USAGE)
   if (COMMANDS[cmd]) return require(COMMANDS[cmd]).main(rest)
   const help = cmd === '--help' || cmd === '-h' || cmd === 'help'
+  if (!help && cmd) console.error(`bulkhead: unknown command "${cmd}"`)
   ;(help ? console.log : console.error)(USAGE)
   process.exit(help ? 0 : 1)
 }
 
-module.exports = { main, USAGE }
+module.exports = { main, USAGE, COMMANDS }

package/src/config-check.js

@@ -1,8 +1,11 @@
 'use strict'
-// SessionStart: one notice when a bulkhead config file is broken. The guards ignore a broken
-// file and run on their defaults, so without this nobody would notice a typo.
+// SessionStart, one message for the user: the first-run line (once ever), what orphan-reaper stopped
+// since the last message, and a broken config file. The guards ignore a broken file and run on
+// their defaults, so without this nobody would notice a typo.
 const { load } = require('./config')
 const { shortPath } = require('./cli-util')
+const { stateDir } = require('./hook')
+const notices = require('./notices')
 
 function notice(cfg) {
   if (!cfg.warnings.length) return null
@@ -11,6 +14,20 @@ function notice(cfg) {
   return `[bulkhead] config problem, defaults are used where it applies:\n${lines.join('\n')}\nRun \`bulkhead config\` or \`bulkhead doctor\` to check.`
 }
 
+function part(f) {
+  try { return f() } catch { return null }
+}
+
+// Each part fails on its own, so a broken one never hides the others.
+function message(input, dir = stateDir()) {
+  const parts = [
+    part(() => notices.firstRun(dir)),
+    part(() => notices.format(notices.claim(dir))),
+    part(() => notice(load({ cwd: process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd() }))),
+  ].filter(Boolean)
+  return parts.length ? parts.join('\n') : null
+}
+
 if (require.main === module) {
   let raw = ''
   process.stdin.setEncoding('utf8')
@@ -19,11 +36,11 @@ if (require.main === module) {
     try {
       let input = {}
       try { input = JSON.parse(raw || '{}') } catch {}
-      const msg = notice(load({ cwd: process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd() }))
+      const msg = message(input)
       if (msg) process.stdout.write(JSON.stringify({ systemMessage: msg }))
     } catch {}
     process.exit(0)
   })
 }
 
-module.exports = { notice }
+module.exports = { notice, message }

package/src/config-cli.js

@@ -1,7 +1,9 @@
 'use strict'
 const fs = require('fs')
-const { load, KEYS } = require('./config')
-const { useColor, paint, shortPath, table, rejectArgs } = require('./cli-util')
+const os = require('os')
+const path = require('path')
+const { load, KEYS, PRESETS, globalFile, projectFile } = require('./config')
+const { useColor, paint, shortPath, table, rejectArgs, option } = require('./cli-util')
 
 function fileState(file, warnings) {
   if (!file) return 'none found'
@@ -9,19 +11,37 @@ function fileState(file, warnings) {
   return warnings.some(w => w.startsWith(file) && /not valid JSON/.test(w)) ? 'INVALID, ignored' : 'loaded'
 }
 
+const USAGE = `usage: bulkhead config [--json]
+       bulkhead config --preset quiet|normal|strict [--project]
+
+Without options, prints every setting, its value and where the value came from.
+--preset writes "preset" into the global config file, or with --project into this project's
+.claude/bulkhead.json, keeping every other key. quiet: only the cross-session guards and the
+rules that cannot be undone. normal: the defaults. strict: everything on, with tighter limits.
+Keys you set yourself and environment variables still win over a preset.`
+
+// The two RAM limits left on auto, as the number they work out to on this machine.
+function autoValue(key, totalGb) {
+  const { autoLimits } = require('./slots')
+  const a = autoLimits(totalGb)
+  const gb = key === 'memory.minFreeGb' ? a.minFreeGb : key === 'memory.slotFloorGb' ? a.floorGb : null
+  return gb == null ? 'auto' : `auto (${gb} GB on this machine)`
+}
+
 // The remotes map is long; the table shows the names and `bulkhead remote list` the rest.
-const show = (v, key) => (v === null ? 'auto' : key === 'remotes' ? Object.keys(v).join(', ') || 'none' : JSON.stringify(v))
+const show = (v, key, totalGb) => (v === null ? autoValue(key, totalGb) : key === 'remotes' ? Object.keys(v).join(', ') || 'none' : JSON.stringify(v))
 
-function render(cfg, { color = false, home } = {}) {
+function render(cfg, { color = false, home, totalGb = os.totalmem() / 2 ** 30 } = {}) {
   const out = []
   out.push(paint(color, 'bold', 'Files (project wins over global, environment wins over both)'))
   out.push(`  global   ${shortPath(cfg.files.global, home)}  ${fileState(cfg.files.global, cfg.warnings)}`)
   out.push(`  project  ${cfg.files.project ? shortPath(cfg.files.project, home) : '<repo>/.claude/bulkhead.json'}  ${fileState(cfg.files.project, cfg.warnings)}`)
+  out.push(`  preset   ${cfg.preset || 'normal'}  ${cfg.presetFrom && cfg.presetFrom !== 'default' ? `(from ${cfg.presetFrom.startsWith('env ') ? cfg.presetFrom : shortPath(cfg.presetFrom, home)})` : '(default)'}`)
   out.push('')
   const rows = [['KEY', 'VALUE', 'FROM']]
   for (const key of Object.keys(KEYS)) {
     const src = cfg.sources[key]
-    rows.push([key, show(cfg.values[key], key), src === 'default' || src.startsWith('env ') ? src : shortPath(src, home)])
+    rows.push([key, show(cfg.values[key], key, totalGb), src === 'default' || src.startsWith('env ') || src.startsWith('preset ') ? src : shortPath(src, home)])
   }
   const lines = table(rows)
   out.push(paint(color, 'bold', lines[0]))
@@ -36,16 +56,61 @@ function render(cfg, { color = false, home } = {}) {
   return out.join('\n')
 }
 
-function main(args, { env = process.env, stdout = process.stdout } = {}) {
-  if (rejectArgs('config', args, { flags: ['json'], valued: [] }, process.stderr, null)) return
-  const cfg = load({ env })
+// Sets "preset" in one config file and leaves every other key alone. A file that is not valid
+// JSON is never overwritten.
+function writePreset(file, name) {
+  let obj = {}
+  let text = null
+  try { text = fs.readFileSync(file, 'utf8') } catch {}
+  if (text !== null) {
+    try { obj = JSON.parse(text.replace(/^\uFEFF/, '')) } catch (e) { return { error: `${file} is not valid JSON (${e.message}); fix it first` } }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return { error: `${file} should hold a JSON object` }
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify({ ...obj, preset: name }, null, 2) + '\n')
+  fs.renameSync(tmp, file)
+  return { file }
+}
+
+function setPreset(args, { env, stdout, stderr, cwd }) {
+  const value = option(args, 'preset')
+  const name = String(value)
+  if (!PRESETS[name]) {
+    const list = Object.keys(PRESETS).join(', ')
+    stderr.write(value === true ? `bulkhead config: --preset needs a name: ${list}\n` : `bulkhead config: unknown preset ${name}; use ${list}\n`)
+    process.exitCode = 1
+    return
+  }
+  const project = args.includes('--project')
+  const file = project ? projectFile(cwd) || path.join(path.resolve(cwd), '.claude', 'bulkhead.json') : globalFile(env)
+  let res
+  try { res = writePreset(file, name) } catch (e) { res = { error: `could not write ${file}: ${e.message}` } }
+  if (res.error) {
+    stderr.write(`bulkhead config: ${res.error}\n`)
+    process.exitCode = 1
+    return
+  }
+  stdout.write(`preset ${name} written to ${shortPath(file)}${project ? '' : ' (every project; a project file or BULKHEAD_PRESET can still override it)'}\n`)
+}
+
+function main(args, { env = process.env, stdout = process.stdout, stderr = process.stderr, cwd = env.CLAUDE_PROJECT_DIR || process.cwd() } = {}) {
+  if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
+  if (rejectArgs('config', args, { flags: ['json', 'project'], valued: ['preset'] }, stderr, USAGE)) return
+  if (option(args, 'preset') !== undefined) return setPreset(args, { env, stdout, stderr, cwd })
+  if (args.includes('--project')) {
+    stderr.write('bulkhead config: --project goes with --preset\n')
+    process.exitCode = 1
+    return
+  }
+  const cfg = load({ env, cwd })
   if (args.includes('--json')) {
     const settings = {}
     for (const key of Object.keys(KEYS)) settings[key] = { value: cfg.values[key], from: cfg.sources[key] }
-    stdout.write(JSON.stringify({ files: cfg.files, settings, warnings: cfg.warnings }, null, 2) + '\n')
+    stdout.write(JSON.stringify({ preset: cfg.preset, files: cfg.files, settings, warnings: cfg.warnings }, null, 2) + '\n')
     return
   }
   stdout.write(render(cfg, { color: useColor(stdout, env) }) + '\n')
 }
 
-module.exports = { main, render }
+module.exports = { main, render, writePreset, USAGE }

package/src/config.js

@@ -5,7 +5,7 @@ const path = require('path')
 const { pathKey } = require('./paths')
 
 // Settings come from three places, later ones winning:
-//   1. defaults below
+//   1. defaults below, then the preset ("preset" in a config file or BULKHEAD_PRESET) over them
 //   2. <state dir>/config.json                      (global, usually ~/.claude/bulkhead/config.json)
 //   3. <project>/.claude/bulkhead.json              (project, merged over global)
 //   4. environment variables                        (always win)
@@ -19,14 +19,25 @@ const GUARDS = {
   'checkout-guard': 'checkoutGuard',
   'disk-guard': 'diskGuard',
   basics: 'basics',
+  'edit-guard': 'editGuard',
+  'secrets-guard': 'secretsGuard',
   'orphan-reaper': 'orphanReaper',
+  'session-state': 'sessionState',
 }
 // rules that can be turned off one at a time, inside a guard that stays on
 const RULES = {
   'rm-root': 'basics.rmRoot',
   'force-push-main': 'basics.forcePushMain',
   'discard-changes': 'basics.discardChanges',
+  'protected-delete': 'basics.protectedDelete',
   'agent-author': 'basics.agentAuthor',
+  'self-allow': 'basics.selfAllow',
+  'mass-kill': 'killGuard.massKill',
+  'docker-mass': 'killGuard.dockerMass',
+  'device-kill': 'killGuard.deviceKill',
+  'app-quit': 'killGuard.appQuit',
+  'service-stop': 'killGuard.serviceStop',
+  'owner-check': 'killGuard.ownerCheck',
   'stage-all': 'checkoutGuard.stageAll',
   'remove-session-dir': 'checkoutGuard.removeSessionDir',
 }
@@ -38,9 +49,19 @@ const KEYS = {
   'killGuard.enabled': on('kill-guard'),
   'killGuard.allowNames': { type: 'string[]', default: [], doc: 'Program names to take off the shared list, so killing them by name passes.' },
   'killGuard.extraSharedNames': { type: 'string[]', default: [], doc: 'More program names that must not be killed by name.' },
+  'killGuard.massKill': bool(true, 'Block pkill -u, kill -1 and kill 0 while another Claude session is alive.'),
+  'killGuard.dockerMass': bool(true, 'Block docker prune, stopping every container, pm2 kill and docker compose down in another session\'s folder while another Claude session is alive.'),
+  'killGuard.deviceKill': bool(true, 'Block adb kill-server, adb emu kill and simctl shutdown all while another Claude session is alive.'),
+  'killGuard.appQuit': bool(true, 'Block quitting shared apps (osascript quit, pkill Slack, killall Finder) while another Claude session is alive.'),
+  'killGuard.serviceStop': bool(true, 'Block stopping shared services (brew services stop, launchctl bootout, pkill redis-server) while another Claude session is alive.'),
+  'killGuard.ownerCheck': bool(true, 'Block kill <pid> and pkill -f <pattern> when they reach another Claude session\'s processes.'),
   'waitGuard.enabled': on('wait-guard'),
   'waitGuard.limitSeconds': { type: 'number', default: 180, env: 'BULKHEAD_WAIT_MAX_SEC', doc: 'Longest foreground wait allowed, in seconds.' },
   'memoryGuard.enabled': on('memory-guard'),
+  'memoryGuard.autoQueue': bool(false, 'Instead of blocking a heavy command, run it through bulkhead-slot so every session waits in one line.'),
+  'memoryGuard.estimatesGb': { type: 'numbers', default: null, doc: 'RAM in GB bulkhead assumes per tool when auto-queueing, by program name: { "gradle": 6 }.' },
+  'memoryGuard.waitMinutes': { type: 'number', default: 10, doc: 'How long an auto-queued command waits for room before giving up (bulkhead-slot --wait).' },
+  'memoryGuard.subagents': bool(false, 'Block starting a new subagent while memory pressure is critical.'),
   'memory.minFreeGb': { type: 'number', default: null, env: 'BULKHEAD_MIN_FREE_GB', doc: 'Free RAM below which memory-guard blocks heavy commands. Default: 3, or 15% of RAM if less.' },
   'memory.slotFloorGb': { type: 'number', default: null, env: 'BULKHEAD_SLOT_FLOOR_GB', doc: 'RAM bulkhead-slot keeps free when it starts a second job. Default: 5, or 25% of RAM if less.' },
   'memory.maxCommitPct': { type: 'number', default: 75, env: 'BULKHEAD_MAX_COMMIT_PCT', doc: 'Windows commit charge above which bulkhead-slot holds a second job.' },
@@ -54,18 +75,61 @@ const KEYS = {
   'basics.protectedBranches': { type: 'string[]', default: ['main', 'master'], doc: 'Branches force-push-main protects.' },
   'basics.rmRoot': bool(true, 'Block rm -rf at roots, top-level system folders, the home directory, folders directly in it (caches excepted) and folders above the repository.'),
   'basics.forcePushMain': bool(true, 'Block force-pushes to the protected branches.'),
+  'basics.protectedDelete': bool(true, 'Block deleting a protected branch (git push origin :main, git push --delete, git branch -D).'),
   'basics.discardChanges': bool(true, 'Block git reset --hard and git clean -fd that would lose work.'),
   'basics.agentAuthor': bool(true, 'Block commits authored as Claude or Anthropic (--author, git config user.*, GIT_AUTHOR_*), so the work counts as yours.'),
+  'basics.selfAllow': bool(true, 'Block the agent running bulkhead allow or writing the allow state files, so only the user approves a block.'),
+  'allowOnce.ttlMinutes': { type: 'number', default: 10, doc: 'Minutes an allow-once code stays valid, and how long an approved command can still be run once.' },
+  'editGuard.enabled': on('edit-guard'),
+  'editGuard.mode': { type: 'string', default: 'warn', doc: 'What edit-guard does when another live session edited the same file lately: "warn" tells the agent, "ask" asks you, "block" stops the edit.' },
+  'editGuard.windowMinutes': { type: 'number', default: 30, doc: 'How recent the other session\'s edit must be, in minutes.' },
+  'secretsGuard.enabled': bool(false, 'Turn secrets-guard on or off. Off by default; on in the strict preset.'),
+  'secretsGuard.extraPatterns': { type: 'string[]', default: [], doc: 'More files secrets-guard keeps out of the conversation: a file name (*.token) or a path pattern (~/vault/**).' },
+  'secretsGuard.allow': { type: 'string[]', default: [], doc: 'Files secrets-guard lets through even though they look secret, by the same patterns.' },
   'orphanReaper.enabled': on('orphan-reaper'),
   'orphanReaper.onSessionEnd': bool(true, 'Also reap right after a session exits, not only when the next session starts.'),
   'orphanReaper.extraNames': { type: 'string[]', default: [], doc: 'More program names orphan-reaper stops once the session that started them has exited.' },
   'orphanReaper.keepNames': { type: 'string[]', default: [], doc: 'Program names orphan-reaper never stops, nor anything they started.' },
+  'orphanReaper.keepPatterns': { type: 'string[]', default: [], doc: 'Text that keeps a process when it appears in its command line, such as "ssh -L" or "my-tunnel.sh". Case is ignored.' },
+  'sessionState.enabled': on('session-state'),
+  'notify.command': { type: 'string', default: null, globalOnly: true, doc: 'Command run (detached) when a session starts waiting for you. Gets BULKHEAD_SESSION_PROJECT, BULKHEAD_SESSION_STATE and BULKHEAD_SESSION_PID. Off by default; global config file only.' },
+  'notify.minIntervalSeconds': { type: 'number', default: 30, doc: 'Least seconds between two notifications for the same session.' },
   'log.enabled': bool(true, 'Write blocks to events.jsonl. BULKHEAD_NO_LOG=1 turns it off.'),
   // Global file only (see src/remotes.js for why).
   'remote.default': { type: 'string', default: null, globalOnly: true, doc: 'The remote bulkhead remote uses when several are configured and --remote is not given.' },
   remotes: { type: 'remotes', default: {}, globalOnly: true, doc: 'Machines bulkhead remote can run jobs on: { name: { host, shell, dir, copies, maxJobs, minFreeGb, sshOptions } }.' },
 }
 
+// Layered defaults: a preset only changes the default of the keys it names, so any key a config
+// file sets, and any environment variable, still wins. normal is the plain defaults. A value
+// that is a function gets the machine's RAM in GB, so a threshold scales on small machines.
+const round1 = n => Math.round(n * 10) / 10
+const PRESETS = {
+  normal: {},
+  // only what protects one session from another, plus the two rules that cannot be undone
+  quiet: {
+    'waitGuard.enabled': false,
+    'diskGuard.enabled': false,
+    'basics.discardChanges': false,
+    'basics.agentAuthor': false,
+  },
+  // everything on, with tighter limits: waits over a minute, less free RAM tolerated, more protected branches
+  strict: {
+    'waitGuard.limitSeconds': 60,
+    'memory.minFreeGb': gb => Math.min(5, round1(gb * 0.2)),
+    'memory.slotFloorGb': gb => Math.min(8, round1(gb * 0.35)),
+    'memory.maxCommitPct': 65,
+    'basics.protectedBranches': ['main', 'master', 'develop', 'release', 'production'],
+    'secretsGuard.enabled': true,
+  },
+}
+
+function presetValues(name, totalGb = os.totalmem() / 2 ** 30) {
+  const out = {}
+  for (const [k, v] of Object.entries(PRESETS[name] || {})) out[k] = typeof v === 'function' ? v(totalGb) : v
+  return out
+}
+
 function stateDir(env = process.env) {
   return env.BULKHEAD_STATE_DIR || path.join(os.homedir(), '.claude', 'bulkhead')
 }
@@ -98,6 +162,7 @@ function typeOk(type, v) {
   if (type === 'string') return typeof v === 'string'
   if (type === 'string[]') return Array.isArray(v) && v.every(x => typeof x === 'string')
   if (type === 'number[]') return Array.isArray(v) && v.every(x => Number.isInteger(x) && x > 0 && x < 65536)
+  if (type === 'numbers') return Boolean(v) && typeof v === 'object' && !Array.isArray(v) && Object.values(v).every(x => typeof x === 'number' && x > 0)
   return false
 }
 
@@ -122,6 +187,11 @@ function flatten(obj, file, warnings, scope = 'global') {
       out.remotes = remotes
       continue
     }
+    if (section === 'preset') {
+      if (PRESETS[body]) out.preset = body
+      else warnings.push(`${file}: "preset" should be one of ${Object.keys(PRESETS).join(', ')}`)
+      continue
+    }
     if (!body || typeof body !== 'object' || Array.isArray(body)) {
       warnings.push(`${file}: "${section}" should be an object`)
       continue
@@ -159,8 +229,8 @@ function envValue(spec, env) {
   return raw
 }
 
-// Defaults with both files merged over them. Read once per process.
-function fileLayer({ env = process.env, cwd = env.CLAUDE_PROJECT_DIR || process.cwd(), read } = {}) {
+// Defaults, then the preset, then both files merged over them. Read once per process.
+function fileLayer({ env = process.env, cwd = env.CLAUDE_PROJECT_DIR || process.cwd(), read, totalGb } = {}) {
   const warnings = []
   const values = {}
   const sources = {}
@@ -169,16 +239,29 @@ function fileLayer({ env = process.env, cwd = env.CLAUDE_PROJECT_DIR || process.
     sources[k] = 'default'
   }
   const files = { global: globalFile(env), project: projectFile(cwd) }
+  const parsed = []
   for (const [scope, file] of [['global', files.global], ['project', files.project]]) {
     if (!file) continue
     const got = readFile(file, warnings, read, scope)
-    if (!got) continue
+    if (got) parsed.push({ file, got })
+  }
+  // the project file's preset wins over the global one; BULKHEAD_PRESET wins over both
+  let preset = 'normal'
+  let presetFrom = 'default'
+  for (const { file, got } of parsed) if (got.preset) [preset, presetFrom] = [got.preset, file]
+  if (PRESETS[String(env.BULKHEAD_PRESET || '').trim()]) [preset, presetFrom] = [env.BULKHEAD_PRESET.trim(), 'env BULKHEAD_PRESET']
+  for (const [k, v] of Object.entries(presetValues(preset, totalGb))) {
+    values[k] = v
+    sources[k] = `preset ${preset}`
+  }
+  for (const { file, got } of parsed) {
     for (const [k, v] of Object.entries(got)) {
+      if (k === 'preset') continue
       values[k] = v
       sources[k] = file
     }
   }
-  return { values, sources, files, warnings }
+  return { values, sources, files, warnings, preset, presetFrom }
 }
 
 // { values, sources, files, warnings }. sources[key] is 'default', a file path or 'env NAME'.
@@ -211,16 +294,30 @@ function withEnv(layer, env) {
       sources[k] = 'env BULKHEAD_DISABLE'
     }
   }
-  return { values, sources, files: layer.files, warnings: layer.warnings }
+  return { values, sources, files: layer.files, warnings: layer.warnings, preset: layer.preset, presetFrom: layer.presetFrom }
 }
 
+// A hook asks for many settings per call; the files are read once and the environment layer is
+// rebuilt only when one of the variables it reads has changed.
 let cached = null
+let withEnvCache = null
+let envNames = null
+function envKey(env) {
+  if (!envNames) envNames = [...new Set(Object.values(KEYS).map(s => s.env).filter(Boolean)), 'BULKHEAD_NO_LOG', 'BULKHEAD_DISABLE']
+  return envNames.map(n => (env[n] === undefined ? '\u0000' : env[n])).join('\u0001')
+}
 function current() {
-  if (!cached) cached = fileLayer()
-  return withEnv(cached, process.env)
+  if (!cached) {
+    cached = fileLayer()
+    withEnvCache = null
+  }
+  const key = envKey(process.env)
+  if (!withEnvCache || withEnvCache.key !== key) withEnvCache = { key, cfg: withEnv(cached, process.env) }
+  return withEnvCache.cfg
 }
 function reset() {
   cached = null
+  withEnvCache = null
 }
 
 function get(key, cfg = current()) {
@@ -233,4 +330,4 @@ function isEnabled(name, cfg = current()) {
   return key ? cfg.values[key] !== false : true
 }
 
-module.exports = { load, current, reset, get, isEnabled, projectFile, globalFile, KEYS, GUARDS, RULES, flatten }
+module.exports = { load, current, reset, get, isEnabled, projectFile, globalFile, KEYS, GUARDS, RULES, PRESETS, presetValues, flatten }