@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/update-issue-progress.sh

@@ -29,6 +29,54 @@
 
 set -euo 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 "update the issue" || exit 3
+
+# Outbound leak gate. Every byte below is composed at runtime out of command
+# output, error text and file excerpts, any of which can carry a token that was
+# on this machine a second earlier - and once it is in a comment it is in
+# someone else's database. The repo's own leak scanner looks at FILES IN THE
+# REPO and never sees this text. See lib/outbound-gate.mjs.
+ma_outbound_gate() {
+  local body_file="$1" og=""
+  for c in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/outbound-gate.mjs" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/outbound-gate.mjs" \
+           "$HOME/.claude/lib/outbound-gate.mjs" \
+           "$HOME/.copilot/lib/outbound-gate.mjs" \
+           "$HOME/.codex/lib/outbound-gate.mjs"; do
+    [ -f "$c" ] && { og="$c"; break; }
+  done
+  # Missing gate is NOT an open door: refusing to publish beats publishing
+  # unchecked, and the only way this file is absent is a broken install.
+  if [ -z "$og" ]; then
+    echo "outbound-gate.mjs not found - refusing to publish unchecked text." >&2
+    return 7
+  fi
+  node "$og" --file "$body_file"
+}
+
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
+_MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+
+
 # Rewrite the `### Progress` block of the body file ($2) with $1 and print the
 # result to stdout. The replaced region is bounded at the FIRST of:
 #   - a line starting with `<!--` (the legend comment, printed and kept), or
@@ -90,13 +138,10 @@ fi
 # per-project directory ($HOME/.claude/logs/multi-agent/{project}/{taskId}/)
 # - not the ~/.claude/projects/*/state/ path this used to glob, which no
 # writer in the pipeline ever populates.
