@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/pipeline/scripts/edit-syntax-gate.mjs

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+/**
+ * edit-syntax-gate.mjs  -  parse the file an edit just wrote, report a syntax error.
+ *
+ * Called by edit-syntax-gate.sh as a PostToolUse hook. Three hosts' payloads
+ * are read (editedFiles):
+ *
+ *   Claude Code   tool_name Edit / Write / MultiEdit, tool_input.file_path
+ *   Copilot CLI   toolName edit / create, toolArgs.path (toolArgs arrives as a
+ *                 JSON string); the VS Code-compatible snake_case form carries
+ *                 tool_name and tool_input.path instead. Read and answered,
+ *                 but not registered by the pipeline: as of 1.0.45 Copilot
+ *                 CLI discards postToolUse output and applies no matcher
+ *   Codex         tool_name apply_patch, tool_input.command holding the patch
+ *                 text; every file it adds, updates or moves to is checked
+ *
+ * For each edited file it picks one parser by extension, runs it under a short
+ * deadline and, when the file does not parse, prints the context object that
+ * host reads back (hookSpecificOutput.additionalContext on Claude Code and
+ * Codex, a top-level additionalContext on Copilot CLI) so the model sees the
+ * error before its next step:
+ *
+ *   .swift              swiftc -parse (when swiftc is on PATH)
+ *   .js .mjs .cjs       node --check (a file that looks like JSX: skipped)
+ *   .py                 python3 py_compile, bytecode written to a temp dir
+ *   .json               JSON.parse after a UTF-8 BOM is dropped; files that
+ *                       are JSONC by convention (tsconfig / jsconfig, .vscode,
+ *                       .devcontainer, .eslintrc, turbo, deno) are skipped
+ *   .sh .bash           bash -n
+ *
+ * Kotlin has no parser that answers inside the deadline (kotlinc starts a JVM),
+ * so .kt / .kts are skipped, as is every other extension (.jsx and .jsonc
+ * among them).
+ *
+ * Silent on: the gate switched off (`editSyntaxGate.enabled` not true), a parser
+ * not installed, a parser that runs past the deadline, a file that is gone or
+ * too large, an unreadable payload. A missing tool is the user's toolchain, not
+ * the edit's fault, and a false alarm costs more than a missed one: the build
+ * still catches what this lets through.
+ *
+ * One hook call checks at most 8 files within about 8 s overall (the hook is
+ * killed at 10 s); files past either limit are not checked, and their count
+ * is added to a message that reports an error.
+ *
+ * Exit 0 always.
+ *
+ * @module pipeline/scripts/edit-syntax-gate
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, extname, join, resolve, sep } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const CLAUDE_EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
+const COPILOT_EDIT_TOOLS = new Set(["edit", "create"]);
+const CODEX_PATCH_TOOL = "apply_patch";
+const DEADLINE_MS = 2000;
+const BUDGET_MS = 8000;
+const MAX_FILES = 8;
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 6;
+const MAX_CHARS = 800;
+const NODE_INTERNAL_FRAME = /^\s*at .*\(?node:internal[/:]/;
+const PREF = "editSyntaxGate.enabled";
+
+function prefsCandidates() {
+  const home = process.env.HOME || homedir();
+  return [
+    process.env.MULTI_AGENT_PREFS,
+    join(home, ".claude", "multi-agent-preferences.json"),
+    join(home, ".config", "multi-agent-pipeline", "multi-agent-preferences.json"),
+  ].filter(Boolean);
+}
+
+/** `prefs.global.editSyntaxGate.enabled` from the first prefs file that exists. */
+export function gateEnabled(paths = prefsCandidates()) {
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    try {
+      let node = JSON.parse(readFileSync(p, "utf8"))?.global;
+      for (const key of PREF.split(".")) node = node?.[key];
+      return node === true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+const JSONC_NAMES =
+  /^(?:(?:tsconfig|jsconfig)(?:\..+)?\.json|\.eslintrc\.json|turbo\.json|deno\.jsonc?|devcontainer\.json|\.devcontainer\.json)$/;
+
+function isJsonc(file) {
+  return (
+    JSONC_NAMES.test(basename(file)) ||
+    file.includes(`${sep}.vscode${sep}`) ||
+    file.includes(`${sep}.devcontainer${sep}`)
+  );
+}
+
+/** `text` with string literals and comments blanked, so only code is left. */
+function codeOnly(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      out += "\n";
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end === -1 ? text.length : end + 1;
+      out += " ";
+    } else if (c === '"' || c === "'" || c === "`") {
+      for (i++; i < text.length && text[i] !== c; i++) {
+        if (text[i] === "\\") i++;
+        else if (c !== "`" && text[i] === "\n") break;
+      }
+      out += " ";
+    } else out += c;
+  }
+  return out;
+}
+
+const JSX_TAG = /<[A-Z][\w.]*(?=[\s/>])|<\/[A-Za-z]?/;
+
+/**
+ * True when the code (strings and comments aside) carries an element-like
+ * `<Capitalized` or a closing `</`. node --check rejects JSX, and a file that
+ * only looks like JSX is skipped rather than flagged.
+ */
+export function looksLikeJsx(text) {
+  return JSX_TAG.test(codeOnly(text));
+}
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    encoding: "utf8",
+    timeout: DEADLINE_MS,
+    killSignal: "SIGKILL",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, PYTHONDONTWRITEBYTECODE: "1" },
+  });
+  if (r.error || r.signal || r.status === null) return null;
+  if (r.status === 0) return { ok: true };
+  return { ok: false, output: `${r.stderr || ""}${r.stdout || ""}` };
+}
+
+/**
+ * Parse one file. `null` = not judged (no parser, parser missing, deadline);
+ * `{ok}` = parsed; `{ok: false, checker, output}` = syntax error.
+ */
+export function checkFile(file) {
+  const ext = extname(file).toLowerCase();
+  if (ext === ".json") {
+    if (isJsonc(file)) return null;
+    try {
+      JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, checker: "JSON.parse", output: err.message };
+    }
+  }
+  const scratch = mkdtempSync(join(tmpdir(), "edit-syntax-gate-"));
+  try {
+    let checker;
+    let res;
+    if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+      if (looksLikeJsx(readFileSync(file, "utf8"))) return null;
+      checker = "node --check";
+      res = run(process.execPath, ["--check", file], scratch);
+    } else if (ext === ".sh" || ext === ".bash") {
+      checker = "bash -n";
+      res = run("bash", ["-n", file], scratch);
+    } else if (ext === ".py") {
+      checker = "python3 py_compile";
+      res = run(
+        "python3",
+        [
+          "-I",
+          "-c",
+          [
+            "import py_compile, sys",
+            "try:",
+            "    py_compile.compile(sys.argv[1], cfile=sys.argv[2], doraise=True)",
+            "except py_compile.PyCompileError as e:",
+            "    sys.stderr.write(e.msg)",
+            "    sys.exit(1)",
+          ].join("\n"),
+          file,
+          join(scratch, "out.pyc"),
+        ],
+        scratch,
+      );
+    } else if (ext === ".swift") {
+      checker = "swiftc -parse";
+      res = run("swiftc", ["-parse", file], scratch);
+    } else {
+      return null;
+    }
+    if (!res) return null;
+    return res.ok ? res : { ...res, checker };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+function brief(output) {
+  const lines = String(output || "")
+    .split("\n")
+    .map((l) => l.trimEnd())
+    .filter((l) => l && !NODE_INTERNAL_FRAME.test(l));
+  const text = lines.slice(0, MAX_LINES).join("\n");
+  return text.length > MAX_CHARS ? `${text.slice(0, MAX_CHARS)}...` : text;
+}
+
+const PATCH_TARGET = /^\*\*\* (?:Add File|Update File|Move to): (.+)$/;
+const PATCH_MOVE = /^\*\*\* Move to: /;
+
+/**
+ * The files an apply_patch leaves on disk, in patch order: every added and
+ * updated file, with a moved file named by its new path. Deleted files are
+ * gone, so they are not listed.
+ */
+export function patchFiles(patch) {
+  if (typeof patch !== "string") return [];
+  const out = [];
+  for (const line of patch.split(/\r?\n/)) {
+    const m = line.match(PATCH_TARGET);
+    if (!m) continue;
+    const path = m[1].trim();
+    if (!path) continue;
+    if (PATCH_MOVE.test(line) && out.length) out[out.length - 1] = path;
+    else out.push(path);
+  }
+  return [...new Set(out)];
+}
+
+function argsObject(raw) {
+  if (raw && typeof raw === "object") return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const v = JSON.parse(raw);
+    return v && typeof v === "object" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which host sent `payload` and the absolute paths it edited, or null for a
+ * call that wrote no file. Relative paths resolve against the payload's cwd,
+ * else the process cwd: the checkers run in a scratch directory.
+ *
+ * @returns {{host: "claude"|"copilot"|"copilot-vscode"|"codex", files: string[]} | null}
+ */
+export function editedFiles(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const abs = (paths) =>
+    paths.filter((p) => typeof p === "string" && p).map((p) => resolve(base, p));
+  let host;
+  let paths;
+  if (typeof payload.toolName === "string") {
+    if (!COPILOT_EDIT_TOOLS.has(payload.toolName)) return null;
+    host = "copilot";
+    paths = [argsObject(payload.toolArgs)?.path];
+  } else if (payload.tool_name === CODEX_PATCH_TOOL) {
+    host = "codex";
+    paths = patchFiles(payload.tool_input?.command);
+  } else if (CLAUDE_EDIT_TOOLS.has(payload.tool_name)) {
+    host = "claude";
+    paths = [payload.tool_input?.file_path];
+  } else if (COPILOT_EDIT_TOOLS.has(payload.tool_name)) {
+    host = "copilot-vscode";
+    const input = argsObject(payload.tool_input);
+    paths = [input?.path ?? input?.file_path];
+  } else {
+    return null;
+  }
+  const files = abs(paths);
+  return files.length ? { host, files } : null;
+}
+
+function report(file, result) {
+  return `edit-syntax-gate: ${file} no longer parses (${result.checker}). Fix it before going on:\n${brief(result.output)}`;
+}
+
+function contextFor(text, host) {
+  if (host === "copilot") return { additionalContext: text };
+  return { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } };
+}
+
+/** The PostToolUse context object `host` reads for a syntax error, or null. */
+export function message(file, result, host = "claude") {
+  if (!result || result.ok) return null;
+  return contextFor(report(file, result), host);
+}
+
+/**
+ * Check `files` in order within the hook's time: at most `maxFiles` of them,
+ * and none started once a further parser deadline would overrun `budgetMs`
+ * (the hook itself is killed at 10 s). Files left over are not checked, and
+ * their count is always reported: appended to the error message, or as a note
+ * of its own when every checked file parsed, so a skipped file that may be
+ * broken is not passed off as clean.
+ *
+ * @returns {{reports: string[], skipped: number, text: string|null}}
+ */
+export function checkEdited(
+  files,
+  { budgetMs = BUDGET_MS, maxFiles = MAX_FILES, now = Date.now } = {},
+) {
+  const start = now();
+  const reports = [];
+  let checked = 0;
+  let i = 0;
+  for (; i < files.length; i++) {
+    if (checked >= maxFiles || now() - start + DEADLINE_MS > budgetMs) break;
+    const file = files[i];
+    let st;
+    try {
+      st = statSync(file);
+    } catch {
+      continue;
+    }
+    if (!st.isFile() || st.size > MAX_BYTES) continue;
+    checked++;
+    const result = checkFile(file);
+    if (result && !result.ok) reports.push(report(file, result));
+  }
+  const skipped = files.length - i;
+  let text = reports.length ? reports.join("\n\n") : null;
+  if (text && skipped)
+    text += `\n\n(${skipped} more file(s) not checked: time or file-count limit)`;
+  else if (skipped)
+    text = `edit-syntax-gate: the checked files parse; ${skipped} file(s) not checked (time or file-count limit), so their syntax is unknown.`;
+  return { reports, skipped, text };
+}
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    return;
+  }
+  const edit = editedFiles(payload);
+  if (!edit) return;
+  if (!gateEnabled()) return;
+  const { text } = checkEdited(edit.files);
+  if (text) process.stdout.write(`${JSON.stringify(contextFor(text, edit.host))}\n`);
+}
+
+// Fail open: a gate bug must not surface as a hook error on every edit.
+if (invokedDirectly(import.meta.url)) {
+  const done = () => process.exit(0);
+  main().catch(done).then(done);
+}

