@ucsandman/legcli 0.7.0

package/src/accounts.mjs

@@ -0,0 +1,119 @@
+// accounts — optional second (third…) subscription logins per agent.
+// `default` is the CLI's own home (~/.claude, ~/.codex). An extra account is a
+// directory under $BATON_HOME/accounts/<agent>/<name>/ that the CLI is pointed
+// at with its config-dir variable (CLAUDE_CONFIG_DIR, CODEX_HOME); the
+// harness (hooks, skills, agents, commands, plugins, rules, prompts…) is shared
+// back into it with directory junctions, and the settings file is refreshed
+// from the real home before every launch. Only the login lives in the
+// account dir. agy 1.2.0 has no config-dir override, so it stays one account.
+import { existsSync, mkdirSync, readFileSync, copyFileSync, readdirSync, lstatSync, symlinkSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { home } from './store.mjs'
+import { writeJsonAtomic } from './fsx.mjs'
+
+// What each CLI keeps in its home. `share` dirs are junctioned into the
+// account dir; `copy` files are refreshed from the real home at launch;
+// everything else (credentials, sessions, history, caches) stays per account.
+export const LAYOUT = {
+  claude: {
+    env: 'CLAUDE_CONFIG_DIR',
+    home: () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'),
+    share: ['hooks', 'skills', 'agents', 'commands', 'plugins', 'rules', 'scripts', 'output-styles', 'tools'],
+    copy: ['settings.json', 'settings.local.json', 'CLAUDE.md', 'keybindings.json', 'statusline.ps1', 'statusline-combined.ps1'],
+    login: (dir) => `$env:CLAUDE_CONFIG_DIR='${dir}'; claude auth login`,
+  },
+  codex: {
+    env: 'CODEX_HOME',
+    home: () => process.env.CODEX_HOME || join(homedir(), '.codex'),
+    share: ['skills', 'prompts', 'rules', 'plugins', 'agents', 'hooks', 'memories', 'superpowers'],
+    copy: ['config.toml', 'AGENTS.md'],
+    login: (dir) => `$env:CODEX_HOME='${dir}'; codex login`,
+  },
+  agy: { env: null, home: () => join(homedir(), '.gemini', 'antigravity-cli'), share: [], copy: [], login: null },
+}
+
+export function accountsFile() { return join(home(), 'accounts.json') }
+export function accountDir(agent, name) { return join(home(), 'accounts', agent, name) }
+
+export function readAccounts() {
+  const base = { claude: ['default'], codex: ['default'], agy: ['default'] }
+  if (!existsSync(accountsFile())) return base
+  try {
+    const j = JSON.parse(readFileSync(accountsFile(), 'utf8'))
+    for (const k of Object.keys(base)) if (Array.isArray(j[k])) base[k] = ['default', ...j[k].filter((n) => n !== 'default')]
+  } catch {}
+  return base
+}
+
+function writeAccounts(acc) {
+  mkdirSync(home(), { recursive: true })
+  writeJsonAtomic(accountsFile(), Object.fromEntries(Object.entries(acc).map(([k, v]) => [k, v.filter((n) => n !== 'default')])))
+}
+
+export function envFor(agent, account) {
+  if (account === 'default') return {}
+  const l = LAYOUT[agent]
+  if (!l?.env) return {}
+  return { [l.env]: accountDir(agent, account) }
+}
+
+function junction(target, link) {
+  if (existsSync(link)) return false
+  if (!existsSync(target)) return false
+  symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir')
+  return true
+}
+
+// Create the account dir, junction the shared harness in, copy the settings.
+export function addAccount(agent, name) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,29}$/i.test(name) || name === 'default') throw new Error(`invalid account name "${name}" (letters, digits, - and _; not "default")`)
+  const l = LAYOUT[agent]
+  if (!l) throw new Error(`unknown agent "${agent}" (claude|codex|agy)`)
+  if (!l.env) throw new Error(`${agent} has no config-dir override in the installed version; extra accounts are not possible`)
+  const dir = accountDir(agent, name)
+  mkdirSync(dir, { recursive: true })
+  const src = l.home()
+  const shared = []
+  for (const d of l.share) if (junction(join(src, d), join(dir, d))) shared.push(d)
+  refreshAccount(agent, name)
+  const acc = readAccounts()
+  if (!acc[agent].includes(name)) { acc[agent].push(name); writeAccounts(acc) }
+  return { dir, shared, login: l.login(dir), env: l.env }
+}
+
+// Before each launch: bring the copied files up to date with the real home.
+export function refreshAccount(agent, name) {
+  if (name === 'default') return []
+  const l = LAYOUT[agent]
+  const dir = accountDir(agent, name)
+  const copied = []
+  for (const f of l.copy) {
+    const s = join(l.home(), f)
+    if (!existsSync(s)) continue
+    try { copyFileSync(s, join(dir, f)); copied.push(f) } catch {}
+  }
+  return copied
+}
+
+export function removeAccount(agent, name) {
+  const dir = accountDir(agent, name)
+  if (existsSync(dir)) {
+    // junctions are removed as links, never followed
+    for (const n of readdirSync(dir)) {
+      const p = join(dir, n)
+      if (lstatSync(p).isSymbolicLink()) rmSync(p, { force: true })
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+  const acc = readAccounts()
+  acc[agent] = acc[agent].filter((n) => n !== name)
+  writeAccounts(acc)
+}
+
+export function listAccountRows() {
+  const acc = readAccounts()
+  const rows = []
+  for (const agent of Object.keys(acc)) for (const name of acc[agent]) rows.push({ agent, name, dir: name === 'default' ? LAYOUT[agent].home() : accountDir(agent, name), env: name === 'default' ? null : LAYOUT[agent].env })
+  return rows
+}

package/src/adapters/agy.mjs

@@ -0,0 +1,56 @@
+// agy adapter — agy CLI headless (`agy -p <prompt> --output-format json`).
+// Facts and sources: docs/cli-contracts.md § agy.
+import { join } from 'node:path'
+import { sanitizeEnv } from '../env.mjs'
+import { assertAllowed, firstExisting, goDuration } from './common.mjs'
+
+const adapter = {
+  name: 'agy',
+  stdin: 'ignore',
+  modes: {
+    default: 'accept-edits',
+    allowed: ['accept-edits', 'plan'],
+  },
+  forbiddenFlags: ['--dangerously-skip-permissions'],
+  resolve() {
+    const bin = (process.env.LEG_AGY_BIN || process.env.BATON_AGY_BIN) || firstExisting([
+      process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'agy', 'bin', 'agy.exe') : null,
+    ], 'agy')
+    return { bin, viaNode: /\.(mjs|cjs|js)$/.test(bin), entry: null }
+  },
+  argv(opts = {}) {
+    const mode = assertAllowed(adapter, opts)
+    const { bin, viaNode } = adapter.resolve()
+    // agy does not work in the process cwd: with no project it writes into its
+    // own scratch workspace (probe 2026-09-10 put hello-agy.txt under
+    // ~/.gemini/antigravity-cli/scratch/). --add-dir puts the worktree in the
+    // workspace and the prompt names it as the working directory.
+    // --print-timeout defaults to 5m; tie it to the card's kill timer so the
+    // supervisor, not agy, decides when a leg is a runaway.
+    const cwd = opts.cwd ?? process.cwd()
+    const prompt = `Working directory: ${cwd}\nEvery relative path in this task is relative to that directory; create files there, never in a scratch workspace.\n\n${opts.prompt ?? ''}`
+    const args = ['-p', prompt, '--output-format', 'json', '--mode', mode,
+      '--add-dir', cwd, '--print-timeout', goDuration(opts.killMs ?? 5400000)]
+    if (opts.model) args.push('--model', opts.model)
+    if (opts.resume) args.push('--conversation', opts.resume)
+    return viaNode ? { bin: process.execPath, args: [bin, ...args] } : { bin, args }
+  },
+  env(base) { return sanitizeEnv(base) },
+  parseResult(text) {
+    const s = String(text)
+    for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
+      try {
+        const j = JSON.parse(s.slice(i))
+        return {
+          session_id: j.conversation_id ?? j.conversationId ?? j.session_id ?? null,
+          last_message: typeof j.response === 'string' ? j.response : (typeof j.result === 'string' ? j.result : null),
+          stop_reason: j.stop_reason ?? j.status ?? null,
+          raw: j,
+        }
+      } catch { continue }
+    }
+    return null
+  },
+}
+
+export default adapter