-AGENT_STATE=""
-for candidate in "$HOME"/.claude/logs/multi-agent/*/"$TASK_ID"/agent-state.json; do
-  if [ -f "$candidate" ]; then
-    AGENT_STATE="$candidate"
-    break
-  fi
-done
+# This globbed ONLY the nested layout. phase-tracker.sh and most Phase 0 paths
+# write flat, so on a real machine the majority of runs resolved to nothing and
+# this script reported "no agent-state.json" for a run whose state existed.
+AGENT_STATE="$(ma_resolve_run_file "$TASK_ID" agent-state.json 2>/dev/null || true)"
 
 if [ -z "$AGENT_STATE" ]; then
   echo "update-issue-progress: no agent-state.json found for task=$TASK_ID" >&2
@@ -154,6 +199,10 @@ if cmp -s "$TMP_BODY" "$TMP_NEW"; then
 fi
 
 # Apply.
+if ! ma_outbound_gate "$TMP_NEW"; then
+  echo "update-issue-progress: outbound gate refused the new body; #$ISSUE_NUM left unchanged" >&2
+  exit 7
+fi
 if ! gh issue edit "$ISSUE_NUM" --repo "$ORG_REPO" --body-file "$TMP_NEW" >/dev/null; then
   echo "update-issue-progress: gh issue edit failed for #$ISSUE_NUM" >&2
   exit 4

package/pipeline/scripts/usage-register.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * usage-register.mjs  -  ask the reporting endpoint for this machine's token.
+ *
+ * WHY THIS EXISTS
+ *
+ * Operational reporting needs two things to work: `usageLog.enabled` true AND a
+ * token that resolves. Since v15.8.0 both are arranged automatically - but only
+ * inside `/multi-agent:update`, as forty lines of shell embedded in a skill. A
+ * new user installs the package, runs `/multi-agent:setup` (which explicitly
+ * says registration happens in update), works for weeks, and never registers.
+ * Their runs emit nothing, and the panel cannot tell that apart from nobody
+ * using the pipeline at all - which is exactly what it looked like.
+ *
+ * So the registration becomes one deterministic call that three places make:
+ * setup (onboarding), update (existing path), and the first run of a machine
+ * that reached neither.
+ *
+ * WHAT IT NEVER DOES
+ *
+ * - It never ships a secret: the token is REQUESTED, and it is write-only.
+ * - It never writes the token to a file. The credential store holds it; prefs
+ *   hold only the name of the entry.
+ * - It never registers when `usageLog.optOut` is true. That is permanent and
+ *   checked before anything else.
+ * - It never fails a caller. Offline, endpoint down, ingest disabled by the
+ *   admin, no credential store: one status line, exit 0.
+ * - It never reports run CONTENT. That is usage-report.mjs's contract, and it
+ *   is coarse metadata only.
+ *
+ * Usage:
+ *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback]
+ *
+ * Exit: always 0. `--json` says what happened; the shell does not need to care.
+ *
+ * @module pipeline/scripts/usage-register
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir, hostname, userInfo } from "node:os";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_ENDPOINT = "https://mmerterden.com/api/usage/ingest";
+const TIMEOUT_MS = 10000;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** The name this machine reports under: the GitHub login, never the git identity. */
+export function reportingUser(prefs, { env = process.env } = {}) {
+  const declared = prefs?.global?.identities?.[0]?.username;
+  if (typeof declared === "string" && declared.trim()) return declared.trim();
+  try {
+    const out = execFileSync("gh", ["api", "user", "--jq", ".login"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (out) return out;
+  } catch {
+    /* gh is optional */
+  }
+  try {
+    return env.USER || userInfo().username || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Should this machine register at all?
+ *
+ * The three "no" answers are deliberately distinguishable: the caller prints
+ * them, and "you opted out" and "we could not reach the endpoint" are different
+ * facts about the same silence.
+ */
+export function decideRegistration(
+  prefs,
+  { env = process.env, hasStoredToken = false, forFeedback = false } = {},
+) {
+  const g = prefs?.global || {};
+  const u = g.usageLog || {};
+  // `optOut` is a choice about PASSIVE collection. /multi-agent:feedback is the
+  // opposite: somebody typed a message meant to be read, and it rides the same
+  // token. So a feedback run may mint one - and it must NOT switch telemetry on
+  // when it does, which is what `enableTelemetry` below is for.
+  if (u.optOut === true && !forFeedback) return { act: false, reason: "opted out" };
+  if (env.MULTI_AGENT_USAGE_TOKEN) return { act: false, reason: "token in environment" };
+  if (typeof u.token === "string" && u.token.trim())
+    return { act: false, reason: "token in prefs" };
+  if (hasStoredToken) return { act: false, reason: "token already onboarded" };
+  return { act: true, reason: "no token resolves" };
+}
+
+/** The /register URL derived from whatever endpoint the prefs name. */
+export function registerUrl(endpoint) {
+  const ep = (endpoint || DEFAULT_ENDPOINT).trim().replace(/\/+$/, "");
+  return ep.endsWith("/ingest") ? `${ep.slice(0, -"/ingest".length)}/register` : `${ep}/register`;
+}
+
+function storedToken(prefs, credStore) {
+  const name = prefs?.global?.keychainMapping?.usage_ingest;
+  if (!name || !existsSync(credStore)) return null;
+  const r = spawnSync("bash", [credStore, "get", name], { encoding: "utf8", timeout: 8000 });
+  const out = (r.stdout || "").trim();
+  return out || null;
+}
+
+async function requestToken(url, body) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    if (!res.ok) return { token: null, why: `endpoint answered ${res.status}` };
+    const json = await res.json().catch(() => null);
+    const token = typeof json?.token === "string" ? json.token.trim() : "";
+    return token ? { token, why: null } : { token: null, why: "endpoint returned no token" };
+  } catch (e) {
+    return {
+      token: null,
+      why: e?.name === "AbortError" ? "endpoint timed out" : "endpoint unreachable",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Write the switch, and the credential-store ENTRY NAME when there is one.
+ *
+ * `entryName` is optional on purpose: a token can resolve from the environment
+ * or from `usageLog.token`, and those machines still need the switch flipped.
+ * Claiming "enabled" while writing nothing is the failure this whole feature is
+ * about, one level smaller.
+ *
+ * The token itself is never written here, whatever the caller passes.
+ */
+export function persistPrefs(prefsPath, entryName = null, { enableTelemetry = true } = {}) {
+  const j = readJson(prefsPath);
+  if (!j) return false;
+  j.global = j.global || {};
+  if (entryName) {
+    j.global.keychainMapping = j.global.keychainMapping || {};
+    j.global.keychainMapping.usage_ingest = entryName;
+  }
+  j.global.usageLog = j.global.usageLog || {};
+  if (enableTelemetry) j.global.usageLog.enabled = true;
+  writeFileSync(prefsPath, `${JSON.stringify(j, null, 2)}\n`);
+  return true;
+}
+
+async function main(argv) {
+  const opts = { quiet: false, json: false, dryRun: false, prefs: null, feedback: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--quiet") opts.quiet = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--feedback") opts.feedback = true;
+    else if (a === "--prefs") opts.prefs = argv[++i];
+  }
+  const HOME = homedir();
+  const prefsPath = opts.prefs || join(HOME, ".claude", "multi-agent-preferences.json");
+  const credStore = join(HOME, ".claude", "lib", "credential-store.sh");
+
+  const say = (line) => {
+    if (!opts.quiet) process.stdout.write(`${line}\n`);
+  };
+  const done = (status, detail) => {
+    if (opts.json) process.stdout.write(`${JSON.stringify({ status, detail })}\n`);
+    return 0;
+  };
+
+  const prefs = readJson(prefsPath);
+  if (!prefs) {
+    // Setup writes this file; nothing here creates it. An installer that seeds
+    // state is the one thing the install contract forbids.
+    say("  -> operational reporting: no preferences file yet (run /multi-agent:setup)");
+    return done("skipped", "no prefs");
+  }
+
+  const has = Boolean(storedToken(prefs, credStore));
+  const decision = decideRegistration(prefs, { hasStoredToken: has, forFeedback: opts.feedback });
+  if (!decision.act) {
+    if (decision.reason !== "opted out") {
+      // Already has a token: make sure the switch is actually on. A token with
+      // enabled:false is the other half of the same silence.
+      if (prefs.global?.usageLog?.enabled !== true && !opts.dryRun) {
+        const name = prefs.global?.keychainMapping?.usage_ingest || null;
+        if (persistPrefs(prefsPath, name)) {
+          say("  -> operational reporting: enabled (a token was already onboarded)");
+          return done("enabled", decision.reason);
+        }
+        say("  -> operational reporting: could not write preferences");
+        return done("unavailable", "prefs write failed");
+      }
+    }
+    say(`  -> operational reporting: unchanged (${decision.reason})`);
+    return done("skipped", decision.reason);
+  }
+
+  const url = registerUrl(prefs.global?.usageLog?.endpoint);
+  const user = reportingUser(prefs);
+  let host = "unknown";
+  try {
+    host = hostname().split(".")[0] || "unknown";
+  } catch {
+    /* a nameless host is still a host */
+  }
+
+  if (opts.dryRun) {
+    say(`  -> operational reporting: would register ${user} with ${url}`);
+    return done("dry-run", url);
+  }
+
+  const { token, why } = await requestToken(url, { u: user, c: host });
+  if (!token) {
+    say(`  -> operational reporting left off (${why})`);
+    return done("unavailable", why);
+  }
+
+  const optedOut = prefs.global?.usageLog?.optOut === true;
+  const entry = `${process.env.USER || user}_Usage_Ingest_Token`;
+  const set = spawnSync("bash", [credStore, "set", entry], {
+    input: token,
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (set.status !== 0) {
+    say("  -> operational reporting left off (the credential store refused the token)");
+    return done("unavailable", "credential store write failed");
+  }
+  persistPrefs(prefsPath, entry, { enableTelemetry: !optedOut });
+  if (optedOut) {
+    say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");
+    return done("registered-feedback-only", entry);
+  }
+  say(
+    "  -> operational reporting: registered this machine (write-only token in the credential store)",
+  );
+  say("     opt out any time: set global.usageLog.optOut=true in multi-agent-preferences.json");
+  return done("registered", entry);
+}
+
+function isEntrypoint() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return import.meta.url === pathToFileURL(arg).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/pipeline/scripts/usage-report.mjs

@@ -9,7 +9,7 @@
  *
  * Enable + configure via prefs.global.usageLog:
  *   { "enabled": true,
- *     "endpoint": "https://mmerterden.vercel.app/api/usage/ingest",
+ *     "endpoint": "https://mmerterden.com/api/usage/ingest",
  *     "token": "<shared ingest token>" }         // token may instead come from
  *                                                 // env MULTI_AGENT_USAGE_TOKEN
  * Nothing is sent when enabled is not true or no token resolves.
@@ -30,7 +30,7 @@ import { createHash } from "crypto";
 import { costUsd } from "./_cost.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ENDPOINT_DEFAULT = "https://mmerterden.vercel.app/api/usage/ingest";
+const ENDPOINT_DEFAULT = "https://mmerterden.com/api/usage/ingest";
 const TIMEOUT_MS = 2500;
 
 // The emitter ships verbatim into ~/.claude, ~/.copilot and ~/.codex, so it must
@@ -609,7 +609,18 @@ async function main() {
 // Windows-safe entry-point check: compare file URLs, never string-split a path.
 const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
-  main().catch(() => process.exit(0));
+  // Exit 0 stays: usage telemetry must never be the reason a run fails, and a
+  // non-zero exit here would propagate into whatever called it.
+  //
+  // But the silence goes. `catch(() => process.exit(0))` reported success for
+  // every failure, so a telemetry path that had been broken for weeks looked
+  // exactly like one that worked - there was no surface on which anyone could
+  // notice. One line on stderr costs nothing and is the difference between a
+  // degraded feature and an invisible one.
+  main().catch((err) => {
+    process.stderr.write(`usage-report: not sent  -  ${err?.message ?? err}\n`);
+    process.exit(0);
+  });
 }
 
 export {

package/pipeline/scripts/validate-analysis-doc.mjs

@@ -41,6 +41,7 @@
 // Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 // A repo-less run (Locked 35) still splits by channel, derived from the evidence:
 // "mobile" and "web" are its platform values. "none" is the narrower case where the
@@ -1019,4 +1020,4 @@ function main() {
   console.log(`validate-analysis-doc: OK (mode=${mode}, ${warns.length} warning(s))`);
 }
 
-main();
+runMain("validate-analysis-doc", main);

package/pipeline/scripts/validate-code-graph.mjs

@@ -162,13 +162,16 @@ export function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -40,6 +40,7 @@
 // Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const REQUIRED_FM = ["run_name", "generated_at", "language", "complaint_count", "graylog_degraded"];
 
@@ -263,4 +264,4 @@ function main() {
   process.exit(0);
 }
 
-main();
+runMain("validate-complaint-doc", main);

package/pipeline/scripts/validate-diff-risk.mjs

@@ -120,13 +120,16 @@ function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

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

@@ -88,13 +88,16 @@ function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

package/pipeline/scripts/validate-triage.mjs

@@ -292,4 +292,6 @@ function validate(raw) {
 const raw = await readInput();
 const result = validate(raw);
 console.log(JSON.stringify(result, null, 2));
-process.exit(result.ok ? result.code : 1);
+// Assigned rather than called: process.exit() would cut this payload short when
+// stdout is a pipe, which is how every caller reads it.
+process.exitCode = result.ok ? result.code : 1;

package/pipeline/scripts/verify-citations.mjs

@@ -45,6 +45,8 @@
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { resolve as resolvePath, sep } from "node:path";
 import { spawnSync } from "node:child_process";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 /**
  * Reject a path before it reaches git.
@@ -423,6 +425,6 @@ function main() {
   process.exit(report.unresolved.length === 0 ? 0 : 1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
+if (invokedDirectly(import.meta.url)) {
+  runMain("verify-citations", main);
 }