@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/lib/fatal.mjs

@@ -0,0 +1,129 @@
+/**
+ * fatal.mjs  -  one line instead of a stack dump, and whatever was held gets
+ * released.
+ *
+ * Node's default for an uncaught throw or a rejected promise nobody awaited is
+ * a stack trace on stderr and exit 1. That is the right default for a library
+ * and the wrong one here for two reasons.
+ *
+ * The first is legibility. Every script in this tree reports its own failures
+ * as `name: what went wrong`, one line, and a caller - a shell gate, a phase
+ * step, a person reading a run log - is written against that shape. A stack
+ * dump in the middle of it reads as a crash of the pipeline rather than as a
+ * failure of one step, and the actual message sits four frames down.
+ *
+ * The second is state, and it is the one that costs something. A script that
+ * dies between acquiring an advisory lock and releasing it leaves the lock on
+ * disk. The next writer then waits out the full acquire window before deciding
+ * the holder is stale - and if it judges wrong it takes a lock a LIVE writer
+ * holds. `cleanup` exists for exactly that: the handler releases before it
+ * exits, so the abnormal path leaves the same state behind as the normal one.
+ *
+ * What this does NOT do is swallow anything. Every path still exits non-zero,
+ * and the message still names the error; only the stack goes, and only when
+ * the error carries a message worth reading on its own.
+ *
+ * Usage:
+ *   import { runMain } from "../lib/fatal.mjs";
+ *   runMain("write-state", main, { cleanup: releaseLock });
+ *
+ * @module pipeline/lib/fatal
+ */
+
+/** Guards against a cleanup that runs twice when a throw follows a rejection. */
+let cleanedUp = false;
+
+/**
+ * Run `cleanup` at most once, and never let it become the failure it is
+ * cleaning up after: a cleanup that throws inside a fatal handler replaces the
+ * original error with its own, which is how a lock bug ends up reported as a
+ * permissions bug.
+ *
+ * @param {(() => void)|undefined} cleanup
+ */
+function runCleanup(cleanup) {
+  if (cleanedUp || typeof cleanup !== "function") return;
+  cleanedUp = true;
+  try {
+    cleanup();
+  } catch {
+    // Deliberately silent. The caller is already exiting with the real error.
+  }
+}
+
+/**
+ * The message a human should see. An Error with a message prints the message;
+ * anything else (a thrown string, a rejected non-Error) prints its own
+ * stringification, because dropping it would leave the line with nothing in it.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function describe(err) {
+  if (err instanceof Error && err.message) return err.message;
+  if (typeof err === "string" && err) return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+/**
+ * Catch what escapes: a rejected promise nobody awaited, and a throw from a
+ * callback that no try/catch surrounds. Both are invisible to a try/catch
+ * around main(), which is why wrapping main() alone is not enough.
+ *
+ * MULTI_AGENT_FATAL_STACK=1 restores the stack for debugging. It is off by
+ * default because the line is for the person running the pipeline, not for the
+ * person maintaining it.
+ *
+ * @param {{name:string, cleanup?:()=>void, code?:number}} opts
+ */
+export function installFatalHandlers({ name, cleanup, code = 1 }) {
+  const report = (kind, err) => {
+    runCleanup(cleanup);
+    // `runs-index.mjs --json | head` is not a failure: head closes the pipe and
+    // the next write raises EPIPE. Reporting it as a fatal would turn the most
+    // ordinary way of looking at a large output into a red line and a non-zero
+    // exit, and the reader that went away is not listening to the complaint
+    // anyway. Quiet, zero, the way every other CLI treats it.
+    if (err && err.code === "EPIPE") process.exit(0);
+    process.stderr.write(`${name}: ${kind}  -  ${describe(err)}\n`);
+    if (process.env.MULTI_AGENT_FATAL_STACK === "1" && err instanceof Error && err.stack) {
+      process.stderr.write(`${err.stack}\n`);
+    }
+    // exit(), not exitCode: the event loop may hold a listener that would keep
+    // the process alive after the failure, and a script that has already
+    // reported a fatal must not go on to do more work.
+    process.exit(code);
+  };
+  process.on("unhandledRejection", (err) => report("unhandled rejection", err));
+  process.on("uncaughtException", (err) => report("uncaught exception", err));
+}
+
+/**
+ * Install the handlers and run main, sync or async, with the same contract for
+ * both. A successful run is untouched: no exit call, so `process.exitCode` set
+ * inside main survives, and stdout drains the way it would have.
+ *
+ * @param {string} name        script name as it should appear in the message
+ * @param {() => unknown} main
+ * @param {{cleanup?:()=>void, code?:number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function runMain(name, main, opts = {}) {
+  const { cleanup, code = 1 } = opts;
+  installFatalHandlers({ name, cleanup, code });
+  try {
+    await main();
+  } catch (err) {
+    runCleanup(cleanup);
+    if (err && err.code === "EPIPE") process.exit(0);
+    process.stderr.write(`${name}: ${describe(err)}\n`);
+    if (process.env.MULTI_AGENT_FATAL_STACK === "1" && err instanceof Error && err.stack) {
+      process.stderr.write(`${err.stack}\n`);
+    }
+    process.exit(code);
+  }
+}

package/pipeline/lib/fetch-fortify.sh

@@ -49,7 +49,7 @@
 #   6  not configured (prefs.global.hosts.fortify empty, or an instance-id-only
 #      lookup with no prefs.global.fortify.versionIds to search)
 #
-# Phase 4 review gate contract:
+# Phase 3 review gate contract:
 #   Critical > 0   → blocking=true, reason="critical-findings"
 #   High > 0       → blocking=false, reason="high-findings-warning"
 #   else           → blocking=false, reason="clean"

package/pipeline/lib/figma-mcp-refresh.sh

@@ -18,6 +18,24 @@
 
 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 "refresh the Figma MCP token" || exit 3
+
 PREFS_FILE="${PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
 TOKEN_ENDPOINT="https://api.figma.com/v1/oauth/token"
 

package/pipeline/lib/figma-screenshot.sh

@@ -39,6 +39,24 @@
 
 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 "fetch a Figma screenshot" || exit 3
+
 # --- Globals ----------------------------------------------------------------
 
 # Locate the resolver with an existence check, not a `.`-chain: sourcing a missing file

package/pipeline/lib/invoked-directly.mjs

@@ -0,0 +1,43 @@
+/**
+ * invoked-directly.mjs  -  "was this file run, or imported", answered correctly.
+ *
+ * The idiom this replaces was in nine files:
+ *
+ *     if (import.meta.url === `file://${process.argv[1]}`) main();
+ *
+ * It compares a RESOLVED, percent-encoded URL against a raw path, and it is
+ * false in three situations that are not exotic:
+ *
+ *   - a symlink. `install --link` symlinks whole directories into ~/.claude, so
+ *     every script a linked install runs is reached through one;
+ *   - a path that resolves elsewhere. On macOS /var is a symlink to /private/var,
+ *     which is where mktemp puts everything;
+ *   - a path containing a space, or any character a URL escapes.
+ *
+ * In all three the guard is false and the script does nothing, silently, exit 0.
+ * On `outbound-gate.mjs` that was a security hole rather than an inconvenience:
+ * the callers read exit 0 as "this text is clean", so a body carrying a token
+ * would have been published unscanned by any install that used --link.
+ *
+ * @module pipeline/lib/invoked-directly
+ */
+
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+/**
+ * True when `metaUrl` names the file Node was asked to run.
+ *
+ * @param {string} metaUrl the caller's own `import.meta.url`
+ * @returns {boolean}
+ */
+export function invokedDirectly(metaUrl) {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return metaUrl === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    // An argv[1] that cannot be resolved is not this file.
+    return false;
+  }
+}

