dev

#!/usr/bin/env bash
#
# Krasis dev helper — single entry point for build, run, test, benchmark.
#
# Usage:
#   ./dev build                     Rebuild Rust extension into this repo only
#   ./dev build-sidecars            Build Marlin/FlashAttention package sidecars
#   ./dev verify-sidecars           Verify package sidecar manifest and hashes
#   ./dev sidecar-key               Print Marlin/FlashAttention sidecar bundle key
#   ./dev pack-sidecar-bundle       Pack verified sidecars into target/sidecars/bundles
#   ./dev restore-sidecar-bundle    Restore sidecars from local/GitHub bundle cache
#   ./dev upload-sidecar-bundle     Upload verified sidecar bundle to configured release
#   ./dev run <config>              Launch server from a test config
#   ./dev run <config> --benchmark  Launch with benchmark, then serve
#   ./dev launcher-run <config>     Launch through the primary launcher path
#   ./dev test <config>             Run short model test (benchmark + network tests)
#   ./dev test <config> --thorough  Run thorough model test (stress + benchmark + network + large)
#   ./dev network <port>            Run network tests against a running server
#   ./dev network <port> --large    Include large-prompt tests
#   ./dev benchmark <config>        Run standard benchmark (prefill/decode/round trip) and exit
#   ./dev approved-heatmap-build <config> --out <path>
#                                    Build approved cumulative HCS route heatmap checkpoints and exit
#                                    Add --resume-from <json> to append prompts to an existing artifact
#   ./dev approved-heatmap-eval <config> <heatmap.json>
#                                    Benchmark a config with an approved heatmap artifact
#   ./dev checkpoint-identity-test   Test unified checkpoint/cache/heatmap identity
#   ./dev approved-heatmap-migrate <audit|migrate|verify> [--dry-run]
#                                    Audit/migrate dual-key online heatmaps
#   ./dev speed-test                Run the fixed standard speed benchmark (QCN INT4 HQQ4 k4v4)
#   ./dev perplexity <config>       Run perplexity eval (WikiText-2 by default) and exit
#   ./dev quality-ppl <config>      Measure PPL through a running Rust prefill test endpoint
#   ./dev release-test <model>      Run full release test (launcher matrix + release config matrix, produces report)
#   ./dev release-test-all [target]  Run release test on all supported models sequentially
#                                     If a target name is given (e.g. "rc8"), progress is saved
#                                     to a state file. Re-running with the same target resumes
#                                     from the first non-passed model. Without a target, runs
#                                     all models with no resume capability.
#   ./dev launcher-test             Validate launcher config serialization and server startup parsing
#   ./dev windows-launcher-test     Build and test the native Windows launcher logic
#   ./dev server-test               Test Rust HTTP/template and reference-verdict contracts
#   ./dev manager-test              Test Rust Manager/API and launcher schema contracts
#   ./dev reference-test <config>   Compare against stored non-HF references; HF artifacts require override
#   ./dev reference-test --compare <model>  Comparison matrix; HF artifacts require override
#   ./dev reference-inventory       Inventory stored reference artifacts and classify contract state
#   ./dev witness-inputs <model>    Build stored input_token_ids from fixed prompt-source JSON
#   ./dev witness-model-check <model>  Check expected BF16 GGUF witness model readiness
#   ./dev witness-build             Build the pinned llama-witness validator
#   ./dev witness-gguf-preflight <model>  Preflight BF16 GGUF witness conversion readiness
#   ./dev witness-gguf-convert <model>  Convert local safetensors to BF16 GGUF after preflight
#   ./dev witness-capture <model>   Capture llama-witness JSON from stored input_token_ids
#   ./dev witness-compare <config>  Compare Krasis against llama-witness JSON
#   ./dev hqq-attn-diff <model>     Offline HQQ attention artifact diff against BF16 source
#   ./dev hqq-self-calibrate <config>  Capture self-calibration evidence / candidates only
#   ./dev hqq-gpu-search-probe       Prototype GPU HQQ candidate-search timing/quality
#   ./dev expert-hqq-cache-generate <manifest.json>  Generate KRHQ cache from explicit manifest
#   ./dev tileq-build <subcommand>  Plan/build/verify source-bound KTQ1 expert caches
#   ./dev expert-hqq-trace-compare <trace.json> <spec.json> <metrics.tsv>  Compare diagnostic HQQ trace export offline
#   ./dev capture-box <subcommand>  ARCHIVED HF capture wrapper; requires explicit override
#   ./dev capture-preflight         ARCHIVED HF capture host preflight; requires explicit override
#   ./dev reference-prep <model>    ARCHIVED HF dependency/model prep; requires explicit override
#   ./dev generate-reference <model>  ARCHIVED HF reference capture; requires explicit override
#   ./dev trace-diff <expected> <actual>  Diff two KRASIS_TRACE logs offline
#   ./dev awq-calibrate <config>    Deprecated AWQ calibration command (disabled)
#   ./dev test-kernels [name]       Run CUDA kernel unit tests (or filter by name)
#   ./dev cpu-tail-calibrate <config> [options]
#                                    Optimize/measure CPU-tail under live GPU DMA
#   ./dev chat [args]               Run krasis chat from source
#   ./dev sanity                    Run sanity test prompts against running server
#   ./dev kill                      Kill all krasis processes and free GPU memory
#   ./dev install                   Sync krasis command to ~/.local/bin (uses source)
#   ./dev shell                     Drop into a Python shell bound to this repo
#   ./dev python <args...>          Run arbitrary Python bound to this repo
#   ./dev verify-imports            Verify imports resolve inside this repo
#
# Timing / profiling:
#   Add --timing to any command to enable per-component decode timing.
#   This inserts GPU synchronization barriers between each decode phase and
#   prints a detailed timing breakdown at the end. Adds ~30-50% overhead so
#   do NOT use for speed benchmarks — only for understanding where time goes.
#
#   Examples:
#     ./dev benchmark qcn --timing    Profile decode components
#     ./dev run qcn --timing          Run server with timing enabled
#     ./dev benchmark qcn             Normal speed benchmark (no timing overhead)
#
# Debug tracing:
#   KRASIS_TRACE=1 enables structured decode tracing with zero normal-mode cost.
#   Optional filters:
#     KRASIS_TRACE_STEPS=0-1
#     KRASIS_TRACE_LAYERS=0-3
#     KRASIS_TRACE_COMPONENTS=embedding,gqa,moe,final
#     KRASIS_TRACE_VALUES=8
#     KRASIS_TRACE_ELEMS=2048
#     KRASIS_TRACE_DUMP_DIR=/tmp/krasis-trace
#     KRASIS_TRACE_PY_COMPARE=1  # one first-step compare via built test endpoint during validate
#
# Configs are short names that map to validated configs:
#   qcn         -> tests/qcn-k4v4-hqq4-int4-benchmark.conf
#   dsv4        -> tests/deepseek-v4-flash-0731-hqq8.conf
#   gemma       -> tests/gemma-4-4-a16.conf
#
set -euo pipefail

# ── Environment ──────────────────────────────────────────────────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
infer_repo_home() {
    local path="$1"
    case "$path" in
        /home/*/*)
            local remainder="${path#/home/}"
            local user="${remainder%%/*}"
            [[ -n "$user" ]] && echo "/home/$user"
            ;;
        /Users/*/*)
            local remainder="${path#/Users/}"
            local user="${remainder%%/*}"
            [[ -n "$user" ]] && echo "/Users/$user"
            ;;
        *)
            return 1
            ;;
    esac
}

REFERENCE_CAPTURE_ROOT_SOURCE="home"
if [[ -n "${KRASIS_REFERENCE_CAPTURE_ROOT:-}" ]]; then
    REFERENCE_CAPTURE_ROOT="${KRASIS_REFERENCE_CAPTURE_ROOT}"
    REFERENCE_CAPTURE_ROOT_SOURCE="env"
elif REPO_HOME="$(infer_repo_home "$SCRIPT_DIR")"; then
    REFERENCE_CAPTURE_ROOT="${REPO_HOME}/.krasis"
    REFERENCE_CAPTURE_ROOT_SOURCE="repo_home"
else
    REFERENCE_CAPTURE_ROOT="${HOME}/.krasis"
fi

PYTHON="${KRASIS_DEV_PYTHON:-/home/main/miniconda3/envs/ktransformers/bin/python}"
export PYTHONUNBUFFERED=1
# WSL2: add CUDA driver path so Rust cudarc can find libcuda.so
[[ -d /usr/lib/wsl/lib ]] && export LD_LIBRARY_PATH="/usr/lib/wsl/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
PIP="${KRASIS_DEV_PIP:-/home/main/miniconda3/envs/ktransformers/bin/pip}"
MATURIN="${KRASIS_DEV_MATURIN:-/home/main/.local/bin/maturin}"
SO_FILE="$SCRIPT_DIR/python/krasis/krasis.cpython-311-x86_64-linux-gnu.so"
WHEEL_DIR="$SCRIPT_DIR/target/dev-wheels"
REPO_PYTHONPATH="$SCRIPT_DIR/python"
REPO_LIBPATH="$SCRIPT_DIR/python/krasis.libs"
STANDARD_SPEED_TEST_CONFIG="$SCRIPT_DIR/tests/qcn-k4v4-hqq4-int4-benchmark.conf"
REFERENCE_CAPTURE_MODELS_DIR="${REFERENCE_CAPTURE_ROOT}/models"
REFERENCE_CAPTURE_VENV="${REFERENCE_CAPTURE_ROOT}/reference-capture-venv"
REFERENCE_CAPTURE_READY_JSON="${REFERENCE_CAPTURE_ROOT}/capture-host-ready.json"
REFERENCE_CAPTURE_READY_STAMP="${REFERENCE_CAPTURE_ROOT}/capture-host-ready.stamp"
WITNESS_REPO="${KRASIS_LLAMA_WITNESS_REPO:-$SCRIPT_DIR/../krasis-llama-witness}"
WITNESS_PROFILE_ID="${KRASIS_WITNESS_PROFILE_ID:-llama_witness_first_token}"

RED="\033[0;31m"
GREEN="\033[0;32m"
YELLOW="\033[1;33m"
CYAN="\033[0;36m"
BOLD="\033[1m"
NC="\033[0m"

info()  { echo -e "${CYAN}${BOLD}=>${NC} $*"; }
ok()    { echo -e "${GREEN}${BOLD}OK${NC} $*"; }
warn()  { echo -e "${YELLOW}${BOLD}!!${NC} $*"; }
err()   { echo -e "${RED}${BOLD}ERROR${NC} $*" >&2; exit 1; }

build_timer_start() {
    date +%s
}

build_timer_end() {
    local label="$1"
    local start="$2"
    local status="${3:-0}"
    local end
    end=$(date +%s)
    echo "KRASIS_BUILD_TIMING phase=\"$label\" status=$status duration_s=$((end - start))"
}

require_archived_hf_reference_override() {
    local command="$1"
    if [[ "${KRASIS_ALLOW_ARCHIVED_HF_REFERENCE:-}" != "1" ]]; then
        err "$command is archived. HF/Transformers reference tooling and artifacts are no longer a trusted witness path for Qwen3.5/large-model HQQ work. Use llama-witness for new reference authority. To rerun archived HF tooling for forensic evidence only, set KRASIS_ALLOW_ARCHIVED_HF_REFERENCE=1 and document the reason in krasis-internal."
    fi
    warn "$command is archived; running only because KRASIS_ALLOW_ARCHIVED_HF_REFERENCE=1 is set."
}

build_base_ld_library_path() {
    local current="${LD_LIBRARY_PATH:-}"
    local preferred=""

    # Some container images expose CUDA compat stubs that can override the real
    # host driver and trigger cuda error 803. When both exist, prefer the host
    # driver directories explicitly.
    if [[ -f /usr/lib/x86_64-linux-gnu/libcuda.so.1 ]] && compgen -G "/usr/local/cuda*/compat/libcuda.so*" >/dev/null; then
        preferred="/usr/lib/x86_64-linux-gnu:/lib/x86_64-linux-gnu"
    fi

    if [[ -n "$preferred" ]]; then
        echo "$preferred${current:+:$current}"
    else
        echo "$current"
    fi
}

create_run_dir() {
    local run_type="$1"
    local ts dir counter=1
    mkdir -p "$SCRIPT_DIR/logs"
    ts=$(date +%Y%m%d_%H%M%S)
    dir="$SCRIPT_DIR/logs/${run_type}_${ts}"
    while [[ -e "$dir" ]]; do
        dir="$SCRIPT_DIR/logs/${run_type}_${ts}_$counter"
        counter=$((counter + 1))
    done
    mkdir -p "$dir"
    echo "$dir"
}

# ── Sanity checks ────────────────────────────────────────────────────
[[ -f "$PYTHON" ]] || err "Python not found at $PYTHON
  See DEV.md for environment setup instructions."

[[ -f "$MATURIN" ]] || err "maturin not found at $MATURIN
  Install: pip install maturin"

# ── Config resolver ──────────────────────────────────────────────────
resolve_config() {
    local name="$1"
    case "$name" in
        qcn|QCN)            echo "$SCRIPT_DIR/tests/qcn-k4v4-hqq4-int4-benchmark.conf" ;;
        dsv4|deepseek-v4|deepseek-v4-flash|dsv4-0731|deepseek-v4-0731|deepseek-v4-flash-0731)
                            echo "$SCRIPT_DIR/tests/deepseek-v4-flash-0731-hqq8.conf" ;;
        gemma|Gemma)        echo "$SCRIPT_DIR/tests/gemma-4-4-a16.conf" ;;
        *)
            # Try as a direct path
            if [[ -f "$name" ]]; then
                echo "$name"
            elif [[ -f "$SCRIPT_DIR/testconfigs/$name" ]]; then
                echo "$SCRIPT_DIR/testconfigs/$name"
            elif [[ -f "$SCRIPT_DIR/tests/$name" ]]; then
                echo "$SCRIPT_DIR/tests/$name"
            else
                err "Unknown config: $name
  Available: qcn, dsv4, gemma
  Or pass a path to a .conf file."
            fi
            ;;
    esac
}

resolve_model_name() {
    case "$1" in
        qcn|QCN|qwen3-coder-next|Qwen3-Coder-Next) echo "Qwen3-Coder-Next" ;;
        q122b|Q122B|Qwen3.5-122B-A10B) echo "Qwen3.5-122B-A10B" ;;
        dsv4|deepseek-v4|deepseek-v4-flash|dsv4-0731|deepseek-v4-0731|deepseek-v4-flash-0731) echo "DeepSeek-V4-Flash-0731" ;;
        *) echo "$1" ;;
    esac
}

# No need for conf_to_args — server.py has native --config support

# Extract port from a .conf file
conf_port() {
    local conf="$1"
    grep '^CFG_PORT=' "$conf" | head -1 | cut -d'"' -f2
}

# ── Auto-rebuild check ──────────────────────────────────────────────
needs_rebuild() {
    # If .so doesn't exist, definitely need to build
    [[ ! -f "$SO_FILE" ]] && return 0

    local so_mtime
    so_mtime=$(stat --format="%Y" "$SO_FILE" 2>/dev/null) || return 0

    # Check if any Rust source or Cargo files are newer than the .so
    while IFS= read -r -d '' f; do
        local f_mtime
        f_mtime=$(stat --format="%Y" "$f" 2>/dev/null) || continue
        if [[ "$f_mtime" -gt "$so_mtime" ]]; then
            return 0
        fi
    done < <(find "$SCRIPT_DIR/src" -name "*.rs" -print0 2>/dev/null)

    # Check Cargo.toml and build.rs
    for f in "$SCRIPT_DIR/Cargo.toml" "$SCRIPT_DIR/build.rs"; do
        if [[ -f "$f" ]]; then
            local f_mtime
            f_mtime=$(stat --format="%Y" "$f" 2>/dev/null) || continue
            if [[ "$f_mtime" -gt "$so_mtime" ]]; then
                return 0
            fi
        fi
    done

    return 1
}

auto_rebuild() {
    if needs_rebuild; then
        warn "Rust source is newer than compiled extension. Rebuilding..."
        do_build
    fi
}

run_repo_python() {
    local ld_path
    ld_path="$(build_base_ld_library_path)"
    if [[ -d "$REPO_LIBPATH" ]]; then
        ld_path="$REPO_LIBPATH${ld_path:+:$ld_path}"
    fi
    PYTHONNOUSERSITE=1 PYTHONPATH="$REPO_PYTHONPATH${PYTHONPATH:+:$PYTHONPATH}" LD_LIBRARY_PATH="$ld_path" "$PYTHON" "$@"
}

exec_repo_python() {
    local ld_path
    ld_path="$(build_base_ld_library_path)"
    if [[ -d "$REPO_LIBPATH" ]]; then
        ld_path="$REPO_LIBPATH${ld_path:+:$ld_path}"
    fi
    exec env PYTHONNOUSERSITE=1 PYTHONPATH="$REPO_PYTHONPATH${PYTHONPATH:+:$PYTHONPATH}" LD_LIBRARY_PATH="$ld_path" "$PYTHON" "$@"
}

reference_capture_python_bin() {
    local capture_python="$REFERENCE_CAPTURE_VENV/bin/python"
    if [[ -x "$capture_python" ]]; then
        echo "$capture_python"
    else
        echo "$PYTHON"
    fi
}

run_reference_capture_python() {
    local ld_path python_bin
    python_bin="$(reference_capture_python_bin)"
    ld_path="$(build_base_ld_library_path)"
    if [[ -d "$REPO_LIBPATH" ]]; then
        ld_path="$REPO_LIBPATH${ld_path:+:$ld_path}"
    fi
    PYTHONNOUSERSITE=1 PYTHONPATH="$REPO_PYTHONPATH${PYTHONPATH:+:$PYTHONPATH}" LD_LIBRARY_PATH="$ld_path" "$python_bin" "$@"
}

print_capture_box_env() {
    info "Capture-box environment"
    echo "repo_root=$SCRIPT_DIR"
    echo "repo_home=$1"
    echo "HOME=$HOME"
    echo "PATH=$PATH"
    echo "capture_root=$REFERENCE_CAPTURE_ROOT"
    echo "capture_root_source=$REFERENCE_CAPTURE_ROOT_SOURCE"
    echo "capture_models_dir=$REFERENCE_CAPTURE_MODELS_DIR"
    echo "capture_venv=$REFERENCE_CAPTURE_VENV"
    echo "ready_json=$REFERENCE_CAPTURE_READY_JSON"
    echo "ready_stamp=$REFERENCE_CAPTURE_READY_STAMP"
}

enter_capture_box_env() {
    local repo_home
    repo_home="$(infer_repo_home "$SCRIPT_DIR" || true)"
    [[ -n "$repo_home" ]] || err "Cannot derive a stable user home from repo path $SCRIPT_DIR.
Run from a checkout under /home/<user>/... or /Users/<user>/..., or set KRASIS_REFERENCE_CAPTURE_ROOT explicitly."

    export HOME="$repo_home"
    export PATH="$repo_home/.cargo/bin:$PATH"
    export KRASIS_CAPTURE_BOX_ACTIVE=1
    export KRASIS_CAPTURE_BOX_REPO_HOME="$repo_home"
    export KRASIS_REFERENCE_CAPTURE_ROOT="$repo_home/.krasis"
    export KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE="capture_box"
    REFERENCE_CAPTURE_ROOT="$KRASIS_REFERENCE_CAPTURE_ROOT"
    REFERENCE_CAPTURE_ROOT_SOURCE="$KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE"
    REFERENCE_CAPTURE_MODELS_DIR="${REFERENCE_CAPTURE_ROOT}/models"
    REFERENCE_CAPTURE_VENV="${REFERENCE_CAPTURE_ROOT}/reference-capture-venv"
    REFERENCE_CAPTURE_READY_JSON="${REFERENCE_CAPTURE_ROOT}/capture-host-ready.json"
    REFERENCE_CAPTURE_READY_STAMP="${REFERENCE_CAPTURE_ROOT}/capture-host-ready.stamp"
    export KRASIS_REFERENCE_CAPTURE_MODELS_DIR="$REFERENCE_CAPTURE_MODELS_DIR"
    export KRASIS_REFERENCE_CAPTURE_VENV="$REFERENCE_CAPTURE_VENV"
    export KRASIS_REFERENCE_CAPTURE_READY_JSON="$REFERENCE_CAPTURE_READY_JSON"
    export KRASIS_REFERENCE_CAPTURE_READY_STAMP="$REFERENCE_CAPTURE_READY_STAMP"

    if [[ ! "$SCRIPT_DIR" =~ ^"$repo_home"/ ]]; then
        err "Repo path $SCRIPT_DIR is not inside the enforced capture-box home $repo_home."
    fi
}

verify_repo_imports() {
    local output
    local ld_path
    ld_path="$(build_base_ld_library_path)"
    if [[ -d "$REPO_LIBPATH" ]]; then
        ld_path="$REPO_LIBPATH${ld_path:+:$ld_path}"
    fi
    output=$(PYTHONNOUSERSITE=1 PYTHONPATH="$REPO_PYTHONPATH" LD_LIBRARY_PATH="$ld_path" SCRIPT_DIR="$SCRIPT_DIR" "$PYTHON" - <<'PY'
import importlib
import os
import pathlib
import sys

repo = pathlib.Path(os.environ["SCRIPT_DIR"]).resolve()
pkg = importlib.import_module("krasis")
ext = importlib.import_module("krasis.krasis")
pkg_path = pathlib.Path(pkg.__file__).resolve()
ext_path = pathlib.Path(ext.__file__).resolve()

def inside_repo(path: pathlib.Path) -> bool:
    try:
        path.relative_to(repo)
        return True
    except ValueError:
        return False

print(f"krasis: {pkg_path}")
print(f"krasis.krasis: {ext_path}")
if not inside_repo(pkg_path) or not inside_repo(ext_path):
    sys.exit(1)
PY
) || {
        echo "$output"
        err "Import verification failed: dev runtime is not bound to this repo."
    }
    info "Import origin check:"
    echo "$output"
}

verify_repo_python_imports() {
    local output
    local ld_path
    ld_path="$(build_base_ld_library_path)"
    if [[ -d "$REPO_LIBPATH" ]]; then
        ld_path="$REPO_LIBPATH${ld_path:+:$ld_path}"
    fi
    local python_bin
    python_bin="$(reference_capture_python_bin)"
    output=$(PYTHONNOUSERSITE=1 PYTHONPATH="$REPO_PYTHONPATH" LD_LIBRARY_PATH="$ld_path" SCRIPT_DIR="$SCRIPT_DIR" "$python_bin" - <<'PY'
import importlib
import os
import pathlib
import sys

repo = pathlib.Path(os.environ["SCRIPT_DIR"]).resolve()
pkg = importlib.import_module("krasis")
contract = importlib.import_module("tests.reference_contract")
pkg_path = pathlib.Path(pkg.__file__).resolve()
contract_path = pathlib.Path(contract.__file__).resolve()
capture_path = (repo / "tests" / "generate_reference.py").resolve()

def inside_repo(path: pathlib.Path) -> bool:
    try:
        path.relative_to(repo)
        return True
    except ValueError:
        return False

print(f"krasis: {pkg_path}")
print(f"tests.reference_contract: {contract_path}")
print(f"tests.generate_reference: {capture_path}")
if not capture_path.is_file():
    sys.exit(1)
if not inside_repo(pkg_path) or not inside_repo(contract_path) or not inside_repo(capture_path):
    sys.exit(1)
PY
) || {
        echo "$output"
        err "Python import verification failed: HF capture runtime is not bound to this repo."
    }
    info "Reference capture python: $python_bin"
    info "Python import origin check:"
    echo "$output"
}

# ── GPU cleanup ─────────────────────────────────────────────────────
# Kill any existing krasis processes and wait for GPUs to be fully clear.
# Called before every run/test to prevent OOMs from stale processes.

