claude-bulkhead 0.0.0-stage → 0.2.2

package/src/slot-cli.js

@@ -0,0 +1,150 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { spawn } = require('child_process')
+const { stateDir, log } = require('./hook')
+const { readMemory } = require('./memory')
+const { take, release, readSlots, staleReason, slotDir, admit, queueDir, enqueue } = require('./slots')
+
+const USAGE = `usage:
+  bulkhead-slot run [--gb=N] [--wait=MINUTES] [--label=TEXT] -- <command...>
+  bulkhead-slot status [--gb=N]
+
+run waits until the machine has room for a job of N GB (default 3), runs the
+command, and releases the slot when it exits, even on failure. The exit code is
+the command's. status shows who holds slots and whether a new job would start.`
+
+function option(args, name, fallback) {
+  const hit = args.find(a => a.startsWith(`--${name}=`))
+  return hit ? hit.slice(name.length + 3) : fallback
+}
+
+function gbOption(args) {
+  const n = Number(option(args, 'gb', 3))
+  return n > 0 && n <= 256 ? n : 3
+}
+
+function findGitBash(env = process.env, exists = fs.existsSync) {
+  const candidates = [
+    env.CLAUDE_CODE_GIT_BASH_PATH,
+    env.ProgramFiles && path.join(env.ProgramFiles, 'Git', 'bin', 'bash.exe'),
+    env['ProgramFiles(x86)'] && path.join(env['ProgramFiles(x86)'], 'Git', 'bin', 'bash.exe'),
+    env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'),
+  ]
+  return candidates.find(f => f && exists(f)) || null
+}
+
+const posixQuote = a => (/^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)
+const cmdQuote = a => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a)
+
+// One argument is a shell line as typed; several are an argv we quote back together,
+// so `-- bash -c "a && b"` keeps its quotes.
+function shellCommand(args, platform = process.platform, gitBash = null) {
+  if (platform === 'win32' && !gitBash) {
+    return { file: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', args.length === 1 ? args[0] : args.map(cmdQuote).join(' ')] }
+  }
+  const line = args.length === 1 ? args[0] : args.map(posixQuote).join(' ')
+  return { file: platform === 'win32' ? gitBash : '/bin/sh', args: ['-c', line] }
+}
+
+function measure(withCommit) {
+  return readMemory({ withCommit })
+}
+
+function run(args) {
+  const sep = args.indexOf('--')
+  if (sep < 0 || sep === args.length - 1) {
+    console.error(USAGE)
+    return process.exit(1)
+  }
+  const opts = args.slice(0, sep)
+  const command = args.slice(sep + 1)
+  const gb = gbOption(opts)
+  const label = option(opts, 'label', command.join(' ').slice(0, 80))
+  const deadline = Date.now() + Number(option(opts, 'wait', 30)) * 60000
+  const dir = slotDir(stateDir())
+  let announced = false
+  let queued = null
+  const unqueue = () => {
+    if (queued) try { fs.unlinkSync(queued) } catch {}
+    queued = null
+  }
+  process.on('exit', unqueue)
+
+  const attempt = () => {
+    const got = take(dir, { label, gb, pid: process.pid }, measure, (slot, why) => log('slot', `reclaimed ${slot.label}: ${why}`))
+    if (got.file) {
+      unqueue()
+      return start(got.file)
+    }
+    if (Date.now() > deadline) {
+      console.error(`[bulkhead-slot] gave up waiting: ${got.reason}. Holders: ${holders(dir)}`)
+      return process.exit(3)
+    }
+    if (!announced) {
+      console.error(`[bulkhead-slot] waiting: ${got.reason}. Holders: ${holders(dir)}`)
+      announced = true
+      for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => process.exit(130))
+    }
+    queued = enqueue(queueDir(stateDir()), { label, gb, pid: process.pid, at: queuedAt, reason: got.reason })
+    setTimeout(attempt, 15000)
+  }
+  const queuedAt = Date.now()
+
+  const start = file => {
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.removeAllListeners(sig)
+    console.error(`[bulkhead-slot] running ${label} (${gb} GB)`)
+    const { file: shell, args: shellArgs } = shellCommand(command, process.platform, process.platform === 'win32' ? findGitBash() : null)
+    const child = spawn(shell, shellArgs, { stdio: 'inherit', windowsHide: true })
+    const done = code => {
+      release(file)
+      process.exit(code)
+    }
+    child.on('exit', (code, signal) => done(code ?? (signal ? 1 : 0)))
+    child.on('error', e => {
+      console.error(`[bulkhead-slot] could not start: ${e.message}`)
+      done(1)
+    })
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      process.on(sig, () => {
+        try { child.kill(sig) } catch {}
+        done(1)
+      })
+    }
+  }
+
+  attempt()
+}
+
+function holders(dir) {
+  return readSlots(dir).map(s => `${s.label} (${s.gb} GB, pid ${s.pid})`).join(', ') || 'none'
+}
+
+function status(args) {
+  const dir = slotDir(stateDir())
+  const gb = gbOption(args)
+  const held = readSlots(dir)
+  if (!held.length) console.log('no slots held')
+  for (const s of held) {
+    const why = staleReason(s)
+    const mins = Math.round((Date.now() - s.at) / 60000)
+    console.log(`${path.basename(s.file)}: ${s.label} (${s.gb} GB, pid ${s.pid}, ${mins} min)${why ? ` stale: ${why}` : ''}`)
+  }
+  const live = held.filter(s => !staleReason(s))
+  const mem = measure(live.length > 0)
+  const reason = admit({ held: live, mem, gb })
+  const commit = mem.commitPct == null ? '' : `, commit ${mem.commitPct}%`
+  console.log(`free ${mem.freeGb.toFixed(1)} of ${mem.totalGb.toFixed(1)} GB${commit}. A ${gb} GB job would ${reason ? `wait: ${reason}` : 'start now'}.`)
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv
+  if (cmd === 'run') return run(rest)
+  if (cmd === 'status') return status(rest)
+  console.error(USAGE)
+  process.exit(cmd === '--help' || cmd === '-h' ? 0 : 1)
+}
+
+if (require.main === module) main(process.argv.slice(2))
+
+module.exports = { main, shellCommand, findGitBash }