package/pipeline/lib/jira-publish.sh

@@ -40,6 +40,47 @@
 
 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 "build the Jira comment" || 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"
+}
+
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
 PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
 CURL="${JIRA_PUBLISH_CURL:-curl}"
@@ -73,6 +114,7 @@ done
 [ -n "$ISSUE" ] || die "usage: jira-publish.sh --issue KEY --body-file FILE [--target comment|description]"
 [ -n "$BODY_FILE" ] || die "usage: jira-publish.sh --issue KEY --body-file FILE [--target comment|description]"
 [ -f "$BODY_FILE" ] || die "body file not found: $BODY_FILE"
+ma_outbound_gate "$BODY_FILE" || die "outbound gate refused this comment; nothing was posted"
 case "$TARGET" in comment|description) ;; *) die "--target must be comment or description, got: $TARGET" ;; esac
 case "$MODE" in append|replace) ;; *) die "--mode must be append or replace, got: $MODE" ;; esac
 

package/pipeline/lib/md2confluence-v3.py

@@ -35,6 +35,7 @@ import argparse
 import html
 import io
 import json
+import tempfile
 import mimetypes
 import os
 import re
@@ -962,6 +963,10 @@ def cmd_create(args: argparse.Namespace) -> int:
         sys.stderr.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
         return 0
 
