Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

30.3 KB
Raw Blame
import { spawnSync } from 'node:child_process'
import { lstatSync, readdirSync, readlinkSync, realpathSync } from 'node:fs'
import { homedir } from 'node:os'
import { isAbsolute, posix, resolve } from 'node:path'

/**
 * The shell guard of a Swarm agent's session (task #3596, inventory Table A #5; anh Dee 11-06: a rule that can be checked
 * runs as code, not as a line in the instructions). Every Swarm agent was told, in its skill and its project's rules, never
 * to stop processes by name, use sudo or install system-wide, write fixed names in /tmp, or remove a worktree a live process
 * uses; they still did (one wrote `> /tmp/instr_wren.txt` on 11-05). Shared machines run several accounts' agents at once,
 * so each of these breaks someone else's work: a `pkill -f node` stops every agent's servers, a fixed /tmp name can be read
 * or planted by any account, and a worktree removed under a live agent loses its work.
 *
 * This reads a command the way a shell splits it (quotes, `;` `&&` `||` `|`, `$(…)`, backticks, `sh -c '…'`, heredocs)
 * and refuses it with one line saying why and what to do instead. It is a guard for honest agents, not a sandbox: a
 * command built at run time (`$(echo pk)ill`) is not read. Plain text (a commit message, `grep pkill`, `echo sudo`) is
 * never taken for a command: only a word in a command's own place is.
 */

const PREFIX = 'Harness shell guard:'

export const GUARD_REASONS = {
  killByName: `${PREFIX} stop only processes you started, by the process id you recorded; never by name or pattern `
    + '(pkill, killall, kill $(pgrep …), taskkill /IM).',
  killAll: `${PREFIX} nonpositive kill targets can signal other agents' process groups or every process this account can reach; `
    + 'stop only processes you started, by the process id you recorded.',
  systemWide: `${PREFIX} no sudo and no system-wide installs on a shared machine; put the tools you need in your session folder.`,
  fixedTmp: `${PREFIX} a fixed name in /tmp can be read or planted by every account; make a folder with `
    + 'mktemp -d "${TMPDIR:-/tmp}/name.XXXXXX" and write inside it.',
  macMktemp: `${PREFIX} on a Mac, mktemp with no template ignores TMPDIR and writes to a folder every app of this account `
    + 'shares, outside your own; name one in your temporary folder: mktemp -d "${TMPDIR:-/tmp}/name.XXXXXX".',
  liveWorktree: (path: string, pid: number) => `${PREFIX} process ${pid} still works in a worktree in ${path}; never remove a `
    + 'worktree a live process uses.',
  worktreeUnknown: (path: string) => `${PREFIX} could not tell whether a live process uses the worktree ${path}, so it is not `
    + 'removed; stop what runs there first.',
}

/** What the guard knows of the machine: seams, so a spec reads none of the machine it runs on. */
export interface GuardFacts {
  /** The folder the command runs in. */
  cwd: string
  platform: NodeJS.Platform
  /** Whether [path] is a folder only this account can open (what `mktemp -d` makes). */
  privateFolder: (path: string) => boolean
  /** Whether [path] is a linked git worktree (its `.git` is a file). */
  linkedWorktree: (path: string) => boolean
  /** Every live process's working folder, or null when they cannot be read. */
  liveCwds: () => { pid: number; cwd: string }[] | null
  /** [path] with its links resolved; [path] itself when absent or when it cannot be. */
  realpath?: (path: string) => string
  /** The account's home, for `~` and `~/…`; left as written without it. */
  home?: string
  /** The names of the folders (not links) in [path], for a glob and for the worktrees a folder holds; none when unread. */
  entries?: (path: string) => string[]
}

/** One command in its own place: its words with quotes removed, and where its redirections write or read. */
interface Simple { words: string[]; targets: string[] }

