@oneie/claude 0.9.0 → 0.10.0

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

@@ -52,7 +52,7 @@ HEAVY_RE='vitest|tsc[[:space:]]+--noEmit|astro[[:space:]]+check|playwright[[:spa
 # <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
+*::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

package/scripts/health.sh

@@ -197,12 +197,26 @@ run_once() {
 # an argument and not as a list of pids.
 REPO_ROOT="$(cd "$HERE/../.." && pwd)"
 
+# Walk REAL descendants via ppid — never signal a process GROUP. A pgid can be
+# shared with an ancestor shell/session when a child is spawned without
+# setsid(2) (tsserver commonly is), and `kill -TERM -$pgid` then kills
+# everything sharing that group, session included. Measured 2026-09-15: this
+# exact line took down 3 of 6 live `claude` sessions whose tsserver children
+# happened to share the launching shell's process group. ppid is the only
+# honest boundary — it can never reach outside the tree rooted at $pid.
+_kill_tree() { # pid -> TERM pid and every process/pid rooted at pid, leaves ancestors untouched
+  local pid="$1" child
+  for child in $(pgrep -P "$pid" 2>/dev/null); do
+    _kill_tree "$child"
+  done
+  kill -TERM "$pid" 2>/dev/null || true
+}
+
 _reap() { # pid why
-  local pid="$1" why="$2" rss pgid
+  local pid="$1" why="$2" rss
   rss=$(( $(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ' || echo 0) / 1024 ))
   if [ "$DRY" = "1" ]; then printf '  %sWOULD%s reclaim pid=%-7s %5sMB  %s\n' "$C_WARN" "$C_OFF" "$pid" "$rss" "$why"; return 0; fi
-  pgid=$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ')
-  kill -TERM -"${pgid:-$pid}" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+  _kill_tree "$pid"
   printf '  %sreclaimed%s pid=%-7s %5sMB  %s\n' "$C_OK" "$C_OFF" "$pid" "$rss" "$why"
 }
 
@@ -401,6 +415,27 @@ self_test() {
   fi
   rm -f "$gutted2"
 
+  # F8 / R3 — _reap must never signal a process GROUP. Measured 2026-09-15: a
+  # negative-pid kill of a shared pgid killed 3 live claude sessions whose
+  # tsserver children shared the launching shell's pgid. Static proof this
+  # pattern can never silently return, since the runtime proof (spawn a real
+  # shared-pgid tree, reap the child, assert the parent survives) needs a real
+  # fork this harness cannot safely stage inside a self-test. Excludes THIS
+  # comment block and itself from the scan.
+  if grep -vE '^\s*#' "${BASH_SOURCE[0]}" | grep -qE 'kill[[:space:]]+-TERM[[:space:]]+-"'; then
+    bad "F8 _reap (or something) still signals a process GROUP with -\"\$pgid\""
+  else
+    ok "F8 nothing in this file signals a process group — only _kill_tree's ppid walk"
+  fi
+
+  # _kill_tree must walk descendants (ppid) and never widen beyond them.
+  REAPED=""
+  pgrep() { case "$1" in -P) case "$2" in 4242) echo 4243 ;; 4243) : ;; esac ;; esac; }
+  kill() { REAPED="$REAPED $2"; }
+  _kill_tree 4242
+  case "$REAPED" in *" 4242"*" 4243"*|*" 4243"*" 4242"*) ok "F9 _kill_tree reaches the target and its real child" ;; *) bad "F9 got: '$REAPED'";; esac
+  unset -f pgrep kill 2>/dev/null || true
+
   if [ $fails -eq 0 ]; then echo "ALL GREEN — the verdict bites and a bad 200 is not UP"; return 0; fi
   echo "RED — $fails check(s) failed"; return 1
 }

