@chrono-meta/fh-gate 1.4.77 → 1.4.78

package/scripts/sidecar_calibrate.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# sidecar_calibrate.sh — measure the cross-family sidecar panel before trusting it.
+#
+# WHY: `auto-decorrelation` and the load-bearing cross-family gate both ask "is a different-family
+# auditor reachable?" — and until now that question was answered from memory. Two measured failures
+# on 2026-07-30, one in each direction:
+#   · A marker was written claiming `cross-family unavailable this session`. Probed later in the same
+#     session, codex ran fine. Unavailability was DECLARED, never measured.
+#   · agy pinned with the slug `gemini-3.1-pro-high` answered as **Gemini 3.6 Flash** — silently, with
+#     no error. "The sidecar ran" and "the model I pinned answered" are different propositions, and
+#     only the second one licenses a claim about model-family diversity.
+# A panel you have not probed is not a panel; it is an assumption with a hostname.
+#
+# WHAT IT MEASURES, per runtime — four legs, because each catches a different lie:
+#   REACHABLE          the binary exists and runs at all
+#   PIN-OK / UNTRUSTED-PIN
+#                      a discriminating identity probe: does the answer NAME the model that was
+#                      pinned? A generic "OK" proves nothing — any model returns it. This is the only
+#                      anchor for a runtime that falls back silently.
+#   control: rejects-bogus / accepts-bogus
+#                      pin a model that cannot exist. This measures ONE thing only: whether unknown
+#                      names are validated. It does NOT mean known names are served faithfully, and
+#                      the gap between those is where the real trap lives — agy REJECTS nonsense yet
+#                      silently served Flash for `gemini-3.1-pro-high`, a slug from its own
+#                      catalogue (measured 2026-07-30). So `rejects-bogus` must never be read as
+#                      "the pin is safe": the identity probe still decides. `accepts-bogus` is the
+#                      stronger warning — there, the identity probe is the ONLY evidence at all.
+#   VERDICT-OK / VERDICT-UNPARSEABLE
+#                      ask for one bare token. A runtime that answers with agentic prose cannot carry
+#                      a machine-read verdict. Measured for agy at 1.0.14 (2026-07-04) and NOT
+#                      inherited here: the version has moved, and this file re-measures rather than
+#                      quoting. Fitness is a per-run measurement, not a property.
+#
+# Detector, never a gate: ALWAYS exits 0. It reports; the caller decides. A calibration run that
+# could block would make callers stop running it, which is the failure this exists to prevent.
+#
+# Cost: real API calls (3 short probes per runtime). Use --only to scope. `--stub-model` exists for
+# the lane harness so it can drive stub CLIs without touching a real catalogue.
+#
+# Usage:  bash scripts/sidecar_calibrate.sh [--only codex|agy] [--stub-model NAME] [--quiet]
+# Output: one block per runtime, then a PANEL line — the line a marker's `crossfamily:` leg quotes.
+
+set -uo pipefail
+
+ONLY=""; STUB_MODEL=""; QUIET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --only) ONLY="${2:-}"; shift 2 ;;
+    --stub-model) STUB_MODEL="${2:-}"; shift 2 ;;
+    --quiet) QUIET=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+TIMEOUT_BIN=""
+command -v timeout >/dev/null 2>&1 && TIMEOUT_BIN="timeout"
+command -v gtimeout >/dev/null 2>&1 && TIMEOUT_BIN="gtimeout"
+# No coreutils timeout on stock macOS. perl's alarm is the portable watchdog; if perl is missing too,
+# run WITHOUT a deadline rather than skipping the probe — a missing watchdog must never become a
+# silently skipped measurement reported as absence (the same rule fh_session_load.sh applies).
+_run() {
+  local secs="$1"; shift
+  if [ -n "$TIMEOUT_BIN" ]; then "$TIMEOUT_BIN" "$secs" "$@"
+  elif command -v perl >/dev/null 2>&1; then perl -e 'alarm shift @ARGV; exec @ARGV' "$secs" "$@"
+  else "$@"; fi
+}
+
+# _answer — reduce a runtime's stdout to THE MODEL'S ANSWER.
+# Measured on the first real run (2026-07-30): matching against whole stdout is unsound, because a
+# real CLI prints a session banner that REPEATS the pinned model back (`codex exec` emits its
+# version, workdir and model config before the reply). Under a whole-stdout match, a runtime that
+# merely echoes its own configuration passes the identity probe — the transport layer supplying the
+# very evidence the probe exists to obtain from the model. So: take the last non-empty line, skipping
+# trailing telemetry (`tokens used`, bare numbers, rule lines).
+# RESIDUAL, named: this is a heuristic on line position. A runtime that prints its answer and then
+# unrecognised trailing chatter would be mis-read. It is checked by the banner-echo lane, not proven
+# in general; a structured output mode (JSON) would replace the heuristic and none is used here yet.
+_answer() {
+  awk 'BEGIN{last=""}
+       {line=$0
+        gsub(/\r/,"",line)
+        gsub(/^[[:space:]]+|[[:space:]]+$/,"",line)
+        if (line=="") next
+        if (line ~ /^[-=_]{3,}$/) next
+        if (tolower(line) ~ /^tokens? used/) next
+        if (line ~ /^[0-9,.]+$/) next
+        last=line}
+       END{print last}'
+}
+
+IDENTITY_PROMPT="Answer with one line only: your exact model name and version."
+VERDICT_PROMPT="Reply with exactly one word, PASS or FAIL, and nothing else. The word is PASS."
+BOGUS_MODEL="zzz-nonexistent-model-9.9"
+
+PANEL=""
+
+# build_cmd <runtime> <model> <prompt> — fills CMD as an argv array.
+# NOT a shell function passed to the watchdog: `timeout`/`gtimeout` exec a BINARY and cannot see
+# shell functions, so an earlier revision fed them a function name and every probe came back as the
+# runtime failing to run (caught by lane 3/4b/5b, not by reading).
+build_cmd() {
+  case "$1" in
+    codex) CMD=(codex exec -m "$2" -c model_reasoning_effort=high --skip-git-repo-check "$3") ;;
+    agy)   CMD=(agy -p "$3" --model "$2" --print-timeout 170s) ;;
+    *)     CMD=("$1" "$3") ;;
+  esac
+}
+
+# probe_runtime <name> <real-model-pin>
+probe_runtime() {
+  local rt="$1" model="$2"
+  [ -n "$ONLY" ] && [ "$ONLY" != "$rt" ] && return 0
+  [ -n "$STUB_MODEL" ] && model="$STUB_MODEL"
+
+  if ! command -v "$rt" >/dev/null 2>&1; then
+    printf '%-6s ABSENT — not installed on this machine (absence measured, not assumed)\n' "$rt"
+    return 0
+  fi
+
+  local id_out pin_state ctl_out ctl_state v_out v_state
+  build_cmd "$rt" "$model" "$IDENTITY_PROMPT"
+  id_out="$(_run 200 "${CMD[@]}" 2>&1 | _answer)"
+
+  # Discriminating check — the answer must be the MODEL's self-report naming the model that was
+  # pinned. What counts as "naming it" is the VERSION token, not every token of the pin slug:
+  # vendors answer with a product name (`gpt-5.6-sol` → "GPT-5.6 Codex"), and demanding the suffix
+  # made this report UNTRUSTED-PIN for a pin that had actually held (measured 2026-07-30). The
+  # version is also exactly where the real failures differ — 3.1 asked, 3.6 answered. If a pin
+  # carries no version token at all, fall back to requiring the name words, since then there is
+  # nothing sharper to test.
+  local ver name_words hit=0
+  ver="$(printf '%s' "$model" | grep -oE '[0-9]+\.[0-9]+' | head -1)"
+  name_words="$(printf '%s' "$model" | tr 'A-Z' 'a-z' | sed -E 's/[^a-z]+/ /g' \
+        | tr ' ' '\n' | grep -E '^[a-z]{3,}$' \
+        | grep -vE '^(high|low|medium|thinking|the|exec)$' | head -1)"
+  if [ -n "$id_out" ]; then
+    if [ -n "$ver" ]; then
+      printf '%s' "$id_out" | grep -qF "$ver" && hit=1
+    elif [ -n "$name_words" ]; then
+      printf '%s' "$id_out" | tr 'A-Z' 'a-z' | grep -qF "$name_words" && hit=1
+    fi
+  fi
+  if [ "$hit" -eq 1 ]; then pin_state="PIN-OK"; else pin_state="UNTRUSTED-PIN"; fi
+
+  build_cmd "$rt" "$BOGUS_MODEL" "$IDENTITY_PROMPT"
+  ctl_out="$(_run 120 "${CMD[@]}" 2>&1)"
+  if [ $? -ne 0 ] || printf '%s' "$ctl_out" | grep -qiE 'not supported|invalid|unknown model|error'; then
+    ctl_state="rejects-bogus"
+  else
+    ctl_state="accepts-bogus"
+  fi
+
+  build_cmd "$rt" "$model" "$VERDICT_PROMPT"
+  v_out="$(_run 200 "${CMD[@]}" 2>&1 | _answer)"
+  # Parseable = a bare verdict token is recoverable from a short answer. Prose that merely CONTAINS
+  # the word does not qualify: a verdict channel must be readable without a human deciding what the
+  # runtime meant.
+  local v_compact
+  v_compact="$(printf '%s' "$v_out" | tr -s '[:space:]' ' ' | sed 's/^ *//; s/ *$//')"
+  if [ "${#v_compact}" -le 12 ] && printf '%s' "$v_compact" | grep -qiE '^(pass|fail)[.!]?$'; then
+    v_state="VERDICT-OK"
+  else
+    v_state="VERDICT-UNPARSEABLE"
+  fi
+
+  printf '%-6s REACHABLE · %s · control: %s · %s\n' "$rt" "$pin_state" "$ctl_state" "$v_state"
+  [ -z "$QUIET" ] && printf '       pinned: %s\n       identity said: %s\n' "$model" "$(printf '%s' "$id_out" | cut -c1-100)"
+  if [ "$ctl_state" = "accepts-bogus" ]; then
+    printf '       ⚠️  this runtime does not validate the pin at all, so the identity probe is the ONLY\n'
+    printf '           evidence that the intended model answered — a clean run proves nothing here.\n'
+  elif [ "$pin_state" = "UNTRUSTED-PIN" ]; then
+    printf '       ⚠️  it rejects UNKNOWN names, which says nothing about serving KNOWN ones faithfully.\n'
+    printf '           The identity probe disagreed with the pin — treat this runtime as substituting.\n'
+  fi
+  # Only a runtime whose pin is trustworthy counts toward the panel. A reachable runtime answering as
+  # some other model contributes no family diversity, which is the entire point of the panel.
+  [ "$pin_state" = "PIN-OK" ] && PANEL="${PANEL:+$PANEL, }$rt"
+  return 0
+}
+
+probe_runtime codex "gpt-5.6-sol"
+probe_runtime agy   "Gemini 3.1 Pro (High)"
+
+if [ -n "$PANEL" ]; then
+  echo "PANEL: $PANEL — usable different-family auditor(s), pin verified this run"
+else
+  echo "PANEL: none — no runtime passed the identity probe on this machine, this run"
+  echo "       State this, do not infer it: a marker's crossfamily leg may say 'none' but never stay silent."
+fi
+exit 0

