@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/run-aggregator.mjs

@@ -38,6 +38,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { costUsd } from "./_cost.mjs";
+import { resolveRunFile, canonicalRunDir } from "./_run-paths.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -82,26 +83,24 @@ function die(msg) {
   process.exit(1);
 }
 
-// phase-tracker.sh writes tracker-state.json (never phase-tracker.json) at
-// $HOME/.claude/logs/multi-agent/<task-id>/ (no <project> segment) - the
-// same drift render-cost-summary.sh/render-agent-log-cost.sh already guard
-// against with a candidate list. Mirror that list here instead of assuming
-// one fixed filename/path.
+// Path resolution lives in _run-paths.mjs: tracker-state.json is written to
+// the flat <root>/<task-id>/ while agent-state.json documents the nested
+// <root>/<project>/<task-id>/, and both layouts are populated in practice.
+// This used to be a hand-rolled candidate list here, a second one in
+// render-cost-summary.sh and a third in render-agent-log-cost.sh.
 function resolveTrackerCandidates() {
   const candidates = [];
   if (flags["task-dir"]) {
     candidates.push(join(flags["task-dir"], "tracker-state.json"));
   }
   if (flags["task-id"]) {
-    const HOME = process.env.HOME || process.env.USERPROFILE;
-    if (!HOME) die("neither HOME nor USERPROFILE is set  -  pass --task-dir");
-    const taskId = String(flags["task-id"]);
-    if (flags.project) {
-      candidates.push(
-        join(HOME, ".claude", "logs", "multi-agent", flags.project, taskId, "tracker-state.json"),
-      );
-    }
-    candidates.push(join(HOME, ".claude", "logs", "multi-agent", taskId, "tracker-state.json"));
+    const found = resolveRunFile(flags["task-id"], "tracker-state.json", flags.project);
+    if (found) candidates.push(found);
+    // Keep the canonical path in the list even when nothing exists yet, so the
+    // "not found" message names a path instead of an empty candidate set.
+    candidates.push(
+      join(canonicalRunDir(String(flags["task-id"]), flags.project), "tracker-state.json"),
+    );
   }
   if (!candidates.length) die("either --task-dir or --task-id is required");
   return candidates;

package/pipeline/scripts/run-metrics.mjs

@@ -215,5 +215,7 @@ const metrics = {
   },
 };
 
+// No process.exit(0) here. Exit code 0 is already the default, and calling it
+// would terminate before this write drained - stdout to a pipe is asynchronous,
+// so `run-metrics.mjs | jq` would read a payload cut at a buffer boundary.
 console.log(JSON.stringify(metrics, null, 2));
-process.exit(0);

