claude-bulkhead 0.2.2 → 0.3.0

package/src/processes.js

@@ -3,6 +3,12 @@ const fs = require('fs')
 const path = require('path')
 const { execFileSync } = require('child_process')
 
+// How long a process read may take. Inside a hook a slow read fails open, so it is kept short;
+// the CLI commands wait longer for a full answer.
+function readTimeout(cliMs, hookMs, env = process.env) {
+  return env.BULKHEAD_IN_HOOK === '1' ? hookMs : cliMs
+}
+
 // Every reader returns { procs: [{ pid, ppid, name, cmd, start, rss, claudePid }], listening: Set<pid>,
 // ports: [{ port, pid }] }. start is milliseconds since the epoch, rss is bytes, and claudePid is null
 // when the environment is unreadable.
@@ -34,7 +40,7 @@ function parseWindows(json) {
 
 function readWindows(run = execFileSync) {
   const out = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_QUERY],
-    { encoding: 'utf8', windowsHide: true, timeout: 60000, maxBuffer: 64 * 1024 * 1024 })
+    { encoding: 'utf8', windowsHide: true, timeout: readTimeout(60000, 8000), maxBuffer: 64 * 1024 * 1024 })
   return parseWindows(out)
 }
 
@@ -57,6 +63,11 @@ function parseNetTcp(text) {
   return inodes
 }
 
