From 20b8435c1c78f5222881d7f261a0ab39e4e1226a Mon Sep 17 00:00:00 2001
From: Jake Sanders <jsanders@endor.ai>
Date: Tue, 4 Aug 2026 15:29:50 -0700
Subject: [PATCH 1/2] package-firewall: add dependency-free JSON editing
 primitives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First code chunk of the VS Code ecosystem. Nothing calls these yet — they are
added with their tests so the byte-fidelity properties can be reviewed on their
own, ahead of the lifecycle that uses them.

VS Code's product.json is the only config target here that is JSON, so it can
carry neither a '#' sentinel nor an ${ENDOR_*} reference, and it must be edited
in place with byte-exact restore. That rules out reserialization, and there is
no jq or python3 guarantee on a stock macOS or a minimal Linux image, so these
are line-oriented awk editors over the depth-1 object. plutil is not an option
either: it reorders every top-level key and minifies, and `plutil -lint` does
not even validate JSON.

  endor_b64url / endor_b64d          base64url on stdin, matching endor_b64
  endor_redact_ak                    strip the _ak/<token> path segment
  endor_file_has_final_newline
  endor_replace_contents_inplace     preserves inode, mode, owner and the
                                     source's final-newline state
  endor_json_top_string              depth-1 scalar, ignoring nested keys
  endor_json_extract_top_object      raw lines of a depth-1 object
  endor_json_merge_object_keys       key-level set and delete, commas recomputed
  endor_json_replace_top_object      verbatim splice-back, for restore
  endor_json_insert_top_line / endor_json_remove_top_key
  endor_json_validate

Two properties are the whole point, and both are asserted:

  - An edit touches only the keys it claims to. The patch is one key set and one
    removed; the diff against a pristine file is 3 lines, not a reserialized
    2963.
  - Restore is byte-exact. Shipped product.json has no final newline while awk
    always emits one, so the newline state is normalised back on write —
    otherwise every patch would dirty the last line and no restore could ever
    match.

Deleting or appending the last entry in an object must not leave a trailing
comma, so the merge recomputes entry-terminating commas rather than editing
lines in isolation. On input it cannot handle (minified, not line-oriented) each
editor declines with a non-zero return and leaves the file untouched, rather
than guessing.

endor_json_validate also rejects trailing commas structurally: node is not
always resolvable, and a trailing comma is precisely the malformation a bad
comma rewrite produces.

Tests: 43 assertions against a synthetic tests/fixtures/product.json — shaped
like a shipped one (tab-indented, LF, no final newline, extensionsGallery at
depth 1) but not tied to a VS Code build, so assertions like "16 accessSKUs"
don't start failing on VS Code's release schedule. Also covers 4-space
indentation, a sole-entry delete, and minified input.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 package-firewall/bash/lib/common.sh           | 294 ++++++++++++++++++
 package-firewall/tests/README.md              |  75 +++++
 package-firewall/tests/bash/harness.sh        |  88 ++++++
 .../tests/bash/json-primitives.sh             | 191 ++++++++++++
 .../tests/fixtures/.gitattributes             |   5 +
 package-firewall/tests/fixtures/product.json  |  74 +++++
 package-firewall/tests/run-all.sh             | 108 +++++++
 7 files changed, 835 insertions(+)
 create mode 100644 package-firewall/tests/README.md
 create mode 100644 package-firewall/tests/bash/harness.sh
 create mode 100755 package-firewall/tests/bash/json-primitives.sh
 create mode 100644 package-firewall/tests/fixtures/.gitattributes
 create mode 100644 package-firewall/tests/fixtures/product.json
 create mode 100755 package-firewall/tests/run-all.sh

diff --git a/package-firewall/bash/lib/common.sh b/package-firewall/bash/lib/common.sh
index 5dab948..c3ca813 100644
--- a/package-firewall/bash/lib/common.sh
+++ b/package-firewall/bash/lib/common.sh
@@ -22,6 +22,17 @@
 #   warn_if_xml_key_conflict <file> <pattern> <label>
 #                                              — same, but for XML-comment-delimited blocks
 #                                                (e.g. Maven settings.xml)
+#
+# VS Code (product.json) — see the "VS Code" section at the bottom of this file:
+#   endor_b64url / endor_b64d                  — base64url encode (stdin) / decode
+#   endor_json_*                               — dependency-free depth-1 JSON editors
+#
+# NOTE for anyone adding to this file: generate.sh inlines it via
+#   grep -v '^# ' lib/common.sh | sed '/^[[:space:]]*$/d'
+# so every column-0 comment and every blank line is stripped from the generated
+# scripts. Nothing here may depend on a blank line or a '# '-prefixed line *inside*
+# a heredoc — which is why the launchd plist and systemd units below are emitted
+# with printf rather than heredocs.
 
 # Sentinel markers — identical across all config files so re-runs and remove work reliably
 ENDOR_BLOCK_START="# ===== BEGIN ENDOR PACKAGE FIREWALL (managed — do not edit) ====="
@@ -33,6 +44,12 @@ ENDOR_BLOCK_END="# ===== END ENDOR PACKAGE FIREWALL ====="
 ENDOR_XML_BLOCK_START="<!-- ===== BEGIN ENDOR PACKAGE FIREWALL (managed — do not edit) ===== -->"
 ENDOR_XML_BLOCK_END="<!-- ===== END ENDOR PACKAGE FIREWALL ===== -->"
 
+# JSON sentinel — product.json cannot carry '#' comments, so the managed marker is
+# a top-level JSON key instead. Part of the same SENTINEL CONTRACT as the strings
+# above: changing it orphans the marker on every already-deployed machine, and the
+# marker is the only record of the original extensionsGallery. Do not change it.
+ENDOR_JSON_MARKER_KEY="_endorPackageFirewall"
+
 # ── User attribution helpers ──────────────────────────────────────────────────
 # Encode <console-user>@<machine> into the Basic-auth username. The firewall
 # decodes the label, auths with the real API key, and logs it as "User".
@@ -51,6 +68,36 @@ endor_urlenc_b64() {
   printf '%s' "$1" | sed -e 's/+/%2B/g' -e 's#/#%2F#g' -e 's/=/%3D/g'
 }
 