/** The guard's answer for [command]: the reason it is refused, or null to let it run. */
export function shellRefusal(command: string, facts: GuardFacts): string | null {
  const commands = allCommands(command)
  if (commands.some(systemWide)) return GUARD_REASONS.systemWide
  if (killsByName(commands)) return GUARD_REASONS.killByName
  if (commands.some(killsAll)) return GUARD_REASONS.killAll
  if (commands.some((simple) => fixedTmp(simple, facts))) return GUARD_REASONS.fixedTmp
  if (facts.platform === 'darwin' && commands.some(mktempIgnoringTmpdir)) return GUARD_REASONS.macMktemp
  return liveWorktree(commands, facts)
}

/** The guard's answer for a file tool writing [path] (Claude Code's Write, Edit, MultiEdit and NotebookEdit). */
export function fileRefusal(path: string, facts: GuardFacts): string | null {
  return tmpPathRefused(resolveIn(facts.cwd, path, facts.platform), facts) ? GUARD_REASONS.fixedTmp : null
}

// ---------------------------------------------------------------------------------------------------------------------
// Reading a command

const MAX_DEPTH = 8

/** Every command in [text], in order, with those inside `$(…)`, backticks, `<(…)`, `sh -c '…'` and `eval`. */
function allCommands(text: string, depth = 0): Simple[] {
  if (depth > MAX_DEPTH) return []
  const nested: string[] = []
  const found: Simple[] = []
  for (const simple of split(text, nested)) {
    const words = programWords(simple.words)
    found.push({ words, targets: simple.targets })
    const script = scriptOf(words)
    if (script !== null) nested.push(script)
  }
  for (const inner of nested) found.push(...allCommands(inner, depth + 1))
  return found
}

/** The script a shell or `eval` runs from its words: `bash -lc '…'`, `sh -c "…"`, `pwsh -Command …`, `eval …`. */
function scriptOf(words: string[]): string | null {
  const program = programName(words[0])
  if (program === 'eval') return words.slice(1).join(' ')
  if (SHELLS.has(program)) {
    const flag = words.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/i.test(word))
    if (flag > 0 && words[flag + 1] !== undefined) return words[flag + 1]
  }
  if (POWERSHELLS.has(program)) {
    const flag = words.findIndex((word, index) => index > 0 && /^-(c|command)$/i.test(word))
    if (flag > 0) return words.slice(flag + 1).join(' ')
  }
  return null
}

const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'])
const POWERSHELLS = new Set(['pwsh', 'powershell'])

/** A program's name as matched: its last path part, lower case, without `.exe`. */
function programName(word: string | undefined): string {
  if (!word) return ''
  return (word.split(/[\\/]/).pop() ?? '').toLowerCase().replace(/\.exe$/, '')
}

/** Shell words that start a command but are not its program. */
const KEYWORDS = new Set(['!', '{', '}', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', 'time', 'function'])
/** Programs that run the rest of their words as a command, each with the options that take a value. */
const WRAPPERS: Record<string, { values: Set<string>; first?: 'duration' }> = {
  env: { values: new Set(['-u', '--unset', '-C', '--chdir', '-S', '--split-string']) },
  command: { values: new Set() },
  builtin: { values: new Set() },
  exec: { values: new Set(['-a']) },
  nohup: { values: new Set() },
  nice: { values: new Set(['-n', '--adjustment']) },
  timeout: { values: new Set(['-s', '--signal', '-k', '--kill-after']), first: 'duration' },
  xargs: { values: new Set(['-I', '-i', '-n', '-P', '-L', '-l', '-d', '-E', '-e', '-s', '-a', '--max-args', '--max-procs', '--delimiter', '--arg-file']) },
  stdbuf: { values: new Set(['-i', '-o', '-e']) },
  caffeinate: { values: new Set(['-t', '-w']) },
}

/** [words] from the program on: leading assignments, shell keywords and wrappers (`env X=1`, `xargs -n1`, `nohup`) go. */
function programWords(words: string[]): string[] {
  let at = 0
  for (;;) {
    while (at < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[at]) || KEYWORDS.has(words[at]))) at++
    const name = programName(words[at])
    const wrapper = WRAPPERS[name]
    if (!wrapper) return words.slice(at)
    at++
    let duration = wrapper.first === 'duration'
    while (at < words.length) {
      const word = words[at]
      if (word === '--') { at++; break }
      if (word.startsWith('-') && word.length > 1) { at += wrapper.values.has(word) ? 2 : 1; continue }
      if (name === 'env' && /^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) { at++; continue }
      if (duration) { duration = false; at++; continue }
      break
    }
  }
}

