@mmerterden/multi-agent-pipeline 20.23.2 → 20.24.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)));
+}

package/pipeline/scripts/gate-ledger.mjs

@@ -52,6 +52,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 
+import { decisionEntry, withDecision } from "../lib/decisions.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { readRegularFile, readRegularJson } from "../lib/regular-file.mjs";
 import { attendedVerdict, gatesActive } from "../lib/unattended.mjs";
@@ -316,6 +317,9 @@ export async function recordQuietly(gate, verdict, detail, opts) {
  * Park an unattended run for a person. The runner reads `waitingFor` as
  * awaiting-answer and `verificationFailed` as verification-failed.
  *
+ * Parking is the run deciding not to go on, so the same write appends the
+ * entry to `decisions[]` that the Phase 5 report and the PR body list.
+ *
  * @param {string} path
  * @param {{outcome: "awaiting-answer"|"verification-failed", waitingFor?: string,
  *          gate?: string, reason?: string}} opts
@@ -327,26 +331,55 @@ export async function park(path, { outcome, waitingFor, gate, reason = "", pendi
     if (waitingFor === "question" && !pendingQuestion) {
       throw new LedgerError("usage", "waitingFor question needs a pendingQuestion to answer");
     }
-    return updateState(path, (s) => ({
-      ...s,
-      waitingFor,
-      ...(pendingQuestion ? { pendingQuestion } : {}),
-      status: "awaiting_input",
-      haltReason: reason || `waiting for ${waitingFor}`,
-    }));
+    return updateState(path, (s) =>
+      withDecision(
+        {
+          ...s,
+          waitingFor,
+          ...(pendingQuestion ? { pendingQuestion } : {}),
+          status: "awaiting_input",
+          haltReason: reason || `waiting for ${waitingFor}`,
+        },
+        decisionEntry({
+          what: `Parked the run to wait for ${waitingFor}`,
+          why: reason || `waiting for ${waitingFor}`,
+          costIfWrong:
+            "the run stops until someone answers, even if the default would have been fine",
+          phase: phaseOf(s),
+          at,
+        }),
+      ),
+    );
   }
   if (outcome === "verification-failed") {
     if (!gate) throw new LedgerError("usage", "verification-failed needs --gate");
-    return updateState(path, (s) => ({
-      ...s,
-      status: "failed",
-      verificationFailed: { gate, reason, at },
-      haltReason: `verification failed at ${gate}: ${reason}`,
-    }));
+    return updateState(path, (s) =>
+      withDecision(
+        {
+          ...s,
+          status: "failed",
+          verificationFailed: { gate, reason, at },
+          haltReason: `verification failed at ${gate}: ${reason}`,
+        },
+        decisionEntry({
+          what: `Parked the run: ${gate} rejected the work`,
+          why: reason || `${gate} failed`,
+          costIfWrong: "work that would have passed is held back until someone resumes it",
+          phase: phaseOf(s),
+          at,
+        }),
+      ),
+    );
   }
   throw new LedgerError("usage", `unknown outcome ${outcome}`);
 }
 
+/** The run's current phase, held to the 0..5 range a decision entry takes. */
+function phaseOf(state) {
+  const n = Number(state?.currentPhase);
+  return Number.isInteger(n) ? Math.min(5, Math.max(0, n)) : 0;
+}
+
 /**
  * Latest entry per gate for one sha. "Latest" is by `at`, then by position.
  */