package/src/slots.js

@@ -0,0 +1,168 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { setting } = require('./hook')
+
+const MAX_SLOTS = 8
+const SETTLE_MS = 150 * 1000
+const MAX_AGE_MS = 12 * 3600 * 1000
+const SMALL_MACHINE_GB = 24
+
+// 3 GB free and a 5 GB floor are right for 32 GB; an 8 GB laptop would never get there.
+// So the defaults are 15% and 25% of total RAM, capped at those values.
+const round1 = n => Math.round(n * 10) / 10
+
+function limits(totalGb = os.totalmem() / 2 ** 30) {
+  return {
+    minFreeGb: setting('memory.minFreeGb', Math.min(3, round1(totalGb * 0.15))),
+    floorGb: setting('memory.slotFloorGb', Math.min(5, round1(totalGb * 0.25))),
+    maxCommitPct: setting('memory.maxCommitPct', 75),
+  }
+}
+
+// Returns '' when a job of `gb` may start, otherwise the reason it has to wait.
+// Jobs younger than SETTLE_MS are counted at their full declared size because
+// they have not reached their peak yet.
+function admit({ held, mem, gb, now = Date.now(), limit = limits(mem.totalGb) }) {
+  const free = mem.freeGb
+  if (!held.length) {
+    return free >= limit.minFreeGb ? '' : `free RAM ${free.toFixed(1)} GB is below ${limit.minFreeGb} GB`
+  }
+  if (mem.totalGb < SMALL_MACHINE_GB) return `this machine has ${Math.round(mem.totalGb)} GB; one heavy job at a time`
+  if (held.length >= MAX_SLOTS) return `all ${MAX_SLOTS} slots are taken`
+  const pending = held.filter(s => now - s.at < SETTLE_MS).reduce((sum, s) => sum + s.gb, 0)
+  const left = free - pending - gb
+  if (left < limit.floorGb) {
+    return `free ${free.toFixed(1)} GB` + (pending ? ` - starting jobs ${pending} GB` : '') +
+      ` - this job ${gb} GB = ${left.toFixed(1)} GB, below the ${limit.floorGb} GB floor`
+  }
+  if (mem.commitPct != null && mem.commitPct > limit.maxCommitPct) return `commit charge ${mem.commitPct}% is above ${limit.maxCommitPct}%`
+  return ''
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e.code === 'EPERM'
+  }
+}
+
+function slotDir(stateDir) {
+  return path.join(stateDir, 'slots')
+}
+
+function readSlots(dir) {
+  let names = []
+  try { names = fs.readdirSync(dir) } catch {}
+  const out = []
+  for (const name of names.filter(n => /^slot-\d+\.json$/.test(n))) {
+    const file = path.join(dir, name)
+    try {
+      out.push({ file, ...JSON.parse(fs.readFileSync(file, 'utf8')) })
+    } catch {
+      // half-written or corrupt: treat as held with no owner so reclaim() removes it
+      out.push({ file, label: '?', gb: 0, at: 0, pid: 0 })
+    }
+  }
+  return out
+}
+
+function staleReason(slot, now = Date.now(), isAlive = alive) {
+  if (!slot.pid || !isAlive(slot.pid)) return `owner ${slot.pid || '?'} is gone`
+  if (now - slot.at > MAX_AGE_MS) return 'older than 12 hours'
+  return null
+}
+
+function reclaim(dir, onReclaim = () => {}) {
+  for (const slot of readSlots(dir)) {
+    const why = staleReason(slot)
+    if (!why) continue
+    try {
+      fs.unlinkSync(slot.file)
+      onReclaim(slot, why)
+    } catch {}
+  }
+}
+
+// mkdir is atomic on every platform we support, so it doubles as a cross-process lock.
+function withLock(dir, fn, timeoutMs = 15000) {
+  const lock = path.join(dir, '.lock')
+  const until = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      fs.mkdirSync(lock)
+      break
+    } catch {
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > 30000) fs.rmdirSync(lock)
+      } catch {}
+      if (Date.now() > until) return null
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
+    }
+  }
+  try {
+    return fn()
+  } finally {
+    try { fs.rmdirSync(lock) } catch {}
+  }
+}
+
+// Returns { file } on success or { reason } when the job has to wait.
+function take(dir, { label, gb, pid }, measure, onReclaim) {
+  fs.mkdirSync(dir, { recursive: true })
+  const result = withLock(dir, () => {
+    reclaim(dir, onReclaim)
+    const held = readSlots(dir)
+    const reason = admit({ held, mem: measure(held.length > 0), gb })
+    if (reason) return { reason }
+    const body = JSON.stringify({ label, gb, pid, at: Date.now() })
+    for (let i = 1; i <= MAX_SLOTS; i++) {
+      const file = path.join(dir, `slot-${i}.json`)
+      try {
+        fs.writeFileSync(file, body + '\n', { flag: 'wx' })
+        return { file }
+      } catch {}
+    }
+    return { reason: `all ${MAX_SLOTS} slots are taken` }
+  })
+  return result || { reason: 'another session is holding the slot lock' }
+}
+
+// Jobs waiting in bulkhead-slot run, one file per waiting process. Only for display: admission
+// never reads them, and a file whose process is gone is skipped.
+function queueDir(stateDir) {
+  return path.join(stateDir, 'queue')
+}
+
+function enqueue(dir, entry) {
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const file = path.join(dir, `${entry.pid}.json`)
+    fs.writeFileSync(file, JSON.stringify(entry) + '\n')
+    return file
+  } catch {
+    return null
+  }
+}
+
+function readQueue(dir, isAlive = alive) {
+  let names = []
+  try { names = fs.readdirSync(dir) } catch {}
+  const out = []
+  for (const name of names.filter(n => /^\d+\.json$/.test(n))) {
+    try {
+      const q = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))
+      if (q.pid && isAlive(q.pid)) out.push(q)
+    } catch {}
+  }
+  return out.sort((a, b) => a.at - b.at)
+}
+
+function release(file) {
+  try { fs.unlinkSync(file) } catch {}
+}
+
+module.exports = { admit, take, release, reclaim, readSlots, staleReason, slotDir, limits, queueDir, enqueue, readQueue }