+    # Every byte below this line leaves the machine. The dry-run branch above
+    # returns before it, which is why the gate sits here and not at the top.
+    outbound_gate(md_text)
+
     auth = resolve_auth()
     warnings = list(result.warnings)
 
@@ -1194,6 +1199,48 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def outbound_gate(text: str) -> None:
+    """Refuse to publish text the leak gate has not cleared.
+
+    This is the choke point for the Confluence half of the pipeline's outbound
+    surface: a page is created or updated only from here, and everything above
+    is rendering. The gate itself is the same one the Jira and PR paths use -
+    one set of patterns, one verdict, rather than a second copy that drifts.
+
+    A missing gate file REFUSES. The only way it is absent is a broken install,
+    and publishing unchecked because the check could not be loaded is the single
+    failure this exists to prevent.
+    """
+    candidates = [
+        Path(__file__).resolve().parent / "outbound-gate.mjs",
+        Path.home() / ".claude" / "lib" / "outbound-gate.mjs",
+        Path.home() / ".copilot" / "lib" / "outbound-gate.mjs",
+        Path.home() / ".codex" / "lib" / "outbound-gate.mjs",
+    ]
+    gate = next((c for c in candidates if c.is_file()), None)
+    if gate is None:
+        sys.stderr.write("outbound-gate.mjs not found - refusing to publish unchecked text.\n")
+        raise SystemExit(2)
+
+    with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8") as fh:
+        fh.write(text)
+        tmp = fh.name
+    try:
+        proc = subprocess.run(
+            ["node", str(gate), "--file", tmp],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    finally:
+        os.unlink(tmp)
+    if proc.returncode != 0:
+        sys.stderr.write(proc.stdout)
+        sys.stderr.write(proc.stderr)
+        sys.stderr.write("outbound gate refused this page; nothing was published.\n")
+        raise SystemExit(2)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)

