@oneie/claude 0.8.0 → 0.10.0

package/scripts/gc-content-check.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# gc-content-check.sh — the red proof for lib/gc-finished.sh.
+#
+# manifest: needs-env
+#   (portable by behaviour — its own sandbox — but it must spell one.ie/web/.astro
+#    to exercise GC_EPHEMERAL. See factory-repo.sh's manifest block comment.)
+#
+# Builds a sandbox repo carrying the branch shapes the sweep meets, drives the
+# REAL predicate (sourced, never re-implemented), and then proves the OLD
+# commit-count predicate gets the important one wrong. A checker that only shows
+# the new code passing would not tell you the change was worth making.
+#
+# NOT reproduced here: `git cherry`'s blind spot on a merge commit. That was
+# measured on this repo (merge/trunk-reconcile, 2026-09-07: cherry reported
+# 0-new for a branch holding 24 files and 3416 lines dev had never seen) and the
+# reasoning lives in lib/gc-finished.sh. Faking a multi-merge-base history to
+# re-stage it would be asserting a claim this sandbox does not actually show —
+# the fourth case below covers the same risk directly: a merge carrying unique
+# content must read NOT finished.
+#
+#   bash .claude/scripts/gc-content-check.sh    # exits non-zero on failure
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$HERE/lib/gc-finished.sh"
+
+SANDBOX="$(mktemp -d)"; trap 'rm -rf "$SANDBOX"' EXIT
+fails=0
+EXPECT_RED=0   # set while driving the neutered predicate, so an INTENDED failure
+               # does not print the word FAIL and read as a broken checker.
+ok()  { printf '  ok    %s\n' "$1"; }
+bad() {
+  if [ "$EXPECT_RED" = 1 ]; then printf '  red   %s — as intended\n' "$1"
+  else printf '  FAIL  %s\n' "$1"; fi
+  fails=$((fails+1))
+}
+want() { # <expected 0|1> <branch> <what>
+  gc_finished trunk "$2"; local got=$?
+  [ "$got" -eq "$1" ] && ok "$3" || bad "$3 (wanted finished=$1, got $got)"
+}
+
+cd "$SANDBOX"
+git init -q -b trunk .
+git config user.email t@e.st; git config user.name t
+git config commit.gpgsign false
+echo base > a.txt; git add a.txt; git commit -qm base
+echo one  > c.txt; git add c.txt; git commit -qm second
+B1="$(git rev-parse HEAD)"
+
+# 1 — REBASED DUPLICATE: the branch's patch reaches trunk under a DIFFERENT sha.
+#     This is the case the commit count gets wrong, and the reason for this file.
+git checkout -q -b dup "$B1"
+echo fixed > a.txt; git commit -qam "fix a"
+git checkout -q trunk
+git cherry-pick dup >/dev/null 2>&1 || { bad "sandbox: cherry-pick failed"; exit 1; }
+# Re-message it. A cherry-pick onto the same parent, in the same second, with the
+# same author and message, produces a byte-identical commit OBJECT — trunk then
+# fast-forwards onto the branch and there is no divergence left to detect. That
+# is a sandbox artifact, not the real world, where a re-landed patch always
+# arrives with a different sha. The amend forces the sha apart while leaving the
+# patch identical, which is precisely the case under test.
+git commit -q --amend -m "fix a (relanded under a different sha)"
+
+# 2 — ORDINARY UNLANDED BRANCH.
+git checkout -q -b ahead trunk
+echo new > b.txt; git add b.txt; git commit -qm "adds b"
+
+# 3 — FULLY CONTAINED: tip is an ancestor of trunk.
+git checkout -q -b behind "$B1"
+
+# 4 — MERGE COMMIT CARRYING UNIQUE CONTENT. The shape that makes a
+#     patch-counting test (git cherry) unsafe on its own.
+git checkout -q -b side "$B1"
+echo unique > only-here.txt; git add only-here.txt; git commit -qm "unique file"
+git checkout -q -b mergey trunk
+git merge --no-edit side >/dev/null 2>&1 || { bad "sandbox: merge failed"; exit 1; }
+
+echo "== the predicate the sweep runs"
+want 0 dup    "a rebased duplicate reads FINISHED — its content is already on the platform"
+want 1 ahead  "an ordinary unlanded branch reads NOT finished"
+want 0 behind "a branch fully contained in the base reads FINISHED"
+want 1 mergey "a merge carrying a file the base lacks reads NOT finished"
+
+echo "== what the OLD commit-count predicate would have said"
+old_finished() { [ "$(git rev-list --count "trunk..$1" 2>/dev/null || echo 1)" -eq 0 ]; }
+if old_finished dup
+then bad "the count predicate should MISS the duplicate — this proof is broken"
+else ok  "the count predicate hoards the duplicate for ever — the ~120MB this fixes"; fi
+if old_finished ahead
+then bad "the count predicate wrongly sweeps an unlanded branch"
+else ok  "the count predicate keeps an unlanded branch (both agree here)"; fi
+
+echo "== the clean-worktree path survives set -e"
+# The sweep runs under `set -euo pipefail`, and `grep -v` exits 1 when it filters
+# EVERYTHING out — the clean-worktree case. Inline, that killed the sweep at the
+# first worktree it was meant to remove: four keep lines, exit 1, no summary, and
+# invisible behind a `| cat`. Drive the real function in a real subshell under
+# the real flags, because that is the only way this comes back red.
+git checkout -q trunk
+if out="$(bash -c '
+      set -euo pipefail
+      . "'"$HERE"'/lib/gc-finished.sh"
+      d="$(gc_real_dirt "'"$SANDBOX"'")"
+      [ -z "$d" ] && echo CLEAN-AND-ALIVE
+    ' 2>&1)" && [ "$out" = "CLEAN-AND-ALIVE" ]; then
+  ok "a clean worktree reports no dirt AND the shell survives it"
+else
+  bad "the clean-tree path died under set -e (got: ${out:-<nothing>})"
+fi
+# And it still SEES real work, or the fix would be a mute button.
+echo scratch > "$SANDBOX/uncommitted.txt"
+if [ -n "$(gc_real_dirt "$SANDBOX")" ]
+then ok "uncommitted work is still reported — the guard did not silence it"
+else bad "gc_real_dirt missed an uncommitted file"; fi
+rm -f "$SANDBOX/uncommitted.txt"
+# Ephemera alone must NOT read as work, or nothing is ever swept.
+# The tracked file is required, not decoration: git COLLAPSES a wholly-untracked
+# directory to its top level, so an unrepresentative sandbox reports `?? one.ie/`
+# and no path pattern can match. A real worktree has one.ie/web/ tracked, so git
+# descends and reports `?? one.ie/web/.astro` — which is what the filter is
+# written against. Committing one file reproduces that.
+mkdir -p "$SANDBOX/one.ie/web"; echo keep > "$SANDBOX/one.ie/web/keep.txt"
+git add one.ie/web/keep.txt; git commit -qm "tracked file under one.ie/web"
+mkdir -p "$SANDBOX/one.ie/web/.astro"; echo x > "$SANDBOX/one.ie/web/.astro/gen.d.ts"
+if [ -z "$(gc_real_dirt "$SANDBOX")" ]
+then ok "build output alone does not count as work"
+else bad "ephemeral dirt was reported as work — nothing would ever be swept"; fi
+rm -rf "$SANDBOX/one.ie/web/.astro"
+
+echo "== red proof: neuter the predicate and the checks must fail"
+gc_finished() { return 0; }   # claim every branch is finished
+before=$fails; EXPECT_RED=1
+want 1 ahead  "(neutered) an unlanded branch must NOT read finished"
+want 1 mergey "(neutered) a unique-content merge must NOT read finished"
+if [ "$fails" -eq $((before+2)) ]; then
+  fails=$before; EXPECT_RED=0; ok "both checks bite when the predicate is gutted"
+else
+  fails=$((before+1)); EXPECT_RED=0; printf '  FAIL  a gutted predicate still passed — this checker proves nothing\n'
+fi
+
+echo
+[ "$fails" -eq 0 ] && { echo "gc-content-check: PASS"; exit 0; }
+echo "gc-content-check: FAIL ($fails)"; exit 1