package/src/adapters/claude.mjs

@@ -0,0 +1,54 @@
+// claude adapter — Claude Code headless (`claude -p --output-format json`).
+// Facts and sources: docs/cli-contracts.md § claude.
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { sanitizeEnv } from '../env.mjs'
+import { assertAllowed, firstExisting } from './common.mjs'
+
+const adapter = {
+  name: 'claude',
+  stdin: 'pipe', // the prompt goes to stdin; argv stays short
+  modes: {
+    default: 'acceptEdits',
+    // claude 2.1.268 --permission-mode choices; the bypass mode is never allowed.
+    allowed: ['acceptEdits', 'auto', 'plan', 'manual', 'dontAsk'],
+  },
+  forbiddenFlags: ['--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--permission-mode=bypassPermissions', 'bypassPermissions'],
+  resolve() {
+    const bin = (process.env.LEG_CLAUDE_BIN || process.env.BATON_CLAUDE_BIN) || firstExisting([
+      join(homedir(), '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude'),
+    ], 'claude')
+    return { bin, viaNode: /\.(mjs|cjs|js)$/.test(bin), entry: null }
+  },
+  argv(opts = {}) {
+    const mode = assertAllowed(adapter, opts)
+    const { bin, viaNode } = adapter.resolve()
+    const args = ['-p', '--output-format', 'json', '--permission-mode', mode]
+    if (opts.maxTurns) args.push('--max-turns', String(opts.maxTurns))
+    if (opts.resume) args.push('--resume', opts.resume)
+    if (opts.model) args.push('--model', opts.model)
+    if (opts.allowedTools?.length) args.push('--allowedTools', opts.allowedTools.join(','))
+    // The Agent tool is never denied: a lead without it degrades to solo (LESSONS 07-10).
+    return viaNode ? { bin: process.execPath, args: [bin, ...args] } : { bin, args }
+  },
+  env(base) { return sanitizeEnv(base) },
+  parseResult(text) {
+    let j
+    try { j = JSON.parse(text) } catch { return null }
+    if (!j || typeof j !== 'object') return null
+    return {
+      session_id: j.session_id ?? null,
+      last_message: typeof j.result === 'string' ? j.result : null,
+      stop_reason: j.stop_reason ?? null,
+      subtype: j.subtype ?? null,
+      is_error: j.is_error ?? null,
+      num_turns: j.num_turns ?? null,
+      terminal_reason: j.terminal_reason ?? null,
+      api_error_status: j.api_error_status ?? null,
+      permission_denials: Array.isArray(j.permission_denials) ? j.permission_denials.length : null,
+      raw: j,
+    }
+  },
+}
+
+export default adapter