cleanup_gpu() {
    # Optional args: config file path and explicit selected-GPU override.
    # If provided, only check GPUs listed in the effective selection.
    local conf="${1:-}"
    local selected_gpus="${2:-}"
    if [[ -z "$selected_gpus" && -n "$conf" && -f "$conf" ]]; then
        selected_gpus=$(grep '^CFG_SELECTED_GPUS=' "$conf" 2>/dev/null | head -1 | cut -d'"' -f2 || true)
    fi

    # Find krasis server/stress/benchmark Python processes (but not this script).
    # When a config selects specific GPUs, only kill krasis processes currently
    # using those GPUs so a separate Krasis runtime on another GPU can stay up.
    local pids
    pids=$(pgrep -f 'python.*krasis\.' 2>/dev/null || true)
    if [[ -n "$pids" && -n "$selected_gpus" ]]; then
        local selected_uuids=""
        local gpu_idx gpu_uuid gpu_pci
        while IFS=',' read -r gpu_idx gpu_uuid gpu_pci; do
            gpu_idx="${gpu_idx//[[:space:]]/}"
            gpu_uuid="${gpu_uuid//[[:space:]]/}"
            gpu_pci="${gpu_pci//[[:space:]]/}"
            for sg in $(echo "$selected_gpus" | tr ',' ' '); do
                if [[ "$gpu_idx" == "$sg" || "$gpu_uuid" == "$sg" || "${gpu_pci,,}" == "${sg,,}" ]]; then
                    selected_uuids+="${gpu_uuid}"$'\n'
                fi
            done
        done < <(nvidia-smi --query-gpu=index,uuid,pci.bus_id --format=csv,noheader,nounits 2>/dev/null || true)

        local selected_gpu_pids=""
        local app_pid app_uuid
        while IFS=',' read -r app_pid app_uuid; do
            app_pid="${app_pid//[[:space:]]/}"
            app_uuid="${app_uuid//[[:space:]]/}"
            [[ -z "$app_pid" || -z "$app_uuid" ]] && continue
            if grep -qxF "$app_uuid" <<< "$selected_uuids"; then
                selected_gpu_pids+="${app_pid}"$'\n'
            fi
        done < <(nvidia-smi --query-compute-apps=pid,gpu_uuid --format=csv,noheader,nounits 2>/dev/null || true)

        local filtered_pids=""
        local p
        for p in $pids; do
            if grep -qxF "$p" <<< "$selected_gpu_pids"; then
                filtered_pids+="${p}"$'\n'
            fi
        done
        pids="$filtered_pids"
    fi

    if [[ -n "$pids" ]]; then
        warn "Found existing krasis processes — killing them:"
        for p in $pids; do
            local cmdline
            cmdline=$(ps -p "$p" -o args= 2>/dev/null || echo "unknown")
            warn "  PID $p: $cmdline"
        done

        # SIGTERM first
        for p in $pids; do
            kill -TERM "$p" 2>/dev/null || true
        done

        # Wait up to 10s for graceful exit
        local waited=0
        while [[ $waited -lt 10 ]]; do
            local still_alive=false
            for p in $pids; do
                if kill -0 "$p" 2>/dev/null; then
                    still_alive=true
                    break
                fi
            done
            $still_alive || break
            sleep 1
            waited=$((waited + 1))
        done

        # SIGKILL any survivors
        for p in $pids; do
            if kill -0 "$p" 2>/dev/null; then
                warn "  PID $p still alive after SIGTERM, sending SIGKILL"
                kill -9 "$p" 2>/dev/null || true
            fi
        done

        # Wait for SIGKILL to take effect
        sleep 2
        for p in $pids; do
            wait "$p" 2>/dev/null || true
        done
    fi

    # Now wait for GPU memory to actually be released.
    # CUDA memory isn't freed until the process fully exits.
    if [[ -n "$selected_gpus" ]]; then
        info "Waiting for selected GPUs ($selected_gpus) to clear..."
    else
        info "Waiting for GPU memory to clear..."
    fi
    local gpu_timeout=30
    local gpu_waited=0
    while [[ $gpu_waited -lt $gpu_timeout ]]; do
        local all_clear=true
        while IFS=', ' read -r idx gpu_uuid gpu_pci used gpu_mem_total; do
            # If selected_gpus is set, only check those GPUs
            if [[ -n "$selected_gpus" ]]; then
                local check_this=false
                for sg in $(echo "$selected_gpus" | tr ',' ' '); do
                    [[ "$idx" == "$sg" || "$gpu_uuid" == "$sg" || "${gpu_pci,,}" == "${sg,,}" ]] && check_this=true
                done
                $check_this || continue
            fi
            # Baseline is ~200-300 MiB (desktop compositor). 500 MiB threshold.
            if [[ "$used" -gt 500 ]]; then
                all_clear=false
                break
            fi
        done < <(nvidia-smi --query-gpu=index,uuid,pci.bus_id,memory.used,memory.total --format=csv,noheader,nounits 2>/dev/null)

        if $all_clear; then
            if [[ -n "$selected_gpus" ]]; then
                ok "Selected GPUs ($selected_gpus) clear."
            else
                ok "All GPUs clear."
            fi
            return 0
        fi

        sleep 1
        gpu_waited=$((gpu_waited + 1))
    done

    # If we get here, GPUs didn't clear. Show what's using them.
    warn "GPUs still not clear after ${gpu_timeout}s:"
    nvidia-smi 2>/dev/null || true
    err "Cannot proceed — GPU memory not released. Check for non-krasis processes using the GPU."
}