package/pipeline/scripts/edit-syntax-gate.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# edit-syntax-gate.sh  -  PostToolUse syntax check for the multi-agent pipeline.
+#
+# Runs after a file edit (Claude Code Edit / Write / MultiEdit, Codex
+# apply_patch) and parses the edited file with the
+# fastest parser its extension has, so a broken file is reported in the turn
+# that broke it instead of at the next build. The parsing is in
+# edit-syntax-gate.mjs; this wrapper exists because every hook the pipeline
+# registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
+#
+# Contract (PostToolUse hook on each host):
+#   - Reads the tool-call JSON on stdin.
+#   - On a parse error prints the context object the host reads back on
+#     stdout ({"hookSpecificOutput": {"hookEventName": "PostToolUse",
+#     "additionalContext": "..."}}), which the model reads as context for its
+#     next step. Copilot CLI's payload is read too, but the pipeline does not
+#     register the hook there: as of 1.0.45 Copilot discards its output.
+#   - Exits 0 on every path: the edit has already happened, so blocking would
+#     only hide the message.
+#
+# Inert unless `prefs.global.editSyntaxGate.enabled` is true. No node on PATH,
+# a missing parser, a timeout or any internal error means no message.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+CORE="$HERE/edit-syntax-gate.mjs"
+[ -f "$CORE" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+node "$CORE" 2>/dev/null || true
+exit 0

package/pipeline/scripts/find-polluter.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * find-polluter.mjs  -  which test leaves state behind that something else trips on?
+ *
+ * Two symptoms, one search:
+ *
+ *   --absent <path>   a file or directory appears after the suite runs and no
+ *                     test should leave it behind
+ *   --target <id>     a test that passes on its own fails after some others
+ *
+ * Given the candidate tests in suite order and a command that runs one of them,
+ * it bisects the list: run half of the candidates from a clean state, check the
+ * symptom, keep the half that reproduces it. When neither half does on its own,
+ * the pollution needs a test from each, and both halves are searched with the
+ * other held in place, so the answer is the smallest set that still reproduces
+ * it (usually one test, sometimes a pair). Each trial costs at most the tests in
+ * that half; a single polluter among n tests is found in about 2*log2(n) trials.
+ *
+ * Clean state between trials: with --absent the path is removed (only a path
+ * under --cwd whose parent, symlinks resolved, is under --cwd too, and only
+ * one that did not exist when the search started; one that already exists,
+ * a dangling symlink included, is refused rather than deleted). --reset "<cmd>" runs
+ * before every trial for anything else the tests mutate. Without a reset,
+ * --target assumes each trial starts clean on its own, and checks it: when the
+ * target fails alone after the full-list trial, the search stops with exit 2
+ * rather than blaming whichever test ran first.
+ *
+ * Usage:
+ *   node find-polluter.mjs --run "<command with {test}>" (--list <file> | --test <id>...)
+ *        (--absent <path> | --target <id>) [--reset "<cmd>"] [--cwd <dir>]
+ *        [--timeout-sec n] [--json]
+ *
+ *   {test} is replaced by the shell-quoted test id; a command without it gets
+ *   the id appended. --list holds one id per line (blank and # lines skipped).
+ *   Commands run through /bin/sh from --cwd (default: the current directory).
+ *
+ * Exit: 0 one polluter found · 4 only a combination reproduces it (all named) ·
+ *       3 the full list does not reproduce the symptom · 2 usage or setup error
+ *
+ * Zero runtime dependencies.
+ *
+ * @module pipeline/scripts/find-polluter
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const DEFAULT_TIMEOUT_SEC = 300;
+
+class UsageError extends Error {}
+
+const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Fill {test}; append the id when the command names none. */
+export function renderRun(template, id) {
+  if (!template.includes("{test}")) return `${template} ${shellQuote(id)}`;
+  return template.replaceAll("{test}", shellQuote(id));
+}
+
+/**
+ * Smallest subset of `items` for which `pollutes` holds, found by halving.
+ * The caller has already seen `pollutes(items)` hold. Subsets are passed in
+ * the original order.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {(subset: T[]) => boolean} pollutes
+ * @returns {{culprits: T[], trials: number}}
+ */
+export function bisect(items, pollutes) {
+  let trials = 0;
+  const order = (idx) => [...new Set(idx)].sort((a, b) => a - b);
+  const test = (idx) => {
+    trials++;
+    return pollutes(order(idx).map((i) => items[i]));
+  };
+  const search = (cands, context) => {
+    if (cands.length <= 1) return cands;
+    const mid = Math.ceil(cands.length / 2);
+    const a = cands.slice(0, mid);
+    const b = cands.slice(mid);
+    if (test([...context, ...a])) return search(a, context);
+    if (test([...context, ...b])) return search(b, context);
+    const fromA = search(a, [...context, ...b]);
+    return [...fromA, ...search(b, [...context, ...fromA])];
+  };
+  const found = search(
+    items.map((_, i) => i),
+    [],
+  );
+  return { culprits: order(found).map((i) => items[i]), trials };
+}
+
+function parseArgs(argv) {
+  const opts = { tests: [], timeoutSec: DEFAULT_TIMEOUT_SEC };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const val = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new UsageError(`${a} needs a value`);
+      return v;
+    };
+    if (a === "--run") opts.run = val();
+    else if (a === "--list") opts.list = val();
+    else if (a === "--test") opts.tests.push(val());
+    else if (a === "--absent") opts.absent = val();
+    else if (a === "--target") opts.target = val();
+    else if (a === "--reset") opts.reset = val();
+    else if (a === "--cwd") opts.cwd = val();
+    else if (a === "--timeout-sec") opts.timeoutSec = Number(val());
+    else if (a === "--json") opts.json = true;
+    else throw new UsageError(`unexpected argument ${a}`);
+  }
+  if (!opts.run) throw new UsageError("--run is required");
+  if (Boolean(opts.absent) === Boolean(opts.target)) {
+    throw new UsageError("exactly one of --absent or --target is required");
+  }
+  if (!(opts.timeoutSec > 0)) throw new UsageError("--timeout-sec must be a positive number");
+  if (opts.list) {
+    let text;
+    try {
+      text = readFileSync(opts.list, "utf8");
+    } catch (err) {
+      throw new UsageError(`cannot read --list: ${err.message}`);
+    }
+    for (const line of text.split("\n")) {
+      const id = line.trim();
+      if (id && !id.startsWith("#")) opts.tests.push(id);
+    }
+  }
+  opts.tests = opts.tests.filter((t) => t !== opts.target);
+  if (opts.tests.length === 0) throw new UsageError("no candidate tests");
+  return opts;
+}
+
+const inside = (child, parent) => {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel) && !rel.split(sep).includes("..");
+};
+
+/** True when something, a dangling symlink included, sits at `path`. */
+function present(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the nearest existing ancestor of `path`, with symlinks resolved,
+ * is `cwd` or lies under it, so removing `path` cannot reach outside.
+ */
+function parentInside(path, cwd) {
+  let dir = dirname(path);
+  while (!existsSync(dir)) {
+    const up = dirname(dir);
+    if (up === dir) return false;
+    dir = up;
+  }
+  const real = realpathSync(dir);
+  return real === cwd || inside(real, cwd);
+}
+
+function sh(command, cwd, timeoutMs) {
+  const { NODE_TEST_CONTEXT: _inherited, ...env } = process.env;
+  const r = spawnSync("/bin/sh", ["-c", command], {
+    cwd,
+    env,
+    stdio: "ignore",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+  });
+  return r.status === 0 && !r.error;
+}
+
+/**
+ * @returns {{exit: number, report: object}}
+ */
+export function findPolluter(argv) {
+  const opts = parseArgs(argv);
+  const cwd = realpathSync(resolve(opts.cwd || process.cwd()));
+  const timeoutMs = Math.round(opts.timeoutSec * 1000);
+  const runTest = (id) => sh(renderRun(opts.run, id), cwd, timeoutMs);
+
+  let stray = null;
+  if (opts.absent) {
+    stray = resolve(cwd, opts.absent);
+    if (!inside(stray, cwd) || !parentInside(stray, cwd)) {
+      throw new UsageError(`--absent ${opts.absent} is not under --cwd ${cwd}`);
+    }
+    if (present(stray)) {
+      throw new UsageError(`${opts.absent} already exists; remove it before searching`);
+    }
+  }
+
+  let runs = 0;
+  const reset = () => {
+    if (stray && parentInside(stray, cwd)) rmSync(stray, { recursive: true, force: true });
+    if (opts.reset) sh(opts.reset, cwd, timeoutMs);
+  };
+  const pollutes = (subset) => {
+    reset();
+    for (const id of subset) {
+      runTest(id);
+      runs++;
+    }
+    if (stray) return present(stray);
+    runs++;
+    return !runTest(opts.target);
+  };
+
+  const report = {
+    symptom: stray ? { absent: opts.absent } : { target: opts.target },
+    candidates: opts.tests.length,
+    polluters: [],
+    alone: null,
+    trials: 0,
+    runs: 0,
+  };
+  try {
+    if (!stray) {
+      reset();
+      runs++;
+      if (!runTest(opts.target)) throw new UsageError(`${opts.target} fails on its own`);
+    }
+    if (!pollutes(opts.tests)) {
+      report.reason = "the full list does not reproduce the symptom";
+      return { exit: 3, report };
+    }
+    if (!stray && !opts.reset) {
+      runs++;
+      if (!runTest(opts.target)) {
+        throw new UsageError(
+          `${opts.target} now fails on its own: state persists between trials, pass --reset "<cmd>" to restore it`,
+        );
+      }
+    }
+    const { culprits, trials } = bisect(opts.tests, pollutes);
+    report.polluters = culprits;
+    report.trials = trials;
+    report.alone = culprits.length === 1 ? pollutes(culprits) : false;
+    return { exit: culprits.length === 1 ? 0 : 4, report };
+  } finally {
+    reset();
+    report.runs = runs;
+  }
+}
+
+function main(argv) {
+  let result;
+  try {
+    result = findPolluter(argv);
+  } catch (err) {
+    process.stderr.write(`find-polluter: ${err.message}\n`);
+    if (err instanceof UsageError) {
+      process.stderr.write(
+        'usage: find-polluter.mjs --run "<cmd with {test}>" (--list file | --test id...) (--absent path | --target id) [--reset "<cmd>"] [--cwd dir] [--timeout-sec n] [--json]\n',
+      );
+    }
+    return 2;
+  }
+  const { exit, report } = result;
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else if (report.polluters.length) {
+    const how = report.alone ? "on its own" : "together";
+    process.stdout.write(`polluter (${how}): ${report.polluters.join(", ")}\n`);
+    process.stdout.write(`${report.trials} trials, ${report.runs} test runs\n`);
+  } else {
+    process.stdout.write(`${report.reason}\n`);
+  }
+  return exit;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}