package/pipeline/lib/model-rung.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# model-rung.sh  -  read or flip the top model rung, and keep cost pricing with it.
+#
+# Backs /multi-agent:model. Two preference keys move as ONE write:
+#   prefs.global.modelFallback.fableEnabled   the rung itself
+#   prefs.global.costBudget.pricingModel      what the ledger prices against
+#
+# They were always meant to move together - model-fallback.md says so in prose -
+# but nothing enforced it, so a hand edit that flipped one left the estimate
+# pricing every call at a rung that was not in play. With the rung off and
+# pricing still `fable`, the budget ceiling trips early and triggers a downgrade
+# nothing needed. One write, or none.
+#
+# Usage:
+#   model-rung.sh            report current state (exit 0)
+#   model-rung.sh on         enable the fable rung
+#   model-rung.sh off        disable it
+#
+# Exit codes:
+#   0  -  reported or applied
+#   2  -  bad argument
+#   3  -  preferences file missing or unparseable (nothing written)
+
+set -uo pipefail
+
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+ACTION="${1:-report}"
+
+case "$ACTION" in
+  report | on | off) ;;
+  *)
+    echo "usage: model-rung.sh [on|off]" >&2
+    exit 2
+    ;;
+esac
+
+# A missing `jq` must not look like a missing setting. Without this the reads
+# below return empty, the command reports the rung as already off, and a user
+# who asked to turn it off is told it was never on.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "model-rung: jq not found  -  cannot read or write preferences (install: brew install jq)" >&2
+  exit 3
+fi
+
+if [ ! -f "$PREFS" ]; then
+  echo "model-rung: preferences not found at $PREFS  -  run /multi-agent:setup first" >&2
+  exit 3
+fi
+
+if ! jq -e . "$PREFS" >/dev/null 2>&1; then
+  echo "model-rung: $PREFS is not valid JSON  -  refusing to write over it" >&2
+  exit 3
+fi
+
+CUR=$(jq -r '.global.modelFallback.fableEnabled // false' "$PREFS")
+PRICING=$(jq -r '.global.costBudget.pricingModel // "fable"' "$PREFS")
+
+host_note() {
+  # Which host this is decides whether the switch is a switch or a status line.
+  # Saying "enabled" on a host where the rung means something else entirely is
+  # the surprise this block exists to avoid.
+  case "${MULTI_AGENT_HOST:-claude}" in
+    claude)
+      echo "Claude Code: the fable rung is Fable 5. This switch is live here."
+      ;;
+    copilot)
+      echo "Copilot CLI: Fable 5 is not offered; its personas never sat on this rung."
+      echo "This setting is recorded but changes nothing on this host."
+      ;;
+    codex)
+      echo "Codex CLI: the fable rung means gpt-5.6 @ xhigh, a different model on a"
+      echo "different account. This switch deliberately does NOT touch it  -  a knob"
+      echo "named after an Anthropic model must not silently retune a Codex run."
+      ;;
+    *)
+      echo "Unknown host '${MULTI_AGENT_HOST}'; reporting the stored value only."
+      ;;
+  esac
+}
+
+if [ "$ACTION" = "report" ]; then
+  echo "fable rung:    $CUR"
+  echo "cost pricing:  $PRICING"
+  if [ "$CUR" = "true" ] && [ "$PRICING" != "fable" ]; then
+    echo "MISMATCH: rung is on but the ledger prices against '$PRICING'  -  run 'model on' to realign"
+  elif [ "$CUR" != "true" ] && [ "$PRICING" = "fable" ]; then
+    echo "MISMATCH: rung is off but the ledger still prices against fable  -  this trips"
+    echo "          the budget ceiling early. Run 'model off' to realign."
+  fi
+  echo ""
+  host_note
+  exit 0
+fi
+
+if [ "$ACTION" = "on" ]; then
+  WANT=true
+  WANT_PRICING=fable
+else
+  WANT=false
+  WANT_PRICING=opus
+fi
+
+TMP=$(mktemp) || { echo "model-rung: mktemp failed" >&2; exit 3; }
+trap 'rm -f "$TMP"' EXIT
+
+# Both keys in one filter. A two-step write can leave the pair half-applied if
+# the second step fails, which is the exact state this command exists to prevent.
+if ! jq --argjson want "$WANT" --arg pricing "$WANT_PRICING" '
+      .global.modelFallback //= {}
+    | .global.modelFallback.fableEnabled = $want
+    | .global.costBudget //= {}
+    | .global.costBudget.pricingModel = $pricing
+  ' "$PREFS" > "$TMP"; then
+  echo "model-rung: jq failed  -  preferences left untouched" >&2
+  exit 3
+fi
+
+if ! jq -e . "$TMP" >/dev/null 2>&1; then
+  echo "model-rung: produced invalid JSON  -  preferences left untouched" >&2
+  exit 3
+fi
+
+mv "$TMP" "$PREFS"
+trap - EXIT
+
+echo "fable rung:    $CUR -> $WANT"
+echo "cost pricing:  $PRICING -> $WANT_PRICING"
+echo ""
+
+if [ "$WANT" = "false" ]; then
+  # Said at the moment of the change rather than left in a doc: the panel
+  # shrinking is the part people discover later and read as a bug.
+  echo "Phase 3 reviewer panel: 3 models -> 2 (opus + sonnet)."
+  echo "Reviewer 1 lands on opus, which Reviewer 2 already holds, and dispatching"
+  echo "one model twice is not cross-model review. consensus.reviewerCount records 2."
+  echo "Triage also runs on opus, so it shares a model with Reviewer 1  -  the Phase 3"
+  echo "Step 3 anonymisation requirement is not optional while the rung is off."
+  echo ""
+fi
+
+host_note
+exit 0