extract_selected_gpus_arg() {
    local arg
    while [[ $# -gt 0 ]]; do
        arg="$1"
        case "$arg" in
            --selected-gpus=*)
                printf '%s\n' "${arg#--selected-gpus=}"
                return 0
                ;;
            --selected-gpus)
                if [[ $# -lt 2 ]]; then
                    err "--selected-gpus requires a comma-separated GPU list"
                fi
                printf '%s\n' "$2"
                return 0
                ;;
        esac
        shift
    done
    return 0
}

resolve_config_cuda_visible_devices() {
    local conf="$1"
    local selected_gpus
    selected_gpus=$(grep '^CFG_SELECTED_GPUS=' "$conf" 2>/dev/null | head -1 | cut -d'"' -f2 || true)
    [[ -n "$selected_gpus" ]] || return 0

    # Reuse the server's stable-selector contract (indices, UUIDs, PCI IDs,
    # and unique name/memory aliases).  This runs after auto_rebuild and in a
    # short-lived setup process, before the actual evaluator imports CUDA.
    run_repo_python -c \
        'import sys; from krasis.server import _normalize_selected_gpus; print(_normalize_selected_gpus(sys.argv[1], "CFG_SELECTED_GPUS"))' \
        "$selected_gpus"
}

# ── Commands ─────────────────────────────────────────────────────────

read_fla_sidecar_architectures() {
    "$PYTHON" -c \
        'import json, sys; data=json.load(open(sys.argv[1], encoding="utf-8")); print(*data["architectures"], sep="\n")' \
        "$SCRIPT_DIR/python/krasis/fla_sidecar_contract.json"
}

do_build_fla() {
    local phase_start
    phase_start=$(build_timer_start)
    # Cross-compile FLA (Flash Linear Attention) Triton kernels for all
    # target GPU architectures.  The resulting .so files are placed in
    # python/krasis/ so maturin can include them in the wheel.
    local fla_script="$SCRIPT_DIR/src/cuda/fla/compile_kernels.py"
    local fla_src_dir="$SCRIPT_DIR/src/cuda/fla"
    local dest="$SCRIPT_DIR/python/krasis"
    local archs=()
    mapfile -t archs < <(read_fla_sidecar_architectures)
    [[ "${#archs[@]}" -gt 0 ]] || err "FLA sidecar contract has no architectures"

    # Check if recompilation is needed: any .so missing or any source newer?
    local needs_rebuild=false
    for arch in "${archs[@]}"; do
        if [[ ! -f "$dest/libkrasis_fla_sm${arch}.so" ]]; then
            needs_rebuild=true
            break
        fi
    done
    if ! $needs_rebuild; then
        # Check if any Python source in fla/ is newer than the oldest .so
        local oldest_so_mtime
        oldest_so_mtime=$(stat --format="%Y" "$dest"/libkrasis_fla_sm*.so 2>/dev/null | sort -n | head -1)
        if [[ -n "$oldest_so_mtime" ]]; then
            while IFS= read -r pyfile; do
                local py_mtime
                py_mtime=$(stat --format="%Y" "$pyfile" 2>/dev/null) || continue
                if [[ "$py_mtime" -gt "$oldest_so_mtime" ]]; then
                    needs_rebuild=true
                    break
                fi
            done < <(find "$fla_src_dir" -name "*.py" -type f 2>/dev/null)
        fi
    fi

    if ! $needs_rebuild; then
        ok "FLA kernels up to date (skipping)"
        build_timer_end "dev FLA kernels" "$phase_start" 0
        return
    fi

    info "Compiling FLA kernels for GPU architectures: ${archs[*]/#/sm_}..."
    local fla_output="/tmp/fla_build"

    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$fla_script" --output-dir "$fla_output" \
        --arch "${archs[@]}"
    local status=$?
    set -e
    build_timer_end "dev FLA kernels" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "FLA kernel compilation failed"

    mkdir -p "$dest"
    local count=0
    for so in "$fla_output"/libkrasis_fla_sm*.so; do
        [[ -f "$so" ]] || continue
        cp "$so" "$dest/"
        count=$((count + 1))
    done
    ok "FLA kernels: $count architectures compiled"
}

do_build_fla_windows_sources() {
    local phase_start
    phase_start=$(build_timer_start)
    local output_dir="$SCRIPT_DIR/target/windows-fla-sources"
    local archs=()
    mapfile -t archs < <(read_fla_sidecar_architectures)
    [[ "${#archs[@]}" -gt 0 ]] || err "FLA sidecar contract has no architectures"
    info "Generating portable Windows FLA sources for: ${archs[*]/#/sm_}..."
    rm -rf "$output_dir"

    set +e
    KRASIS_DEV_SCRIPT=1 KRASIS_FLA_CROSS_COMPILE=1 KRASIS_FLA_REQUIRE_ALL_ARCHS=1 \
        "$PYTHON" "$SCRIPT_DIR/src/cuda/fla/compile_kernels.py" \
        --output-dir "$output_dir" \
        --target-platform windows \
        --arch "${archs[@]}"
    local status=$?
    set -e
    build_timer_end "dev Windows FLA source generation" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "Windows FLA source generation failed"

    local count=0
    local source
    for source in "$output_dir"/krasis_fla_sm*.cu; do
        [[ -f "$source" ]] || continue
        count=$((count + 1))
    done
    [[ "$count" -eq "${#archs[@]}" ]] || \
        err "Windows FLA source generation produced $count/${#archs[@]} architectures"
    [[ -f "$output_dir/windows-fla-manifest.json" ]] || \
        err "Windows FLA source generation omitted windows-fla-manifest.json"

    local nvcc_bin
    nvcc_bin=$(command -v nvcc 2>/dev/null || true)
    if [[ -z "$nvcc_bin" && -n "${CUDA_HOME:-}" && -x "$CUDA_HOME/bin/nvcc" ]]; then
        nvcc_bin="$CUDA_HOME/bin/nvcc"
    fi
    if [[ -z "$nvcc_bin" && -n "${CUDA_PATH:-}" && -x "$CUDA_PATH/bin/nvcc" ]]; then
        nvcc_bin="$CUDA_PATH/bin/nvcc"
    fi
    if [[ -z "$nvcc_bin" ]]; then
        nvcc_bin=$(find /usr/local -maxdepth 4 -path "*/bin/nvcc" -type f -print -quit 2>/dev/null || true)
    fi
    [[ -n "$nvcc_bin" && -x "$nvcc_bin" ]] || \
        err "nvcc not found after Windows FLA source generation"
    local arch
    for arch in "${archs[@]}"; do
        "$nvcc_bin" \
            -c \
            -std=c++17 \
            -allow-unsupported-compiler \
            -Xcompiler -fPIC \
            "$output_dir/krasis_fla_sm${arch}.cu" \
            -o "$output_dir/krasis_fla_sm${arch}.o" || \
            err "Portable FLA wrapper compile check failed for sm_$arch"
    done
    ok "Windows FLA sources: $count architectures generated"
}

do_build_sidecars() {
    local phase_start
    phase_start=$(build_timer_start)
    info "Building Marlin/FlashAttention sidecars..."
    local args=(build)
    if [[ "${1:-}" == "--force" ]]; then
        args+=(--force)
    fi
    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" "${args[@]}"
    local status=$?
    set -e
    build_timer_end "dev Marlin/FlashAttention sidecars" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "Marlin/FlashAttention sidecar build failed"
}

do_verify_sidecars() {
    local phase_start
    phase_start=$(build_timer_start)
    info "Verifying Marlin/FlashAttention sidecars..."
    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" verify
    local status=$?
    set -e
    build_timer_end "dev sidecar verification" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "Marlin/FlashAttention sidecar verification failed"
}

do_sidecar_key() {
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" bundle-key "$@"
}

do_pack_sidecar_bundle() {
    local phase_start
    phase_start=$(build_timer_start)
    info "Packing Marlin/FlashAttention sidecar bundle..."
    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" pack-bundle
    local status=$?
    set -e
    build_timer_end "dev sidecar bundle pack" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "Marlin/FlashAttention sidecar bundle pack failed"
}

do_restore_sidecar_bundle() {
    local phase_start
    phase_start=$(build_timer_start)
    info "Restoring Marlin/FlashAttention sidecar bundle..."
    local args=(restore-bundle)
    if [[ "${1:-}" == "--github" ]]; then
        args+=(--github)
    fi
    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" "${args[@]}"
    local status=$?
    set -e
    build_timer_end "dev sidecar bundle restore" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || return "$status"
}

do_upload_sidecar_bundle() {
    local phase_start
    phase_start=$(build_timer_start)
    info "Uploading Marlin/FlashAttention sidecar bundle..."
    set +e
    KRASIS_DEV_SCRIPT=1 "$PYTHON" "$SCRIPT_DIR/scripts/build_sidecars.py" upload-bundle
    local status=$?
    set -e
    build_timer_end "dev sidecar bundle upload" "$phase_start" "$status"
    [[ "$status" -eq 0 ]] || err "Marlin/FlashAttention sidecar bundle upload failed"
}

do_build() {
    local build_start
    build_start=$(build_timer_start)
    info "Building Rust extension (repo-local maturin build --release)..."
    export LD_LIBRARY_PATH
    LD_LIBRARY_PATH="$(build_base_ld_library_path)"

    # Compile FLA kernels first so they're in python/krasis/ for maturin
    do_build_fla
    do_build_sidecars
    do_verify_sidecars

    cd "$SCRIPT_DIR"
    mkdir -p "$WHEEL_DIR"
    rm -f "$WHEEL_DIR"/krasis-*.whl
    local maturin_start
    maturin_start=$(build_timer_start)
    set +e
    PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
        "$MATURIN" build --release --skip-auditwheel --out "$WHEEL_DIR" 2>&1
    local maturin_status=$?
    set -e
    build_timer_end "dev maturin build" "$maturin_start" "$maturin_status"
    [[ "$maturin_status" -eq 0 ]] || return "$maturin_status"
    local wheel
    wheel=$(ls -t "$WHEEL_DIR"/krasis-*.whl 2>/dev/null | head -1)
    [[ -n "$wheel" ]] || err "Build succeeded but no wheel was produced in $WHEEL_DIR"
    "$PYTHON" - "$wheel" "$SCRIPT_DIR/python/krasis" "$SCRIPT_DIR/python/krasis.libs" <<'PY'
import pathlib
import shutil
import sys
import zipfile

wheel = pathlib.Path(sys.argv[1])
target = pathlib.Path(sys.argv[2])
lib_target = pathlib.Path(sys.argv[3])
target.mkdir(parents=True, exist_ok=True)
lib_target.mkdir(parents=True, exist_ok=True)
for pattern in ("krasis*.so", "krasis*.pyd", "lib*.so", "*.dylib", "*.dll"):
    for path in target.glob(pattern):
        path.unlink()
for pattern in ("*.so", "*.so.*", "*.dylib", "*.dll"):
    for path in lib_target.glob(pattern):
        path.unlink()
with zipfile.ZipFile(wheel) as zf:
    ext_members = [
        name for name in zf.namelist()
        if name.startswith("krasis/") and name.endswith((".so", ".pyd", ".dll", ".dylib"))
    ]
    lib_members = [
        name for name in zf.namelist()
        if name.startswith("krasis.libs/")
    ]
    if not ext_members:
        raise SystemExit("No compiled artifacts found in wheel")
    for member in ext_members:
        dest = target / pathlib.Path(member).name
        with zf.open(member) as src, open(dest, "wb") as dst:
            shutil.copyfileobj(src, dst)
        print(dest)
    for member in lib_members:
        dest = lib_target / pathlib.Path(member).name
        with zf.open(member) as src, open(dest, "wb") as dst:
            shutil.copyfileobj(src, dst)
        print(dest)
PY
    ok "Build complete. Extension at: $SO_FILE"
    verify_repo_imports
    build_timer_end "dev build total" "$build_start" 0
}

do_run() {
    [[ $# -lt 1 ]] && err "Usage: ./dev run <config> [--benchmark] [--selected-gpus GPU[,GPU...]] [extra args...]"
    local conf
    conf=$(resolve_config "$1")
    shift
    local selected_gpus_override
    selected_gpus_override=$(extract_selected_gpus_arg "$@")
    local run_dir
    run_dir=$(create_run_dir "dev-run")
    cleanup_gpu "$conf" "$selected_gpus_override"
    auto_rebuild
    info "Launching from: $conf"
    if [[ -n "$selected_gpus_override" ]]; then
        info "Selected GPU override: $selected_gpus_override"
    fi
    info "Run dir: $run_dir"
    verify_repo_imports
    export KRASIS_RUN_DIR="$run_dir"
    export KRASIS_RUN_TYPE="dev-run"
    exec_repo_python -m krasis.server --config "$conf" "$@"
}

do_launcher_run() {
    [[ $# -lt 1 ]] && err "Usage: ./dev launcher-run <config> [--benchmark] [extra args...]"
    local conf
    conf=$(resolve_config "$1")
    shift
    local selected_gpus_override
    selected_gpus_override=$(extract_selected_gpus_arg "$@")
    local run_dir
    run_dir=$(create_run_dir "dev-launcher-run")
    cleanup_gpu "$conf" "$selected_gpus_override"
    auto_rebuild
    info "Launching through Krasis launcher from: $conf"
    info "Run dir: $run_dir"
    verify_repo_imports
    export KRASIS_RUN_DIR="$run_dir"
    export KRASIS_RUN_TYPE="dev-launcher-run"
    exec_repo_python -m krasis.launcher --config "$conf" "$@"
}

do_test() {
    [[ $# -lt 1 ]] && err "Usage: ./dev test <config> [--thorough]"
    local conf
    conf=$(resolve_config "$1")
    local thorough=false
    [[ "${2:-}" == "--thorough" ]] && thorough=true
    cleanup_gpu "$conf"
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "dev-test")

    local port
    port=$(conf_port "$conf")
    [[ -z "$port" ]] && port=8012

    info "=== Short Model Test ==="
    info "Config: $conf"
    info "Port: $port"
    info "Run dir: $run_dir"

    # Step 1: Launch server with benchmark
    info "Step 1: Launching server with --benchmark..."
    local logfile
    logfile="$run_dir/test_stdout.log"
    info "Log: $logfile"

    verify_repo_imports
    KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="dev-test" run_repo_python -m krasis.server --config "$conf" --benchmark > >(tee "$logfile") 2>&1 &
    local pid=$!

    # Wait for benchmark to complete AND server to be ready.
    # Must wait for BENCHMARK COMPLETE, not just "Server ready", because
    # the benchmark runs on a separate thread. Sending HTTP requests while
    # the benchmark is still using the GPU causes CUDA_ERROR_ILLEGAL_ADDRESS.
    local ready=false
    local timeout=1200  # 20 minutes for model load + benchmark
    local elapsed=0
    while kill -0 "$pid" 2>/dev/null && [[ $elapsed -lt $timeout ]]; do
        if grep -q "BENCHMARK COMPLETE" "$logfile" 2>/dev/null; then
            ready=true
            break
        fi
        sleep 2
        elapsed=$((elapsed + 2))
    done

    if ! $ready; then
        if kill -0 "$pid" 2>/dev/null; then
            warn "Timed out waiting for server (${timeout}s). Killing..."
            kill -TERM "$pid" 2>/dev/null || true
            sleep 2
            kill -9 "$pid" 2>/dev/null || true
        fi
        err "Server did not start. Check log: $logfile"
    fi

    ok "Server is ready. Benchmark results are in the log."

    # Step 2: Run network multi-prompt tests
    info "Step 2: Running network multi-prompt tests..."
    if $thorough; then
        run_repo_python "$SCRIPT_DIR/tests/test_network.py" --port "$port" --large 2>&1 | tee -a "$logfile"
    else
        run_repo_python "$SCRIPT_DIR/tests/test_network.py" --port "$port" 2>&1 | tee -a "$logfile"
    fi

    local net_result=$?

    # Cleanup: kill the server
    info "Stopping server..."
    kill -TERM "$pid" 2>/dev/null || true
    sleep 2
    kill -9 "$pid" 2>/dev/null || true
    wait "$pid" 2>/dev/null || true

    echo ""
    if [[ $net_result -eq 0 ]]; then
        ok "=== All tests PASSED ==="
    else
        err "Network tests FAILED (exit code $net_result)"
    fi
    info "Full log: $logfile"
}

do_release_test() {
    [[ $# -lt 1 ]] && err "Usage: ./dev release-test <model> [--force-rebuild-cache]
  model = directory name under ~/.krasis/models/
  Example: ./dev release-test Qwen3-Coder-Next"
    local model
    model=$(resolve_model_name "$1")
    shift
    cleanup_gpu
    local run_dir
    run_dir=$(create_run_dir "release-test")
    info "Starting release test for model: $model"
    info "Run dir: $run_dir"
    verify_repo_imports
    if [[ "${KRASIS_SKIP_RELEASE_LAUNCHER_MATRIX:-}" != "1" ]]; then
        run_launcher_matrix_test "$run_dir/launcher-matrix" "release-test-launcher-matrix"
    fi
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="release-test" run_repo_python "$SCRIPT_DIR/tests/release_test.py" "$model" "$@"
}

do_release_test_all() {
    local release_target="${1:-}"
    local MODELS=(
        "Qwen3-Coder-Next"
        "Qwen3.5-35B-A3B"
        "Qwen3.5-122B-A10B"
        "Qwen3-235B-A22B"
    )

    local total=${#MODELS[@]}
    local completed=0
    local skipped=0
    local failed_model=""
    local resuming=false
    local state_file=""
    local start_time
    start_time=$(date +%s)

    # State file for resume support (only when release target is given)
    if [[ -n "$release_target" ]]; then
        local state_dir="$SCRIPT_DIR/logs/release-tests"
        mkdir -p "$state_dir"
        state_file="$state_dir/release-all-${release_target}.state"

        if [[ -f "$state_file" ]]; then
            resuming=true
            # Count previously passed models
            for model in "${MODELS[@]}"; do
                local status
                status=$(grep "^${model}:" "$state_file" 2>/dev/null | cut -d: -f2) || true
                if [[ "$status" == "PASSED" ]]; then
                    skipped=$((skipped + 1))
                    completed=$((completed + 1))
                fi
            done

            if [[ $skipped -eq $total ]]; then
                ok "All models already passed for release target '$release_target'. Nothing to do."
                return 0
            fi

            info "=== Resuming Release Test All: $release_target ==="
            info "Previously passed: $skipped/$total"
        else
            info "=== Release Test All: $release_target ==="
            # Create initial state file
            for model in "${MODELS[@]}"; do
                echo "${model}:PENDING" >> "$state_file"
            done
        fi
    else
        info "=== Release Test All ==="
    fi

    info "Models: ${MODELS[*]}"
    info "Total: $total"

    # Verify all models exist before starting
    for model in "${MODELS[@]}"; do
        local model_dir="$HOME/.krasis/models/$model"
        if [[ ! -d "$model_dir" ]]; then
            local msg="FAILED: Model $model not found at $model_dir. Cannot run release-test-all."
            err "$msg"
        fi
    done

    # Release-test-all runs the launcher matrix once before model work. Each
    # per-model release-test then skips the duplicate preflight.
    local launcher_run_dir
    launcher_run_dir=$(create_run_dir "release-test-all-launcher-matrix")
    run_launcher_matrix_test "$launcher_run_dir" "release-test-all-launcher-matrix"

    if $resuming; then
        info "Resuming release-test-all '$release_target': $skipped/$total already passed, $(( total - skipped )) remaining."
    else
        local target_info=""
        [[ -n "$release_target" ]] && target_info=" ($release_target)"
        info "Starting release-test-all${target_info}: $total models to test."
    fi

    for model in "${MODELS[@]}"; do
        # Skip already-passed models on resume
        if [[ -n "$state_file" && -f "$state_file" ]]; then
            local prev_status
            prev_status=$(grep "^${model}:" "$state_file" 2>/dev/null | cut -d: -f2) || true
            if [[ "$prev_status" == "PASSED" ]]; then
                info "=== Skipping $model (already passed) ==="
                continue
            fi
        fi

        local idx=$((completed + 1))
        info "=== [$idx/$total] Starting: $model ==="

        local model_start
        model_start=$(date +%s)

        # Run release test — cleanup_gpu is called inside do_release_test
        if KRASIS_SKIP_RELEASE_LAUNCHER_MATRIX=1 do_release_test "$model"; then
            completed=$((completed + 1))
            local model_elapsed=$(( $(date +%s) - model_start ))
            local model_mins=$((model_elapsed / 60))
            local model_secs=$((model_elapsed % 60))
            ok "[$completed/$total] PASSED: $model (${model_mins}m ${model_secs}s)"

            # Update state file
            if [[ -n "$state_file" ]]; then
                sed -i "s/^${model}:.*/${model}:PASSED/" "$state_file"
            fi
        else
            failed_model="$model"
            local model_elapsed=$(( $(date +%s) - model_start ))
            local model_mins=$((model_elapsed / 60))
            local model_secs=$((model_elapsed % 60))
            local msg="FAILED: $model (${model_mins}m ${model_secs}s). Stopping. $completed/$total models completed."
            warn "$msg"

            # Update state file
            if [[ -n "$state_file" ]]; then
                sed -i "s/^${model}:.*/${model}:FAILED/" "$state_file"
            fi

            err "Release test failed on $model. Aborting."
        fi
    done

    local configs_elapsed=$(( $(date +%s) - start_time ))
    local configs_mins=$((configs_elapsed / 60))
    local configs_secs=$((configs_elapsed % 60))
    local target_suffix=""
    [[ -n "$release_target" ]] && target_suffix=" ($release_target)"
    local configs_msg="All configs passed: $completed/$total models in ${configs_mins}m ${configs_secs}s. Starting perplexity phase.${target_suffix}"
    ok "$configs_msg"

    # ── Perplexity phase: one INT4/HQQ8/k6v6 pass per model ──────────────
    info "=== Perplexity Phase: INT4/HQQ8/k6v6 for all models ==="

    local ppl_passed=0
    local ppl_failed=0
    local best_gpu_idx
    best_gpu_idx=$(nvidia-smi --query-gpu=index,memory.total --format=csv,noheader,nounits | sort -t',' -k2 -nr | head -1 | cut -d',' -f1 | tr -d ' ')

    for model in "${MODELS[@]}"; do
        local model_dir="$HOME/.krasis/models/$model"
        local config_json="$model_dir/config.json"

        if [[ ! -f "$config_json" ]]; then
            warn "No config.json for $model — skipping perplexity"
            ppl_failed=$((ppl_failed + 1))
            continue
        fi

        # Get num_layers from model config
        local num_layers
        num_layers=$("$PYTHON" -c "
import json, sys
c = json.load(open('$config_json'))
tc = c.get('text_config', c)
print(tc.get('num_hidden_layers', 0))
") || num_layers=0

        if [[ "$num_layers" -eq 0 ]]; then
            warn "Could not detect num_layers for $model — skipping perplexity"
            ppl_failed=$((ppl_failed + 1))
            continue
        fi

        # Generate temp INT4/HQQ8/k6v6 config
        local ppl_conf
        ppl_conf=$(mktemp /tmp/krasis-ppl-XXXXXX.conf)
        cat > "$ppl_conf" <<PPLCONF
# Perplexity config — INT4/INT4 HQQ8 k6v6 — $model
MODEL_PATH="$model_dir"
CFG_SELECTED_GPUS="$best_gpu_idx"
CFG_PP_PARTITION="$num_layers"
CFG_LAYER_GROUP_SIZE="2"
CFG_KV_DTYPE="k6v6"
CFG_GPU_EXPERT_BITS="4"
CFG_CPU_EXPERT_BITS="4"
CFG_ATTENTION_QUANT="hqq8"
CFG_SHARED_EXPERT_QUANT="int8"
CFG_DENSE_MLP_QUANT="int8"
CFG_LM_HEAD_QUANT="int8"
PPLCONF

        info "=== [PPL] $model (INT4/HQQ8/k6v6) ==="
        local ppl_start
        ppl_start=$(date +%s)

        if do_perplexity "$ppl_conf" --max-tokens 20000; then
            local ppl_elapsed=$(( $(date +%s) - ppl_start ))
            local ppl_mins=$((ppl_elapsed / 60))
            local ppl_secs=$((ppl_elapsed % 60))
            ppl_passed=$((ppl_passed + 1))
            ok "[PPL] PASSED: $model (${ppl_mins}m ${ppl_secs}s)"
        else
            local ppl_elapsed=$(( $(date +%s) - ppl_start ))
            local ppl_mins=$((ppl_elapsed / 60))
            local ppl_secs=$((ppl_elapsed % 60))
            ppl_failed=$((ppl_failed + 1))
            warn "[PPL] FAILED: $model (${ppl_mins}m ${ppl_secs}s)"
        fi

        rm -f "$ppl_conf"
    done

    # ── Final summary ──────────────────────────────────────────────
    local total_elapsed=$(( $(date +%s) - start_time ))
    local total_mins=$((total_elapsed / 60))
    local total_secs=$((total_elapsed % 60))
    local final_msg="COMPLETE: $completed/$total models passed, perplexity $ppl_passed/$total passed, total ${total_mins}m ${total_secs}s.${target_suffix}"
    ok "$final_msg"

    # Clean up state file on full success
    if [[ -n "$state_file" ]]; then
        rm -f "$state_file"
        info "State file removed (all passed)."
    fi
}

do_benchmark() {
    [[ $# -lt 1 ]] && err "Usage: ./dev benchmark <config> [extra server args...]"
    local conf
    conf=$(resolve_config "$1")
    shift
    local selected_gpus_override
    selected_gpus_override=$(extract_selected_gpus_arg "$@")
    cleanup_gpu "$conf" "$selected_gpus_override"
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "dev-benchmark")
    local logfile
    logfile="$run_dir/benchmark_stdout.log"
    info "Running standard benchmark: $conf"
    if [[ -n "$selected_gpus_override" ]]; then
        info "Selected GPU override: $selected_gpus_override"
    fi
    info "Run dir: $run_dir"
    info "Log: $logfile"
    verify_repo_imports
    cd "$SCRIPT_DIR" && KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="dev-benchmark" run_repo_python -m krasis.server --config "$conf" --benchmark-only "$@" 2>&1 | tee "$logfile"
    info "Benchmark log saved: $logfile"
    summarize_dynamic_hcs_from_log "$logfile"
}

summarize_dynamic_hcs_from_log() {
    local logfile="$1"
    [[ -f "$logfile" ]] || return 0

    local summary
    summary=$(perl -ne '
        s/\e\[[0-9;]*m//g;
        if (/Dynamic HCS: hit=([0-9.]+)% .*?request_promotions=(\d+)\/(\d+) budget_skips=(\d+) no_slot=(\d+) copy_failures=(\d+)/) {
            ($hit, $promotions, $limit, $budget_skips, $no_slot, $copy_failures) = ($1, $2, $3, $4, $5, $6);
        }
        END {
            if (defined $hit) {
                print "hit=${hit}% request_promotions=${promotions}/${limit} budget_skips=${budget_skips} no_slot=${no_slot} copy_failures=${copy_failures}\n";
            }
        }
    ' "$logfile")

    if [[ -n "$summary" ]]; then
        info "Final Dynamic HCS summary: $summary"
    fi
}

do_approved_heatmap_build() {
    [[ $# -lt 1 ]] && err "Usage: ./dev approved-heatmap-build <config> --out <path> [--resume-from <path>] [--bootstrap-from <path>] [--residency-refresh-every N] [--prompts <path>] [--decode-tokens N] [--max-prompts N] [--checkpoint-every N]"
    local conf
    conf=$(resolve_config "$1")
    shift

    local out=""
    local prompts=""
    local resume_from=""
    local bootstrap_from=""
    local residency_refresh_every=""
    local decode_tokens=""
    local max_prompts=""
    local checkpoint_every=""
    local passthrough=()
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --out)
                [[ $# -ge 2 ]] || err "--out requires a path"
                out="$2"
                shift 2
                ;;
            --prompts)
                [[ $# -ge 2 ]] || err "--prompts requires a path"
                prompts="$2"
                shift 2
                ;;
            --resume-from)
                [[ $# -ge 2 ]] || err "--resume-from requires a path"
                resume_from="$2"
                shift 2
                ;;
            --bootstrap-from)
                [[ $# -ge 2 ]] || err "--bootstrap-from requires a path"
                bootstrap_from="$2"
                shift 2
                ;;
            --residency-refresh-every)
                [[ $# -ge 2 ]] || err "--residency-refresh-every requires a positive integer"
                residency_refresh_every="$2"
                shift 2
                ;;
            --decode-tokens)
                [[ $# -ge 2 ]] || err "--decode-tokens requires a positive integer"
                decode_tokens="$2"
                shift 2
                ;;
            --max-prompts)
                [[ $# -ge 2 ]] || err "--max-prompts requires an integer"
                max_prompts="$2"
                shift 2
                ;;
            --checkpoint-every)
                [[ $# -ge 2 ]] || err "--checkpoint-every requires an integer"
                checkpoint_every="$2"
                shift 2
                ;;
            *)
                passthrough+=("$1")
                shift
                ;;
        esac
    done
    [[ -n "$out" ]] || err "--out is required"

    cleanup_gpu "$conf"
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "approved-heatmap-build")
    local logfile
    logfile="$run_dir/approved_heatmap_build_stdout.log"
    info "Building approved HCS route heatmap: $conf"
    info "Run dir: $run_dir"
    info "Log: $logfile"
    verify_repo_imports

    local args=("--config" "$conf" "--approved-heatmap-build-out" "$out")
    [[ -z "$prompts" ]] || args+=("--approved-heatmap-prompts" "$prompts")
    [[ -z "$resume_from" ]] || args+=("--approved-heatmap-resume-from" "$resume_from")
    [[ -z "$bootstrap_from" ]] || args+=("--approved-heatmap-bootstrap-from" "$bootstrap_from")
    [[ -z "$residency_refresh_every" ]] || args+=("--approved-heatmap-residency-refresh-every" "$residency_refresh_every")
    [[ -z "$decode_tokens" ]] || args+=("--approved-heatmap-decode-tokens" "$decode_tokens")
    [[ -z "$max_prompts" ]] || args+=("--approved-heatmap-max-prompts" "$max_prompts")
    [[ -z "$checkpoint_every" ]] || args+=("--approved-heatmap-checkpoint-every" "$checkpoint_every")
    args+=("${passthrough[@]}")

    cd "$SCRIPT_DIR" && KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="approved-heatmap-build" run_repo_python -m krasis.server "${args[@]}" 2>&1 | tee "$logfile"
    info "Approved heatmap build log saved: $logfile"
}

do_approved_heatmap_eval() {
    [[ $# -lt 2 ]] && err "Usage: ./dev approved-heatmap-eval <config> <heatmap.json> [extra benchmark args...]"
    local conf
    conf=$(resolve_config "$1")
    local heatmap="$2"
    shift 2
    [[ -f "$heatmap" ]] || err "Heatmap file not found: $heatmap"
    do_benchmark "$conf" --heatmap-path "$heatmap" "$@"
}

do_checkpoint_identity_test() {
    cd "$SCRIPT_DIR"
    KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_checkpoint_identity
    KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_approved_heatmap_auto
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/checkpoint_identity.rs
    PYO3_PYTHON="$PYTHON" \
    LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
    RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
        cargo test --release --lib checkpoint_identity::tests -- --nocapture
}

do_approved_heatmap_migrate() {
    [[ $# -lt 1 ]] && err "Usage: ./dev approved-heatmap-migrate <audit|migrate|verify> [--dry-run]"
    cd "$SCRIPT_DIR"
    KRASIS_DEV_SCRIPT=1 run_repo_python scripts/migrate_approved_heatmap_identities.py "$@"
}

do_speed_test() {
    [[ -f "$STANDARD_SPEED_TEST_CONFIG" ]] || err "Standard speed-test config not found: $STANDARD_SPEED_TEST_CONFIG"
    info "Standard speed benchmark config: $STANDARD_SPEED_TEST_CONFIG"
    do_benchmark "$STANDARD_SPEED_TEST_CONFIG" "$@"
}

do_decode_harness() {
    [[ $# -lt 1 ]] && err "Usage: ./dev decode-harness <config> [extra args...]"
    local conf
    conf=$(resolve_config "$1")
    shift
    cleanup_gpu "$conf"
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "dev-decode-harness")
    local logfile
    logfile="$run_dir/decode_harness_stdout.log"
    info "Running decode harness: $conf"
    info "Run dir: $run_dir"
    info "Log: $logfile"
    verify_repo_imports
    cd "$SCRIPT_DIR" && KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="dev-decode-harness" KRASIS_DEV_SCRIPT="1" run_repo_python "$SCRIPT_DIR/tests/decode_harness.py" --config "$conf" "$@" 2>&1 | tee "$logfile"
    info "Decode harness log saved: $logfile"
}

do_perplexity() {
    [[ $# -lt 1 ]] && err "Usage: ./dev perplexity <config> [--dataset wikitext-2] [--max-tokens N] [--max-windows N] [--vram-report]"
    local conf
    conf=$(resolve_config "$1")
    shift
    local vram_report=false
    local -a ppl_args=()
    while [[ $# -gt 0 ]]; do
        if [[ "$1" == "--vram-report" ]]; then
            vram_report=true
        else
            ppl_args+=("$1")
        fi
        shift
    done
    set -- "${ppl_args[@]}"
    cleanup_gpu "$conf"
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "dev-perplexity")
    local logfile="$run_dir/perplexity_stdout.log"
    local server_log="$run_dir/perplexity_server.log"
    local port
    port=$(conf_port "$conf")
    [[ -n "$port" ]] || port=8012
    info "Running perplexity through the Rust prefill endpoint: $conf"
    info "Run dir: $run_dir"
    info "Log: $logfile"
    info "Server log: $server_log"
    verify_repo_imports
    local cuda_visible_devices
    cuda_visible_devices=$(resolve_config_cuda_visible_devices "$conf") || \
        err "Could not resolve CFG_SELECTED_GPUS for perplexity"
    if [[ -n "$cuda_visible_devices" ]]; then
        info "Perplexity CUDA_VISIBLE_DEVICES=$cuda_visible_devices"
    fi

    # Perplexity must exercise the current production Rust prefill path.  The
    # former direct model.forward() evaluator depended on Python attention and
    # prefill objects that no longer exist.  Start a test-endpoint server as an
    # exact child of this built command, score through its Rust endpoint, then
    # tear down only that child.
    (
        [[ -z "$cuda_visible_devices" ]] || export CUDA_VISIBLE_DEVICES="$cuda_visible_devices"
        cd "$SCRIPT_DIR"
        export KRASIS_RUN_DIR="$run_dir"
        export KRASIS_RUN_TYPE="dev-perplexity-server"
        local -a server_args=(--config "$conf" --test-endpoints)
        if $vram_report; then
            server_args+=(--vram-report)
        fi
        exec_repo_python -m krasis.server "${server_args[@]}"
    ) > >(tee "$server_log") 2>&1 &
    local server_pid=$!

    cleanup_perplexity_server() {
        if kill -0 "$server_pid" 2>/dev/null; then
            kill -TERM "$server_pid" 2>/dev/null || true
            local waited=0
            while kill -0 "$server_pid" 2>/dev/null && [[ $waited -lt 30 ]]; do
                sleep 1
                waited=$((waited + 1))
            done
            if kill -0 "$server_pid" 2>/dev/null; then
                warn "Perplexity server did not exit after SIGTERM; sending SIGKILL"
                kill -KILL "$server_pid" 2>/dev/null || true
            fi
        fi
        wait "$server_pid" 2>/dev/null || true
    }
    trap 'cleanup_perplexity_server; exit 130' INT TERM
    trap 'cleanup_perplexity_server' EXIT

    local ready=false
    local startup_timeout="${KRASIS_PERPLEXITY_STARTUP_TIMEOUT_SEC:-1200}"
    local elapsed=0
    while kill -0 "$server_pid" 2>/dev/null && [[ $elapsed -lt $startup_timeout ]]; do
        if curl -fsS --max-time 2 "http://127.0.0.1:${port}/health" >/dev/null 2>&1; then
            ready=true
            break
        fi
        sleep 2
        elapsed=$((elapsed + 2))
    done
    if ! $ready; then
        cleanup_perplexity_server
        trap - EXIT INT TERM
        if [[ $elapsed -ge $startup_timeout ]]; then
            err "Perplexity server did not become ready within ${startup_timeout}s; see $server_log"
        fi
        err "Perplexity server exited before becoming ready; see $server_log"
    fi
    ok "Rust prefill endpoint ready on port $port"

    set +e
    (
        [[ -z "$cuda_visible_devices" ]] || export CUDA_VISIBLE_DEVICES="$cuda_visible_devices"
        cd "$SCRIPT_DIR"
        KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/rust_prefill_ppl.py" \
            "$conf" --port "$port" "$@"
    ) 2>&1 | tee "$logfile"
    local status=${PIPESTATUS[0]}
    set -e

    cleanup_perplexity_server
    trap - EXIT INT TERM
    info "Perplexity log saved: $logfile"
    return "$status"
}

do_quality_ppl() {
    [[ $# -lt 1 ]] && err "Usage: ./dev quality-ppl <config> [--max-tokens N] [--dataset wikitext-2]"
    local conf
    conf=$(resolve_config "$1")
    shift
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/rust_prefill_ppl.py" "$conf" "$@"
}

do_awq_calibrate() {
    err "AWQ calibration is deprecated and disabled. Use HQQ attention modes (hqq4, hqq6, hqq8, hqq46_auto, hqq68_auto)."
}

do_network() {
    [[ $# -lt 1 ]] && err "Usage: ./dev network <port> [--large] [--quick]"
    local port="$1"
    shift
    exec_repo_python "$SCRIPT_DIR/tests/test_network.py" --port "$port" "$@"
}

do_prefill_decode_compare() {
    [[ $# -lt 1 ]] && err "Usage: ./dev prefill-decode-compare <port> [--prompt TEXT] [--output PATH] [--debug-early] [--prefill-trace-layer N]"
    local port="$1"
    shift
    KRASIS_DEV_SCRIPT=1 exec_repo_python "$SCRIPT_DIR/tests/prefill_decode_compare_live.py" \
        --port "$port" "$@"
}

do_vision_test() {
    [[ $# -lt 2 ]] && err "Usage: ./dev vision-test <port> <image> --prompt TEXT [--expect TEXT ...]"
    local port="$1"
    local image="$2"
    shift 2
    KRASIS_DEV_SCRIPT=1 exec_repo_python "$SCRIPT_DIR/tests/test_vision_live.py" \
        --port "$port" --image "$image" "$@"
}

do_session_cache_test() {
    [[ $# -lt 1 ]] && err "Usage: ./dev session-cache-test <port> [--prompt-chars N] [--vision-uncacheable] [--require-cache-hits]"
    local port="$1"
    shift
    KRASIS_DEV_SCRIPT=1 exec_repo_python "$SCRIPT_DIR/tests/test_session_cache_live.py" \
        --port "$port" "$@"
}

do_session_cache_operations() {
    [[ $# -lt 1 ]] && err "Usage: ./dev session-cache-operations <port>"
    local port="$1"
    shift
    KRASIS_DEV_SCRIPT=1 exec_repo_python "$SCRIPT_DIR/tests/test_session_cache_operations.py" \
        --port "$port" "$@"
}

do_session_cache_benchmark() {
    [[ $# -ne 1 ]] && err "Usage: ./dev session-cache-benchmark <port>"
    local port="$1"
    (
        cd "$SCRIPT_DIR"
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --quiet --bin session-cache-benchmark -- "$port"
    )
}

do_peer_rtt() {
    [[ $# -lt 2 ]] && err "Usage: ./dev peer-rtt <primary-gpu> <peer-gpu> [--message-bytes N] [--warmup N] [--samples N] [--timeout-ms N] [--output PATH]"
    (
        cd "$SCRIPT_DIR"
        KRASIS_BUILD_PEER_RTT_PROBE=1 PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --quiet --bin peer-rtt -- "$@"
    )
}

do_expert_compression_probe() {
    [[ $# -lt 3 ]] && err "Usage: ./dev expert-compression-probe <cache.bin> <config.json> <heatmap.json> [measurement options]"
    (
        cd "$SCRIPT_DIR"
        KRASIS_BUILD_PEER_RTT_PROBE=1 PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --quiet --bin expert-compression-probe -- "$@"
    )
}

do_expert_compression_gpu() {
    [[ $# -lt 2 ]] && err "Usage: ./dev expert-compression-gpu <cache.bin> <config.json> [measurement options]"
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    (
        cd "$SCRIPT_DIR"
        KRASIS_BUILD_EXPERT_CODEC_PROBE=1 \
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --quiet --bin expert-compression-gpu -- "$@"
    )
}

do_expert_compression_build() {
    [[ $# -ne 4 ]] && err "Usage: ./dev expert-compression-build <cache.bin> <config.json> <output.krec> <lane-bytes>"
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    (
        cd "$SCRIPT_DIR"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --quiet --bin expert-compression-build -- "$@"
    )
}

do_test_kernels() {
    info "Running CUDA kernel unit tests..."
    # First ensure test data exists
    local test_data_dir="$SCRIPT_DIR/tests/kernel_test_data"
    if [[ ! -d "$test_data_dir" ]] || [[ -z "$(ls -A "$test_data_dir" 2>/dev/null)" ]]; then
        info "Generating kernel test data..."
        cd "$SCRIPT_DIR" && run_repo_python tests/generate_kernel_test_data.py
    fi

    # PyO3 extension modules need Python library for test linking.
    # Get the python lib dir from the conda env Python.
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    export PYO3_PYTHON="$PYTHON"
    export LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
    # Tell the linker where to find libpython and to link it
    export RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}"
    # Kernel tests must validate the exact repo sidecars paired with the
    # current source and manifest, never whichever wheel happens to be
    # importable by the embedded test interpreter.
    local sidecar_dir="$SCRIPT_DIR/python/krasis"
    [[ -f "$sidecar_dir/libkrasis_marlin.so" ]] \
        || err "Repo Marlin sidecar missing: $sidecar_dir/libkrasis_marlin.so"
    [[ -f "$sidecar_dir/libkrasis_flash_attn.so" ]] \
        || err "Repo FlashAttention sidecar missing: $sidecar_dir/libkrasis_flash_attn.so"
    [[ -f "$sidecar_dir/libkrasis_fla_sm80.so" ]] \
        || err "Repo FLA sm80 sidecar missing: $sidecar_dir/libkrasis_fla_sm80.so"
    [[ -f "$sidecar_dir/libkrasis_fla_sm89.so" ]] \
        || err "Repo FLA sm89 sidecar missing: $sidecar_dir/libkrasis_fla_sm89.so"
    [[ -f "$sidecar_dir/libkrasis_fla_sm90.so" ]] \
        || err "Repo FLA sm90 sidecar missing: $sidecar_dir/libkrasis_fla_sm90.so"
    [[ -f "$sidecar_dir/libkrasis_fla_sm120.so" ]] \
        || err "Repo FLA sm120 sidecar missing: $sidecar_dir/libkrasis_fla_sm120.so"
    [[ -f "$sidecar_dir/sidecar_manifest.json" ]] \
        || err "Repo sidecar manifest missing: $sidecar_dir/sidecar_manifest.json"
    export KRASIS_LIBKRASIS_MARLIN_SO="$sidecar_dir/libkrasis_marlin.so"
    export KRASIS_LIBKRASIS_FLASH_ATTN_SO="$sidecar_dir/libkrasis_flash_attn.so"
    export KRASIS_LIBKRASIS_FLA_SM80_SO="$sidecar_dir/libkrasis_fla_sm80.so"
    export KRASIS_LIBKRASIS_FLA_SM89_SO="$sidecar_dir/libkrasis_fla_sm89.so"
    export KRASIS_LIBKRASIS_FLA_SM90_SO="$sidecar_dir/libkrasis_fla_sm90.so"
    export KRASIS_LIBKRASIS_FLA_SM120_SO="$sidecar_dir/libkrasis_fla_sm120.so"
    export KRASIS_SIDECAR_MANIFEST="$sidecar_dir/sidecar_manifest.json"

    # Build and run kernel tests (lib only, skip other test binaries)
    cd "$SCRIPT_DIR"
    if [[ $# -gt 0 ]]; then
        local filter="kernel_tests::test_$1"
        if [[ "$1" == "expert_hqq" ]]; then
            filter="expert_hqq"
        elif [[ "$1" == "adaptive_cold_drop" ]]; then
            filter="adaptive_cold_drop::tests"
        elif [[ "$1" == "expert_codec" ]]; then
            filter="expert_codec::tests"
        elif [[ "$1" == "expert_sidecar" ]]; then
            filter="expert_sidecar::tests"
        elif [[ "$1" == "tileq" ]]; then
            filter="tileq"
        elif [[ "$1" == "expert_compression_payload" ]]; then
            filter="gpu_decode::dsa_registration_tests::expert_payload_uses_all_four_component_ranges_in_cache_order"
        elif [[ "$1" == "peer_selector_check" ]]; then
            filter="gpu_decode::dsa_registration_tests::peer_selector_check_"
        elif [[ "$1" == "dynamic_peer" ]]; then
            filter="gpu_decode::dsa_registration_tests::dynamic_peer_demand_"
        elif [[ "$1" == "n_peer" ]]; then
            filter="gpu_decode::dsa_registration_tests::n_peer_"
        elif [[ "$1" == "dsa_registration" ]]; then
            filter="dsa_registration_tests"
        elif [[ "$1" == "owner_score_pipeline_matches_cpu_reference_on_cuda" ]]; then
            filter="gpu_decode::dsa_registration_tests::test_owner_score_pipeline_matches_cpu_reference_on_cuda"
        elif [[ "$1" == "dspark" ]]; then
            filter="gpu_decode::dsa_registration_tests::dspark_"
        elif [[ "$1" == "split_expert_launch" ]]; then
            filter="gpu_decode::dsa_registration_tests::split_expert_launch_defaults_on_for_native_dsa_and_honors_overrides"
        elif [[ "$1" == "pcie_batch" ]]; then
            filter="pcie_batch::tests"
        elif [[ "$1" == "route_locality_global_lru" ]]; then
            filter="gpu_decode::dsa_registration_tests::route_locality_global_lru_tracks_cross_layer_capacity"
        elif [[ "$1" == "hqq4_warp_geometry" ]]; then
            filter="gpu_decode::dsa_registration_tests::hqq4_warp_geometry_is_bit_exact"
        elif [[ "$1" == "hqq4_group_cache" ]]; then
            filter="gpu_decode::dsa_registration_tests::hqq4_group_cache_is_bit_exact"
        elif [[ "$1" == "hqq6_quartet_decode" ]]; then
            filter="gpu_decode::dsa_registration_tests::hqq6_quartet_decode_matches_scalar_within_bf16_rounding"
        elif [[ "$1" == "int4_w13_n32" ]]; then
            filter="gpu_decode::dsa_registration_tests::int4_w13_n32_matches_n16_bit_exact"
        elif [[ "$1" == "int4_w2_n32" ]]; then
            filter="gpu_decode::dsa_registration_tests::int4_w2_n32_matches_n16_bit_exact"
        elif [[ "$1" == "hqq_stage_async_copy_mode" ]]; then
            filter="gpu_decode::dsa_registration_tests::hqq_stage_async_copy_mode_is_stage_specific_and_rejects_invalid_values"
        elif [[ "$1" == "shared_w2_reduce" ]]; then
            filter="gpu_decode::dsa_registration_tests::shared_w2_ksplit_reduce_matches_reference"
        elif [[ "$1" == "gpu_route_split_classifier" ]]; then
            filter="gpu_decode::dsa_registration_tests::gpu_route_split_classifier_partitions_weights_exactly"
        elif [[ "$1" == "route_prep_rmsnorm" ]]; then
            filter="gpu_decode::dsa_registration_tests::route_prep_wide_rmsnorm_matches_established_launch"
        elif [[ "$1" == "deepseek_v4_weights" ]]; then
            filter="weights::tests::test_deepseek_v4"
        elif [[ "$1" == "glm53_weights" ]]; then
            filter="weights::tests::test_glm5_next"
        elif [[ "$1" == "glm53_kda" ]]; then
            filter="gpu_prefill::kernel_tests::test_glm53_kda"
        elif [[ "$1" == "glm53_kpool" ]]; then
            filter="gpu_prefill::kernel_tests::test_glm53_kpool"
        elif [[ "$1" == "glm53_dense_clamp" ]]; then
            filter="gpu_decode::dsa_registration_tests::test_glm53_dense_deepseek_clamp"
        elif [[ "$1" == "glm53_mla_k6" ]]; then
            filter="gpu_prefill::kernel_tests::test_native_mla_k6_prefill_and_decode_writers_match_cpu"
        elif [[ "$1" == "glm53_dsa_prefill" ]]; then
            filter="gpu_prefill::kernel_tests::test_mla_prefill_norm_and_race_free_rope_pack"
        elif [[ "$1" == "glm53_dsa_compute_mode" ]]; then
            filter="gpu_prefill::kernel_tests::test_dsa_mla_gathered_compute_mode_parser_is_strict"
        elif [[ "$1" == "glm53_dsa_schedule" ]]; then
            filter="gpu_decode::dsa_registration_tests::owner_and_shared_contracts_are_fail_closed"
        elif [[ "$1" == "glm53_dsa_capacity" ]]; then
            filter="gpu_decode::dsa_registration_tests::compressed_dsa_keeps_logical_and_score_capacities_distinct"
        elif [[ "$1" == "glm53_hcs_tail" ]]; then
            filter="gpu_decode::dynamic_tail_tests"
        elif [[ "$1" == "vram_calibration" ]]; then
            filter="gpu_decode::vram_calibration_tests"
        elif [[ "$1" == "deepseek_v4_math" ]]; then
            filter="deepseek_v4_"
        elif [[ "$1" == "deepseek_v4_grouped_wo_a" ]]; then
            filter="gpu_decode::dsa_registration_tests::deepseek_v4_grouped_wo_a_batched_gemv_matches_individual_within_one_bf16_ulp"
        elif [[ "$1" == "chunk_plan" ]]; then
            filter="gpu_prefill::chunk_plan_tests"
        elif [[ "$1" == "split_dense_scratch" ]]; then
            filter="chunk_plan_tests::shared_intermediate_scratch"
        elif [[ "$1" == "context_window" ]]; then
            filter="server::tests::context_window_accounts_for_prompt_and_requested_output"
        elif [[ "$1" == "cpu_tail" ]]; then
            filter="cpu_tail"
        elif [[ "$1" == "cpu_tail_persistent" ]]; then
            filter="cpu_tail::tests::persistent_transposed_team_matches_rayon_glm_shape_and_tears_down"
        elif [[ "$1" == "cpu_tail_calibrated_admission" ]]; then
            filter="cpu_tail::tests::calibrated_admission_uses_first_measured_positive_win_depth_and_fails_closed"
        elif [[ "$1" == "cpu_tail_bench" ]]; then
            filter="moe::tests::test_cpu_tail_marlin_shape_bench"
        elif [[ "$1" == "marlin_cpu" ]]; then
            filter="kernel::avx2::tests::test_marlin_kernel"
        fi
        info "Filter: $filter"
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib "$filter" -- --nocapture 2>&1
    else
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib kernel_tests -- --nocapture 2>&1
    fi
}

do_glm53_check() {
    info "Checking the Rust/CUDA GLM-5.3 integration without linking a test binary..."
    cd "$SCRIPT_DIR"
    PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
        cargo check --release --lib 2>&1
}

do_cpu_tail_calibrate() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev cpu-tail-calibrate <config> --budget-seconds N --histogram-log PATH [options]"
        echo "Options: --gpu-ordinal N | --gpu-uuid GPU-..., --group-size N, --output PATH,"
        echo "         --histogram-log PATH (repeatable), --baseline-ms-per-token MS,"
        echo "         --isolated-reference-ms MS, --integrated-reference-ms MS,"
        echo "         --two-team --layer-gap-us N, --smoke"
        echo "Standalone Rust calibration only: does not load a model or alter runtime caches."
        return 0
    fi
    [[ $# -ge 1 ]] || err "Usage: ./dev cpu-tail-calibrate <config> --budget-seconds N --histogram-log PATH [options]"
    local config
    config=$(resolve_config "$1")
    shift
    [[ -f "$config" ]] || err "Config not found: $config"
    local run_dir
    run_dir=$(create_run_dir "cpu-tail-calibrate")
    local output="$run_dir/cpu_tail_calibration.json"
    local has_output=false
    local arg
    for arg in "$@"; do
        [[ "$arg" == "--output" ]] && has_output=true
    done
    info "Running standalone Rust CPU-tail calibration"
    info "Config: $config"
    info "Run dir: $run_dir"
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    local output_args=()
    if ! $has_output; then
        output_args=(--output "$output")
    fi
    (
        cd "$SCRIPT_DIR"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin cpu-tail-calibrate -- \
            "$config" "${output_args[@]}" "$@"
    ) 2>&1 | tee "$run_dir/cpu_tail_calibration.log"
    ok "CPU-tail calibration complete"
    if ! $has_output; then
        ok "JSON report: $output"
    fi
}

do_pcie_batch_probe() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev pcie-batch-probe --gpu N --component-bytes N,N,... --cold-experts N,N,... [--warmup N] [--samples N]"
        echo "Standalone Rust probe: compares ordinary pinned H2D calls with CUDA's batched-copy API."
        return 0
    fi
    local run_dir
    run_dir=$(create_run_dir "pcie-batch-probe")
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    info "Running standalone Rust PCIe batch-copy probe"
    info "Run dir: $run_dir"
    (
        cd "$SCRIPT_DIR"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin pcie-batch-probe -- "$@"
    ) 2>&1 | tee "$run_dir/pcie_batch_probe.log"
    ok "PCIe batch-copy probe complete: $run_dir/pcie_batch_probe.log"
}

do_expert_hqq_cache_generate() {
    if [[ $# -ne 1 || "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev expert-hqq-cache-generate <manifest.json>"
        echo "  Generates an expert-HQQ KRHQ cache from an explicit validated manifest."
        echo "  This is a data-generation command only; it does not launch runtime GPU HQQ kernels."
        return 0
    fi
    local manifest="$1"
    [[ -f "$manifest" ]] || err "Manifest not found: $manifest"

    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    export PYO3_PYTHON="$PYTHON"
    export LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
    export RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}"

    cd "$SCRIPT_DIR"
    PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
        cargo run --release --bin expert_hqq_cache_generate -- "$manifest"
}

do_tileq_build() {
    if [[ $# -eq 0 ]]; then
        echo "Usage: ./dev tileq-build <plan|inspect-capture|prepare-corpus|capture-corpus|counterfactual-test|build|verify> [args...]"
        return 0
    fi
    cd "$SCRIPT_DIR"
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/scripts/tileq_build.py" "$@"
}

do_expert_hqq_trace_compare() {
    if [[ $# -lt 3 || $# -gt 5 || "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev expert-hqq-trace-compare <trace_outputs.json> <diagnostic_spec.json> <metrics.tsv> [mismatch_details.tsv [failure_rows.tsv]]"
        echo "  Compares diagnostic expert-HQQ full-buffer trace export against the BF16-path oracle offline."
        echo "  If mismatch_details.tsv is provided, writes exact BF16 mismatch locations and bit patterns."
        echo "  If failure_rows.tsv is provided, compares only those failing activation blocks."
        echo "  This command does not launch runtime GPU kernels or consume model outputs."
        return 0
    fi
    local trace_path="$1"
    local spec_path="$2"
    local metrics_path="$3"
    [[ -f "$trace_path" ]] || err "Trace outputs not found: $trace_path"
    [[ -f "$spec_path" ]] || err "Diagnostic spec not found: $spec_path"

    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    export PYO3_PYTHON="$PYTHON"
    export LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
    export RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}"

    cd "$SCRIPT_DIR"
    if [[ $# -eq 5 ]]; then
        [[ -f "$5" ]] || err "Failure rows TSV not found: $5"
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin expert_hqq_trace_compare -- "$trace_path" "$spec_path" "$metrics_path" "$4" "$5"
    elif [[ $# -eq 4 ]]; then
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin expert_hqq_trace_compare -- "$trace_path" "$spec_path" "$metrics_path" "$4"
    else
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin expert_hqq_trace_compare -- "$trace_path" "$spec_path" "$metrics_path"
    fi
}

do_expert_hqq_row_attribution() {
    if [[ $# -lt 3 || $# -gt 4 || "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev expert-hqq-row-attribution <response.json> <diagnostic_spec.json> <metrics.tsv> [details.json]"
        echo "  Attributes a targeted expert-HQQ exact-row capture against KRHQ/HQQ dequant math offline."
        echo "  This command does not launch runtime GPU kernels or consume model outputs."
        return 0
    fi
    local response_path="$1"
    local spec_path="$2"
    local metrics_path="$3"
    [[ -f "$response_path" ]] || err "Response JSON not found: $response_path"
    [[ -f "$spec_path" ]] || err "Diagnostic spec not found: $spec_path"

    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    export PYO3_PYTHON="$PYTHON"
    export LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
    export RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}"

    cd "$SCRIPT_DIR"
    if [[ $# -eq 4 ]]; then
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin expert_hqq_row_attribution -- "$response_path" "$spec_path" "$metrics_path" "$4"
    else
        PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo run --release --bin expert_hqq_row_attribution -- "$response_path" "$spec_path" "$metrics_path"
    fi
}

do_validate() {
    local config="${1:?Usage: ./dev validate <config> [--no-server] [--l1-only] [--no-logprobs] [--no-prefill]}"
    shift
    local conf_path
    conf_path=$(resolve_config "$config")
    if [[ ! -f "$conf_path" ]]; then
        die "Config not found: $conf_path"
    fi
    do_build
    info "Running model validation: $conf_path"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 exec_repo_python "$SCRIPT_DIR/tests/validate_model.py" "$conf_path" "$@"
}

do_reference_test() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev reference-test <config> [--verbose] [--no-server] [--port PORT]"
        echo "       ./dev reference-test --compare <model> [--verbose]"
        echo "  Runs reference test comparing engine output against stored reference data."
        echo "  Use --no-server to connect to an already-running test-endpoint server."
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev reference-test <config> [--verbose] [--no-server] [--port PORT]
       ./dev reference-test --compare <model> [--verbose]
  Runs reference test comparing engine output against BF16 reference data.
  Produces an HTML report in logs/reference-tests/.
  Single config:  ./dev reference-test qwen35-a4
  Comparison:     ./dev reference-test --compare qcn"

    if [[ "$1" == "--compare" ]]; then
        shift
        [[ $# -lt 1 ]] && err "Usage: ./dev reference-test --compare <model>
  Available models: qcn, q35b, q122b
  Single-config aliases: gemma"
        local model="$1"
        shift
        cleanup_gpu
        auto_rebuild
        local run_dir
        run_dir=$(create_run_dir "reference-test")
        info "Running comparative reference test: $model"
        info "Run dir: $run_dir"
        verify_repo_imports
        KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="reference-test" run_repo_python "$SCRIPT_DIR/tests/reference_test.py" --compare "$model" "$@"
	    else
	        local conf
	        conf=$(resolve_config "$1")
	        shift
	        local selected_gpus_override
	        selected_gpus_override=$(extract_selected_gpus_arg "$@")
	        local -a reference_args=()
	        while [[ $# -gt 0 ]]; do
	            case "$1" in
	                --selected-gpus=*) shift ;;
	                --selected-gpus)
	                    [[ $# -ge 2 ]] || err "--selected-gpus requires a comma-separated GPU list"
	                    shift 2
	                    ;;
	                *) reference_args+=("$1"); shift ;;
	            esac
	        done
	        set -- "${reference_args[@]}"
	        local no_server=false
	        local arg
	        for arg in "$@"; do
	            if [[ "$arg" == "--no-server" ]]; then
	                no_server=true
	                break
	            fi
	        done
	        if [[ "$no_server" == true ]]; then
	            info "Reference test using existing server; skipping GPU cleanup/rebuild"
	        else
	            cleanup_gpu "$conf" "$selected_gpus_override"
	            auto_rebuild
	        fi
	        local run_dir
	        run_dir=$(create_run_dir "reference-test")
        info "Running reference test: $conf"
        info "Run dir: $run_dir"
        verify_repo_imports
        KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="reference-test" \
            KRASIS_REFERENCE_SELECTED_GPUS="$selected_gpus_override" \
            run_repo_python "$SCRIPT_DIR/tests/reference_test.py" "$conf" "$@"
    fi
}

do_reference_inventory() {
    cleanup_gpu
    auto_rebuild
    local run_dir
    run_dir=$(create_run_dir "reference-inventory")
    info "Running reference inventory"
    info "Run dir: $run_dir"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="reference-inventory" run_repo_python "$SCRIPT_DIR/tests/reference_inventory.py" "$@"
}

witness_model_paths() {
    local requested="$1"
    if [[ -d "$requested" ]]; then
        local resolved basename
        resolved=$(realpath "$requested")
        basename=$(basename "$resolved")
        echo "$resolved"
        echo ""
        echo "$HOME/.krasis/witness-gguf/${basename}-bf16.gguf"
        return 0
    fi
    local model="${requested,,}"
    case "$model" in
        qcn|qwen3-coder-next)
            echo "$HOME/.krasis/models/Qwen3-Coder-Next"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/output/Qwen3-Coder-Next/llama_witness_stage3_qcn_expanded.json"
            echo "$HOME/.krasis/witness-gguf/Qwen3-Coder-Next-bf16.gguf"
            ;;
        qwen35|q35b|qwen3.5-35b-a3b)
            echo "$HOME/.krasis/models/Qwen3.5-35B-A3B"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference.json"
            echo "$HOME/.krasis/witness-gguf/Qwen3.5-35B-A3B-bf16.gguf"
            ;;
        qwen36|q36b|qwen3.6-35b-a3b)
            echo "$HOME/.krasis/models/Qwen3.6-35B-A3B"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/Qwen3.6-35B-A3B/qwen36_witness_expanded_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/Qwen3.6-35B-A3B-bf16.gguf"
            ;;
        q122b|qwen122|qwen3.5-122b-a10b)
            echo "$HOME/.krasis/models/Qwen3.5-122B-A10B"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/output/Qwen3.5-122B-A10B/greedy_reference.json"
            echo "$HOME/.krasis/witness-gguf/Qwen3.5-122B-A10B-bf16.gguf"
            ;;
        q235|qwen235|qwen3-235b-a22b)
            echo "$HOME/.krasis/models/Qwen3-235B-A22B"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/output/Qwen3-235B-A22B/greedy_reference.json"
            echo "$HOME/.krasis/witness-gguf/Qwen3-235B-A22B-bf16.gguf"
            ;;
        nemotron-nano|nemotronnano|nano|nvidia-nemotron-3-nano-30b-a3b-bf16)
            echo "$HOME/.krasis/models/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16/nemotron_nano_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16-bf16.gguf"
            ;;
        nemotron-super|nemotronsuper|super|nvidia-nemotron-3-super-120b-a12b-bf16)
            echo "$HOME/.krasis/models/NVIDIA-Nemotron-3-Super-120B-A12B-BF16"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/NVIDIA-Nemotron-3-Super-120B-A12B-BF16/nemotron_super_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/NVIDIA-Nemotron-3-Super-120B-A12B-BF16-bf16.gguf"
            ;;
        step37|step3.7|step3p7|step-3.7-flash|step-3.7-flash-bf16)
            echo "$HOME/.krasis/models/Step-3.7-Flash"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/Step-3.7-Flash/step37_witness_thinking_off_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/Step-3.7-Flash-bf16.gguf"
            ;;
        glm47|glm4.7|glm47-flash|glm4.7-flash|glm-4.7-flash)
            echo "$HOME/.krasis/models/GLM-4.7-Flash"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/GLM-4.7-Flash/glm47_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/GLM-4.7-Flash-bf16.gguf"
            ;;
        glm52|glm5.2|glm-5.2)
            echo "$HOME/.krasis/models/GLM-5.2"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/GLM-5.2/glm52_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/GLM-5.2-bf16.gguf"
            ;;
        glm53|glm5.3|glm-5.3|glm5.3-flash|glm-5.3-flash)
            echo "$HOME/.krasis/models/GLM-5.3-Flash"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/GLM-5.3-Flash/glm53_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/GLM-5.3-Flash-bf16.gguf"
            ;;
        dsv4-preview|deepseek-v4-preview|deepseek-v4-flash-preview)
            echo "$HOME/.krasis/models/deepseek-ai/DeepSeek-V4-Flash"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/DeepSeek-V4-Flash/deepseek_v4_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/DeepSeek-V4-Flash-native-source.gguf"
            ;;
        dsv4|deepseek-v4|deepseek-v4-flash|dsv4-0731|deepseek-v4-0731|deepseek-v4-flash-0731)
            echo "$HOME/.krasis/models/deepseek-ai/DeepSeek-V4-Flash-0731"
            echo "$SCRIPT_DIR/../krasis-internal/reference-outputs/input-sources/DeepSeek-V4-Flash-0731/deepseek_v4_0731_witness_input_tokens.json"
            echo "$HOME/.krasis/witness-gguf/DeepSeek-V4-Flash-0731-native-source.gguf"
            ;;
        *)
            err "Unknown witness model: $model
  Available: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53, dsv4, dsv4-0731, dsv4-preview"
            ;;
    esac
}

is_step_witness_model() {
    case "${1,,}" in
        step37|step3.7|step3p7|step-3.7-flash|step-3.7-flash-bf16)
            return 0
            ;;
        *)
            return 1
            ;;
    esac
}

do_witness_model_check() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-model-check <model> [--hash]"
        echo "  Checks local readiness for BF16 llama-witness capture."
        echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, dsv4, dsv4-0731"
        echo "  --hash computes the GGUF SHA-256 when the expected BF16 file exists."
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-model-check <model> [--hash]"
    local model="$1"
    shift
    local do_hash=0
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --hash)
                do_hash=1
                shift
                ;;
            --help|-h)
                echo "Usage: ./dev witness-model-check <model> [--hash]"
                echo "  Checks local readiness for BF16 llama-witness capture."
                echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52"
                return 0
                ;;
            *)
                err "Unknown witness-model-check argument: $1"
                ;;
        esac
    done

    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local default_reference_json="${paths[1]}"
    local model_gguf="${paths[2]}"
    local status=0

    info "Checking llama-witness model readiness for $model"
    echo "model_dir=$model_dir"
    if [[ -d "$model_dir" ]]; then
        ok "model_dir exists"
        local config_eos_present=false
        if is_step_witness_model "$model" && [[ -f "$model_dir/config.json" ]] \
            && jq -e '(.eos_token_id // .text_config.eos_token_id // empty) | if type == "array" then length > 0 else type == "number" end' "$model_dir/config.json" >/dev/null; then
            config_eos_present=true
        fi
        for required in config.json tokenizer.json tokenizer_config.json generation_config.json; do
            if [[ -f "$model_dir/$required" ]]; then
                stat -c "  $required: %s bytes" "$model_dir/$required"
            elif [[ "$required" == "generation_config.json" && "$config_eos_present" == "true" ]]; then
                echo "  generation_config.json: not present; Step EOS ids are in config.json text_config"
            else
                echo "  MISSING: $required"
                status=1
            fi
        done
    else
        echo "MISSING: model_dir"
        status=1
    fi

    echo "default_input_token_source=$default_reference_json"
    if [[ -f "$default_reference_json" ]]; then
        ok "default input-token source exists"
    else
        echo "MISSING: default input-token source"
        status=1
    fi

    echo "expected_bf16_gguf=$model_gguf"
    if [[ -f "$model_gguf" ]]; then
        stat -c "bf16_gguf_size_bytes=%s" "$model_gguf"
        ok "expected BF16 GGUF exists"
        if [[ "$do_hash" == "1" ]]; then
            sha256sum "$model_gguf"
        fi
    else
        echo "MISSING: expected BF16 GGUF"
        status=1
    fi

    if [[ "${model,,}" == qwen35 || "${model,,}" == q35b || "${model,,}" == qwen3.5-35b-a3b ]]; then
        local q4_path="$HOME/.krasis/models/Qwen3.5-35B-A3B-GGUF/Qwen3.5-35B-A3B-Q4_K_M.gguf"
        if [[ -f "$q4_path" ]]; then
            stat -c "non_authority_q4_gguf=$q4_path (%s bytes)" "$q4_path"
            echo "NOTE: Q4 GGUF is present but is not acceptable as a BF16 witness authority."
        fi
    fi

    if [[ "$status" == "0" ]]; then
        ok "Witness model readiness check passed"
    else
        echo "Witness model readiness check failed"
    fi
    return "$status"
}

do_hqq_attn_diff() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev hqq-attn-diff <model> [--layer N] [--tensor in_proj_qkvz|in_proj_ba|out_proj|fused_qkv|q_proj|k_proj|v_proj|o_proj|cache-audit|source-map-audit|capture-plan|case-row-audit|named-row-divergence] [--output PATH]"
        echo "       [--top-rows N] [--top-groups N] [--sample-cols N]"
        echo "       [--input-row-trace PATH ...] [--input-row-pos N|all] [--case-summary PATH]"
        echo "       [--max-input-rows N]"
        echo "       [--focus-row N] [--focus-group N]"
        echo "       [--candidate-grid-steps N] [--candidate-local-grid-steps N]"
        echo "       [--bf16-trace PATH] [--hqq-trace PATH] [--bf16-summary PATH] [--hqq-summary PATH]"
        echo "  Offline reporting-only HQQ attention artifact diff, attribution, quantizer-choice, activation-aware what-if, decision-summary, and named-row divergence diagnostics."
        echo "  Currently supports qwen35 selected LA/GQA attention diagnostics, qcn/qwen35 cache/source-map audits, capture-plan reporting, and named-row divergence maps."
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev hqq-attn-diff <model> [--layer N] [--tensor in_proj_qkvz|in_proj_ba|out_proj|fused_qkv|q_proj|k_proj|v_proj|o_proj|cache-audit|source-map-audit|capture-plan|case-row-audit|named-row-divergence] [--output PATH]"
    local model="$1"
    shift
    local layer=0
    local tensor="in_proj_qkvz"
    local output=""
    local top_rows=12
    local top_groups=12
    local sample_cols=8
    local input_row_traces=()
    local input_row_pos=36
    local case_summary=""
    local max_input_rows=""
    local focus_row=""
    local focus_group=""
    local candidate_grid_steps=129
    local candidate_local_grid_steps=65
    local bf16_trace=""
    local hqq_trace=""
    local bf16_summary=""
    local hqq_summary=""
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --layer)
                layer="${2:-}"
                [[ -n "$layer" ]] || err "--layer requires a value"
                shift 2
                ;;
            --tensor)
                tensor="${2:-}"
                [[ -n "$tensor" ]] || err "--tensor requires a value"
                shift 2
                ;;
            --output)
                output="${2:-}"
                [[ -n "$output" ]] || err "--output requires a value"
                shift 2
                ;;
            --top-rows)
                top_rows="${2:-}"
                [[ -n "$top_rows" ]] || err "--top-rows requires a value"
                shift 2
                ;;
            --top-groups)
                top_groups="${2:-}"
                [[ -n "$top_groups" ]] || err "--top-groups requires a value"
                shift 2
                ;;
            --sample-cols)
                sample_cols="${2:-}"
                [[ -n "$sample_cols" ]] || err "--sample-cols requires a value"
                shift 2
                ;;
            --input-row-trace)
                [[ -n "${2:-}" ]] || err "--input-row-trace requires a value"
                input_row_traces+=(--input-row-trace "$2")
                shift 2
                ;;
            --input-row-pos)
                input_row_pos="${2:-}"
                [[ -n "$input_row_pos" ]] || err "--input-row-pos requires a value"
                shift 2
                ;;
            --case-summary)
                case_summary="${2:-}"
                [[ -n "$case_summary" ]] || err "--case-summary requires a path"
                shift 2
                ;;
            --max-input-rows)
                max_input_rows="${2:-}"
                [[ -n "$max_input_rows" ]] || err "--max-input-rows requires a value"
                shift 2
                ;;
            --focus-row)
                focus_row="${2:-}"
                [[ -n "$focus_row" ]] || err "--focus-row requires a value"
                shift 2
                ;;
            --focus-group)
                focus_group="${2:-}"
                [[ -n "$focus_group" ]] || err "--focus-group requires a value"
                shift 2
                ;;
            --candidate-grid-steps)
                candidate_grid_steps="${2:-}"
                [[ -n "$candidate_grid_steps" ]] || err "--candidate-grid-steps requires a value"
                shift 2
                ;;
            --candidate-local-grid-steps)
                candidate_local_grid_steps="${2:-}"
                [[ -n "$candidate_local_grid_steps" ]] || err "--candidate-local-grid-steps requires a value"
                shift 2
                ;;
            --bf16-trace)
                bf16_trace="${2:-}"
                [[ -n "$bf16_trace" ]] || err "--bf16-trace requires a value"
                shift 2
                ;;
            --hqq-trace)
                hqq_trace="${2:-}"
                [[ -n "$hqq_trace" ]] || err "--hqq-trace requires a value"
                shift 2
                ;;
            --bf16-summary)
                bf16_summary="${2:-}"
                [[ -n "$bf16_summary" ]] || err "--bf16-summary requires a value"
                shift 2
                ;;
            --hqq-summary)
                hqq_summary="${2:-}"
                [[ -n "$hqq_summary" ]] || err "--hqq-summary requires a value"
                shift 2
                ;;
            --help|-h)
                echo "Usage: ./dev hqq-attn-diff <model> [--layer N] [--tensor in_proj_qkvz|in_proj_ba|out_proj|fused_qkv|q_proj|k_proj|v_proj|o_proj|cache-audit|source-map-audit|capture-plan|case-row-audit|named-row-divergence] [--output PATH]"
                echo "       [--top-rows N] [--top-groups N] [--sample-cols N]"
                echo "       [--input-row-trace PATH ...] [--input-row-pos N|all] [--case-summary PATH]"
                echo "       [--max-input-rows N]"
                echo "       [--focus-row N] [--focus-group N]"
                echo "       [--candidate-grid-steps N] [--candidate-local-grid-steps N]"
                echo "       [--bf16-trace PATH] [--hqq-trace PATH] [--bf16-summary PATH] [--hqq-summary PATH]"
                echo "  Offline reporting-only HQQ attention artifact diff, attribution, quantizer-choice, activation-aware what-if, decision-summary, and named-row divergence diagnostics."
                return 0
                ;;
            *)
                err "Unknown hqq-attn-diff argument: $1"
                ;;
        esac
    done
    case "$tensor" in
        in_proj_qkvz|in_proj_ba|out_proj|fused_qkv|q_proj|k_proj|v_proj|o_proj|cache-audit|source-map-audit|capture-plan|case-row-audit|named-row-divergence) ;;
        *) err "Only selected Qwen3.5 LA/GQA HQQ tensors, cache-audit, source-map-audit, capture-plan, or named-row-divergence are supported today" ;;
    esac
    local model_key="${model,,}"
    case "$model_key" in
        qcn|qwen3-coder-next)
            case "$tensor" in
                cache-audit|source-map-audit|capture-plan|case-row-audit) ;;
                *) err "qcn hqq-attn-diff currently supports audit-only tensors: cache-audit, source-map-audit, capture-plan" ;;
            esac
            ;;
        qwen35|q35b|qwen3.5-35b-a3b) ;;
        *) err "hqq-attn-diff currently supports qcn and qwen35" ;;
    esac
    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local cache_dir
    case "$model_key" in
        qcn|qwen3-coder-next) cache_dir="$HOME/.krasis/cache/Qwen3-Coder-Next/attention_hqq_v5" ;;
        *) cache_dir="$HOME/.krasis/cache/Qwen3.5-35B-A3B/attention_hqq_v5" ;;
    esac
    [[ -d "$model_dir" ]] || err "model dir not found: $model_dir"
    [[ -d "$cache_dir" ]] || err "HQQ cache dir not found: $cache_dir"
    local run_dir
    run_dir=$(create_run_dir "hqq-attn-diff")
    if [[ -z "$output" ]]; then
        output="$run_dir/hqq_attention_diff.json"
    fi
    local tsv="${output%.json}.tsv"
    local input_row_args=()
    if [[ ${#input_row_traces[@]} -gt 0 ]]; then
        input_row_args=("${input_row_traces[@]}" --input-row-pos "$input_row_pos")
        if [[ -n "$case_summary" ]]; then
            input_row_args+=(--case-summary "$case_summary")
        fi
        if [[ -n "$max_input_rows" ]]; then
            input_row_args+=(--max-input-rows "$max_input_rows")
        fi
    fi
    local focus_args=()
    if [[ -n "$focus_row" || -n "$focus_group" ]]; then
        [[ -n "$focus_row" && -n "$focus_group" ]] || err "--focus-row and --focus-group must be supplied together"
        focus_args=(--focus-row "$focus_row" --focus-group "$focus_group")
    fi
    local named_row_args=()
    if [[ "$tensor" == "named-row-divergence" ]]; then
        [[ -n "$bf16_trace" && -n "$hqq_trace" ]] || err "named-row-divergence requires --bf16-trace and --hqq-trace"
        named_row_args=(--bf16-trace "$bf16_trace" --hqq-trace "$hqq_trace")
        if [[ -n "$bf16_summary" ]]; then
            named_row_args+=(--bf16-summary "$bf16_summary")
        fi
        if [[ -n "$hqq_summary" ]]; then
            named_row_args+=(--hqq-summary "$hqq_summary")
        fi
    fi
    info "Running offline HQQ attention diff"
    info "Run dir: $run_dir"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="hqq-attn-diff" run_repo_python \
        "$SCRIPT_DIR/tests/hqq_attention_diff.py" \
        --model-dir "$model_dir" \
        --cache-dir "$cache_dir" \
        --layer "$layer" \
        --tensor "$tensor" \
        --output "$output" \
        --tsv-output "$tsv" \
        --top-rows "$top_rows" \
        --top-groups "$top_groups" \
        --sample-cols "$sample_cols" \
        --candidate-grid-steps "$candidate_grid_steps" \
        --candidate-local-grid-steps "$candidate_local_grid_steps" \
        "${input_row_args[@]}" \
        "${focus_args[@]}" \
        "${named_row_args[@]}"
    ok "Wrote $output"
    ok "Wrote $tsv"
}

do_hqq_self_calibrate() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev hqq-self-calibrate <config> [--profile selfcal_v1] [--duration-seconds N]"
        echo "       [--dataset canonical|c4] [--dataset-path PATH] [--trace-log PATH]"
        echo "       [--output PATH] [--dry-run]"
        echo "       [--positions LIST] [--layers LIST] [--tensors LIST]"
        echo "       [--build-candidates EVIDENCE_JSON] [--top-candidates N]"
        echo "       [--build-int8-exception-candidates TRAIN_EVIDENCE_JSON] [--heldout-evidence HELDOUT_EVIDENCE_JSON]"
        echo "       [--evaluate-refits CANDIDATES_JSON] [--trace-log PATH]"
        echo "       [--max-output-rows N] [--activation-policy all|shared_bf16_hqq_activation|lane_local_only]"
        echo "       [--simulate-sidecars REFIT_EVAL_JSON] [--sidecar-modes exact_bf16,int8_symmetric]"
        echo "       [--write-sidecar-artifact SIDECAR_SIM_JSON] [--sidecar-artifact-mode int8_symmetric|exact_bf16]"
        echo "       [--write-int8-exception-manifest CANDIDATES_JSON]"
        echo "       [--int8-exception-groups LIST] [--int8-exception-top-groups N]"
        echo "       [--int8-exception-max-sidecar-ratio R] [--int8-exception-max-sidecar-bytes N]"
        echo "       [--int8-exception-decode-sidecar-ratio R] [--int8-exception-prefill-sidecar-ratio R]"
        echo "       [--int8-exception-decode-sidecar-bytes N] [--int8-exception-prefill-sidecar-bytes N]"
        echo "       [--write-sidecar-contract-manifest SOURCE_MAP_AUDIT_JSON] [--source-contract-audit SOURCE_MAP_AUDIT_JSON]"
        echo "       [--sidecar-correction-scale SCALE]"
        echo "       [--sidecar-include-entries LIST] [--sidecar-exclude-entries LIST] [--sidecar-entry-scales LIST]"
        echo "       [--write-experimental-cache REFIT_EVAL_JSON] [--variant-name NAME]"
        echo "       [--patch-tensors LIST] [--patch-methods LIST] [--patch-top-groups N]"
        echo "       [--summarize-ablation SPEC_JSON] [--search-sidecar-conflicts SPEC_JSON]"
        echo "  Captures evidence, builds candidates, evaluates refits, or writes an explicit"
        echo "  experimental selfcal_v1 cache/ablation report from a refit-evaluation artifact."
        echo "  Evidence, candidate, refit-evaluation, sidecar-simulation, and sidecar-artifact modes remain non-loadable as HQQ manifests."
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev hqq-self-calibrate <config> [options]"
    local config
    config=$(resolve_config "$1")
    shift
    [[ -f "$config" ]] || err "Config not found: $config"
    local run_dir
    run_dir=$(create_run_dir "hqq-self-calibrate")
    info "Running HQQ self-calibration evidence/candidate tool"
    info "Config: $config"
    info "Run dir: $run_dir"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="hqq-self-calibrate" run_repo_python \
        -m krasis.hqq_self_calibrate \
        --config "$config" \
        "$@"
}

do_hqq_self_calibrate_test() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev hqq-self-calibrate-test"
        echo "  Runs no-GPU checks for HQQ cache profile selection and Phase 2A evidence files."
        return 0
    fi
    [[ $# -eq 0 ]] || err "hqq-self-calibrate-test takes no arguments"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_hqq_cache_profile.py"
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_hqq_self_calibrate.py"
}

do_model_config_test() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev model-config-test"
        echo "  Runs no-GPU model configuration contract tests."
        return 0
    fi
    [[ $# -eq 0 ]] || err "model-config-test takes no arguments"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_model_config.py"
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_deepseek_v4_hqq_contract.py"
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_deepseek_v4_vision.py"
    KRASIS_DEV_SCRIPT=1 run_repo_python "$SCRIPT_DIR/tests/test_startup_calibration.py"
}

do_hqq_gpu_search_probe() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev hqq-gpu-search-probe [--model q122b|q35b|qcn] [--layer N]"
        echo "       [--tensors q_proj,k_proj,o_proj,fused_qkv] [--nbits 4,6,8]"
        echo "       [--global-steps N] [--local-steps N] [--candidate-batch N]"
        echo "       [--backend torch|rust-cuda] [--output PATH]"
        echo "  Diagnostic-only GPU HQQ candidate-search prototype. Does not write cache artifacts."
        echo "  HQQ8 here means integer 8-bit HQQ, not FP8."
        return 0
    fi
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_TYPE="hqq-gpu-search-probe" run_repo_python \
        "$SCRIPT_DIR/tests/hqq_gpu_search_probe.py" "$@"
}

json_escape() {
    local s="$1"
    s=${s//\\/\\\\}
    s=${s//\"/\\\"}
    s=${s//$'\n'/\\n}
    printf '%s' "$s"
}

sum_file_sizes() {
    local total=0
    local f
    for f in "$@"; do
        [[ -f "$f" ]] || continue
        total=$((total + $(stat -c '%s' "$f")))
    done
    echo "$total"
}

do_witness_build() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-build"
        echo "  Configures and builds the pinned llama-witness validator without loading a model."
        return 0
    fi
    [[ $# -eq 0 ]] || err "witness-build takes no arguments"
    [[ -d "$WITNESS_REPO" ]] || err "llama-witness repo not found: $WITNESS_REPO"

    local run_dir
    run_dir=$(create_run_dir "witness-build")
    info "Building pinned llama-witness validator"
    info "Run dir: $run_dir"
    (
        cd "$WITNESS_REPO"
        cmake -S . -B build
        cmake --build build --target llama-witness-validate -j "${WITNESS_BUILD_JOBS:-$(nproc)}"
    ) 2>&1 | tee "$run_dir/witness_build.log"
    ok "llama-witness validator build complete"
}

do_witness_gguf_preflight() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-gguf-preflight <model> [--output PATH] [--outtype bf16] [--converter-dry-run]"
        echo "  Preflights BF16 GGUF witness conversion without starting conversion."
        echo "  Records source files, expected output, resource estimates, converter command, and support gates."
        echo "  --converter-dry-run traverses the converter and tensor mappings without writing output data."
        echo "  A direct local checkpoint directory is accepted for uncatalogued derivatives."
        echo "  Models: qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, dsv4, dsv4-0731"
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-gguf-preflight <model> [--output PATH] [--outtype bf16] [--converter-dry-run]"
    local model="$1"
    shift
    local output_override=""
    local outtype="bf16"
    local converter_dry_run=0
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --output)
                [[ $# -ge 2 ]] || err "--output requires a path"
                output_override="$2"
                shift 2
                ;;
            --outtype)
                [[ $# -ge 2 ]] || err "--outtype requires a value"
                outtype="$2"
                shift 2
                ;;
            --converter-dry-run)
                converter_dry_run=1
                shift
                ;;
            --help|-h)
                echo "Usage: ./dev witness-gguf-preflight <model> [--output PATH] [--outtype bf16] [--converter-dry-run]"
                echo "  Preflights BF16 GGUF witness conversion without starting conversion."
                echo "  --converter-dry-run traverses the converter and tensor mappings without writing output data."
                echo "  Models: qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53, dsv4, dsv4-0731"
                return 0
                ;;
            *)
                err "Unknown witness-gguf-preflight argument: $1"
                ;;
        esac
    done
    [[ "$outtype" == "bf16" ]] || err "Only --outtype bf16 is accepted for witness authority preflight"
    [[ -d "$WITNESS_REPO" ]] || err "llama-witness repo not found: $WITNESS_REPO"

    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local default_reference_json="${paths[1]}"
    local expected_gguf="${paths[2]}"
    [[ -n "$output_override" ]] && expected_gguf="$output_override"
    local model_key="${model,,}"

    local run_dir report
    run_dir=$(create_run_dir "witness-gguf-preflight")
    report="$run_dir/witness_gguf_preflight.json"
    info "Running BF16 GGUF witness conversion preflight"
    info "Run dir: $run_dir"
    info "Report: $report"

    local status=0
    local converter="$WITNESS_REPO/convert_hf_to_gguf.py"
    local config="$model_dir/config.json"
    local tokenizer="$model_dir/tokenizer.json"
    local tokenizer_config="$model_dir/tokenizer_config.json"
    local generation_config="$model_dir/generation_config.json"
    local index_json="$model_dir/model.safetensors.index.json"
    local arch model_type text_model_type transformers_version
    arch=""
    model_type=""
    text_model_type=""
    transformers_version=""

    if [[ -f "$config" ]]; then
        arch=$(jq -r '.architectures[0] // ""' "$config")
        model_type=$(jq -r '.model_type // ""' "$config")
        text_model_type=$(jq -r '.text_config.model_type // ""' "$config")
        transformers_version=$(jq -r '.transformers_version // ""' "$config")
    else
        status=1
    fi

    # A direct model directory is an explicit validation target. Classify it
    # from normalized checkpoint metadata instead of forcing callers to add a
    # model-name alias for every derivative.
    if [[ -d "$model" ]]; then
        case "$model_type:$text_model_type" in
            deepseek_v4:*) model_key="dsv4" ;;
            glm_moe_dsa:*) model_key="glm52" ;;
            glm5_next:glm5_next_text) model_key="glm53" ;;
            step3p7:step3p5) model_key="step37" ;;
            qwen3_moe:*) model_key="q235" ;;
            nemotron_h:*) model_key="nemotron-nano" ;;
            *:qwen3_5_moe_text) model_key="qwen35" ;;
        esac
    fi

    local expected_arch expected_model_type expected_text_model_type
    case "$model_key" in
        glm47|glm4.7|glm47-flash|glm4.7-flash|glm-4.7-flash)
            expected_arch="Glm4MoeLiteForCausalLM"
            expected_model_type="glm4_moe_lite"
            expected_text_model_type=""
            ;;
        glm52|glm5.2|glm-5.2)
            expected_arch="GlmMoeDsaForCausalLM"
            expected_model_type="glm_moe_dsa"
            expected_text_model_type=""
            ;;
        glm53|glm5.3|glm-5.3|glm5.3-flash|glm-5.3-flash)
            expected_arch="Glm5NextForConditionalGeneration"
            expected_model_type="glm5_next"
            expected_text_model_type="glm5_next_text"
            ;;
        dsv4|deepseek-v4|deepseek-v4-flash|dsv4-0731|deepseek-v4-0731|deepseek-v4-flash-0731)
            expected_arch="DeepseekV4ForCausalLM"
            expected_model_type="deepseek_v4"
            expected_text_model_type=""
            ;;
        step37|step3.7|step3p7|step-3.7-flash|step-3.7-flash-bf16)
            expected_arch="Step3p7ForConditionalGeneration"
            expected_model_type="step3p7"
            expected_text_model_type="step3p5"
            ;;
        q235|qwen235|qwen3-235b-a22b)
            expected_arch="Qwen3MoeForCausalLM"
            expected_model_type="qwen3_moe"
            expected_text_model_type=""
            ;;
        nemotron-nano|nemotronnano|nano|nvidia-nemotron-3-nano-30b-a3b-bf16|nemotron-super|nemotronsuper|super|nvidia-nemotron-3-super-120b-a12b-bf16)
            expected_arch="NemotronHForCausalLM"
            expected_model_type="nemotron_h"
            expected_text_model_type=""
            ;;
        *)
            expected_arch="Qwen3_5MoeForConditionalGeneration"
            expected_model_type="qwen3_5_moe"
            expected_text_model_type="qwen3_5_moe_text"
            ;;
    esac
    local config_supported=false
    if [[ "$arch" == "$expected_arch" && "$model_type" == "$expected_model_type" && ( -z "$expected_text_model_type" || "$text_model_type" == "$expected_text_model_type" ) ]]; then
        config_supported=true
    else
        status=1
    fi

    local converter_supported=false gguf_supported=false runtime_supported=false
    case "$model_key" in
        dsv4|deepseek-v4|deepseek-v4-flash|dsv4-0731|deepseek-v4-0731|deepseek-v4-flash-0731)
            local deepseek_converter="$WITNESS_REPO/conversion/deepseek.py"
            if [[ -f "$deepseek_converter" ]] \
                && rg -q 'DeepseekV4ForCausalLM' "$deepseek_converter" \
                && rg -q 'class DeepseekV4Model' "$deepseek_converter" \
                && rg -q 'MODEL_ARCH.DEEPSEEK4' "$deepseek_converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'DEEPSEEK4' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_DEEPSEEK4' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llama_model_deepseek4' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/deepseek4.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        glm47|glm4.7|glm47-flash|glm4.7-flash|glm-4.7-flash)
            if rg -q 'Glm4MoeLiteForCausalLM' "$converter" \
                && rg -q 'class Glm4MoeLiteModel' "$converter" \
                && rg -q 'MODEL_ARCH.DEEPSEEK2' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'DEEPSEEK2' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_DEEPSEEK2' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llm_build_deepseek2' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/deepseek2.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        glm52|glm5.2|glm-5.2)
            if rg -q 'GlmMoeDsaForCausalLM' "$converter" \
                && rg -q 'class GlmMoeDsaModel' "$converter" \
                && rg -q 'MODEL_ARCH.GLM_DSA' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'GLM_DSA' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_GLM_DSA' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'GLM DSA sparse attention is not implemented in this graph' \
                    "$WITNESS_REPO/src/models/deepseek2.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/deepseek2.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        glm53|glm5.3|glm-5.3|glm5.3-flash|glm-5.3-flash)
            local glm53_converter="$WITNESS_REPO/conversion/glm5next.py"
            if [[ -f "$glm53_converter" ]] \
                && rg -q 'Glm5NextForConditionalGeneration' "$glm53_converter" \
                && rg -q 'class Glm5NextModel' "$glm53_converter" \
                && rg -q 'MODEL_ARCH.GLM5NEXT' "$glm53_converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'GLM5NEXT' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_GLM5NEXT' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llama_model_glm5next' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/glm5next.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        step37|step3.7|step3p7|step-3.7-flash|step-3.7-flash-bf16)
            if rg -q 'Step3p5ForCausalLM' "$converter" \
                && rg -q 'MODEL_ARCH.STEP35' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'STEP35' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_STEP35' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llm_build_step35' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/step35-iswa.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        q235|qwen235|qwen3-235b-a22b)
            if rg -q 'Qwen3MoeForCausalLM' "$converter" \
                && rg -q 'MODEL_ARCH.QWEN3MOE' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'QWEN3MOE' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_QWEN3MOE' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llm_build_qwen3moe' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/qwen3moe.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        nemotron-nano|nemotronnano|nano|nvidia-nemotron-3-nano-30b-a3b-bf16|nemotron-super|nemotronsuper|super|nvidia-nemotron-3-super-120b-a12b-bf16)
            if rg -q 'NemotronHForCausalLM' "$converter" \
                && rg -q 'MODEL_ARCH.NEMOTRON_H_MOE' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'NEMOTRON_H_MOE' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_NEMOTRON_H_MOE' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llm_build_nemotron_h' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/nemotron-h.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
        *)
            if rg -q 'Qwen3_5MoeForConditionalGeneration' "$converter" \
                && rg -q 'class Qwen3_5MoeTextModel' "$converter" \
                && rg -q 'MODEL_ARCH.QWEN35MOE' "$converter"; then
                converter_supported=true
            else
                status=1
            fi
            if rg -q 'QWEN35MOE' "$WITNESS_REPO/gguf-py/gguf/constants.py"; then
                gguf_supported=true
            else
                status=1
            fi
            if rg -q 'LLM_ARCH_QWEN35MOE' "$WITNESS_REPO/src/llama-arch.h" \
                && rg -q 'llm_build_qwen35moe' "$WITNESS_REPO/src/llama-model.cpp" \
                && [[ -f "$WITNESS_REPO/src/models/qwen35moe.cpp" ]]; then
                runtime_supported=true
            else
                status=1
            fi
            ;;
    esac

    local required_missing=()
    local required_file
    local config_eos_present=false
    if is_step_witness_model "$model" && [[ -f "$config" ]] \
        && jq -e '(.eos_token_id // .text_config.eos_token_id // empty) | if type == "array" then length > 0 else type == "number" end' "$config" >/dev/null; then
        config_eos_present=true
    fi
    for required_file in "$config" "$tokenizer" "$tokenizer_config" "$generation_config" "$index_json"; do
        if [[ ! -f "$required_file" ]]; then
            if [[ "$required_file" == "$generation_config" && "$config_eos_present" == "true" ]]; then
                :
            else
                required_missing+=("$required_file")
                status=1
            fi
        fi
    done

    local safetensors=()
    local largest_shard_bytes=0
    while IFS= read -r shard; do
        safetensors+=("$shard")
        local shard_bytes
        shard_bytes=$(stat -c '%s' "$shard")
        if [[ "$shard_bytes" -gt "$largest_shard_bytes" ]]; then
            largest_shard_bytes="$shard_bytes"
        fi
    done < <(find "$model_dir" -maxdepth 1 -type f -name '*.safetensors' | sort)
    local shard_count="${#safetensors[@]}"
    [[ "$shard_count" -gt 0 ]] || status=1
    local source_bytes
    source_bytes=$(sum_file_sizes "${safetensors[@]}" "$config" "$tokenizer" "$tokenizer_config" "$generation_config" "$index_json")

    local output_dir output_available_bytes
    output_dir="$(dirname "$expected_gguf")"
    mkdir -p "$output_dir"
    output_available_bytes=$(df -B1 --output=avail "$output_dir" | tail -n 1 | tr -d ' ')
    local ram_available_bytes
    ram_available_bytes=$(awk '/MemAvailable:/ {print $2 * 1024}' /proc/meminfo)

    # The converter is lazy, but its MoE merge waits for all three expert
    # families (down/gate/up) for one layer before stacking the first output.
    # Derive that simultaneous set from checkpoint dimensions. Non-expert
    # conversion may instead hold one source shard and one output copy.
    local hidden_size moe_intermediate_size routed_experts merged_expert_tensor_bytes
    hidden_size=$(jq -r '.hidden_size // .text_config.hidden_size // 0' "$config")
    moe_intermediate_size=$(jq -r '.moe_intermediate_size // .text_config.moe_intermediate_size // 0' "$config")
    routed_experts=$(jq -r '.n_routed_experts // .num_local_experts // .text_config.n_routed_experts // .text_config.num_local_experts // 0' "$config")
    merged_expert_tensor_bytes=0
    if [[ "$routed_experts" -gt 0 ]]; then
        if [[ "$hidden_size" -le 0 || "$moe_intermediate_size" -le 0 ]]; then
            status=1
        else
            merged_expert_tensor_bytes=$((hidden_size * moe_intermediate_size * routed_experts * 2))
        fi
    fi
    local largest_materialized_tensor_bytes
    largest_materialized_tensor_bytes="$largest_shard_bytes"
    if [[ "$merged_expert_tensor_bytes" -gt "$largest_materialized_tensor_bytes" ]]; then
        largest_materialized_tensor_bytes="$merged_expert_tensor_bytes"
    fi

    local nonexpert_peak_bytes expert_merge_peak_bytes
    nonexpert_peak_bytes=$((largest_shard_bytes * 2))
    expert_merge_peak_bytes=$((merged_expert_tensor_bytes * 4 + largest_shard_bytes))

    local disk_required_bytes ram_required_bytes
    disk_required_bytes=$((source_bytes + largest_materialized_tensor_bytes))
    ram_required_bytes="$nonexpert_peak_bytes"
    if [[ "$expert_merge_peak_bytes" -gt "$ram_required_bytes" ]]; then
        ram_required_bytes="$expert_merge_peak_bytes"
    fi
    local disk_sane=false ram_sane=false
    if [[ "$ram_available_bytes" -ge "$ram_required_bytes" ]]; then
        ram_sane=true
    else
        status=1
    fi

    local converter_cmd
    printf -v converter_cmd '%q ' "$PYTHON" "$converter" "$model_dir" --outtype "$outtype" --outfile "$expected_gguf"
    converter_cmd="${converter_cmd% }"

    local converter_dry_run_log=""
    local converter_dry_run_status=-1
    local converter_dry_run_output_bytes=0
    local disk_estimate_rule="source-sized output plus the largest runtime-derived materialized tensor"
    if [[ "$converter_dry_run" == "1" ]]; then
        converter_dry_run_log="$run_dir/converter_dry_run.log"
        info "Running converter dry-run; no GGUF tensor data will be written"
        set +e
        (
            cd "$WITNESS_REPO"
            "$PYTHON" "$converter" "$model_dir" --outtype "$outtype" \
                --outfile "$expected_gguf" --dry-run
        ) 2>&1 | tee "$converter_dry_run_log"
        converter_dry_run_status=${PIPESTATUS[0]}
        set -e
        if [[ "$converter_dry_run_status" != "0" ]]; then
            status=1
        else
            local dry_run_size dry_run_number dry_run_unit dry_run_multiplier
            dry_run_size=$(sed -n 's/.*total_size = \([0-9][0-9.]*[KMGT]\).*/\1/p' "$converter_dry_run_log" | tail -n 1)
            if [[ -z "$dry_run_size" ]]; then
                status=1
            else
                dry_run_number="${dry_run_size%?}"
                dry_run_unit="${dry_run_size: -1}"
                case "$dry_run_unit" in
                    K) dry_run_multiplier=1024 ;;
                    M) dry_run_multiplier=$((1024 * 1024)) ;;
                    G) dry_run_multiplier=$((1024 * 1024 * 1024)) ;;
                    T) dry_run_multiplier=$((1024 * 1024 * 1024 * 1024)) ;;
                    *) dry_run_multiplier=0 ;;
                esac
                converter_dry_run_output_bytes=$(awk \
                    -v number="$dry_run_number" -v multiplier="$dry_run_multiplier" \
                    'BEGIN { printf "%.0f", number * multiplier }')
                if [[ "$converter_dry_run_output_bytes" -le 0 ]]; then
                    status=1
                else
                    disk_required_bytes=$((converter_dry_run_output_bytes + largest_materialized_tensor_bytes))
                    disk_estimate_rule="converter dry-run output size plus the largest runtime-derived materialized tensor"
                fi
            fi
        fi
    fi
    if [[ "$output_available_bytes" -ge "$disk_required_bytes" ]]; then
        disk_sane=true
    else
        status=1
    fi

    {
        printf '{\n'
        printf '  "format": "krasis_witness_gguf_preflight",\n'
        printf '  "format_version": 1,\n'
        printf '  "model": "%s",\n' "$(json_escape "$model")"
        printf '  "outtype": "%s",\n' "$(json_escape "$outtype")"
        printf '  "source_model_path": "%s",\n' "$(json_escape "$model_dir")"
        printf '  "expected_output_path": "%s",\n' "$(json_escape "$expected_gguf")"
        printf '  "default_input_token_source": "%s",\n' "$(json_escape "$default_reference_json")"
        printf '  "converter": {\n'
        printf '    "repo": "%s",\n' "$(json_escape "$WITNESS_REPO")"
        printf '    "script": "%s",\n' "$(json_escape "$converter")"
        printf '    "outtype": "%s",\n' "$(json_escape "$outtype")"
        printf '    "command": "%s"\n' "$(json_escape "$converter_cmd")"
        printf '  },\n'
        printf '  "converter_dry_run": {\n'
        if [[ "$converter_dry_run" == "1" ]]; then
            printf '    "requested": true,\n'
            printf '    "exit_status": %s,\n' "$converter_dry_run_status"
            printf '    "log": "%s",\n' "$(json_escape "$converter_dry_run_log")"
            printf '    "estimated_output_bytes": %s\n' "$converter_dry_run_output_bytes"
        else
            printf '    "requested": false,\n'
            printf '    "exit_status": null,\n'
            printf '    "log": null\n'
        fi
        printf '  },\n'
        printf '  "config": {\n'
        printf '    "architecture": "%s",\n' "$(json_escape "$arch")"
        printf '    "expected_architecture": "%s",\n' "$(json_escape "$expected_arch")"
        printf '    "model_type": "%s",\n' "$(json_escape "$model_type")"
        printf '    "expected_model_type": "%s",\n' "$(json_escape "$expected_model_type")"
        printf '    "text_model_type": "%s",\n' "$(json_escape "$text_model_type")"
        printf '    "expected_text_model_type": "%s",\n' "$(json_escape "$expected_text_model_type")"
        printf '    "transformers_version": "%s"\n' "$(json_escape "$transformers_version")"
        printf '  },\n'
        printf '  "required_files": [\n'
        local first=1
        for required_file in "$config" "$tokenizer" "$tokenizer_config" "$generation_config" "$index_json"; do
            [[ "$first" == "1" ]] || printf ',\n'
            first=0
            if [[ -f "$required_file" ]]; then
                printf '    {"path": "%s", "exists": true, "size_bytes": %s, "sha256": "%s"}' \
                    "$(json_escape "$required_file")" \
                    "$(stat -c '%s' "$required_file")" \
                    "$(sha256sum "$required_file" | awk '{print $1}')"
            elif [[ "$required_file" == "$generation_config" && "$config_eos_present" == "true" ]]; then
                printf '    {"path": "%s", "exists": false, "accepted_missing": true, "reason": "Step EOS ids are provided by config.json text_config.eos_token_id"}' \
                    "$(json_escape "$required_file")"
            else
                printf '    {"path": "%s", "exists": false}' "$(json_escape "$required_file")"
            fi
        done
        printf '\n  ],\n'
        printf '  "safetensors": {\n'
        printf '    "shard_count": %s,\n' "$shard_count"
        printf '    "total_source_bytes": %s\n' "$source_bytes"
        printf '  },\n'
        printf '  "resources": {\n'
        printf '    "disk_available_bytes": %s,\n' "$output_available_bytes"
        printf '    "disk_required_bytes": %s,\n' "$disk_required_bytes"
        printf '    "disk_estimate_rule": "%s",\n' "$(json_escape "$disk_estimate_rule")"
        printf '    "disk_sane": %s,\n' "$disk_sane"
        printf '    "ram_available_bytes": %s,\n' "$ram_available_bytes"
        printf '    "ram_required_bytes": %s,\n' "$ram_required_bytes"
        printf '    "largest_source_shard_bytes": %s,\n' "$largest_shard_bytes"
        printf '    "largest_merged_expert_tensor_bytes": %s,\n' "$merged_expert_tensor_bytes"
        printf '    "largest_materialized_tensor_bytes": %s,\n' "$largest_materialized_tensor_bytes"
        printf '    "nonexpert_peak_bytes": %s,\n' "$nonexpert_peak_bytes"
        printf '    "expert_merge_peak_bytes": %s,\n' "$expert_merge_peak_bytes"
        printf '    "ram_estimate_rule": "maximum of two largest-shard copies or three config-derived BF16 expert families plus one stacked output and one active source shard",\n'
        printf '    "ram_sane": %s\n' "$ram_sane"
        printf '  },\n'
        printf '  "support": {\n'
        printf '    "config_supported": %s,\n' "$config_supported"
        printf '    "converter_supported": %s,\n' "$converter_supported"
        printf '    "gguf_constants_supported": %s,\n' "$gguf_supported"
        printf '    "runtime_supported": %s\n' "$runtime_supported"
        printf '  },\n'
        printf '  "conversion_started": false,\n'
        if [[ "$status" == "0" ]]; then
            printf '  "preflight_status": "pass"\n'
        else
            printf '  "preflight_status": "fail"\n'
        fi
        printf '}\n'
    } > "$report"

    jq '.' "$report"
    if [[ "$status" == "0" ]]; then
        ok "GGUF preflight passed. Conversion was not started."
    else
        echo "GGUF preflight failed. Conversion was not started."
    fi
    return "$status"
}

