@oneie/claude 0.7.0 → 0.9.0

package/scripts/govern-mem-check.sh

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# govern-mem-check.sh — prove the machine governor's memory probe can say NO.
+#
+#   bash .claude/scripts/govern-mem-check.sh            # all checks
+#   bash .claude/scripts/govern-mem-check.sh --self-test # same, explicit
+#   bash .claude/scripts/govern-mem-check.sh --live      # just read this box
+#
+# WHY THIS EXISTS
+# gate_headroom used to compute availability as
+#     hw.memsize * (memory_pressure "free percentage") / 100
+# and that percentage counts reclaimable memory — file cache, purgeable, and
+# already-compressed pages — as free. It is a PRESSURE signal, not a quantity.
+# Measured three times on one 24GB box, all while ~1% of RAM was actually free
+# and 9-12 GB sat in swap, the old probe answered "room for 2 / 7 / 7 more
+# 2GB cycles". A governor that cannot say no is not a governor.
+#
+# Every check below drives a SYNTHETIC machine state — a fake vm_stat, a fake
+# memory_pressure block and a fake vm.swapusage line, together, so the old
+# formula and the new one see the SAME input and the comparison is honest.
+# Stubbing is done by overriding _gv_vm_stat / _gv_swapusage / _gv_memsize,
+# the same idiom govern-claims-check.sh uses to stub _gv_alive.
+#
+# Nothing here touches the real machine, the real $GOVERN_DIR, or any gate.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT" || exit 1
+
+# Sandbox: never touch the machine-wide governor dir.
+export GOVERN_DIR="${TMPDIR:-/tmp}/one-govern-memcheck.$$"
+mkdir -p "$GOVERN_DIR"
+trap 'rm -rf "$GOVERN_DIR"' EXIT
+
+# shellcheck source=lib/govern.sh
+. "$ROOT/.claude/scripts/lib/govern.sh"
+
+PASS=0; FAIL=0
+ok()   { PASS=$((PASS+1)); printf '  \033[32mPASS\033[0m  %s\n' "$*"; }
+bad()  { FAIL=$((FAIL+1)); printf '  \033[31mFAIL\033[0m  %s\n' "$*"; }
+hdr()  { printf '\n\033[1m%s\033[0m\n' "$*"; }
+
+# ── the pre-fix arithmetic, VERBATIM ────────────────────────────────────────
+# Copied unchanged from lib/govern.sh before 2026-09-03 (the `deploy-gate-check.sh`
+# idiom: carry the old code so the red proof is a real comparison, not a story).
+_old_gate_headroom() {
+  local total_gb free_pct avail_gb usable_gb per_cycle reserve slots
+  total_gb=$(( $(_gv_memsize 2>/dev/null || echo 0) / 1073741824 ))
+  [ "$total_gb" -lt 1 ] && { echo 99; return 0; }
+  free_pct=$(_gv_memory_pressure 2>/dev/null | awk -F': ' '/free percentage/{gsub(/%/,"",$2); print int($2)}')
+  [ -z "$free_pct" ] && { echo 99; return 0; }
+  per_cycle="${GOVERN_GB_PER_CYCLE:-2}"
+  reserve="${GOVERN_RESERVE_GB:-2}"
+  avail_gb=$(( total_gb * free_pct / 100 ))
+  usable_gb=$(( avail_gb - reserve ))
+  [ "$usable_gb" -lt 0 ] && usable_gb=0
+  slots=$(( usable_gb / per_cycle ))
+  [ "$slots" -lt 1 ] && slots=1
+  echo "$slots"
+}
+_old_gate_pressure() {
+  local free_pct
+  free_pct=$(_gv_memory_pressure 2>/dev/null | awk -F': ' '/free percentage/{gsub(/%/,"",$2); print $2}')
+  [ -z "$free_pct" ] && return 0
+  [ "$free_pct" -lt "${GOVERN_MIN_FREE_PCT:-12}" ] && return 1
+  return 0
+}
+
+# ── synthetic machine states ────────────────────────────────────────────────
+# All on a 24 GB / 16384-byte-page box, so hw.memsize is constant and only the
+# page counts move. FIX_* are set by fixture(); the stubs read them.
+FIX_FREE=0; FIX_PURGE=0; FIX_INACT=0; FIX_FILEBK=0; FIX_ACTIVE=0; FIX_WIRED=0
+FIX_COMPRESSOR=0; FIX_PCT=0; FIX_SWAP_USED="0.00"; FIX_SWAP_TOTAL="0.00"
+FIX_MODE=normal   # normal | empty | garbage | nopagesize
+
+_gv_memsize()   { [ "$FIX_MODE" = "nomemsize" ] && return 1; echo 25769803776; }
+_gv_swapusage() { echo "total = ${FIX_SWAP_TOTAL}M  used = ${FIX_SWAP_USED}M  free = 0.00M  (encrypted)"; }
+_gv_memory_pressure() {
+  cat <<PRESSURE
+Swapins: 1614739
+Swapouts: 2928367
+
+Page Q counts:
+Pages active: $FIX_ACTIVE
+Pages inactive: $FIX_INACT
+Pages speculative: 6772
+Pages throttled: 0
+Pages wired down: $FIX_WIRED
+
+Compressor Stats:
+Pages used by compressor: $FIX_COMPRESSOR
+
+System-wide memory free percentage: ${FIX_PCT}%
+PRESSURE
+}
+_gv_vm_stat() {
+  case "$FIX_MODE" in
+    empty)      return 0 ;;
+    garbage)    echo "vm_stat: command not found"; return 0 ;;
+    nopagesize) echo "Mach Virtual Memory Statistics:" ;;
+    *)          echo "Mach Virtual Memory Statistics: (page size of 16384 bytes)" ;;
+  esac
+  cat <<VMSTAT
+Pages free:                                   $FIX_FREE.
+Pages active:                                 $FIX_ACTIVE.
+Pages inactive:                               $FIX_INACT.
+Pages speculative:                              6772.
+Pages throttled:                                   0.
+Pages wired down:                             $FIX_WIRED.
+Pages purgeable:                              $FIX_PURGE.
+File-backed pages:                            $FIX_FILEBK.
+Anonymous pages:                              893951.
+Pages occupied by compressor:                 $FIX_COMPRESSOR.
+Swapins:                                     1614739.
+Swapouts:                                    2928367.
+VMSTAT
+}
+
+fixture() {
+  FIX_MODE=normal
+  case "$1" in
+    # ── The live reading taken 2026-09-03 at load 8, verbatim from vm_stat and
+    #    memory_pressure on the box the operator was complaining about. It
+    #    reproduces Receipt B: 1.3% of RAM free, 9.4 GB in swap, probe says 7.
+    thrash-now)
+      FIX_FREE=21032; FIX_PURGE=646; FIX_INACT=547837; FIX_FILEBK=216477
+      FIX_ACTIVE=555819; FIX_WIRED=250202; FIX_COMPRESSOR=135982
+      FIX_PCT=74; FIX_SWAP_USED="9400.56"; FIX_SWAP_TOTAL="10240.00" ;;
+    # ── Receipt A: the verifier's sample at load 27, with hook:load-guard itself
+    #    reporting the machine saturated. free 15798 pages, compressor 8.7 GB,
+    #    swap 11997/13312 M, memory_pressure 32%. Old probe answered 2.
+    thrash-A)
+      FIX_FREE=15798; FIX_PURGE=500; FIX_INACT=137812; FIX_FILEBK=100000
+      FIX_ACTIVE=600000; FIX_WIRED=250000; FIX_COMPRESSOR=569254
+      FIX_PCT=32; FIX_SWAP_USED="11997.44"; FIX_SWAP_TOTAL="13312.00" ;;
+    # ── The row that kills a swap-subtraction design: genuinely idle NOW
+    #    (8 GB free, 6 GB cache) but macOS has not released the 9.4 GB swapfile
+    #    it grew an hour ago. A probe that charges for history serialises this.
+    recovered-idle)
+      FIX_FREE=524288; FIX_PURGE=1000; FIX_INACT=655360; FIX_FILEBK=393216
+      FIX_ACTIVE=200000; FIX_WIRED=200000; FIX_COMPRESSOR=50000
+      FIX_PCT=85; FIX_SWAP_USED="9400.56"; FIX_SWAP_TOTAL="10240.00" ;;
+    # ── Fresh idle: 12 GB free, swap never grown.
+    fresh-idle)
+      FIX_FREE=786432; FIX_PURGE=500; FIX_INACT=65536; FIX_FILEBK=131072
+      FIX_ACTIVE=100000; FIX_WIRED=150000; FIX_COMPRESSOR=20000
+      FIX_PCT=90; FIX_SWAP_USED="0.00"; FIX_SWAP_TOTAL="0.00" ;;
+    # ── Absurd: nothing available at all. Must floor to 1, never 0 —
+    #    do-fleet.sh clamps its slot count to this with no floor of its own.
+    starved)
+      FIX_FREE=0; FIX_PURGE=0; FIX_INACT=0; FIX_FILEBK=0
+      FIX_ACTIVE=1000000; FIX_WIRED=500000; FIX_COMPRESSOR=72864
+      FIX_PCT=1; FIX_SWAP_USED="16000.00"; FIX_SWAP_TOTAL="16384.00" ;;
+    *) echo "unknown fixture $1" >&2; exit 2 ;;
+  esac
+}
+
+# The environment the checks are scored in: the box's real settings.json values
+# minus the stale GOVERN_GB_PER_CYCLE pin, so the derived price is live.
+unset GOVERN_GB_PER_CYCLE
+export GOVERN_RESERVE_GB=3
+export VITEST_MAX_FORKS=4          # what a Claude Code session actually sets
+
+[ "${1:-}" = "--live" ] && { echo "live: $(gate_mem_report)"; exit 0; }
+
+# ═══════════════════════════════════════════════════════════════════════════
+hdr "1. THRASH — the new probe says no, and the OLD one says yes (red proof)"
+for st in thrash-now thrash-A; do
+  fixture "$st"
+  new=$(gate_headroom); old=$(_old_gate_headroom)
+  avail=$(gate_mem_avail_mb)
+  oldpct=$FIX_PCT
+  if _old_gate_pressure; then oldp="0 (has headroom)"; else oldp="1 (thrashing)"; fi
+  if gate_pressure;      then newp="0 (has headroom)"; else newp="1 (thrashing)"; fi
+  echo "  [$st] memory_pressure says ${oldpct}% free · vm_stat says $((FIX_FREE*16384/1048576))MB free · swap ${FIX_SWAP_USED}M used"
+  echo "        OLD: headroom=$old  pressure=$oldp        NEW: avail=${avail}MB headroom=$new  pressure=$newp"
+  [ "$new" -eq 1 ] && ok "$st: new cap FELL to 1" || bad "$st: new cap is $new, expected 1"
+  [ "$old" -gt 1 ] && ok "$st: OLD arithmetic authorised $old cycles on this same state (red proof)" \
+                   || bad "$st: OLD arithmetic did not over-authorise — red proof is inert"
+  _old_gate_pressure && ok "$st: OLD gate_pressure called it healthy (red proof)" \
+                     || bad "$st: OLD gate_pressure already fired — red proof is inert"
+  gate_pressure && bad "$st: NEW gate_pressure still calls it healthy" \
+                || ok "$st: NEW gate_pressure fires"
+done
+
+hdr "2. HEALTHY — not replaced by a serialising bug"
+for st in recovered-idle fresh-idle; do
+  fixture "$st"
+  new=$(gate_headroom); avail=$(gate_mem_avail_mb)
+  echo "  [$st] avail=${avail}MB  swap ${FIX_SWAP_USED}M used  ->  headroom=$new"
+  [ "$new" -ge 2 ] && ok "$st: healthy box still funds $new cycles (>=2)" \
+                   || bad "$st: healthy box collapsed to $new — this is the serialising bug"
+  gate_pressure && ok "$st: gate_pressure stays quiet" || bad "$st: gate_pressure fired on a healthy box"
+done
+echo "  (recovered-idle is the row that refutes any design subtracting vm.swapusage:"
+echo "   9.4GB of stale swap would drive it to 1 while 8GB of RAM sits free.)"
+
+hdr "3. BROKEN SENSOR — 99, never 0, never 1"
+for mode in empty garbage nopagesize; do
+  fixture thrash-now; FIX_MODE="$mode"
+  h=$(gate_headroom)
+  [ "$h" = "99" ] && ok "vm_stat '$mode' -> headroom=99 (do not constrain)" \
+                  || bad "vm_stat '$mode' -> headroom=$h, expected 99"
+  gate_pressure && ok "vm_stat '$mode' -> gate_pressure does not block" \
+                || bad "vm_stat '$mode' -> gate_pressure blocked on a broken probe"
+done
+
+hdr "4. FLOOR — a starved box slows down, it never stops"
+fixture starved
+h=$(gate_headroom); a=$(gate_mem_avail_mb)
+echo "  avail=${a}MB, reserve=$((GOVERN_RESERVE_GB*1024))MB, price=$(gate_price_mb)MB -> headroom=$h"
+[ "$h" = "1" ] && ok "starved box -> 1 (do-fleet.sh clamps to this with no floor of its own; 0 would launch nothing)" \
+               || bad "starved box -> $h, expected 1"
+
+hdr "5. PRICE — derived from the live fork count, not a stale constant"
+p4=$(VITEST_MAX_FORKS=4 gate_price_mb)
+p8=$(VITEST_MAX_FORKS=8 gate_price_mb)
+pdef=$(unset VITEST_MAX_FORKS; gate_price_mb)
+povr=$(GOVERN_GB_PER_CYCLE=2 gate_price_mb)
+echo "  forks=4 -> ${p4}MB · forks=8 -> ${p8}MB · unset -> ${pdef}MB · GOVERN_GB_PER_CYCLE=2 -> ${povr}MB"
+[ "$p8" -gt "$p4" ]  && ok "price tracks fork count (8 forks cost more than 4)" || bad "price ignores fork count"
+[ "$p4" -gt 2048 ]   && ok "a 4-fork slot is priced above the old flat 2048MB" || bad "4-fork slot still priced at or below the stale constant ($p4)"
+[ "$pdef" = "$p8" ]  && ok "unset VITEST_MAX_FORKS prices the config default of 8" || bad "unset != 8-fork price"
+[ "$povr" = "2048" ] && ok "explicit GOVERN_GB_PER_CYCLE still wins (operator override)" || bad "override ignored"
+if grep -q '"GOVERN_GB_PER_CYCLE"' "$ROOT/.claude/settings.json" 2>/dev/null; then
+  bad "settings.json still pins GOVERN_GB_PER_CYCLE — the derivation is dead code in every Claude Code session"
+else
+  ok "settings.json no longer pins GOVERN_GB_PER_CYCLE"
+fi
+
+hdr "6. SELF-RED — gut the probe and the checks above MUST go red"
+# A checker that stays green against a gutted probe proves nothing
+# (govern-claims-check.sh stubs _gv_alive for exactly this reason). Here we
+# put the OLD arithmetic back behind the new name and re-run section 1's
+# assertions: they have to fail.
+_saved_headroom=$(declare -f gate_headroom)
+_saved_pressure=$(declare -f gate_pressure)
+gate_headroom() { _old_gate_headroom; }
+gate_pressure() { _old_gate_pressure; }
+red=0
+for st in thrash-now thrash-A; do
+  fixture "$st"
+  h=$(gate_headroom)
+  [ "$h" -eq 1 ] || red=$((red+1))
+  gate_pressure && red=$((red+1))
+done
+if [ "$red" -ge 4 ]; then
+  ok "with the old arithmetic restored, all 4 thrash assertions fail ($red/4) — the checks have power"
+else
+  bad "gutted probe still satisfied $(( 4 - red ))/4 thrash assertions — this checker proves nothing"
+fi
+eval "$_saved_headroom"; eval "$_saved_pressure"
+
+hdr "7. LOAD-GUARD's MEMORY ARM — the one site that actually BLOCKS"
+# load-guard-check.sh exercises the regex classifier (which commands count as
+# heavy), never the memory state. This drives the real hook against the REAL
+# box with only the memory threshold moving, so the arm is seen firing AND
+# staying silent — a guard only ever seen to fire is an unproven guard. The load
+# and running-gate arms are pinned out of the way so nothing else can explain
+# the verdict.
+_lg_run() {  # _lg_run <GUARD_MIN_FREE_PCT> -> prints "deny" or "allow"
+  local out
+  out=$(CLAUDE_PROJECT_DIR="$ROOT" GUARD_MIN_FREE_PCT="$1" \
+        GUARD_LOAD_FACTOR=100000 GUARD_MAX_RUNNING=100000 \
+        bash "$ROOT/.claude/hooks/load-guard.sh" \
+        '{"tool_name":"Bash","tool_input":{"command":"bunx vitest run"}}' 2>/dev/null)
+  case "$out" in *'"deny"'*) echo deny ;; *) echo allow ;; esac
+}
+_lg_hi=$(_lg_run 101)   # threshold above any possible reading -> must deny
+_lg_lo=$(_lg_run 0)     # threshold below any possible reading -> must allow
+echo "  GUARD_MIN_FREE_PCT=101 -> $_lg_hi   ·   GUARD_MIN_FREE_PCT=0 -> $_lg_lo"
+[ "$_lg_hi" = "deny" ]  && ok "memory arm FIRES (hook emits a deny decision, does not crash open)" \
+                        || bad "memory arm did not fire — the blocking hook failed OPEN"
+[ "$_lg_lo" = "allow" ] && ok "memory arm stays silent on a satisfied threshold" \
+                        || bad "memory arm fires unconditionally — it is not reading memory"
+# And it must survive a probe that cannot be read at all: point the hook at a
+# project dir with no govern.sh. FREE falls back to 100, so the arm goes quiet
+# rather than taking the hook down with it.
+_lg_nolib=$(CLAUDE_PROJECT_DIR="$GOVERN_DIR" GUARD_MIN_FREE_PCT=101 \
+            GUARD_LOAD_FACTOR=100000 GUARD_MAX_RUNNING=100000 \
+            bash "$ROOT/.claude/hooks/load-guard.sh" \
+            '{"tool_name":"Bash","tool_input":{"command":"bunx vitest run"}}' 2>/dev/null; echo "rc=$?")
+case "$_lg_nolib" in
+  *rc=0*) ok "missing govern.sh -> hook still exits 0 (FREE=100, arm silent, nothing crashes)" ;;
+  *)      bad "missing govern.sh -> hook exited non-zero: $_lg_nolib" ;;
+esac
+
+hdr "RESULT"
+echo "  $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] || { echo "  GOVERN-MEM-CHECK: RED"; exit 1; }
+echo "  GOVERN-MEM-CHECK: GREEN"