package/src/status.js

@@ -0,0 +1,111 @@
+'use strict'
+const os = require('os')
+const path = require('path')
+const { stateDir } = require('./hook')
+const { rejectArgs } = require('./cli-util')
+const { readMemory } = require('./memory')
+const { readProcesses } = require('./processes')
+const { readSessionFiles, findSessions } = require('./sessions')
+const { readSlots, slotDir, staleReason, readQueue, queueDir } = require('./slots')
+
+const GB = 2 ** 30
+const MONTHS = 'Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec'.split(' ')
+
+// A failed process scan (no powershell, no /proc) still leaves slots and memory to show.
+const orNull = f => { try { return f() } catch { return null } }
+
+function collect({
+  snapshot = orNull(() => readProcesses()),
+  files = readSessionFiles(),
+  slots = readSlots(slotDir(stateDir())).filter(s => !staleReason(s)),
+  queue = readQueue(queueDir(stateDir())),
+  mem = readMemory({ withCommit: true }),
+  now = Date.now(),
+} = {}) {
+  return {
+    at: now,
+    sessions: snapshot ? findSessions(snapshot, files) : [],
+    slots: slots.map(s => ({ slot: path.basename(s.file || '', '.json'), label: s.label, gb: s.gb, pid: s.pid, at: s.at })),
+    queue: queue.map(q => ({ label: q.label, gb: q.gb, pid: q.pid, at: q.at, reason: q.reason })),
+    memory: mem,
+  }
+}
+
+const pad2 = n => String(n).padStart(2, '0')
+
+function when(ms, now) {
+  const d = new Date(ms)
+  const time = `${pad2(d.getHours())}:${pad2(d.getMinutes())}`
+  return d.toDateString() === new Date(now).toDateString() ? time : `${MONTHS[d.getMonth()]} ${d.getDate()} ${time}`
+}
+
+function size(bytes) {
+  return bytes >= GB ? `${(bytes / GB).toFixed(1)} GB` : `${Math.round(bytes / 2 ** 20)} MB`
+}
+
+function shortPath(p, home) {
+  if (!p) return '?'
+  return home && p.toLowerCase().startsWith(home.toLowerCase()) ? '~' + p.slice(home.length).replace(/\\/g, '/') : p
+}
+
+function table(rows) {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map(r => (r[i] == null ? 0 : String(r[i]).length))))
+  return rows.map(r => r.map((c, i) => (i === r.length - 1 ? String(c) : String(c).padEnd(widths[i]))).join('  ').trimEnd())
+}
+
+function render(st, { color = false, home = os.homedir() } = {}) {
+  const head = s => (color ? `\x1b[1m${s}\x1b[0m` : s)
+  const out = []
+  if (st.sessions.length) {
+    const rows = [['SESSION', 'STARTED', 'RSS', 'PROJECT']]
+    const portsAfter = new Map()
+    for (const s of st.sessions) {
+      rows.push([s.pid, when(s.start, st.at), size(s.rss), shortPath(s.cwd, home)])
+      portsAfter.set(rows.length - 1, s.ports)
+    }
+    const lines = table(rows)
+    out.push(head(lines[0]))
+    for (let i = 1; i < lines.length; i++) {
+      out.push(lines[i])
+      for (const p of portsAfter.get(i)) out.push(`  :${p.port}  ${p.name}  pid ${p.pid}`)
+    }
+  } else {
+    out.push('no Claude sessions found')
+  }
+  out.push('')
+  if (st.slots.length) {
+    const lines = table([['SLOT', 'GB', 'PID', 'AGE', 'COMMAND'],
+      ...st.slots.map(s => [s.slot, s.gb, s.pid, `${Math.round((st.at - s.at) / 60000)} min`, s.label])])
+    out.push(head(lines[0]), ...lines.slice(1), '')
+  } else {
+    out.push('no heavy jobs in bulkhead-slot', '')
+  }
+  if (st.queue && st.queue.length) {
+    const lines = table([['WAITING', 'GB', 'PID', 'FOR', 'COMMAND'],
+      ...st.queue.map((q, i) => [`#${i + 1}`, q.gb, q.pid, `${Math.round((st.at - q.at) / 60000)} min`, q.label])])
+    out.push(head(lines[0]), ...lines.slice(1), '')
+  }
+  const m = st.memory
+  out.push(`${m.freeGb.toFixed(1)} GB free of ${m.totalGb.toFixed(1)} GB` + (m.commitPct == null ? '' : `, commit ${m.commitPct}%`))
+  return out.join('\n')
+}
+
+function toJson(st) {
+  return {
+    at: new Date(st.at).toISOString(),
+    sessions: st.sessions.map(s => ({ ...s, start: new Date(s.start).toISOString() })),
+    slots: st.slots.map(s => ({ ...s, at: new Date(s.at).toISOString() })),
+    queue: (st.queue || []).map(q => ({ ...q, at: new Date(q.at).toISOString() })),
+    memory: st.memory,
+  }
+}
+
+function main(args, env = process.env, stdout = process.stdout) {
+  if (rejectArgs('status', args, { flags: ['json'], valued: [] }, process.stderr, null)) return
+  const st = collect()
+  if (args.includes('--json')) return stdout.write(JSON.stringify(toJson(st), null, 2) + '\n')
+  const color = Boolean(stdout.isTTY) && !('NO_COLOR' in env) && env.TERM !== 'dumb'
+  stdout.write(render(st, { color }) + '\n')
+}
+
+module.exports = { collect, render, toJson, main, size, when }