do_witness_gguf_convert() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-gguf-convert <model> [--output PATH] [--outtype bf16] [--force]"
        echo "  Converts a local safetensors model to BF16 GGUF only after the built preflight gate passes."
        echo "  Writes logs and conversion manifest under logs/witness-gguf-convert_*."
        echo "  Refuses to overwrite an existing expected output unless --force is supplied."
        echo "  A direct local checkpoint directory is accepted for uncatalogued derivatives."
        echo "  Models: qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53, dsv4, dsv4-0731"
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-gguf-convert <model> [--output PATH] [--outtype bf16] [--force]"
    local model="$1"
    shift
    local output_override=""
    local outtype="bf16"
    local force=0
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --output)
                [[ $# -ge 2 ]] || err "--output requires a path"
                output_override="$2"
                shift 2
                ;;
            --outtype)
                [[ $# -ge 2 ]] || err "--outtype requires a value"
                outtype="$2"
                shift 2
                ;;
            --force)
                force=1
                shift
                ;;
            --help|-h)
                echo "Usage: ./dev witness-gguf-convert <model> [--output PATH] [--outtype bf16] [--force]"
                echo "  Converts a local safetensors model to BF16 GGUF only after the built preflight gate passes."
                echo "  Models: qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53, dsv4, dsv4-0731"
                return 0
                ;;
            *)
                err "Unknown witness-gguf-convert argument: $1"
                ;;
        esac
    done
    [[ "$outtype" == "bf16" ]] || err "Only --outtype bf16 is accepted for witness authority conversion"
    [[ -d "$WITNESS_REPO" ]] || err "llama-witness repo not found: $WITNESS_REPO"

    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local expected_gguf="${paths[2]}"
    [[ -n "$output_override" ]] && expected_gguf="$output_override"
    local converter="$WITNESS_REPO/convert_hf_to_gguf.py"
    [[ -f "$converter" ]] || err "converter not found: $converter"

    local run_dir preflight_log convert_log manifest
    run_dir=$(create_run_dir "witness-gguf-convert")
    preflight_log="$run_dir/preflight.log"
    convert_log="$run_dir/converter.log"
    manifest="$run_dir/witness_gguf_conversion.json"
    info "Running BF16 GGUF witness conversion"
    info "Run dir: $run_dir"
    info "Preflight log: $preflight_log"
    info "Converter log: $convert_log"
    info "Manifest: $manifest"

    if [[ -e "$expected_gguf" && "$force" != "1" ]]; then
        {
            printf '{\n'
            printf '  "format": "krasis_witness_gguf_conversion",\n'
            printf '  "format_version": 1,\n'
            printf '  "model": "%s",\n' "$(json_escape "$model")"
            printf '  "source_model_path": "%s",\n' "$(json_escape "$model_dir")"
            printf '  "output_path": "%s",\n' "$(json_escape "$expected_gguf")"
            printf '  "outtype": "%s",\n' "$(json_escape "$outtype")"
            printf '  "conversion_started": false,\n'
            printf '  "exit_status": 1,\n'
            printf '  "failure_reason": "expected output already exists; rerun with --force to overwrite intentionally"\n'
            printf '}\n'
        } > "$manifest"
        err "Expected BF16 GGUF already exists: $expected_gguf
