fix(ci): repair bridge boot gates

Author: hyperpolymath

.github/CICD-CHANGES-2026-06-04.md

@@ -1,3 +1,8 @@
+<!--
+SPDX-License-Identifier: MPL-2.0
+Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+
 # CI/CD Changes — 2026-06-04
 
 **Date:** 2026-06-04  
@@ -22,7 +27,7 @@ All 18 workflows in this repository have been updated to include `timeout-minute
 | Workflow | timeout-minutes | Concurrency Added | Notes |
 |----------|-----------------|------------------|-------|
 | `abi-drift.yml` | 15 | | ABI manifest + FFI verification |
-| `codeql.yml` | 15 | ✓ | Includes C++ support (has C/C++ headers) |
+| `codeql.yml` | 15 | ✓ | JavaScript/TypeScript CodeQL only; Zig FFI is covered by Zig workflows |
 | `container-publish.yml` | 30 | | Container build & push |
 | `dogfood-gate.yml` | 5-15 | ✓ | 6 jobs: a2ml(5), k9(5), empty-lint(15), groove(5), eclexiaiser(5), summary(5) |
 | `e2e.yml` | 15 | ✓ | MCP bridge input fuzz tests |
@@ -54,8 +59,13 @@ All 18 workflows in this repository have been updated to include `timeout-minute
 
 ## CodeQL Configuration
 
-**Languages:** `javascript-typescript` + `cpp`  
-**Reason:** This repository contains C/C++ headers in the FFI layer.
+**Languages:** `javascript-typescript`
+
+**Reason:** The FFI implementation is Zig. The tracked C ABI file is a generated
+header-only surface (`generated/abi/boj_catalogue.h`), not a C/C++ translation
+unit; enabling CodeQL `cpp` for headers alone makes extraction fail before
+analysis. Re-add `cpp` only when tracked `.c`, `.cc`, `.cpp`, or `.cxx` sources
+exist.
 
 ---
 

.github/workflows/codeql.yml

@@ -33,8 +33,10 @@ jobs:
         include:
           - language: javascript-typescript
             build-mode: none
-          - language: cpp
-            build-mode: none
+            # C/C++ CodeQL is intentionally not enabled for the generated
+            # header-only ABI surface. The FFI implementation is Zig and is
+            # covered by the Zig workflows; re-add cpp only when tracked
+            # .c/.cc/.cpp/.cxx translation units exist.
 
     steps:
       - name: Checkout

.github/workflows/dogfood-gate.yml

@@ -165,6 +165,9 @@ jobs:
             echo "::warning file=${REL_PATH}::Invisible Unicode characters detected (zero-width space, BOM, NBSP, etc.)"
           done < /tmp/empty-lint-results.txt
 
+      - name: Check shebang placement
+        run: bash scripts/check-shebang-first.sh
+
       - name: Write summary
         run: |
           if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then
@@ -374,4 +377,3 @@ jobs:
           *Generated by the [Dogfood Gate](https://github.com/hyperpolymath/rsr-template-repo) workflow.*
           *Dogfooding is guinea pig fooding — we test our tools on ourselves.*
           EOF
-

cartridges/claude-ai-mcp/src/server.js

@@ -1,6 +1,6 @@
+#!/usr/bin/env node
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-#!/usr/bin/env node
 //
 // claude-ai-mcp — Anthropic Messages API cartridge for the BoJ
 //

cartridges/model-router-mcp/src/router.js

@@ -1,6 +1,6 @@
+#!/usr/bin/env node
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-#!/usr/bin/env node
 //
 // Model Router — Intelligent model switching for Claude Code
 //

mcp-bridge/lib/generate-offline-menu.js

@@ -1,6 +1,6 @@
+#!/usr/bin/env -S deno run --allow-read
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-#!/usr/bin/env -S deno run --allow-read
 //
 // Generate offline-menu.js from the cartridges/ directory structure.
 //

mcp-bridge/lib/runtime.js

@@ -7,6 +7,8 @@
 // Supports the "Deno > Bun > NPM" hierarchy while maintaining
 // compatibility with Node-only MCP clients like Glama.
 
+import { writeSync as writeFdSync } from "node:fs";
+
 const isDeno = typeof globalThis.Deno !== "undefined";
 
 /** @type {{ get: (name: string) => string|undefined }} */
@@ -32,7 +34,7 @@ export const stdout = {
     if (isDeno) {
       globalThis.Deno.stdout.writeSync(buf);
     } else if (typeof process !== "undefined") {
-      process.stdout.write(buf);
+      writeFdSync(process.stdout.fd, buf);
     }
   }
 };
@@ -44,7 +46,7 @@ export const stderr = {
     if (isDeno) {
       globalThis.Deno.stderr.writeSync(buf);
     } else if (typeof process !== "undefined") {
-      process.stderr.write(buf);
+      writeFdSync(process.stderr.fd, buf);
     }
   }
 };

mcp-bridge/main.js