package/pipeline/scripts/runs-index.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * @file runs-index.mjs  -  one deterministic answer to "what runs exist and
+ * where is each one".
+ *
+ * `/multi-agent:status` used to answer this by telling the model to go and find
+ * the files itself: scan three hard-coded `.worktrees/` paths, then `find` the
+ * log tree at one depth, then merge. Three problems with that. It cannot be
+ * called by anything that is not a model, the depth was wrong for half the
+ * layouts, and two invocations could disagree because nothing pinned the
+ * traversal. A UI, a gate, or a second phase reading the same question got a
+ * different answer than the terminal did.
+ *
+ * This is the producer. `--json` and the human table are rendered from the SAME
+ * in-memory records, so a dashboard and a terminal cannot disagree - the rule
+ * autopilot-status.sh already follows for the autopilot half of the picture.
+ *
+ * Grouping follows the contract in commands/multi-agent/status/SKILL.md 3b,
+ * including its final clause: a run with no `status` is placed in no group at
+ * all. Unknown is not a finding, and calling it dead is the same false claim in
+ * the other direction.
+ *
+ * Read-only. Never writes, never migrates, never deletes.
+ *
+ * Usage:
+ *   node runs-index.mjs                 # human table, grouped
+ *   node runs-index.mjs --json          # the same records as JSON
+ *   node runs-index.mjs --group waiting # one group only
+ *   node runs-index.mjs --task-id <id>  # one run
+ *
+ * Exit codes:
+ *   0  -  answered (including "no runs")
+ *   2  -  usage error
+ *
+ * @module pipeline/scripts/runs-index
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { costUsd } from "./_cost.mjs";
+import { listRuns, logsRoot, resolveRunDir, taskIdVariants } from "./_run-paths.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const GROUPS = {
+  waiting: "Waiting on you",
+  stopped: "Stopped mid-development",
+  question: "Left at a question",
+  unknown: "Status not recorded",
+};
+
+function parseArgs(argv) {
+  const flags = { json: false, group: null, taskId: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") flags.json = true;
+    else if (a === "--group") flags.group = argv[++i];
+    else if (a.startsWith("--group=")) flags.group = a.slice(8);
+    else if (a === "--task-id") flags.taskId = argv[++i];
+    else if (a.startsWith("--task-id=")) flags.taskId = a.slice(10);
+    else if (a === "-h" || a === "--help") flags.help = true;
+    else {
+      process.stderr.write(`runs-index: unknown argument ${a}\n`);
+      process.exit(2);
+    }
+  }
+  if (flags.group && !Object.hasOwn(GROUPS, flags.group)) {
+    process.stderr.write(
+      `runs-index: unknown group ${flags.group} (want ${Object.keys(GROUPS).join(", ")})\n`,
+    );
+    process.exit(2);
+  }
+  return flags;
+}
+
+function readJson(path) {
+  if (!path || !existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    // A truncated state file is a fact about the run, not a reason to refuse
+    // the whole index. It surfaces as `stateReadable: false`.
+    return null;
+  }
+}
+
+function firstFile(dir, name) {
+  for (const base of [dir, join(dir, "artifacts")]) {
+    const p = join(base, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+let COST_TABLE = null;
+function rateFor(model) {
+  if (!COST_TABLE) {
+    COST_TABLE = readJson(new URL("./cost-table.json", import.meta.url).pathname) ?? { prices: {} };
+  }
+  if (!model) return null;
+  const prices = COST_TABLE.prices ?? {};
+  // phase-tracker.sh stores the short tier name ("opus", "fable"), which is the
+  // table's own key - the same lookup run-aggregator.mjs does. A caller that
+  // stored the full model id instead is matched on the table's `modelId`
+  // rather than guessed at by prefix: "gpt-5.6" is a prefix of "gpt-5.6-terra"
+  // and those are two different prices.
+  if (prices[model]) return prices[model];
+  for (const rate of Object.values(prices)) {
+    if (rate?.modelId === model) return rate;
+  }
+  return null;
+}
+
+/**
+ * Phase rows plus token/cost totals, from the tracker document.
+ *
+ * @param {object|null} tracker
+ */
+function summarisePhases(tracker) {
+  const phases = Array.isArray(tracker?.phases) ? tracker.phases : [];
+  let tokensIn = 0;
+  let tokensOut = 0;
+  let tokensCached = 0;
+  let usd = 0;
+  const rows = phases.map((p) => {
+    // phase-tracker.sh writes flat `tokens_in` / `tokens_out` / `tokens_cached`
+    // on each phase, not a nested `tokens` object.
+    const tin = Number(p.tokens_in ?? 0) || 0;
+    const tout = Number(p.tokens_out ?? 0) || 0;
+    const tcached = Number(p.tokens_cached ?? 0) || 0;
+    tokensIn += tin;
+    tokensOut += tout;
+    tokensCached += tcached;
+    const c = costUsd(rateFor(p.model), tin, tout, tcached);
+    if (typeof c === "number") usd += c;
+    return {
+      id: String(p.id ?? ""),
+      name: p.name ?? "",
+      status: p.status ?? "pending",
+      model: p.model ?? null,
+      startedAt: p.started_at ?? null,
+      completedAt: p.completed_at ?? null,
+      now: p.now ?? null,
+      subs: Array.isArray(p.subs) ? p.subs.length : 0,
+    };
+  });
+  return {
+    phases: rows,
+    startedAt: tracker?.started_at ?? null,
+    tokens: { in: tokensIn, out: tokensOut, cached: tokensCached },
+    estUsd: Number(usd.toFixed(4)),
+  };
+}
+
+/**
+ * The group a run belongs to, per status/SKILL.md 3b.
+ *
+ * @param {object|null} state
+ * @returns {"waiting"|"stopped"|"question"|"unknown"}
+ */
+function groupOf(state) {
+  const status = state?.status;
+  if (!status) return "unknown";
+  const phase = Number(state?.currentPhase);
+  const prUrl = state?.pr?.url ?? state?.prUrl ?? null;
+  if (status === "awaiting_input" || status === "awaiting-user-test-main-checkout")
+    return "waiting";
+  if (prUrl) return "waiting";
+  if (Number.isFinite(phase) && phase >= 6) return "waiting";
+  if (Number.isFinite(phase) && phase === 0) return "question";
+  return "stopped";
+}
+
+/**
+ * Every run, enriched, in one stable order.
+ *
+ * @returns {object[]}
+ */
+export function buildIndex() {
+  return listRuns().map((run) => {
+    const statePath = firstFile(run.dir, "agent-state.json");
+    const trackerPath = firstFile(run.dir, "tracker-state.json");
+    const state = readJson(statePath);
+    const tracker = readJson(trackerPath);
+    const phases = summarisePhases(tracker);
+    const prUrl = state?.pr?.url ?? state?.prUrl ?? null;
+    return {
+      taskId: run.taskId,
+      project: run.project ?? run.projectHint ?? null,
+      dir: run.dir,
+      layout: run.layout,
+      duplicateOf: run.duplicateOf,
+      salvaged: Boolean(statePath && statePath.includes(`${run.dir}/artifacts/`)),
+      // What KIND of record this is, before asking whether it is healthy.
+      //
+      // 74 of the 103 runs on this machine have a tracker file and no agent
+      // state, and the first version of this index called every one of them
+      // `stateReadable: false` - so a panel built on it announced "74 runs
+      // could not be read" about records that are not damaged and never had
+      // agent state to begin with. `/multi-agent:analysis` says so in its own
+      // description ("no worktree, no commits, no dev chain"), and design-check
+      // is the same shape.
+      //
+      // Derived from what is on disk, not from the task id: `ANALYSIS-` and
+      // `DC-` are naming conventions, and a convention is not a contract.
+      kind: statePath ? "pipeline" : trackerPath ? "tracker-only" : "empty",
+      // Now the health question, and it only applies where state was expected.
+      // A tracker-only record is `true` because there is nothing it failed to
+      // read; "could not read" and "there is none" are different answers and
+      // only the first one asks anyone to do something.
+      stateReadable: statePath ? Boolean(state) : true,
+      status: state?.status ?? null,
+      currentPhase: Number.isFinite(Number(state?.currentPhase))
+        ? Number(state.currentPhase)
+        : null,
+      branch: state?.branch ?? state?.branchName ?? null,
+      baseBranch: state?.baseBranch ?? null,
+      startedAt: state?.startedAt ?? phases.startedAt,
+      worktreePath: state?.worktreePath ?? null,
+      prUrl,
+      autopilot: Boolean(state?.autopilot),
+      schemaVersion: state?.schemaVersion ?? null,
+      rev: Number.isInteger(state?.rev) ? state.rev : null,
+      group: groupOf(state),
+      phases: phases.phases,
+      tokens: phases.tokens,
+      estUsd: phases.estUsd,
+      // How many tracker writes went through without the lock. Non-zero means
+      // two writers were in the critical section and one of their token
+      // deltas was dropped, so the numbers on this run are LOW. Reporting the
+      // count rather than the loss, because the size of what was dropped is
+      // exactly what nobody measured.
+      unlockedWrites: Number.isInteger(tracker?.unlockedWrites) ? tracker.unlockedWrites : 0,
+    };
+  });
+}
+
+function fmtDuration(startedAt) {
+  if (!startedAt) return "-";
+  const t = Date.parse(startedAt);
+  if (!Number.isFinite(t)) return "-";
+  const mins = Math.max(0, Math.round((Date.now() - t) / 60000));
+  if (mins < 60) return `${mins}m`;
+  const h = Math.floor(mins / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+function renderHuman(records) {
+  const out = [];
+  const total = records.length;
+  out.push(`multi-agent runs  -  ${total} under ${logsRoot()}`);
+
+  const dupes = records.filter((r) => r.duplicateOf);
+  if (dupes.length) {
+    out.push(
+      `  ${dupes.length} run(s) also have a copy in the other directory layout; ` +
+        `the newer one is shown. migrate-state.mjs --all reports them.`,
+    );
+  }
+
+  for (const key of Object.keys(GROUPS)) {
+    const rows = records.filter((r) => r.group === key);
+    if (!rows.length) continue;
+    out.push("");
+    out.push(`${GROUPS[key]}  (${rows.length})`);
+    out.push(
+      "  ID                              Phase  Status            Branch                    Age    ~USD",
+    );
+    for (const r of rows) {
+      const phase = r.currentPhase === null ? " -" : `${r.currentPhase}/7`;
+      out.push(
+        "  " +
+          [
+            r.taskId.padEnd(30).slice(0, 30),
+            String(phase).padStart(5),
+            (r.status ?? "-").padEnd(17).slice(0, 17),
+            (r.branch ?? "-").padEnd(24).slice(0, 24),
+            fmtDuration(r.startedAt).padStart(5),
+            (r.estUsd ? r.estUsd.toFixed(2) : "-").padStart(6),
+          ].join("  "),
+      );
+    }
+  }
+
+  const hints = {
+    waiting: "resume #N  -  the work landed, it needs your answer",
+    stopped: "resume #N  or  kill #N",
+    question: "garbage-collect --abandoned  -  nothing was built",
+  };
+  const present = Object.keys(hints).filter((k) => records.some((r) => r.group === k));
+  if (present.length) {
+    out.push("");
+    for (const k of present) out.push(`  ${GROUPS[k]}: ${hints[k]}`);
+  }
+  return out.join("\n");
+}
+
+function main() {
+  const flags = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    process.stdout.write(
+      "Usage: runs-index.mjs [--json] [--group waiting|stopped|question|unknown] [--task-id <id>]\n",
+    );
+    return 0;
+  }
+
+  let records = buildIndex();
+
+  if (flags.taskId) {
+    const wanted = new Set(taskIdVariants(flags.taskId));
+    records = records.filter((r) => wanted.has(r.taskId));
+    if (!records.length) {
+      const dir = resolveRunDir(flags.taskId);
+      process.stderr.write(
+        `runs-index: no run for ${flags.taskId}${dir ? ` (directory ${dir} has no markers)` : ""}\n`,
+      );
+      return 0;
+    }
+  }
+  if (flags.group) records = records.filter((r) => r.group === flags.group);
+
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify({ logsRoot: logsRoot(), count: records.length, runs: records }, null, 2) +
+        "\n",
+    );
+  } else {
+    process.stdout.write(renderHuman(records) + "\n");
+  }
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  // process.exitCode, not process.exit(): stdout to a PIPE is asynchronous and
+  // process.exit() throws away whatever has not drained. 103 runs render to
+  // ~200KB of JSON, so a caller doing `runs-index.mjs --json | jq` received the
+  // first 64KB and a parse error. A terminal hid it, because stdout to a TTY is
+  // synchronous - and a terminal is where this was tested.
+  runMain("runs-index", () => {
+    process.exitCode = main();
+  });
+}

package/pipeline/scripts/scorecard-snapshot.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * scorecard-snapshot.mjs  -  keep what the scorecard said, and say what moved.
+ *
+ * The scorecard answers "does every mechanical claim hold right now". It
+ * cannot answer "is this better or worse than last week", and that second
+ * question is the one that catches slow rot: a metric that has been failing
+ * for a month reads identically to one that broke an hour ago.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: collapse the result into a 0-100 score.
+ * ruflo's scorecard does, and the discipline worth taking from it is
+ * "measurable and comparable over time", not the number. The scorecard already
+ * reports twelve measured metrics AND four it refuses to measure - a single
+ * figure would hide both halves, and an unmeasured category would silently
+ * count as zero or as full marks depending on an arithmetic choice nobody
+ * would ever read. A diff keeps every metric answering for itself.
+ *
+ * Snapshots live in ~/.claude/state/scorecard/<iso>.json and are never pruned
+ * by this script: they are small, and a history that deletes itself cannot
+ * answer the question it was kept for.
+ *
+ * Usage:
+ *   scorecard-snapshot.mjs --save             run the scorecard, store a snapshot
+ *   scorecard-snapshot.mjs --diff             latest vs the one before it
+ *   scorecard-snapshot.mjs --diff a.json b.json   two snapshots by path
+ *   scorecard-snapshot.mjs --list             what is stored
+ *
+ * Exit codes:
+ *   0  -  nothing regressed (or a save succeeded)
+ *   1  -  at least one metric that used to pass now fails
+ *   2  -  usage error, or not enough snapshots to compare
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const STORE = process.env.SCORECARD_STORE || join(homedir(), ".claude", "state", "scorecard");
+
+/** Metric identity. Category plus metric name, because neither is unique alone. */
+const keyOf = (r) => `${r.category} :: ${r.metric}`;
+
+function runScorecard() {
+  // `--json` prints the report on stdout; a failing metric is a non-zero exit
+  // and is exactly the case worth snapshotting, so the status is captured
+  // rather than thrown.
+  try {
+    return JSON.parse(
+      execFileSync("node", ["pipeline/scripts/scorecard.mjs", "--json"], {
+        cwd: ROOT,
+        encoding: "utf-8",
+        maxBuffer: 32 * 1024 * 1024,
+      }),
+    );
+  } catch (err) {
+    const out = err?.stdout;
+    if (typeof out === "string" && out.trim().startsWith("{")) return JSON.parse(out);
+    throw new Error(`scorecard did not produce JSON: ${err?.message ?? err}`, { cause: err });
+  }
+}
+
+function snapshots() {
+  if (!existsSync(STORE)) return [];
+  return (
+    readdirSync(STORE)
+      .filter((f) => f.endsWith(".json"))
+      // ISO-8601 sorts lexically in time order, which is the whole reason the
+      // file is named after the timestamp rather than a counter.
+      .sort()
+      .map((f) => join(STORE, f))
+  );
+}
+
+function save() {
+  const report = runScorecard();
+  mkdirSync(STORE, { recursive: true });
+  const at = new Date().toISOString().replace(/[:.]/g, "-");
+  const path = join(STORE, `${at}.json`);
+  writeFileSync(path, JSON.stringify({ at: new Date().toISOString(), ...report }, null, 2) + "\n");
+  process.stdout.write(`scorecard snapshot: ${path}\n`);
+  process.stdout.write(`  ${report.passed} passed, ${report.failed} failed\n`);
+  return 0;
+}
+
+function diff(aPath, bPath) {
+  const a = JSON.parse(readFileSync(aPath, "utf-8"));
+  const b = JSON.parse(readFileSync(bPath, "utf-8"));
+  // UNMEASURED rows carry no `ok` at all - they are the categories the
+  // scorecard refuses to score. Comparing verdicts across them would invent
+  // one, which is the thing that section exists to avoid.
+  const measured = (rs) => (rs || []).filter((r) => r.kind !== "UNMEASURED");
+  const ma = new Map(measured(a.results).map((r) => [keyOf(r), r]));
+  const mb = new Map(measured(b.results).map((r) => [keyOf(r), r]));
+
+  const regressed = [];
+  const fixed = [];
+  const added = [];
+  const removed = [];
+  const changed = [];
+
+  for (const [k, rb] of mb) {
+    const ra = ma.get(k);
+    if (!ra) {
+      added.push(rb);
+      continue;
+    }
+    if (ra.ok && !rb.ok) regressed.push({ k, ra, rb });
+    else if (!ra.ok && rb.ok) fixed.push({ k, ra, rb });
+    // A metric whose verdict held but whose DETAIL moved is the early warning:
+    // coverage sliding from 72 to 69 passes the floor and is still the thing
+    // that will fail next month.
+    else if (ra.detail !== rb.detail) changed.push({ k, ra, rb });
+  }
+  for (const [k, ra] of ma) if (!mb.has(k)) removed.push({ k, ra });
+
+  const out = [];
+  out.push(`scorecard diff  -  ${a.at ?? aPath} → ${b.at ?? bPath}`);
+  out.push(`  ${a.passed}/${a.passed + a.failed} → ${b.passed}/${b.passed + b.failed} passing`);
+  const section = (title, rows, fmt) => {
+    if (!rows.length) return;
+    out.push("");
+    out.push(`${title} (${rows.length})`);
+    for (const r of rows) out.push(`  ${fmt(r)}`);
+  };
+  section("REGRESSED", regressed, ({ k, rb }) => `${k}\n      now: ${rb.detail ?? "(no detail)"}`);
+  section("FIXED", fixed, ({ k, rb }) => `${k}\n      now: ${rb.detail ?? "(no detail)"}`);
+  section("NEW METRIC", added, (r) => `${keyOf(r)} ${r.ok ? "passing" : "FAILING"}`);
+  section("METRIC GONE", removed, ({ k }) => `${k}  -  no longer measured`);
+  section(
+    "SAME VERDICT, DIFFERENT NUMBERS",
+    changed,
+    ({ k, ra, rb }) =>
+      `${k}\n      was: ${ra.detail ?? "(none)"}\n      now: ${rb.detail ?? "(none)"}`,
+  );
+
+  if (!regressed.length && !fixed.length && !added.length && !removed.length && !changed.length) {
+    out.push("");
+    out.push("  nothing moved");
+  }
+  process.stdout.write(out.join("\n") + "\n");
+  return regressed.length ? 1 : 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--save")) return save();
+  if (args.includes("--list")) {
+    const s = snapshots();
+    process.stdout.write(s.length ? s.join("\n") + "\n" : `no snapshots under ${STORE}\n`);
+    return 0;
+  }
+  if (args.includes("--diff")) {
+    const paths = args.filter((a) => !a.startsWith("--"));
+    if (paths.length === 2) return diff(paths[0], paths[1]);
+    const s = snapshots();
+    if (s.length < 2) {
+      process.stderr.write(
+        `need two snapshots to compare, found ${s.length} under ${STORE}\n` +
+          `  take one with: node pipeline/scripts/scorecard-snapshot.mjs --save\n`,
+      );
+      return 2;
+    }
+    return diff(s[s.length - 2], s[s.length - 1]);
+  }
+  process.stderr.write("usage: scorecard-snapshot.mjs --save | --diff [a.json b.json] | --list\n");
+  return 2;
+}
+
+// `process.exitCode`, never `process.exit()`: stdout to a pipe is asynchronous
+// and exit() discards whatever has not drained, which truncated two scripts in
+// this repo at a buffer boundary and only ever when piped.
+runMain("scorecard-snapshot", () => {
+  process.exitCode = main();
+});

package/pipeline/scripts/search-logs.sh

@@ -30,6 +30,24 @@
 
 set -uo pipefail
 
+# jq is not optional on this path. Without the guard below a missing binary
+# renders as EMPTY DATA and the work continues on it; see lib/require-jq.sh.
+for _rq in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/require-jq.sh" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/require-jq.sh" \
+           "$HOME/.claude/lib/require-jq.sh" \
+           "$HOME/.copilot/lib/require-jq.sh" \
+           "$HOME/.codex/lib/require-jq.sh"; do
+  [ -f "$_rq" ] || continue
+  # shellcheck source=/dev/null
+  . "$_rq" && break
+done
+unset _rq
+if ! command -v ma_require_jq >/dev/null 2>&1; then
+  # The helper itself is missing, which is an install problem, not a jq one.
+  ma_require_jq() { command -v jq >/dev/null 2>&1 || { echo "jq not found - cannot ${1:-continue}." >&2; return 1; }; }
+fi
+ma_require_jq "search the logs" || exit 3
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 ROOT="$HOME/.claude/logs/multi-agent"

package/pipeline/scripts/test-gap-scan.mjs

@@ -392,8 +392,9 @@ function main() {
     gaps,
   };
 
+  // Returning, not exiting: `gaps` grows with the repo and process.exit() would
+  // cut the payload at the pipe buffer.
   process.stdout.write(PRETTY ? JSON.stringify(out, null, 2) + "\n" : JSON.stringify(out) + "\n");
-  process.exit(0);
 }
 
 try {

package/pipeline/scripts/test-integrity-gate.mjs

@@ -29,6 +29,7 @@
  * only on a setup error (unreadable/invalid input is treated as "no findings").
  */
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const args = process.argv.slice(2);
 const fileFlag = args.indexOf("--file");
@@ -92,4 +93,4 @@ function main() {
   );
 }
 
-main();
+runMain("test-integrity-gate", main);