@oneie/claude 0.7.0 → 0.9.0

package/scripts/governor-escape-check.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# governor-escape-check.sh — proof for hook:governor-escape, both directions.
+#
+#   bash .claude/scripts/governor-escape-check.sh
+#
+# Three parts, and the third is the one that makes the first two mean anything:
+#
+#   A  the matcher's case table — every escape BLOCKS, and every innocent
+#      command that merely NAMES an escape is ALLOWED. A guard with false
+#      positives gets switched off, which is worse than no guard at all.
+#   B  the REAL hook, driven end to end with a real payload on stdin. A
+#      matcher-only table stays green while the hook is broken (a wrong jq
+#      path, a missing tool_name guard, malformed deny JSON), so at least one
+#      BLOCK and one allow go through the actual file.
+#   C  the RED PROOF. Gut the matcher and assert A goes red; neuter the hook
+#      (ECC_DISABLED_HOOKS) and assert B goes red. A checker that stays green
+#      against a gutted subject proves nothing — the same argument
+#      govern-claims-check.sh makes when it stubs _gv_alive.
+#
+# Exits non-zero on any failure. Touches nothing outside a temp dir.
+# Test-case strings deliberately avoid absolute monorepo paths: this script is
+# classified `portable` in factory-repo.sh's manifest, and --check-portability
+# greps the file CONTENTS for them.
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+MATCH="${GOV_MATCH_FILE:-$ROOT/.claude/hooks/lib/governor-escape-match.sh}"
+HOOK="$ROOT/.claude/hooks/governor-escape.sh"
+# shellcheck source=/dev/null
+. "$MATCH"
+
+# A stray ECC_DISABLED_HOOKS in the operator's environment would neuter part B
+# and read as a red. Clear it for the real run; part C sets it explicitly on the
+# child it wants neutered.
+[ -z "${GOV_CHECK_INNER:-}" ] && unset ECC_DISABLED_HOOKS
+
+bad=0
+ok()   { printf '  ok    %s\n' "$*"; }
+nope() { printf '  FAIL  %s\n' "$*"; bad=$((bad + 1)); }
+
+# ---------------------------------------------------------------------------
+# A — the matcher
+# ---------------------------------------------------------------------------
+m_check() { # m_check <BLOCK|allow> <label> <command>
+  local want="$1" label="$2" cmd="$3" kind
+  kind="$(gov_escape_kind "$cmd")"
+  local got="allow"; [ -n "$kind" ] && got="BLOCK"
+  if [ "$got" = "$want" ]; then ok "$want  $label${kind:+  [$kind]}"
+  else nope "$want expected, got $got  —  $label"; fi
+}
+
+part_a() {
+  echo "== A. matcher — escapes must BLOCK"
+  m_check BLOCK 'bun run test:raw'            'cd web && bun run test:raw'
+  m_check BLOCK 'bun run verify:raw'          'bun run verify:raw'
+  m_check BLOCK 'bunx vitest run <file>'      'bunx vitest run tests/unit/foo.test.ts'
+  m_check BLOCK 'npx vitest'                  'npx vitest'
+  m_check BLOCK 'bare vitest run'             'vitest run'
+  m_check BLOCK 'path-invoked vitest'         'node_modules/.bin/vitest run'
+  m_check BLOCK 'vitest after an operator'    'echo starting; bunx vitest run'
+  m_check BLOCK 'GOVERN_DISABLE in front'     'GOVERN_DISABLE=1 bun run verify'
+  m_check BLOCK 'CI=1 in front'               'CI=1 bunx vitest run'
+  m_check BLOCK 'env bypass beats gate-run'   'GOVERN_DISABLE=1 bash .claude/scripts/gate-run.sh verify -- bun run verify'
+
+  echo "== A. matcher — merely NAMING an escape must be allowed"
+  m_check allow 'the governed form'           'bash .claude/scripts/gate-run.sh test -- bunx vitest run tests/unit/foo.test.ts'
+  m_check allow 'governed package script'     'cd web && bun run verify'
+  m_check allow 'the dev lane'                'cd web && bun run verify:fast'
+  m_check allow 'a commit message'            "git commit -m 'fix: bun run test:raw is the escape hatch'"
+  m_check allow 'grepping for it'             'grep -rn "verify:raw" web/package.json'
+  m_check allow 'reading package.json'        "sed -n '47,48p' web/package.json"
+  m_check allow 'reading the vitest config'   'cat web/vitest.config.ts'
+  m_check allow 'echoing the override'        'echo "GOVERN_DISABLE=1 bun run verify is the override"'
+  m_check allow 'env bypass, but no gate'     'GOVERN_DISABLE=1 ls -la'
+  m_check allow 'CI=1 on a non-gate'          'CI=1 bun run build'
+  m_check allow 'reading the hook itself'     'cat .claude/hooks/governor-escape.sh'
+  m_check allow 'tsc is out of scope'         'bunx tsc --noEmit'
+  # THE FALSE POSITIVE THAT ALREADY BIT SOMEONE. hook:load-guard REFUSES this
+  # command: the `|` INSIDE the quoted regex is a shell-operator position as
+  # far as a position-anchored pattern is concerned, and what follows it is
+  # `tsc --noEmit'` -- which load-guard.sh:57 matches as a bare alternative.
+  # Reading `ps` is not running a gate. This guard cannot reproduce it: the
+  # vitest rule needs the literal word `vitest` at that position, and tsc is
+  # deliberately out of scope -- so the scope decision is load-bearing, not
+  # incidental.
+  m_check allow 'ps piped into grep'          "ps -Ao rss,command | grep -E 'vitest|tsc --noEmit'"
+  m_check allow 'ps grep, vitest first'       "ps -Ao command | grep -E 'vitest|astro check'"
+  m_check allow 'pgrep for a runner'          'pgrep -fl vitest'
+  # The heredoc case. `grep -E` anchors ^ per LINE, so a doc BODY quoting an
+  # escape would match without _gov_strip_heredocs. Writing about the escape is
+  # the most innocent act there is.
+  m_check allow 'heredoc body quoting it'     "$(printf '%s\n' \
+    "cat > notes.md <<'EOF'" \
+    'bun run test:raw is the ungoverned lane' \
+    'GOVERN_DISABLE=1 bun run verify bypasses the cap' \
+    'EOF')"
+}
+
+# ---------------------------------------------------------------------------
+# B — the real hook, end to end
+# ---------------------------------------------------------------------------
+h_deny() { # h_deny <command>  -> prints "deny" or "allow"
+  local payload out
+  payload="$(jq -nc --arg c "$1" --arg d "$ROOT" \
+    '{tool_name:"Bash",cwd:$d,tool_input:{command:$c}}')"
+  out="$(printf '%s' "$payload" | CLAUDE_PROJECT_DIR="$ROOT" bash "$HOOK" 2>&1)"
+  case "$out" in *'"permissionDecision":"deny"'*) printf 'deny' ;; *) printf 'allow' ;; esac
+}
+
+part_b() {
+  echo "== B. the hook itself, driven with a real payload"
+  local got
+  got="$(h_deny 'cd web && bun run test:raw')"
+  [ "$got" = "deny" ] && ok "hook DENIES  bun run test:raw" \
+                      || nope "hook did not deny  bun run test:raw  (got $got)"
+  got="$(h_deny 'GOVERN_DISABLE=1 bun run verify')"
+  [ "$got" = "deny" ] && ok "hook DENIES  GOVERN_DISABLE=1 bun run verify" \
+                      || nope "hook did not deny the env bypass  (got $got)"
+  got="$(h_deny "git commit -m 'fix: bun run test:raw is the escape hatch'")"
+  [ "$got" = "allow" ] && ok "hook ALLOWS a commit message that quotes it" \
+                       || nope "hook denied an innocent commit message — FALSE POSITIVE"
+  got="$(h_deny 'bash .claude/scripts/gate-run.sh test -- bunx vitest run tests/unit/foo.test.ts')"
+  [ "$got" = "allow" ] && ok "hook ALLOWS the governed form" \
+                       || nope "hook denied the governed form (got $got)"
+
+  # The documented human override must actually work, or nobody can get past it.
+  local payload out
+  payload="$(jq -nc --arg c 'bun run test:raw' --arg d "$ROOT" \
+    '{tool_name:"Bash",cwd:$d,tool_input:{command:$c}}')"
+  out="$(printf '%s' "$payload" | CLAUDE_PROJECT_DIR="$ROOT" \
+        ECC_DISABLED_HOOKS=hook:governor-escape bash "$HOOK" 2>&1)"
+  case "$out" in
+    *'"permissionDecision":"deny"'*) nope "ECC_DISABLED_HOOKS=hook:governor-escape did NOT disable it" ;;
+    *) ok "ECC_DISABLED_HOOKS=hook:governor-escape releases it (the human override)" ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# C — the red proof
+# ---------------------------------------------------------------------------
+part_c() {
+  echo "== C. red proof — gut the subject, the checks must go RED"
+  local tmp; tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' EXIT
+
+  # C1 — a matcher that never matches. If part A still passes, part A is theatre.
+  { cat "$MATCH"; printf '\ngov_escape_kind() { return 1; }\n'; } > "$tmp/stub.sh"
+  if GOV_CHECK_INNER=matcher GOV_MATCH_FILE="$tmp/stub.sh" \
+       bash "${BASH_SOURCE[0]}" >"$tmp/a.log" 2>&1; then
+    nope "matcher gutted to always-allow and part A STILL PASSED"
+  else
+    ok "matcher gutted -> part A goes red ($(grep -c '^  FAIL' "$tmp/a.log") failures)"
+  fi
+
+  # C2 — a hook that cannot deny. If part B still passes, part B is theatre.
+  if GOV_CHECK_INNER=hook ECC_DISABLED_HOOKS=hook:governor-escape \
+       bash "${BASH_SOURCE[0]}" >"$tmp/b.log" 2>&1; then
+    nope "hook disabled and part B STILL PASSED"
+  else
+    ok "hook disabled -> part B goes red ($(grep -c '^  FAIL' "$tmp/b.log") failures)"
+  fi
+}
+
+case "${GOV_CHECK_INNER:-}" in
+  matcher) part_a ;;
+  hook)    part_b ;;
+  *)       part_a; echo; part_b; echo; part_c ;;
+esac
+
+echo
+if [ "$bad" -eq 0 ]; then echo "RESULT: PASS — the guard bites, and it does not bite the innocent"
+else echo "RESULT: RED — $bad failure(s)"; exit 1; fi

