@mmerterden/multi-agent-pipeline 17.6.0 → 18.0.0

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);
 }

package/pipeline/scripts/verify.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * verify.mjs  -  "is this install the thing that was published".
+ *
+ * Two questions, and they fail in different directions.
+ *
+ * 1. PACKAGE. Every file the package shipped, against the SHA-256 recorded in
+ *    manifest.json at publish time. A file that differs was edited after
+ *    install or arrived damaged; a file that is missing was never written.
+ * 2. INSTALL. ~/.claude holds a COPY of the package's pipeline tree, made by
+ *    install.js. From the moment it is written the two drift independently,
+ *    and both directions are real: an edit in ~/.claude is a change with no
+ *    source, and a file the installer skipped is a script the docs describe
+ *    and nobody has.
+ *
+ * Only the Claude tree is compared byte for byte. The Copilot and Codex trees
+ * are path-rewritten by the installer on purpose, so a byte difference there is
+ * the design rather than the bug, and they are reported as counts.
+ *
+ * What a green result means, stated plainly because the opposite is easy to
+ * imply: it means the bytes match what the publisher recorded. It is not proof
+ * of who published them. The manifest, the signature and this verifier all
+ * travel inside the same tarball, so anyone able to rewrite one can rewrite the
+ * others - provenance is npm's integrity field, not ours. This catches damage,
+ * partial installs and post-install edits, which are the failures that actually
+ * happen.
+ *
+ * Usage:
+ *   verify.mjs                 both questions, human output
+ *   verify.mjs --package       package integrity only
+ *   verify.mjs --install       install drift only
+ *   verify.mjs --json
+ *
+ * Exit codes:
+ *   0  everything matches
+ *   1  a difference was found
+ *   2  nothing to verify (no manifest - a dev checkout, or a pre-manifest version)
+ */
+
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const MANIFEST = join(ROOT, "manifest.json");
+
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const json = has("--json");
+
+/**
+ * The ed25519 public key a signature is checked against. It comes from the
+ * environment and nothing is pinned in this file yet - so on a stock install a
+ * signed manifest reports "signed, no public key to check it against" rather
+ * than claiming valid. That is the honest state: a signature nobody can check
+ * is not a signature that passed, and hard-coding a key here before there is a
+ * release key to hard-code would be the opposite.
+ */
+const PUBLIC_KEY = process.env.MULTI_AGENT_SIGNING_PUBKEY || "";
+
+const sha256 = (p) => createHash("sha256").update(readFileSync(p)).digest("hex");
+
+/**
+ * Walk a tree, following symlinks but never twice.
+ *
+ * Following them is required rather than optional: `install --link` puts a
+ * symlink at ~/.claude/scripts, and a walker that skipped symlinks would report
+ * a linked install as entirely missing. The cost is that a link pointing at an
+ * ancestor turns the walk into a loop, so every directory is recorded by its
+ * RESOLVED path and visited once.
+ */
+function walk(dir, base = dir, out = [], seen = new Set()) {
+  let real;
+  try {
+    real = realpathSync(dir);
+  } catch {
+    return out;
+  }
+  if (seen.has(real)) return out;
+  seen.add(real);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    if (name === ".DS_Store" || name === "__pycache__") continue;
+    const abs = join(dir, name);
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walk(abs, base, out, seen);
+    else out.push(relative(base, abs));
+  }
+  return out;
+}
+
+// --- 1. package integrity ----------------------------------------------------
+
+function verifyPackage() {
+  const manifest = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+  const changed = [];
+  const missing = [];
+  for (const [rel, want] of Object.entries(manifest.files)) {
+    const abs = join(ROOT, rel);
+    if (!existsSync(abs)) {
+      missing.push(rel);
+      continue;
+    }
+    if (sha256(abs) !== want) changed.push(rel);
+  }
+
+  let signature = "unsigned";
+  const sigPath = join(ROOT, "manifest.sig");
+  if (existsSync(sigPath)) {
+    if (!PUBLIC_KEY) signature = "signed, no public key to check it against";
+    else {
+      try {
+        const ok = cryptoVerify(
+          null,
+          Buffer.from(readFileSync(MANIFEST)),
+          createPublicKey(PUBLIC_KEY),
+          Buffer.from(readFileSync(sigPath, "utf-8").trim(), "base64"),
+        );
+        signature = ok ? "valid" : "INVALID";
+      } catch (err) {
+        signature = `unverifiable: ${err?.message ?? err}`;
+      }
+    }
+  }
+
+  return {
+    version: manifest.version,
+    commit: manifest.commit,
+    fileCount: manifest.fileCount,
+    changed,
+    missing,
+    signature,
+    ok: changed.length === 0 && missing.length === 0 && signature !== "INVALID",
+  };
+}
+
+// --- 2. install drift --------------------------------------------------------
+
+/**
+ * The trees install.js writes into ~/.claude, and how each one may be compared.
+ * Kept as data rather than asked of the installer, because the installer's job
+ * is to WRITE them and a verifier that asks the writer what it wrote proves
+ * nothing.
+ *
+ * `bytes` means the copy is verbatim and a difference is drift. `presence` is
+ * for commands/, where install.js rewrites each SKILL.md's `description` into
+ * the user's outputLanguage - every file differs there BY DESIGN, so comparing
+ * bytes would report 57 findings on a healthy machine and teach everyone to
+ * ignore the whole report.
+ */
+const CLAUDE_TREES = [
+  ["scripts", "scripts", "bytes"],
+  ["lib", "lib", "bytes"],
+  ["multi-agent-refs", "multi-agent-refs", "bytes"],
+  ["agents", "agents", "bytes"],
+  ["commands/multi-agent", "commands/multi-agent", "presence"],
+];
+
+/**
+ * Files the package carries but the installer deliberately does not write:
+ * smokes, linters, fixtures and the rest of the maintainer surface. Without
+ * this filter every one of them reads as "the installer skipped a file", which
+ * is 251 false findings on a correct install.
+ */
+async function devOnly() {
+  try {
+    const mod = await import(new URL("../../install/_dev-only-files.mjs", import.meta.url).href);
+    return mod.isDevOnlyScript;
+  } catch {
+    // No filter available: say so by filtering nothing, and let the counts be
+    // wrong loudly rather than silently.
+    return null;
+  }
+}
+
+async function verifyInstall() {
+  const home = homedir();
+  const claude = join(home, ".claude");
+  if (!existsSync(claude)) {
+    return { present: false, reason: "no ~/.claude on this machine", ok: true, trees: [] };
+  }
+
+  const isDevOnly = await devOnly();
+  const trees = [];
+  let differing = 0;
+  let absent = 0;
+  for (const [srcRel, dstRel, mode] of CLAUDE_TREES) {
+    const src = join(ROOT, "pipeline", srcRel);
+    const dst = join(claude, dstRel);
+    if (!existsSync(src)) continue;
+    const srcFiles = walk(src).filter(
+      (rel) => !(srcRel === "scripts" && isDevOnly && isDevOnly(rel)),
+    );
+    const changed = [];
+    const missing = [];
+    for (const rel of srcFiles) {
+      const b = join(dst, rel);
+      if (!existsSync(b)) {
+        missing.push(rel);
+        continue;
+      }
+      if (mode === "bytes" && sha256(join(src, rel)) !== sha256(b)) changed.push(rel);
+    }
+    differing += changed.length;
+    absent += missing.length;
+    trees.push({ tree: dstRel, mode, files: srcFiles.length, changed, missing });
+  }
+
+  const others = [".copilot", ".codex"].filter((h) => existsSync(join(home, h)));
+
+  return {
+    present: true,
+    trees,
+    differing,
+    absent,
+    otherHosts: others,
+    ok: differing === 0 && absent === 0,
+  };
+}
+
+// --- output ------------------------------------------------------------------
+
+async function main() {
+  const wantPackage = has("--package") || !has("--install");
+  const wantInstall = has("--install") || !has("--package");
+
+  if (wantPackage && !existsSync(MANIFEST)) {
+    const msg =
+      "no manifest.json - this is a source checkout or a version published before manifests existed";
+    if (json)
+      process.stdout.write(`${JSON.stringify({ kind: "UNVERIFIABLE", reason: msg }, null, 2)}\n`);
+    else process.stdout.write(`UNVERIFIABLE: ${msg}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const pkg = wantPackage ? verifyPackage() : null;
+  const inst = wantInstall ? await verifyInstall() : null;
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ package: pkg, install: inst }, null, 2)}\n`);
+  } else {
+    if (pkg) {
+      process.stdout.write(
+        `paket: ${pkg.version} (${pkg.commit?.slice(0, 12) ?? "commit bilinmiyor"}) - ${pkg.fileCount} dosya, imza: ${pkg.signature}\n`,
+      );
+      if (!pkg.changed.length && !pkg.missing.length)
+        process.stdout.write("  butun dosyalar yayinlandigi gibi\n");
+      const SHOWN = 20;
+      for (const f of pkg.changed.slice(0, SHOWN)) process.stdout.write(`  ! degismis: ${f}\n`);
+      for (const f of pkg.missing.slice(0, SHOWN)) process.stdout.write(`  ! eksik:    ${f}\n`);
+      // Counted per list against what was actually PRINTED. Subtracting a flat
+      // 40 from the combined total spent a budget the lists had not used: with
+      // 25 changed and 0 missing it printed 20, hid 5, and said nothing - a
+      // tampered install under-reported by up to twenty files with no sign.
+      const hidden =
+        Math.max(0, pkg.changed.length - SHOWN) + Math.max(0, pkg.missing.length - SHOWN);
+      if (hidden > 0) process.stdout.write(`  ... ve ${hidden} dosya daha\n`);
+    }
+    if (inst) {
+      if (!inst.present) process.stdout.write(`kurulum: ${inst.reason}\n`);
+      else {
+        const total = inst.trees.reduce((a, t) => a + t.files, 0);
+        process.stdout.write(
+          `kurulum: ~/.claude - ${inst.trees.length} agac, ${total} dosya karsilastirildi\n`,
+        );
+        for (const t of inst.trees) {
+          if (!t.changed.length && !t.missing.length) continue;
+          const how =
+            t.mode === "presence" ? " (yalnizca varlik: aciklamalar kurulumda cevriliyor)" : "";
+          process.stdout.write(
+            `  ${t.tree}: ${t.changed.length} farkli, ${t.missing.length} eksik${how}\n`,
+          );
+          for (const f of [...t.changed.slice(0, 5)]) process.stdout.write(`    ! ${f}\n`);
+          for (const f of [...t.missing.slice(0, 5)])
+            process.stdout.write(`    ? ${f} (hic yazilmamis)\n`);
+        }
+        if (inst.ok) process.stdout.write("  kaynakla birebir ayni\n");
+        if (inst.otherHosts.length)
+          process.stdout.write(
+            `  ${inst.otherHosts.join(", ")} kurulu - yollari kurulumda yeniden yazildigi icin bayt karsilastirmasi yapilmadi\n`,
+          );
+      }
+    }
+  }
+
+  const bad = (pkg && !pkg.ok) || (inst && !inst.ok);
+  process.exitCode = bad ? 1 : 0;
+}
+
+// Importable AND runnable: index.js calls main() for `multi-agent-pipeline
+// verify`, and the direct-run guard keeps a bare `node verify.mjs` behaving
+// the same way every other script here does.
+export { main };
+
+/**
+ * realpath, not a string compare against argv[1]. Two ordinary situations break
+ * the naive form: macOS hands out /var/folders/... paths that resolve to
+ * /private/var/folders/..., and `install --link` puts a SYMLINK at
+ * ~/.claude/scripts/verify.mjs - in both cases import.meta.url is the resolved
+ * path, argv[1] is not, and the script silently does nothing at all.
+ */
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  runMain("verify", main);
+}