package/src/adapters/codex.mjs

@@ -0,0 +1,73 @@
+// codex adapter — OpenAI Codex CLI headless (`codex exec --json`).
+// Facts and sources: docs/cli-contracts.md § codex.
+// stdin is 'ignore' on purpose: codex exec reads stdin whenever it is not a
+// TTY and hangs on an open pipe ("Reading additional input from stdin...").
+import { join } from 'node:path'
+import { sanitizeEnv } from '../env.mjs'
+import { resolveNpmCliEntry } from './resolve.mjs'
+import { assertAllowed, firstExisting } from './common.mjs'
+
+const PKG = '@openai/codex'
+
+const adapter = {
+  name: 'codex',
+  stdin: 'ignore',
+  modes: {
+    default: 'workspace-write',
+    allowed: ['read-only', 'workspace-write'],
+  },
+  forbiddenFlags: ['danger-full-access', '--dangerously-bypass-approvals-and-sandbox', '--dangerously-bypass-hook-trust', '--full-auto', '--approve-for-me'],
+  resolve() {
+    if ((process.env.LEG_CODEX_BIN || process.env.BATON_CODEX_BIN)) {
+      const bin = process.env.BATON_CODEX_BIN
+      return { bin, viaNode: /\.(mjs|cjs|js)$/.test(bin), entry: null }
+    }
+    // The npm package's bin/codex.js only spawns the platform package's native
+    // exe; spawning that exe directly keeps one process to kill.
+    const pkgDir = process.env.APPDATA ? join(process.env.APPDATA, 'npm', 'node_modules', PKG) : null
+    const native = pkgDir ? firstExisting([
+      join(pkgDir, 'node_modules', '@openai', 'codex-win32-x64', 'vendor', 'x86_64-pc-windows-msvc', 'bin', 'codex.exe'),
+      join(pkgDir, 'node_modules', '@openai', 'codex-win32-arm64', 'vendor', 'aarch64-pc-windows-msvc', 'bin', 'codex.exe'),
+    ], null) : null
+    if (native) return { bin: native, viaNode: false, entry: null }
+    const entry = resolveNpmCliEntry(PKG, 'codex')
+    if (entry) return { bin: process.execPath, viaNode: true, entry }
+    return { bin: 'codex', viaNode: false, entry: null }
+  },
+  argv(opts = {}) {
+    const mode = assertAllowed(adapter, opts)
+    const { bin, viaNode, entry } = adapter.resolve()
+    const args = ['exec', '--json', '-s', mode, '-C', opts.cwd ?? process.cwd(),
+      '-c', `sandbox_workspace_write.network_access=${opts.network ? 'true' : 'false'}`]
+    if (opts.model) args.push('-m', opts.model)
+    if (opts.runDir) args.push('-o', join(opts.runDir, 'last.md'))
+    if (opts.resume) args.push('resume', opts.resume)
+    args.push(opts.prompt ?? '')
+    return viaNode ? { bin, args: [entry, ...args] } : { bin, args }
+  },
+  env(base) { return sanitizeEnv(base) },
+  parseResult(text) {
+    const events = []
+    for (const line of String(text).split('\n')) {
+      const t = line.trim()
+      if (!t) continue
+      try { events.push(JSON.parse(t)) } catch { continue }
+    }
+    if (!events.length) return null
+    const started = events.find((e) => e.type === 'thread.started')
+    const messages = events.filter((e) => e.type === 'item.completed' && e.item?.type === 'agent_message')
+    const errors = events.filter((e) => e.type === 'item.completed' && e.item?.type === 'error').map((e) => e.item.message)
+    const turnDone = events.find((e) => e.type === 'turn.completed')
+    const turnFailed = events.find((e) => e.type === 'turn.failed' || e.type === 'error')
+    return {
+      session_id: started?.thread_id ?? null,
+      last_message: messages.length ? messages[messages.length - 1].item.text ?? null : null,
+      stop_reason: turnDone ? 'turn.completed' : turnFailed ? (turnFailed.type) : null,
+      usage: turnDone?.usage ?? null,
+      errors,
+      raw: events,
+    }
+  },
+}
+
+export default adapter

