@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/pipeline/scripts/plan-complexity.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+
+/**
+ * @file plan-complexity.mjs  -  how big each plan task is, measured rather than guessed.
+ *
+ * A planner asked "is this task too big" answers from the task's title. This
+ * answers from the repo: what the task touches and what depends on that. The
+ * score is a sum of points over five counted factors, so two runs over the
+ * same plan and graph give the same answer, and every point can be traced to
+ * a number.
+ *
+ *   files             files the task lists                 0-4 points
+ *                     (1 | 2-3 | 4-5 | 6-8 | 9+)
+ *   fanIn             distinct non-test files that depend  0-3 points
+ *                     on the task's files' declarations,   (0 | 1-3 | 4-10 | 11+)
+ *                     one ring out in the code graph,
+ *                     the task's own files excluded
+ *   modules           modules the task's non-test files    0-2 points
+ *                     span, beyond the first
+ *   crossModuleEdges  fan-in files outside every module    0-2 points
+ *                     the task touches                     (0 | 1-3 | 4+)
+ *   testSurface       test files the task lists plus the   0-2 points
+ *                     test files that depend on its        (0-2 | 3-5 | 6+)
+ *                     files in the graph
+ *
+ * score = 1 + points, capped at 10. A task scoring above the split threshold
+ * (prefs.global.planComplexity.splitAbove, default 7) gets
+ * `recommendSplit: true`; Phase 1 splits it before the plan is approved.
+ *
+ * A module is the SPM target under a `Sources` / `Tests` segment
+ * (`Sources/<Target>/`, `Tests/<Target>Tests/`), else the directory above the
+ * first source-root segment (`src`, `test`, `tests`, `lib`, or a file loose
+ * under `Sources` / `Tests`), which is the package or Gradle module; a path
+ * with no such segment belongs to its first directory, and a top-level file
+ * to `.`.
+ *
+ * Without a code graph, fanIn and crossModuleEdges are null and score no
+ * points, and `graph` says `absent`: the score then reads the file list only,
+ * and says so instead of passing for a full measurement. A file the graph does
+ * not know (usually one the task creates) is counted in `notIndexed`.
+ *
+ * Reuses graph-affected.mjs's reverse walk as a module; nothing here runs git
+ * or reaches the network. Zero runtime dependencies (ADR-0004).
+ *
+ * Usage:
+ *   plan-complexity.mjs <plan.json|->  [--graph <path>] [--split-above N]
+ *                                      [--prefs <path>] [--write]
+ *
+ *   --graph        code graph; default ~/.claude/knowledge/<cwd name>/code-graph.json
+ *                  when it exists. A missing file means no graph.
+ *   --split-above  threshold; wins over the prefs file
+ *   --prefs        preferences file; default ~/.claude/multi-agent-preferences.json
+ *   --write        also store {score, recommendSplit, factors} as each task's
+ *                  `complexity` in the plan file (planning-output.schema.json)
+ *
+ * Output: {splitAbove, graph: "used"|"absent"|"unreadable", split: [ids],
+ *          tasks: [{id, score, recommendSplit, factors, points}]}
+ *
+ * Exit codes: 0 scored, 1 plan unreadable or without tasks, 64 usage.
+ *
+ * @module pipeline/scripts/plan-complexity
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { affected } from "./graph-affected.mjs";
+import { defaultGraphPath, loadGraph } from "./graph-query.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const DEFAULT_SPLIT_ABOVE = 7;
+const MAX_SCORE = 10;
+const SOURCE_ROOTS = new Set(["Sources", "Tests", "src", "test", "tests", "lib"]);
+const TEST_PATH = [
+  /Tests?\.(swift|kt|ts|tsx|js|mjs|py)$/i,
+  /(^|\/)(__tests__|Tests|tests|test|androidTest)\//,
+  /\.(test|spec)\.(ts|tsx|js|mjs|py)$/i,
+  /(^|\/)test_[^/]+\.py$/,
+];
+
+const isTestPath = (path) => TEST_PATH.some((r) => r.test(path));
+
+const SPM_ROOTS = new Set(["Sources", "Tests"]);
+
+/**
+ * The module a repo-relative path belongs to. Under an SPM `Sources/` or
+ * `Tests/` root the target directory is the module (`Sources/<Target>/...`,
+ * `Tests/<Target>Tests/...`), so two targets of one package are two modules;
+ * otherwise the directory above the first source root, then the first
+ * directory, then the repository root.
+ */
+export function moduleOf(path) {
+  const parts = String(path).split("/").filter(Boolean);
+  const at = parts.findIndex((p, i) => i < parts.length - 1 && SOURCE_ROOTS.has(p));
+  if (at !== -1 && SPM_ROOTS.has(parts[at]) && at + 1 < parts.length - 1) return parts[at + 1];
+  if (at > 0) return parts.slice(0, at).join("/");
+  if (at === 0 || parts.length < 2) return ".";
+  return parts[0];
+}
+
+const band = (n, limits) => limits.filter((l) => n >= l).length;
+
+function points(f) {
+  return {
+    files: band(f.files, [2, 4, 6, 9]),
+    fanIn: f.fanIn == null ? 0 : band(f.fanIn, [1, 4, 11]),
+    modules: Math.min(2, Math.max(0, f.modules - 1)),
+    crossModuleEdges: f.crossModuleEdges == null ? 0 : band(f.crossModuleEdges, [1, 4]),
+    testSurface: band(f.testSurface, [3, 6]),
+  };
+}
+
+/** Dependent files of everything `files` declares, one ring out. */
+function dependentsInGraph(graph, files) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const seeds = [];
+  let notIndexed = 0;
+  for (const f of files) {
+    const node = byId.get(`file:${f}`);
+    if (node) seeds.push(node);
+    else notIndexed++;
+  }
+  const hits = seeds.length ? affected({ graph, seeds, depth: 1 }) : [];
+  const own = new Set(files);
+  const code = new Set();
+  const tests = new Set();
+  for (const h of hits) {
+    const p = h.node?.path;
+    if (!p || own.has(p)) continue;
+    (h.node.isTest || isTestPath(p) ? tests : code).add(p);
+  }
+  return { code, tests, notIndexed };
+}
+
+function scoreTask(task, graph, splitAbove) {
+  const files = [...new Set((Array.isArray(task.files) ? task.files : []).map(String))];
+  const ownTests = files.filter(isTestPath);
+  const modules = new Set(files.filter((f) => !isTestPath(f)).map(moduleOf));
+  const factors = {
+    files: files.length,
+    fanIn: null,
+    modules: modules.size,
+    crossModuleEdges: null,
+    testSurface: ownTests.length,
+    notIndexed: null,
+  };
+  if (graph) {
+    const d = dependentsInGraph(graph, files);
+    factors.fanIn = d.code.size;
+    factors.crossModuleEdges = [...d.code].filter((p) => !modules.has(moduleOf(p))).length;
+    factors.testSurface = new Set([...ownTests, ...d.tests]).size;
+    factors.notIndexed = d.notIndexed;
+  }
+  const pts = points(factors);
+  const score = Math.min(MAX_SCORE, 1 + Object.values(pts).reduce((s, n) => s + n, 0));
+  return {
+    id: String(task.id),
+    score,
+    recommendSplit: score > splitAbove,
+    factors,
+    points: pts,
+  };
+}
+
+/**
+ * @param {Array<{id: string, files?: string[]}>} tasks
+ * @param {{graph?: object|null, splitAbove?: number, graphState?: string}} [opts]
+ */
+export function planComplexity(tasks, opts = {}) {
+  const graph = opts.graph || null;
+  const splitAbove = Number.isInteger(opts.splitAbove) ? opts.splitAbove : DEFAULT_SPLIT_ABOVE;
+  const scored = (Array.isArray(tasks) ? tasks : [])
+    .filter((t) => t && t.id != null)
+    .map((t) => scoreTask(t, graph, splitAbove));
+  return {
+    splitAbove,
+    graph: opts.graphState || (graph ? "used" : "absent"),
+    split: scored.filter((t) => t.recommendSplit).map((t) => t.id),
+    tasks: scored,
+  };
+}
+
+/** prefs.global.planComplexity.splitAbove from a preferences file, or null. */
+export function splitAboveFromPrefs(path) {
+  try {
+    const prefs = JSON.parse(readFileSync(path, "utf8"));
+    const v = prefs?.global?.planComplexity?.splitAbove;
+    return Number.isInteger(v) && v >= 1 && v <= MAX_SCORE ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--write") flags.write = true;
+    else if (["--graph", "--split-above", "--prefs"].includes(a)) flags[a.slice(2)] = argv[++i];
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function main(argv) {
+  const { flags, positional } = parseArgs(argv);
+  const file = positional[0];
+  if (!file || (flags.write && file === "-")) {
+    process.stderr.write(
+      "usage: plan-complexity.mjs <plan.json|-> [--graph <path>] [--split-above N] [--prefs <path>] [--write]\n",
+    );
+    process.exitCode = 64;
+    return;
+  }
+  let plan;
+  try {
+    plan = JSON.parse(readFileSync(file === "-" ? 0 : file, "utf8"));
+    if (!Array.isArray(plan?.tasks) || plan.tasks.length === 0) throw new Error("no tasks[]");
+  } catch (e) {
+    process.stderr.write(`plan-complexity: ${e.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const cli = Number(flags["split-above"]);
+  const splitAbove = Number.isInteger(cli)
+    ? cli
+    : (splitAboveFromPrefs(
+        flags.prefs || join(homedir(), ".claude", "multi-agent-preferences.json"),
+      ) ?? DEFAULT_SPLIT_ABOVE);
+
+  const graphPath = flags.graph || defaultGraphPath();
+  let graph = null;
+  let graphState = "absent";
+  if (existsSync(graphPath)) {
+    try {
+      graph = loadGraph(graphPath);
+      graphState = "used";
+    } catch (e) {
+      graphState = "unreadable";
+      process.stderr.write(`plan-complexity: graph unreadable, scoring without it: ${e.message}\n`);
+    }
+  }
+
+  const result = planComplexity(plan.tasks, { graph, splitAbove, graphState });
+  if (flags.write) {
+    const byId = new Map(result.tasks.map((t) => [t.id, t]));
+    for (const task of plan.tasks) {
+      const t = byId.get(String(task.id));
+      if (t)
+        task.complexity = { score: t.score, recommendSplit: t.recommendSplit, factors: t.factors };
+    }
+    writeFileSync(file, `${JSON.stringify(plan, null, 2)}\n`);
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (invokedDirectly(import.meta.url)) main(process.argv.slice(2));

package/pipeline/scripts/pre-push-check.sh

@@ -11,12 +11,9 @@
 #   broken commit and npm.
 #
 #   It therefore runs the CANONICAL chain, `npm test`, rather than a hand-picked
-#   subset. The subset it used to run was missing eight of the eleven steps
-#   (lint-skills, lint-mcp-refs, three of the four evals, validate-prefs,
-#   scorecard) and drove the smoke suites through the bare
-#   `for f in smoke-*.sh` loop that run-smokes.mjs was written to replace,
-#   because that loop cannot tell a passing suite from one that exited 0 having
-#   asserted nothing. A safety net with holes in it is worse than a known gap:
+#   subset. A subset drifts from the chain as steps are added, and a bare
+#   `for f in smoke-*.sh` loop cannot tell a passing suite from one that exited 0
+#   having asserted nothing; run-smokes.mjs can. A safety net with holes in it is worse than a known gap:
 #   it is trusted.
 #
 # Two modes, because a gate that runs INSIDE the push is a gate that breaks

package/pipeline/scripts/review-decision-gate.mjs

@@ -60,10 +60,11 @@
 import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
+import { decisionEntry, withDecision } from "../lib/decisions.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { findingFingerprint, FINGERPRINT_RE, normalizeFile } from "./_fingerprint.mjs";
 import { compileMarkers, getAdapter, resolveStack } from "./_stack-adapter.mjs";
-import { gateContext, recordQuietly } from "./gate-ledger.mjs";
+import { gateContext, recordQuietly, updateState } from "./gate-ledger.mjs";
 import { summarize } from "./test-summary.mjs";
 
 export const GATE = "review-decision";
@@ -327,6 +328,34 @@ function emit(json, result, stream) {
   writeFileSync(stream, `${lines.join("\n")}\n`);
 }
 
+/**
+ * Each lowered blocker is a finding nobody was asked to waive, so it is listed
+ * in `decisions[]`, once: a re-run that lowers the same finding (same
+ * file:line, same reason) adds nothing. Best-effort: a state write problem
+ * never changes the gate's verdict.
+ */
+async function recordDowngrades(statePath, downgraded) {
+  try {
+    await updateState(statePath, (s) =>
+      downgraded.reduce((acc, d) => {
+        const entry = decisionEntry({
+          what: `Lowered blocking finding ${d.file}:${d.line} to important`,
+          why: d.reason,
+          costIfWrong:
+            "a real blocker no longer stops the run; the rework still fixes it, but the commit is not held for it",
+          phase: 3,
+        });
+        const seen = (Array.isArray(acc?.decisions) ? acc.decisions : []).some(
+          (e) => e?.what === entry.what && e?.why === entry.why,
+        );
+        return seen ? acc : withDecision(acc, entry);
+      }, s),
+    );
+  } catch (err) {
+    process.stderr.write(`review-decision-gate: decisions not recorded: ${err.message}\n`);
+  }
+}
+
 async function main(argv) {
   let opts;
   try {
@@ -417,6 +446,9 @@ async function main(argv) {
     repo: existsSync(root) ? root : null,
     statePath: ctx.statePath,
   });
+  if (decided && !opts.dryRun && ctx.statePath && result.downgraded?.length) {
+    await recordDowngrades(ctx.statePath, result.downgraded);
+  }
   emit(opts.json, result, result.verdict === "pass" ? 1 : 2);
   if (result.verdict === "pass") return 0;
   return result.verdict === "rebuttal-round" ? 1 : 3;

package/pipeline/scripts/rework-escalation.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * rework-escalation.mjs  -  which rung the next Phase 2 rework dispatch runs on.
+ *
+ * A rework round that dispatches the same model with the same findings tends
+ * to produce the same fix. Two signals say the current rung is not enough:
+ *
+ *   last-round     this is the final rework the cap allows; a failure here
+ *                  ends the loop, so it is the round worth paying more for
+ *   still-present  review-delta.mjs found findings from the previous round's
+ *                  mandate still present after that round's fix
+ *
+ * On either signal the fresh dev agent goes one rung up the model-fallback
+ * ladder (fable -> opus -> sonnet -> haiku, top first), and only one. Every
+ * limit already in force holds it back, checked in this order:
+ *
+ *   disabled         prefs.global.reworkEscalation.enabled is false
+ *   past-cap         the iteration is beyond maxIterations; Phase 2 has stopped
+ *   run-fell-back    the run took a model_fallback; it is not re-upgraded
+ *                    mid-run (model-fallback.md, Non-goals)
+ *   budget-*         cost-budget-check.mjs is at warn, exceeded, or unreadable,
+ *                    or was not run while prefs.global.costBudget.enabled is true
+ *   unknown-tier     the current rung is not on the ladder (another host's model)
+ *   top-of-ladder    nothing above the current rung
+ *   fable-off        the next rung is fable and modelFallback.fableEnabled is not true
+ *   at-ceiling       the next rung is above prefs.global.reworkEscalation.maxTier
+ *
+ * A refusal is a decision too: the result carries the reason, the CLI records
+ * it on the latest review iteration, and the round runs on the current rung.
+ *
+ * Usage:
+ *   rework-escalation.mjs --iteration <n> --current-tier <rung>
+ *       [--max-iterations <n>] [--still-present <n>] [--budget-exit <code>]
+ *       [--fallen-back] [--prefs <path>] [--state <path>]
+ *
+ *   --budget-exit is cost-budget-check.mjs's exit code (0 ok, 10 warn,
+ *   11 exceeded, anything else unknown). Absent, the budget counts as disabled
+ *   only when prefs.global.costBudget.enabled is not true; with the gate on it
+ *   is `unchecked` and holds the rung, because an unrun check is no evidence
+ *   that the budget has room. --prefs defaults to $MULTI_AGENT_PREFS, then
+ *   ~/.claude/multi-agent-preferences.json.
+ *   --state records the result as reviewIterations[-1].reworkEscalation and,
+ *   in an autopilot run, an escalation as an entry in decisions[].
+ *
+ * Output: the decision as JSON on stdout.
+ * Exit: 0 decided (either way) · 2 usage · 3 state write failed
+ *
+ * @module pipeline/scripts/rework-escalation
+ */
+
+import { writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { decisionEntry, withDecision } from "../lib/decisions.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { gatesActive } from "../lib/unattended.mjs";
+import { updateState } from "./gate-ledger.mjs";
+
+export const LADDER = Object.freeze(["fable", "opus", "sonnet", "haiku"]);
+export const DEFAULT_MAX_TIER = "opus";
+export const DEFAULT_MAX_ITERATIONS = 3;
+const BUDGET_OK = new Set(["ok", "disabled"]);
+
+/**
+ * cost-budget-check.mjs exit code -> budget state.
+ * @param {number|undefined|null} code
+ */
+export function budgetFromExit(code) {
+  if (code === 0) return "ok";
+  if (code === 10) return "warn";
+  if (code === 11) return "exceeded";
+  return "unknown";
+}
+
+function settings(prefs) {
+  const g = prefs?.global ?? {};
+  const cfg = g.reworkEscalation ?? {};
+  return {
+    enabled: cfg.enabled !== false,
+    maxTier: LADDER.includes(cfg.maxTier) ? cfg.maxTier : DEFAULT_MAX_TIER,
+    fableEnabled: g.modelFallback?.fableEnabled === true,
+  };
+}
+
+/**
+ * Decide the rung for one rework dispatch. Pure.
+ *
+ * @param {{iteration: number, maxIterations?: number, stillPresent?: number,
+ *          currentTier: string, ladder?: string[], budget?: string,
+ *          prefs?: object, fallenBack?: boolean}} input
+ * @returns {{escalate: boolean, fromTier: string, toTier: string,
+ *            trigger: "last-round"|"still-present"|null, reason: string}}
+ */
+export function decide({
+  iteration,
+  maxIterations = DEFAULT_MAX_ITERATIONS,
+  stillPresent = 0,
+  currentTier,
+  ladder = LADDER,
+  budget = "disabled",
+  prefs = {},
+  fallenBack = false,
+}) {
+  const cfg = settings(prefs);
+  const stay = (reason, trigger = null) => ({
+    escalate: false,
+    fromTier: currentTier,
+    toTier: currentTier,
+    trigger,
+    reason,
+  });
+
+  const trigger =
+    iteration > maxIterations
+      ? null
+      : stillPresent > 0
+        ? "still-present"
+        : iteration === maxIterations
+          ? "last-round"
+          : null;
+
+  if (!cfg.enabled) return stay("disabled", trigger);
+  if (iteration > maxIterations) return stay("past-cap");
+  if (!trigger) return stay("not-triggered");
+  if (fallenBack) return stay("run-fell-back", trigger);
+  if (!BUDGET_OK.has(budget)) {
+    return stay(
+      ["warn", "exceeded", "unchecked"].includes(budget) ? `budget-${budget}` : "budget-unknown",
+      trigger,
+    );
+  }
+
+  const at = ladder.indexOf(currentTier);
+  if (at < 0 || !LADDER.includes(currentTier)) return stay("unknown-tier", trigger);
+  if (at === 0) return stay("top-of-ladder", trigger);
+  const next = ladder[at - 1];
+  if (next === "fable" && !cfg.fableEnabled) return stay("fable-off", trigger);
+  if (LADDER.indexOf(next) < LADDER.indexOf(cfg.maxTier)) return stay("at-ceiling", trigger);
+
+  return { escalate: true, fromTier: currentTier, toTier: next, trigger, reason: "escalated" };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+class UsageError extends Error {}
+
+const VALUE_FLAGS = new Set([
+  "iteration",
+  "max-iterations",
+  "still-present",
+  "current-tier",
+  "budget-exit",
+  "prefs",
+  "state",
+]);
+
+function parse(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--fallen-back") {
+      opts.fallenBack = true;
+      continue;
+    }
+    if (!a.startsWith("--")) throw new UsageError(`unexpected argument ${a}`);
+    const name = a.slice(2);
+    if (!VALUE_FLAGS.has(name)) throw new UsageError(`unknown flag ${a}`);
+    const v = argv[++i];
+    if (v === undefined) throw new UsageError(`${a} needs a value`);
+    if (!v.trim()) throw new UsageError(`${a} needs a non-empty value`);
+    opts[name] = v;
+  }
+  return opts;
+}
+
+function int(opts, name, fallback) {
+  if (opts[name] === undefined) return fallback;
+  const raw = opts[name].trim();
+  const n = Number(raw);
+  if (!/^[0-9]+$/.test(raw) || !Number.isInteger(n)) {
+    throw new UsageError(`--${name} must be a whole number`);
+  }
+  return n;
+}
+
+async function record(statePath, decision) {
+  const at = new Date().toISOString();
+  await updateState(statePath, (s) => {
+    const iterations = Array.isArray(s.reviewIterations) ? [...s.reviewIterations] : [];
+    if (iterations.length) {
+      iterations[iterations.length - 1] = {
+        ...iterations[iterations.length - 1],
+        reworkEscalation: { ...decision, at },
+      };
+    }
+    let next = { ...s, reviewIterations: iterations };
+    if (decision.escalate && gatesActive(s)) {
+      next = withDecision(
+        next,
+        decisionEntry({
+          what: `Ran the rework on a higher model (${decision.fromTier} -> ${decision.toTier})`,
+          why:
+            decision.trigger === "still-present"
+              ? "findings were still present after the previous fix"
+              : "this was the last rework round the cap allows",
+          costIfWrong: `one rework round billed at ${decision.toTier} rates`,
+          phase: 2,
+          at,
+        }),
+      );
+    }
+    return next;
+  });
+}
+
+async function main(argv) {
+  const opts = parse(argv);
+  if (!opts["current-tier"]) throw new UsageError("--current-tier is required");
+  const iteration = int(opts, "iteration", undefined);
+  if (iteration === undefined) throw new UsageError("--iteration is required");
+  const prefsPath =
+    opts.prefs ||
+    process.env.MULTI_AGENT_PREFS ||
+    join(homedir(), ".claude", "multi-agent-preferences.json");
+  const prefs = readRegularJson(prefsPath, {}) || {};
+  const decision = decide({
+    iteration,
+    maxIterations: int(opts, "max-iterations", DEFAULT_MAX_ITERATIONS),
+    stillPresent: int(opts, "still-present", 0),
+    currentTier: opts["current-tier"],
+    budget:
+      opts["budget-exit"] !== undefined
+        ? budgetFromExit(int(opts, "budget-exit", undefined))
+        : prefs.global?.costBudget?.enabled === true
+          ? "unchecked"
+          : "disabled",
+    prefs,
+    fallenBack: opts.fallenBack === true,
+  });
+  if (opts.state) {
+    try {
+      await record(opts.state, decision);
+    } catch (err) {
+      writeFileSync(1, `${JSON.stringify(decision)}\n`);
+      process.stderr.write(`rework-escalation: not recorded: ${err.message}\n`);
+      return 3;
+    }
+  }
+  writeFileSync(1, `${JSON.stringify(decision)}\n`);
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`rework-escalation: ${err.message}\n`);
+      process.exit(err instanceof UsageError ? 2 : 3);
+    },
+  );
+}

package/pipeline/scripts/test-strength.mjs

@@ -102,9 +102,10 @@ export function renderTestCommand(template, file) {
 
 /**
  * Run one shell command in its own process group so a timeout kills the whole
- * tree, not only the shell.
+ * tree, not only the shell. `onSpawn` receives the group's pid, so a caller
+ * that exits on a signal can kill the group first.
  */
-function runCommand(command, cwd, timeoutMs) {
+export function runCommand(command, cwd, timeoutMs, { onSpawn } = {}) {
   // NODE_TEST_CONTEXT is set when this script itself runs under `node --test`;
   // inherited, it turns the inner `node --test` into a reporting child that
   // exits 0 whatever its tests did.
@@ -116,6 +117,7 @@ function runCommand(command, cwd, timeoutMs) {
       stdio: ["ignore", "pipe", "pipe"],
       env: { ...env, CI: "1" },
     });
+    if (onSpawn && child.pid) onSpawn(child.pid);
     let output = "";
     const take = (chunk) => {
       if (output.length < MAX_OUTPUT) output += chunk.toString("utf8");
@@ -183,7 +185,7 @@ const WORKTREE_HEAD = "worktree";
  * Built in a private index file, so the caller's index is never written, and
  * never referenced by a ref: nothing but this run can see it.
  */
-function snapshotWorktree(root) {
+export function snapshotWorktree(root) {
   const holder = mkdtempSync(join(tmpdir(), "test-strength-index-"));
   const env = {
     ...process.env,