+# endor_b64url — base64url from stdin (matches endor_b64's stdin interface).
+# Used for the VS Code gallery URL, where the credential is a path segment rather
+# than userinfo, so '+' and '/' must be substituted rather than percent-encoded.
+# Padding is stripped; the firewall applies strings.TrimRight(token, "=") anyway.
+endor_b64url() {
+  endor_b64 | tr '+/' '-_' | tr -d '='
+}
+
+# endor_redact_ak — replace the _ak/<token> path segment on stdin.
+#
+# A deliberate deviation from the other ecosystems, which echo full credentialed
+# URLs in --dry-run: this token is a bearer credential in a URL *path*, and MDM
+# consoles retain script output for far more people than can read the target file.
+# Redacted wholesale rather than truncated to a prefix, so it is safe regardless
+# of token length.
+endor_redact_ak() {
+  sed -e 's#/_ak/[A-Za-z0-9_-]*#/_ak/<redacted>#g'
+}
+
+# endor_b64d — decode base64 from stdin. Probes for the flag rather than trying
+# and retrying, because a failed attempt would already have consumed stdin.
+# GNU and current macOS both accept --decode; older macOS base64 only had -D.
+endor_b64d() {
+  if base64 --help 2>&1 | grep -q -- '--decode'; then
+    base64 --decode
+  else
+    base64 -D
+  fi
+}
+
 # endor_host_label — a stable, human-readable machine name for attribution.
 endor_host_label() {
   scutil --get ComputerName 2>/dev/null || hostname 2>/dev/null || echo unknown
@@ -517,3 +564,250 @@ warn_if_xml_key_conflict() {
     _ENDOR_WARNED=1
   fi
 }
+
+# ══════════════════════════════════════════════════════════════════════════════
+# VS Code
+#
+# VS Code reads its extension gallery endpoints from product.json inside the
+# install directory. Unlike every other ecosystem here, the target file is owned
+# and rewritten by a third party (VS Code's own updater), and it is JSON, so it
+# can carry neither an Endor sentinel comment nor an env-var reference.
+#
+# Hence: a key-level merge into the depth-1 "extensionsGallery" object, and a
+# top-level JSON marker key holding the byte-exact original for restore.
+#
+# The editors below are deliberately line-oriented rather than JSON-aware. There
+# is no jq or python3 guarantee on a stock macOS or a minimal Linux image, and
+# plutil is not an option: it reorders every top-level key and minifies the file
+# (and `plutil -lint` does not even validate JSON — it accepts old-style plists).
+# Shipped product.json is pretty-printed, one entry per line, so a depth-1 line
+# range is unambiguous. Anything else makes these editors decline — they return
+# non-zero and leave the file untouched rather than guessing — so a caller can
+# fall back to a real JSON parser.
+# ══════════════════════════════════════════════════════════════════════════════
+
+# endor_file_has_final_newline <file>
+# Command substitution strips trailing newlines, so an empty capture of the last
+# byte means that byte was a newline.
+endor_file_has_final_newline() {
+  [[ -s "$1" ]] || return 1
+  [[ -z "$(tail -c 1 "$1")" ]]
+}
+
+# endor_replace_contents_inplace <file> <tmp>
+# Overwrites <file> with <tmp> in place, preserving inode, mode and owner — we
+# must never add a new file inside a signed app bundle, because an *added*
+# unsealed resource is worse for codesign than a modified one.
+#
+# Shipped product.json has no trailing newline but awk always emits one, so the
+# newline is normalised back to whatever the target had. Without this every patch
+# would dirty the final line and a restore could never be byte-exact.
+endor_replace_contents_inplace() {
+  local file="$1" tmp="$2" size
+  if [[ -f "$file" ]] && ! endor_file_has_final_newline "$file" \
+     && endor_file_has_final_newline "$tmp"; then
+    size=$(wc -c < "$tmp")
+    head -c "$(( size - 1 ))" "$tmp" > "$file"
+  else
+    cat "$tmp" > "$file"
+  fi
+}
+
+# endor_json_top_string <file> <key>
+# Prints a depth-1 string value. Anchored to the exact indent of the first
+# top-level key (line 2), because product.json contains nested "version" keys
+# hundreds of lines before the top-level one — an indent-agnostic match returns
+# the wrong value.
+endor_json_top_string() {
+  awk -v key="$2" '
+    function indentof(l,   s) { s = l; sub(/[^ \t].*/, "", s); return s }
+    NR == 2 { tind = indentof($0) }
+    NR >= 2 && !done && indentof($0) == tind {
+      pat = "^" tind "\"" key "\"[ \t]*:[ \t]*\""
+      if ($0 ~ pat) {
+        line = $0; sub(pat, "", line); sub(/".*/, "", line)
+        print line; done = 1; exit
+      }
+    }
+    END { exit(done ? 0 : 1) }
+  ' "$1"
+}
+
+# endor_json_extract_top_object <file> <key>
+# Prints the raw lines of a depth-1 object value, opening and closing lines
+# included. Returns 1 when the key is absent or the file is not line-oriented,
+# which is the signal to fall back to the node writer.
+endor_json_extract_top_object() {
+  local file="$1" key="$2"
+  awk -v key="$key" '
+    BEGIN { pat = "^[ \t]*\"" key "\"[ \t]*:[ \t]*\\{[ \t]*$" }
+    !inblk && $0 ~ pat { ind = $0; sub(/".*/, "", ind); inblk = 1; print; next }
+    inblk {
+      print
+      if ($0 == ind "}" || $0 == ind "},") { done = 1; exit }
+    }
+    END { exit(done ? 0 : 1) }
+  ' "$file"
+}
+
+# endor_json_merge_object_keys <file> <key> <setfile> <delfile>
+# Rewrites the depth-1 object <key>, printing the whole file to stdout:
+#   - each line in <setfile> ("key": value) replaces the matching entry in place,
+#     keeping its position, or is appended when the key is absent
+#   - each key named in <delfile> has its entry removed, however many lines it
+#     spans (so deleting a multi-line value like accessSKUs works)
+#   - entry-terminating commas are recomputed from scratch, so removing or
+#     appending the last entry cannot leave a trailing comma
+# Every other byte of the file passes through untouched. Returns 1 if <key> was
+# not found as a multi-line object.
+#
+# Entries are segmented by indent: a line whose indent equals the first inner
+# line's indent and which starts with "name": opens a new entry, and everything
+# more deeply indented belongs to the entry above it. That is what makes the
+# comma rewrite safe across nested arrays and objects.
+endor_json_merge_object_keys() {
+  local file="$1" key="$2" setfile="$3" delfile="$4"
+  awk -v key="$key" -v setfile="$setfile" -v delfile="$delfile" '
+    function entrykey(line,   k) {
+      if (match(line, /^[ \t]*"[^"]+"[ \t]*:/) == 0) return ""
+      k = substr(line, RSTART, RLENGTH)
+      sub(/^[ \t]*"/, "", k); sub(/"[ \t]*:$/, "", k)
+      return k
+    }
+    function indentof(line,   s) { s = line; sub(/[^ \t].*/, "", s); return s }
+    function flush(   i, j, k, n, out, line, last) {
+      for (i = 1; i <= nset; i++) {
+        if (setkey[i] in entryidx) {
+          j = entryidx[setkey[i]]; entrylines[j] = 1; entry[j, 1] = iind setline[i]
+        } else {
+          ne++; entryidx[setkey[i]] = ne; entrylines[ne] = 1
+          entry[ne, 1] = iind setline[i]
+        }
+      }
+      n = 0
+      for (i = 1; i <= ne; i++) if (!dropped[i]) out[++n] = i
+      for (i = 1; i <= n; i++) {
+        j = out[i]
+        last = entrylines[j]
+        for (k = 1; k <= last; k++) {
+          line = entry[j, k]
+          if (k == last) { sub(/,[ \t]*$/, "", line); if (i < n) line = line "," }
+          print line
+        }
+      }
+    }
+    BEGIN {
+      pat = "^[ \t]*\"" key "\"[ \t]*:[ \t]*\\{[ \t]*$"
+      while ((getline line < setfile) > 0) {
+        if (line ~ /^[ \t]*$/) continue
+        sub(/^[ \t]+/, "", line); sub(/,[ \t]*$/, "", line)
+        setline[++nset] = line; setkey[nset] = entrykey(line)
+      }
+      close(setfile)
+      while ((getline line < delfile) > 0) {
+        if (line ~ /^[ \t]*$/) continue
+        gsub(/[ \t]/, "", line); del[line] = 1
+      }
+      close(delfile)
+    }
+    !inblk && !after && $0 ~ pat { ind = indentof($0); inblk = 1; print; next }
+    inblk {
+      if ($0 == ind "}" || $0 == ind "},") {
+        flush(); print; inblk = 0; after = 1; next
+      }
+      if (iind == "") iind = indentof($0)
+      k = (indentof($0) == iind) ? entrykey($0) : ""
+      if (k != "") {
+        ne++; entryidx[k] = ne; entrylines[ne] = 0
+        if (k in del) dropped[ne] = 1
+      }
+      if (ne == 0) { ne = 1; entrylines[1] = 0 }
+      entry[ne, ++entrylines[ne]] = $0
+      next
+    }
+    { print }
+    END { exit(after ? 0 : 1) }
+  ' "$file"
+}
+
+# endor_json_replace_top_object <file> <key> <blockfile>
+# Replaces the depth-1 object <key> with the verbatim lines of <blockfile>, which
+# must include its own opening and closing lines. This is the restore path: the
+# captured original goes back exactly as it was. The trailing comma is taken from
+# whatever is being replaced, so the enclosing object stays well-formed.
+endor_json_replace_top_object() {
+  local file="$1" key="$2" blockfile="$3"
+  awk -v key="$key" -v blockfile="$blockfile" '
+    BEGIN { pat = "^[ \t]*\"" key "\"[ \t]*:[ \t]*\\{[ \t]*$" }
+    !inblk && !after && $0 ~ pat { ind = $0; sub(/".*/, "", ind); inblk = 1; next }
+    inblk {
+      if ($0 == ind "}" || $0 == ind "},") {
+        comma = ($0 ~ /,[ \t]*$/)
+        nb = 0
+        while ((getline line < blockfile) > 0) blk[++nb] = line
+        close(blockfile)
+        for (i = 1; i <= nb; i++) {
+          if (i == nb) { sub(/,[ \t]*$/, "", blk[i]); if (comma) blk[i] = blk[i] "," }
+          print blk[i]
+        }
+        inblk = 0; after = 1
+      }
+      next
+    }
+    { print }
+    END { exit(after ? 0 : 1) }
+  ' "$file"
+}
+
+# endor_json_insert_top_line <file> <line>
+# Inserts <line> immediately after the opening brace on line 1. Inserting at the
+# top means we emit our own trailing comma and never have to append one to a line
+# that already exists.
+endor_json_insert_top_line() {
+  awk -v ins="$2" 'NR == 1 { print; print ins; next } { print }' "$1"
+}
+
+# endor_json_remove_top_key <file> <key>
+# Removes a depth-1 key whose value is a single-line scalar or object — which is
+# how the marker is always written.
+endor_json_remove_top_key() {
+  awk -v key="$2" '
+    BEGIN { pat = "^[ \t]*\"" key "\"[ \t]*:" }
+    $0 ~ pat { next }
+    { print }
+  ' "$1"
+}
+
+# endor_json_validate <file> [node_bin]
+# Cheap structural self-check, always run; plus a real JSON.parse when a node
+# binary is available. Guards against ever installing a corrupt product.json.
+#
+# The trailing-comma check is not redundant with the node parse: node is not
+# always resolvable (some Linux layouts ship no Electron next to product.json),
+# and a dangling comma before } or ] is precisely what the comma rewrite in
+# endor_json_merge_object_keys could introduce. Checked structurally — a line
+# ending in a bare comma followed by a line starting with } or ] — because a
+# string value always ends in a quote, so this cannot false-positive on content.
+endor_json_validate() {
+  local file="$1" node_bin="${2:-}"
+
+  [[ -s "$file" ]] || return 1
+  [[ "$(head -c 1 "$file")" == "{" ]] || return 1
+  [[ "$(tr -d '[:space:]' < "$file" | tail -c 1)" == "}" ]] || return 1
+  [[ "$(grep -cF "\"${ENDOR_JSON_MARKER_KEY}\"" "$file")" -le 1 ]] || return 1
+
+  awk '
+    { line = $0; gsub(/^[ \t]+|[ \t]+$/, "", line) }
+    line == "" { next }
+    prev ~ /,$/ && line ~ /^[}\]]/ { bad = 1; exit }
+    { prev = line }
+    END { exit(bad ? 1 : 0) }
+  ' "$file" || return 1
+
+  if [[ -n "$node_bin" && -x "$node_bin" ]]; then
+    ENDOR_PJ="$file" ELECTRON_RUN_AS_NODE=1 "$node_bin" \
+      -e 'JSON.parse(require("fs").readFileSync(process.env.ENDOR_PJ,"utf8"))' \
+      >/dev/null 2>&1 || return 1
+  fi
+  return 0
+}
diff --git a/package-firewall/tests/README.md b/package-firewall/tests/README.md
new file mode 100644
index 0000000..d07f6f2
--- /dev/null
+++ b/package-firewall/tests/README.md
@@ -0,0 +1,75 @@
+# package-firewall tests
+
+Tests for the VS Code ecosystem.
+
+```sh
+cd package-firewall/tests
+./run-all.sh                 # every suite
+./run-all.sh --bash          # bash suites only
+./run-all.sh json            # suites matching a name
+```
+
+Suites are discovered by glob (`bash/*.sh`, `powershell/*.ps1`, minus the harness), so
+adding one needs no edit to the runner. Individual suites run standalone too:
+`bash bash/json-primitives.sh`.
+
+## Why VS Code has tests when the other ecosystems don't
+
+The other ecosystems append a sentinel-delimited block to a config file that nothing
+else rewrites. VS Code is different in three ways, and each one is a place to get
+byte-level fidelity wrong:
+
+1. **`product.json` is JSON**, so it can carry neither a `#` sentinel nor an
+   `${ENDOR_*}` reference. The managed marker has to be a top-level JSON key, and it
+   stores the original `extensionsGallery` object verbatim, because that is what makes
+   removal byte-exact. Nothing about that is checkable by eye.
+2. **The file lives inside a signed application bundle** and is replaced wholesale by
+   every VS Code update. Restore has to reproduce the original *exactly* — a stray
+   trailing newline is a permanent diff against the vendor file.
+3. **Two independent implementations** (awk and PowerShell, plus a node fallback on
+   each side) write the same marker and the same patched lines into the same file. An
+   admin may well run the bash script on Macs and the PowerShell one on Windows across
+   one fleet. If the ports drift, one platform's output stops being readable by the
+   other's state machine, and that surfaces as a mysterious re-patch loop rather than
+   as an error.
+
+## Layout
+
+| Path | |
+|---|---|
+| `run-all.sh` | runner; aggregates tallies, non-zero on any failure |
+| `fixtures/product.json` | synthetic `product.json` — the target for almost everything |
+| `bash/harness.sh` | paths, assertion helpers, the stripped-lib loader |
+| `bash/json-primitives.sh` | the awk JSON editing primitives in isolation |
+
+## The fixture, and why not a real install
+
+`fixtures/product.json` is synthetic but shaped like the real thing: tab-indented,
+LF line endings, **no final newline**, `extensionsGallery` at depth 1 with the same
+keys in the same order, a 16-entry multi-line `accessSKUs` array, and a *nested*
+`version` deeper in the file so "read the top-level key, not that one" stays a real
+assertion.
+
+Targeting an installed `product.json` instead would tie assertions like "16 SKUs" and
+"74 lines" to one VS Code build, so the suites would start failing on an unrelated
+schedule — VS Code's release schedule. The fixture makes those counts stable.
+
+Its byte layout *is* the test data. `fixtures/.gitattributes` sets `-text` so no
+checkout can normalise the line endings or add the final newline, and the missing final
+newline is intentional — git will say `\ No newline at end of file`, which is correct.
+
+Individual suites may additionally exercise a real installed `product.json` when one is
+present, asserting nothing version-specific.
+
+## Conventions
+
+- No root, no network, no writes outside a `mktemp` directory.
+- Suites source the lib in its **inlined** form (`grep -v '^# ' | sed '/^ *$/d'`), which
+  is what `generate.sh` actually embeds. Testing the pristine file would not prove that
+  nothing in the lib depends on a comment or a blank line surviving — and a heredoc body
+  silently would.
+- Suites keep going after a failure and print a tally, so one run reports every problem
+  rather than the first.
+- `python3` is required by the bash suites: several assertions are structural (key
+  order, array lengths, sibling survival), not just "is it valid JSON". Deliberately
+  not `node` — node is the lib's own fallback writer, so it is not an independent check.
diff --git a/package-firewall/tests/bash/harness.sh b/package-firewall/tests/bash/harness.sh
new file mode 100644
index 0000000..ea84f15
--- /dev/null
+++ b/package-firewall/tests/bash/harness.sh
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Shared harness for the bash suites. Sourced, never run.
+#
+# No `set` options here on purpose: each suite sets its own, and the assertion
+# helpers deliberately keep going after a failure so one run reports every
+# problem rather than the first.
+
+# ─── Paths ────────────────────────────────────────────────────────────────────
+# Everything is derived from this file's location, so the suites run from any cwd
+# and from a checkout at any path.
+TESTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PF_DIR="$(cd "$TESTS_DIR/.." && pwd)"
+REPO_DIR="$(cd "$PF_DIR/.." && pwd)"
+BASH_DIR="$PF_DIR/bash"
+LIB="$BASH_DIR/lib/common.sh"
+FIXTURE="$TESTS_DIR/fixtures/product.json"
+
+# Facts about the fixture that several suites assert against. Kept here so a
+# deliberate fixture edit is a one-line update instead of a scavenger hunt.
+FIXTURE_LINES=74           # real lines; `wc -l` reports 73 as the last has no newline
+FIXTURE_GALLERY_LINES=28   # extensionsGallery incl. its opening and closing lines
+FIXTURE_GALLERY_KEYS=9     # keys inside extensionsGallery
+FIXTURE_SKUS=16
+FIXTURE_VERSION="1.999.0"
+FIXTURE_COMMIT="0123456789abcdef0123456789abcdef01234567"
+
+# ─── Counters ─────────────────────────────────────────────────────────────────
+pass=0; fail=0; skipped=0
+ok()   { printf '  ok   %s\n' "$1"; pass=$((pass+1)); }
+bad()  { printf '  FAIL %s\n' "$1"; fail=$((fail+1)); }
+skip() { printf '  skip %s\n' "$1"; skipped=$((skipped+1)); }
+chk()  { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (got [$2] want [$3])"; fi; }
+
+# summarize — print the tally and set the exit status. Last line of every suite.
+summarize() {
+  echo
+  if [ "$skipped" -gt 0 ]; then
+    printf 'passed %d, failed %d, skipped %d\n' "$pass" "$fail" "$skipped"
+  else
+    printf 'passed %d, failed %d\n' "$pass" "$fail"
+  fi
+  [ "$fail" -eq 0 ]
+}
+
+# ─── Independent JSON parser ──────────────────────────────────────────────────
+# Checking the lib's output with the lib's own validator would be circular, so an
+# outside parser is required. python3 rather than node, because several assertions
+# are about structure (key order, array lengths, sibling survival) and not merely
+# validity — and because node is the lib's own fallback writer, so it is not
+# independent of the code under test.
+require_json_tool() {
+  command -v python3 >/dev/null 2>&1 && return 0
+  echo "ERROR: these suites need python3 to parse JSON independently of the code" >&2
+  echo "       under test. Install python3 and re-run." >&2
+  exit 2
+}
+
+# json_ok <file> — true when <file> parses as JSON.
+json_ok() { python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$1" 2>/dev/null; }
+
+# jget <file> <python-expr> — evaluate an expression against the parsed document,
+# available as `d`, and print the result. Used for structural assertions that a
+# grep cannot make honestly (key order, array lengths, sibling survival).
+jget() {
+  python3 -c '
+import json, sys
+d = json.load(open(sys.argv[1]))
+v = eval(sys.argv[2])
+print("" if v is None else ("true" if v is True else ("false" if v is False else v)))
+' "$1" "$2" 2>/dev/null
+}
+
+# ─── The lib, in the form that actually ships ─────────────────────────────────
+# inline_common() in generate.sh strips `^# ` comment lines and blank lines, so
+# the pristine file is not what runs on a managed machine. Testing the stripped
+# form is what proves nothing in the lib depends on a comment or a blank line
+# surviving — which a heredoc body silently would.
+strip_lib() { grep -v '^# ' "$LIB" | sed '/^[[:space:]]*$/d'; }
+
+# source_stripped_lib <workdir> — write the stripped lib into <workdir> and source
+# it, then set the two globals the lib expects its host script to have defined.
+source_stripped_lib() {
+  strip_lib > "$1/stripped.sh"
+  # shellcheck disable=SC1090
+  . "$1/stripped.sh"
+  DRY_RUN=0
+  _ENDOR_WARNED=0
+}
diff --git a/package-firewall/tests/bash/json-primitives.sh b/package-firewall/tests/bash/json-primitives.sh
new file mode 100755
index 0000000..e1f80ca
--- /dev/null
+++ b/package-firewall/tests/bash/json-primitives.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# The JSON editing primitives in bash/lib/common.sh, in isolation.
+#
+# product.json is JSON, so it can carry neither an Endor sentinel comment nor an
+# env-var reference — which is why these primitives exist at all, and why they are
+# awk rather than jq (no new dependency may be introduced on a managed machine).
+# Everything here is about byte-level fidelity: an edit must touch the two keys it
+# claims to touch and nothing else, and the original must come back byte-exact.
+#
+# Every mutation routes through endor_replace_contents_inplace, exactly as the
+# generated install script does, so trailing-newline fidelity is under test too.
+#
+# Target: tests/fixtures/product.json, whose shape mirrors a shipped product.json
+# (tab-indented, no final newline, extensionsGallery at depth 1). Pass a path to
+# run against a different file — a real install, say — but note that the
+# fixture-specific counts below will then not apply.
+set -uo pipefail
+. "$(dirname "${BASH_SOURCE[0]}")/harness.sh"
+require_json_tool
+
+T=$(mktemp -d)
+trap 'rm -rf "$T"' EXIT
+source_stripped_lib "$T"
+
+PJ_SRC="${1:-$FIXTURE}"
+PJ="$T/pj.json"
+cp "$PJ_SRC" "$PJ"
+echo "target: $PJ_SRC"
+
+URL='https://factory.endorlabs.com/v1/namespaces/spiderman/firewall/vscode/_ak/dGVzdDp0b2tlbg'
+MARK=$(printf '\t"_endorPackageFirewall": {"schema":1,"namespace":"spiderman"},')
+
+# apply <fn> <file> [args...] — run a primitive and write the result back in place,
+# the way the shipping code does.
+apply() {
+  local fn="$1" f="$2" t rc
+  shift 2
+  t="$T/apply.$$"
+  "$fn" "$f" "$@" > "$t"
+  rc=$?
+  [ "$rc" -eq 0 ] && endor_replace_contents_inplace "$f" "$t"
+  rm -f "$t"
+  return $rc
+}
+
+echo "== 1. extract a depth-1 object =="
+endor_json_extract_top_object "$PJ" extensionsGallery > "$T/orig.block"
+chk "exit 0"           "$?" "0"
+chk "opening line"     "$(head -1 "$T/orig.block" | tr '\t' '@')" '@"extensionsGallery": {'
+chk "closing line"     "$(tail -1 "$T/orig.block" | tr '\t' '@')" '@},'
+chk "captured every line" "$(wc -l < "$T/orig.block" | tr -d ' ')" "$FIXTURE_GALLERY_LINES"
+endor_json_extract_top_object "$PJ" noSuchKeyHere > /dev/null 2>&1
+chk "missing key -> exit 1" "$?" "1"
+chk "top-level version, not the nested one in builtInExtensions" \
+  "$(endor_json_top_string "$PJ" version)" "$FIXTURE_VERSION"
+chk "top-level commit" "$(endor_json_top_string "$PJ" commit)" "$FIXTURE_COMMIT"
+
+echo "== 2. the actual patch: set serviceUrl, delete extensionUrlTemplate =="
+printf '"serviceUrl": "%s"\n' "$URL" > "$T/set.txt"
+printf 'extensionUrlTemplate\n' > "$T/del.txt"
+cp "$PJ" "$T/patched.json"
+apply endor_json_merge_object_keys "$T/patched.json" extensionsGallery "$T/set.txt" "$T/del.txt"
+chk "exit 0" "$?" "0"
+if json_ok "$T/patched.json"; then ok "valid JSON"; else bad "INVALID JSON"; fi
+chk "serviceUrl points at the firewall" \
+  "$(jget "$T/patched.json" "d['extensionsGallery']['serviceUrl'].endswith('/_ak/dGVzdDp0b2tlbg')")" "true"
+chk "extensionUrlTemplate gone (the 5xx unpkg bypass)" \
+  "$(jget "$T/patched.json" "'extensionUrlTemplate' in d['extensionsGallery']")" "false"
+chk "every sibling key survived" \
+  "$(jget "$T/patched.json" "all(k in d['extensionsGallery'] for k in ('nlsBaseUrl','itemUrl','publisherUrl','resourceUrlTemplate','controlUrl','mcpUrl','accessSKUs'))")" "true"
+chk "accessSKUs untouched by a key-level merge" \
+  "$(jget "$T/patched.json" "len(d['extensionsGallery']['accessSKUs'])")" "$FIXTURE_SKUS"
+chk "top-level key order unchanged" \
+  "$(jget "$T/patched.json" "list(d.keys())" | tr -d " '")" \
+  "$(jget "$PJ" "list(d.keys())" | tr -d " '")"
+chk "no other top-level key touched" \
+  "$(jget "$T/patched.json" "{k:v for k,v in d.items() if k!='extensionsGallery'} == {k:v for k,v in __import__('json').load(open('$PJ')).items() if k!='extensionsGallery'}")" "true"
+# One line replaced (< plus >) and one line removed (<) = 3 diff lines. This is the
+# assertion that makes "one key set, one key removed" a checked claim rather than
+# an intention — a writer that reserialized the object would blow it up.
+chk "diff touches only the 2 intended keys" \
+  "$(diff "$PJ" "$T/patched.json" | grep -c '^[<>]')" "3"
+chk "final-newline state matches the source" \
+  "$(endor_file_has_final_newline "$T/patched.json" && echo y || echo n)" \
+  "$(endor_file_has_final_newline "$PJ" && echo y || echo n)"
+
+echo "== 3. delete the LAST entry, which is multi-line -> no trailing comma =="
+# The comma rewrite is the subtle part: JSON has no trailing commas, so removing or
+# appending the final entry must fix up the entry before it.
+printf 'accessSKUs\n' > "$T/del2.txt"; : > "$T/set2.txt"
+cp "$PJ" "$T/drop_last.json"
+apply endor_json_merge_object_keys "$T/drop_last.json" extensionsGallery "$T/set2.txt" "$T/del2.txt"
+if json_ok "$T/drop_last.json"; then ok "valid JSON"; else bad "INVALID JSON"; fi
+chk "the entry before it lost its comma" \
+  "$(endor_json_extract_top_object "$T/drop_last.json" extensionsGallery | tail -2 | head -1 | sed 's/^[[:space:]]*//')" \
+  '"mcpUrl": "https://main.vscode-cdn.net/mcp/servers.json"'
+
+echo "== 4. delete the FIRST entry =="
+printf 'nlsBaseUrl\n' > "$T/del4.txt"; : > "$T/set4.txt"
+cp "$PJ" "$T/drop_first.json"
+apply endor_json_merge_object_keys "$T/drop_first.json" extensionsGallery "$T/set4.txt" "$T/del4.txt"
+if json_ok "$T/drop_first.json"; then ok "valid JSON"; else bad "INVALID JSON"; fi
+chk "first entry gone, the rest intact" \
+  "$(jget "$T/drop_first.json" "'nlsBaseUrl' not in d['extensionsGallery'] and len(d['extensionsGallery'])==$((FIXTURE_GALLERY_KEYS - 1))")" "true"
+
+echo "== 5. append a key that is not there yet =="
+printf '"endorProbe": "x"\n' > "$T/set3.txt"; : > "$T/del3.txt"
+cp "$PJ" "$T/appended.json"
+apply endor_json_merge_object_keys "$T/appended.json" extensionsGallery "$T/set3.txt" "$T/del3.txt"
+if json_ok "$T/appended.json"; then ok "valid JSON"; else bad "INVALID JSON"; fi
+chk "appended, and the preceding entry gained its comma" \
+  "$(jget "$T/appended.json" "d['extensionsGallery']['endorProbe']=='x' and len(d['extensionsGallery']['accessSKUs'])==$FIXTURE_SKUS")" "true"
+
+echo "== 6. idempotency =="
+cp "$T/patched.json" "$T/patched2.json"
+apply endor_json_merge_object_keys "$T/patched2.json" extensionsGallery "$T/set.txt" "$T/del.txt"
+if cmp -s "$T/patched.json" "$T/patched2.json"; then ok "re-patch is byte-identical"; else bad "re-patch differs"; fi
+
+echo "== 7. restore round-trip =="
+cp "$T/patched.json" "$T/restored.json"
+apply endor_json_replace_top_object "$T/restored.json" extensionsGallery "$T/orig.block"
+chk "exit 0" "$?" "0"
+if cmp -s "$PJ" "$T/restored.json"; then ok "byte-identical to pristine"
+else bad "differs: $(diff "$PJ" "$T/restored.json" | head -4)"; fi
+
+echo "== 8. marker insert and removal =="
+cp "$T/patched.json" "$T/marked.json"
+apply endor_json_insert_top_line "$T/marked.json" "$MARK"
+if json_ok "$T/marked.json"; then ok "valid JSON with the marker"; else bad "INVALID with the marker"; fi
+chk "marker is readable by a real parser" \
+  "$(jget "$T/marked.json" "d['_endorPackageFirewall']['namespace']")" "spiderman"
+cp "$T/marked.json" "$T/unmarked.json"
+apply endor_json_remove_top_key "$T/unmarked.json" _endorPackageFirewall
+if cmp -s "$T/patched.json" "$T/unmarked.json"; then ok "removal is byte-exact"; else bad "removal differs"; fi
+
+echo "== 9. full lifecycle: pristine -> patch+mark -> unmark+restore =="
+cp "$PJ" "$T/life.json"
+apply endor_json_merge_object_keys "$T/life.json" extensionsGallery "$T/set.txt" "$T/del.txt"
+apply endor_json_insert_top_line "$T/life.json" "$MARK"
+if json_ok "$T/life.json"; then ok "the managed state is valid JSON"; else bad "managed state INVALID"; fi
+apply endor_json_remove_top_key "$T/life.json" _endorPackageFirewall
+apply endor_json_replace_top_object "$T/life.json" extensionsGallery "$T/orig.block"
+if cmp -s "$PJ" "$T/life.json"; then ok "returns to pristine bytes"; else bad "lifecycle drifted"; fi
+
+echo "== 10. the greps the state machine relies on =="
+# vscode_managed_state decides current-vs-stale with plain grep -F, so the patched
+# lines have to be greppable exactly as written.
+grep -qF "\"serviceUrl\": \"$URL\"" "$T/patched.json" \
+  && ok "expected serviceUrl line is greppable" || bad "grep -F for the serviceUrl line failed"
+grep -qF '"extensionUrlTemplate"' "$T/patched.json" \
+  && bad "extensionUrlTemplate still greppable" || ok "extensionUrlTemplate absent"
+
+echo "== 11. shapes other than the shipped one =="
+# 4-space indentation: the indent must be read from the file, never assumed to be
+# a tab. Forks and repackagers do reformat product.json.
+printf '{\n    "a": 1,\n    "extensionsGallery": {\n        "serviceUrl": "old",\n        "extensionUrlTemplate": "u",\n        "itemUrl": "i"\n    },\n    "z": 2\n}\n' > "$T/sp.json"
+apply endor_json_merge_object_keys "$T/sp.json" extensionsGallery "$T/set.txt" "$T/del.txt"
+if json_ok "$T/sp.json"; then ok "space-indented file valid"; else bad "space-indented file INVALID"; fi
+chk "space-indented: edit applied, siblings intact" \
+  "$(jget "$T/sp.json" "d['extensionsGallery']['serviceUrl'].startswith('https://factory') and 'extensionUrlTemplate' not in d['extensionsGallery'] and d['extensionsGallery']['itemUrl']=='i' and d['z']==2")" "true"
+chk "the set line took the file's own 8-space indent, not a tab" \
+  "$(awk '/factory/ { s=$0; sub(/[^ \t].*/,"",s); printf "%d:%s\n", length(s), (index(s,"\t")?"tab":"spaces"); exit }' "$T/sp.json")" \
+  "8:spaces"
+
+# Deleting the sole entry must leave a valid empty object, not a dangling comma.
+printf '{\n\t"extensionsGallery": {\n\t\t"extensionUrlTemplate": "u"\n\t}\n}\n' > "$T/only.json"
+apply endor_json_merge_object_keys "$T/only.json" extensionsGallery "$T/set2.txt" "$T/del.txt"
+if json_ok "$T/only.json"; then ok "deleting the sole entry leaves a valid empty object"
+else bad "sole-entry delete INVALID: $(cat "$T/only.json")"; fi
+
+# Minified: there is no depth-1 line range to edit, so the awk writer must decline
+# and leave the file alone — that refusal is what hands off to the node writer.
+printf '{"extensionsGallery":{"serviceUrl":"old"},"z":1}' > "$T/min.json"
+endor_json_extract_top_object "$T/min.json" extensionsGallery >/dev/null 2>&1
+chk "minified -> extract returns 1 (the fallback trigger)" "$?" "1"
+apply endor_json_merge_object_keys "$T/min.json" extensionsGallery "$T/set.txt" "$T/del.txt"
+chk "minified -> merge returns 1" "$?" "1"
+chk "minified file left untouched" "$(cat "$T/min.json")" '{"extensionsGallery":{"serviceUrl":"old"},"z":1}'
+
+echo "== 12. validation refuses what it must =="
+printf 'not json at all' > "$T/bad.json"
+chk "rejects non-JSON" "$(endor_json_validate "$T/bad.json" && echo y || echo n)" "n"
+printf '{\n\t"a": 1\n}\n' > "$T/good.json"
+chk "accepts good JSON" "$(endor_json_validate "$T/good.json" && echo y || echo n)" "y"
+# A trailing comma is precisely the malformation the comma rewrite can produce, and
+# it must be caught on machines where no node binary is resolvable.
+printf '{\n\t"a": 1,\n}\n' > "$T/tc.json"
+chk "rejects a trailing comma with no node available" \
+  "$(endor_json_validate "$T/tc.json" && echo y || echo n)" "n"
+
+summarize
diff --git a/package-firewall/tests/fixtures/.gitattributes b/package-firewall/tests/fixtures/.gitattributes
new file mode 100644
index 0000000..637b0a1
--- /dev/null
+++ b/package-firewall/tests/fixtures/.gitattributes
@@ -0,0 +1,5 @@
+# Byte fidelity is the point of these fixtures. The suites assert LF line endings
+# and the *absence* of a final newline, mirroring what VS Code actually ships, and
+# byte-exact restore is the property under test. `-text` disables every form of
+# eol conversion, so a Windows checkout with core.autocrlf=true cannot rewrite them.
+*.json -text
diff --git a/package-firewall/tests/fixtures/product.json b/package-firewall/tests/fixtures/product.json
new file mode 100644
index 0000000..66c66c2
--- /dev/null
+++ b/package-firewall/tests/fixtures/product.json
@@ -0,0 +1,74 @@
+{
+	"nameShort": "Code",
+	"nameLong": "Visual Studio Code",
+	"applicationName": "code",
+	"dataFolderName": ".vscode",
+	"win32MutexName": "vscode",
+	"quality": "stable",
+	"commit": "0123456789abcdef0123456789abcdef01234567",
+	"date": "2026-01-15T09:00:00.000Z",
+	"version": "1.999.0",
+	"webviewContentExternalBaseUrlTemplate": "https://{{uuid}}.vscode-cdn.net/{{quality}}/{{commit}}/out/vs/workbench/contrib/webview/browser/pre/",
+	"extensionsGallery": {
+		"nlsBaseUrl": "https://www.vscode-unpkg.net/_lp/",
+		"serviceUrl": "https://marketplace.visualstudio.com/_apis/public/gallery",
+		"itemUrl": "https://marketplace.visualstudio.com/items",
+		"publisherUrl": "https://marketplace.visualstudio.com/publishers",
+		"resourceUrlTemplate": "https://{publisher}.vscode-unpkg.net/{publisher}/{name}/{version}/{path}",
+		"extensionUrlTemplate": "https://www.vscode-unpkg.net/_gallery/{publisher}/{name}/latest",
+		"controlUrl": "https://main.vscode-cdn.net/extensions/marketplace.json",
+		"mcpUrl": "https://main.vscode-cdn.net/mcp/servers.json",
+		"accessSKUs": [
+			"copilot_enterprise_seat",
+			"copilot_enterprise_seat_quota",
+			"copilot_enterprise_seat_multi_quota",
+			"copilot_enterprise_seat_assignment",
+			"copilot_enterprise_seat_assignment_quota",
+			"copilot_enterprise_seat_assignment_multi_quota",
+			"copilot_enterprise_trial_seat",
+			"copilot_enterprise_trial_seat_quota",
+			"copilot_for_business_seat",
+			"copilot_for_business_seat_quota",
+			"copilot_for_business_seat_multi_quota",
+			"copilot_for_business_seat_assignment",
+			"copilot_for_business_seat_assignment_quota",
+			"copilot_for_business_seat_assignment_multi_quota",
+			"copilot_for_business_trial_seat",
+			"copilot_for_business_trial_seat_quota"
+		]
+	},
+	"linkProtectionTrustedDomains": [
+		"https://open-vsx.org",
+		"https://github.com"
+	],
+	"extensionEnabledApiProposals": {
+		"ms-vscode.vscode-selfhost-test-provider": [
+			"testObserver"
+		]
+	},
+	"builtInExtensions": [
+		{
+			"name": "ms-vscode.js-debug",
+			"version": "9.9.9",
+			"repo": "https://github.com/microsoft/vscode-js-debug",
+			"metadata": {
+				"id": "00000000-0000-0000-0000-000000000001",
+				"publisherId": {
+					"publisherId": "00000000-0000-0000-0000-000000000002",
+					"publisherName": "ms-vscode",
+					"displayName": "Microsoft",
+					"flags": "verified"
+				},
+				"publisherDisplayName": "Microsoft"
+			}
+		}
+	],
+	"tasConfig": {
+		"endpoint": "https://example.invalid/vscode/ab",
+		"telemetryEventName": "query-expfeature"
+	},
+	"win32TunnelServiceMutex": "vscode-tunnelservice",
+	"aiConfig": {
+		"ariaKey": "0000000000000000000000000000000000000000000000000000000000000000"
+	}
+}
\ No newline at end of file
diff --git a/package-firewall/tests/run-all.sh b/package-firewall/tests/run-all.sh
new file mode 100755
index 0000000..443b344
--- /dev/null
+++ b/package-firewall/tests/run-all.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Runs every suite and aggregates the tallies.
+#
+#   ./run-all.sh              all suites
+#   ./run-all.sh lib watcher  only suites whose name matches one of these
+#   ./run-all.sh --bash       only the bash suites
+#   ./run-all.sh --powershell only the PowerShell suites
+#
+# Suites are discovered by glob — bash/*.sh and powershell/*.ps1, minus the shared
+# harness — so adding one needs no edit here.
+#
+# Nothing here needs root, and nothing touches an installed VS Code: the suites work
+# on copies of tests/fixtures/product.json inside a temp directory.
+set -uo pipefail
+cd "$(dirname "$0")"
+
+want_bash=1; want_ps=1
+filters=()
+for a in "$@"; do
+  case "$a" in
+    --bash)       want_ps=0 ;;
+    --powershell) want_bash=0 ;;
+    -h|--help)    sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)            filters+=("$a") ;;
+  esac
+done
+
+wanted() {
+  [ "${#filters[@]}" -eq 0 ] && return 0
+  local f
+  for f in "${filters[@]}"; do case "$1" in *"$f"*) return 0 ;; esac; done
+  return 1
+}
+
+# discover <dir> <ext> — suite paths, excluding the dot-sourced harness.
+discover() {
+  local p
+  for p in "$1"/*."$2"; do
+    [ -e "$p" ] || continue
+    case "$(basename "$p")" in harness.sh|Harness.ps1) continue ;; esac
+    printf '%s\n' "$p"
+  done
+}
+
+PWSH=$(command -v pwsh || command -v powershell || true)
+tot_pass=0; tot_fail=0; tot_skip=0; failed_suites=(); ran=0
+
+run() { # run <label> <command...>
+  local label="$1"; shift
+  printf '\n\033[1m─── %s ───\033[0m\n' "$label"
+  local out rc line
+  out=$("$@" 2>&1); rc=$?
+  printf '%s\n' "$out"
+  ran=$((ran+1))
+  # The tally line every suite ends with.
+  line=$(printf '%s' "$out" | grep -E '^passed [0-9]+, failed [0-9]+' | tail -1)
+  if [ -n "$line" ]; then
+    tot_pass=$(( tot_pass + $(printf '%s' "$line" | sed -n 's/^passed \([0-9]*\).*/\1/p') ))
+    tot_fail=$(( tot_fail + $(printf '%s' "$line" | sed -n 's/.*failed \([0-9]*\).*/\1/p') ))
+    case "$line" in *skipped*)
+      tot_skip=$(( tot_skip + $(printf '%s' "$line" | sed -n 's/.*skipped \([0-9]*\).*/\1/p') )) ;;
+    esac
+  else
+    # No tally means the suite died before finishing, which must not be mistaken for
+    # a pass.
+    tot_fail=$(( tot_fail + 1 ))
+  fi
+  [ "$rc" -eq 0 ] || failed_suites+=("$label")
+}
+
+if [ "$want_bash" -eq 1 ]; then
+  while IFS= read -r s; do
+    label="bash/$(basename "$s" .sh)"
+    wanted "$label" && run "$label" bash "$s"
+  done < <(discover bash sh)
+fi
+
+if [ "$want_ps" -eq 1 ]; then
+  ps_wanted=0
+  while IFS= read -r s; do
+    label="powershell/$(basename "$s" .ps1)"
+    wanted "$label" || continue
+    ps_wanted=$((ps_wanted+1))
+    [ -n "$PWSH" ] && run "$label" "$PWSH" -NoProfile -File "$s"
+  done < <(discover powershell ps1)
+  if [ -z "$PWSH" ] && [ "$ps_wanted" -gt 0 ]; then
+    printf '\n\033[1m─── powershell ───\033[0m\n'
+    echo "  skip $ps_wanted PowerShell suite(s) (no pwsh on PATH)"
+    echo "       macOS/Linux: brew install powershell  |  https://aka.ms/powershell"
+    tot_skip=$(( tot_skip + ps_wanted ))
+  fi
+fi
+
+printf '\n\033[1m─── total ───\033[0m\n'
+if [ "$ran" -eq 0 ] && [ "$tot_skip" -eq 0 ]; then
+  echo "no suites matched"
+  exit 1
+fi
+if [ "$tot_skip" -gt 0 ]; then
+  printf 'passed %d, failed %d, skipped %d\n' "$tot_pass" "$tot_fail" "$tot_skip"
+else
+  printf 'passed %d, failed %d\n' "$tot_pass" "$tot_fail"
+fi
+if [ "${#failed_suites[@]}" -gt 0 ]; then
+  printf 'failing suites: %s\n' "${failed_suites[*]}"
+  exit 1
+fi
+[ "$tot_fail" -eq 0 ]

From 8e733c6f1408ad88eaa3051c59480138649f665f Mon Sep 17 00:00:00 2001
From: Jake Sanders <jsanders@endor.ai>
Date: Thu, 6 Aug 2026 17:09:54 -0700
Subject: [PATCH 2/2] package-firewall: satisfy shellcheck on the test harness

The harness is sourced, so the constants it defines are read by the suites
and never by the file itself, which shellcheck cannot see from a single-file
lint. Declare that once at the top rather than per variable.

REPO_DIR and FIXTURE_LINES had no reader at all; the 74-line fact is already
recorded in tests/README.md.

run-all.sh runs without -e, so an unguarded cd would have let suite discovery
glob the caller's directory instead of failing.
---
 package-firewall/tests/bash/harness.sh | 6 ++++--
 package-firewall/tests/run-all.sh      | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/package-firewall/tests/bash/harness.sh b/package-firewall/tests/bash/harness.sh
index ea84f15..04bb2d8 100644
--- a/package-firewall/tests/bash/harness.sh
+++ b/package-firewall/tests/bash/harness.sh
@@ -4,20 +4,22 @@
 # No `set` options here on purpose: each suite sets its own, and the assertion
 # helpers deliberately keep going after a failure so one run reports every
 # problem rather than the first.
+#
+# Every name defined below is read by the suites that source this file, never
+# within the file itself, which shellcheck has no way to see from here.
+# shellcheck disable=SC2034
 
 # ─── Paths ────────────────────────────────────────────────────────────────────
 # Everything is derived from this file's location, so the suites run from any cwd
 # and from a checkout at any path.
 TESTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PF_DIR="$(cd "$TESTS_DIR/.." && pwd)"
-REPO_DIR="$(cd "$PF_DIR/.." && pwd)"
 BASH_DIR="$PF_DIR/bash"
 LIB="$BASH_DIR/lib/common.sh"
 FIXTURE="$TESTS_DIR/fixtures/product.json"
 
 # Facts about the fixture that several suites assert against. Kept here so a
 # deliberate fixture edit is a one-line update instead of a scavenger hunt.
-FIXTURE_LINES=74           # real lines; `wc -l` reports 73 as the last has no newline
 FIXTURE_GALLERY_LINES=28   # extensionsGallery incl. its opening and closing lines
 FIXTURE_GALLERY_KEYS=9     # keys inside extensionsGallery
 FIXTURE_SKUS=16
diff --git a/package-firewall/tests/run-all.sh b/package-firewall/tests/run-all.sh
index 443b344..3f4314b 100755
--- a/package-firewall/tests/run-all.sh
+++ b/package-firewall/tests/run-all.sh
@@ -12,7 +12,7 @@
 # Nothing here needs root, and nothing touches an installed VS Code: the suites work
 # on copies of tests/fixtures/product.json inside a temp directory.
 set -uo pipefail
-cd "$(dirname "$0")"
+cd "$(dirname "$0")" || exit 1
 
 want_bash=1; want_ps=1
 filters=()