@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

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

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
 #
 # worktree-finalize.sh  -  salvage a finished task's artefacts, then remove its
-# worktree. Called by Phase 6 once the PR is open.
+# worktree. Called by Phase 4 once the PR is open.
 #
 # The problem it solves: a task's worktree is dead weight the moment its PR
 # exists, but people forget to remove it, so `.worktrees/` accumulates full
-# checkouts. Removing it at PR-open is safe ONLY if the files Phase 7 and
+# checkouts. Removing it at PR-open is safe ONLY if the files Phase 5 and
 # `:resume` read are moved somewhere that outlives it  -  hence salvage first.
 #
 # What it deliberately does NOT do:
@@ -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 {
@@ -121,7 +125,7 @@ rp_pr="$(cd "$PROJECT_ROOT" 2>/dev/null && pwd -P || echo "")"
 [ "$rp_wt" != "$rp_pr" ] || skip "worktree equals project root (--local mode)  -  nothing to remove"
 
 # Refuse if the caller is standing inside the tree being removed. A shell left on
-# a deleted inode is worse than a leftover directory, and Phase 6 legitimately
+# a deleted inode is worse than a leftover directory, and Phase 4 legitimately
 # cd's into the worktree earlier, so this is a real case rather than a theoretical
 # one. The caller must cd out first.
 cwd_rp="$(pwd -P)"
@@ -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"
@@ -206,7 +213,7 @@ fi
 [ "$head_sha" = "$upstream_sha" ] || skip "HEAD ($(echo "$head_sha" | cut -c1-8)) differs from remote ($(echo "$upstream_sha" | cut -c1-8))  -  push before finalizing"
 
 # --- salvage ---------------------------------------------------------------
-# Everything Phase 7, :resume, :status and :log read out of the worktree. Each is
+# Everything Phase 5, :resume, :status and :log read out of the worktree. Each is
 # copied only if present; a task that never reached Phase 4 has no triage output
 # and that is not an error.
 DEST="$LOGS_ROOT/${PROJECT:+$PROJECT/}$TASK_ID/artifacts"
@@ -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\""
 }
 
@@ -300,7 +309,7 @@ if git -C "$rp_pr" worktree remove "$rp_wt" 2>/dev/null; then
   # Stamp the outcome into the SALVAGED agent-state.json here, rather than leaving
   # the caller to write it. In single-repo worktree mode the caller's $STATE_FILE
   # is the copy that just went away with the worktree, so a write there fails and
-  # `worktreeRemovedAt` / `artifactsPath` land nowhere  -  which then makes Phase 7
+  # `worktreeRemovedAt` / `artifactsPath` land nowhere  -  which then makes Phase 5
   # read a dead path, fall back to the removed worktree, and silently skip the
   # triage-memory ingest. Exactly the [ -f ]-guarded degradation this step exists
   # to prevent.