@@ -1,6 +1,6 @@
+#!/usr/bin/env -S deno run --allow-net --allow-env --allow-read
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-#!/usr/bin/env -S deno run --allow-net --allow-env --allow-read
 //
 // BoJ Server — MCP transport bridge (stdio + HTTP per ADR-0013)
 //
@@ -17,10 +17,8 @@
 
 import { env, stdout } from "./lib/runtime.js";
 import { sanitizeErrorMessage } from "./lib/security.js";
-import { dispatchMcpMessage } from "./lib/dispatcher.js";
 import { info, error as logError } from "./lib/logger.js";
 import * as otel from "./lib/otel.js";
-import { startHttpTransport } from "./lib/http-transport.js";
 
 const TRANSPORT = (env.get("BOJ_TRANSPORT") ?? "stdio").toLowerCase();
 
@@ -43,6 +41,15 @@ function sendError(id, code, message) {
   send({ jsonrpc: "2.0", id, error: { code, message: sanitizeErrorMessage(message) } });
 }
 
+let dispatchMcpMessagePromise;
+
+async function getDispatchMcpMessage() {
+  if (!dispatchMcpMessagePromise) {
+    dispatchMcpMessagePromise = import("./lib/dispatcher.js").then((m) => m.dispatchMcpMessage);
+  }
+  return dispatchMcpMessagePromise;
+}
+
 async function handleStdioLine(line) {
   let msg;
   try {
@@ -51,6 +58,7 @@ async function handleStdioLine(line) {
     sendError(null, -32700, "Parse error");
     return;
   }
+  const dispatchMcpMessage = await getDispatchMcpMessage();
   const response = await dispatchMcpMessage(msg, { transport: "stdio" });
   if (response !== null) send(response);
 }
@@ -77,8 +85,16 @@ async function runStdio() {
   if (typeof Deno !== "undefined") {
     for await (const chunk of Deno.stdin.readable) processChunk(chunk);
   } else {
-    // @ts-ignore: process is global in Node
-    for await (const chunk of process.stdin) processChunk(chunk);
+    await new Promise((resolve, reject) => {
+      // @ts-ignore: process is global in Node/Bun
+      process.stdin.on("data", processChunk);
+      // @ts-ignore: process is global in Node/Bun
+      process.stdin.once("end", resolve);
+      // @ts-ignore: process is global in Node/Bun
+      process.stdin.once("error", reject);
+      // @ts-ignore: process is global in Node/Bun
+      process.stdin.resume();
+    });
   }
   await Promise.allSettled(pendingMessages);
 }
@@ -88,6 +104,7 @@ async function runStdio() {
 // ===================================================================
 
 async function runHttp() {
+  const { startHttpTransport } = await import("./lib/http-transport.js");
   const handle = await startHttpTransport();
   await new Promise((resolve) => {
     const stop = async () => {

mcp-bridge/tests/boot_smoke.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MPL-2.0
-// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 //
 // BoJ Server — bridge boot smoke (runtime portability gate)
 //
@@ -58,14 +58,17 @@ let stdout = "";
 let stderr = "";
 child.stdout.on("data", (d) => (stdout += d));
 child.stderr.on("data", (d) => (stderr += d));
+child.stdin.on("error", (e) => (stderr += `stdin error: ${e.message}\n`));
 
 const killTimer = setTimeout(() => {
   console.error(`FAIL: bridge did not exit within ${TIMEOUT_MS}ms`);
   child.kill("SIGKILL");
 }, TIMEOUT_MS);
 
-child.stdin.write(requests.map((r) => JSON.stringify(r)).join("\n") + "\n");
-child.stdin.end();
+const payload = requests.map((r) => JSON.stringify(r)).join("\n") + "\n";
+child.once("spawn", () => {
+  child.stdin.end(payload);
+});
 
 child.on("close", (code) => {
   clearTimeout(killTimer);

scripts/check-shebang-first.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Shebangs are only interpreter directives when they are the first line.
+# A license header above "#!" makes Node, Deno, Bun, and POSIX shells parse it
+# as source text instead, so executable scripts must keep "#!" at line 1.
+
+set -euo pipefail
+
+fail=0
+
+while IFS= read -r -d '' path; do
+  case "$path" in
+    *.awk|*.bash|*.cjs|*.exs|*.fish|*.js|*.mjs|*.pl|*.py|*.rb|*.scm|*.sh|*.ts|*.zsh) ;;
+    *) continue ;;
+  esac
+
+  line_no=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_no=$((line_no + 1))
+    case "$line" in
+      '#!'*)
+        if [ "$line_no" != "1" ]; then
+          printf 'ERROR: %s:%s has a shebang after line 1\n' "$path" "$line_no" >&2
+          fail=1
+        fi
+        ;;
+    esac
+  done < "$path"
+done < <(git ls-files -z)
+
+if [ "$fail" -ne 0 ]; then
+  cat >&2 <<'EOF'
+
+Shebangs must be the first line of executable scripts. Put SPDX and copyright
+comments immediately after the shebang.
+EOF
+  exit 1
+fi
+
+echo "OK: all tracked shebangs are on line 1"