claude-bulkhead 0.0.0-stage → 0.2.2

package/src/top.js

@@ -0,0 +1,305 @@
+'use strict'
+const os = require('os')
+const path = require('path')
+const { stateDir } = require('./hook')
+const { tailEvents } = require('./events')
+const { limits } = require('./slots')
+const { size, when } = require('./status')
+const { useColor, paint, shortPath, option, fit, rejectArgs } = require('./cli-util')
+
+const USAGE = `usage: bulkhead top [--interval=SECONDS] [--once]
+
+A live view of the Claude Code sessions on this machine, their memory, child processes
+and ports, the bulkhead-slot jobs and queue, free RAM, and the latest blocks.
+Keys: q or Ctrl-C quits, r refreshes now.
+When the output is not a terminal, or with --once, it prints one snapshot and exits.`
+
+const ESC = '\x1b['
+const ALT_ON = `${ESC}?1049h`
+const ALT_OFF = `${ESC}?1049l`
+const HIDE = `${ESC}?25l`
+const SHOW = `${ESC}?25h`
+const HOME = `${ESC}H`
+const CLEAR_EOL = `${ESC}K`
+const CLEAR_EOS = `${ESC}J`
+const SPINNER = '|/-\\'
+
+function defaultInterval(platform = process.platform) {
+  return platform === 'win32' ? 4000 : 2000
+}
+
+function meter(fraction, width) {
+  const n = Math.max(0, Math.min(width, Math.round(fraction * width)))
+  return '█'.repeat(n) + '░'.repeat(width - n)
+}
+
+// Plain cell of exactly `width` columns.
+const cell = (s, width, right = false) => {
+  const t = fit(s, width)
+  return right ? t.padStart(width) : t.padEnd(width)
+}
+
+// Session table columns. When the terminal is narrow, columns go in `drop` order, then the
+// project column shrinks. Widths are fixed except the project and ports columns.
+const COLUMNS = [
+  { key: 'pid', title: 'PID', width: 7 },
+  { key: 'started', title: 'STARTED', width: 12, drop: 2 },
+  { key: 'project', title: 'PROJECT', width: 12, flex: true },
+  { key: 'rss', title: 'RSS', width: 7, right: true },
+  { key: 'bar', title: '', width: 10, drop: 1 },
+  { key: 'procs', title: 'PROCS', width: 5, right: true, drop: 4 },
+  { key: 'ports', title: 'PORTS', width: 6, grow: 22, drop: 3 },
+]
+
+function layout(width) {
+  let cols = COLUMNS.slice()
+  const total = cs => cs.reduce((n, c) => n + c.width, 0) + (cs.length - 1) * 2
+  for (const d of [1, 2, 3, 4]) {
+    if (total(cols) <= width) break
+    cols = cols.filter(c => c.drop !== d)
+  }
+  cols = cols.map(c => ({ ...c }))
+  let spare = width - total(cols)
+  const ports = cols.find(c => c.key === 'ports')
+  if (ports && spare > 0) {
+    const add = Math.min(spare, ports.grow - ports.width)
+    ports.width += add
+    spare -= add
+  }
+  const project = cols.find(c => c.key === 'project')
+  project.width = Math.max(4, project.width + spare)
+  return cols
+}
+
+// One screen as an array of lines, each at most `width` visible columns.
+function frame(view, { width = 100, height = 40, color = false, home = os.homedir() } = {}) {
+  width = Math.max(24, width)
+  const c = (style, s) => paint(color, style, s)
+  const lines = []
+  const st = view.st
+  const now = view.now || Date.now()
+  const d = new Date(now)
+  const clock = [d.getHours(), d.getMinutes(), d.getSeconds()].map(n => String(n).padStart(2, '0')).join(':')
+
+  // header
+  const state = view.scanning ? `scanning ${SPINNER[(view.tick || 0) % 4]}` : view.lastScanMs != null ? `scan ${(view.lastScanMs / 1000).toFixed(1)}s` : ''
+  const left = `bulkhead top  ${clock}`
+  const right = `${state}  every ${Math.round(view.interval / 1000)}s  q quit  r refresh`
+  const gap = width - left.length - right.length
+  if (gap >= 2) lines.push(c('bold', left) + ' '.repeat(gap) + (view.scanning ? c('yellow', right.slice(0, state.length)) + right.slice(state.length) : right))
+  else lines.push(c('bold', fit(`${left}  ${state}`, width)))
+
+  if (!st) {
+    lines.push('', view.error ? c('red', fit(`scan failed: ${view.error}`, width)) : 'reading processes...')
+    return lines
+  }
+
+  // memory
+  const m = st.memory
+  const lim = limits(m.totalGb)
+  const used = m.totalGb - m.freeGb
+  const low = m.freeGb < lim.minFreeGb
+  const tight = m.freeGb < lim.floorGb
+  const extra = [
+    m.commitPct != null ? `commit ${m.commitPct}%` : null,
+    m.swapTotalGb ? `swap ${m.swapUsedGb.toFixed(1)}/${m.swapTotalGb.toFixed(1)} GB` : null,
+  ].filter(Boolean).join('  ')
+  const memText = `${m.freeGb.toFixed(1)} GB free of ${m.totalGb.toFixed(1)} GB` + (extra ? `  ${extra}` : '')
+  const barWidth = Math.max(0, Math.min(30, width - memText.length - 7))
+  const barStyle = low ? 'red' : tight ? 'yellow' : 'green'
+  lines.push((barWidth >= 5 ? `RAM ${c(barStyle, meter(used / m.totalGb, barWidth))}  ` : 'RAM ') + fit(memText, width - (barWidth >= 5 ? barWidth + 6 : 4)))
+  if (low) lines.push(c('red', fit(`below ${lim.minFreeGb} GB: memory-guard is blocking heavy commands`, width)))
+  lines.push('')
+
+  // sessions
+  const sessions = st.sessions
+  const cols = layout(width)
+  lines.push(c('bold', fit(`SESSIONS ${sessions.length}`, width)))
+  lines.push(c('dim', cols.map(col => cell(col.title, col.width, col.right)).join('  ').trimEnd()))
+  const maxRss = Math.max(1, ...sessions.map(s => s.rss))
+
+  // what has to fit below the session rows
+  const slotRows = st.slots.length + (st.queue || []).length
+  const events = view.events || []
+  const below = 2 + (slotRows ? slotRows + 1 : 1) + 2 + Math.max(1, events.length)
+  const room = Math.max(1, height - lines.length - below)
+  const shown = sessions.length > room ? sessions.slice(0, Math.max(0, room - 1)) : sessions
+  for (const s of shown) {
+    const parts = cols.map(col => {
+      switch (col.key) {
+        case 'pid': return cell(s.pid, col.width)
+        case 'started': return cell(when(s.start, now), col.width)
+        case 'project': return cell(shortPath(s.cwd, home), col.width)
+        case 'rss': return cell(size(s.rss), col.width, true)
+        case 'bar': return c('cyan', meter(s.rss / maxRss, col.width))
+        case 'procs': return cell(s.children == null ? '-' : s.children, col.width, true)
+        case 'ports': return cell(s.ports.map(p => `:${p.port}`).join(' ') || '-', col.width)
+      }
+      return ''
+    })
+    lines.push(parts.join('  ').trimEnd())
+  }
+  if (shown.length < sessions.length) lines.push(c('dim', fit(`... ${sessions.length - shown.length} more`, width)))
+  if (!sessions.length) lines.push(c('dim', 'no Claude sessions found'))
+  lines.push('')
+
+  // slots and queue
+  const queue = st.queue || []
+  lines.push(c('bold', fit(`HEAVY JOBS  ${st.slots.length} running, ${queue.length} waiting`, width)))
+  for (const s of st.slots) {
+    lines.push(fit(`${cell(s.slot, 7)} ${cell(`${s.gb} GB`, 6)} ${cell(s.pid, 7)} ${cell(`${Math.round((now - s.at) / 60000)} min`, 7)} ${s.label}`, width))
+  }
+  queue.forEach((q, i) => {
+    lines.push(c('yellow', fit(`${cell(`wait #${i + 1}`, 7)} ${cell(`${q.gb} GB`, 6)} ${cell(q.pid, 7)} ${cell(`${Math.round((now - q.at) / 60000)} min`, 7)} ${q.label}  (${q.reason})`, width)))
+  })
+  if (!slotRows) lines.push(c('dim', 'none'))
+  lines.push('')
+
+  // recent blocks
+  lines.push(c('bold', 'RECENT BLOCKS'))
+  if (!events.length) lines.push(c('dim', 'none recorded'))
+  for (const e of events.slice().reverse()) {
+    const t = new Date(e.time)
+    const hm = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}`
+    lines.push(fit(`${hm}  ${cell(e.guard, 14)} ${cell(e.rule || '', 14)} ${cell(shortPath(e.project, home), 18)} ${e.command || ''}`, width))
+  }
+  return lines.slice(0, Math.max(1, height))
+}
+
+// The process scan in a worker thread, so the screen and keys never wait for it.
+function workerScanner() {
+  const { Worker } = require('worker_threads')
+  let worker = null
+  let pending = null
+  const start = () => {
+    worker = new Worker(path.join(__dirname, 'top-worker.js'))
+    worker.unref()
+    worker.on('message', msg => {
+      const p = pending
+      pending = null
+      if (p) (msg.ok ? p.resolve(msg) : p.reject(Object.assign(new Error(msg.error), { ms: msg.ms })))
+    })
+    worker.on('error', e => {
+      const p = pending
+      pending = null
+      worker = null
+      if (p) p.reject(e)
+    })
+  }
+  return {
+    scan() {
+      if (!worker) start()
+      return new Promise((resolve, reject) => {
+        pending = { resolve, reject }
+        worker.postMessage('scan')
+      })
+    },
+    close() {
+      if (worker) worker.terminate()
+      worker = null
+    },
+  }
+}
+
+// Live loop. Resolves when the user quits. Every dependency can be replaced for tests.
+function live({
+  stdin = process.stdin, stdout = process.stdout, env = process.env, interval = defaultInterval(),
+  scanner = workerScanner(), events = () => tailEvents(stateDir(), 5), proc = process,
+} = {}) {
+  const color = useColor(stdout, env)
+  const view = { st: null, scanning: false, lastScanMs: null, interval, tick: 0, events: [], error: null }
+  let timer = null
+  let clock = null
+  let closed = false
+  let again = false
+  let resolveDone
+  const done = new Promise(r => (resolveDone = r))
+
+  const draw = () => {
+    if (closed) return
+    view.now = Date.now()
+    const lines = frame(view, { width: stdout.columns || 80, height: stdout.rows || 24, color })
+    stdout.write(HOME + lines.map(l => l + CLEAR_EOL).join('\r\n') + CLEAR_EOS)
+  }
+
+  const refresh = () => {
+    if (closed) return
+    if (view.scanning) { again = true; return }
+    view.scanning = true
+    draw()
+    scanner.scan().then(msg => {
+      view.st = msg.st
+      view.lastScanMs = msg.ms
+      view.error = null
+    }, e => {
+      view.error = e.message
+    }).then(() => {
+      view.scanning = false
+      try { view.events = events() } catch { view.events = [] }
+      draw()
+      if (again) {
+        again = false
+        refresh()
+      }
+    })
+  }
+
+  const cleanup = () => {
+    if (closed) return
+    closed = true
+    clearInterval(timer)
+    clearInterval(clock)
+    try { scanner.close() } catch {}
+    stdin.removeListener('data', onKey)
+    stdout.removeListener('resize', draw)
+    try { if (stdin.isTTY && stdin.setRawMode) stdin.setRawMode(false) } catch {}
+    try { stdin.pause() } catch {}
+    stdout.write(SHOW + ALT_OFF)
+    for (const [sig, fn] of signals) proc.removeListener(sig, fn)
+    proc.removeListener('exit', cleanup)
+    resolveDone()
+  }
+
+  const onKey = data => {
+    const s = String(data)
+    if (s === 'q' || s === 'Q' || s === '\x03' || s === '\x1b' || s === '\x04') cleanup()
+    else if (s === 'r' || s === 'R') refresh()
+  }
+
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'].map(sig => [sig, () => { cleanup(); proc.exit(130) }])
+  for (const [sig, fn] of signals) proc.on(sig, fn)
+  proc.on('exit', cleanup)
+
+  stdout.write(ALT_ON + HIDE + `${ESC}2J`)
+  try { if (stdin.isTTY && stdin.setRawMode) stdin.setRawMode(true) } catch {}
+  stdin.setEncoding && stdin.setEncoding('utf8')
+  stdin.on('data', onKey)
+  stdin.resume()
+  stdout.on('resize', draw)
+  timer = setInterval(refresh, interval)
+  clock = setInterval(() => {
+    view.tick++
+    draw()
+  }, 1000)
+  refresh()
+  return done
+}
+
+function snapshot({ stdout = process.stdout, env = process.env } = {}) {
+  const { collect } = require('./status')
+  const started = Date.now()
+  const st = collect()
+  const view = { st, scanning: false, lastScanMs: Date.now() - started, interval: defaultInterval(), events: tailEvents(stateDir(), 5) }
+  stdout.write(frame(view, { width: stdout.columns || 100, height: Infinity, color: useColor(stdout, env) }).join('\n') + '\n')
+}
+
+function main(args, { stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
+  if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
+  if (rejectArgs('top', args, { flags: ['once'], valued: ['interval'] }, process.stderr, USAGE)) return
+  if (args.includes('--once') || !stdout.isTTY || !stdin.isTTY) return snapshot({ stdout, env })
+  const sec = Number(option(args, 'interval'))
+  const interval = sec >= 0.5 ? sec * 1000 : defaultInterval()
+  return live({ stdin, stdout, env, interval }).then(() => process.exit(0))
+}
+
+module.exports = { main, frame, layout, live, snapshot, workerScanner, defaultInterval, ALT_ON, ALT_OFF, SHOW }

package/src/wait-guard.js

@@ -0,0 +1,263 @@
+'use strict'
+const { runHook, setting, blocked, ASK_USER } = require('./hook')
+const shell = require('./shell')
+
+const DEFAULT_TOOL_TIMEOUT_S = 120
+
+// Shell, PowerShell and cmd.exe waits in seconds: sleep 300, Start-Sleep 300, timeout /t 300,
+// ping -n 301 127.0.0.1, [Threading.Thread]::Sleep(300000).
+function sleeps(cmd) {
+  const out = []
+  for (const m of cmd.matchAll(/(?:^|[\s;&|({])sleep\s+(?:(\d+(?:\.\d+)?)([smhd]?)\b|(inf(?:inity)?)\b)/g)) {
+    if (m[3]) { out.push(Infinity); continue }
+    const n = parseFloat(m[1])
+    out.push(n * ({ m: 60, h: 3600, d: 86400 }[m[2]] || 1))
+  }
+  for (const m of cmd.matchAll(/Start-Sleep\s+(?:(-s(?:econds)?|-m(?:illiseconds)?)\s+)?(\d+(?:\.\d+)?)/gi)) {
+    const n = parseFloat(m[2])
+    out.push(m[1] && /^-m/i.test(m[1]) ? n / 1000 : n)
+  }
+  for (const m of cmd.matchAll(/(?:^|[\s;&|({])timeout(?:\.exe)?\s+\/t\s+(-?\d+)/gi)) {
+    out.push(Number(m[1]) < 0 ? Infinity : Number(m[1]))
+  }
+  for (const m of cmd.matchAll(/\[(?:System\.)?Threading\.Thread\]::Sleep\(\s*(\d+)\s*\)/gi)) out.push(Number(m[1]) / 1000)
+  for (const m of cmd.matchAll(/(?:^|[\s;&|({])ping(?:\.exe)?\b([^\n;&|)]*)/gi)) {
+    const w = pingWait(m[1])
+    if (w) out.push(w)
+  }
+  return out
+}
+
+// ping -n 301 waits 300 s on Windows, ping -c 300 -i 1 about 300 s elsewhere, ping -t forever.
+function pingWait(args) {
+  if (/(?:^|\s)-t\b/.test(args) && process.platform === 'win32') return Infinity
+  const n = /(?:^|\s)-n\s+(\d+)(?![.\d])/.exec(args)
+  if (n) return Math.max(0, Number(n[1]) - 1)
+  const c = /(?:^|\s)-c\s*(\d+)/.exec(args)
+  const i = /(?:^|\s)-i\s*(\d+(?:\.\d+)?)/.exec(args)
+  if (c) return Math.max(0, Number(c[1]) - 1) * (i ? Number(i[1]) : 1)
+  const deadline = /(?:^|\s)-w\s*(\d+)/.exec(args)
+  if (deadline && process.platform !== 'win32') return Number(deadline[1])
+  return process.platform === 'win32' ? 3 : Infinity
+}
+
+// Commands that follow a log or a stream until they are stopped.
+function follows(argv) {
+  const b = shell.bin(argv[0])
+  const rest = argv.slice(1)
+  if (b === 'tail') return rest.some(a => /^-[a-zA-Z0-9]*[fF]/.test(a) || a === '--follow' || a.startsWith('--follow='))
+  if (/^(?:get-content|gc|cat|type)$/i.test(argv[0])) return rest.some(a => /^-wait$/i.test(a))
+  if (b === 'journalctl') return rest.some(a => /^-[a-zA-Z]*f/.test(a) || a === '--follow')
+  if (/^(?:docker|podman|kubectl|oc|docker-compose)$/.test(b) && rest.includes('logs')) return rest.some(a => a === '-f' || a === '--follow')
+  return false
+}
+
+// A loop inside an interpreter's code: Infinity for while loops, the count for range(N),
+// N.times or for (i = 0; i < N; ...), and 1 for no loop.
+function codeLoops(code) {
+  if (/\bwhile\b|\bloop\s+do\b|\bfor\s*\(\s*;\s*;|\bsetInterval\s*\(/.test(code)) return Infinity
+  let best = 1
+  for (const m of code.matchAll(/\brange\(\s*(?:(\d+)\s*,\s*)?(\d+)\s*\)/g)) best = Math.max(best, Number(m[2]) - Number(m[1] || 0))
+  for (const m of code.matchAll(/\b(\d+)\.times\b/g)) best = Math.max(best, Number(m[1]))
+  for (const m of code.matchAll(/\bfor\s*\([^;)]{0,80};\s*\w+\s*<=?\s*(\d+)/g)) best = Math.max(best, Number(m[1]))
+  return best
+}
+
+// Worst-case wait in seconds of python -c, node -e, ruby -e, perl -e or php -r code:
+// sleep(300), time.sleep(300), sleep 300, setTimeout(f, 300000).
+function codeWait(code) {
+  const s = []
+  for (const m of code.matchAll(/\bsleep\s*\(?\s*(\d+(?:\.\d+)?)\s*\)?/g)) s.push(Number(m[1]))
+  for (const m of code.matchAll(/\bsetTimeout\s*\(([^;]{0,300}?),\s*(\d+(?:\.\d+)?)\s*\)/g)) s.push(Number(m[2]) / 1000)
+  if (!s.length) return 0
+  const loops = codeLoops(code)
+  return loops > 1 ? loops * s.reduce((a, b) => Math.max(a, b), 0) : s.reduce((a, b) => a + b, 0)
+}
+
+const INTERPRETER = /^(?:python[\d.]*|py|pythonw|node|deno|bun|ruby|perl|php)$/
+const INTERPRETER_HEREDOC = /(?:^|[\s;&|(])(?:python[\d.]*|py|node|deno|bun|ruby|perl|php)(?:\.exe)?(?:\s+-)?\s*$/
+const CODE_FLAG = { python: /^-c$/, node: /^(?:-e|--eval|-p|--print)$/, ruby: /^-e$/, perl: /^-[Ee]$/, php: /^-r$/ }
+
+function codeOf(argv) {
+  const b = shell.bin(argv[0])
+  if (!INTERPRETER.test(b)) return null
+  const kind = /^py/.test(b) ? 'python' : /^(?:node|deno|bun)$/.test(b) ? 'node' : b
+  if (/^(?:deno|bun)$/.test(b) && argv[1] === 'eval') return argv[2] || null
+  const i = argv.findIndex((a, k) => k > 0 && CODE_FLAG[kind].test(a))
+  return i > 0 ? argv[i + 1] || null : null
+}
+
+// Inert commands only print or search text: echo "sleep 600", git log -S "sleep 300".
+const INERT = /^(?:echo|printf|git|grep|egrep|rg|write-host|write-output|select-string|sls)$/i
+const BACKGROUND = /^(?:start-job|sajb|start-threadjob)$/i
+
+// Blanks out inert commands, keeping every offset, and collects interpreter code waits.
+function scan(text, mode) {
+  const { cmds } = shell.lex(text, mode)
+  const cut = []
+  const code = []
+  let follow = false
+  for (const c of cmds) {
+    const s = shell.strip(text, c.words, mode)
+    if (!s.argv.length) continue
+    const argv = s.argv.map(w => w.v)
+    // inert commands, and PowerShell jobs, which run in the background like `&`
+    // and `docker exec -d` or `docker run -d`, which return as soon as the container starts the command
+    const detached = s.remote && argv.some(v => v === '-d' || v === '--detach')
+    if (INERT.test(shell.bin(argv[0])) || BACKGROUND.test(argv[0]) || detached) { cut.push([s.argv[0].s, c.e]); continue }
+    const src = codeOf(argv)
+    if (src) code.push(codeWait(src))
+    if (follows(argv)) follow = true
+  }
+  if (!cut.length) return { text, code, follow }
+  cut.sort((a, b) => a[0] - b[0])
+  let out = ''
+  let last = 0
+  for (const [s, e] of cut) {
+    if (e <= last) continue
+    const from = Math.max(s, last)
+    out += text.slice(last, from) + ' '.repeat(e - from)
+    last = e
+  }
+  return { text: out + text.slice(last), code, follow }
+}
+
+// Upper bound on iterations, or Infinity when the loop has no fixed count.
+function loopCount(cmd) {
+  if (/\b(until|while)\b/i.test(cmd)) return Infinity
+  let best = null
+  const take = n => (best = best === null ? n : Math.max(best, n))
+  for (const m of cmd.matchAll(/\bseq\s+(?:(\d+)\s+)?(?:(\d+)\s+)?(\d+)/g)) {
+    const nums = [m[1], m[2], m[3]].filter(Boolean).map(Number)
+    if (nums.length === 1) take(nums[0])
+    else if (nums.length === 2) take(nums[1] - nums[0] + 1)
+    else take(Math.floor((nums[2] - nums[0]) / nums[1]) + 1)
+  }
+  for (const m of cmd.matchAll(/\{(\d+)\.\.(\d+)\}/g)) take(Number(m[2]) - Number(m[1]) + 1)
+  // for x in a b c; do: the list runs to the next `;`. A `for` inside a list already read is
+  // skipped, so the text is read once however many `for`s it holds.
+  let listEnd = -1
+  for (const m of cmd.matchAll(/\bfor\s+\w+\s+in\s+/g)) {
+    const from = m.index + m[0].length
+    if (from <= listEnd) continue
+    listEnd = cmd.indexOf(';', from)
+    if (listEnd < 0) break
+    const list = cmd.slice(from, listEnd)
+    if (!/[$`(]/.test(list) && /^;\s*do\b/.test(cmd.slice(listEnd, listEnd + 16))) take(list.trim().split(/\s+/).length)
+  }
+  // bounded repeat: an unbounded [^;]* rescans to the end of the text from every `for (`
+  for (const m of cmd.matchAll(/\bfor\s*\(\(?[^;]{0,200};\s*\$?\w+\s*(?:<=?|-lt|-le)\s*(\d+)/gi)) take(Number(m[1]))
+  for (const m of cmd.matchAll(/\b(\d+)\.\.(\d+)\b/g)) take(Number(m[2]) - Number(m[1]) + 1)
+  return best === null ? Infinity : best
+}
+
+// for/while/until ... do, PowerShell loops and ForEach-Object. Two plain searches instead of
+// /\b(for|while|until)\b[\s\S]*?\bdo\b/, which rescans to the end from every unmatched `for`.
+function hasLoop(cmd) {
+  const head = /\b(?:for|while|until)\b/.exec(cmd)
+  return (head && /\bdo\b/.test(cmd.slice(head.index))) ||
+    /\b(while|for|foreach|do)\s*[({]/i.test(cmd) ||
+    /ForEach-Object|\|\s*%\s*\{/i.test(cmd)
+}
+
+const QUOTED = /"[^"]*"|'[^']*'/g
+
+const OPENERS = new Set(['do', 'if', 'case'])
+const CLOSERS = new Set(['done', 'fi', 'esac'])
+
+// Splits a shell line into top-level lists, each with the operator that ends it
+// (';', '\n', '&' or ''). && and || stay inside a list, as in bash, where `a && b &`
+// backgrounds both. Quotes, loops, groups and subshells are kept whole.
+function topLevelLists(cmd) {
+  const out = []
+  let depth = 0
+  let start = 0
+  let quote = null
+  const push = (end, op) => {
+    out.push({ text: cmd.slice(start, end), op })
+    start = end + op.length
+  }
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i]
+    if (quote) {
+      if (c === quote) quote = null
+      else if (c === '\\' && quote === '"') i++
+      continue
+    }
+    if (c === '\\') { i++; continue }
+    if (c === '"' || c === "'") { quote = c; continue }
+    if (c === '(' || c === '{') { depth++; continue }
+    if (c === ')' || c === '}') { depth = Math.max(0, depth - 1); continue }
+    if (/[a-z]/i.test(c) && (i === 0 || /[\s;&|]/.test(cmd[i - 1]))) {
+      const word = /^[\w.-]+/.exec(cmd.slice(i, i + 64))[0]
+      if (OPENERS.has(word)) depth++
+      else if (CLOSERS.has(word)) depth = Math.max(0, depth - 1)
+      i += word.length - 1
+      continue
+    }
+    if (depth) continue
+    if (c === ';' || c === '\n') push(i, c)
+    else if (c === '&') {
+      const prev = cmd[i - 1]
+      const next = cmd[i + 1]
+      // &&, >&, &>, |&, 2>&1 are not background operators
+      if (next === '&') { i++; continue }
+      if (prev === '>' || prev === '|' || prev === '<' || next === '>') continue
+      push(i, '&')
+    }
+  }
+  if (start < cmd.length) out.push({ text: cmd.slice(start), op: '' })
+  return out
+}
+
+// A list ending in a single & runs as a background job: the tool call returns without waiting
+// for it, so its sleeps cost nothing. A later `wait` brings them back into the foreground.
+function dropBackgrounded(cmd) {
+  const lists = topLevelLists(cmd)
+  if (!lists.some(l => l.op === '&')) return cmd
+  if (lists.some(l => l.op !== '&' && /^\s*wait\b/.test(l.text))) return cmd
+  return lists.filter(l => l.op !== '&').map(l => l.text).join('\n')
+}
+
+// Worst-case wait in seconds, capped by the tool timeout. Returns null when within the limit.
+function judge(cmd, timeoutMs, maxSec = 180, mode = 'sh') {
+  const opened = shell.unwrap(shell.prepare(String(cmd || ''), mode), mode, 0, { remote: true })
+  const { text, code, follow } = scan(dropBackgrounded(opened), mode)
+  // python3 - <<'EOF' ... EOF: the body is the interpreter's code
+  if (opened.includes('<<')) {
+    for (const d of shell.heredocs(opened, prefix => INTERPRETER_HEREDOC.test(prefix))) code.push(codeWait(d.body))
+  }
+  // Quoted text is an argument, not shell code: a `for (` inside node -e "..." is not a loop.
+  const bare = text.replace(QUOTED, '_')
+  const s = sleeps(bare).concat(code.filter(n => n > 0))
+  if (follow) s.push(Infinity)
+  if (!s.length) return null
+  const wrapped = bare.match(/\b(?:g?timeout)\s+(?:-\w+\s+)*(\d+)s?\b/)
+  if (wrapped && Number(wrapped[1]) <= maxSec) return null
+  const cap = Number(timeoutMs) > 0 ? Number(timeoutMs) / 1000 : DEFAULT_TOOL_TIMEOUT_S
+  const loop = hasLoop(bare)
+  const worst = loop ? loopCount(bare) * s.reduce((a, b) => Math.max(a, b), 0) : s.reduce((a, b) => a + b, 0)
+  const est = Math.min(worst, cap)
+  return est > maxSec ? { est, maxSec, rule: follow && !loop ? 'follow' : loop ? 'poll-loop' : 'long-sleep' } : null
+}
+
+function message({ est, maxSec }) {
+  return `[bulkhead] wait-guard: this command can sit in the foreground for about ${Math.round(est)}s (limit ${maxSec}s).\n` +
+    'A foreground wait holds the session: it cannot answer the user or do anything else until the command returns. ' +
+    'The prompt cache also expires after about 5 minutes without a request, so the request after a long wait writes the whole context to the cache again instead of reading it.\n' +
+    'Run the same loop with run_in_background: true and end your turn; you are notified once when it exits. For example:\n' +
+    '  until [ -f out/DONE ]; do sleep 15; done; tail -20 out/log.txt\n' +
+    'For a one-off check, skip the sleep and read the output file now.'
+}
+
+if (require.main === module) {
+  runHook('wait-guard', input => {
+    const ti = input.tool_input || {}
+    if (ti.run_in_background || typeof ti.command !== 'string') return
+    const verdict = judge(ti.command, ti.timeout, setting('waitGuard.limitSeconds', 180), shell.modeFor(input))
+    if (!verdict) return
+    return blocked('wait-guard', verdict.rule, input, `${message(verdict)}\n${ASK_USER}`)
+  })
+}
+
+module.exports = { judge, message, topLevelLists, dropBackgrounded }