Use --force only if overwriting that witness artifact is intentional."
    fi

    local preflight_status=0
    set +e
    do_witness_gguf_preflight "$model" --output "$expected_gguf" --outtype "$outtype" --converter-dry-run 2>&1 | tee "$preflight_log"
    preflight_status=${PIPESTATUS[0]}
    set -e
    local preflight_report
    preflight_report=$(ls -td "$SCRIPT_DIR"/logs/witness-gguf-preflight_*/witness_gguf_preflight.json 2>/dev/null | head -1 || true)
    [[ -n "$preflight_report" && -f "$preflight_report" ]] || err "Preflight did not produce a report; see $preflight_log"
    if [[ "$preflight_status" != "0" ]]; then
        err "Preflight failed; conversion was not started. See $preflight_report and $preflight_log"
    fi
    jq -e '
      .preflight_status == "pass"
      and .conversion_started == false
      and .support.config_supported == true
      and .support.converter_supported == true
      and .support.gguf_constants_supported == true
      and .support.runtime_supported == true
      and .resources.disk_sane == true
      and .resources.ram_sane == true
    ' "$preflight_report" >/dev/null || err "Preflight report did not pass all support/resource gates: $preflight_report"

    if [[ -e "$expected_gguf" && "$force" != "1" ]]; then
        err "Expected BF16 GGUF appeared after preflight and --force was not supplied: $expected_gguf"
    fi
    if [[ -e "$expected_gguf" && "$force" == "1" ]]; then
        warn "Removing existing output because --force was supplied: $expected_gguf"
        rm -f "$expected_gguf"
    fi
    mkdir -p "$(dirname "$expected_gguf")"

    local converter_cmd start_ts end_ts exit_status
    printf -v converter_cmd '%q ' "$PYTHON" "$converter" "$model_dir" --outtype "$outtype" --outfile "$expected_gguf"
    converter_cmd="${converter_cmd% }"
    start_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
    info "Starting converter:"
    echo "  $converter_cmd"
    set +e
    (
        cd "$WITNESS_REPO"
        "$PYTHON" "$converter" "$model_dir" --outtype "$outtype" --outfile "$expected_gguf"
    ) 2>&1 | tee "$convert_log"
    exit_status=${PIPESTATUS[0]}
    set -e
    end_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ')

    {
        printf '{\n'
        printf '  "format": "krasis_witness_gguf_conversion",\n'
        printf '  "format_version": 1,\n'
        printf '  "model": "%s",\n' "$(json_escape "$model")"
        printf '  "source_model_path": "%s",\n' "$(json_escape "$model_dir")"
        printf '  "output_path": "%s",\n' "$(json_escape "$expected_gguf")"
        printf '  "outtype": "%s",\n' "$(json_escape "$outtype")"
        printf '  "preflight_report": "%s",\n' "$(json_escape "$preflight_report")"
        printf '  "preflight_log": "%s",\n' "$(json_escape "$preflight_log")"
        printf '  "converter_log": "%s",\n' "$(json_escape "$convert_log")"
        printf '  "converter_command": "%s",\n' "$(json_escape "$converter_cmd")"
        printf '  "start_timestamp_utc": "%s",\n' "$start_ts"
        printf '  "end_timestamp_utc": "%s",\n' "$end_ts"
        printf '  "conversion_started": true,\n'
        printf '  "exit_status": %s,\n' "$exit_status"
        if [[ -f "$expected_gguf" ]]; then
            printf '  "output_exists": true,\n'
            printf '  "output_size_bytes": %s\n' "$(stat -c '%s' "$expected_gguf")"
        else
            printf '  "output_exists": false,\n'
            printf '  "output_size_bytes": null\n'
        fi
        printf '}\n'
    } > "$manifest"

    jq '.' "$manifest"
    if [[ "$exit_status" == "0" && -f "$expected_gguf" ]]; then
        ok "GGUF conversion complete: $expected_gguf"
    else
        echo "GGUF conversion failed. See $convert_log and $manifest"
    fi
    return "$exit_status"
}

