Harden GitNexus runtime fallback diagnostics

docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md

@@ -49,6 +49,12 @@ Use them with this posture:
 - the retained `mirrors/GitNexus` working reference already includes the newer
   stack-overflow prevention and cycle-hardening work recorded in its
   `CHANGELOG.md`
+- `HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1` can force the GitNexus wrappers to
+  skip the retained local CLI and go straight to the `npx` fallback on hosts
+  where the local mirror runtime is known to be unusable
+- `HYPERTWIST_GITNEXUS_DEBUG_LOCAL=1` keeps local GitNexus stderr visible so
+  retained-runtime problems can be diagnosed instead of being silently
+  suppressed during the normal fallback path
 - `scripts/run-hypertwist-sentrux-source-only.sh` now prefers a HyperTwist
   owned entry path first: `HYPERTWIST_SENTRUX_BINARY`, repo-local `./sentrux`
   or `./sentrux.exe`, then repo-local `tools/sentrux/bin/`, then a bootstrap
@@ -259,6 +265,34 @@ Latest later higher-dimensional proof refresh still on `2026-06-24`:
   - `generatedAtUtc: 2026-06-24T12:53:32.7234772Z`
   - `result: passed`
 
+Latest GitNexus wrapper hardening follow-up still on `2026-06-24`:
+
+- the retained local GitNexus CLI failure on this Linux host is now identified
+  explicitly instead of being hidden behind a vague fallback message:
+  `ERR_DLOPEN_FAILED` from `@ladybugdb/core` with an `invalid ELF header` in
+  the retained mirror runtime
+- `scripts/run-hypertwist-gitnexus-analyze.sh` and
+  `scripts/run-hypertwist-gitnexus-status.sh` now preflight the retained
+  runtime first, so the wrapper can explain that native-module mismatch before
+  it falls back to `npx -y gitnexus@latest`
+- the same wrappers now also support:
+  - `HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1` for a deliberate direct-fallback
+    path
+  - `HYPERTWIST_GITNEXUS_DEBUG_LOCAL=1` for unsuppressed retained-runtime
+    diagnostics
+- the current bounded source-only mirror then re-indexed successfully at:
+  - `16,245` nodes
+  - `38,118` edges
+  - `668` clusters
+  - `300` flows
+- `scripts/run-hypertwist-gitnexus-status.sh` then reported:
+  - `Indexed commit: f1fd833`
+  - `Current commit: f1fd833`
+  - `Status: up-to-date`
+- `scripts/run-hypertwist-sentrux-source-only.sh` stayed green afterward at:
+  - `Quality: 6139`
+  - all `7` rules passing
+
 Latest same-day browser/distribution continuity follow-up still on `2026-06-24`:
 
 - auth-entry, protected-route loading, dashboard auth health, and release-authority fallback states now share a more deliberate operator-facing recovery shape instead of scattering single-line warnings across public and protected surfaces

scripts/lib-hypertwist-gitnexus.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+hypertwist_gitnexus_probe_local_runtime() {
+  local repo_root="$1"
+  local local_gitnexus_dir="$repo_root/mirrors/GitNexus/gitnexus"
+  local local_gitnexus_cli="$local_gitnexus_dir/dist/cli/index.js"
+
+  if [[ ! -f "$local_gitnexus_cli" ]]; then
+    return 1
+  fi
+
+  if [[ "${HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI:-0}" == "1" ]]; then
+    echo "Skipping local retained GitNexus CLI because HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1." >&2
+    return 1
+  fi
+
+  local probe_output=""
+  local probe_exit=0
+
+  set +e
+  probe_output="$(
+    cd "$local_gitnexus_dir" &&
+    node --input-type=module -e 'try { await import("@ladybugdb/core"); } catch (error) { const code = error?.code ? `${error.code}: ` : ""; const message = error?.message || String(error); console.error(`${code}${message}`); process.exit(1); }' 2>&1
+  )"
+  probe_exit=$?
+  set -e
+
+  if [[ "$probe_exit" -eq 0 ]]; then
+    return 0
+  fi
+
+  probe_output="${probe_output//$'\n'/ }"
+  echo "Local retained GitNexus runtime is not usable on this host (${probe_output}). Falling back to npx gitnexus@latest." >&2
+  return 1
+}

scripts/run-hypertwist-gitnexus-analyze.sh

@@ -2,6 +2,7 @@
 set -euo pipefail
 
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$repo_root/scripts/lib-hypertwist-gitnexus.sh"
 local_gitnexus_cli="$repo_root/mirrors/GitNexus/gitnexus/dist/cli/index.js"
 analysis_root="$repo_root/.gitnexus-source-only-root"
 max_size_kb="${HYPERTWIST_GITNEXUS_MAX_FILE_SIZE_KB:-256}"
@@ -73,7 +74,7 @@ run_analysis_attempt() {
   local analysis_exit_code=0
 
   set +e
-  if [[ "$cli_kind" == "local" ]]; then
+  if [[ "$cli_kind" == "local" && "${HYPERTWIST_GITNEXUS_DEBUG_LOCAL:-0}" != "1" ]]; then
     run_analysis_command command 2>/dev/null
   else
     run_analysis_command command
@@ -127,12 +128,17 @@ npx_cli_command=(
 local_cli_command+=("$@")
 npx_cli_command+=("$@")
 
-if [[ -f "$local_gitnexus_cli" ]]; then
+local_cli_available=0
+if hypertwist_gitnexus_probe_local_runtime "$repo_root"; then
+  local_cli_available=1
+fi
+
+if [[ "$local_cli_available" -eq 1 ]]; then
   if run_analysis_attempt "local" "${local_cli_command[@]}"; then
     exit 0
   fi
 
-  echo "Local retained GitNexus CLI did not complete cleanly on this host. Falling back to npx gitnexus@latest." >&2
+  echo "Local retained GitNexus CLI passed the runtime probe but did not complete cleanly. Falling back to npx gitnexus@latest." >&2
 fi
 
 run_analysis_attempt "npx" "${npx_cli_command[@]}"

scripts/run-hypertwist-gitnexus-status.sh

@@ -2,6 +2,7 @@
 set -euo pipefail
 
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$repo_root/scripts/lib-hypertwist-gitnexus.sh"
 local_gitnexus_cli="$repo_root/mirrors/GitNexus/gitnexus/dist/cli/index.js"
 analysis_root="$repo_root/.gitnexus-source-only-root"
 
@@ -12,12 +13,21 @@ fi
 
 cd "$analysis_root"
 
-if [[ -f "$local_gitnexus_cli" ]]; then
-  if node "$local_gitnexus_cli" status "$@" 2>/dev/null; then
+local_cli_available=0
+if hypertwist_gitnexus_probe_local_runtime "$repo_root"; then
+  local_cli_available=1
+fi
+
+if [[ "$local_cli_available" -eq 1 ]]; then
+  if [[ "${HYPERTWIST_GITNEXUS_DEBUG_LOCAL:-0}" == "1" ]]; then
+    if node "$local_gitnexus_cli" status "$@"; then
+      exit 0
+    fi
+  elif node "$local_gitnexus_cli" status "$@" 2>/dev/null; then
     exit 0
   fi
 
-  echo "Local retained GitNexus CLI was not runnable on this host. Falling back to npx gitnexus@latest." >&2
+  echo "Local retained GitNexus CLI status failed after passing the runtime probe. Falling back to npx gitnexus@latest." >&2
 fi
 
 exec npx -y gitnexus@latest status "$@" 2>/dev/null