package/scripts/test_node_check_lanes.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# test_node_check_lanes.sh — regression lanes for scripts/fh_node_check.sh.
+#
+# WHY THIS FILE EXISTS: across three adversarial rounds on the node check, every surviving defect
+# was a NEGATIVE leg nobody was testing — "the floor does not apply here", "those are someone
+# else's hooks", "that file is absent on a fresh clone". Each round's fix reverted a previous
+# round's fix because no lane pinned it. The lanes below are that pin: they encode the *shape* of
+# each defect, not just its instance.
+#
+# Usage:  bash scripts/test_node_check_lanes.sh
+# Exit:   0 = all lanes pass; 1 = at least one lane failed (prints which and why).
+
+set -uo pipefail
+
+FH_REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CHECK="$FH_REPO/scripts/fh_node_check.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+PASS=0; FAIL=0
+ok()   { PASS=$((PASS+1)); printf '  ✅ %s\n' "$1"; }
+bad()  { FAIL=$((FAIL+1)); printf '  ❌ %s\n     got: %s\n' "$1" "$(printf '%s' "$2" | tr '\n' '|' | cut -c1-220)"; }
+
+# run <hubdir> <statefile> [env assignments...] → stdout of one check run
+run() { local hub="$1" st="$2"; shift 2; env "$@" HUB_DIR="$hub" FH_NODE_STATE="$st" bash "$CHECK" 2>&1; }
+
+mk_git_hub() {   # a git repo with FH-style hooks installed and executable
+  local d="$1" fh_sentinel="${2:-yes}"
+  mkdir -p "$d" && git -C "$d" init -q && git -C "$d" config user.email t@t && git -C "$d" config user.name t
+  echo x > "$d/f" && git -C "$d" add f && git -C "$d" -c commit.gpgsign=false commit -qm init
+  mkdir -p "$d/.git/hooks"
+  local body='#!/bin/sh\nexit 0\n'
+  [ "$fh_sentinel" = "yes" ] && body='#!/bin/sh\n# FH 4-Axis Gate Pre-Commit Hook\nfh-gate\nexit 0\n'
+  printf "$body" > "$d/.git/hooks/pre-commit"; printf "$body" > "$d/.git/hooks/pre-push"
+  chmod +x "$d/.git/hooks/pre-commit" "$d/.git/hooks/pre-push"
+}
+
+echo "── node-check lanes ──"
+
+# LANE 1 (S3-1) — NOT a git repo. The git-hook floor cannot be installed here at all, so it is
+# N/A, not missing. Reporting it would be an unfixable notice repeating every session forever.
+mkdir -p "$TMP/nogit"
+out="$(run "$TMP/nogit" "$TMP/s1" FH_MACHINE_ID=nogitbox)"
+# POSITIVE CONTROL: assert what MUST appear alongside what must not. Absence-only lanes are
+# satisfied by a script that prints nothing at all — an `exit 0` stub passed lanes 1, 4 and 7
+# (cross-family mutation 2026-07-30), so each now pins an expected utterance too.
+case "$out" in
+  *"Missing mechanical floor"*) bad "lane1 non-git: must NOT claim a missing floor (N/A, unfixable)" "$out" ;;
+  *"first session for this clone"*) ok "lane1 non-git: N/A on the git floor, but still reports the node event" ;;
+  *) bad "lane1 non-git: silent — a stub would pass this lane" "$out" ;;
+esac
+
+# LANE 2 (S3-2) — hooks exist but belong to another framework (husky/pre-commit). Executable ≠ FH's
+# gate. Silence here is the exact accident this check was built for: FH gates absent, machine quiet.
+mk_git_hub "$TMP/husky" no
+out="$(run "$TMP/husky" "$TMP/s2" FH_MACHINE_ID=huskybox)"
+case "$out" in
+  *"Missing mechanical floor"*) ok "lane2 foreign hooks: FH gate absence reported" ;;
+  *) bad "lane2 foreign hooks: non-FH hooks were accepted as FH floors" "$out" ;;
+esac
+
+# LANE 3 (S3-3) — Mode D user on a FRESH clone: companion store present, settings.local.json absent
+# (it is gitignored, so a clone never has it). This is the MEASURED 2026-07-30 incident. Must speak.
+mk_git_hub "$TMP/moded" yes
+mkdir -p "$TMP/companion/.git"
+out="$(run "$TMP/moded" "$TMP/s3" FH_MACHINE_ID=modedbox BE_DIR="$TMP/companion")"
+case "$out" in
+  *companion-load*) ok "lane3 fresh Mode D clone: companion-load absence surfaced" ;;
+  *) bad "lane3 fresh Mode D clone: SILENT — the measured incident would recur" "$out" ;;
+esac
+
+# LANE 4 (M2-4) — public non-Mode-D user: no companion store anywhere. The companion item must not
+# appear, or the majority path gets a false positive for a feature it does not use.
+mk_git_hub "$TMP/public" yes
+out="$(run "$TMP/public" "$TMP/s4" FH_MACHINE_ID=publicbox)"
+case "$out" in
+  *companion-load*) bad "lane4a non-Mode-D: companion item shown to a user with no store" "$out" ;;
+  *"first session for this clone"*) ok "lane4a non-Mode-D: companion absent, node event still reported" ;;
+  *) bad "lane4a non-Mode-D: silent — a stub would pass this lane" "$out" ;;
+esac
+
+# LANE 4b (S4-1) — CLAUDE.local.md is Claude Code's STANDARD local-override file; anyone may keep
+# one for any reason. Its mere EXISTENCE must not classify a user as Mode D, or the majority path
+# gets a companion notice every session forever (state-based emission makes it permanent, not
+# one-shot). Only the binding INSIDE the file counts.
+printf '# my local notes\nuse tabs not spaces\n' > "$TMP/public/CLAUDE.local.md"
+out="$(run "$TMP/public" "$TMP/s4b" FH_MACHINE_ID=publicbox)"
+case "$out" in
+  *companion-load*) bad "lane4b plain CLAUDE.local.md: existence alone classified the user as Mode D" "$out" ;;
+  *) ok "lane4b plain CLAUDE.local.md: not treated as a Mode D signal" ;;
+esac
+
+# LANE 4c — the same file WITH a companion binding must classify as Mode D and speak. Without this
+# leg, "never classify as Mode D" would also pass 4b.
+# One fixture PER alternative: a single fixture like `BE_DIR=/some/companion-store` satisfies two
+# alternatives at once, so either could be deleted and the lane would still pass. The store is a
+# ROLE, not a repo layout (install-wizard SKILL.md: Obsidian vault / gbrain ingest target / *-be
+# repo all qualify) — so the vocabulary variants are the documented user base, not hypotheticals.
+i=0
+# `backend: obsidian` carries no other keyword on purpose — with a `vault:` fixture only, the
+# `obsidian` alternative is never exercised and could be deleted with the suite staying green
+# (verified: removing it left 16/16). An untested alternative is an untested branch.
+for binding in 'BE_DIR=/x/store' 'companion store: ~/notes' '컴패니언 스토어: ~/notes' \
+               'vault: ~/vaults/notes' 'gbrain ingest target: ~/gbrain' 'backend: obsidian'; do
+  i=$((i+1))
+  printf '# local\n%s\n' "$binding" > "$TMP/public/CLAUDE.local.md"
+  out="$(run "$TMP/public" "$TMP/s4c$i" FH_MACHINE_ID=publicbox)"
+  case "$out" in
+    *companion-load*) ok "lane4c.$i Mode D detected via: $binding" ;;
+    *) bad "lane4c.$i binding present but Mode D not detected: $binding" "$out" ;;
+  esac
+done
+rm -f "$TMP/public/CLAUDE.local.md"
+
+# LANE 5 — emission model: a healthy machine speaks once (event) then goes silent.
+mk_git_hub "$TMP/healthy" yes
+r1="$(run "$TMP/healthy" "$TMP/s5" FH_MACHINE_ID=healthybox)"
+r2="$(run "$TMP/healthy" "$TMP/s5" FH_MACHINE_ID=healthybox)"
+if [ -n "$r1" ] && [ -z "$r2" ]; then ok "lane5 healthy: event once, then silent"
+else bad "lane5 healthy: expected run1 non-empty and run2 empty" "r1=[$r1] r2=[$r2]"; fi
+
+# LANE 6 (S2-4) — a missing floor is a CONDITION: it must be reported on every run, not once.
+mk_git_hub "$TMP/broken" yes
+rm -f "$TMP/broken/.git/hooks/pre-commit"
+n=0
+for i in 1 2 3; do
+  o="$(run "$TMP/broken" "$TMP/s6" FH_MACHINE_ID=brokenbox)"
+  case "$o" in *"Missing mechanical floor"*) n=$((n+1)) ;; esac
+done
+[ "$n" -eq 3 ] && ok "lane6 broken: reported on all 3 runs (condition, not event)" \
+               || bad "lane6 broken: reported $n/3 runs — a broken machine went quiet" "n=$n"
+
+# LANE 7 (M2-2) — linked worktree: .git is a FILE there, so a hand-built "$FH/.git/hooks" does not
+# exist and working hooks read as missing.
+mk_git_hub "$TMP/wt" yes
+git -C "$TMP/wt" worktree add -q "$TMP/wt_linked" -b lane7 2>/dev/null
+out="$(run "$TMP/wt_linked" "$TMP/s7" FH_MACHINE_ID=wtbox)"
+case "$out" in
+  *"Missing mechanical floor"*) bad "lane7 worktree: false missing-floor (hooks resolve to the main gitdir)" "$out" ;;
+  *"first session for this clone"*) ok "lane7 worktree: hooks resolved correctly, node event reported" ;;
+  *) bad "lane7 worktree: silent — a stub would pass this lane" "$out" ;;
+esac
+
+# LANE 8 (M3-3) — python3 unavailable: the companion verdict is UNMEASURED, never silently "fine".
+# Simulated by a PATH with no python3, for a Mode D hub (so the check is applicable).
+mk_git_hub "$TMP/nopy" yes
+mkdir -p "$TMP/emptybin" "$TMP/companion2/.git"
+out="$(PATH="$TMP/emptybin:/usr/bin:/bin" run "$TMP/nopy" "$TMP/s8" FH_MACHINE_ID=nopybox BE_DIR="$TMP/companion2")"
+if command -v python3 >/dev/null 2>&1 && [ -x /usr/bin/python3 ]; then
+  ok "lane8 skipped: /usr/bin/python3 exists so absence cannot be simulated via PATH"
+else
+  case "$out" in
+    *UNMEASURED*|*unmeasured*) ok "lane8 no python3: reported UNMEASURED, not silence" ;;
+    *) bad "lane8 no python3: absence read as pass" "$out" ;;
+  esac
+fi
+
+# LANE 9 (S4-2) — the sentinel regex is coupled to PROSE THAT LIVES IN ANOTHER FILE. Every other
+# lane hands it a fixture containing the string it expects, so the suite would stay fully green
+# while a purely cosmetic edit to the real hook headers (which no gate checks) made every FH machine
+# report "not FH's gate" every session. Calibrate the instrument against the shipped article.
+# DERIVE the regex from the script — never retype it. A hardcoded copy is the divergent-copy class
+# this repo already paid for once (SYNC_EXCLUDES in three places, which needed its own parity
+# checker): tighten the script's regex and a duplicated lane keeps validating the SHIPPED hooks
+# against the OLD pattern, staying green while the real check drifts.
+SENT="$(sed -n "s/.*grep -qE '\([^']*\)'.*/\1/p" "$FH_REPO/scripts/fh_node_check.sh" | head -1)"
+if [ -z "$SENT" ]; then
+  bad "lane9 sentinel: could not derive the regex from fh_node_check.sh (extraction broke — not a pass)" "empty"
+  SENT='__never_matches__'
+fi
+for h in "$FH_REPO"/templates/.git-hooks/pre-commit "$FH_REPO"/templates/.git-hooks/pre-push; do
+  if [ ! -f "$h" ]; then bad "lane9 sentinel: shipped hook missing: $h" "absent"; continue; fi
+  if grep -qE "$SENT" "$h"; then ok "lane9 sentinel matches shipped $(basename "$h")"
+  else bad "lane9 sentinel does NOT match shipped $(basename "$h") — every FH machine would report 'not FH gate'" "$(head -3 "$h")"; fi
+done
+
+printf '\nnode-check lanes: %d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ] || exit 1
+exit 0