package/scripts/governor-doors-check.sh

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# governor-doors-check.sh — the DOORS half of the governor guard.
+#
+#   bash .claude/scripts/governor-doors-check.sh          # audit + reentrancy
+#   bash .claude/scripts/governor-doors-check.sh --list    # every heavy script
+#   bash .claude/scripts/governor-doors-check.sh --self-test
+#
+# hook:governor-escape guards what an executor TYPES. This guards what the tree
+# OFFERS. They are different holes and only the second one explains the real
+# failure: `cd channels && bun run test` is an ungoverned 135-file two-runner
+# suite, and nothing about that command string looks like an escape. The hole
+# was the package script, not the command.
+#
+# Enumerated from `git ls-files` at run time, never from a hardcoded package
+# list -- the rot test-lanes.sh explicitly avoided. A NEW package, or a new
+# heavy script in an existing one, is therefore a failure the day it lands
+# rather than the day someone remembers to look.
+#
+# WHAT COUNTS AS A DOOR: a package.json script that reaches a runner pool --
+# vitest / bun test / playwright / astro check -- directly, or one hop through
+# `bash <script>.sh`. `channels`' test is the one-hop case and the reason the
+# hop is followed: its own file, not its package.json, holds the two runners.
+#
+# WHAT IS DELIBERATELY NOT A DOOR is in SKIP below, each with its reason. That
+# list is the argument, not an allowlist of convenience.
+#
+# A LOCK IS NOT A SLOT. Until 2026-09-07 the typecheck skip below read "tsc
+# already has its own lock via tsc-cached.sh", and that reasoning is wrong in a
+# way that cost the machine: gate_lock is keyed by FOLDER and dedupes identical
+# work, while a SLOT caps concurrent heavy work machine-wide. N worktrees are N
+# folders, so N locks are all uncontended while N typecheckers run. Measured that
+# day: three 2.5GB tsc processes at once, load 171, localhost at 8.4s a page, and
+# THIS CHECKER REPORTING "0 open". The "2-second typecheck" half was wrong too --
+# the measured runs were 2.5GB and 7+ minutes. The compute sites now take a slot
+# (see the `compute sites` section below, which is what would have caught it).
+# SHIPS (needs-env). In a generated factory clone this enumerates THAT repo
+# package.json files, while every line in the skip list names a monorepo path
+# that can never match there -- so it may report open doors it has no opinion
+# about. That is loud rather than wrong: the doors it names really are
+# ungoverned in that tree. Read the skip list as this repo argument, not as a
+# universal one.
+set -uo pipefail
+# GOV_DOORS_ROOT lets --self-test point the REAL audit at a sandbox tree.
+# Without it the red proof has to duplicate the classifier, and a duplicated
+# classifier is the drift this file exists to avoid.
+ROOT="${GOV_DOORS_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+cd "$ROOT" || exit 1
+
+HEAVY_RE='vitest|tsc[[:space:]]+--noEmit|astro[[:space:]]+check|playwright[[:space:]]+test|(^|[^a-zA-Z0-9_-])bun[[:space:]]+test([^a-zA-Z0-9_:-]|$)'
+
+# ── the reasoned skips ──────────────────────────────────────────────────────
+# <pkg-relpath>::<script>   why
+skips() {
+  cat <<'SKIP'
+*::typecheck                routes through tsc-cached.sh, which since 2026-09-07 takes a real SLOT around its compute (gate-run.sh), not merely its dedupe lock -- enforced by the `compute sites` section, not asserted here
+*::test:watch               a watch never exits; a wall-clock bound would kill it
+*::test:raw                 an escape hatch by definition -- ungoverned is the whole point
+*::verify:raw               an escape hatch by definition
+*::test:coverage            watch-mode vitest (no `run`); a bound would kill it
+one.ie/web::test:e2e:pw     opt-in e2e needing a live server; a 1800s bound could kill a legitimate long run
+one.ie/web::test:e2e:pw:ui  interactive -- a bound would kill a human's session
+one.ie/web::test:e2e:pw:debug interactive -- a bound would kill a human's session
+backup::test                2 test files under `bun test`, no fork pool -- cannot be the memory driver
+packages/evals::test        1 test file -- cannot be the memory driver
+packages/plugin-pages::test 1 test file -- cannot be the memory driver
+packages/plugin-pages::build tsc --noEmit wearing a build's name; same reason as typecheck
+pay/packages/one-protocol::test watch-mode vitest (no `run`) AND 0 test files -- see FINDINGS
+pay/packages/sdk::test      0 test files
+oo-brain::typecheck         not a deployed service
+template/site::typecheck    Astro 7 template, not a deployed service
+template-release::test      a release template, not a live package
+template-release::verify    a TEMPLATE: it is copied out to users WITHOUT .claude/, so wrapping it would bake in a gate-run.sh path that does not exist downstream and break the template itself
+SKIP
+}
+
+is_skipped() { # is_skipped <pkgdir> <script>
+  local pkg="$1" name="$2" k v
+  while read -r k v; do
+    [ -z "$k" ] && continue
+    case "$k" in
+      "*::$name")      return 0 ;;
+      "$pkg::$name")   return 0 ;;
+    esac
+  done < <(skips)
+  return 1
+}
+
+# ── enumerate ───────────────────────────────────────────────────────────────
+# Emits: <state> <pkgdir> <script> <command>   state = GOVERNED|OPEN|SKIP
+# Tracked files in a repo; a plain walk in a sandbox. Never node_modules.
+_list_package_jsons() {
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git ls-files '*package.json' | grep -v node_modules
+  else
+    find . -name package.json -not -path '*/node_modules/*' | sed 's|^\./||'
+  fi
+}
+
+enumerate() {
+  local pj
+  while IFS= read -r pj; do
+    [ -f "$pj" ] || continue
+    node -e '
+      const fs=require("fs"), path=require("path");
+      const pj=process.argv[1], dir=path.dirname(pj);
+      let j; try{ j=JSON.parse(fs.readFileSync(pj,"utf8")); }catch(e){ process.exit(0); }
+      const heavy=/vitest|tsc\s+--noEmit|astro\s+check|playwright\s+test|(^|[^\w-])bun\s+test([^\w:-]|$)/;
+      const scripts=j.scripts||{};
+      for(const [k,v] of Object.entries(scripts)){
+        let reaches=heavy.test(v), via="", hopGoverned=false;
+        // ONE HOP: `bash scripts/test.sh` hides its runners in its own file.
+        // Two traps, both hit on the FIRST run of this checker:
+        //  - install-hooks.sh only NAMES tsc, in a comment and an echo. A bare
+        //    mention is not an invocation, so the hop is position-anchored the
+        //    same way hook:governor-escape is. It is the same scar
+        //    this repo already carries under "a hook greps the whole
+        //    command"; reproducing it here made the checker cry wolf
+        //    on six innocent scripts.
+        //  - verify-fast.sh IS governed: it routes everything through
+        //    gate-run.sh internally. Governance can live in the HOPPED file,
+        //    so it has to be read there too, not only in package.json.
+        if(!reaches){
+          // Take EVERY `bash <x>.sh` in the value and skip gate-run.sh itself:
+          // once a one-hop script is wrapped, the first .sh in the string is the
+          // wrapper, and matching only that made channels and the three demos
+          // vanish from this audit the moment they were fixed. A guard that goes
+          // blind on the thing it just repaired cannot detect a later regression.
+          const all=[...v.matchAll(/bash\s+([^\s;&|]+\.sh)/g)].map(function(x){return x[1];});
+          const wrapped=all.some(function(x){return /gate-run\.sh$/.test(x);});
+          const m=all.filter(function(x){return !/gate-run\.sh$/.test(x);}).map(function(x){return [null,x];})[0];
+          if(m){
+            const hp=path.join(dir,m[1]);
+            try{
+              // Comments are prose, never invocations. install-hooks.sh
+              // line 2 reads "(astro check + tsc)" -- the bare paren made
+              // it look like a command position. Strip comments first.
+              const body=fs.readFileSync(hp,"utf8")
+                .split("\n").filter(function(l){return !/^\s*#/.test(l);}).join("\n");
+              const invoked=new RegExp(
+                "(^|[;&|(]|&&|\\|\\|)[ \\t]*([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]+)*"+
+                "((bunx|npx|bun|npm|xargs)[ \\t]+)*"+
+                "(vitest|tsc[ \\t]+--noEmit|astro[ \\t]+check|playwright[ \\t]+test|bun[ \\t]+test)","m");
+              if(invoked.test(body)){
+                reaches=true; via=" [via "+m[1]+"]";
+                // governed either by the wrapper in package.json, or because the
+                // hopped file routes through gate-run.sh internally (verify-fast).
+                if(wrapped || /gate-run\.sh/.test(body)) hopGoverned=true;
+              }
+            }catch(e){}
+          }
+        }
+        if(!reaches) continue;
+        const governed=/gate-run\.sh/.test(v) || hopGoverned;
+        console.log((governed?"GOVERNED":"OPEN")+"\t"+dir+"\t"+k+"\t"+v+via);
+      }
+    ' "$pj"
+  done < <(_list_package_jsons)
+}
+
+bad=0
+ok()   { printf '  ok    %s\n' "$*"; }
+nope() { printf '  FAIL  %s\n' "$*"; bad=$((bad + 1)); }
+
+audit() {
+  echo "== doors — every heavy package script is governed, or skipped for a stated reason"
+  local state pkg name cmd n_gov=0 n_skip=0
+  while IFS=$'\t' read -r state pkg name cmd; do
+    [ -z "${state:-}" ] && continue
+    if [ "$state" = "GOVERNED" ]; then n_gov=$((n_gov+1)); continue; fi
+    if is_skipped "$pkg" "$name"; then n_skip=$((n_skip+1)); continue; fi
+    nope "UNGOVERNED heavy script: (cd $pkg && bun run $name)  ->  $cmd"
+    printf '        fix: wrap it — bash <rel>/.claude/scripts/gate-run.sh %s -- %s\n' "$name" "$cmd"
+  done < <(enumerate)
+  [ "$bad" -eq 0 ] && ok "$n_gov governed, $n_skip skipped with a reason, 0 open"
+}
+
+# ── the wrapped paths must actually resolve ────────────────────────────────
+# Every wrap names gate-run.sh RELATIVELY, resolved from the package dir that
+# `bun run` cd's into. A wrong `../` count is the one way wrapping can break a
+# script, and it would surface only when somebody ran it -- months later, as a
+# "test command is broken" that nobody connects to this change. Derived from the
+# enumeration, never from a list, so a package wrapped tomorrow is checked too.
+paths() {
+  echo "== wrapped paths — every relative gate-run.sh resolves from its package dir"
+  local state pkg name cmd rel n=0
+  while IFS=$'\t' read -r state pkg name cmd; do
+    [ "${state:-}" = "GOVERNED" ] || continue
+    rel=$(printf '%s' "$cmd" | sed -nE 's|.*bash ([^ ]*gate-run\.sh) .*|\1|p' | head -1)
+    [ -n "$rel" ] || continue
+    case "$rel" in /*) [ -f "$rel" ] && { n=$((n+1)); continue; } ;; esac
+    if [ -f "$pkg/$rel" ]; then
+      n=$((n+1))
+    else
+      nope "$pkg :: $name names $rel, which does NOT resolve from $pkg"
+    fi
+  done < <(enumerate)
+  [ "$bad" -eq 0 ] && ok "$n wrapped scripts, every relative path resolves"
+}
+
+# ── re-entrancy: the one way wrapping could make things WORSE ───────────────
+# gate-run is re-entrant by design (GOVERN_IN_GATE), so a wrapped `test` called
+# from a wrapped `verify` must inherit the outer slot rather than queue behind
+# it. With the cap at 1 a non-re-entrant nest DEADLOCKS -- which is exactly what
+# the red half below forces, so this check is not taking re-entrancy on trust.
+reentrancy() {
+  echo "== re-entrancy — a wrapped gate nested in a wrapped gate must not deadlock"
+  local sandbox G o e
+  sandbox="$(mktemp -d)"
+  G="$ROOT/.claude/scripts/gate-run.sh"
+  o="$sandbox/out"; e="$sandbox/err"
+  local T=30   # bound the whole experiment; the commands under test are echoes
+
+  # NEVER capture a gate with `out=$(gate-run ... 2>&1)`. run_bounded
+  # (govern.sh:130-134) forks a watchdog holding `sleep $GOVERN_GATE_TIMEOUT`,
+  # deliberately detached from STDOUT on 2026-09-01 so a command substitution
+  # would not block on it -- but `2>&1` reattaches it to the captured pipe, and
+  # the substitution then hangs for the FULL timeout after the command has
+  # already finished. Measured here: 1800s of nothing, killed at 144.
+  # Redirect to files and read the files.
+
+  # GREEN: the nested gate inherits the outer slot even with the cap at 1.
+  GOVERN_DIR="$sandbox" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=8 GOVERN_GATE_TIMEOUT=$T \
+    bash "$G" outer -- bash -c \
+    "GOVERN_DIR='$sandbox' GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=8 GOVERN_GATE_TIMEOUT=$T bash '$G' inner -- echo NESTED_OK" \
+    >"$o" 2>"$e"
+  if grep -q NESTED_OK "$o"; then
+    ok "nested gate inherited the outer slot at cap 1 (no deadlock)"
+  else
+    nope "nested gate did NOT complete at cap 1 — deadlock. out=[$(cat "$o")] err=[$(cat "$e")]"
+  fi
+
+  # RED: clear GOVERN_IN_GATE inside, so the nest asks for a SECOND slot at cap
+  # 1. It must starve -- proving the green above was re-entrancy doing the work
+  # and not merely a cap that never bound.
+  : > "$o"; : > "$e"
+  GOVERN_DIR="$sandbox" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=4 GOVERN_GATE_TIMEOUT=$T \
+    bash "$G" outer2 -- bash -c \
+    "unset GOVERN_IN_GATE; GOVERN_DIR='$sandbox' GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=4 GOVERN_GATE_TIMEOUT=$T bash '$G' inner2 -- echo SHOULD_NOT_RUN" \
+    >"$o" 2>"$e"
+  if grep -q SHOULD_NOT_RUN "$o"; then
+    nope "a second slot was granted at cap 1 — the cap does not bind, so the green proves nothing"
+  elif grep -q "no slot after" "$e"; then
+    ok "without re-entrancy the same nest starves at cap 1 (the cap really binds)"
+  else
+    nope "unexpected red-half output. out=[$(cat "$o")] err=[$(cat "$e")]"
+  fi
+  # RED PROOF for `compute sites`: a script that spawns a heavy compute with no
+  # gate-run.sh must turn compute_sites red. This is the exact shape tsc-cached.sh
+  # had before 2026-09-07 -- a gate_lock, and a bare bunx tsc inside it.
+  local probe_dir probe
+  probe_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  # NOT a dotfile: `for f in "$d"/*.sh` does not glob dotfiles, so a probe named
+  # .zz-*.sh is invisible to the very check it is supposed to drive red -- the
+  # proof would pass by never being seen. Named plainly, and rm'd below.
+  probe="$probe_dir/zz-compute-probe.sh"
+  cat > "$probe" <<'PROBE'
+#!/usr/bin/env bash
+# a lock, and a heavy compute with no slot -- the 2026-09-07 defect, in miniature
+gate_lock "probe" 10 && bunx tsc --noEmit
+PROBE
+  local b0=$bad
+  compute_sites >/dev/null 2>&1
+  if [ "$bad" -gt "$b0" ]; then
+    ok "a lock-without-slot compute site turns the audit RED"
+    bad=$b0
+  else
+    nope "compute_sites stayed green against a bare 'bunx tsc --noEmit' with no gate-run"
+  fi
+  rm -f "$probe"
+
+  rm -rf "$sandbox"
+}
+
+# ── compute sites — a gate_lock is not a slot ───────────────────────────────
+#
+# The `doors` section above audits PACKAGE SCRIPTS. It cannot see the defect
+# that actually cost the machine on 2026-09-07, because that one lived one layer
+# down: tsc-cached.sh held a per-folder gate_lock and spawned `bunx tsc` with no
+# slot at all. Every door was green, the skip list had a stated reason, and three
+# 2.5GB typecheckers ran concurrently while the governor reported 1 of 2 slots.
+#
+# The rule this enforces: ANY script here that spawns a heavy compute must also
+# reference gate-run.sh. Not "takes a lock" -- a lock dedupes identical work, a
+# slot bounds the machine, and only one of those is a concurrency cap.
+compute_sites() {
+  echo "== compute sites — a heavy compute behind a lock still needs a SLOT"
+  local d f n_ok=0 hits
+  d="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for f in "$d"/*.sh; do
+    case "$(basename "$f")" in
+      gate-run.sh|governor-doors-check.sh|governor-escape-check.sh|machine-check.sh) continue ;;
+      # FIXTURES — these NAME a heavy command as test data and spawn nothing:
+      #   load-guard-check.sh   passes command STRINGS to the hook  ( check 1 "bunx ..." )
+      #   govern-mem-check.sh   embeds them in JSON tool_input payloads
+      #   deploy-gate-check.sh  greps deploy.sh for the command as a PATTERN
+      # Each was verified by reading the matching lines, not assumed.
+      load-guard-check.sh|govern-mem-check.sh|deploy-gate-check.sh) continue ;;
+    esac
+    # PRESENCE, not command-position. The first version of this asked "is the
+    # compute in command position", blanking quoted regions -- and it could not
+    # see the very defect it was written for: tsc-cached.sh spawned its tsc from
+    # inside a quoted `bash -c "... ${TSC_CACHE_CMD:-bunx tsc --noEmit} ..."`.
+    # Reverting tsc-cached.sh to its pre-fix state left that check GREEN, which
+    # is the only test of a checker that matters.
+    #
+    # So the rule is blunt on purpose: if a heavy token appears outside a comment,
+    # this file must reference gate-run.sh somewhere. Scripts that only NAME a
+    # command as a test fixture are handled by FIXTURES below, by name and with a
+    # reason -- the same "the skip list is the argument" doctrine as the doors.
+    hits=$(grep -nE '(bunx|npx|bun x) +(tsc +--noEmit|vitest +run)' "$f" 2>/dev/null \
+           | grep -vE '^[0-9]+:[[:space:]]*#' || true)
+    [ -n "$hits" ] || continue
+    if grep -q 'gate-run\.sh' "$f"; then
+      n_ok=$((n_ok+1))
+    else
+      nope "$(basename "$f") spawns a heavy compute with no gate-run.sh anywhere:
+$(printf '%s' "$hits" | head -3 | sed 's/^/          /')"
+    fi
+  done
+  [ "$bad" -eq 0 ] && ok "$n_ok script(s) spawn a heavy compute, every one routes through gate-run.sh"
+}
+
+# ── red proof ───────────────────────────────────────────────────────────────
+self_test() {
+  echo "== self-test — plant an open door, the REAL audit must go RED"
+  local sandbox out rc
+  sandbox="$(mktemp -d)"
+  mkdir -p "$sandbox/planted"
+  cat > "$sandbox/planted/package.json" <<'PKG'
+{ "name": "planted", "scripts": { "test": "vitest run" } }
+PKG
+  # Drive audit() itself, in a sandbox tree, through the same enumerate().
+  out=$(GOV_DOORS_ROOT="$sandbox" GOV_DOORS_INNER=1 bash "${BASH_SOURCE[0]}" 2>&1); rc=$?
+  if [ $rc -ne 0 ] && printf '%s' "$out" | grep -q 'UNGOVERNED heavy script'; then
+    ok "a planted ungoverned test makes the real audit go RED"
+  else
+    nope "planted open door did not turn the audit red (rc=$rc): $out"
+  fi
+
+  # And the inverse: wrapping the SAME script must clear the SAME audit.
+  cat > "$sandbox/planted/package.json" <<'PKG'
+{ "name": "planted", "scripts": { "test": "bash ../.claude/scripts/gate-run.sh t -- vitest run" } }
+PKG
+  out=$(GOV_DOORS_ROOT="$sandbox" GOV_DOORS_INNER=1 bash "${BASH_SOURCE[0]}" 2>&1); rc=$?
+  if [ $rc -eq 0 ]; then
+    ok "wrapping the same script clears the same audit"
+  else
+    nope "wrapped script still reads open: $out"
+  fi
+  rm -rf "$sandbox"
+}
+
+case "${1:-}" in
+  --list)      enumerate | sort | column -t -s$'\t' 2>/dev/null || enumerate | sort; exit 0 ;;
+  --self-test) self_test ;;
+  *)           if [ -n "${GOV_DOORS_INNER:-}" ]; then audit
+               else audit; echo; paths; echo; compute_sites; echo; reentrancy; echo; self_test; fi ;;
+esac
+
+echo
+if [ "$bad" -eq 0 ]; then echo "RESULT: PASS — no ungoverned heavy door, and nesting does not deadlock"
+else echo "RESULT: RED — $bad failure(s)"; exit 1; fi