package/pipeline/scripts/worktree-finalize.sh

@@ -28,7 +28,7 @@
 #   0  removed (or dry-run that would remove)
 #   3  SKIPPED by a safety precondition  -  not an error, reason is reported
 #   1  usage / hard error
-set -uo pipefail
+set -euo pipefail
 
 WORKTREE=""; PROJECT_ROOT=""; TASK_ID=""; PROJECT=""; BRANCH=""
 LOGS_ROOT="${HOME}/.claude/logs/multi-agent"
@@ -97,6 +97,10 @@ skip() { REASON="$1"; emit; exit 3; }
 # preference at all, because turning it off appears to work and does nothing.
 PREFS="${PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
 if [ -f "$PREFS" ] && command -v node >/dev/null 2>&1; then
+  # `|| echo true` on the far side already covers a node that throws: an
+  # unreadable preference file reads as "not set", which is the default. Noted
+  # here because it is the one assignment in this file that was ALREADY safe
+  # under `set -e`, and the next reader should not have to re-derive that.
   enabled="$(node -e '
     const fs=require("fs");
     try {
@@ -173,6 +177,9 @@ fi
 # alternatives are end-anchored  -  unanchored, `.build.log.old` was forgiven here
 # but not deletable below, which made every removal refuse forever.
 ARTIFACTS_RE='^(agent-state\.json|phase-tracker\.json|triage-output\.json|\.review-diff\.txt|\.build\.log|\.test\.log)$|^\.pipeline/'
+# Forgiven at the end of the pipeline (see below): a worktree whose git dir is
+# already gone reports nothing, and "nothing dirty" is the correct reading of
+# that - aborting would strand the removal this function exists to perform.
 dirty="$(git -C "$rp_wt" status --porcelain 2>/dev/null | awk '
   {
     st = substr($0, 1, 2); path = substr($0, 4);
@@ -183,7 +190,7 @@ dirty="$(git -C "$rp_wt" status --porcelain 2>/dev/null | awk '
       continue   # our own untracked artefact
     fi
     printf '%s\n' "$path"
-  done)"
+  done || true)"
 if [ -n "$dirty" ]; then
   first="$(printf '%s\n' "$dirty" | head -1)"
   skip "worktree has uncommitted changes (e.g. $first)  -  refusing to remove"
@@ -219,7 +226,9 @@ copy_one() {
     SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
     return 0
   fi
-  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null
+  # Forgiven: this function already tolerates a copy that does not happen, and
+  # aborting here would skip the worktree removal that follows.
+  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null || true
   [ -d "$DEST/$1" ] && rm -rf "${DEST:?}/$1"
   cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
 }
@@ -240,7 +249,7 @@ copy_from_logs() {
     SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
     return 0
   fi
-  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null
+  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null || true
   cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
 }