@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/graph-report.mjs

@@ -34,6 +34,7 @@ import { execFileSync } from "node:child_process";
 import { join, dirname, resolve } from "node:path";
 import { parseFlags } from "./graph-build.mjs";
 import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+import { loadRules } from "./_code-graph.mjs";
 
 /**
  * Top-level source directory of a path, used as the module bucket.
@@ -86,7 +87,109 @@ export function summarize(graph, top) {
   const kinds = {};
   for (const s of symbols) kinds[s.symbolKind] = (kinds[s.symbolKind] || 0) + 1;
 
-  return { hubs, modules, externals, orphans, kinds, fileCount: files.length };
+  // The stack's rules say which symbol kinds can be reference targets at all.
+  // Without them the unreferenced question has no honest answer, so the section
+  // says that rather than listing symbols that never could have had an edge.
+  let referenceKinds;
+  try {
+    referenceKinds = loadRules(graph.stack).referenceKinds;
+  } catch {
+    // A stack with no rule file on disk, or one this build cannot parse. The
+    // section says so instead of guessing.
+    referenceKinds = null;
+  }
+  const unreferenced = referenceKinds ? unreferencedSymbols(graph, referenceKinds) : null;
+
+  return {
+    hubs,
+    modules,
+    externals,
+    orphans,
+    kinds,
+    fileCount: files.length,
+    referenceKinds,
+    unreferenced,
+  };
+}
+
+/**
+ * Symbols no OTHER file in this graph names.
+ *
+ * The orphan section finds FILES with no edge at all. A file imported for one
+ * symbol while three of its other exports are dead has edges, so it is invisible
+ * there - which is the gap this closes. The data needed was already in the graph:
+ * a symbol's only incoming edge kinds are `defines` (from its own file) and
+ * `references` (from another file).
+ *
+ * CANDIDATES, NOT VERDICTS. ADR-0010 records what the extractor is: regex over
+ * comment-stripped source, not a parser. Dynamic dispatch, reflection,
+ * string-keyed lookup, a public API consumed outside this repo, and anything
+ * reached through a name the rules do not treat as a reference target all look
+ * identical to dead code from here. So this reports and never gates, and the
+ * exclusions below exist so the list does not fill with symbols that COULD NOT
+ * have an edge no matter how heavily used they are:
+ *
+ *   - a nested declaration is never a reference target by construction
+ *   - a symbolKind outside this stack's referenceKinds is never a target
+ *   - a name declared in two places gets no reference edge at all (the builder
+ *     drops ambiguous tokens), so absence proves nothing about it
+ *   - a symbol declared in a test file is not the subject of this question
+ *
+ * Same-file use also produces no edge, so "unreferenced" here means precisely
+ * "no other file in this repo names it", which is what the section says.
+ *
+ * @param {object} graph
+ * @param {Set<string>|null} referenceKinds - null when the stack's rules did not load
+ * @returns {{candidates: object[], testOnly: object[], excluded: object}}
+ */
+export function unreferencedSymbols(graph, referenceKinds) {
+  const symbols = graph.nodes.filter((n) => n.kind === "symbol");
+  const fileById = new Map(graph.nodes.filter((n) => n.kind === "file").map((n) => [n.id, n]));
+
+  const nameCount = new Map();
+  for (const sym of symbols) {
+    if (sym.nested === true) continue;
+    nameCount.set(sym.name, (nameCount.get(sym.name) || 0) + 1);
+  }
+
+  const incoming = new Map();
+  for (const e of graph.edges) {
+    if (e.kind !== "references") continue;
+    if (!incoming.has(e.to)) incoming.set(e.to, []);
+    incoming.get(e.to).push(e.from);
+  }
+
+  const excluded = { nested: 0, kindNotATarget: 0, ambiguousName: 0, test: 0 };
+  const candidates = [];
+  const testOnly = [];
+
+  for (const sym of symbols) {
+    if (sym.isTest) {
+      excluded.test += 1;
+      continue;
+    }
+    if (sym.nested === true) {
+      excluded.nested += 1;
+      continue;
+    }
+    if (referenceKinds && !referenceKinds.has(sym.symbolKind)) {
+      excluded.kindNotATarget += 1;
+      continue;
+    }
+    if ((nameCount.get(sym.name) || 0) > 1) {
+      excluded.ambiguousName += 1;
+      continue;
+    }
+    const from = incoming.get(sym.id) || [];
+    if (from.length === 0) {
+      candidates.push(sym);
+      continue;
+    }
+    if (from.every((fid) => fileById.get(fid)?.isTest === true)) testOnly.push(sym);
+  }
+
+  const bySymbol = (a, b) => a.path.localeCompare(b.path) || a.name.localeCompare(b.name);
+  return { candidates: candidates.sort(bySymbol), testOnly: testOnly.sort(bySymbol), excluded };
 }
 
 /**
@@ -160,6 +263,57 @@ export function render(graph, top) {
   }
   L.push("");
 
+  L.push(`## Symbols nothing else references`);
+  L.push("");
+  if (!s.referenceKinds) {
+    L.push(
+      `Not computed: this stack's code-graph rules did not load, so which symbol kinds can be ` +
+        `reference targets at all is unknown, and every answer would be a guess.`,
+    );
+  } else {
+    const u = s.unreferenced;
+    L.push(
+      `Candidates, not verdicts. These are symbols no OTHER file in this repo names. ` +
+        `The extractor is regex over comment-stripped source, not a parser, so dynamic dispatch, ` +
+        `reflection, string-keyed lookup and a public API consumed outside this repo all look ` +
+        `exactly like dead code from here. Nothing gates on this list.`,
+    );
+    L.push("");
+    L.push(
+      `Excluded because they could not carry a reference edge either way: ` +
+        `${u.excluded.kindNotATarget} of a kind this stack never treats as a target, ` +
+        `${u.excluded.ambiguousName} declared under a name that exists in more than one place, ` +
+        `${u.excluded.nested} nested, ${u.excluded.test} declared in test files.`,
+    );
+    L.push("");
+    if (u.candidates.length === 0) {
+      L.push(`None: every eligible symbol is named by at least one other file.`);
+    } else {
+      L.push(`${u.candidates.length} symbol(s) with no reference from any other file:`);
+      L.push("");
+      L.push(`| Symbol | Kind | Path |`);
+      L.push(`|---|---|---|`);
+      for (const c of u.candidates.slice(0, top)) {
+        L.push(`| \`${c.name}\` | ${c.symbolKind} | \`${c.path}:${c.line || 1}\` |`);
+      }
+      if (u.candidates.length > top) L.push("");
+      if (u.candidates.length > top) L.push(`... ${u.candidates.length - top} more`);
+    }
+    L.push("");
+    if (u.testOnly.length > 0) {
+      L.push(
+        `${u.testOnly.length} more are referenced ONLY from test files. That is not dead code - ` +
+          `it is code whose only consumer is its own test, which is worth knowing before a plan ` +
+          `treats it as load-bearing:`,
+      );
+      L.push("");
+      for (const t of u.testOnly.slice(0, top))
+        L.push(`- \`${t.name}\` - \`${t.path}:${t.line || 1}\``);
+      if (u.testOnly.length > top) L.push(`- ... ${u.testOnly.length - top} more`);
+      L.push("");
+    }
+  }
+
   return L.join("\n");
 }
 

package/pipeline/scripts/keychain-save.sh

@@ -2,55 +2,126 @@
 
 set -uo pipefail
 
-# Kullanım: ./keychain-save.sh <service-adı>
-# Örnek:    ./keychain-save.sh github-pat
-#           ./keychain-save.sh firebase-sa
+# Kullanım (interaktif):  ./keychain-save.sh <service-adı>
+# Örnek:                  ./keychain-save.sh github-pat
+#                         ./keychain-save.sh firebase-sa
+#
+# HEADLESS: terminal yokken script SORMAZ. Üç `read` koruma olmadan duruyordu
+# ve bir launchd ajanının altında ilki sonsuza kadar bekler; kurulum "asılı
+# kaldı" diye görünür.
+#
+#   MULTI_AGENT_UNATTENDED=1               terminal olsa bile sorulmaz
+#   ./keychain-save.sh <ad> --stdin        token stdin'den okunur (satır değil,
+#                                          tüm gövde - JSON çok satırlıdır)
+#   ./keychain-save.sh <ad> --json <yol>   JSON dosyadan okunur
+#
+# Secret İÇİN env değişkeni bilerek YOK. Bir env değeri çocuk süreçlere
+# miras kalır ve bazı sistemlerde `ps e` ile görünür; borudan okumak onu
+# yalnız bu sürecin belleğinde tutar. Aynı sebeple argv'ye de hiç değmez.
 
 SERVICE_NAME="${1:-}"
+MODE="${2:-}"
+MODE_ARG="${3:-}"
+
+usage() {
+    echo "Kullanım: $0 <service-adı>                  (interaktif)"
+    echo "          $0 <service-adı> --stdin          (token borudan)"
+    echo "          $0 <service-adı> --json <yol>     (JSON dosyadan)"
+}
 
 if [ -z "$SERVICE_NAME" ]; then
-    echo "Kullanım: $0 <service-adı>"
-    echo "Örnek:    $0 github-pat"
+    usage
     exit 1
 fi
 
-echo "Ne tür bir secret kaydedeceksin?"
-echo "  1) Personal Access Token / API Key"
-echo "  2) JSON dosyası (service account vb.)"
-read -rp "Seçim (1/2): " CHOICE
+# Başsızken mod verilmediyse, soruyu sormak yerine reddet. Sessizce beklemek
+# en kötü seçenek: dışarı hiçbir şey yazmaz ve kimse neyi beklediğini bilmez.
+if [ -z "$MODE" ] && { [ ! -t 0 ] || [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ]; }; then
+    # Sebebi doğru söyle. "terminal yok" derken terminalin VAR olması,
+    # okuyanı kendi kurulumunu yanlış yerde aramaya gönderir.
+    if [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ]; then
+        echo "Hata: MULTI_AGENT_UNATTENDED=1 ve mod verilmedi." >&2
+    else
+        echo "Hata: terminal yok ve mod verilmedi." >&2
+    fi
+    usage >&2
+    exit 1
+fi
+
+read_json_file() {
+    local path="$1"
+    # Kullanıcının girdiği tırnak işaretlerini temizle
+    path="${path//\'/}"
+    path="${path//\"/}"
+    # Tilde (~) expand
+    path="${path/#\~/$HOME}"
+    if [ ! -f "$path" ]; then
+        echo "Hata: Dosya bulunamadı: $path" >&2
+        return 1
+    fi
+    # JSON olduğu gibi saklanır. Kimlik deposu çok satırlı değeri
+    # bayt bayt geri verir; base64 sarmalı okuma tarafında çözülmeyen
+    # bir katman ekliyordu.
+    cat "$path"
+}
 
-case "$CHOICE" in
-    1)
-        read -rsp "Token'ı yapıştır (gizli yazılır): " SECRET
-        echo ""
+case "$MODE" in
+    --stdin)
+        # `read` DEĞİL `cat`: `read` ilk satırda durur ve bir service-account
+        # JSON'unun geri kalanını sessizce atar.
+        SECRET=$(cat)
         if [ -z "$SECRET" ]; then
-            echo "Hata: Token boş olamaz."
+            echo "Hata: stdin boş." >&2
             exit 1
         fi
         ;;
-    2)
-        read -rp "JSON dosya yolunu gir: " JSON_PATH
-        # Kullanıcının girdiği tırnak işaretlerini temizle
-        JSON_PATH="${JSON_PATH//\'/}"
-        JSON_PATH="${JSON_PATH//\"/}"
-        # Tilde (~) expand
-        JSON_PATH="${JSON_PATH/#\~/$HOME}"
-        if [ ! -f "$JSON_PATH" ]; then
-            echo "Hata: Dosya bulunamadı: $JSON_PATH"
+    --json)
+        if [ -z "$MODE_ARG" ]; then
+            echo "Hata: --json bir dosya yolu ister." >&2
+            usage >&2
             exit 1
         fi
-        # JSON olduğu gibi saklanır. Kimlik deposu çok satırlı değeri
-        # bayt bayt geri verir; base64 sarmalı okuma tarafında çözülmeyen
-        # bir katman ekliyordu.
-        SECRET=$(cat "$JSON_PATH")
+        SECRET=$(read_json_file "$MODE_ARG") || exit 1
         if [ -z "$SECRET" ]; then
-            echo "Hata: Dosya okunamadı."
+            echo "Hata: Dosya okunamadı." >&2
             exit 1
         fi
-        echo "JSON olduğu gibi saklanacak."
+        ;;
+    "")
+        echo "Ne tür bir secret kaydedeceksin?"
+        echo "  1) Personal Access Token / API Key"
+        echo "  2) JSON dosyası (service account vb.)"
+        # EOF (Ctrl-D) bir cevaptır: korumasız `read` onu boş bir seçime
+        # çevirip aşağıdaki "Geçersiz seçim"e düşürür, ki doğru sonuç.
+        read -rp "Seçim (1/2): " CHOICE || CHOICE=""
+
+        case "$CHOICE" in
+            1)
+                read -rsp "Token'ı yapıştır (gizli yazılır): " SECRET || SECRET=""
+                echo ""
+                if [ -z "$SECRET" ]; then
+                    echo "Hata: Token boş olamaz."
+                    exit 1
+                fi
+                ;;
+            2)
+                read -rp "JSON dosya yolunu gir: " JSON_PATH || JSON_PATH=""
+                SECRET=$(read_json_file "$JSON_PATH") || exit 1
+                if [ -z "$SECRET" ]; then
+                    echo "Hata: Dosya okunamadı."
+                    exit 1
+                fi
+                echo "JSON olduğu gibi saklanacak."
+                ;;
+            *)
+                echo "Geçersiz seçim."
+                exit 1
+                ;;
+        esac
         ;;
     *)
-        echo "Geçersiz seçim."
+        echo "Hata: bilinmeyen mod: $MODE" >&2
+        usage >&2
         exit 1
         ;;
 esac

package/pipeline/scripts/learn-from-transcripts.mjs

@@ -66,6 +66,7 @@ import { execFileSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
@@ -622,4 +623,4 @@ function main() {
   }
 }
 
-main();
+runMain("learn-from-transcripts", main);

package/pipeline/scripts/learning-curve.mjs

@@ -19,7 +19,7 @@
 //
 // Exit: 0 always (advisory; empty/missing metrics -> friendly note).
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -39,8 +39,11 @@ for (const a of args) {
 const METRICS_FILE =
   process.env.METRICS_FILE || join(homedir(), ".claude", "logs", "multi-agent", "metrics.jsonl");
 
+// Called from module scope and has to stop the script, so the write goes to
+// fd 1 synchronously: console.log would still be in the pipe when process.exit
+// tore the process down.
 function emitEmpty(reason) {
-  if (opts.json) console.log(JSON.stringify({ ok: false, reason, buckets: [] }));
+  if (opts.json) writeFileSync(1, `${JSON.stringify({ ok: false, reason, buckets: [] })}\n`);
   else console.error(`learning-curve: ${reason}`);
   process.exit(0);
 }
@@ -183,35 +186,37 @@ if (buckets.length >= 2) {
 
 const out = { ok: true, bucketDays: opts.bucketDays, buckets, trend };
 
+// else, not process.exit(0) after the write: stdout to a pipe is asynchronous
+// and exiting drops whatever has not drained, so the JSON arrived truncated to
+// anything reading it through a pipe.
 if (opts.json) {
   console.log(JSON.stringify(out, null, 2));
-  process.exit(0);
-}
-
-// Markdown / text (default)
-const arrow = (v, goodIsUp) => {
-  if (v == null || v === 0) return "-";
-  const up = v > 0;
-  const good = up === goodIsUp;
-  return `${up ? "+" : ""}${v} ${good ? "(better)" : "(worse)"}`;
-};
-console.log(`# Learning curve (${opts.bucketDays}-day buckets)\n`);
-console.log(
-  "| Bucket | Tasks | First-pass clean | Avg review cycles | Rework/task | Tokens/task | Cache ratio | Memory precision | Mined lessons/task | Offload bytes saved/task |",
-);
-console.log("|---|---|---|---|---|---|---|---|---|---|");
-for (const b of buckets) {
+} else {
+  // Markdown / text (default)
+  const arrow = (v, goodIsUp) => {
+    if (v == null || v === 0) return "-";
+    const up = v > 0;
+    const good = up === goodIsUp;
+    return `${up ? "+" : ""}${v} ${good ? "(better)" : "(worse)"}`;
+  };
+  console.log(`# Learning curve (${opts.bucketDays}-day buckets)\n`);
   console.log(
-    `| ${b.bucketStart} | ${b.tasks} | ${b.firstPassCleanRate ?? "-"} | ${b.avgReviewCycles ?? "-"} | ${b.reworkPerTask} | ${b.tokensPerTask} | ${b.cacheRatio ?? "-"} | ${b.memoryPrecision ?? "-"} | ${b.minedLessonsPerTask ?? "-"} | ${b.offloadBytesSavedPerTask ?? "-"} |`,
+    "| Bucket | Tasks | First-pass clean | Avg review cycles | Rework/task | Tokens/task | Cache ratio | Memory precision | Mined lessons/task | Offload bytes saved/task |",
   );
-}
-if (trend) {
-  console.log(`\n**Trend ${trend.from} -> ${trend.to}:**`);
-  console.log(`- First-pass clean: ${arrow(trend.firstPassCleanRate, true)}`);
-  console.log(`- Avg review cycles: ${arrow(trend.avgReviewCycles, false)}`);
-  console.log(`- Tokens/task: ${arrow(trend.tokensPerTask, false)}`);
-  console.log(`- Cache ratio: ${arrow(trend.cacheRatio, true)}`);
-  console.log(`- Memory precision: ${arrow(trend.memoryPrecision, true)}`);
-} else {
-  console.log("\n(need >= 2 buckets for a trend; keep running the pipeline)");
+  console.log("|---|---|---|---|---|---|---|---|---|---|");
+  for (const b of buckets) {
+    console.log(
+      `| ${b.bucketStart} | ${b.tasks} | ${b.firstPassCleanRate ?? "-"} | ${b.avgReviewCycles ?? "-"} | ${b.reworkPerTask} | ${b.tokensPerTask} | ${b.cacheRatio ?? "-"} | ${b.memoryPrecision ?? "-"} | ${b.minedLessonsPerTask ?? "-"} | ${b.offloadBytesSavedPerTask ?? "-"} |`,
+    );
+  }
+  if (trend) {
+    console.log(`\n**Trend ${trend.from} -> ${trend.to}:**`);
+    console.log(`- First-pass clean: ${arrow(trend.firstPassCleanRate, true)}`);
+    console.log(`- Avg review cycles: ${arrow(trend.avgReviewCycles, false)}`);
+    console.log(`- Tokens/task: ${arrow(trend.tokensPerTask, false)}`);
+    console.log(`- Cache ratio: ${arrow(trend.cacheRatio, true)}`);
+    console.log(`- Memory precision: ${arrow(trend.memoryPrecision, true)}`);
+  } else {
+    console.log("\n(need >= 2 buckets for a trend; keep running the pipeline)");
+  }
 }

package/pipeline/scripts/make-manifest.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * make-manifest.mjs  -  a digest of everything the package ships.
+ *
+ * "Is my install the one that was published, or has something edited it" is a
+ * question this tree could not answer. The install is a COPY: `install.js`
+ * writes into ~/.claude, ~/.copilot and ~/.codex, and from that moment the two
+ * halves drift independently. An edit made in the installed copy looks like a
+ * feature nobody can find the source of; a file the installer failed to write
+ * looks like a bug in a script that was never there.
+ *
+ * The manifest turns both into one command. It records a SHA-256 for every
+ * file the package ships, the version, and the commit it was built from, and
+ * `multi-agent-pipeline verify` compares an installed tree against it, file by
+ * file.
+ *
+ * The file set is not guessed: it comes from `npm pack --dry-run --json`, so
+ * it is by construction the same set npm will publish, `files` globs and all.
+ * `--ignore-scripts` is on the inner call because this script runs FROM
+ * prepack, and without it npm would run prepack again.
+ *
+ * Two things the manifest cannot cover, said here rather than discovered later:
+ * it cannot hash itself (it does not exist when the list is taken), and a
+ * signature over it does not authenticate the tarball - the verifier and the
+ * public key travel inside the same tarball, so anyone able to rewrite one can
+ * rewrite the others. What a signature DOES catch is a manifest damaged in
+ * transit or edited after install, which is the failure this file exists for.
+ * Provenance belongs to npm's own integrity field, not to us.
+ *
+ * Usage:
+ *   make-manifest.mjs              write manifest.json at the repo root
+ *   make-manifest.mjs --sign       also write manifest.sig (needs a signing key)
+ *   make-manifest.mjs --check      recompute and report drift, write nothing
+ *   make-manifest.mjs --json
+ *
+ * Exit codes:
+ *   0  written, or --check found no drift
+ *   1  --check found drift
+ *   2  usage or environment error
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash, createPrivateKey, sign as cryptoSign } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+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 MANIFEST = join(ROOT, "manifest.json");
+
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+
+/** The exact set npm would publish, in npm's own words. */
+function shippedFiles() {
+  const out = execFileSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], {
+    cwd: ROOT,
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const parsed = JSON.parse(out);
+  const files = parsed?.[0]?.files;
+  if (!Array.isArray(files) || !files.length) {
+    throw new Error("npm pack --dry-run returned no file list");
+  }
+  return files
+    .map((f) => f.path)
+    .filter((p) => p !== "manifest.json" && p !== "manifest.sig")
+    .sort();
+}
+
+function sha256(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function gitCommit() {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: ROOT,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    // A tarball unpacked outside a checkout has no git. The manifest is still
+    // valid; only the provenance line is unknown, and saying so beats writing
+    // a placeholder that reads like a real commit.
+    return null;
+  }
+}
+
+function build() {
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+  const files = {};
+  for (const rel of shippedFiles()) {
+    const abs = join(ROOT, rel);
+    if (!existsSync(abs)) continue;
+    files[rel] = sha256(abs);
+  }
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    commit: gitCommit(),
+    generatedAt: new Date().toISOString(),
+    algorithm: "sha256",
+    fileCount: Object.keys(files).length,
+    files,
+  };
+}
+
+/**
+ * Sign the manifest with an ed25519 key. Optional, and silent about its absence
+ * on the common path: a package with no signature still verifies on hashes
+ * alone, which is the property that actually gets used.
+ *
+ * The key is read through the credential store, never taken from argv and never
+ * printed. MULTI_AGENT_SIGNING_KEY is the fallback for a build host that has no
+ * store (CI), and it holds the PEM itself.
+ *
+ * @param {string} manifestJson exact bytes that were written to disk
+ * @returns {string|null} base64 signature, or null when no key is configured
+ */
+function sign(manifestJson) {
+  let pem = process.env.MULTI_AGENT_SIGNING_KEY || "";
+  if (!pem) {
+    try {
+      pem = execFileSync(
+        join(ROOT, "pipeline", "lib", "credential-store.sh"),
+        ["get", "pipeline_signing"],
+        {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"],
+        },
+      ).trim();
+    } catch {
+      pem = "";
+    }
+  }
+  if (!pem) {
+    process.stderr.write(
+      "make-manifest: no signing key configured - manifest written unsigned (hashes still verify)\n",
+    );
+    return null;
+  }
+  const privateKey = createPrivateKey(pem);
+  return cryptoSign(null, Buffer.from(manifestJson), privateKey).toString("base64");
+}
+
+function main() {
+  if (has("--check")) {
+    if (!existsSync(MANIFEST)) {
+      process.stderr.write("make-manifest: no manifest.json to check\n");
+      process.exit(2);
+    }
+    const stored = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+    const fresh = build();
+    const changed = [];
+    for (const [rel, hash] of Object.entries(fresh.files)) {
+      if (stored.files[rel] !== hash) changed.push(rel);
+    }
+    const gone = Object.keys(stored.files).filter((r) => !(r in fresh.files));
+    const report = { changed, gone, stale: changed.length + gone.length > 0 };
+    if (has("--json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    else if (!report.stale)
+      process.stdout.write(`manifest.json is current (${fresh.fileCount} files)\n`);
+    else {
+      process.stdout.write(
+        `manifest.json is stale: ${changed.length} changed, ${gone.length} gone\n`,
+      );
+      for (const r of [...changed, ...gone].slice(0, 20)) process.stdout.write(`  ${r}\n`);
+    }
+    process.exitCode = report.stale ? 1 : 0;
+    return;
+  }
+
+  const manifest = build();
+  const json = `${JSON.stringify(manifest, null, 2)}\n`;
+  writeFileSync(MANIFEST, json);
+  if (has("--sign")) {
+    const sig = sign(json);
+    if (sig) writeFileSync(join(ROOT, "manifest.sig"), `${sig}\n`);
+  }
+  if (has("--json"))
+    process.stdout.write(
+      `${JSON.stringify({ written: MANIFEST, ...manifest, files: undefined }, null, 2)}\n`,
+    );
+  else
+    // STDERR, not stdout. This runs as `prepack`, and npm passes a prepack
+    // script's stdout straight through - so one friendly line here lands INSIDE
+    // `npm pack --dry-run --json` and every consumer that parses that JSON
+    // fails with "Unexpected token 'm'". Two gates caught it within minutes;
+    // a publish would not have.
+    process.stderr.write(
+      `manifest.json: ${manifest.fileCount} files, version ${manifest.version}, commit ${manifest.commit?.slice(0, 12) ?? "unknown"}\n`,
+    );
+}
+
+runMain("make-manifest", main);