package/scripts/gh-traffic-capture.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# gh-traffic-capture.sh — keep GitHub traffic before GitHub throws it away.
+#
+#   bash .claude/scripts/gh-traffic-capture.sh                 # capture, default repos
+#   bash .claude/scripts/gh-traffic-capture.sh --repo o/r       # one repo
+#   bash .claude/scripts/gh-traffic-capture.sh --report         # read the ledger
+#   bash .claude/scripts/gh-traffic-capture.sh --install-cron   # daily at 07:15
+#   bash .claude/scripts/gh-traffic-capture.sh --self-test
+#
+# manifest: needs-env — (gh CLI + network; no repo state beyond its own ledger)
+#
+# WHY: /traffic/clones and /traffic/views return THE LAST 14 DAYS AND NOTHING
+# ELSE. There is no backfill, no paging, no "all time" — a day that scrolls out
+# of that window is gone from the API permanently. Measured 2026-09-14 on
+# one-ie/one: the repo has existed since 2024-11-12 and the API could account
+# for 14 days of it. Every day this does not run, a day is lost for good.
+#
+# THE MERGE IS THE WHOLE JOB, and it has one rule that is easy to get wrong:
+# TODAY'S ROW IS PARTIAL. Capture at 07:15 and the day is a few hours old; the
+# same date re-fetched tomorrow is larger and correct. So a merge must take the
+# GREATER of stored and incoming per date — never "skip if the date exists"
+# (freezes every day at its morning value) and never "last write wins" (a later
+# call that drops a day to 0 would erase a real number). max() is the only
+# rule that is right on the first write, the same-day rewrite, and the replay.
+#
+# Idempotent by construction: re-running an hour later, or ten times, converges.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DATA="${GH_TRAFFIC_DIR:-$ROOT/.claude/data/gh-traffic}"
+REPOS=(); MODE=capture
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) REPOS+=("$2"); shift ;;
+    --report) MODE=report ;;
+    --install-cron) MODE=cron ;;
+    --self-test) MODE=selftest ;;
+    -h|--help) sed -n '2,9p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "gh-traffic-capture.sh: unknown flag '$1'" >&2; exit 2 ;;
+  esac
+  shift
+done
+# ENUMERATE THE ORG, never a hardcoded list. The first version of this script
+# listed the seven subtree-mirror repos from the root CLAUDE.md table — and so
+# it silently missed `ontology` (53 clones) and `astro-shadcn` (18 clones, 17
+# uniques, 26 views), the org's second- and third-busiest repos. A capture that
+# is blind to a repo loses that repo's history permanently, which is the one
+# failure this script exists to prevent. A new repo joins the ledger by
+# existing, not by someone remembering to add it here.
+# GH_TRAFFIC_ORG overrides; --repo still pins an explicit set.
+if (( ! ${#REPOS[@]} )); then
+  while IFS= read -r r; do [[ -n "$r" ]] && REPOS+=("$r"); done < <(
+    gh api "orgs/${GH_TRAFFIC_ORG:-one-ie}/repos?per_page=100&type=public" --jq '.[].full_name' 2>/dev/null
+  )
+  (( ${#REPOS[@]} )) || { echo "gh-traffic-capture.sh: could not enumerate org repos" >&2; exit 1; }
+fi
+
+command -v jq >/dev/null || { echo "gh-traffic-capture.sh: needs jq" >&2; exit 2; }
+command -v gh >/dev/null || { echo "gh-traffic-capture.sh: needs the gh CLI" >&2; exit 2; }
+
+mkdir -p "$DATA"
+
+# merge_series <file> <key> <json-array of {timestamp,count,uniques}>
+# max() per date, per the rule above.
+merge_series() {
+  local f="$1" key="$2" incoming="$3" tmp
+  tmp="$(mktemp)"
+  [[ -s "$f" ]] || printf '{"repo":"","clones":{},"views":{},"captured":[]}' > "$f"
+  jq --arg k "$key" --argjson inc "$incoming" '
+    .[$k] = ( (.[$k] // {}) as $have
+      | reduce $inc[] as $d ($have;
+          ($d.timestamp[0:10]) as $day
+          | .[$day] = {
+              count:   ([ (.[$day].count   // 0), ($d.count   // 0) ] | max),
+              uniques: ([ (.[$day].uniques // 0), ($d.uniques // 0) ] | max)
+            }
+        ) )
+  ' "$f" > "$tmp" && mv "$tmp" "$f"
+}
+
+capture_one() {
+  # TWO statements, deliberately. `local repo="$1" f="$DATA/${repo//\//__}.json"`
+  # expands EVERY word before it performs ANY assignment, so ${repo} there is
+  # still unset: f became "$DATA/.json" and all seven repos shared one ledger.
+  # The tell was subtle — the merge is max(), so the first repo's 163 clones
+  # survived every later repo's zeros and each one reported 163.
+  local repo="$1"
+  local f="$DATA/${repo//\//__}.json"
+  local c v
+  c="$(gh api "repos/$repo/traffic/clones" --jq '.clones' 2>/dev/null)"
+  v="$(gh api "repos/$repo/traffic/views"  --jq '.views'  2>/dev/null)"
+  if [[ -z "$c" && -z "$v" ]]; then
+    echo "  ! $repo — no traffic data (needs push access on that repo)" >&2
+    return 1
+  fi
+  [[ -s "$f" ]] || printf '{"repo":"%s","clones":{},"views":{},"captured":[]}' "$repo" > "$f"
+  [[ -n "$c" && "$c" != "null" ]] && merge_series "$f" clones "$c"
+  [[ -n "$v" && "$v" != "null" ]] && merge_series "$f" views  "$v"
+  local tmp; tmp="$(mktemp)"
+  jq --arg r "$repo" --arg t "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+     '.repo=$r | .captured = ((.captured // []) + [$t] | .[-200:])' "$f" > "$tmp" && mv "$tmp" "$f"
+  local days tot
+  days="$(jq '(.clones|length)' "$f")"; tot="$(jq '[.clones[].count]|add // 0' "$f")"
+  printf '  ✓ %-22s %s day(s) kept · %s clones total\n' "$repo" "$days" "$tot"
+}
+
+case "$MODE" in
+  capture)
+    echo "── capturing GitHub traffic → $DATA"
+    rc=0; for r in "${REPOS[@]}"; do capture_one "$r" || rc=1; done
+    exit $rc ;;
+
+  report)
+    printf '\n  %-24s %8s %9s %8s %9s   %s\n' "REPO" "CLONES" "UNIQ" "VIEWS" "UNIQ" "DAYS KEPT"
+    printf '  %s\n' "$(printf '─%.0s' {1..76})"
+    for f in "$DATA"/*.json; do
+      [[ -e "$f" ]] || { echo "  (ledger empty — run a capture first)"; break; }
+      jq -r '"  \(.repo[0:24] + "                        "|.[0:24]) \([.clones[].count]|add // 0|tostring|(("        "+.)|.[-8:])) \([.clones[].uniques]|add // 0|tostring|(("         "+.)|.[-9:])) \([.views[].count]|add // 0|tostring|(("        "+.)|.[-8:])) \([.views[].uniques]|add // 0|tostring|(("         "+.)|.[-9:]))   \(.clones|length)"' "$f"
+    done
+    printf '\n  NOTE: totals are what THIS LEDGER has kept, not GitHub all-time —\n'
+    printf '  anything before the first capture was already unrecoverable.\n\n' ;;
+
+  cron)
+    line="15 7 * * * cd $ROOT && /bin/bash .claude/scripts/gh-traffic-capture.sh >> $DATA/cron.log 2>&1"
+    if crontab -l 2>/dev/null | grep -qF 'gh-traffic-capture.sh'; then
+      echo "  already installed:"; crontab -l 2>/dev/null | grep -F 'gh-traffic-capture.sh' | sed 's/^/    /'
+    else
+      ( crontab -l 2>/dev/null; echo "$line" ) | crontab - \
+        && echo "  ✓ installed — daily 07:15" && crontab -l | grep -F 'gh-traffic' | sed 's/^/    /'
+    fi
+    echo "  NOTE: cron only fires while this Mac is awake. A missed day is still"
+    echo "  recoverable for 14 days — that is the window, and the reason for daily." ;;
+
+  selftest)
+    # The merge is the only logic worth proving, and the property is max().
+    d="$(mktemp -d)"; f="$d/t.json"; fails=0
+    printf '{"repo":"x","clones":{},"views":{},"captured":[]}' > "$f"
+    merge_series "$f" clones '[{"timestamp":"2026-09-01T00:00:00Z","count":5,"uniques":2}]'
+    [[ "$(jq -r '.clones["2026-09-01"].count' "$f")" == "5" ]] || { echo "  FAIL: first write"; fails=1; }
+    # same day, larger (the partial-today case) -> must grow
+    merge_series "$f" clones '[{"timestamp":"2026-09-01T00:00:00Z","count":9,"uniques":4}]'
+    [[ "$(jq -r '.clones["2026-09-01"].count' "$f")" == "9" ]] || { echo "  FAIL: partial day did not grow"; fails=1; }
+    # same day, smaller (a late/rescoped answer) -> must NOT shrink
+    merge_series "$f" clones '[{"timestamp":"2026-09-01T00:00:00Z","count":1,"uniques":1}]'
+    [[ "$(jq -r '.clones["2026-09-01"].count' "$f")" == "9" ]] || { echo "  FAIL: a smaller number overwrote a larger one"; fails=1; }
+    # a day older than the 14d window must survive a capture that omits it
+    merge_series "$f" clones '[{"timestamp":"2026-09-02T00:00:00Z","count":3,"uniques":1}]'
+    [[ "$(jq -r '.clones|length' "$f")" == "2" ]] || { echo "  FAIL: an out-of-window day was dropped"; fails=1; }
+    rm -rf "$d"
+    (( fails )) && { echo "gh-traffic-capture.sh: self-test FAILED"; exit 1; }
+    echo "gh-traffic-capture.sh: self-test PASS (grows, never shrinks, never forgets)" ;;
+esac

package/scripts/govern-order-check.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# govern-order-check.sh — the governor's LOCK ORDER, proved by deadlocking it.
+#
+# manifest: needs-env
+#
+# THE DEFECT (measured 2026-09-13, three occurrences in ~35 minutes, each
+# stalling every session on the box for 8-28 minutes at 0% CPU — one of them a
+# production release gate):
+#
+#   tsc-cached.sh took the per-folder dedupe LOCK and then, still holding it,
+#   queued for a governor SLOT.                             LOCK -> SLOT
+#   Any caller already inside a gate has the opposite order: `bun run verify:fast`
+#   IS `gate-run.sh verify-fast -- verify-fast.sh`, so it holds a SLOT, and its
+#   child tsc-cached.sh then waits for the LOCK.            SLOT -> LOCK
+#
+#   A: gate-run(verify-fast) holds slot-1  ->  child tsc-cached waits for lock-tsc-one.ie_web
+#   B: tsc-cached holds lock-tsc-one.ie_web ->  its inner gate-run waits for a slot
+#
+# Two orders, one cycle. Neither owner is DEAD, so nothing reaps it:
+# `gate_lock`/`gate_slot` only reap an owner whose pid is gone (govern.ts
+# `reapLock`), and gate-reaper.sh is the same predicate. Measured owner pairs:
+# 22173/68920, then 15762/97557, then 87579.
+#
+# KILLING THE LOCK HOLDER DOES NOT FIX IT — observed twice. The lock is released
+# and immediately taken by the next waiter, which is itself inside a gate holding
+# a slot, and the cycle re-forms within seconds. Killing the SLOT holder is what
+# breaks it, because that is the resource nobody else can produce.
+#
+# THE FIX this proves: SLOT before LOCK, everywhere. A cache HIT still takes
+# neither.
+#
+# WHAT EACH HALF PROVES. The green half proves tsc-cached.sh is no longer an
+# inverted participant. It does NOT prove the cycle is impossible — a synthetic
+# LOCK -> SLOT holder still deadlocks a fixed tsc-cached, and that is exactly
+# what the red half plants, so this checker is never green for lack of power.
+# Both halves run in their own GOVERN_DIR: nothing here touches the machine's
+# real governor, so a real gate in another session is never delayed or killed.
+set -uo pipefail
+
+_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$_HERE/../.." && pwd)"
+GR="$_HERE/gate-run.sh"
+TSC="$_HERE/tsc-cached.sh"
+
+# A folder inside ROOT, because tsc_tree_fingerprint cd's to ROOT and resolves
+# the folder relatively. Never one.ie/web: that is a real 2.5GB typecheck.
+REL=".govern-order-probe"
+P="$ROOT/$REL"
+LOCKNAME="tsc-$(printf '%s' "$REL" | tr '/' '_')"
+
+# Waits are SHORT and bounded on purpose: a deadlocked pair must expire by
+# itself in under a minute, on a box where other sessions are running real
+# gates. OBSERVE is when the verdict is read — long enough for both roles to
+# have taken their ground, short enough to finish inside a Bash tool call.
+WAIT="${GOVERN_ORDER_WAIT:-20}"
+OBSERVE="${GOVERN_ORDER_OBSERVE:-10}"
+
+bad=0
+ok()   { echo "  ok: $*"; }
+nope() { echo "  FAIL: $*"; bad=$((bad + 1)); }
+
+probe_up() {
+  rm -rf "$P"; mkdir -p "$P/src"
+  printf '{ "compilerOptions": { "strict": true, "noEmit": true }, "include": ["src"] }\n' > "$P/tsconfig.json"
+  printf 'export const x: number = 1;\n' > "$P/src/a.ts"
+}
+probe_down() { rm -rf "$P"; }
+
+# _race <sandbox> <role-b-command...> — start the two roles in the two orders and
+# read the state at OBSERVE seconds.
+#
+# Role A is always the REAL shape a session runs: gate-run holds a slot, and its
+# child tsc-cached asks for the lock. The `sleep 3` is the whole determinism of
+# this repro — it lets role B take its ground first, so the interleaving is
+# fixed rather than raced.
+#
+# Echoes "done" (both roles exited) or "stalled <lock-owner> <slot-owner>".
+_race() {
+  local sb="$1"; shift
+  local aout="$sb/a.log" bout="$sb/b.log" pa pb t
+
+  ( GOVERN_DIR="$sb" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT="$WAIT" \
+    GOVERN_GATE_TIMEOUT=$((WAIT * 4)) TSC_CACHE_WAIT="$WAIT" TSC_CACHE_TIMEOUT="$WAIT" \
+    TSC_CACHE_CMD='echo no-errors-here' \
+    bash "$GR" role-a -- bash -c "sleep 3; bash '$TSC' '$REL'" ) >"$aout" 2>&1 &
+  pa=$!
+  sleep 2
+  ( GOVERN_DIR="$sb" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT="$WAIT" \
+    GOVERN_GATE_TIMEOUT=$((WAIT * 4)) TSC_CACHE_WAIT="$WAIT" TSC_CACHE_TIMEOUT="$WAIT" \
+    TSC_CACHE_CMD='echo no-errors-here' \
+    "$@" ) >"$bout" 2>&1 &
+  pb=$!
+
+  t=0
+  while [ "$t" -lt "$OBSERVE" ]; do
+    kill -0 "$pa" 2>/dev/null || kill -0 "$pb" 2>/dev/null || break
+    sleep 1; t=$((t + 1))
+  done
+
+  # The exit codes go to DISK, not to variables: _race is read through a command
+  # substitution, so anything it assigns dies with the subshell.
+  if ! kill -0 "$pa" 2>/dev/null && ! kill -0 "$pb" 2>/dev/null; then
+    wait "$pa"; echo $? > "$sb/rc.a"; wait "$pb"; echo $? > "$sb/rc.b"
+    echo "done"; return 0
+  fi
+  # Still alive at OBSERVE: name the two owners, then stop them. These are our
+  # own children in our own sandbox — never another session's gate.
+  local lo so
+  lo=$(cat "$sb/lock-$LOCKNAME/pid" 2>/dev/null | tr -d '[:space:]')
+  so=$(cat "$sb/lock-slot-1/pid" 2>/dev/null | tr -d '[:space:]')
+  kill -TERM "$pa" "$pb" 2>/dev/null
+  sleep 1
+  kill -KILL "$pa" "$pb" 2>/dev/null
+  wait "$pa" 2>/dev/null; wait "$pb" 2>/dev/null
+  echo 99 > "$sb/rc.a"; echo 99 > "$sb/rc.b"
+  echo "stalled lock=${lo:-none} slot=${so:-none}"
+}
+
+# ── 1. THE REAL PAIR — both roles are the shipped tsc-cached.sh ──────────────
+real_pair() {
+  echo "== the real pair — gate-run(slot)->tsc-cached(lock) vs bare tsc-cached"
+  local sb r ra rb
+  sb="$(mktemp -d)"; probe_up
+  r=$(_race "$sb" bash "$TSC" "$REL")
+  ra=$(cat "$sb/rc.a" 2>/dev/null); rb=$(cat "$sb/rc.b" 2>/dev/null)
+  case "$r" in
+    done)
+      if [ "${ra:-1}" = "0" ] && [ "${rb:-1}" = "0" ]; then
+        ok "both roles completed (rc 0/0) — tsc-cached takes the SLOT before the LOCK"
+      else
+        nope "both roles exited but not cleanly (a=${ra:-?} b=${rb:-?})
+$(sed 's/^/          A| /' "$sb/a.log"; sed 's/^/          B| /' "$sb/b.log")"
+      fi ;;
+    stalled*)
+      nope "DEADLOCK reproduced against this code — $r
+          neither owner is dead, so nothing reaps it. This is the 2026-09-13 stall.
+$(sed 's/^/          A| /' "$sb/a.log"; sed 's/^/          B| /' "$sb/b.log")" ;;
+  esac
+  probe_down; rm -rf "$sb"
+}
+
+# ── 2. RED PROOF — plant the pre-fix order and the SAME harness must stall ───
+# Without this, a green section 1 could mean "the harness cannot see a deadlock".
+# The planted role is tsc-cached.sh's own pre-2026-09-13 body in miniature: take
+# the folder lock, then queue for a slot while holding it.
+red_proof() {
+  echo "== red proof — a planted LOCK->SLOT holder must still deadlock the pair"
+  local sb r
+  sb="$(mktemp -d)"; probe_up
+  r=$(_race "$sb" bash -c ". '$_HERE/lib/govern.sh'
+      gate_lock '$LOCKNAME' $WAIT || exit 9
+      trap 'gate_release_all' EXIT INT TERM
+      bash '$GR' planted -- echo computed")
+  case "$r" in
+    stalled*)
+      ok "the inverted order still deadlocks and the harness sees it — $r" ;;
+    done)
+      nope "a planted LOCK->SLOT holder did NOT stall — this checker has no power,
+          so section 1 going green proves nothing.
+$(sed 's/^/          A| /' "$sb/a.log"; sed 's/^/          B| /' "$sb/b.log")" ;;
+  esac
+  probe_down; rm -rf "$sb"
+}
+
+# ── 3. A CACHE HIT COSTS NOTHING — no lock, no slot ─────────────────────────
+# The memo lookup is what makes this cache worth having. If a HIT queued for a
+# slot, every cheap verify-fast would join the same queue as a real typecheck —
+# and land.sh's `--probe` (a lookup, never a compute) would be able to hang.
+hit_is_free() {
+  echo "== a cache HIT takes neither the lock nor a slot"
+  local sb out n
+  sb="$(mktemp -d)"; probe_up
+  # compute once (this one legitimately takes a slot)
+  GOVERN_DIR="$sb" GOVERN_MAX_GATES=1 TSC_CACHE_CMD='echo no-errors-here' \
+    bash "$TSC" "$REL" >/dev/null 2>&1
+  n=$(ls "$sb" 2>/dev/null | grep -c "^${LOCKNAME}\." | tr -d ' ')
+  [ "${n:-0}" -ge 1 ] || nope "nothing was memoised — the rest of this section cannot bind"
+  # Now a HIT, with the slots ALL taken. If it needs one, it cannot finish.
+  mkdir -p "$sb/lock-slot-1"; echo $$ > "$sb/lock-slot-1/pid"
+  out=$(GOVERN_DIR="$sb" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=6 TSC_CACHE_WAIT=6 \
+        TSC_CACHE_CMD='echo no-errors-here' bash "$TSC" "$REL" 2>/dev/null)
+  if [ "$(printf '%s' "$out" | tr -d '[:space:]')" = "0" ]; then
+    ok "a HIT answers 0 with every slot held (it never queued)"
+  else
+    nope "a HIT could not answer with the slots held (got '${out:-}') — it is taking a slot"
+  fi
+  [ -d "$sb/lock-$LOCKNAME" ] && nope "a HIT left the folder lock behind — it took the lock" \
+    || ok "a HIT took no folder lock"
+  # --probe, the pure lookup land.sh uses, under the same starvation
+  out=$(GOVERN_DIR="$sb" GOVERN_MAX_GATES=1 GOVERN_QUEUE_WAIT=6 \
+        bash "$TSC" --probe "$REL" 2>/dev/null)
+  [ "$out" = "green" ] && ok "--probe answers green with every slot held" \
+    || nope "--probe could not answer with the slots held (got '${out:-}')"
+  probe_down; rm -rf "$sb"
+}
+
+echo "govern-order-check — SLOT before LOCK, proved by deadlocking it"
+real_pair
+red_proof
+hit_is_free
+[ "$bad" -eq 0 ] && { echo "govern-order: PASS"; exit 0; }
+echo "govern-order: FAILED ($bad)"; exit 1

package/scripts/governor-doors-check.sh

@@ -22,9 +22,17 @@
 # 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 governed slot on a
-# 2-second typecheck is cost with no benefit, and `tsc` already has its own
-# lock via tsc-cached.sh -- nesting it would put two locks on one logical gate.
+# 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
@@ -44,7 +52,7 @@ HEAVY_RE='vitest|tsc[[:space:]]+--noEmit|astro[[:space:]]+check|playwright[[:spa
 # <pkg-relpath>::<script>   why
 skips() {
   cat <<'SKIP'
-*::typecheck                a bare tsc, seconds not minutes, and verify-fast routes tsc through tsc-cached.sh which takes its OWN gate lock -- wrapping would be a second lock on one logical gate
+*::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 -- and since 2026-09-13 takes that slot BEFORE the lock, never while holding it (govern-order-check.sh proves both halves). 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
@@ -236,9 +244,82 @@ reentrancy() {
   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"
@@ -273,7 +354,7 @@ 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; reentrancy; echo; self_test; fi ;;
+               else audit; echo; paths; echo; compute_sites; echo; reentrancy; echo; self_test; fi ;;
 esac
 
 echo