package/src/adapters/common.mjs

@@ -0,0 +1,32 @@
+// Shared adapter helpers. An adapter exports:
+//   name, stdin ('pipe' | 'ignore'), modes {default, allowed}, forbiddenFlags,
+//   resolve() → {bin, viaNode, entry}, argv(opts) → {bin, args},
+//   env(base) → sanitized copy, parseResult(text) → {session_id, last_message, stop_reason, raw} | null
+// argv() throws `forbidden flag: …` before anything is spawned when the chain
+// entry names a mode outside `modes.allowed` or smuggles a forbidden flag.
+import { existsSync } from 'node:fs'
+
+export function assertAllowed(adapter, opts = {}) {
+  const mode = opts.mode ?? adapter.modes.default
+  if (!adapter.modes.allowed.includes(mode)) {
+    throw new Error(`forbidden flag: ${adapter.name} mode "${mode}" is not allowed (allowed: ${adapter.modes.allowed.join(', ')})`)
+  }
+  for (const flag of opts.extraArgs ?? []) {
+    if (adapter.forbiddenFlags.some((f) => flag === f || flag.startsWith(`${f}=`))) {
+      throw new Error(`forbidden flag: ${flag}`)
+    }
+  }
+  return mode
+}
+
+// First existing candidate path, else the bare command name (PATH lookup).
+export function firstExisting(candidates, fallback) {
+  for (const c of candidates) if (c && existsSync(c)) return c
+  return fallback
+}
+
+// Go-style duration for CLIs that want "90m" rather than milliseconds.
+export function goDuration(ms) {
+  const s = Math.max(1, Math.ceil(ms / 1000))
+  return s % 60 === 0 ? `${s / 60}m` : `${s}s`
+}