package/scripts/health.sh

@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+# health.sh — is this box healthy enough to work on, and is the estate up?
+#
+# manifest: portable
+#
+# WHY (measured 2026-09-05). Answering "why is localhost slow" took a dozen
+# ad-hoc commands: uptime, vm_stat, sysctl vm.swapusage, three greps of ps, a
+# gate-reaper dry run, an ls of the governor dir, and a curl per surface. Every
+# one of those numbers already had a home; nothing put them on one page. The
+# session that prompted this found 19 orphaned workerd processes holding the box
+# at 20.5G of 21.5G swap — visible in ps all along, in a shape nobody was
+# looking at.
+#
+# It reuses rather than restates: machine-check.sh owns the process/memory read,
+# gate-reaper.sh --dry-run owns the orphan shape, govern.sh owns the arithmetic.
+# This adds the VERDICT and the service probes, and nothing else.
+#
+# Usage:  health.sh [--box] [--services] [--json] [--watch N] [--self-test]
+#   (no flags)   both halves, human-readable
+#   --box        the machine only          --services   the estate only
+#   --json       machine-readable, both halves, no colour
+#   --watch N    re-run every N seconds until interrupted
+#   --fix        reclaim what nothing is coming back for, then re-read
+#   --dry-run    with --fix, name every kill instead of making it
+#   --signal     emit the box verdict into the world, tagged `engineering`, so
+#                the doctor sees the Mac in the same graph as the estate
+#   --self-test  prove the verdict thresholds bite (red proof included)
+#
+# WHAT --fix WILL AND WILL NOT TOUCH. It reclaims three shapes, each one dead by
+# a test that cannot be true of live work:
+#   1. orphaned gates and workerd  — delegated whole to gate-reaper.sh, whose own
+#      checker proves it spares a live parent and a fresh reparent
+#   2. language servers rooted in a WORKTREE — the editor should not have opened
+#      a project there at all (.vscode/settings.json excludes it); the real
+#      tsserver for the main tree is never a candidate
+#   3. dev servers in a worktree with NO live claude session — the session that
+#      started it is gone, so nobody is watching the port
+# It will NEVER kill a claude session, anything holding a governor slot, or
+# anything running in the main tree. Those are judgement calls a script does not
+# get to make: a session classifier misfired twice on 2026-09-05, which is the
+# reason this list is shapes-with-a-dead-owner and not "looks idle".
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/govern.sh
+. "$HERE/lib/govern.sh" 2>/dev/null || true
+
+WANT_BOX=1; WANT_SVC=1; AS_JSON=0; WATCH=0; SELFTEST=0; FIX=0; DRY=0; SIGNAL=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --box)       WANT_SVC=0 ;;
+    --services)  WANT_BOX=0 ;;
+    --json)      AS_JSON=1 ;;
+    --watch)     WATCH="${2:-10}"; shift ;;
+    --fix)       FIX=1 ;;
+    --dry-run)   DRY=1 ;;
+    --signal)    SIGNAL=1 ;;
+    --self-test) SELFTEST=1 ;;
+    -h|--help)   sed -n '2,24p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "health: unknown flag $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+C_OK=$'\033[32m'; C_WARN=$'\033[33m'; C_BAD=$'\033[31m'; C_DIM=$'\033[2m'; C_OFF=$'\033[0m'
+[ -t 1 ] || { C_OK=""; C_WARN=""; C_BAD=""; C_DIM=""; C_OFF=""; }
+[ "$AS_JSON" = "1" ] && { C_OK=""; C_WARN=""; C_BAD=""; C_DIM=""; C_OFF=""; }
+
+# ── the box ───────────────────────────────────────────────────────────────────
+# Every number here has exactly one source. load and swap come from the kernel;
+# headroom comes from govern.sh so the dashboard can never disagree with the
+# governor that actually admits gates.
+cores() { sysctl -n hw.ncpu 2>/dev/null || nproc 2>/dev/null || echo 1; }
+load1()  { uptime | sed -E 's/.*load averages?: *([0-9.]+).*/\1/'; }
+swap_used_mb() { sysctl -n vm.swapusage 2>/dev/null | sed -E 's/.*used = ([0-9.]+)M.*/\1/' | cut -d. -f1; }
+swap_free_mb() { sysctl -n vm.swapusage 2>/dev/null | sed -E 's/.*free = ([0-9.]+)M.*/\1/' | cut -d. -f1; }
+orphan_count() {
+  [ -x "$HERE/gate-reaper.sh" ] || { echo 0; return; }
+  bash "$HERE/gate-reaper.sh" --once --dry-run 2>/dev/null | grep -c 'WOULD reap' || true
+}
+slots_held() { ls -d "${TMPDIR:-/tmp}/one-govern"/lock-slot-* 2>/dev/null | wc -l | tr -d ' '; }
+sessions()   { ps -Ao command= 2>/dev/null | grep -cE '^claude( --|$)' || true; }
+
+# VERDICT — the whole point of the file. Thresholds are the ones the harness
+# already uses: machine-check calls load healthy under `cores`, and govern.sh
+# refuses to fund a second cycle below one cycle's price. A dashboard that
+# invents its own thresholds would drift from the governor within a week.
+box_verdict() {
+  local c load_i head orph swapfree
+  c=$(cores); load_i=$(printf '%.0f' "$(load1)"); head=$(gate_headroom 2>/dev/null || echo 99)
+  orph=$(orphan_count); swapfree=$(swap_free_mb)
+  if [ "$orph" -gt 0 ]; then echo "DEGRADED|${orph} abandoned gate(s)/orphan(s) burning the box — gate-reaper.sh --once"; return; fi
+  if [ "$load_i" -gt $(( c * 2 )) ]; then echo "UNHEALTHY|load ${load_i} is over 2x the ${c} cores — gates are queueing, not running"; return; fi
+  if [ "${swapfree:-9999}" -lt 512 ]; then echo "UNHEALTHY|swap has ${swapfree}MB free — the box is paging, every gate runs long"; return; fi
+  if [ "$load_i" -gt "$c" ]; then echo "DEGRADED|load ${load_i} is over ${c} cores — work is contending"; return; fi
+  if [ "${head:-99}" -lt 2 ]; then echo "DEGRADED|memory funds only ${head} concurrent gate — close idle sessions to widen"; return; fi
+  echo "HEALTHY|load ${load_i} on ${c} cores, memory funds ${head} gates"
+}
+
+print_box() {
+  local v state why
+  v=$(box_verdict); state="${v%%|*}"; why="${v#*|}"
+  local col="$C_OK"; [ "$state" = "DEGRADED" ] && col="$C_WARN"; [ "$state" = "UNHEALTHY" ] && col="$C_BAD"
+  printf '%s\n' "── box ─────────────────────────────────────────"
+  printf '  %s%s%s  %s\n' "$col" "$state" "$C_OFF" "$why"
+  printf '  %sload %s · %s cores · swap %sM used / %sM free · gates funded %s · slots held %s · sessions %s · orphans %s%s\n' \
+    "$C_DIM" "$(load1)" "$(cores)" "$(swap_used_mb)" "$(swap_free_mb)" \
+    "$(gate_headroom 2>/dev/null || echo '?')" "$(slots_held)" "$(sessions)" "$(orphan_count)" "$C_OFF"
+}
+
+# ── the estate ────────────────────────────────────────────────────────────────
+# The URL/assert pairs are deploy.sh's, deliberately. If a probe here disagrees
+# with the one that gates a deploy, this file is the one that is wrong.
+SURFACES="one.ie|https://one.ie/api/health|\"status\":\"ok\"
+api|https://api.one.ie/health|
+channels|https://channels.one.ie/health|
+pay|https://pay.one.ie/status|\"ok\""
+
+probe() { # name url assert -> "name|state|code|ms|note"
+  local name="$1" url="$2" assert="$3" body code ms t0 t1
+  t0=$(date +%s%N 2>/dev/null || echo 0)
+  body=$(curl -sL --max-time 8 -w $'\n%{http_code}' "$url" 2>/dev/null)
+  t1=$(date +%s%N 2>/dev/null || echo 0)
+  ms=$(( (t1 - t0) / 1000000 )); [ "$ms" -lt 0 ] && ms=0
+  code="${body##*$'\n'}"; body="${body%$'\n'*}"
+  if [ "$code" != "200" ]; then echo "${name}|DOWN|${code:-000}|${ms}|no 200"; return; fi
+  if [ -n "$assert" ] && ! printf '%s' "$body" | grep -qF "$assert"; then
+    echo "${name}|DEGRADED|${code}|${ms}|200 but missing ${assert}"; return
+  fi
+  echo "${name}|UP|${code}|${ms}|"
+}
+
+print_services() {
+  printf '%s\n' "── estate ──────────────────────────────────────"
+  local line name url assert r state code ms note col
+  while IFS='|' read -r name url assert; do
+    [ -n "$name" ] || continue
+    r=$(probe "$name" "$url" "$assert")
+    IFS='|' read -r _ state code ms note <<<"$r"
+    col="$C_OK"; [ "$state" = "DEGRADED" ] && col="$C_WARN"; [ "$state" = "DOWN" ] && col="$C_BAD"
+    printf '  %s%-9s%s %-4s %5sms  %s%s%s\n' "$col" "$state" "$C_OFF" "$code" "$ms" "$C_DIM" "${name} ${note}" "$C_OFF"
+  done <<<"$SURFACES"
+  printf '  %s%-9s%s   —      —  %ssync · backup — cron-only, no health endpoint exists%s\n' \
+    "$C_DIM" "UNKNOWN" "$C_OFF" "$C_DIM" "$C_OFF"
+}
+
+print_json() {
+  local v state why
+  v=$(box_verdict); state="${v%%|*}"; why="${v#*|}"
+  printf '{"box":{"verdict":"%s","why":"%s","load":%s,"cores":%s,"swap_used_mb":%s,"swap_free_mb":%s,"gates_funded":%s,"slots_held":%s,"sessions":%s,"orphans":%s},"services":[' \
+    "$state" "$why" "$(load1)" "$(cores)" "$(swap_used_mb)" "$(swap_free_mb)" \
+    "$(gate_headroom 2>/dev/null || echo 0)" "$(slots_held)" "$(sessions)" "$(orphan_count)"
+  local first=1 name url assert r s code ms note
+  while IFS='|' read -r name url assert; do
+    [ -n "$name" ] || continue
+    r=$(probe "$name" "$url" "$assert"); IFS='|' read -r _ s code ms note <<<"$r"
+    [ $first = 1 ] || printf ','; first=0
+    printf '{"name":"%s","state":"%s","code":"%s","ms":%s}' "$name" "$s" "$code" "$ms"
+  done <<<"$SURFACES"
+  printf ']}\n'
+}
+
+# ── signal ────────────────────────────────────────────────────────────────────
+# The estate's half (health:diagnose) already writes its verdict back as weighted
+# paths. This is the Mac's half of the same graph: same tag vocabulary, so a
+# symptom here ranks beside a symptom there instead of living in a terminal
+# nobody reads. Tagged `engineering` because that is the doctor's bare stake —
+# a namespaced tag would match zero subscribers (root CLAUDE.md § the stake is
+# written as BARE words).
+emit_verdict() {
+  local lib="$HERE/../hooks/lib/signal.sh"
+  [ -f "$lib" ] || return 0
+  local v state why
+  v=$(box_verdict); state="${v%%|*}"; why="${v#*|}"
+  # shellcheck source=../hooks/lib/signal.sh
+  . "$lib" 2>/dev/null || return 0
+  command -v emit_world >/dev/null 2>&1 || return 0
+  emit_world "health" "$([ "$state" = "HEALTHY" ] && echo fyi || echo attention)" \
+    "engineering,health,box" "box is ${state}: ${why}" \
+    "verdict=${state}" "load=$(load1)" "cores=$(cores)" \
+    "swap_free_mb=$(swap_free_mb)" "gates_funded=$(gate_headroom 2>/dev/null || echo 0)" \
+    "orphans=$(orphan_count)" "sessions=$(sessions)" 2>/dev/null || true
+}
+
+run_once() {
+  if [ "$AS_JSON" = "1" ]; then print_json; return; fi
+  [ "$FIX" = "1" ] && run_fix
+  [ "$SIGNAL" = "1" ] && emit_verdict
+  [ "$WANT_BOX" = "1" ] && print_box
+  [ "$WANT_BOX" = "1" ] && [ "$WANT_SVC" = "1" ] && echo
+  [ "$WANT_SVC" = "1" ] && print_services
+  return 0
+}
+
+# ── fix ───────────────────────────────────────────────────────────────────────
+# Every candidate is named with the reason it is dead, so a --dry-run reads as
+# an argument and not as a list of pids.
+REPO_ROOT="$(cd "$HERE/../.." && pwd)"
+
+_reap() { # pid why
+  local pid="$1" why="$2" rss pgid
+  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
+  printf '  %sreclaimed%s pid=%-7s %5sMB  %s\n' "$C_OK" "$C_OFF" "$pid" "$rss" "$why"
+}
+
+# A governor slot owner is live work by definition — it is holding the lock the
+# whole box queues behind.
+_holds_slot() {
+  local pid="$1" d
+  for d in "${TMPDIR:-/tmp}/one-govern"/lock-slot-*; do
+    [ -d "$d" ] || continue
+    [ "$(cat "$d/pid" 2>/dev/null)" = "$pid" ] && return 0
+  done
+  return 1
+}
+
+# Is any live claude session cwd'd inside this worktree? lsof on the session pid
+# is the only honest test — a worktree path in a command line proves nothing.
+_worktree_has_session() {
+  local wt="$1" pid
+  for pid in $(ps -Ao pid=,command= 2>/dev/null | awk '$2 ~ /claude$/ || / claude --/ {print $1}'); do
+    lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | grep -q "^n${wt}" && return 0
+  done
+  return 1
+}
+
+fix_orphans() { # delegated whole — this file must not own a second reaper
+  [ -x "$HERE/gate-reaper.sh" ] || return 0
+  local out
+  if [ "$DRY" = "1" ]; then out=$(bash "$HERE/gate-reaper.sh" --once --dry-run 2>/dev/null)
+  else out=$(bash "$HERE/gate-reaper.sh" --once 2>/dev/null); fi
+  [ -n "$out" ] && printf '%s\n' "$out" | sed 's/^/  /'
+  return 0
+}
+
+fix_worktree_lsp() {
+  local pid root rss
+  for pid in $(pgrep -f 'tsserver.js|typescript/lib/tsserver' 2>/dev/null); do
+    _holds_slot "$pid" && continue
+    root=$(lsof -nP -p "$pid" 2>/dev/null | grep -oE "${REPO_ROOT}/\.claude/worktrees/[^/]+" | head -1)
+    [ -n "$root" ] || continue
+    _reap "$pid" "language server indexing $(basename "$root") — the editor config excludes worktrees"
+  done
+}
+
+fix_dead_dev_servers() {
+  # Resolve each dev server by its CWD, never by string-matching its argv. The
+  # first draft grepped pids and worktree paths out of one ps stream and paired
+  # them with `paste - -`; when a server's argv carried no worktree path the
+  # columns silently shifted and it paired one pid with ANOTHER pid. A kill list
+  # built by that is a coin flip, so cwd it is.
+  local pid cwd wt
+  for pid in $(pgrep -f 'bin/astro dev' 2>/dev/null); do
+    _holds_slot "$pid" && continue
+    cwd=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -1)
+    case "$cwd" in
+      "$REPO_ROOT"/.claude/worktrees/*) ;;
+      *) continue ;;
+    esac
+    wt="${cwd#"$REPO_ROOT"/.claude/worktrees/}"; wt="$REPO_ROOT/.claude/worktrees/${wt%%/*}"
+    _worktree_has_session "$wt" && continue
+    _reap "$pid" "dev server in $(basename "$wt") — no live session is cwd'd there"
+  done
+}
+
+run_fix() {
+  printf '%s\n' "── reclaiming ──────────────────────────────────"
+  [ "$DRY" = "1" ] && printf '  %sdry run — nothing will be killed%s\n' "$C_DIM" "$C_OFF"
+  local before after
+  before=$(swap_free_mb)
+  fix_orphans
+  fix_worktree_lsp
+  fix_dead_dev_servers
+  sleep 2
+  after=$(swap_free_mb)
+  printf '  %sswap free %sM -> %sM%s\n\n' "$C_DIM" "$before" "$after" "$C_OFF"
+}
+
+# ── self-test ─────────────────────────────────────────────────────────────────
+# Proves the two things that can silently rot: the verdict thresholds, and the
+# probe's willingness to call a 200 that lacks its assert DEGRADED rather than UP.
+self_test() {
+  local fails=0
+  ok()  { printf '  \033[32mPASS\033[0m  %s\n' "$1"; }
+  bad() { printf '  \033[31mFAIL\033[0m  %s\n' "$1"; fails=$((fails + 1)); }
+  echo "── health.sh: the verdict bites, and a bad 200 is not UP ──"
+
+  cores() { echo 10; }; gate_headroom() { echo 4; }; orphan_count() { echo 0; }
+  load1() { echo 2.0; }; swap_free_mb() { echo 4000; }
+  [ "$(box_verdict)" != "${_x:-}" ] && case "$(box_verdict)" in HEALTHY*) ok "C1 quiet box reads HEALTHY";; *) bad "C1 quiet box: $(box_verdict)";; esac
+
+  load1() { echo 25.0; }
+  case "$(box_verdict)" in UNHEALTHY*) ok "C2 load over 2x cores reads UNHEALTHY";; *) bad "C2 got: $(box_verdict)";; esac
+
+  load1() { echo 2.0; }; swap_free_mb() { echo 100; }
+  case "$(box_verdict)" in UNHEALTHY*) ok "C3 swap under 512MB free reads UNHEALTHY";; *) bad "C3 got: $(box_verdict)";; esac
+
+  swap_free_mb() { echo 4000; }; orphan_count() { echo 3; }
+  case "$(box_verdict)" in DEGRADED*orphan*) ok "C4 orphans read DEGRADED and name the fix";; *) bad "C4 got: $(box_verdict)";; esac
+
+  orphan_count() { echo 0; }; gate_headroom() { echo 1; }
+  case "$(box_verdict)" in DEGRADED*funds*) ok "C5 headroom of 1 reads DEGRADED";; *) bad "C5 got: $(box_verdict)";; esac
+
+  # A 200 whose body lost its assert is the failure deploy.sh's probe exists to
+  # catch — a worker that boots and serves the wrong app.
+  curl() { printf 'not the droid\n200'; }
+  case "$(probe x http://stub '"status":"ok"')" in *"|DEGRADED|"*) ok "C6 a 200 missing its assert is DEGRADED, not UP";; *) bad "C6 got: $(probe x http://stub '\"status\":\"ok\"')";; esac
+  curl() { printf '{"status":"ok"}\n200'; }
+  case "$(probe x http://stub '"status":"ok"')" in *"|UP|"*) ok "C7 a 200 carrying its assert is UP";; *) bad "C7 got: $(probe x http://stub)";; esac
+
+  # ── the --fix rules: each candidate must be dead by a test live work fails ──
+  # _reap is replaced by a recorder, so nothing is killed and the LIST is the
+  # assertion. That list is the whole safety argument of --fix.
+  REAPED=""
+  _reap() { REAPED="$REAPED $1"; }
+  REPO_ROOT="/repo"
+
+  pgrep() { echo 4242; }
+  lsof()  { echo "n/repo/.claude/worktrees/wt-a/app/web"; }   # generic on purpose: a portable script must name no monorepo path
+  _holds_slot() { return 1; }
+  _worktree_has_session() { return 1; }
+
+  REAPED=""; fix_worktree_lsp
+  case "$REAPED" in *4242*) ok "F1 a language server rooted in a worktree is a candidate";; *) bad "F1 missed it: '$REAPED'";; esac
+
+  _holds_slot() { return 0; }
+  REAPED=""; fix_worktree_lsp
+  case "$REAPED" in *4242*) bad "F2 killed a language server that holds a governor slot";; *) ok "F2 a slot holder is spared — it is the lock the box queues behind";; esac
+  _holds_slot() { return 1; }
+
+  REAPED=""; fix_dead_dev_servers
+  case "$REAPED" in *4242*) ok "F3 a dev server in a session-less worktree is a candidate";; *) bad "F3 missed it: '$REAPED'";; esac
+
+  _worktree_has_session() { return 0; }
+  REAPED=""; fix_dead_dev_servers
+  case "$REAPED" in *4242*) bad "F4 killed a dev server whose worktree HAS a live session";; *) ok "F4 a worktree with a live session is spared";; esac
+  _worktree_has_session() { return 1; }
+
+  # A dev server in the MAIN tree is never a candidate — the cwd case only
+  # admits paths under .claude/worktrees/.
+  lsof() { echo "n/repo/app/web"; }
+  REAPED=""; fix_dead_dev_servers
+  case "$REAPED" in *4242*) bad "F5 killed a dev server running in the MAIN tree";; *) ok "F5 the main tree's dev server is never a candidate";; esac
+
+  # --dry-run must not kill. Restore the real _reap and prove its dry path never
+  # reaches kill by stubbing kill itself as a recorder.
+  unset -f _reap 2>/dev/null || true
+  eval "$(sed -n '/^_reap() {/,/^}/p' "${BASH_SOURCE[0]}")"
+  KILLED=""; kill() { KILLED="$KILLED $*"; }
+  DRY=1; out=$(_reap 4242 "stub"); 
+  case "$out$KILLED" in *WOULD*) [ -z "$KILLED" ] && ok "F6 --dry-run names the kill and never calls it" || bad "F6 dry run called kill: $KILLED";; *) bad "F6 dry run printed: $out";; esac
+  unset -f kill 2>/dev/null || true
+
+  # The red proofs below run the file AGAINST ITSELF. Without this guard the
+  # gutted child runs them too, and each child spawns two more — the first
+  # version of R2 died on `mktemp: File exists`, which was the recursion, not
+  # the template.
+  if [ "${HEALTH_SELFTEST_CHILD:-0}" = "1" ]; then
+    if [ $fails -eq 0 ]; then echo "ALL GREEN (child)"; return 0; fi
+    echo "RED — $fails check(s) failed"; return 1
+  fi
+
+  # RED PROOF — take the REAL file, delete the swap arm, and run its OWN
+  # self-test. C3 must fail there. Stubbing box_verdict to a constant would
+  # prove nothing about the arm; this proves the assertion is load-bearing.
+  local gutted anchor_lines out
+  gutted="$(mktemp "${TMPDIR:-/tmp}/health-gutted.XXXXXX")"
+  grep -v "swapfree:-""9999" "${BASH_SOURCE[0]}" > "$gutted"
+  anchor_lines=$(( $(wc -l < "${BASH_SOURCE[0]}") - $(wc -l < "$gutted") ))
+  if [ "$anchor_lines" -ne 1 ]; then
+    bad "R1 could not remove the swap arm — anchor moved, this checker is blind"
+  else
+    out=$(HEALTH_SELFTEST_CHILD=1 bash "$gutted" --self-test 2>&1)
+    case "$out" in
+      *"FAIL"*"C3"*) ok "R1 red-proof: with the swap arm deleted, C3 goes red" ;;
+      *) bad "R1 red-proof did not bite — gutted script still passed C3" ;;
+    esac
+  fi
+  rm -f "$gutted"
+
+  # RED PROOF for the fix rules — delete the governor-slot guard from the real
+  # file and require F2 to go red there. F1..F6 passing against a build that
+  # cannot spare live work would be worthless.
+  local gutted2 removed out2 guard
+  gutted2="$(mktemp "${TMPDIR:-/tmp}/health-gutted2.XXXXXX")"
+  # Assembled with printf so this line is not itself the anchor it deletes.
+  guard=$(printf '_holds_slot "$%s" && continue' pid)
+  grep -vF "$guard" "${BASH_SOURCE[0]}" > "$gutted2"
+  removed=$(( $(wc -l < "${BASH_SOURCE[0]}") - $(wc -l < "$gutted2") ))
+  if [ "$removed" -ne 2 ]; then
+    bad "R2 could not remove the slot guard (removed ${removed} lines, expected 2) — anchor moved, this checker is blind"
+  else
+    out2=$(HEALTH_SELFTEST_CHILD=1 bash "$gutted2" --self-test 2>&1)
+    case "$out2" in
+      *"FAIL"*"F2"*) ok "R2 red-proof: with the slot guard deleted, F2 goes red" ;;
+      *) bad "R2 red-proof did not bite — gutted --fix still spared a slot holder" ;;
+    esac
+  fi
+  rm -f "$gutted2"
+
+  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
+}
+
+[ "$SELFTEST" = "1" ] && { self_test; exit $?; }
+
+if [ "${WATCH:-0}" != "0" ]; then
+  while :; do clear 2>/dev/null || true; date '+%H:%M:%S'; run_once; sleep "$WATCH"; done
+fi
+run_once