do_witness_capture() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-capture <model> [--output PATH] [--reference PATH] [--profile ID] [--max-cases N] [validator args...]"
        echo "  Captures llama-witness JSON from stored input_token_ids only."
        echo "  A direct local checkpoint directory is accepted with --reference for its frozen input-token source."
        echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53"
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-capture <model> [--output PATH] [--reference PATH] [--profile ID] [--max-cases N] [validator args...]
  Captures llama-witness JSON from stored input_token_ids only.
  Default profile: $WITNESS_PROFILE_ID"
    local model="$1"
    shift
    local output=""
    local reference_override=""
    local profile="$WITNESS_PROFILE_ID"
    local validator_args=()
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --help|-h)
                echo "Usage: ./dev witness-capture <model> [--output PATH] [--reference PATH] [--profile ID] [--max-cases N] [validator args...]"
                echo "  Captures llama-witness JSON from stored input_token_ids only."
                echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53"
                return 0
                ;;
            --reference)
                [[ $# -ge 2 ]] || err "--reference requires a path"
                reference_override="$2"
                shift 2
                ;;
            --output)
                [[ $# -ge 2 ]] || err "--output requires a path"
                output="$2"
                shift 2
                ;;
            --profile)
                [[ $# -ge 2 ]] || err "--profile requires an id"
                profile="$2"
                shift 2
                ;;
            --max-cases)
                [[ $# -ge 2 ]] || err "--max-cases requires a count"
                validator_args+=(--max-cases "$2")
                shift 2
                ;;
            *)
                validator_args+=("$1")
                shift
                ;;
        esac
    done

    [[ -d "$WITNESS_REPO" ]] || err "llama-witness repo not found: $WITNESS_REPO"
    local script="$WITNESS_REPO/scripts/witness/validate_frozen_reference.sh"
    [[ -x "$script" ]] || err "witness script not executable: $script"

    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local reference_json="${paths[1]}"
    local model_gguf="${paths[2]}"
    [[ -n "$reference_override" ]] && reference_json="$reference_override"
    [[ -d "$model_dir" ]] || err "witness model dir not found: $model_dir"
    [[ -f "$reference_json" ]] || err "input-token source reference not found: $reference_json"

    local run_dir
    run_dir=$(create_run_dir "witness-capture")
    if [[ -z "$output" ]]; then
        local output_model_name
        output_model_name=$(basename "${model%/}")
        output="$run_dir/${output_model_name}_${profile}.json"
    fi
    mkdir -p "$(dirname "$output")"

    info "Running llama-witness capture"
    info "Run dir: $run_dir"
    info "Output: $output"
    (
        cd "$WITNESS_REPO"
        WITNESS_PROFILE_ID="$profile" \
        WITNESS_MAX_NEW_TOKENS="${KRASIS_WITNESS_MAX_NEW_TOKENS:-1}" \
        WITNESS_GENERATED_AT="${KRASIS_WITNESS_GENERATED_AT:-$(date -u '+%Y-%m-%dT%H:%M:%SZ')}" \
            "$script" "$model_dir" "$reference_json" "$model_gguf" \
            --json-output "$output" \
            --capture-only \
            "${validator_args[@]}"
    ) 2>&1 | tee "$run_dir/witness_capture.log"
    ok "Witness capture complete: $output"
}

do_witness_inputs() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-inputs <model> --prompt-source PATH --output PATH [--profile ID] [validator args...]"
        echo "  Tokenizes fixed prompt-source JSON into a stored llama-witness input_token_ids artifact."
        echo "  Qwen3.5 models require proven chat-template enable_thinking=false application."
        echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53"
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-inputs <model> --prompt-source PATH --output PATH [--profile ID] [validator args...]"
    local model="$1"
    shift
    local prompt_source=""
    local output=""
    local profile="$WITNESS_PROFILE_ID"
    local validator_args=()
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --help|-h)
                echo "Usage: ./dev witness-inputs <model> --prompt-source PATH --output PATH [--profile ID] [validator args...]"
                echo "  Tokenizes fixed prompt-source JSON into a stored llama-witness input_token_ids artifact."
                echo "  Qwen3.5 models require proven chat-template enable_thinking=false application."
                echo "  Models: qcn, qwen35, qwen36, q122b, q235, nemotron-nano, nemotron-super, step37, glm47, glm52, glm53"
                return 0
                ;;
            --prompt-source)
                [[ $# -ge 2 ]] || err "--prompt-source requires a path"
                prompt_source="$2"
                shift 2
                ;;
            --output)
                [[ $# -ge 2 ]] || err "--output requires a path"
                output="$2"
                shift 2
                ;;
            --profile)
                [[ $# -ge 2 ]] || err "--profile requires an id"
                profile="$2"
                shift 2
                ;;
            *)
                validator_args+=("$1")
                shift
                ;;
        esac
    done
    [[ -n "$prompt_source" ]] || err "--prompt-source is required"
    [[ -n "$output" ]] || err "--output is required"
    [[ -d "$WITNESS_REPO" ]] || err "llama-witness repo not found: $WITNESS_REPO"
    local validator_bin="$WITNESS_REPO/build/bin/llama-witness-validate"

    mapfile -t paths < <(witness_model_paths "$model")
    local model_dir="${paths[0]}"
    local model_gguf="${paths[2]}"
    [[ -d "$model_dir" ]] || err "witness model dir not found: $model_dir"
    [[ -f "$prompt_source" ]] || err "prompt source not found: $prompt_source"
    if is_step_witness_model "$model"; then
        local run_dir
        run_dir=$(create_run_dir "witness-inputs")
        mkdir -p "$(dirname "$output")"

        info "Building Step llama-witness input-token source with Krasis tokenizer"
        info "Run dir: $run_dir"
        info "Output: $output"
        KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="witness-inputs" \
            run_repo_python "$SCRIPT_DIR/tests/step37_witness_inputs.py" \
                --model-dir "$model_dir" \
                --prompt-source "$prompt_source" \
                --output "$output" \
                --profile "$profile" \
                "${validator_args[@]}" \
            2>&1 | tee "$run_dir/witness_inputs.log"
        ok "Witness input-token source complete: $output"
        return 0
    fi
    [[ -f "$model_gguf" ]] || err "witness GGUF not found: $model_gguf"
    case "${model,,}" in
        qwen35|q35b|qwen3.5-35b-a3b|q122b|qwen122|qwen3.5-122b-a10b|q235|qwen235|qwen3-235b-a22b)
            validator_args+=(--require-thinking-off-proof)
            ;;
    esac
    local run_dir
    run_dir=$(create_run_dir "witness-inputs")
    mkdir -p "$(dirname "$output")"

    info "Building llama-witness input-token source"
    info "Run dir: $run_dir"
    info "Output: $output"
    (
        cd "$WITNESS_REPO"
        cmake -S . -B build
        cmake --build build --target llama-witness-validate -j "${WITNESS_BUILD_JOBS:-$(nproc)}"
        "$validator_bin" \
            --model "$model_gguf" \
            --prompt-source "$prompt_source" \
            --write-input-source "$output" \
            --artifact-model-name "$(basename "$model_dir")" \
            --artifact-model-path "$model_dir" \
            --profile-id "$profile" \
            "${validator_args[@]}"
    ) 2>&1 | tee "$run_dir/witness_inputs.log"
    ok "Witness input-token source complete: $output"
}

do_witness_compare() {
    if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
        echo "Usage: ./dev witness-compare <config> [--profile ID] [reference-test args...]"
        echo "  Compares Krasis against a llama-witness-authored artifact."
        return 0
    fi
    [[ $# -lt 1 ]] && err "Usage: ./dev witness-compare <config> [--profile ID] [reference-test args...]
  Runs reference-test against a llama-witness-authored artifact."
    local config="$1"
    shift
    local profile="$WITNESS_PROFILE_ID"
    local args=()
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --help|-h)
                echo "Usage: ./dev witness-compare <config> [--profile ID] [reference-test args...]"
                echo "  Compares Krasis against a llama-witness-authored artifact."
                return 0
                ;;
            --profile)
                [[ $# -ge 2 ]] || err "--profile requires an id"
                profile="$2"
                shift 2
                ;;
            *)
                args+=("$1")
                shift
                ;;
        esac
    done
    do_reference_test "$config" --profile "$profile" "${args[@]}"
}

do_capture_preflight() {
    require_archived_hf_reference_override "./dev capture-preflight"
    info "Running capture host preflight"
    KRASIS_DEV_SCRIPT=1 \
    KRASIS_DEV_PYTHON="$PYTHON" \
    KRASIS_DEV_PIP="$PIP" \
    KRASIS_DEV_MATURIN="$MATURIN" \
    KRASIS_REFERENCE_CAPTURE_ROOT="$REFERENCE_CAPTURE_ROOT" \
    KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE="$REFERENCE_CAPTURE_ROOT_SOURCE" \
    KRASIS_REFERENCE_CAPTURE_MODELS_DIR="$REFERENCE_CAPTURE_MODELS_DIR" \
    KRASIS_REFERENCE_CAPTURE_VENV="$REFERENCE_CAPTURE_VENV" \
    KRASIS_REFERENCE_CAPTURE_READY_JSON="$REFERENCE_CAPTURE_READY_JSON" \
    KRASIS_REFERENCE_CAPTURE_READY_STAMP="$REFERENCE_CAPTURE_READY_STAMP" \
    "$SCRIPT_DIR/scripts/capture_preflight.sh" "$@"
}

do_reference_prep() {
    [[ $# -lt 1 && ! " ${*:-} " =~ [[:space:]](--help|-h|--list-models|--deps-only|--print-deps-json)[[:space:]] ]] && err "Usage: ./dev reference-prep <model> [--detach] [--print-urls|--urls-only] [--deps-only|--download-only|--print-deps-json] [--max-workers N] [--retry-count N] [--retry-backoff-sec N] [--enable-xet|--disable-xet] [--dest-root PATH]
  Prepares the HF reference-capture environment and downloads a public model to ${REFERENCE_CAPTURE_MODELS_DIR}.
  Examples:
    ./dev capture-preflight --bootstrap
    ./dev reference-prep qcn
    ./dev reference-prep qwen35 --detach
    ./dev reference-prep qcn --download-only --max-workers 4 --retry-count 8
    ./dev reference-prep --deps-only
    ./dev reference-prep --print-deps-json
    ./dev reference-prep gemma --urls-only"
    require_archived_hf_reference_override "./dev reference-prep"
    info "Preparing reference host: ${1:-listing models}"
    KRASIS_DEV_SCRIPT=1 KRASIS_DEV_PYTHON="$PYTHON" KRASIS_DEV_PIP="$PIP" \
    KRASIS_REFERENCE_CAPTURE_ROOT="$REFERENCE_CAPTURE_ROOT" \
    KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE="$REFERENCE_CAPTURE_ROOT_SOURCE" \
    KRASIS_REFERENCE_CAPTURE_MODELS_DIR="$REFERENCE_CAPTURE_MODELS_DIR" \
    KRASIS_REFERENCE_CAPTURE_VENV="$REFERENCE_CAPTURE_VENV" \
    "$SCRIPT_DIR/scripts/reference_capture_prep.sh" "$@"
}

do_generate_reference() {
    [[ $# -lt 1 ]] && err "Usage: ./dev generate-reference <model> [--max-tokens N] [--profile PROFILE] [--conversation-index N [--turn-index N|--turn-start-index N --turn-end-index N] | --first-stored-turns N | --raw-input-json PATH] [--attn-implementation eager|sdpa|flash_attention_2] [--use-cache auto|on|off] [--generate-use-cache auto|on|off] [--diagnostic-use-cache auto|on|off] [--diagnostic-scope all|final|postponed] [--between-turn-cleanup none|gc|reset] [--diagnose-pre-post-forward] [--diagnose-hidden-summaries] [--diagnose-layer0-internals] [--diagnose-layer0-element-dims CSV] [--diagnose-layer1-internals] [--diagnose-layer1-element-dims CSV] [--reload-model-between-turns] [--diagnostic-only] [--output PATH]
  ARCHIVED: HF/Transformers reference capture is no longer trusted by default.
  Generates a BF16 HuggingFace greedy reference with full contract metadata only when explicitly unarchived for forensic evidence.
  Subset captures write a diagnostic non-canonical filename unless --output is supplied.
  Profiles:
    auto                    thinking_off if supported, otherwise default
    greedy_chat_default     default template invocation
    greedy_chat_thinking_off  pass enable_thinking=False
    greedy_chat_thinking_on   pass enable_thinking=True
  Example:
    ./dev generate-reference Qwen3-Coder-Next --profile greedy_chat_thinking_off
    ./dev generate-reference qwen35 --profile greedy_chat_thinking_off --conversation-index 0 --turn-index 0 --diag-steps 1 --diag-topk 10 --attn-implementation eager
    ./dev generate-reference qwen35 --profile greedy_chat_thinking_off --conversation-index 0 --turn-start-index 0 --turn-end-index 1 --diag-steps 1 --diag-topk 10 --attn-implementation sdpa --diagnostic-scope final --diagnostic-only
    ./dev generate-reference qwen35 --profile greedy_chat_thinking_off --first-stored-turns 4 --diag-steps 1 --diag-topk 10 --attn-implementation sdpa --diagnostic-scope postponed --diagnostic-only
	    ./dev generate-reference nemotron-super --raw-input-json benchmarks/exact_payload.json --max-tokens 2 --diag-steps 2 --diag-topk 12 --diagnose-pre-post-forward --diagnose-hidden-summaries --diagnose-layer0-internals --diagnose-layer0-element-dims 3265,739,1067,445 --diagnose-layer1-internals --diagnose-layer1-element-dims 3265,739,1067,445 --output benchmarks/exact_oracle.json
    ./dev generate-reference qwen35 --profile greedy_chat_thinking_off --conversation-index 0 --turn-start-index 0 --turn-end-index 1 --diag-steps 1 --diag-topk 10 --attn-implementation sdpa --generate-use-cache auto --diagnostic-use-cache off --diagnose-pre-post-forward --diagnostic-only"
    require_archived_hf_reference_override "./dev generate-reference"
    cleanup_gpu
    local run_dir logfile dev_cmd
    run_dir=$(create_run_dir "generate-reference")
    logfile="$run_dir/generate_reference_stdout.log"
    printf -v dev_cmd '%q ' ./dev generate-reference "$@"
    dev_cmd="${dev_cmd% }"
    info "Generating reference: $1"
    info "Run dir: $run_dir"
    verify_repo_python_imports
    set +e
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="generate-reference" KRASIS_DEV_CMD="$dev_cmd" \
        KRASIS_REFERENCE_CAPTURE_ROOT="$REFERENCE_CAPTURE_ROOT" \
        KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE="$REFERENCE_CAPTURE_ROOT_SOURCE" \
        KRASIS_REFERENCE_CAPTURE_MODELS_DIR="$REFERENCE_CAPTURE_MODELS_DIR" \
        run_reference_capture_python "$SCRIPT_DIR/tests/generate_reference.py" "$@" 2>&1 | tee "$logfile"
    local status=${PIPESTATUS[0]}
    set -e
    return "$status"
}

do_reference_backfill_topk() {
    [[ $# -lt 1 ]] && err "Usage: ./dev reference-backfill-topk <model> --reference <existing-greedy-reference.json> [--output <new-json>] [--diag-steps N] [--diag-topk N] [--diagnose-turn CONV:TURN] [--diagnose-prefix-search] [--diagnose-prefix-lengths CSV] [--attn-implementation eager|sdpa|flash_attention_2]
  ARCHIVED: HF/Transformers reference backfill is no longer trusted by default.
  Backfills teacher-forced top-k/logprob diagnostics from exact stored raw input_token_ids only when explicitly unarchived for forensic evidence.
  Writes a new artifact by default; in-place backfill is not allowed.
  With --diagnose-turn, writes no output artifact and reports strict logits/log-softmax diagnostics for selected turns.
  With --diagnose-prefix-search, also probes raw-token prefixes for diagnosed turns.
  With --diagnose-prefix-lengths, probes exact prefix lengths and records token pieces, validity, round-trip, and logits stats.
  With --attn-implementation, requests an HF attention implementation for this diagnostic/backfill model load.
  Example:
    ./dev reference-backfill-topk qwen35 --reference ../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference.json --output ../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference_backfilled_topk.json --diag-steps 1 --diag-topk 10
    ./dev reference-backfill-topk qwen35 --reference ../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference.json --diagnose-turn 0:0 --diagnose-turn 0:2 --diagnose-prefix-search
    ./dev reference-backfill-topk qwen35 --reference ../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference.json --diagnose-turn 0:0 --diagnose-turn 0:2 --diagnose-prefix-lengths 1,2,3,13,32,78 --attn-implementation eager"
    require_archived_hf_reference_override "./dev reference-backfill-topk"
    cleanup_gpu
    local run_dir logfile dev_cmd
    run_dir=$(create_run_dir "reference-backfill-topk")
    logfile="$run_dir/reference_backfill_topk_stdout.log"
    printf -v dev_cmd '%q ' ./dev reference-backfill-topk "$@"
    dev_cmd="${dev_cmd% }"
    info "Backfilling reference top-k/logprobs: $1"
    info "Run dir: $run_dir"
    verify_repo_python_imports
    set +e
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="reference-backfill-topk" KRASIS_DEV_CMD="$dev_cmd" \
        KRASIS_REFERENCE_CAPTURE_ROOT="$REFERENCE_CAPTURE_ROOT" \
        KRASIS_REFERENCE_CAPTURE_ROOT_SOURCE="$REFERENCE_CAPTURE_ROOT_SOURCE" \
        KRASIS_REFERENCE_CAPTURE_MODELS_DIR="$REFERENCE_CAPTURE_MODELS_DIR" \
        run_reference_capture_python "$SCRIPT_DIR/tests/reference_backfill_topk.py" "$@" 2>&1 | tee "$logfile"
    local status=${PIPESTATUS[0]}
    set -e
    return "$status"
}

do_capture_box() {
    local subcmd="${1:-help}"
    shift || true
    enter_capture_box_env

    case "$subcmd" in
        env)
            print_capture_box_env "$KRASIS_CAPTURE_BOX_REPO_HOME"
            ;;
        preflight|capture-preflight)
            print_capture_box_env "$KRASIS_CAPTURE_BOX_REPO_HOME"
            do_capture_preflight "$@"
            ;;
        prep|reference-prep)
            print_capture_box_env "$KRASIS_CAPTURE_BOX_REPO_HOME"
            do_reference_prep "$@"
            ;;
        stage)
            local dry_run=0
            local skip_bootstrap=0
            local -a stage_models=()
            while [[ $# -gt 0 ]]; do
                case "$1" in
                    --dry-run)
                        dry_run=1
                        shift
                        ;;
                    --no-bootstrap)
                        skip_bootstrap=1
                        shift
                        ;;
                    -h|--help)
                        echo "Usage: ./dev capture-box stage [--dry-run] [--no-bootstrap] <model> [more models...]"
                        echo ""
                        echo "Bootstrap the paid-box capture host once, then queue one or more model"
                        echo "downloads through the enforced capture-box environment."
                        echo ""
                        echo "Options:"
                        echo "  --dry-run       Print the exact staged commands without running them"
                        echo "  --no-bootstrap  Skip capture-preflight --bootstrap and assume the host is already ready"
                        echo ""
                        echo "Example:"
                        echo "  ./dev capture-box stage qcn gemma"
                        echo "  ./dev capture-box stage --dry-run qcn gemma"
                        return 0
                        ;;
                    -*)
                        err "Unknown capture-box stage option: $1"
                        ;;
                    *)
                        stage_models+=("$1")
                        shift
                        ;;
                esac
            done
            [[ "${#stage_models[@]}" -gt 0 ]] || err "Usage: ./dev capture-box stage [--dry-run] [--no-bootstrap] <model> [more models...]"
            print_capture_box_env "$KRASIS_CAPTURE_BOX_REPO_HOME"
            if [[ "$skip_bootstrap" -eq 0 ]]; then
                info "Stage bootstrap target: ${stage_models[0]}"
                if [[ "$dry_run" -eq 1 ]]; then
                    local bootstrap_cmd
                    printf -v bootstrap_cmd '%q ' ./dev capture-box preflight --bootstrap --model "${stage_models[0]}"
                    echo "DRY RUN: ${bootstrap_cmd% }"
                else
                    do_capture_preflight --bootstrap --model "${stage_models[0]}"
                fi
            else
                warn "Skipping capture bootstrap as requested"
            fi
            local model
            for model in "${stage_models[@]}"; do
                info "Queueing staged model: $model"
                if [[ "$dry_run" -eq 1 ]]; then
                    local prep_cmd
                    printf -v prep_cmd '%q ' ./dev capture-box prep "$model" --detach
                    echo "DRY RUN: ${prep_cmd% }"
                else
                    do_reference_prep "$model" --detach
                fi
            done
            if [[ "$dry_run" -eq 1 ]]; then
                info "Dry run complete"
            else
                ok "Staged ${#stage_models[@]} model download(s)"
                echo "Next: run ./dev capture-box generate <model> --profile <profile> once the first model is ready."
            fi
            ;;
        generate|generate-reference)
            print_capture_box_env "$KRASIS_CAPTURE_BOX_REPO_HOME"
            [[ $# -ge 1 ]] || err "Usage: ./dev capture-box generate <model> [--profile PROFILE] [--max-tokens N] [--conversation-index N [--turn-index N|--turn-start-index N --turn-end-index N]] [--attn-implementation eager|sdpa|flash_attention_2]"
            info "Verifying paid-box capture host for model: $1"
            do_capture_preflight --bootstrap --model "$1"
            do_generate_reference "$@"
            ;;
        help|-h|--help)
            echo "Usage: ./dev capture-box <subcommand> [args...]"
            echo ""
            echo "ARCHIVED strict paid-box wrapper for HF capture work."
            echo "HF/Transformers capture commands now require KRASIS_ALLOW_ARCHIVED_HF_REFERENCE=1."
            echo ""
            echo "Historical behavior:"
            echo "It enforces one remote identity before any expensive work:"
            echo "  - HOME := inferred repo owner home"
            echo "  - PATH prepends <repo-home>/.cargo/bin"
            echo "  - capture root := <repo-home>/.krasis"
            echo "  - capture root source := capture_box"
            echo ""
            echo "Subcommands:"
            echo "  env                            Print the enforced environment and exit"
            echo "  preflight [args...]            Run ./dev capture-preflight under the enforced environment"
            echo "  prep [args...]                 Run ./dev reference-prep under the enforced environment"
            echo "  stage [args...]                Bootstrap once, then queue one or more model downloads"
            echo "  generate [args...]             Run ./dev generate-reference under the enforced environment"
            echo ""
            echo "Examples:"
            echo "  ./dev capture-box env"
            echo "  ./dev capture-box preflight --bootstrap --model qcn"
            echo "  ./dev capture-box prep qcn --detach"
            echo "  ./dev capture-box stage qcn gemma"
            echo "  ./dev capture-box generate Qwen3-Coder-Next --profile greedy_chat_thinking_off"
            ;;
        *)
            err "Unknown capture-box subcommand: $subcmd
  Expected one of: env, preflight, prep, stage, generate"
            ;;
    esac
}

do_trace_diff() {
    [[ $# -lt 2 ]] && err "Usage: ./dev trace-diff <expected-trace> <actual-trace> [--events mark,tensor,...] [--components decode,...] [--contexts ctx1,ctx2] [--phases artifact,validation] [--show-window N] [--resync-window N] [--family-resync-window N]
  Diffs two KRASIS_TRACE logs offline, reports the first divergence, summarizes matching-prefix plus context/phase counts,
  classifies the divergence, gives bounded event-level and family-region resync hints for short shifted regions,
  adds typed analysis for tensor/logits/route mismatches, and reports stronger family-packet signatures."
    local run_dir
    run_dir=$(create_run_dir "trace-diff")
    info "Running trace diff"
    info "Run dir: $run_dir"
    verify_repo_imports
    KRASIS_DEV_SCRIPT=1 KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="trace-diff" run_repo_python "$SCRIPT_DIR/tests/trace_diff.py" "$@"
}

do_kill() {
    info "Killing all krasis processes and freeing GPU memory..."

    # Kill any krasis Python processes
    local pids
    pids=$(pgrep -f 'python.*krasis\.' 2>/dev/null || true)
    if [[ -n "$pids" ]]; then
        for p in $pids; do
            local cmdline
            cmdline=$(ps -p "$p" -o args= 2>/dev/null || echo "unknown")
            warn "  Killing PID $p: $cmdline"
            kill -9 "$p" 2>/dev/null || true
        done
        sleep 2
    fi

    # Check for zombie processes holding GPU memory
    local zombie_pids
    zombie_pids=$(ps -eo pid,ppid,stat,args 2>/dev/null | awk '$3 ~ /Z/ && /krasis|python/ {print $1 " " $2}' || true)
    if [[ -n "$zombie_pids" ]]; then
        warn "Found zombie processes — killing their parents:"
        while read -r zpid zppid; do
            warn "  Zombie PID $zpid, killing parent PID $zppid"
            kill -9 "$zppid" 2>/dev/null || true
        done <<< "$zombie_pids"
        sleep 2
    fi

    # Kill any process using GPU memory (except desktop compositor type stuff)
    local gpu_pids
    gpu_pids=$(nvidia-smi --query-compute-apps=pid --format=csv,noheader,nounits 2>/dev/null | tr -d ' ' || true)
    if [[ -n "$gpu_pids" ]]; then
        for p in $gpu_pids; do
            [[ -z "$p" ]] && continue
            local cmdline
            cmdline=$(ps -p "$p" -o args= 2>/dev/null || echo "unknown")
            warn "  GPU process PID $p: $cmdline"
            kill -9 "$p" 2>/dev/null || true
        done
        sleep 2
    fi

    # Wait up to 10s for GPU to clear
    local waited=0
    while [[ $waited -lt 10 ]]; do
        local gpu0_used gpu1_used
        gpu0_used=$(nvidia-smi --id=0 --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | tr -d ' ')
        gpu1_used=$(nvidia-smi --id=1 --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | tr -d ' ')
        if [[ "${gpu0_used:-9999}" -lt 500 ]] && [[ "${gpu1_used:-9999}" -lt 500 ]]; then
            ok "All GPUs clear."
            return 0
        fi
        sleep 1
        waited=$((waited + 1))
    done

    # Last resort: nvidia-smi GPU reset
    warn "GPUs still not clear after 10s. Attempting nvidia-smi --gpu-reset..."
    if sudo nvidia-smi --gpu-reset 2>&1; then
        ok "GPU reset successful."
    else
        err "GPU reset failed. You may need to reboot.
  To reboot: sudo reboot"
    fi
}

do_shell() {
    exec_repo_python "$@"
}

do_python() {
    exec_repo_python "$@"
}

do_verify_imports() {
    verify_repo_imports
}

run_launcher_matrix_test() {
    local run_dir="$1"
    local run_type="${2:-launcher-test}"
    shift 2
    mkdir -p "$run_dir"
    info "Running launcher config matrix test"
    info "Run dir: $run_dir"
    KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="$run_type" \
        run_repo_python -m unittest discover -s "$SCRIPT_DIR/tests" -p 'test_launcher_matrix.py' "$@"
    KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="$run_type" \
        run_repo_python -m unittest discover -s "$SCRIPT_DIR/tests" -p 'test_hf_downloader.py' "$@"
    KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="$run_type" \
        run_repo_python -m unittest tests.test_multi_gpu_planner "$@"
}

do_launcher_test() {
    local run_dir
    run_dir=$(create_run_dir "launcher-test")
    run_launcher_matrix_test "$run_dir" "launcher-test" "$@"
}

do_windows_launcher_test() {
    info "Building and testing native Windows launcher logic"
    (
        cd "$SCRIPT_DIR"
        PATH="$HOME/.cargo/bin:$PATH" \
            cargo test --release --bin krasis-windows-launcher "$@"
    )
}

do_server_test() {
    info "Building and testing Rust HTTP response/server and reference verdict contracts"
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    (
        cd "$SCRIPT_DIR"
        PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/server.rs
        PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/chat_template.rs
        PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/session_cache.rs
        PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/bin/session-cache-benchmark.rs
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
            PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib server::tests "$@"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
            PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib chat_template::tests "$@"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
            PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib session_cache::tests "$@"
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
            PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib gpu_prefill::chunk_plan_tests "$@"
        KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_reference_judgement
        KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_session_cache_gate
        KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_vram_pressure
    )
}

do_manager_test() {
    info "Building and testing Rust Manager/API and launcher schema contracts"
    local pyver
    pyver=$("$PYTHON" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    local pylibdir
    pylibdir=$("$PYTHON" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    (
        cd "$SCRIPT_DIR"
        PATH="$HOME/.cargo/bin:$PATH" rustfmt --edition 2021 --check src/manager.rs
        PYO3_PYTHON="$PYTHON" \
        LD_LIBRARY_PATH="$pylibdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
        RUSTFLAGS="${RUSTFLAGS:-} -L $pylibdir -l python${pyver}" \
            PATH="$HOME/.cargo/bin:$(dirname "$PYTHON"):$PATH" \
            cargo test --release --lib manager::tests "$@"
        KRASIS_DEV_SCRIPT=1 run_repo_python -m unittest tests.test_manager_launcher
    )
}

# ── Extract --timing flag ────────────────────────────────────────
# Can appear anywhere in args. Removes it and sets KRASIS_DECODE_TIMING=1.
TIMING_FLAG=false
args=()
for arg in "$@"; do
    if [[ "$arg" == "--timing" ]]; then
        TIMING_FLAG=true
    else
        args+=("$arg")
    fi
done
set -- "${args[@]}"

if $TIMING_FLAG; then
    export KRASIS_DECODE_TIMING=1
    info "Decode timing ENABLED (adds ~30-50% overhead — not for speed benchmarks)"
fi

#── Dispatch ─────────────────────────────────────────────────────────
cmd="${1:-help}"
shift || true

case "$cmd" in
    build)          do_build ;;
    build-fla-windows-sources) do_build_fla_windows_sources ;;
    build-sidecars) do_build_sidecars "$@" ;;
    verify-sidecars) do_verify_sidecars ;;
    sidecar-key)    do_sidecar_key "$@" ;;
    pack-sidecar-bundle) do_pack_sidecar_bundle ;;
    restore-sidecar-bundle) do_restore_sidecar_bundle "$@" ;;
    upload-sidecar-bundle) do_upload_sidecar_bundle ;;
    run)            do_run "$@" ;;
    launcher-run)   do_launcher_run "$@" ;;
    test)           do_test "$@" ;;
    benchmark)      do_benchmark "$@" ;;
    approved-heatmap-build) do_approved_heatmap_build "$@" ;;
    approved-heatmap-eval) do_approved_heatmap_eval "$@" ;;
    checkpoint-identity-test) do_checkpoint_identity_test "$@" ;;
    approved-heatmap-migrate) do_approved_heatmap_migrate "$@" ;;
    speed-test|speedtest) do_speed_test "$@" ;;
    decode-harness) do_decode_harness "$@" ;;
    release-test)   do_release_test "$@" ;;
    release-test-all) do_release_test_all "$@" ;;
    launcher-test)  do_launcher_test "$@" ;;
    windows-launcher-test) do_windows_launcher_test "$@" ;;
    server-test)    do_server_test "$@" ;;
    manager-test)   do_manager_test "$@" ;;
    reference-test) do_reference_test "$@" ;;
    witness-inputs) do_witness_inputs "$@" ;;
    witness-model-check) do_witness_model_check "$@" ;;
    witness-build) do_witness_build "$@" ;;
    witness-gguf-preflight) do_witness_gguf_preflight "$@" ;;
    witness-gguf-convert) do_witness_gguf_convert "$@" ;;
    witness-capture) do_witness_capture "$@" ;;
    witness-compare) do_witness_compare "$@" ;;
    hqq-attn-diff) do_hqq_attn_diff "$@" ;;
    hqq-self-calibrate) do_hqq_self_calibrate "$@" ;;
    hqq-self-calibrate-test) do_hqq_self_calibrate_test "$@" ;;
    model-config-test) do_model_config_test "$@" ;;
    hqq-gpu-search-probe) do_hqq_gpu_search_probe "$@" ;;
    expert-hqq-cache-generate) do_expert_hqq_cache_generate "$@" ;;
    tileq-build)    do_tileq_build "$@" ;;
    expert-hqq-trace-compare) do_expert_hqq_trace_compare "$@" ;;
    expert-hqq-row-attribution) do_expert_hqq_row_attribution "$@" ;;
    reference-inventory) do_reference_inventory "$@" ;;
    capture-box)    do_capture_box "$@" ;;
    capture-preflight) do_capture_preflight "$@" ;;
    reference-prep) do_reference_prep "$@" ;;
    generate-reference) do_generate_reference "$@" ;;
    reference-backfill-topk) do_reference_backfill_topk "$@" ;;
    trace-diff)     do_trace_diff "$@" ;;
    perplexity)     do_perplexity "$@" ;;
    quality-ppl)    do_quality_ppl "$@" ;;
    awq-calibrate)  do_awq_calibrate "$@" ;;
    network)        do_network "$@" ;;
    prefill-decode-compare) do_prefill_decode_compare "$@" ;;
    vision-test)    do_vision_test "$@" ;;
    session-cache-test) do_session_cache_test "$@" ;;
    session-cache-operations) do_session_cache_operations "$@" ;;
    session-cache-benchmark) do_session_cache_benchmark "$@" ;;
    peer-rtt)       do_peer_rtt "$@" ;;
    expert-compression-probe) do_expert_compression_probe "$@" ;;
    expert-compression-gpu) do_expert_compression_gpu "$@" ;;
    expert-compression-build) do_expert_compression_build "$@" ;;
    test-kernels)   do_test_kernels "$@" ;;
    glm53-check)    do_glm53_check ;;
    cpu-tail-calibrate) do_cpu_tail_calibrate "$@" ;;
    pcie-batch-probe) do_pcie_batch_probe "$@" ;;
    validate)       do_validate "$@" ;;
    shell)          do_shell "$@" ;;
    python)         do_python "$@" ;;
    verify-imports) do_verify_imports ;;
    help|-h|--help)
        echo "Krasis dev helper"
        echo ""
        echo "Usage: ./dev <command> [args...]"
        echo ""
        echo "Core commands:"
        echo "  build                          Rebuild Rust extension into this repo only"
        echo "  build-fla-windows-sources      Generate portable FLA CUDA sources for Windows CI"
        echo "  cpu-tail-calibrate <config>    Optimize/measure CPU-tail under live GPU DMA"
        echo "  pcie-batch-probe <options>     Compare ordinary and batched pinned H2D copies"
        echo "  build-sidecars [--force]       Build Marlin/FlashAttention package sidecars"
        echo "  verify-sidecars                Verify sidecar manifest, hashes, and symbols"
        echo "  sidecar-key [--json]           Print sidecar bundle cache key"
        echo "  pack-sidecar-bundle            Pack verified sidecars into a local bundle"
        echo "  restore-sidecar-bundle [--github] Restore sidecars from bundle cache"
        echo "  upload-sidecar-bundle          Upload bundle to configured GitHub release"
        echo "  run <config> [flags]           Launch server (add --benchmark or --selected-gpus GPU[,GPU...] as needed)"
        echo "  launcher-run <config> [flags]  Launch through the primary launcher path"
        echo "  benchmark <config>             Run standard benchmark and exit"
        echo "  approved-heatmap-build <config> --out <path>"
        echo "                                 Build approved cumulative HCS route heatmap checkpoints"
        echo "  approved-heatmap-eval <config> <heatmap.json>"
        echo "                                 Benchmark a config with an approved heatmap artifact"
        echo "  checkpoint-identity-test      Test unified checkpoint/cache/heatmap identity"
        echo "  approved-heatmap-migrate <audit|migrate|verify>"
        echo "                                 Audit/migrate dual-key online heatmaps"
        echo "  speed-test                     Run the fixed standard speed benchmark"
        echo "  decode-harness <config>        Run synthetic GPU decode harness and exit"
        echo "  perplexity <config>            Run perplexity eval (WikiText-2) and exit"
        echo "  quality-ppl <config>           Measure PPL through a running Rust prefill test endpoint"
        echo "  awq-calibrate <config>         Deprecated AWQ calibration command (disabled)"
        echo ""
        echo "Test and validation commands:"
        echo "  model-config-test              Run no-GPU model config contract tests"
        echo "  test <config>                  Short model test (benchmark + network tests)"
        echo "  test <config> --thorough       Thorough test (+ stress + large prompts)"
        echo "  network <port> [--large]       Run network tests against a running server"
        echo "  prefill-decode-compare <port>  Compare exact-token prefill and teacher-forced decode logits"
        echo "  session-cache-test <port>      Compare active/RAM cached continuations with full prefill"
        echo "  session-cache-operations <port> Test eviction, branches, cancellation and concurrency"
        echo "  session-cache-benchmark <port> Benchmark interleaved agent conversations cache off/on"
        echo "  peer-rtt <primary> <peer>      Measure pinned-host peer-GPU round-trip latency"
        echo "  expert-compression-probe ...  Measure real Marlin cache entropy and lossless ratio"
        echo "  expert-compression-gpu ...    Gate bit-exact GPU entropy decode on real experts"
        echo "  expert-compression-build ...  Build a versioned expert compression sidecar"
        echo "  validate <config>              Validate against stored non-HF references; HF artifacts require override"
        echo "  reference-test <config>        Compare against stored non-HF references; HF artifacts require override"
        echo "  reference-test --compare <model>  Comparison matrix; HF artifacts require override"
        echo "  launcher-test                  Validate launcher config serialization and server startup parsing"
        echo "  windows-launcher-test          Build and test native Windows launcher logic"
        echo "  server-test                    Test Rust HTTP/template and reference-verdict contracts"
        echo "  manager-test                   Test Rust Manager/API and launcher schema contracts"
        echo "  vision-test <port> <image> ... Test live image understanding against exact expected text"
        echo "  reference-inventory            Inventory stored reference artifacts"
        echo "  witness-inputs <model>         Build stored input_token_ids from fixed prompt-source JSON"
        echo "  witness-model-check <model>    Check expected BF16 GGUF witness model readiness"
        echo "  witness-build                  Build the pinned llama-witness validator"
        echo "  witness-gguf-preflight <model> Preflight BF16 GGUF witness conversion readiness"
        echo "  witness-gguf-convert <model>   Convert local safetensors to BF16 GGUF after preflight"
        echo "  witness-capture <model>        Capture llama-witness JSON from stored input_token_ids"
        echo "  witness-compare <config>       Compare Krasis against llama-witness JSON"
        echo "  hqq-attn-diff <model>          Offline HQQ attention artifact diff against BF16 source"
        echo "  hqq-self-calibrate <config>    Capture HQQ self-calibration evidence/candidates"
        echo "  expert-hqq-cache-generate <manifest.json> Generate KRHQ cache from explicit manifest"
        echo "  tileq-build <subcommand>       Plan/build/verify source-bound KTQ1 expert caches"
        echo "  expert-hqq-trace-compare <trace.json> <spec.json> <metrics.tsv> Compare HQQ trace export offline"
        echo "  expert-hqq-row-attribution <response.json> <spec.json> <metrics.tsv> Attribute exact HQQ row capture"
        echo "  capture-box <subcommand>      ARCHIVED HF capture wrapper; requires explicit override"
        echo "  capture-preflight             ARCHIVED HF capture host preflight; requires explicit override"
        echo "  reference-prep <model>         ARCHIVED HF dependency/model prep; requires explicit override"
        echo "  generate-reference <model>     ARCHIVED HF reference capture; requires explicit override"
        echo "  reference-backfill-topk <model>  ARCHIVED HF top-k backfill; requires explicit override"
        echo "  trace-diff <expected> <actual> Diff two KRASIS_TRACE logs offline"
        echo "  release-test <model>           Run full release test (launcher matrix, config matrix, report)"
        echo "  release-test-all [target]      Run release test on all supported models sequentially"
        echo ""
        echo "Maintenance commands:"
        echo "  test-kernels [name]            Run CUDA kernel unit tests (or filter by name)"
        echo "  glm53-check                    Compile-check GLM-5.3 Rust/CUDA integration"
        echo "  chat [args]                    Run krasis chat from source"
        echo "  sanity                         Run sanity test prompts against running server"
        echo "  kill                           Kill all krasis/GPU processes, reset if needed"
        echo "  install                        Sync krasis command to ~/.local/bin (uses source)"
        echo "  shell                          Python shell bound to this repo"
        echo "  python <args>                  Run Python bound to this repo"
        echo "  verify-imports                 Verify imports resolve inside this repo"
        echo ""
        echo "Global flags:"
        echo "  --timing    Enable per-component decode timing (adds ~30-50% overhead)"
        echo "              Prints detailed breakdown of where decode time is spent."
        echo "              NOT for speed benchmarks — only for profiling."
        echo ""
        echo "Reference workflow:"
        echo "  HF/Transformers reference capture is archived and blocked by default."
        echo "  Use llama-witness for new large-model reference authority."
        echo "  Archived HF commands require KRASIS_ALLOW_ARCHIVED_HF_REFERENCE=1 and a documented reason."
        echo ""
        echo "  1. Check the BF16 witness model is present:"
        echo "       ./dev witness-model-check qcn"
        echo "  2. Preflight BF16 GGUF conversion if the witness model is missing:"
        echo "       ./dev witness-gguf-preflight qwen35"
        echo "  3. Convert BF16 GGUF only after preflight passes:"
        echo "       ./dev witness-gguf-convert qwen35"
        echo "  4. Capture a llama-witness first-token artifact from stored input_token_ids:"
        echo "       ./dev witness-capture qcn --max-cases 4 --output ../krasis-internal/reference-outputs/output/Qwen3-Coder-Next/llama_witness_first_token.json"
        echo "  5. Compare Krasis against that non-HF witness artifact:"
        echo "       ./dev witness-compare tests/qcn-bf16kv-hqq8-accuracy.conf"
        echo "  6. Inventory current historical artifacts:"
        echo "       ./dev reference-inventory"
        echo "  Archived HF workflow for forensic reruns only:"
        echo "  2. On paid boxes, enforce the remote environment first:"
        echo "       ./dev capture-box env"
        echo "  3. Prove the host is ready before queueing downloads/captures:"
        echo "       ./dev capture-box preflight --bootstrap --model <model>"
        echo "  4. Prepare the host and fetch the public model if needed:"
        echo "       ./dev capture-box prep <model>"
        echo "  5. Generate an explicit reference profile:"
        echo "       ./dev capture-box generate <model> --profile <profile>"
        echo "     For minimal diagnostic recaptures:"
        echo "       ./dev generate-reference qwen35 --profile greedy_chat_thinking_off --conversation-index 0 --turn-index 0 --diag-steps 1 --diag-topk 10 --attn-implementation eager"
        echo "  5b. Backfill exact raw-token diagnostics into an existing artifact:"
        echo "       ./dev reference-backfill-topk <model> --reference <greedy_reference.json> --output <new-json>"
        echo "    Or stage multiple downloads at once:"
        echo "       ./dev capture-box stage qcn gemma"
        echo "  6. Validate a non-HF capture against a runtime config; HF artifacts require override:"
        echo "       ./dev validate <config> --max-prompts 0 --no-server --port 1"
        echo "  7. Run the real non-HF comparison; HF artifacts require override:"
        echo "       ./dev reference-test <config>"
        echo "  8. Diff stored traces offline when needed:"
        echo "       ./dev trace-diff <expected-trace> <actual-trace>"
        echo "  Reference-prep aliases:"
        echo "    qcn, qwen35, q122b, gemma, minimax, q235, q397"
        echo "  Subset and attention controls:"
        echo "    --conversation-index N       Restrict capture to one zero-based prompt conversation"
        echo "    --turn-index N               Record one zero-based turn; prior turns are generated as context"
        echo "    --turn-start-index N         Record a zero-based turn range inside --conversation-index"
        echo "    --turn-end-index N           End of the recorded turn range"
        echo "    --attn-implementation NAME   Request HF eager, sdpa, or flash_attention_2 for capture"
        echo "    --use-cache auto|on|off      Legacy default for generate and diagnostics unless split flags are supplied"
        echo "    --generate-use-cache MODE    Cache mode for model.generate only: auto, on, off"
        echo "    --diagnostic-use-cache MODE  Cache mode for diagnostic forward only: auto, on, off"
        echo "    --diagnostic-scope MODE      all, final, or postponed diagnostics for selected turns"
        echo "    --diagnose-pre-post-forward  Capture diagnostic forward before and after generate"
        echo "    --diagnose-hidden-summaries  Capture per-hidden-state summaries during diagnostic forward"
        echo "    --diagnose-layer0-internals Capture layer-0 internal summaries during diagnostic forward"
        echo "    --diagnose-layer1-internals Capture layer-1 MoE internal summaries during diagnostic forward"
        echo "    --diagnose-layer1-element-dims CSV  Limit layer-1 exact element details to these hidden dims"
        echo "    --between-turn-cleanup MODE  none, gc, or reset before turns after the first"
        echo "    --reload-model-between-turns Reload HF model before turns after the first"
        echo "    --diagnostic-only            Write diagnostic/failure manifest only, not a reference artifact"
        echo "    --output PATH                Explicit output path; subset captures otherwise use diagnostic filenames"
        echo "  Notes:"
        echo "    - Uses public Hugging Face repo IDs only; does not use an HF token."
        echo "    - capture root:"
        echo "        $REFERENCE_CAPTURE_ROOT"
        echo "    - paid-box wrapper:"
        echo "        ./dev capture-box ..."
        echo "    - capture-preflight writes:"
        echo "        $REFERENCE_CAPTURE_READY_JSON"
        echo "        $REFERENCE_CAPTURE_READY_STAMP"
        echo "    - reference-prep installs capture/download deps in the isolated capture venv:"
        echo "        $REFERENCE_CAPTURE_VENV"
        echo "    - reference-prep downloads models to:"
        echo "        $REFERENCE_CAPTURE_MODELS_DIR"
        echo "    - Use --detach to keep a long download running with a log file."
        echo ""
        echo "Reference profiles for ./dev generate-reference:"
        echo "  auto                       Use thinking_off when template supports enable_thinking"
        echo "  greedy_chat_default        Default chat template invocation"
        echo "  greedy_chat_thinking_off   Pass enable_thinking=False"
        echo "  greedy_chat_thinking_on    Pass enable_thinking=True"
        echo "  Output files:"
        echo "    greedy_chat_default.json"
        echo "    greedy_chat_thinking_off.json"
        echo "    greedy_chat_thinking_on.json"
        echo "  Notes:"
        echo "    - Use explicit --profile for any durable reference capture."
        echo "    - Legacy greedy_reference.json is compatibility-only and may fail closed."
        echo "    - New captures store contract metadata and should be regenerated through ./dev only."
        echo ""
        echo "Trace / contract debugging:"
        echo "  KRASIS_TRACE=1 enables structured trace output."
        echo "  KRASIS_TRACE_COMPONENTS=config_contract traces reference inventory/generation/validation state."
        echo "  ./dev trace-diff compares stored KRASIS_TRACE logs, reports the first divergence,"
        echo "  summarizes matching-prefix plus context/phase counts, can suggest a short"
        echo "  resync point when one stream has inserted or dropped a few events, emits"
        echo "  typed mismatch analysis for tensor, values, logits, route, and python_compare events,"
        echo "  adds a top-level divergence classification summary,"
        echo "  adds local decode-family analysis for missing/unexpected sub-events within one"
        echo "  step/layer packet, adds bounded family-region resync hints across neighboring"
        echo "  decode packets, reports stronger family-packet signatures, and reports the"
        echo "  nearest preceding config_contract state for decode divergences."
        echo "  Example:"
        echo "    KRASIS_TRACE=1 KRASIS_TRACE_COMPONENTS=config_contract ./dev reference-inventory"
        echo "    ./dev trace-diff /tmp/expected.log /tmp/actual.log --components config_contract --contexts reference_test_single --phases artifact,validation"
        echo ""
        echo "Configs: qcn, dsv4, gemma"
        echo "         (or path to .conf file)"
        echo "Standard speed benchmark config: tests/qcn-k4v4-hqq4-int4-benchmark.conf"
        echo ""
        echo "Examples:"
        echo "  ./dev build"
        echo "  ./dev build-fla-windows-sources"
        echo "  ./dev build-sidecars"
        echo "  ./dev verify-sidecars"
        echo "  ./dev sidecar-key --json"
        echo "  ./dev run qcn"
        echo "  ./dev run qcn --benchmark"
        echo "  ./dev speed-test    # QCN INT4 HQQ4 k4v4"
        echo "  ./dev benchmark qcn --timing    Profile decode components"
        echo "  ./dev benchmark qcn             Normal speed benchmark"
        echo "  ./dev decode-harness qcn --prompt-len 8192 --steps 64"
        echo "  ./dev release-test Qwen3-Coder-Next    Full release test"
        echo "  ./dev release-test-all                 Test all models (no resume)"
        echo "  ./dev release-test-all rc8             Test all models (resume on re-run with same target)"
        echo "  ./dev capture-box env"
        echo "  ./dev capture-box preflight --bootstrap --model qcn"
        echo "  ./dev capture-box prep qcn --detach"
        echo "  ./dev capture-box stage qcn gemma"
        echo "  ./dev capture-box generate Qwen3-Coder-Next --profile greedy_chat_thinking_off"
        echo "  ./dev reference-backfill-topk qwen35 --reference ../krasis-internal/reference-outputs/output/Qwen3.5-35B-A3B/greedy_reference.json"
        echo "  ./dev awq-calibrate qcn    Deprecated; AWQ is disabled"
        echo "  ./dev perplexity qcn"
        echo "  ./dev trace-diff /tmp/expected.log /tmp/actual.log --events mark,tensor"
        echo "  ./dev trace-diff /tmp/expected.log /tmp/actual.log --components config_contract --contexts reference_inventory --show-window 3"
        echo "  ./dev trace-diff /tmp/expected.log /tmp/actual.log --components decode --resync-window 6"
        echo "  ./dev trace-diff /tmp/expected.log /tmp/actual.log --components decode --family-resync-window 3"
        echo "  ./dev test qcn"
        echo "  ./dev network 8012"
        echo "  ./dev python -m krasis.launcher"
        ;;
    kill)       do_kill ;;
    manager)    verify_repo_imports; exec_repo_python -m krasis.launcher manager "$@" ;;
    chat)       verify_repo_imports; exec_repo_python -m krasis.chat "$@" ;;
    sanity)
        verify_repo_imports
        run_dir=$(create_run_dir "dev-sanity")
        info "Run dir: $run_dir"
        KRASIS_RUN_DIR="$run_dir" KRASIS_RUN_TYPE="dev-sanity" exec_repo_python -m krasis.chat --sanitytest "$@"
        ;;
    install)
        info "Installing krasis command to ~/.local/bin/krasis..."
        mkdir -p "$HOME/.local/bin"
        # Symlink so installed command is always identical to repo script
        rm -f "$HOME/.local/bin/krasis"
        ln -s "$SCRIPT_DIR/krasis" "$HOME/.local/bin/krasis"
        # Clean up any stale pip/venv artifacts
        rm -f "$HOME/.local/bin/krasis-chat" "$HOME/.local/bin/krasis-setup"
        rm -rf "$HOME/.krasis/venv"
        ok "Installed. 'krasis' command symlinked to $SCRIPT_DIR/krasis"
        ;;
    *)
        err "Unknown command: $cmd
  Run ./dev help for usage."
        ;;
esac