package/pipeline/lib/outbound-gate.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * outbound-gate.mjs  -  nothing leaves this machine carrying a credential.
+ *
+ * The repo already has a leak scanner, and it looks at the wrong thing for
+ * this purpose: `smoke-personal-data.sh` audits the FILES IN THE REPO so the
+ * published pipeline stays generic. It never sees a Jira comment, a PR body or
+ * an issue update - text that a run composes at runtime out of command output,
+ * error messages and file excerpts, any of which can contain a token that was
+ * on the machine a second earlier.
+ *
+ * SCOPE, and the part the plan for this got wrong: corporate names are NOT
+ * checked here. A Jira comment on a corporate ticket legitimately contains the
+ * corporate project key, the repo name and the hostname - refusing those would
+ * make the gate fire on every correct publish, and a gate that cries wolf is
+ * turned off. Repo genericity and run-output hygiene are different jobs with
+ * different lists, and only the second one ships.
+ *
+ * WIRED INTO, and the honest limit: the three SHELL publishers -
+ * lib/jira-publish.sh (which is also how `channels` posts to Jira),
+ * lib/post-pr-review.sh (per-finding comments and the request-changes body),
+ * and scripts/update-issue-progress.sh. That is every publish this repo makes
+ * from a script.
+ *
+ * It is NOT every publish. `channels` also writes a Confluence page and a PR
+ * description, and those are composed and posted by the agent following the
+ * skill rather than by a script, so nothing in shell can intercept them. A
+ * gate that claimed four paths while covering three would be worse than one
+ * that covers three and says so.
+ *
+ * WHAT IT NEVER DOES: print the thing it found. A gate that echoes the secret
+ * into a terminal, a log and a CI transcript has moved it somewhere new.
+ * Findings are reported as rule name plus line number, nothing else.
+ *
+ * Usage:
+ *   cat body.md | outbound-gate.mjs                 # exit 0 clean, 7 if blocked
+ *   outbound-gate.mjs --file body.md
+ *   cat body.md | outbound-gate.mjs --json
+ *   cat body.md | outbound-gate.mjs --warn          # report, never block
+ *
+ * Exit codes:
+ *   0  -  nothing found
+ *   7  -  at least one finding; the caller must not publish
+ *   2  -  usage error (no input)
+ */
+
+import { readFileSync } from "node:fs";
+import { invokedDirectly } from "./invoked-directly.mjs";
+
+/**
+ * Each rule is a SHAPE, not a dictionary. A list of known token prefixes goes
+ * stale the moment a provider adds one; a shape keeps working.
+ *
+ * `confidence` separates the two kinds of finding. A GitHub PAT has a fixed
+ * prefix and length and is never a false positive - that blocks. An email
+ * address is a shape that legitimate prose contains, so it is reported and the
+ * caller decides. Mixing them would mean either blocking valid publishes or
+ * letting credentials through, and there is no threshold that does both.
+ */
+export const RULES = [
+  // --- credentials: a match is a match -------------------------------------
+  { name: "github-pat", certain: true, re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
+  { name: "github-fine-grained-pat", certain: true, re: /\bgithub_pat_[A-Za-z0-9_]{50,}\b/g },
+  { name: "slack-token", certain: true, re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g },
+  { name: "aws-access-key-id", certain: true, re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { name: "google-api-key", certain: true, re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { name: "openai-key", certain: true, re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/g },
+  { name: "anthropic-key", certain: true, re: /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g },
+  { name: "figma-token", certain: true, re: /\bfig[a-z]_[A-Za-z0-9_-]{20,}\b/g },
+  { name: "npm-token", certain: true, re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  {
+    name: "jwt",
+    certain: true,
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  },
+  { name: "private-key-block", certain: true, re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  // A URL carrying credentials. This is the one that leaks by accident most
+  // often: a `git remote -v` pasted into a comment.
+  {
+    name: "url-with-credentials",
+    certain: true,
+    re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@/g,
+  },
+  // `Authorization: Bearer <something long>` copied out of a curl trace.
+  {
+    name: "bearer-header",
+    certain: true,
+    re: /\bAuthorization:\s*(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{16,}/gi,
+  },
+
+  // --- PII and environment: a shape, so reported rather than certain -------
+  {
+    name: "email-address",
+    certain: false,
+    re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  },
+  // An absolute path under /Users or /home names the operator.
+  { name: "home-directory-path", certain: false, re: /\/(?:Users|home)\/[A-Za-z0-9_.-]+\//g },
+  {
+    name: "private-ip",
+    certain: false,
+    re: /\b(?:10\.\d{1,3}|192\.168|172\.(?:1[6-9]|2\d|3[01]))\.\d{1,3}\.\d{1,3}\b/g,
+  },
+];
+
+/**
+ * @param {string} text
+ * @returns {{rule: string, certain: boolean, line: number}[]}
+ */
+export function scan(text) {
+  const findings = [];
+  const lines = String(text).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    for (const rule of RULES) {
+      // `lastIndex` survives between calls on a /g regex and would make every
+      // second line skip its start. Reset per line.
+      rule.re.lastIndex = 0;
+      if (rule.re.test(lines[i])) {
+        findings.push({ rule: rule.name, certain: rule.certain, line: i + 1 });
+      }
+    }
+  }
+  return findings;
+}
+
+function readInput(args) {
+  const fileFlag = args.indexOf("--file");
+  if (fileFlag !== -1) {
+    const p = args[fileFlag + 1];
+    if (!p) {
+      process.stderr.write("outbound-gate: --file needs a path\n");
+      process.exitCode = 2;
+      return null;
+    }
+    return readFileSync(p, "utf-8");
+  }
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    process.stderr.write("outbound-gate: nothing on stdin and no --file\n");
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const text = readInput(args);
+  if (text === null) return;
+
+  const findings = scan(text);
+  const blocking = findings.filter((f) => f.certain);
+
+  if (args.includes("--json")) {
+    process.stdout.write(
+      JSON.stringify({ findings, blocked: blocking.length > 0 }, null, 2) + "\n",
+    );
+  } else if (findings.length) {
+    // Rule name and line only. The value is deliberately absent: writing it
+    // here would put the secret into a terminal, a log and a CI transcript.
+    const shown = findings.map(
+      (f) => `  ${f.certain ? "BLOCK" : "check"}  ${f.rule}  line ${f.line}`,
+    );
+    process.stderr.write(
+      `outbound-gate: ${findings.length} finding(s) in the text about to be published\n` +
+        shown.join("\n") +
+        "\n  (values are not printed - reading them out would move the secret here)\n",
+    );
+  }
+
+  if (blocking.length && !args.includes("--warn")) process.exitCode = 7;
+}
+
+const isDirectRun = invokedDirectly(import.meta.url);
+if (isDirectRun) main();