/**
 * The commands of [text] as a shell splits them. What `$(…)`, backticks and `<(…)` hold goes to [nested], to be read as
 * commands of their own; the word keeps its text. A heredoc's body is data, never commands (a commit message saying
 * "sudo" at a line's start is not a sudo). `#` starts a comment at a word's start.
 */
function split(text: string, nested: string[]): Simple[] {
  const out: Simple[] = []
  const variables = new Map<string, string>()
  let words: string[] = [], targets: string[] = []
  let word = '', inWord = false, redirect = false
  const heredocs: { delimiter: string; strip: boolean }[] = []
  let pendingHeredoc: { strip: boolean } | null = null

  const endWord = () => {
    if (!inWord) return
    if (pendingHeredoc) { heredocs.push({ delimiter: word, strip: pendingHeredoc.strip }); pendingHeredoc = null }
    else if (redirect) { targets.push(word); redirect = false }
    else {
      // Only leading shell assignments and export declarations set values; an echo argument never does.
      const assignment = word.includes('=') && /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(word)
      if (assignment && words.every((value) => value === 'export' || /^[A-Za-z_][A-Za-z0-9_]*=/.test(value))) {
        if (/[$`]/.test(assignment[2])) variables.delete(assignment[1])
        else variables.set(assignment[1], assignment[2])
      }
      words.push(word)
    }
    word = ''; inWord = false
  }
  const endCommand = () => {
    endWord()
    if (words.length || targets.length) out.push({ words, targets })
    words = []; targets = []; redirect = false
  }

  // Expand at the lexical position, so single quotes and escaped dollars remain literal and reassignments keep order.
  const variableAt = (at: number): { value: string; end: number } | null => {
    if (text[at] !== '$') return null
    const match = /^\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/.exec(text.slice(at))
    if (!match) return null
    const value = variables.get(match[1] ?? match[2])
    return value === undefined ? null : { value, end: at + match[0].length }
  }

  let i = 0
  while (i < text.length) {
    const c = text[i]
    if (c === '\n') {
      endCommand()
      i++
      // Skip each heredoc's body, line by line, up to its delimiter.
      for (const doc of heredocs.splice(0)) {
        while (i < text.length) {
          const end = text.indexOf('\n', i)
          const line = text.slice(i, end === -1 ? text.length : end)
          i = end === -1 ? text.length : end + 1
          if ((doc.strip ? line.replace(/^\t+/, '') : line) === doc.delimiter) break
        }
      }
      continue
    }
    if (c === ' ' || c === '\t') { endWord(); i++; continue }
    if (c === '#' && !inWord) { while (i < text.length && text[i] !== '\n') i++; continue }
    if (c === '\\') {
      if (text[i + 1] === '\n') { i += 2; continue }
      word += text[i + 1] ?? ''; inWord = true; i += 2; continue
    }
    if (c === "'") {
      const end = text.indexOf("'", i + 1)
      word += text.slice(i + 1, end === -1 ? text.length : end); inWord = true
      i = end === -1 ? text.length : end + 1
      continue
    }
    if (c === '"') {
      inWord = true; i++
      while (i < text.length && text[i] !== '"') {
        if (text[i] === '\\' && '"\\$`\n'.includes(text[i + 1] ?? '')) { word += text[i + 1]; i += 2; continue }
        const sub = substitution(text, i)
        if (sub) { nested.push(sub.inner); word += text.slice(i, sub.end); i = sub.end; continue }
        const variable = text[i] === '$' && variables.size ? variableAt(i) : null
        if (variable) { word += variable.value; i = variable.end; continue }
        word += text[i]; i++
      }
      i++
      continue
    }
    const variable = text[i] === '$' && variables.size ? variableAt(i) : null
    if (variable) { word += variable.value; inWord = true; i = variable.end; continue }
    const sub = substitution(text, i)
    if (sub) { nested.push(sub.inner); word += text.slice(i, sub.end); inWord = true; i = sub.end; continue }
    if ((c === '<' || c === '>') && text[i + 1] === '(') {
      const end = closing(text, i + 1)
      nested.push(text.slice(i + 2, end - 1)); word += text.slice(i, end); inWord = true; i = end
      continue
    }
    if (c === ';' || c === '&' || c === '|' || c === '(' || c === ')') {
      if (c === '&' && text[i + 1] === '>') { endWord(); i += text[i + 2] === '>' ? 3 : 2; redirect = true; continue }
      endCommand()
      i += (c === '&' && text[i + 1] === '&') || (c === '|' && (text[i + 1] === '|' || text[i + 1] === '&')) || (c === ';' && text[i + 1] === ';') ? 2 : 1
      continue
    }
    if (c === '<' || c === '>') {
      // A file descriptor before it (`2>`) is part of the redirection, not a word.
      if (inWord && /^\d+$/.test(word)) { word = ''; inWord = false } else endWord()
      if (c === '<' && text[i + 1] === '<' && text[i + 2] !== '<') {
        const strip = text[i + 2] === '-'
        i += strip ? 3 : 2
        pendingHeredoc = { strip }
        continue
      }
      let j = i + 1
      while (text[j] === '>' || text[j] === '<' || text[j] === '|') j++
      if (text[j] === '&') {
        // `>&2`, `2>&1`: to another descriptor, no file.
        j++
        while (/\d|-/.test(text[j] ?? '')) j++
        i = j
        continue
      }
      i = j
      redirect = true
      continue
    }
    word += c; inWord = true; i++
  }
  endCommand()
  return out
}

/** `$(…)` or `` `…` `` at [at]: what it holds and where it ends. */
function substitution(text: string, at: number): { inner: string; end: number } | null {
  if (text[at] === '$' && text[at + 1] === '(') {
    const end = closing(text, at + 1)
    return { inner: text.slice(at + 2, end - 1), end }
  }
  if (text[at] === '`') {
    const end = text.indexOf('`', at + 1)
    const stop = end === -1 ? text.length : end
    return { inner: text.slice(at + 1, stop), end: stop + 1 }
  }
  return null
}

/** Just past the `)` that closes the `(` at [open], skipping quotes and nested parentheses. */
function closing(text: string, open: number): number {
  let depth = 0
  for (let i = open; i < text.length; i++) {
    const c = text[i]
    if (c === '\\') { i++; continue }
    if (c === "'") { const end = text.indexOf("'", i + 1); i = end === -1 ? text.length : end; continue }
    if (c === '"') {
      i++
      while (i < text.length && text[i] !== '"') { if (text[i] === '\\') i++; i++ }
      continue
    }
    if (c === '(') depth++
    if (c === ')' && --depth === 0) return i + 1
  }
  return text.length
}

// ---------------------------------------------------------------------------------------------------------------------
// The rules

const lower = (words: string[]) => words.map((word) => word.toLowerCase())
/** The first word after the program that is not an option. */
const subcommand = (words: string[]) => words.slice(1).find((word) => !word.startsWith('-'))?.toLowerCase()

const ELEVATORS = new Set(['sudo', 'doas', 'su', 'pkexec', 'gsudo', 'runas'])
const NODE_MANAGERS = new Set(['npm', 'pnpm', 'bun'])
const NODE_CHANGES = new Set(['install', 'i', 'in', 'isntall', 'add', 'update', 'up', 'upgrade', 'uninstall', 'remove', 'rm', 'un', 'r', 'link', 'ln'])
const BREW_CHANGES = new Set(['install', 'reinstall', 'upgrade', 'uninstall', 'remove', 'rm', 'tap', 'untap', 'link', 'unlink'])
const SYSTEM_PACKAGES = new Set(['apt', 'apt-get', 'aptitude', 'dnf', 'yum', 'zypper', 'apk', 'snap', 'port', 'pkg', 'emerge'])
const PACKAGE_CHANGES = new Set(['install', 'reinstall', 'upgrade', 'remove', 'purge', 'add', 'del', 'erase', 'autoremove',
  'dist-upgrade', 'full-upgrade', 'uninstall', 'selfupdate', 'selfupgrade', 'refresh'])
const WINDOWS_PACKAGES = new Set(['winget', 'choco'])

/** sudo and its kin, or an install that writes for every account on the machine. */
function systemWide({ words }: Simple): boolean {
  const program = programName(words[0])
  const all = lower(words)
  if (ELEVATORS.has(program)) return true
  if (NODE_MANAGERS.has(program)) {
    const global = all.some((word) => word === '-g' || word === '--global' || word === '--location=global')
      || all.some((word, index) => word === '--location' && all[index + 1] === 'global')
    return global && NODE_CHANGES.has(subcommand(words) ?? '')
  }
  if (program === 'yarn') return subcommand(words) === 'global'
  if (program === 'brew') return BREW_CHANGES.has(subcommand(words) ?? '')
  if (SYSTEM_PACKAGES.has(program)) return PACKAGE_CHANGES.has(subcommand(words) ?? '')
  if (program === 'pacman') return words.slice(1).some((word) => /^-[A-Za-z]*[SRU]/.test(word) || /^--(sync|remove|upgrade)$/.test(word))
  if (program === 'pip' || program === 'pip3' || (/^python[\d.]*$/.test(program) && all.includes('pip'))) {
    return all.includes('install') && all.some((word) => word === '--break-system-packages' || word === '--system')
  }
  if (program === 'installer') return all.includes('-pkg')
  if (program === 'softwareupdate') return all.slice(1).some((word) => ['-i', '--install', '-a', '--all', '-r', '--recommended'].includes(word))
  if (WINDOWS_PACKAGES.has(program)) return ['install', 'upgrade', 'uninstall'].includes(subcommand(words) ?? '')
  if (program === 'msiexec') return all.slice(1).some((word) => /^[/-](i|x|package|uninstall)$/.test(word))
  if (program === 'osascript') return all.some((word) => word.includes('with administrator privileges'))
  if (program === 'start-process') return all.some((word, index) => word === '-verb' && all[index + 1] === 'runas')
  if (['install-module', 'install-package', 'install-script'].includes(program)) {
    return all.some((word, index) => word === '-scope' && all[index + 1] === 'allusers')
  }
  return false
}

const BY_NAME = new Set(['pkill', 'killall', 'killall5'])
const KILLERS = new Set(['kill', 'stop-process', 'spps'])
const LOOKUPS = new Set(['pgrep', 'pidof', 'lsof', 'fuser', 'get-process', 'gps'])

/** pkill and its kin, or a kill fed by a lookup by name or pattern (`kill $(pgrep …)`, `lsof -ti :3000 | xargs kill`). */
function killsByName(commands: Simple[]): boolean {
  let kills = false, looksUp = false
  for (const { words } of commands) {
    const program = programName(words[0])
    const all = lower(words)
    if (BY_NAME.has(program)) return true
    if (program === 'fuser' && all.slice(1).some((word) => /^-[a-z]*k/.test(word))) return true
    if (program === 'taskkill' && all.some((word) => word === '/im' || word === '-im')) return true
    if (KILLERS.has(program) && all.some((word) => word === '-name' || word === '-processname')) return true
    if (program === 'wmic' && all.includes('process') && all.some((word) => word === 'delete' || word === 'terminate')) return true
    if (KILLERS.has(program)) kills = true
    // `ps -p 4242` checks a recorded id; `ps aux` lists everything for a pattern to pick from.
    if (LOOKUPS.has(program) || (program === 'ps' && !all.some((word) => /^-[a-z]*[pq]$/.test(word) || word === '--pid'))) {
      if (!(program === 'get-process' || program === 'gps') || !all.includes('-id')) looksUp = true
    }
  }
  return kills && looksUp
}

/** Negative and zero targets reach process groups or the whole account, not a single recorded process.
 *  A bare negative argument is refused even where a shell interprets it as a signal with a missing target. */
function killsAll({ words }: Simple): boolean {
  if (programName(words[0]) !== 'kill') return false
  let at = 1
  if (words[at] === '-s' || words[at] === '-n') at += 2
  else if (words[at] === '-l' || words[at] === '-L') return false
  else if (words[at]?.startsWith('-') && words[at] !== '--') at += 1
  if (words[at] === '--') at += 1
  const targets = words.slice(at)
  return (!targets.length && /^-\d+$/.test(words[1] ?? ''))
    || targets.some((word) => /^-?\d+$/.test(word) && Number(word) <= 0)
}

const TMP_ROOTS = ['/tmp', '/private/tmp', '/var/tmp', '/private/var/tmp']
/** A path in /tmp inside a word: at its start, or after `=`, `:` or `,` (`--output=/tmp/x`, `PATH=a:/tmp/b`). */
const TMP_PATH = /(?:^|[=:,])((?:\/private)?(?:\/var)?\/tmp\/[^\s"'`;|&<>()]+)/g

/** A word or redirection writing, reading or running a fixed name in /tmp; `mktemp`'s own words are its templates. */
function fixedTmp({ words, targets }: Simple, facts: GuardFacts): boolean {
  const program = programName(words[0])
  if (targets.some((target) => fileRefusal(target, facts) !== null)) return true
  if (program === 'mktemp') return false
  // `cd /tmp` and then a plain name writes a fixed name there.
  if ((program === 'cd' || program === 'pushd') && words[1] && TMP_ROOTS.includes(words[1].replace(/\/+$/, ''))) return true
  return words.some((word) => tmpPathRefused(word, facts))
}

/** A mktemp that names no template and no folder (`-p`, `--tmpdir`): macOS's then writes in the account's own temporary
 *  folder, whatever TMPDIR says (the Mac test of #3506). `-t` takes a prefix, not a folder. */
function mktempIgnoringTmpdir({ words }: Simple): boolean {
  if (programName(words[0]) !== 'mktemp') return false
  for (let at = 1; at < words.length; at++) {
    const word = words[at]
    if (word === '--tmpdir' || word.startsWith('--tmpdir=')) return false
    if (!word.startsWith('-')) return false
    // A cluster such as -dt or -dp: its last letter may take the next word as its value.
    if (!word.startsWith('--') && word.includes('p')) return false
    if (!word.startsWith('--') && word.endsWith('t')) at++
  }
  return true
}

/** Whether [word] names a path in /tmp whose top folder is not one only this account can open. */
function tmpPathRefused(word: string, facts: GuardFacts): boolean {
  for (const match of word.matchAll(TMP_PATH)) {
    // Check the destination, not an earlier private component that `..` leaves behind.
    const path = posix.normalize(match[1])
    const root = TMP_ROOTS.find(root => path.startsWith(`${root}/`))
    if (root && !facts.privateFolder(`${root}/${path.slice(root.length + 1).split('/')[0]}`)) return true
  }
  return false
}

/**
 * `git worktree remove P`, or `rm -r P` of a folder holding a linked worktree, while a live process still works in it.
 * Rowan's security review (11-06): naming the worktree's parent, a glob over the worktrees or a `~/` path removed a live
 * worktree too, so the target is the folder after `~` and globs are read, and it counts when it holds a worktree at
 * any depth the walk reaches. Live processes are read only then: they cost an lsof on a Mac.
 */
function liveWorktree(commands: Simple[], facts: GuardFacts): string | null {
  let cwd = facts.cwd
  for (const { words } of commands) {
    const program = programName(words[0])
    if (program === 'cd' && words[1] && !words[1].startsWith('-') && !words[1].includes('$')) {
      const folder = expandHome(words[1], facts)
      if (!folder.startsWith('~')) cwd = resolveIn(cwd, folder, facts.platform)
      continue
    }
    for (const target of removedFolders(words, cwd, facts)) {
      const real = facts.realpath?.(target) ?? target
      if (!holdsWorktree(real, facts) && (real === target || !holdsWorktree(target, facts))) continue
      const live = facts.liveCwds()
      if (live === null) return GUARD_REASONS.worktreeUnknown(target)
      const user = live.find(({ cwd: there }) => within(there, real) || within(there, target))
      if (user) return GUARD_REASONS.liveWorktree(target, user.pid)
    }
  }
  return null
}

const within = (path: string, folder: string) => path === folder || path.startsWith(`${folder}/`)
const resolveIn = (cwd: string, path: string, platform: NodeJS.Platform) =>
  (platform === 'win32' ? resolve(cwd, path) : posix.resolve(cwd, path)).replace(/(.)\/+$/, '$1')

/** How deep, and through how many folders, the walk looks for a worktree: ~/harnesses/worktrees/<project>/<id> is 4. */
const WALK_DEPTH = 4
const WALK_FOLDERS = 2000
const WALK_SKIPS = new Set(['node_modules', '.git'])

/** Whether [path] is a linked worktree or holds one; a walk too big to finish counts as holding one. */
function holdsWorktree(path: string, facts: GuardFacts): boolean {
  if (facts.linkedWorktree(path)) return true
  if (!facts.entries) return false
  let seen = 0
  const walk = (folder: string, depth: number): boolean => {
    if (depth === 0) return false
    for (const name of facts.entries!(folder)) {
      if (WALK_SKIPS.has(name)) continue
      if (++seen > WALK_FOLDERS) return true
      const inner = `${folder.replace(/\/+$/, '')}/${name}`
      if (facts.linkedWorktree(inner) || walk(inner, depth - 1)) return true
    }
    return false
  }
  return walk(path, WALK_DEPTH)
}

const expandHome = (path: string, facts: GuardFacts): string =>
  facts.home && (path === '~' || path.startsWith('~/')) ? `${facts.home}${path.slice(1)}` : path

const GLOB = /[*?[]/
/** A segment's shell glob as a pattern: `*`, `?` and `[…]`; a leading `*` or `?` matches no dot file, as the shell's. */
function globPattern(segment: string): RegExp {
  let source = ''
  for (let i = 0; i < segment.length; i++) {
    const c = segment[i]
    if (c === '*') source += '[^/]*'
    else if (c === '?') source += '[^/]'
    else if (c === '[') {
      const close = segment.indexOf(']', i + 2)
      if (close === -1) { source += '\\['; continue }
      source += `[${segment.slice(i + 1, close).replace(/^!/, '^').replace(/\\/g, '\\\\')}]`
      i = close
    } else source += c.replace(/[.+^${}()|\\\]]/g, '\\$&')
  }
  return new RegExp(`^${/^[*?[]/.test(segment) ? '(?!\\.)' : ''}${source}$`)
}

/** The folders a path argument names: itself, or for a glob each folder its first glob segment matches (what is below
 *  it counts, so the rest of the pattern is not needed). */
function namedFolders(path: string, cwd: string, facts: GuardFacts): string[] {
  const expanded = expandHome(path, facts)
  if (expanded.startsWith('~') || expanded.includes('$')) return []
  if (!GLOB.test(expanded)) return [resolveIn(cwd, expanded, facts.platform)]
  const segments = expanded.split('/')
  const at = segments.findIndex((segment) => GLOB.test(segment))
  const base = resolveIn(cwd, segments.slice(0, at).join('/') || (expanded.startsWith('/') ? '/' : '.'), facts.platform)
  const pattern = globPattern(segments[at])
  return (facts.entries?.(base) ?? []).filter((name) => pattern.test(name)).map((name) => `${base.replace(/\/+$/, '')}/${name}`)
}

/** The folders [words] remove: `git [-C dir] worktree remove [-f] P`, or each target of a recursive `rm`. */
function removedFolders(words: string[], cwd: string, facts: GuardFacts): string[] {
  const { platform } = facts
  const program = programName(words[0])
  if (program === 'git') {
    let at = 1, here = cwd
    while (at < words.length && words[at].startsWith('-')) {
      if (words[at] === '-C' && words[at + 1]) { here = resolveIn(here, words[at + 1], platform); at += 2; continue }
      at += words[at] === '-c' ? 2 : 1
    }
    if (words[at] !== 'worktree' || words[at + 1] !== 'remove') return []
    const path = words.slice(at + 2).find((word) => !word.startsWith('-'))
    return path ? [resolveIn(here, path, platform)] : []
  }
  if (program === 'rm') {
    const args = words.slice(1)
    const end = args.indexOf('--')
    const options = end === -1 ? args.filter((word) => word.startsWith('-')) : args.slice(0, end).filter((word) => word.startsWith('-'))
    if (!options.some((word) => word === '--recursive' || /^-[a-zA-Z]*[rR]/.test(word))) return []
    const paths = end === -1 ? args.filter((word) => !word.startsWith('-')) : [...args.slice(0, end).filter((word) => !word.startsWith('-')), ...args.slice(end + 1)]
    return paths.flatMap((path) => namedFolders(path, cwd, facts))
  }
  return []
}

// ---------------------------------------------------------------------------------------------------------------------
// The machine's facts

/** Whether [path] is a folder (not a link) this account owns and only it can open: what `mktemp -d` makes. */
export function privateFolderOf(path: string): boolean {
  try {
    const stat = lstatSync(path)
    const uid = process.getuid?.()
    return stat.isDirectory() && (uid === undefined || stat.uid === uid) && (stat.mode & 0o077) === 0
  } catch { return false }
}

/** The folders (not links) in [path]; none when it cannot be read. */
export function foldersIn(path: string): string[] {
  try { return readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) }
  catch { return [] }
}

/** Whether [path] is a linked git worktree: a folder whose `.git` is a file naming the main repository's. */
export function linkedWorktreeOf(path: string): boolean {
  try { return lstatSync(path).isDirectory() && lstatSync(`${path}/.git`).isFile() } catch { return false }
}

/**
 * Every live process's working folder. Linux reads /proc; a Mac asks lsof for working folders only (`-d cwd`), which
 * lists this account's processes. Windows refuses by itself to remove a folder a process works in, so nothing is read
 * there. Null when they cannot be read: the guard then refuses the removal rather than guess.
 */
export function liveCwdsOf(platform: NodeJS.Platform = process.platform): { pid: number; cwd: string }[] | null {
  if (platform === 'win32') return []
  if (platform === 'linux') {
    try {
      return readdirSync('/proc').filter((name) => /^\d+$/.test(name)).flatMap((pid) => {
        try { return [{ pid: Number(pid), cwd: readlinkSync(`/proc/${pid}/cwd`) }] } catch { return [] }
      })
    } catch { return null }
  }
  const run = spawnSync('lsof', ['-a', '-d', 'cwd', '-F', 'pn', '-w'], { encoding: 'utf8', timeout: 5000, windowsHide: true })
  if (run.error || !run.stdout) return null
  const found: { pid: number; cwd: string }[] = []
  let pid = 0
  for (const line of run.stdout.split('\n')) {
    if (line.startsWith('p')) pid = Number(line.slice(1))
    else if (line.startsWith('n') && pid) found.push({ pid, cwd: line.slice(1) })
  }
  return found
}

/** The guard's facts for a command run in [cwd] on this machine. */
export function machineFacts(cwd: string): GuardFacts {
  let live: ReturnType<typeof liveCwdsOf> | undefined
  return {
    cwd: isAbsolute(cwd) ? cwd : resolve(cwd),
    platform: process.platform,
    home: homedir(),
    entries: foldersIn,
    privateFolder: privateFolderOf,
    linkedWorktree: linkedWorktreeOf,
    liveCwds: () => (live === undefined ? (live = liveCwdsOf()) : live),
    realpath: (path) => { try { return realpathSync(path) } catch { return path } },
  }
}