package/scripts/test_sidecar_calibrate_lanes.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# test_sidecar_calibrate_lanes.sh — regression lanes for scripts/sidecar_calibrate.sh.
+#
+# WHY LANES FIRST: the calibrator's whole job is to distinguish states that LOOK the same from the
+# outside — "the sidecar ran" vs "the model I asked for answered", "absent" vs "unmeasured". Those
+# are negative legs, and negative legs are what three adversarial rounds on the node check showed
+# nobody tests until a lane forces it. Each lane below drives the calibrator with a STUB CLI whose
+# behaviour is known, so the calibrator's verdict can be checked against ground truth.
+#
+# No network, no API spend: every sidecar binary is replaced by a stub on PATH.
+#
+# Usage:  bash scripts/test_sidecar_calibrate_lanes.sh
+# Exit:   0 = all lanes pass; 1 = at least one failed.
+
+set -uo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CAL="$REPO/scripts/sidecar_calibrate.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+PASS=0; FAIL=0
+ok()  { PASS=$((PASS+1)); printf '  ✅ %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  ❌ %s\n     got: %s\n' "$1" "$(printf '%s' "$2" | tr '\n' '|' | cut -c1-240)"; }
+
+# stub <name> <behaviour> — write a fake sidecar CLI onto the lane PATH.
+#   honest        : echoes back the model it was pinned to (a truthful runtime)
+#   silent-fallback: ALWAYS answers as one fixed model, whatever the pin (the agy trap)
+#   loud-reject   : exits non-zero on an unknown pin (the codex behaviour)
+#   chatty        : answers with agentic prose instead of the requested token (unparseable verdict)
+#   banner-echo   : prints a session banner that REPEATS the pinned model, then answers as a
+#                   different model — the real shape of `codex exec` stdout (measured 2026-07-30)
+#   listed-substitute: REJECTS an unknown name (so the bogus control says "rejects-bogus") yet
+#                   silently serves a different model for a name that IS in its own catalogue —
+#                   the measured agy shape (`gemini-3.1-pro-high` answered as 3.6 Flash, no error)
+#   alias-name    : answers with the vendor's PRODUCT name carrying the right version but not every
+#                   token of the pin slug — measured: pin `gpt-5.6-sol` → "GPT-5.6 Codex"
+#   absent        : not created at all
+mkstub() {
+  local name="$1" mode="$2" bin="$TMP/bin"
+  mkdir -p "$bin"
+  case "$mode" in
+    absent) rm -f "$bin/$name"; return ;;
+  esac
+  cat > "$bin/$name" <<STUB
+#!/usr/bin/env bash
+mode="$mode"
+pin=""
+prev=""
+for a in "\$@"; do
+  case "\$prev" in -m|--model) pin="\$a" ;; esac
+  prev="\$a"
+done
+case "\$1" in --version) echo "stub 9.9.9"; exit 0 ;; esac
+# Scan ALL arguments for the verdict prompt — it is NOT always last. codex puts the prompt at the
+# end; agy puts it after -p with `--print-timeout 170s` trailing. A first draft read only the last
+# argument, so the agy-shaped call never looked like a verdict request and lane5b failed against a
+# correct script. An honest runtime ANSWERS THE QUESTION ASKED: a one-token request gets one token.
+is_verdict=0
+for a in "\$@"; do case "\$a" in *"PASS or FAIL"*) is_verdict=1 ;; esac; done
+case "\$mode" in
+  loud-reject)
+     case "\$pin" in *nonexistent*|*bogus*) echo "ERROR: model '\$pin' is not supported" >&2; exit 1 ;; esac
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "I am \$pin, by StubCorp."; fi ;;
+  silent-fallback)
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "I am stub-flash-3.6, by StubCorp."; fi ;;
+  alias-name)
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "StubGPT-3.1 Coder"; fi ;;
+  listed-substitute)
+     case "\$pin" in *nonexistent*|*bogus*) echo "ERROR: model '\$pin' is not supported" >&2; exit 1 ;; esac
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "I am stub-flash-3.6, by StubCorp."; fi ;;
+  banner-echo)
+     echo "Reading additional input from stdin... CLI v0.0.0"
+     echo "--------"
+     echo "model: \$pin   workdir: /tmp   approval: never"
+     echo "--------"
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "I am stub-flash-3.6, by StubCorp."; fi ;;
+  chatty)
+     printf 'Summary of Work\n- considered the request\n- the answer is probably PASS\n' ;;
+  honest|*)
+     if [ "\$is_verdict" -eq 1 ]; then echo "PASS"; else echo "I am \$pin, by StubCorp."; fi ;;
+esac
+exit 0
+STUB
+  chmod +x "$bin/$name"
+}
+
+# HERMETIC PATH — system paths only, plus the stub dir. Inheriting $PATH looked harmless and was
+# not: "absent" is simulated by NOT creating a stub, so the real codex/agy further down $PATH were
+# found instead and the lanes fired REAL, billed API calls (measured: a lane run hung past 120s
+# against live runtimes). A test that can reach production is not a test.
+run_cal() { PATH="$TMP/bin:/usr/bin:/bin:/usr/sbin:/sbin" bash "$CAL" --stub-model "stub-pro-3.1" "$@" 2>&1; }
+
+echo "── sidecar-calibrate lanes ──"
+
+# LANE 1 — absent runtime must read as ABSENT, never as a failure of the panel and never as "fine".
+mkstub codex absent; mkstub agy absent
+out="$(run_cal --only codex)"
+case "$out" in
+  *"codex"*ABSENT*) ok "lane1 absent runtime reported ABSENT" ;;
+  *) bad "lane1 absent runtime not reported as ABSENT" "$out" ;;
+esac
+
+# LANE 2 — THE POINT OF THE WHOLE SCRIPT. A runtime that silently answers as a different model must
+# be reported as UNTRUSTED-PIN, not as reachable. "The sidecar ran" and "the model I pinned answered"
+# are different propositions; agy's slug fallback is the measured instance (2026-07-30).
+mkstub agy silent-fallback
+out="$(run_cal --only agy)"
+case "$out" in
+  *UNTRUSTED-PIN*) ok "lane2 silent fallback caught (pinned model did not answer)" ;;
+  *) bad "lane2 silent fallback passed as a healthy sidecar" "$out" ;;
+esac
+
+# LANE 3 — an honest runtime that echoes its pin is PIN-OK.
+mkstub agy honest
+out="$(run_cal --only agy)"
+case "$out" in
+  *PIN-OK*) ok "lane3 honest runtime reported PIN-OK" ;;
+  *) bad "lane3 honest runtime not reported PIN-OK" "$out" ;;
+esac
+
+# LANE 4 — the negative control must actually control. A runtime that ACCEPTS a bogus model pin has
+# no server-side validation, so "it ran without error" proves nothing about which model answered;
+# that must be visible in the report rather than inferred.
+mkstub codex loud-reject
+out="$(run_cal --only codex)"
+case "$out" in
+  *"control: rejects-bogus"*) ok "lane4 bogus-pin control observed (runtime validates pins)" ;;
+  *) bad "lane4 bogus-pin control not reported" "$out" ;;
+esac
+mkstub codex honest      # honest stub answers ANY pin, including a bogus one
+out="$(run_cal --only codex)"
+case "$out" in
+  *"control: accepts-bogus"*) ok "lane4b runtime accepting a bogus pin is flagged" ;;
+  *) bad "lane4b runtime accepting a bogus pin was not flagged" "$out" ;;
+esac
+
+# LANE 5 — verdict fitness is MEASURED, not assumed. A runtime that answers a one-token request with
+# agentic prose cannot carry a machine-read verdict. The recorded 2026-07-04 finding said exactly
+# this about agy at 1.0.14; the version has moved since, so the answer must be re-measured, never
+# inherited.
+mkstub agy chatty
+out="$(run_cal --only agy)"
+case "$out" in
+  *VERDICT-UNPARSEABLE*) ok "lane5 prose-answering runtime flagged VERDICT-UNPARSEABLE" ;;
+  *) bad "lane5 prose answer accepted as a usable verdict channel" "$out" ;;
+esac
+mkstub agy honest
+out="$(run_cal --only agy)"
+case "$out" in
+  *VERDICT-OK*) ok "lane5b token-answering runtime reported VERDICT-OK" ;;
+  *) bad "lane5b clean token answer not reported VERDICT-OK" "$out" ;;
+esac
+
+# LANE 8 (measured on the first real run) — BANNER ECHO MUST NOT SATISFY THE IDENTITY PROBE.
+# Real CLIs print a session banner before the answer, and that banner repeats the pinned model name
+# back (`codex exec` prints its version and config header). Matching against whole stdout therefore
+# passes any runtime that merely echoes its own configuration — which is precisely the lie this
+# script exists to catch, re-entering through the transport layer instead of the model.
+mkstub agy banner-echo
+out="$(run_cal --only agy)"
+case "$out" in
+  *UNTRUSTED-PIN*) ok "lane8 banner echo rejected (config echo is not a self-report)" ;;
+  *) bad "lane8 banner echoing the pin passed the identity probe" "$out" ;;
+esac
+
+# LANE 10 (measured 2026-07-30) — a vendor product alias carrying the RIGHT VERSION is not a pin
+# failure. Pinning `gpt-5.6-sol` returned "GPT-5.6 Codex": same family, same version, different
+# product suffix. Requiring every token of the pin slug to appear made the calibrator report
+# UNTRUSTED-PIN on a runtime whose pin had actually held — and that runtime also validates pins
+# server-side, so the corroborating evidence was there to read. The version token is the
+# discriminator that matters; the fallback cases (3.1 asked, 3.6 answered) differ exactly there.
+mkstub agy alias-name
+out="$(run_cal --only agy)"
+case "$out" in
+  *PIN-OK*) ok "lane10 product alias with matching version accepted as PIN-OK" ;;
+  *) bad "lane10 matching version rejected because a suffix token was absent" "$out" ;;
+esac
+
+# LANE 9 (measured 2026-07-30) — "rejects unknown names" does NOT imply "serves known names
+# faithfully", and the gap between them is where the real trap lives. agy rejects a nonsense model
+# yet silently substituted Flash for `gemini-3.1-pro-high`, a slug from its OWN catalogue. A control
+# that only probes nonsense therefore returns reassuring evidence about the wrong question: the
+# identity probe must still decide, and the report must not let `rejects-bogus` read as "pin safe".
+mkstub agy listed-substitute
+out="$(run_cal --only agy)"
+case "$out" in
+  *"control: rejects-bogus"*UNTRUSTED-PIN*|*UNTRUSTED-PIN*"control: rejects-bogus"*)
+      ok "lane9 validates unknown names yet substitutes a known one → still UNTRUSTED-PIN" ;;
+  *) bad "lane9 pin substitution masked by a passing bogus-control" "$out" ;;
+esac
+
+# LANE 6 — panel verdict. With no usable different-family sidecar the script must say so explicitly:
+# this is the line a marker's `crossfamily:` leg quotes, and the 2026-07-30 defect was asserting
+# "cross-family unavailable" without ever probing.
+mkstub codex absent; mkstub agy absent
+out="$(run_cal)"
+case "$out" in
+  *"PANEL: none"*) ok "lane6 empty panel stated explicitly (not silence)" ;;
+  *) bad "lane6 empty panel not stated" "$out" ;;
+esac
+mkstub codex honest
+out="$(run_cal)"
+case "$out" in
+  *"PANEL: "*codex*) ok "lane6b populated panel names the usable runtime" ;;
+  *) bad "lane6b populated panel not named" "$out" ;;
+esac
+
+# LANE 7 — detector, not gate: always exit 0, so a calibration run can never block a caller. The
+# caller reads the verdict; the script does not decide for it.
+mkstub codex absent; mkstub agy absent
+PATH="$TMP/bin:/usr/bin:/bin:/usr/sbin:/sbin" bash "$CAL" >/dev/null 2>&1
+[ $? -eq 0 ] && ok "lane7 exits 0 even with an empty panel (detector, not gate)" \
+             || bad "lane7 non-zero exit on empty panel" "exit=$?"
+
+printf '\nsidecar-calibrate lanes: %d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ] || exit 1
+exit 0