package/src/statusline.js

@@ -0,0 +1,69 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { stateDir } = require('./hook')
+const { readMemory } = require('./memory')
+const { execFileSync } = require('child_process')
+const { readSessionFiles, isClaudeCli } = require('./sessions')
+const { readSlots, slotDir, staleReason } = require('./slots')
+
+const CACHE_MS = 5000
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e.code === 'EPERM'
+  }
+}
+
+// Claude Code CLI processes running now, from one `ps` listing (about 20 ms), the same test
+// `bulkhead status` uses. A session file outlives its process and the OS reuses pids, so counting
+// files whose pid is merely alive overcounts. null when there is no cheap listing (Windows).
+function claudeCount({ platform = process.platform, run = execFileSync } = {}) {
+  if (platform === 'win32') return null
+  let out
+  try {
+    out = run('ps', ['-axww', '-o', 'pid=,args='], { encoding: 'utf8', timeout: 2000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'ignore'] })
+  } catch { return null }
+  let n = 0
+  for (const l of out.split('\n')) {
+    const m = /^\s*(\d+)\s+(.*)$/.exec(l)
+    if (!m) continue
+    const cmd = m[2]
+    if (isClaudeCli({ name: (cmd.split(' ')[0] || '').split(/[\\/]/).pop(), cmd })) n++
+  }
+  return n
+}
+
+// Only cheap reads: session files, slot files and free RAM. No process scan, so it stays
+// well under the 300 ms the status line debounce allows.
+function line({ files = readSessionFiles(), slots = readSlots(slotDir(stateDir())), mem = readMemory(), isAlive = alive, count = null } = {}) {
+  const sessions = count != null ? count : (claudeCount() ?? [...files.keys()].filter(isAlive).length)
+  const heavy = slots.filter(s => !staleReason(s, Date.now(), isAlive)).length
+  return `${sessions} session${sessions === 1 ? '' : 's'}  ${heavy} heavy  ${mem.freeGb.toFixed(1)} GB free`
+}
+
+function cached(file, now = Date.now(), compute = line) {
+  try {
+    const c = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (now - c.at < CACHE_MS && now >= c.at) return c.text
+  } catch {}
+  const text = compute()
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify({ at: now, text }))
+  } catch {}
+  return text
+}
+
+function main() {
+  let text = ''
+  try {
+    text = cached(path.join(stateDir(), 'statusline.json'))
+  } catch {}
+  process.stdout.write(text + '\n')
+}
+
+module.exports = { line, cached, main, claudeCount }

package/src/top-worker.js

@@ -0,0 +1,14 @@
+'use strict'
+// Runs the process scan for `bulkhead top` off the main thread. On Windows the scan is a
+// PowerShell call of a second or more, and the screen and keys must stay responsive meanwhile.
+const { parentPort } = require('worker_threads')
+const { collect } = require('./status')
+
+parentPort.on('message', () => {
+  const started = Date.now()
+  try {
+    parentPort.postMessage({ ok: true, st: collect(), ms: Date.now() - started })
+  } catch (e) {
+    parentPort.postMessage({ ok: false, error: e.message, ms: Date.now() - started })
+  }
+})