package/src/adapters/fake.mjs

@@ -0,0 +1,48 @@
+// fake adapter — drives bin/fake-agent.mjs, a stand-in CLI for tests and the
+// demo. FAKE_MODE in the environment selects its behaviour (see the bin).
+// Registered as `fake`, and as `fake-claude` / `fake-codex` so demo events read
+// like a real chain; `fake-nostdin` is the same agent with stdin ignored.
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { sanitizeEnv } from '../env.mjs'
+
+const FAKE_AGENT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'fake-agent.mjs')
+
+export function makeFake(name = 'fake', stdin = 'pipe') {
+  const m = /^fake-(claude|codex|agy)$/.exec(name)
+  return {
+    name,
+    stdin,
+    // The classifier treats fake-<cli> as that CLI (its limit fixtures apply).
+    emulates: m ? m[1] : null,
+    modes: { default: 'acceptEdits', allowed: ['acceptEdits', 'plan', 'workspace-write', 'read-only', 'accept-edits', 'auto_edit'] },
+    forbiddenFlags: ['--dangerously-skip-permissions', '--yolo'],
+    resolve() { return { bin: process.execPath, viaNode: true, entry: FAKE_AGENT } },
+    argv({ mode, maxTurns, resume, model, network } = {}) {
+      const args = [FAKE_AGENT]
+      if (mode) args.push('--mode', mode)
+      if (maxTurns) args.push('--max-turns', String(maxTurns))
+      if (resume) args.push('--resume', resume)
+      if (model) args.push('--model', model)
+      if (network) args.push('--network')
+      return { bin: process.execPath, args }
+    },
+    env(base) { return sanitizeEnv(base) },
+    parseResult(text) {
+      try {
+        const j = JSON.parse(text)
+        return {
+          session_id: j.session_id ?? null,
+          last_message: typeof j.result === 'string' ? j.result : null,
+          stop_reason: j.is_error ? 'error' : 'end_turn',
+          is_error: j.is_error ?? false,
+          raw: j,
+        }
+      } catch {
+        return null
+      }
+    },
+  }
+}
+
+export default makeFake('fake')

package/src/adapters/grok.mjs

@@ -0,0 +1,51 @@
+// grok adapter — Grok CLI headless (`grok -p <prompt> --output-format json`).
+// NOT REGISTERED in index.mjs: the phase-3 probe could not verify it because
+// the build machine had no grok login (device-code prompt, exit "Cancelled").
+// Built from `grok --help` only; see docs/cli-contracts.md § grok. Register it
+// after `grok` is logged in and `node scripts/probe.mjs --adapter grok` passes.
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { sanitizeEnv } from '../env.mjs'
+import { assertAllowed, firstExisting } from './common.mjs'
+
+const adapter = {
+  name: 'grok',
+  stdin: 'ignore',
+  modes: {
+    default: 'acceptEdits',
+    allowed: ['default', 'acceptEdits', 'auto', 'dontAsk', 'plan'],
+  },
+  forbiddenFlags: ['--always-approve', 'bypassPermissions', '--permission-mode=bypassPermissions'],
+  resolve() {
+    const bin = (process.env.LEG_GROK_BIN || process.env.BATON_GROK_BIN) || firstExisting([
+      join(homedir(), '.grok', 'bin', process.platform === 'win32' ? 'grok.exe' : 'grok'),
+    ], 'grok')
+    return { bin, viaNode: /\.(mjs|cjs|js)$/.test(bin), entry: null }
+  },
+  argv(opts = {}) {
+    const mode = assertAllowed(adapter, opts)
+    const { bin, viaNode } = adapter.resolve()
+    const args = ['-p', opts.prompt ?? '', '--output-format', 'json', '--permission-mode', mode]
+    if (opts.model) args.push('-m', opts.model)
+    if (opts.resume) args.push('-r', opts.resume)
+    return viaNode ? { bin: process.execPath, args: [bin, ...args] } : { bin, args }
+  },
+  env(base) { return sanitizeEnv(base) },
+  parseResult(text) {
+    const s = String(text)
+    for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
+      try {
+        const j = JSON.parse(s.slice(i))
+        return {
+          session_id: j.session_id ?? j.sessionId ?? null,
+          last_message: typeof j.response === 'string' ? j.response : (typeof j.result === 'string' ? j.result : null),
+          stop_reason: j.stop_reason ?? null,
+          raw: j,
+        }
+      } catch { continue }
+    }
+    return null
+  },
+}
+
+export default adapter