package/templates/settings.SessionStart.snippet.json

@@ -0,0 +1,54 @@
+{
+  "_README": [
+    "SessionStart hook snippet — TRACKED, so it arrives with a clone. Every .claude/settings*.json",
+    "path in this repo is gitignored (confirm with `git check-ignore -v .claude/settings.json`; do",
+    "not cite a line number, they move), so a hook registration cannot itself be tracked. This is the tracked",
+    "SOURCE that install-wizard merges into the user's local settings. Without the merge step the",
+    "hooks do not run — shipping the file is not the same proposition as wiring it.",
+    "",
+    "Two entries, deliberately split by privacy:",
+    "  - fh_node_check.sh   → NO private path. Belongs in .claude/settings.json (project-local).",
+    "  - fh_session_load.sh + fh_env_delta_scan.sh → carry BE_DIR (an operator-private companion",
+    "    store path), so they belong ONLY in .claude/settings.local.json, and only for Mode D users.",
+    "",
+    "Merge, do not overwrite: preserve any SessionStart entries the user already has; replace only",
+    "the FH ones, keyed by script name."
+  ],
+  "project_settings_json": {
+    "hooks": {
+      "SessionStart": [
+        {
+          "matcher": "",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/fh_node_check.sh\"",
+              "timeout": 10
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "settings_local_json_MODE_D_ONLY": {
+    "hooks": {
+      "SessionStart": [
+        {
+          "matcher": "",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "BE_DIR=\"<absolute path to your companion store>\" bash \"$CLAUDE_PROJECT_DIR/scripts/fh_session_load.sh\"",
+              "timeout": 20
+            },
+            {
+              "type": "command",
+              "command": "BE_DIR=\"<absolute path to your companion store>\" bash \"$CLAUDE_PROJECT_DIR/scripts/fh_env_delta_scan.sh\"",
+              "timeout": 15
+            }
+          ]
+        }
+      ]
+    }
+  }
+}