package/scripts/incident.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# incident.sh — the accounts, fetched when they are relevant, not carried always.
+#
+# manifest: monorepo-only
+#
+# THE PROBLEM IT SOLVES. 35,752 lines of shell under .claude/scripts/, of which
+# 10,961 — THIRTY PERCENT — are comments, and most of that is incident history:
+# the day a thing was measured, the sha, the count, what was diagnosed wrong
+# first. Every one of those lines is load-bearing (it is why the code has the
+# shape it has) and every one of them is paid for on every read, by every human
+# and every agent, whether or not it is relevant to the edit in hand.
+#
+# THE SPLIT. A comment block is two different things wearing one coat:
+#
+#   the RULE     imperative, 1-2 lines, true at the line it guards.
+#                "Never pipe a gate." "gc measures against origin/main."
+#                STAYS INLINE. Moving it is how a trap stops biting.
+#
+#   the ACCOUNT  the story that earned the rule — dates, shas, counts, the
+#                wrong diagnosis that came first. Read ONCE, when you are about
+#                to change that code or doubt that rule. MOVES HERE, VERBATIM.
+#
+# Nothing is paraphrased and nothing is deleted: a trap loses its authority the
+# moment it is summarised, so the account moves whole and the rule stays put.
+# The script keeps a `# incident:<id>` pointer, which is the guarantee — an
+# agent with no inherited context still sees it in the file it is editing and
+# needs one command.
+#
+# Usage:
+#   incident.sh                      # every family, with counts
+#   incident.sh <family>             # the whole family (e.g. sweep, deploy)
+#   incident.sh <id>                 # one account
+#   incident.sh --for <script>       # every account that script points at
+#   incident.sh --check              # parity, both directions, both copies
+#   incident.sh --self-test          # prove --check can go red
+#
+# WHY --check IS NOT OPTIONAL. A pointer to a moved section is worse than no
+# pointer: it reads as authority and resolves to nothing. So the check runs both
+# ways — every `# incident:<id>` in a script resolves to a `## <id>` here, and
+# every `## <id>` here is pointed at by at least one script. An orphaned account
+# is an account nobody will ever be shown.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${INCIDENT_ROOT:-$(cd "$HERE/../.." && pwd)}"
+DIR="$ROOT/.claude/incidents"
+# Both copies, or the check lies: packages/claude/ is a hand-maintained verbatim
+# mirror with no build step, so it rots silently.
+SCRIPT_DIRS=("$ROOT/.claude/scripts" "$ROOT/packages/claude/scripts")
+
+say() { printf '%s\n' "$*"; }
+ok()  { printf '  ok   %s\n' "$*"; }
+bad() { printf '  RED  %s\n' "$*" >&2; }
+
+# _ids_declared — every `## <id>` across the ledger.
+_ids_declared() { grep -h '^## ' "$DIR"/*.md 2>/dev/null | sed 's/^## //' | sort -u; }
+
+# _ids_in — ONE matcher for every `incident:<id>` token, used by --check AND by
+# --for. They had two, and the two drifted within the hour: --for still carried
+# the older `#[[:space:]]*incident:` form, which requires the token to follow the
+# `#` directly — so every pointer written at the END of a rule line was invisible
+# to it. `--check` reported 32 reachable while `--for deploy.sh` found 9, and only
+# one of them was right. A checker that re-implements what it checks proves only
+# that two copies agree.
+#
+# The token is `incident:` immediately followed by the id, with NO space. That is
+# what keeps a sentence out of the count: `incident: demo` (spaced) is prose and
+# never matches, so a script that merely talks about an incident does not claim
+# to point at one. Presence greps are not proof; this one has a shape.
+#
+# AND IT SKIPS ITSELF, which is not fastidiousness. This file's --self-test
+# writes fixture scripts containing `# incident:demo-one` and friends; scanned,
+# the checker reported its own test data as three DANGLING production pointers
+# (measured 2026-09-17, first run). A checker that reads its own fixtures is
+# measuring the test, not the tree. The cost is that a real pointer inside
+# incident.sh would be invisible — there are none, by construction.
+_ids_in() { # <file-or-dir>...
+  grep -rhoE 'incident:[A-Za-z0-9_-]+' "$@" 2>/dev/null \
+    --exclude=incident.sh | sed 's/.*incident://' | sort -u
+}
+_ids_referenced() { _ids_in "${SCRIPT_DIRS[@]}"; }
+
+_section() { # <id> — print that one account
+  local id="$1" f
+  for f in "$DIR"/*.md; do
+    awk -v id="$id" '
+      $0 == "## " id {inside=1; print; next}
+      inside && /^## / {exit}
+      inside {print}
+    ' "$f"
+  done
+}
+
+cmd_check() {
+  local rc=0 id decl ref miss=0 orph=0
+  [ -d "$DIR" ] || { bad "no ledger at $DIR"; return 1; }
+  decl="$(_ids_declared)"; ref="$(_ids_referenced)"
+  say "── incident ledger ──"
+  say "  declared=$(printf '%s\n' "$decl" | grep -c . ) referenced=$(printf '%s\n' "$ref" | grep -c . )"
+  # A pointer that resolves to nothing.
+  while IFS= read -r id; do
+    [ -n "$id" ] || continue
+    printf '%s\n' "$decl" | grep -qx "$id" || { bad "DANGLING pointer: # incident:$id — no '## $id' in .claude/incidents/"; miss=$((miss+1)); rc=1; }
+  done <<< "$ref"
+  # An account nobody is ever shown.
+  while IFS= read -r id; do
+    [ -n "$id" ] || continue
+    printf '%s\n' "$ref" | grep -qx "$id" || { bad "ORPHAN account: ## $id — no script points at it"; orph=$((orph+1)); rc=1; }
+  done <<< "$decl"
+  [ $rc -eq 0 ] && ok "every pointer resolves, every account is reachable"
+  say "  dangling=$miss orphans=$orph"
+  return $rc
+}
+
+cmd_self_test() {
+  local tmp rc=0 out
+  tmp="$(mktemp -d)"
+  mkdir -p "$tmp/.claude/incidents" "$tmp/.claude/scripts" "$tmp/packages/claude/scripts"
+  say "── incident.sh --self-test ──"
+
+  # 1. a matched pair is green
+  printf '## demo-one\n\nthe account.\n' > "$tmp/.claude/incidents/demo.md"
+  printf '#!/usr/bin/env bash\n# incident:demo-one\n' > "$tmp/.claude/scripts/x.sh"
+  out="$( INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check 2>&1 )" \
+    && ok "matched pair passes" || { bad "matched pair failed: $out"; rc=1; }
+
+  # 2. a DANGLING pointer must fail — this is the failure the whole ledger
+  #    exists to prevent: a pointer that reads as authority and resolves to
+  #    nothing.
+  printf '#!/usr/bin/env bash\n# incident:demo-gone\n' > "$tmp/.claude/scripts/y.sh"
+  if INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check >/dev/null 2>&1; then
+    bad "a dangling pointer passed the check"; rc=1
+  else ok "a dangling pointer goes RED"; fi
+  rm -f "$tmp/.claude/scripts/y.sh"
+
+  # 3. an ORPHANED account must fail — an account nobody is shown is an account
+  #    that rots without anyone noticing.
+  printf '## demo-one\n\nthe account.\n\n## demo-orphan\n\nnobody points here.\n' > "$tmp/.claude/incidents/demo.md"
+  if INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check >/dev/null 2>&1; then
+    bad "an orphaned account passed the check"; rc=1
+  else ok "an orphaned account goes RED"; fi
+
+  # 4. the MIRROR counts as a referencing copy — canon green while the mirror
+  #    rots is the trap do-plan-json-batches was written for.
+  printf '## demo-one\n\nthe account.\n\n## demo-mirror\n\nonly the mirror points here.\n' > "$tmp/.claude/incidents/demo.md"
+  printf '#!/usr/bin/env bash\n# incident:demo-mirror\n' > "$tmp/packages/claude/scripts/z.sh"
+  INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check >/dev/null 2>&1 \
+    && ok "the mirror copy is scanned too" || { bad "the mirror copy was not scanned"; rc=1; }
+
+  # 5. a mention in PROSE is not a reference. (Clearing z.sh first is not
+  #    housekeeping — leaving it made this case go red on a DANGLING pointer
+  #    from case 4, which is the check working and the fixture lying. A fixture
+  #    looser than the case it claims to test certifies nothing.)
+  rm -f "$tmp/packages/claude/scripts/z.sh"
+  printf '## demo-one\n\nthe account.\n' > "$tmp/.claude/incidents/demo.md"
+  printf '#!/usr/bin/env bash\n# incident:demo-one\n# talk about incident: demo-prose here\n' > "$tmp/.claude/scripts/x.sh"
+  INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check >/dev/null 2>&1 \
+    && ok "a spaced-out mention is not counted as a pointer" || { bad "prose counted as a pointer"; rc=1; }
+
+  # 6. --for and --check read the SAME tokens. They did not: --for missed every
+  #    pointer written at the end of a line, and reported 9 of 24.
+  printf '## demo-tail\n\nthe account.\n' >> "$tmp/.claude/incidents/demo.md"
+  printf '#!/usr/bin/env bash\n# a rule, stated first.        incident:demo-tail\n' \
+    > "$tmp/.claude/scripts/tail.sh"
+  # NOT `... | grep -q`. Under `set -o pipefail` grep -q exits on the FIRST match
+  # and closes the pipe, the upstream bash takes SIGPIPE and exits 141, and the
+  # pipeline status is 141 — so a case that PASSED reads as RED. It did, here,
+  # for ten minutes, while the --for output being tested was visibly correct.
+  _for_out="$( INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --for "$tmp/.claude/scripts/tail.sh" 2>/dev/null )"
+  case "$_for_out" in
+    "## demo-tail"*) ok "--for finds a pointer at the END of a line" ;;
+    *) bad "--for missed an end-of-line pointer"; rc=1 ;;
+  esac
+  rm -f "$tmp/.claude/scripts/tail.sh"
+  printf '## demo-one\n\nthe account.\n' > "$tmp/.claude/incidents/demo.md"
+
+  # 7. the checker does not scan itself — its own fixtures are not pointers.
+  cp "$HERE/incident.sh" "$tmp/.claude/scripts/incident.sh"
+  INCIDENT_ROOT="$tmp" bash "$HERE/incident.sh" --check >/dev/null 2>&1 \
+    && ok "incident.sh's own fixtures are not counted as pointers" \
+    || { bad "the checker scanned itself"; rc=1; }
+
+  rm -rf "$tmp"
+  say ""
+  [ $rc -eq 0 ] && say "  self-test PASS" || say "  self-test RED"
+  return $rc
+}
+
+case "${1:-}" in
+  --check)     cmd_check; exit $? ;;
+  --self-test) cmd_self_test; exit $? ;;
+  --for)
+    [ -n "${2:-}" ] || { say "usage: incident.sh --for <script>"; exit 2; }
+    ids="$(_ids_in "$2")"
+    [ -n "$ids" ] || { say "no incident pointers in $2"; exit 0; }
+    while IFS= read -r id; do [ -n "$id" ] && _section "$id" && say ""; done <<< "$ids"
+    exit 0 ;;
+  "")
+    say "incident ledger — .claude/incidents/"
+    for f in "$DIR"/*.md; do
+      [ -e "$f" ] || { say "  (empty)"; break; }
+      say "  $(basename "${f%.md}")  ($(grep -c '^## ' "$f") account(s))"
+    done
+    say ""
+    say "  incident.sh <family> | <id> | --for <script> | --check"
+    exit 0 ;;
+  *)
+    if [ -f "$DIR/$1.md" ]; then cat "$DIR/$1.md"; exit 0; fi
+    out="$(_section "$1")"
+    [ -n "$out" ] && { printf '%s\n' "$out"; exit 0; }
+    say "no family or account named '$1' — try: incident.sh"; exit 2 ;;
+esac