package/src/adapters/index.mjs

@@ -0,0 +1,27 @@
+// Adapter registry. Adapters are loaded lazily so a typo fails with a named
+// error before anything is spawned. Every real CLI here was probed live
+// through the runner in phase 3 (fixtures/live/<name>/, docs/cli-contracts.md).
+// grok.mjs exists but is NOT registered: the build machine had no grok login
+// (the probe printed a device-code prompt and exited "Cancelled"). Register it
+// after `grok` is logged in and scripts/probe.mjs --adapter grok passes.
+const REGISTRY = {
+  fake: { path: './fake.mjs' },
+  'fake-claude': { path: './fake.mjs', fake: ['fake-claude', 'pipe'] },
+  'fake-codex': { path: './fake.mjs', fake: ['fake-codex', 'ignore'] },
+  'fake-agy': { path: './fake.mjs', fake: ['fake-agy', 'ignore'] },
+  'fake-nostdin': { path: './fake.mjs', fake: ['fake-nostdin', 'ignore'] },
+  claude: { path: './claude.mjs' },
+  codex: { path: './codex.mjs' },
+  agy: { path: './agy.mjs' },
+}
+
+export function names() { return Object.keys(REGISTRY) }
+
+export function isFake(name) { return Boolean(REGISTRY[name]?.fake) || name === 'fake' }
+
+export async function get(name) {
+  const entry = REGISTRY[name]
+  if (!entry) throw new Error(`unknown adapter: ${name}`)
+  const mod = await import(entry.path)
+  return entry.fake ? mod.makeFake(...entry.fake) : mod.default
+}

package/src/adapters/resolve.mjs

@@ -0,0 +1,40 @@
+// Ported 2026-09-10 from private ucsandman team tooling; see NOTICE and docs/REUSE.md.
+// resolveNpmCliEntry — the real JS entry of a globally installed npm CLI, so
+// the runner can spawn(node, [entry, ...]) with NO shell. The global npm .cmd
+// shim needs a shell on Windows, and a shell may resolve to the WSL bash shim,
+// which drops Windows variables and misresolves node. A bin override that
+// already points at a .mjs/.cjs/.js short-circuits the resolution (tests).
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+export function resolveNpmCliEntry(pkgName, binName = pkgName, { binOverride, pkgDir, execPath = process.execPath, log = () => {} } = {}) {
+  if (binOverride && /\.(mjs|cjs|js)$/.test(binOverride)) return binOverride
+  const candidates = []
+  if (pkgDir) candidates.push(pkgDir)
+  if (process.env.APPDATA) {
+    candidates.push(join(process.env.APPDATA, 'npm', 'node_modules', pkgName))
+  }
+  // Derived from the running node, not guessed: POSIX installs put the binary
+  // at <prefix>/bin/node and its global packages at <prefix>/lib/node_modules.
+  // The absolute paths below only cover a system install under /usr; Homebrew,
+  // nvm, asdf and the GitHub runners' hostedtoolcache all live elsewhere, and
+  // on macOS none of them are under /usr at all — which is why `npm test`
+  // during a Land failed there with "cannot resolve npm's JS entry" while the
+  // same code passed on Linux, where /usr/local/lib/node_modules happens to
+  // exist. (2026-09-15, first CI run with macOS in the matrix.)
+  if (execPath) candidates.push(join(dirname(execPath), '..', 'lib', 'node_modules', pkgName))
+  candidates.push(`/usr/local/lib/node_modules/${pkgName}`)
+  candidates.push(`/usr/lib/node_modules/${pkgName}`)
+  for (const dir of candidates) {
+    const pkgPath = join(dir, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[binName]
+      if (bin) return join(dir, bin)
+    } catch (err) {
+      log(`${pkgName} package.json unreadable at ${pkgPath}: ${err.message}`)
+    }
+  }
+  return null
+}