+// BULKHEAD_KEEP=1 in a process's environment marks something started on purpose to outlive its
+// session (see orphan-reaper). Children inherit it, so a marked server's helpers are marked too.
+const KEEP_VALUE = /^(?:1|true|yes)$/i
+const isKeepValue = v => KEEP_VALUE.test(String(v || '').trim())
+
 function envValue(environ, key) {
   for (const kv of environ.split('\0')) if (kv.startsWith(key + '=')) return kv.slice(key.length + 1)
   return null
@@ -68,11 +79,11 @@ const realFs = {
   link: p => fs.readlinkSync(p),
 }
 
-function readLinux(io = realFs, clockTicks = 100, pageSize = 4096) {
+function readLinux(io = realFs, clockTicks = 100, pageSize = 4096, { withPorts = true } = {}) {
   const bootMs = Number(io.read('/proc/stat').match(/^btime (\d+)/m)[1]) * 1000
   const tryRead = p => { try { return io.read(p) } catch { return null } }
   const listenInodes = new Map()
-  for (const f of ['/proc/net/tcp', '/proc/net/tcp6']) {
+  for (const f of withPorts ? ['/proc/net/tcp', '/proc/net/tcp6'] : []) {
     const t = tryRead(f)
     if (t) for (const [inode, port] of parseNetTcp(t)) listenInodes.set(inode, port)
   }
@@ -94,6 +105,7 @@ function readLinux(io = realFs, clockTicks = 100, pageSize = 4096) {
       pid, ppid: s.ppid, name: s.name, cmd, start: bootMs + (s.startTicks / clockTicks) * 1000,
       rss: s.rssPages * pageSize, claudePid: claudePid || null,
     })
+    if (environ && isKeepValue(envValue(environ, 'BULKHEAD_KEEP'))) procs[procs.length - 1].keep = true
     if (!listenInodes.size) continue
     let fds = []
     try { fds = io.list(`/proc/${entry}/fd`) } catch {}
@@ -150,8 +162,18 @@ function parsePsEnv(text) {
   return out
 }
 
-function readMac(run = execFileSync, { withEnv = false } = {}) {
-  const opts = { encoding: 'utf8', timeout: 15000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } }
+// The PIDs whose `ps -E` line carries BULKHEAD_KEEP=1 as a whole word.
+function parsePsKeep(text) {
+  const out = new Set()
+  for (const line of text.split('\n')) {
+    const m = /^\s*(\d+)\s.*\sBULKHEAD_KEEP=(\w+)(?=\s|$)/.exec(line)
+    if (m && isKeepValue(m[2])) out.add(Number(m[1]))
+  }
+  return out
+}
+
+function readMac(run = execFileSync, { withEnv = false, withPorts = true } = {}) {
+  const opts = { encoding: 'utf8', timeout: readTimeout(15000, 4000), maxBuffer: 64 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } }
   const names = new Map()
   for (const line of run('ps', ['-axo', 'pid=,ucomm='], opts).split('\n')) {
     const m = /^\s*(\d+)\s+(.*)$/.exec(line)
@@ -160,22 +182,32 @@ function readMac(run = execFileSync, { withEnv = false } = {}) {
   const procs = parsePs(run('ps', ['-axww', '-o', 'pid=,ppid=,rss=,lstart=,args='], opts), names)
   if (withEnv) {
     let env = new Map()
-    try { env = parsePsEnv(run('ps', ['-axwwE', '-o', 'pid=,command='], opts)) } catch {}
-    for (const p of procs) p.claudePid = env.get(p.pid) || null
+    let keep = new Set()
+    try {
+      const text = run('ps', ['-axwwE', '-o', 'pid=,command='], opts)
+      env = parsePsEnv(text)
+      keep = parsePsKeep(text)
+    } catch {}
+    for (const p of procs) {
+      p.claudePid = env.get(p.pid) || null
+      if (keep.has(p.pid)) p.keep = true
+    }
   }
   let ports = []
   // lsof exits 1 when nothing is listening
-  try { ports = parseLsof(run('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn'], opts)) } catch (e) { ports = parseLsof(String(e.stdout || '')) }
+  if (withPorts) try { ports = parseLsof(run('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn'], opts)) } catch (e) { ports = parseLsof(String(e.stdout || '')) }
   return { procs, listening: new Set(ports.map(l => l.pid)), ports }
 }
 
-function readProcesses(platform = process.platform, { withEnv = false } = {}) {
+// withPorts: false (or ports: false) skips the listening sockets, the slowest part, for callers that need processes only.
+function readProcesses(platform = process.platform, { withEnv = false, withPorts, ports } = {}) {
+  const wantPorts = withPorts !== undefined ? withPorts : ports !== undefined ? ports : true
   if (platform === 'win32') return readWindows()
-  if (platform === 'linux') return readLinux()
-  if (platform === 'darwin') return readMac(execFileSync, { withEnv })
+  if (platform === 'linux') return readLinux(realFs, 100, 4096, { withPorts: wantPorts })
+  if (platform === 'darwin') return readMac(execFileSync, { withEnv, withPorts: wantPorts })
   return null
 }
 
 module.exports = {
-  readProcesses, parseWindows, readWindows, parseProcStat, parseNetTcp, readLinux, envValue, parsePs, parseLsof, readMac, parsePsEnv,
+  readProcesses, parseWindows, readWindows, parseProcStat, parseNetTcp, readLinux, envValue, parsePs, parseLsof, readMac, parsePsEnv, parsePsKeep, isKeepValue, readTimeout,
 }

package/src/scan-report.js

@@ -0,0 +1,166 @@
+'use strict'
+// Plain-words views of a scan result: the shareable summary, the matched part of a command, and
+// --explain. Everything here reads the same r.summary.rules the normal report prints.
+const REPO = 'https://github.com/dooly6276/claude-bulkhead'
+const DAY_MS = 86400000
+
+// What each rule means, in words a person who has never seen the guard names understands.
+// A group is one line of the share text; rules in the same group are added together.
+const GROUPS = [
+  { key: 'stage-all', match: (g, r) => g === 'checkout-guard' && r === 'stage-all', text: 'git add -A while another session was active in the same tree' },
+  { key: 'git', match: (g, r) => g === 'checkout-guard' && r.startsWith('git-'), text: 'checkout/merge/rebase/stash in a tree another session was using' },
+  { key: 'remove-dir', match: (g, r) => g === 'checkout-guard' && r === 'remove-session-dir', text: 'rm -rf or worktree remove on a folder another session was in' },
+  { key: 'kill', match: g => g === 'kill-guard', text: 'pkill/killall by name, which also stops other sessions\' processes' },
+  { key: 'wait', match: g => g === 'wait-guard', text: 'foreground sleeps and polling loops past the wait limit' },
+  { key: 'disk', match: g => g === 'disk-guard', text: 'whole-disk or parallel disk scans' },
+  { key: 'rm-root', match: (g, r) => g === 'basics' && r === 'rm-root', text: 'rm -rf at a root, home or system folder' },
+  { key: 'force-push', match: (g, r) => g === 'basics' && r === 'force-push-main', text: 'force-pushes to main' },
+  { key: 'discard', match: (g, r) => g === 'basics' && r === 'discard-changes', text: 'reset --hard or clean -f that lose uncommitted work' },
+  { key: 'author', match: (g, r) => g === 'basics' && r === 'agent-author', text: 'commits authored as Claude' },
+  { key: 'slots', match: g => g === 'memory-guard', text: 'hand-edited slot files' },
+]
+
+function describe(guard, rule) {
+  const g = GROUPS.find(x => x.match(guard, rule))
+  return g ? g.text : `${guard} ${rule}`
+}
+
+// Counts per group, largest first. Hits are commands, so the same command can count in two groups.
+function groups(r) {
+  const by = new Map()
+  for (const x of r.summary.rules) {
+    const g = GROUPS.find(y => y.match(x.guard, x.rule))
+    const key = g ? g.key : `${x.guard} ${x.rule}`
+    const cur = by.get(key) || { text: g ? g.text : `${x.guard} ${x.rule}`, count: 0 }
+    cur.count += x.count
+    by.set(key, cur)
+  }
+  return [...by.values()].sort((a, b) => b.count - a.count || a.text.localeCompare(b.text))
+}
+
+const num = n => n.toLocaleString('en-US')
+const plural = (n, word) => `${num(n)} ${word}${n === 1 ? '' : 's'}`
+
+function days(r) {
+  if (!r.first || !r.last) return 0
+  return Math.max(1, Math.ceil((r.last - r.first) / DAY_MS))
+}
+
+// The numbers the share text carries. Nothing else leaves this function: no paths, no commands.
+function shareSummary(r) {
+  return {
+    days: days(r),
+    sessions: r.sessions,
+    maxAtOnce: r.concurrency.max,
+    commandsHit: r.summary.commandsHit,
+    sessionsHit: r.summary.sessionsHit,
+    items: groups(r),
+  }
+}
+
+const SHOWN = 4
+
+function headline(s) {
+  const parts = []
+  if (s.days) parts.push(plural(s.days, 'day'))
+  parts.push(plural(s.sessions, 'session'))
+  if (s.maxAtOnce >= 2) parts.push(`up to ${s.maxAtOnce} at once`)
+  return parts.join(', ')
+}
+
+// Folds the groups beyond the shown ones into one "other" line.
+function shownItems(s) {
+  if (s.items.length <= SHOWN) return s.items
+  const rest = s.items.slice(SHOWN - 1)
+  return [...s.items.slice(0, SHOWN - 1), { text: `other risky commands (${plural(rest.length, 'kind')})`, count: rest.reduce((n, x) => n + x.count, 0) }]
+}
+
+function shareText(r) {
+  const s = shareSummary(r)
+  if (!r.commands) return 'bulkhead scan found no Claude Code shell commands to replay.'
+  const out = [`bulkhead scan, ${headline(s)}.`]
+  if (!s.items.length) out.push('Nothing in these sessions would have been stopped.')
+  else {
+    out.push(`It would have stopped ${plural(s.commandsHit, 'command')} in ${plural(s.sessionsHit, 'session')}:`)
+    for (const x of shownItems(s)) out.push(`  ${num(x.count)} ${x.text}`)
+  }
+  out.push(`(bulkhead scan, ${REPO.replace('https://', '')})`)
+  return out.join('\n')
+}
+
+function shareMarkdown(r) {
+  const s = shareSummary(r)
+  if (!r.commands) return 'bulkhead scan found no Claude Code shell commands to replay.'
+  const out = [`**bulkhead scan**, ${headline(s)}.`, '']
+  if (!s.items.length) out.push('Nothing in these sessions would have been stopped.')
+  else {
+    out.push('| Would have been stopped | Count |', '| --- | ---: |')
+    for (const x of shownItems(s)) out.push(`| ${x.text} | ${num(x.count)} |`)
+    out.push(`| **Total** | **${num(s.commandsHit)}** commands in ${plural(s.sessionsHit, 'session')} |`)
+  }
+  out.push('', `_bulkhead scan, [${REPO.replace('https://', '')}](${REPO})_`)
+  return out.join('\n')
+}
+
+// ---------------------------------------------------------------------------------------------
+// The part of a command a rule matched. A best guess from the rule's name: the guards decide on a
+// parsed command, scan only has the text, so this finds the clause a person would point at.
+
+// One shell clause: up to ; & | or a newline, but `2>&1` stays inside it.
+const CLAUSE = '(?:[^\\n;&|]|(?<=>)&)*'
+const MATCHERS = {
+  'kill-guard': /\b(?:pkill|killall|Stop-Process|taskkill|wmic|Get-Process|xargs\s+kill|kill)\b[^\n;&|]*/,
+  'wait-guard': /\b(?:sleep|Start-Sleep|timeout|Wait-Process|tail\s+-\w*f)\b[^\n;&|]*/i,
+  'disk-guard': /\b(?:du|ncdu|dust|find|tree|xargs|parallel|ForEach-Object|Get-ChildItem|dir|ls\s+-\w*R)\b[^\n;&|]*/,
+  'memory-guard': /\S*slots?\S*/,
+  'basics:rm-root': /\brm\s[^\n;&|]*/,
+  'basics:force-push-main': /\bgit\s[^\n;&|]*?\bpush\b[^\n;&|]*/,
+  'basics:discard-changes': /\bgit\s[^\n;&|]*?\b(?:reset|clean|checkout|restore)\b[^\n;&|]*/,
+  'basics:agent-author': /--author\S*(?:\s*=?\s*(?:"[^"]*"|'[^']*'|\S+))?|git\s[^\n;&|]*user\.\w+[^\n;&|]*|GIT_(?:AUTHOR|COMMITTER)_\w+=\S+/,
+  'checkout-guard:stage-all': /\bgit\s[^\n;&|]*?\b(?:add|commit)\b[^\n;&|]*/,
+  'checkout-guard:remove-session-dir': /\b(?:rm\s[^\n;&|]*|git\s[^\n;&|]*?worktree\s+remove[^\n;&|]*)/,
+}
+
+const widen = re => new RegExp(re.source.split('[^\\n;&|]*').join(CLAUSE), re.flags)
+
+function matcherFor(guard, rule) {
+  const given = MATCHERS[`${guard}:${rule}`]
+  if (given) return widen(given)
+  if (guard === 'checkout-guard' && rule.startsWith('git-')) return new RegExp(`\\bgit\\s[^\\n;&|]*?\\b${rule.slice(4).replace(/[^\w-]/g, '')}\\b${CLAUSE}`)
+  return MATCHERS[guard] ? widen(MATCHERS[guard]) : null
+}
+
+// { start, end } of the matched clause in the command, or null.
+function findMatch(guard, rule, command) {
+  const re = matcherFor(guard, rule)
+  const m = re ? re.exec(command) : null
+  if (!m || !m[0].trim()) return null
+  const text = m[0].replace(/\s+$/, '')
+  return { start: m.index, end: m.index + text.length }
+}
+
+// A command cut to `width` characters around the match. The match is wrapped by `mark`.
+function clipAround(command, match, width, mark) {
+  const flat = command.replace(/\s*\n\s*/g, ' ⏎ ')
+  // newline collapsing moves offsets, so find the match again in the flat text
+  let m = null
+  if (match) {
+    const raw = command.slice(match.start, match.end).replace(/\s*\n\s*/g, ' ⏎ ')
+    const at = flat.indexOf(raw)
+    if (at >= 0) m = { start: at, end: at + raw.length }
+  }
+  if (!m) return flat.length > width ? flat.slice(0, Math.max(0, width - 1)) + '…' : flat
+  if (flat.length <= width) return flat.slice(0, m.start) + mark(flat.slice(m.start, m.end)) + flat.slice(m.end)
+  const len = Math.min(m.end - m.start, Math.max(10, width - 8))
+  const room = Math.max(0, width - len)
+  let from = Math.max(0, m.start - Math.floor(room * 0.4))
+  if (from + width > flat.length) from = Math.max(0, flat.length - width)
+  const to = Math.min(flat.length, from + width)
+  const mEnd = Math.min(m.start + len, to)
+  const body = flat.slice(from, m.start) + mark(flat.slice(m.start, mEnd)) + flat.slice(mEnd, to)
+  return (from > 0 ? '…' : '') + body + (to < flat.length ? '…' : '')
+}
+
+const docsLink = guard => `${REPO}/blob/main/docs/guards/${guard}.md`
+
+module.exports = { GROUPS, describe, groups, shareSummary, shareText, shareMarkdown, findMatch, clipAround, docsLink, days, REPO }

package/src/scan.js

@@ -8,10 +8,13 @@ const os = require('os')
 const path = require('path')
 const { claudeDir } = require('./sessions')
 const { setting } = require('./hook')
-const { useColor, paint, shortPath, option, fit, table, bytes } = require('./cli-util')
+const { useColor, paint, shortPath, option, table, bytes } = require('./cli-util')
 const { parseSince } = require('./log-cli')
+const scanReport = require('./scan-report')
 
 const USAGE = `usage: bulkhead scan [30d|DATE] [--since 30d|DATE] [--path DIR|FILE] [--project TEXT] [-n N] [--json]
+       bulkhead scan [30d] --share [--markdown]
+       bulkhead scan [30d] --explain N
 
 Replays the shell commands in your Claude Code transcripts against bulkhead's guards and shows
 what they would have stopped. Read-only. Nothing leaves this machine.
@@ -19,7 +22,9 @@ what they would have stopped. Read-only. Nothing leaves this machine.
   --path P         transcripts to read (default: ~/.claude/projects)
   --project TEXT   only sessions whose folder contains TEXT
   -n N             examples to show per rule (default 3, 0 for none)
-  --json           machine-readable output`
+  --json           machine-readable output
+  --share          5 to 8 plain lines with counts only, to paste in a post or a chat (--markdown: a small table)
+  --explain N      one example in full: the command, the part that matched, the rule, and the guard's docs`
 
 // Minutes on either side of a command in which another session counts as active.
 const ACTIVE_WINDOW_MIN = 10
@@ -410,53 +415,110 @@ const RULE_NOTES = {
   'checkout-guard': 'another session was active in the same tree at that minute',
 }
 
+// Examples in the order the report prints them, numbered for --explain.
+function exampleList(r, n) {
+  const out = []
+  for (const x of r.summary.rules) for (const e of x.examples.slice(0, n)) out.push({ n: out.length + 1, rule: x, example: e })
+  return out
+}
+
+// Rules where at least half of the hits were already stopped by a hook or declined by the user.
+function mostlyStopped(rules) {
+  return rules.filter(x => x.hook + x.user > 0 && (x.hook + x.user) * 2 >= x.count)
+}
+
 function renderScan(r, { color = false, home = os.homedir(), examples = 3, width = 120 } = {}) {
   const out = []
   const b = s => paint(color, 'bold', s)
-  out.push(`${b('bulkhead scan')}  replaying your Claude Code sessions against the guards`)
-  out.push(`  read     ${plural(r.files, 'transcript')} (${bytes(r.bytes)}), ${plural(r.sessions, 'session')}, ${plural(r.commands, 'shell command')} in ${r.seconds.toFixed(1)}s`)
-  if (r.first) out.push(`  span     ${day(r.first)} .. ${day(r.last)}${r.sinceLabel ? `  (since ${r.sinceLabel})` : ''}`)
+  const s = r.summary
+  out.push(`${b('bulkhead scan')}  what your past Claude Code sessions would have run into`)
+  if (!r.commands) {
+    out.push('No shell commands found in these transcripts.')
+    return out.join('\n')
+  }
+  if (!s.rules.length) out.push(`Found nothing bulkhead would have stopped in ${plural(r.commands, 'shell command')} from ${plural(r.sessions, 'session')}.`)
+  else {
+    out.push(`Found ${b(plural(s.commandsHit, 'shell command'))} in ${s.sessionsHit.toLocaleString('en-US')} of your ${plural(r.sessions, 'session')} that bulkhead would have stopped.`)
+    const top = scanReport.groups(r).slice(0, 2).map(g => `${g.count.toLocaleString('en-US')} ${g.text}`)
+    out.push(`Most common: ${top.join('; ')}.`)
+  }
   if (r.concurrency.max >= 2) {
-    out.push(`  overlap  up to ${b(r.concurrency.max)} sessions running at once (${day(Date.parse(r.concurrency.at))}), ` +
-      `${plural(r.concurrency.overlapDays, 'day')} with two or more at once`)
+    out.push(`Up to ${b(r.concurrency.max)} Claude Code sessions ran at the same time (${day(Date.parse(r.concurrency.at))}); ` +
+      `on ${plural(r.concurrency.overlapDays, 'day')} two or more did.`)
   }
+  out.push(paint(color, 'dim', `  read ${plural(r.files, 'transcript')} (${bytes(r.bytes)}), ${plural(r.commands, 'shell command')} in ${r.seconds.toFixed(1)}s` +
+    (r.first ? `, ${day(r.first)} .. ${day(r.last)}${r.sinceLabel ? ` (since ${r.sinceLabel})` : ''}` : '')))
   out.push('')
-  if (!r.summary.rules.length) {
-    out.push(r.commands ? 'Nothing in these transcripts would have been stopped.' : 'No shell commands found.')
+  if (!s.rules.length) {
+    out.push('Nothing in these transcripts would have been stopped.')
     return out.join('\n')
   }
   const rows = [['GUARD', 'RULE', 'HITS', 'SESSIONS', 'STOPPED', 'LAST']]
-  for (const x of r.summary.rules) {
+  for (const x of s.rules) {
     const stopped = x.hook + x.user
     rows.push([x.guard, x.rule, String(x.count).padStart(4), String(x.sessions).padStart(8), stopped ? `${stopped}`.padStart(7) : '      -', x.last ? day(x.last) : ''])
   }
   const lines = table(rows)
   out.push(b(lines[0]), ...lines.slice(1))
+  out.push(paint(color, 'dim', 'STOPPED: hits a hook already stopped or you declined, as the transcript recorded them. "-" means none recorded: the command ran.'))
   if (examples > 0) {
     let lastGuard = null
-    for (const x of r.summary.rules) {
+    const mark = color ? t => paint(color, 'bold', t) : t => `[${t}]`
+    const numbered = exampleList(r, examples)
+    for (const x of s.rules) {
       out.push('')
       const note = x.guard !== lastGuard && RULE_NOTES[x.guard] ? paint(color, 'dim', `  ${RULE_NOTES[x.guard]}`) : ''
       lastGuard = x.guard
       out.push(`${paint(color, x.guard === 'checkout-guard' || x.guard === 'kill-guard' ? 'red' : 'yellow', `${x.guard}  ${x.rule}`)}  ${plural(x.count, 'time')} in ${plural(x.sessions, 'session')}${note}`)
-      for (const e of x.examples.slice(0, examples)) {
+      for (const { n, example: e } of numbered.filter(y => y.rule === x)) {
         const tag = e.outcome === 'hook' ? '  [stopped by a hook]' : e.outcome === 'user' ? '  [declined by you]' : ''
-        const meta = `${shortPath(e.cwd ? treeRoot(e.cwd) : '?', home)}  ${e.ts ? day(e.ts) : ''}${tag}`
+        const meta = `${shortPath(e.cwd ? treeRoot(e.cwd) : '?', home)}  ${e.ts ? day(e.ts) : ''}${tag}  #${n}`
         const room = Math.max(30, width - meta.length - 8)
-        out.push(`  $ ${fit(e.command.replace(/\s*\n\s*/g, ' ⏎ '), room)}  ${paint(color, 'gray', meta)}`)
+        out.push(`  $ ${scanReport.clipAround(e.command, scanReport.findMatch(x.guard, x.rule, e.command), room, mark)}  ${paint(color, 'gray', meta)}`)
       }
     }
+    if (!color) out.push('', paint(color, 'dim', 'The part of a command that matched is shown in [brackets].'))
   }
   out.push('')
-  const s = r.summary
   const already = s.rules.reduce((n, x) => n + x.hook + x.user, 0)
   out.push(b(`${plural(s.commandsHit, 'command')} in ${plural(s.sessionsHit, 'session')} would have been stopped by bulkhead.`) +
     (already ? ` ${already.toLocaleString('en-US')} of the hits were already stopped by a hook or declined by you.` : ''))
+  const mostly = mostlyStopped(s.rules)
+  if (mostly.length) {
+    const names = mostly.slice(0, 3).map(x => `${x.guard} ${x.rule} (${x.hook + x.user} of ${x.count})`).join(', ')
+    out.push(`Most hits of ${names} were already stopped by your own hooks or by you, so bulkhead adds less there than the count suggests.`)
+  }
   out.push(paint(color, 'dim', 'A hit means the command had the shape a guard blocks, not that damage was done. port-guard and the low-RAM check depend on'))
   out.push(paint(color, 'dim', 'what was running at that moment and are not replayed. checkout-guard is replayed from which sessions were active in the same folder.'))
+  out.push(paint(color, 'dim', 'Share these numbers: bulkhead scan --share'))
+  if (examples > 0) out.push(paint(color, 'dim', 'One example in full, with the matched part and the rule: bulkhead scan --explain 1'))
   return out.join('\n')
 }
 
+// One example in full: the whole command, what matched, the rule and where it is documented.
+function renderExplain(r, number, { examples = 3, home = os.homedir(), color = false } = {}) {
+  const list = exampleList(r, examples > 0 ? examples : 3)
+  const hit = list.find(y => y.n === number)
+  if (!hit) return `No example #${number}: this scan has ${list.length}. Examples are numbered in the report (#1 ...).`
+  const { rule: x, example: e } = hit
+  const match = scanReport.findMatch(x.guard, x.rule, e.command)
+  const mark = color ? t => paint(color, 'bold', t) : t => `[${t}]`
+  const full = e.command.length > 4000 ? e.command.slice(0, 4000) + '\n…' : e.command
+  const body = match && match.end <= full.length ? full.slice(0, match.start) + mark(full.slice(match.start, match.end)) + full.slice(match.end) : full
+  const outcome = e.outcome === 'hook' ? 'stopped by a hook at the time' : e.outcome === 'user' ? 'declined by you at the time' : 'it ran'
+  return [
+    `${paint(color, 'bold', `Example #${number}`)}  ${x.guard} ${x.rule}`,
+    `  when     ${e.ts ? day(e.ts) : '?'}   in ${shortPath(e.cwd ? treeRoot(e.cwd) || e.cwd : '?', home)}   (${outcome})`,
+    `  meaning  ${scanReport.describe(x.guard, x.rule)}`,
+    RULE_NOTES[x.guard] ? `  why      ${RULE_NOTES[x.guard]}` : null,
+    match ? `  matched  ${e.command.slice(match.start, match.end).replace(/\s*\n\s*/g, ' ⏎ ')}` : '  matched  (the whole command; scan could not narrow it down)',
+    `  docs     ${scanReport.docsLink(x.guard)}`,
+    '',
+    'The command (secret-looking values are masked):',
+    body.replace(/^/gm, '  '),
+  ].filter(l => l !== null).join('\n')
+}
+
 function toJson(r) {
   return {
     files: r.files,
@@ -531,8 +593,8 @@ async function scan({ dir = path.join(claudeDir(), 'projects'), since = null, pr
   }
 }
 
-const VALUE_FLAGS = ['since', 'path', 'project']
-const BOOL_FLAGS = ['json']
+const VALUE_FLAGS = ['since', 'path', 'project', 'explain']
+const BOOL_FLAGS = ['json', 'share', 'markdown']
 // The first bare argument that is not a flag's value: `bulkhead scan 30d`.
 function positionals(args) {
   const out = []
@@ -554,6 +616,11 @@ function checkArgs(args) {
     const name = a.startsWith('--') ? a.slice(2).split('=')[0] : null
     if (!name || ![...VALUE_FLAGS, ...BOOL_FLAGS].includes(name)) return `unknown option ${a}`
   }
+  if (args.includes('--markdown') && !args.includes('--share')) return '--markdown goes with --share'
+  const explain = option(args, 'explain')
+  if (explain !== undefined && !(Number.isInteger(Number(explain)) && Number(explain) >= 1)) return '--explain takes an example number, 1 or more'
+  const modes = ['json', 'share', 'explain'].filter(m => args.some(a => a === `--${m}` || a.startsWith(`--${m}=`)))
+  if (modes.length > 1) return `use one of --${modes.join(', --')}, not several`
   const pos = positionals(args)
   if (pos.length > 1) return `unexpected argument ${pos[1]}`
   if (pos.length && option(args, 'since') !== undefined) return `give the time span once: --since ${option(args, 'since')} or ${pos[0]}, not both`
@@ -598,7 +665,9 @@ async function main(args, { env = process.env, stdout = process.stdout, stderr =
   if (shown) stderr.write('\r\x1b[2K')
   r.sinceLabel = typeof sinceArg === 'string' ? sinceArg : null
   if (args.includes('--json')) return stdout.write(JSON.stringify(toJson(r), null, 2) + '\n')
+  if (args.includes('--share')) return stdout.write((args.includes('--markdown') ? scanReport.shareMarkdown(r) : scanReport.shareText(r)) + '\n')
+  if (option(args, 'explain') !== undefined) return stdout.write(renderExplain(r, Number(option(args, 'explain')), { examples: n, color: useColor(stdout, env) }) + '\n')
   stdout.write(renderScan(r, { color: useColor(stdout, env), examples: n, width: stdout.columns || 120 }) + '\n')
 }
 
-module.exports = { main, scan, timeSpan, replay, renderScan, toJson, mask, outcomeOf, sessionKey, findTranscripts, concurrency, USAGE }
+module.exports = { main, scan, timeSpan, replay, renderScan, renderExplain, exampleList, toJson, mask, outcomeOf, sessionKey, findTranscripts, concurrency, USAGE }