karnel-termux 4.17.45 → 4.18.1

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="https://github.com/karnel-termuxOFC/karnel-termux">
-    <img src="https://img.shields.io/badge/version-4.17.45-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.18.1-0078D4?style=for-the-badge" alt="Version">
   </a>
   <a href="https://www.npmjs.com/package/karnel-termux">
     <img src="https://img.shields.io/npm/v/karnel-termux?style=for-the-badge&logo=npm&color=cb3837" alt="npm">
@@ -78,7 +78,7 @@ Why it's great:
 ### Via checksummed GitHub release (recommended)
 
 ```bash
-version=4.17.45
+version=4.18.1
 tmpdir=$(mktemp -d) && trap 'rm -rf "$tmpdir"' EXIT
 base="https://github.com/karnel-termuxOFC/karnel-termux/releases/download/v$version"
 curl -fsSL "$base/karnel-termux-install.sh" -o "$tmpdir/karnel-termux-install.sh"

package/docs/CHANGELOG.md

@@ -6,6 +6,20 @@ layout: base
 
 # Documentation Changelog
 
+## 4.18.1
+
+- **The ladder is reachable from every installer, not just Freebuff:** `compat_adapt_installed()` is the single entry point behind `_tool_compat_adapt` (utils/tools.sh), `_ai_tool_compat_adapt` (tools/ai/all.sh) and the post-install loop in `cli/commands/install.sh`, so it already covered all 16 categories — but it only ever called `compat_wrap()`, which stops at the loader tier. Tiers 3 (glibc userland) and 4 (proot FHS root) were reachable solely from Freebuff's `compat_adapt()` call, which is why no other tool could ever climb above tier 2. It now escalates after wrapping, and re-probes wrappers already on disk so a tool that stops starting at its current tier climbs on the next install or update instead of staying broken behind a launcher nobody re-examines.
+- **No cost for what already runs:** native binaries, scripts and plain files still return before any probe, so the added `--version` probe applies only to tools that actually needed a wrapper — the hundreds of native entries in a Termux prefix are untouched.
+- **Tests:** three new cases pin the behaviour (ladder reachable from the installer path, existing wrappers re-evaluated, natives never probed — the last with a positive control so its zero cannot pass vacuously). Each was proven to fail first: dropping the escalation fails 3 cases, probing natives fails the efficiency case alone, removing tier 3's `PATH` export fails the 3 ladder cases, and letting tier 4 write a wrapper without a root fails the refusal case alone. The suite runs 20 cases in 7 seconds.
+
+## 4.18.0
+
+- **Three-tier compatibility layer:** a foreign glibc binary is no longer handled by one fixed trick. `compat_adapt` wraps, probes and climbs to the cheapest tier that actually starts the tool — the glibc loader alone (free, installs nothing), the glibc userland (`$PREFIX/glibc/bin`, 383 glibc tools, prepended to `PATH` together with the glibc exec shim so child processes resolve the same way), or proot over a synthetic `/lib`, `/usr` and `/etc` assembled from the sysroot already on the device. That last tier replaces `proot-distro install ubuntu` for binaries that merely hardcode an absolute path, and it downloads nothing. A tier that cannot be reached is refused before the wrapper is written, so `proot -r ''` can never ship, and every step unwraps back to `<path>.karnel-real`.
+- **Shebang repair that survives symlinks:** `compat_fix_shebang` edits the target of a link rather than the link itself. `sed -i` unlinks its argument, so repairing `$PREFIX/bin/npm` used to replace that symlink with a detached copy of `npm-cli.js` whose relative `require('../lib/cli.js')` then resolved from `$PREFIX/bin` — one broken `npm` traded for another. The same bug was live in `karnel doctor`, whose `_fix_npm_shebangs` ran `sed -i` over every entry in `$PREFIX/bin`.
+- **`npm` and the CLIs on top of it were dead on arrival:** Android has no `/usr`, so `#!/usr/bin/env node` exits 126 with `bad interpreter` even though node is installed, and none of the three `termux-exec` preloads intercepts the kernel's shebang resolution. `npm`, `npx`, `kc`, `kcode`, `keel`, `snyk`, `httptmuxd`, `gdbus-codegen`, `glib-genmarshal` and `glib-mkenums` all now resolve to their Termux interpreter; `$PREFIX/bin` reports 0 unresolvable shebangs.
+- **Doctor:** the check asks whether the interpreter path exists instead of grepping for the literal `#!/usr/bin/env`, so a stale absolute path is caught and a resolvable `env` line is left alone; the fix delegates to the compatibility layer; a new *Android Compatibility Layer* section reports the glibc sysroot, how many tools are riding a wrapper, whether proot is reachable for the FHS tier, and any shebang that still does not resolve.
+- **Tests:** `tests/android-compat.sh` covers classification, wrapping, re-tiering without disturbing the parked original, escalation, falling back when no tier helps, building the FHS root exactly once, refusing tier 4 without a root, shebang repair through a symlink, and agreement with `readelf` (17 cases).
+
 ## 4.17.45
 
 - **npm on a real Termux host:** every npm call goes through `karnel_npm()`, which runs npm through `node` when its `#!/usr/bin/env node` shebang cannot be executed (Termux ships no `/usr`, so the kernel answered `bad interpreter`) and retries with `--force` only on `EBADPLATFORM`. The remaining bare `npm install/uninstall/update/view/ls` calls in the installers were converted; guests inside proot keep plain npm.

package/karnel/RELEASE_COMMIT

@@ -1 +1 @@
-29fb2632bc7558b002e10d68272418bcb4450cb1
+a046270feccbad261fd440a040fb960250c8e699

package/karnel/cli/commands/doctor/fixes.sh

@@ -4,6 +4,7 @@
 import "@/utils/log"
 import "@/utils/colors"
 import "@/utils/install"
+import "@/utils/compat"
 
 _fix_storage() {
   termux-setup-storage 2>/dev/null
@@ -219,19 +220,13 @@ _fix_pip_check() {
 }
 
 _fix_npm_shebangs() {
-  local fixed=0
-  for f in "$PREFIX/bin/"*; do
-    [[ -f "$f" ]] || continue
-    local shebang
-		shebang=$(head -1 "$f" 2>/dev/null | tr -d '\0\r' | xargs)
-		if [[ "$shebang" == "#!/usr/bin/env node" ]]; then
-      sed -i "1s|^.*$|#!$PREFIX/bin/node|" "$f" && ((fixed++))
-    elif [[ "$shebang" == "#!/usr/bin/env bash" ]] || [[ "$shebang" == "#!/usr/bin/env sh" ]]; then
-      sed -i "1s|^.*$|#!$PREFIX/bin/bash|" "$f" && ((fixed++))
-    elif [[ "$shebang" == "#!/usr/bin/env python3" ]] || [[ "$shebang" == "#!/usr/bin/env python" ]]; then
-      sed -i "1s|^.*$|#!$PREFIX/bin/python3|" "$f" && ((fixed++))
-    fi
-  done
+  # Delegates to the compatibility layer instead of sed-ing $PREFIX/bin
+  # itself: most of those entries are symlinks into node_modules, and
+  # `sed -i` unlinks its argument, which would replace npm's symlink with a
+  # detached copy whose relative require() resolves from the wrong directory.
+  # compat_fix_shebang edits the target and copes with any interpreter, not
+  # just node/bash/python3.
+  compat_fix_shebangs "$PREFIX/bin" >/dev/null 2>&1
   return 0
 }
 

package/karnel/cli/commands/doctor.sh

@@ -2,6 +2,7 @@
 
 import "@/utils/log"
 import "@/utils/colors"
+import "@/utils/compat"
 
 doctor_main() {
   local subcommand="${1:-termux}"
@@ -769,19 +770,31 @@ doctor_termux() {
   separator_section "Binary & Shebang Health"
   echo
 
-  # Check for bad shebangs (#!/usr/bin/env) in PREFIX/bin (fast grep)
+  # Interpreters that do not exist on this device. Android has no /usr, so
+  # every "#!/usr/bin/env node" the kernel meets answers ENOENT and the shell
+  # reports 126, even though node itself is installed. The check is on the
+  # interpreter path rather than on the literal "#!/usr/bin/env" prefix, so a
+  # shebang pointing at a stale absolute path is caught too.
   local bad_shebangs=0
-  local bad_files
-  bad_files=$(timeout 10 rg -l "^#!/usr/bin/env" "$PREFIX/bin/" 2>/dev/null || true)
-  if [[ -n "$bad_files" ]]; then
-    bad_shebangs=$(echo "$bad_files" | wc -l)
-    log_warn "$bad_shebangs binary(s) with #!/usr/bin/env — will fail on Termux"
-    echo "$bad_files" | while IFS= read -r f; do
-      list_item "$(basename "$f")"
+  bad_shebangs="$(timeout 20 compat_count_broken_shebangs "$PREFIX/bin" 2>/dev/null)"
+  bad_shebangs="${bad_shebangs:-0}"
+  if [[ "$bad_shebangs" =~ ^[0-9]+$ ]] && ((bad_shebangs > 0)); then
+    log_warn "$bad_shebangs binary(s) point at an interpreter that does not exist"
+    local sb_file sb_name
+    for sb_file in "$PREFIX/bin"/*; do
+      [[ -f "$sb_file" && -r "$sb_file" ]] || continue
+      IFS= read -r sb_head <"$sb_file" 2>/dev/null || continue
+      [[ "$sb_head" == '#!'* ]] || continue
+      sb_name="${sb_head#\#!}"
+      sb_name="${sb_name# }"
+      sb_name="${sb_name%% *}"
+      if [[ "$sb_name" == /* && ! -x "$sb_name" ]]; then
+        list_item "$(basename "$sb_file") ($sb_name)"
+      fi
     done
     ((warnings++))
-    fix_commands+=("karnel install npm 2>/dev/null || true")
-    fix_descriptions+=("Reinstall npm tools to fix shebangs")
+    fix_commands+=("karnel doctor --fix")
+    fix_descriptions+=("Repoint $bad_shebangs shebang(s) at their Termux interpreter")
     fix_callbacks+=("_fix_npm_shebangs")
   else
     log_success "All binaries have valid shebangs"
@@ -963,6 +976,53 @@ doctor_termux() {
     log_info "proot not installed (optional)"
   fi
 
+  # ===== ANDROID COMPATIBILITY LAYER =====
+  echo
+  separator_section "Android Compatibility Layer"
+  echo
+  # A foreign (glibc) binary cannot be started by the Android kernel at all;
+  # karnel hands it to the loader from the glibc sysroot instead. This block
+  # reports which of the three tiers are reachable and how many tools are
+  # currently riding them.
+  local compat_root compat_wrapped=0 compat_entry compat_fixable
+  if compat_glibc_ready; then
+    compat_root="$(compat_glibc_root)"
+    log_success "glibc sysroot: available ($compat_root)"
+  else
+    log_info "glibc sysroot: not installed (required to run glibc-only tools)"
+    fix_commands+=("pkg install -y glibc-repo glibc")
+    fix_descriptions+=("Install the glibc sysroot so foreign binaries can run")
+    fix_callbacks+=("_fix_pkg_install")
+  fi
+
+  for compat_entry in "$PREFIX/bin"/*; do
+    [[ -f "$compat_entry" ]] || continue
+    if _compat_is_wrapper "$compat_entry"; then
+      compat_wrapped=$((compat_wrapped + 1))
+    fi
+  done
+  if ((compat_wrapped > 0)); then
+    log_success "$compat_wrapped tool(s) running through the compatibility wrapper"
+  else
+    log_info "no tool on PATH currently needs a compatibility wrapper"
+  fi
+
+  if compat_proot_available; then
+    log_success "proot: available (tier 4 for binaries that hardcode /usr or /etc)"
+  elif command -v proot >/dev/null 2>&1; then
+    log_info "proot: installed, but the FHS root could not be assembled"
+  else
+    log_info "proot: not installed (optional; only needed for absolute-path tools)"
+  fi
+
+  compat_fixable="$(timeout 20 compat_count_broken_shebangs "$PREFIX/bin" 2>/dev/null)"
+  compat_fixable="${compat_fixable:-0}"
+  if [[ "$compat_fixable" =~ ^[0-9]+$ ]] && ((compat_fixable > 0)); then
+    log_warn "$compat_fixable shebang(s) still point at a missing interpreter"
+  else
+    log_success "every shebang in $PREFIX/bin resolves"
+  fi
+
   # ===== TERMUX:API =====
   echo
   separator_section "Termux:API"

package/karnel/cli/commands/install.sh

@@ -3,6 +3,7 @@
 import "@/utils/log"
 import "@/utils/colors"
 import "@/utils/tools"
+import "@/utils/compat"
 
 install_main() {
 
@@ -244,6 +245,10 @@ _install_specific_tools() {
               fi
             done
             if [ -n "$found_bin" ]; then
+              for _bin in "${_bin_list[@]}"; do
+                declare -f compat_adapt_installed >/dev/null 2>&1 &&
+                  compat_adapt_installed "$_bin" || true
+              done
               ((installed_count++))
             else
               log_warn "$tool: binary not found in PATH after installation"

package/karnel/cli/commands/reinstall.sh

@@ -3,6 +3,7 @@
 import "@/utils/log"
 import "@/utils/colors"
 import "@/utils/tools"
+import "@/utils/compat"
 
 reinstall_main() {
 

package/karnel/cli/commands/update.sh

@@ -4,6 +4,7 @@ import "@/utils/npm"
 import "@/utils/log"
 import "@/utils/colors"
 import "@/utils/tools"
+import "@/utils/compat"
 
 update_main() {
 

package/karnel/tools/ai/all.sh

@@ -136,6 +136,25 @@ _validate_tool_installed() {
 
 # ---- FUNÇÕES DE LOTE ----
 
+# Runs the Android compatibility layer over the binaries an AI tool puts on
+# PATH. glibc-only binaries cannot be exec'd here - their PT_INTERP points at
+# /lib/ld-linux-*.so.1, which Android does not have - until compat wraps them.
+_ai_tool_compat_adapt() {
+  local id="$1" entry entry_id name bins
+  local -a bin_list=()
+  declare -f compat_adapt_installed >/dev/null 2>&1 || return 0
+  for entry in "${AI_TOOLS_REGISTRY[@]}"; do
+    IFS=':' read -r entry_id name bins <<<"$entry"
+    [[ "$entry_id" == "$id" ]] || continue
+    IFS=',' read -ra bin_list <<<"$bins"
+    for entry_id in "${bin_list[@]}"; do
+      compat_adapt_installed "$entry_id" || true
+    done
+    break
+  done
+  return 0
+}
+
 _ai_tool_registered() {
   local wanted="$1"
   local entry id
@@ -184,13 +203,21 @@ _run_ai_tool_action() {
 
   if [[ "$action" != "reinstall" ]]; then
     declare -f "$func_name" &>/dev/null || return 127
-    "$func_name"
-    return $?
+    local rc=0
+    "$func_name" || rc=$?
+    if (( rc == 0 || rc == 2 )) && [[ "$action" == "install" || "$action" == "update" ]]; then
+      _ai_tool_compat_adapt "$id"
+    fi
+    return "$rc"
   fi
 
   if declare -f "$func_name" &>/dev/null; then
-    "$func_name"
-    return $?
+    local rc=0
+    "$func_name" || rc=$?
+    if (( rc == 0 )); then
+      _ai_tool_compat_adapt "$id"
+    fi
+    return "$rc"
   fi
 
   local uninstall_fn="uninstall_${id//-/_}"

package/karnel/tools/ai/freebuff/install.sh

@@ -1,13 +1,28 @@
 #!/usr/bin/env bash
 import "@/utils/npm"
 import "@/utils/npm-shebang"
+import "@/utils/compat"
 
 import "@/utils/log"
+import "@/utils/install"
 import "@/utils/version"
 
+# Freebuff ships its launcher on npm and fetches the real runtime (a Bun
+# standalone, ~50 MB) on first use. That runtime is a glibc ELF whose
+# PT_INTERP, /lib/ld-linux-aarch64.so.1, Android does not have, so the kernel
+# refuses to start it with ENOENT ("bad interpreter"). The fix is to hand it
+# to the glibc loader instead - and never to patchelf it, which grows the image
+# by a PT_LOAD segment and makes it SIGSEGV.
+FREEBUFF_ORIGIN="${FREEBUFF_ORIGIN:-https://codebuff.com}"
+FREEBUFF_DATA_DIR="${FREEBUFF_DATA_DIR:-$HOME/.config/manicode}"
+# Line 2 of the generated npm entry wrapper, used to recognise our own copy.
+FREEBUFF_ENTRY_MARKER="# karnel-freebuff-entry"
+
 install_freebuff() {
   if command -v freebuff &>/dev/null; then
     log_info "Freebuff is already installed"
+    _fix_freebuff_runtime || true
+    _install_freebuff_entry || true
     return 2
   fi
 
@@ -25,21 +40,224 @@ install_freebuff() {
   }
   _fix_npm_shebang "freebuff" || return 1
   _fix_freebuff_shebang || return 1
+  _fix_freebuff_runtime || return 1
+  _install_freebuff_entry || return 1
   log_success "Freebuff installed"
 }
 
 _fix_freebuff_shebang() {
-  local binary
+  local binary real
   binary="$(command -v freebuff 2>/dev/null)"
   if [[ -z "$binary" || ! -f "$binary" ]]; then
     log_error "Freebuff binary was not found after npm operation"
     return 1
   fi
-  if command -v termux-fix-shebang &>/dev/null; then
-    termux-fix-shebang "$binary" &>/dev/null || return 1
+  real="$(readlink -f -- "$binary" 2>/dev/null || printf '%s' "$binary")"
+  [[ -f "$real" ]] || return 0
+  # 2 = already runnable, 1 = nothing to resolve; neither is fatal here,
+  # _fix_npm_shebang has already normalised the npm shim.
+  compat_fix_shebang "$real" || true
+  return 0
+}
+
+# Prepares the runtime: fetch it when it is missing, wrap it so the glibc
+# loader can start it, and replace it when the copy on disk no longer runs.
+_fix_freebuff_runtime() {
+  local data_bin="$FREEBUFF_DATA_DIR/freebuff"
+  if [[ ! -e "$data_bin" ]]; then
+    if ! _fetch_freebuff_binary "$data_bin"; then
+      log_warn "Freebuff runtime was not fetched (offline?); it will be prepared on the next install"
+      return 0
+    fi
+  fi
+  compat_adapt "$data_bin"
+  if _freebuff_binary_runs "$data_bin"; then
+    return 0
+  fi
+  log_info "Freebuff runtime does not run; downloading it again"
+  if ! _replace_freebuff_binary "$data_bin"; then
+    log_error "Freebuff runtime could not be repaired"
+    return 1
+  fi
+  if ! _freebuff_binary_runs "$data_bin"; then
+    log_error "Freebuff runtime still does not run after repair"
+    return 1
+  fi
+  return 0
+}
+
+_freebuff_binary_runs() {
+  local bin="$1" rc=0
+  [[ -e "$bin" ]] || return 1
+  # The braces redirect the shell itself: bash prints "Segmentation fault" to
+  # its own stderr, not to the child's, so `2>/dev/null` on the command alone
+  # would still leak the crash of a damaged runtime into the install output.
+  { timeout 30 "$bin" --version >/dev/null 2>&1; rc=$?; } 2>/dev/null
+  ((rc == 0))
+}
+
+_freebuff_target_key() {
+  case "$(uname -m)" in
+  aarch64 | arm64) printf 'linux-arm64\n' ;;
+  x86_64 | amd64) printf 'linux-x64\n' ;;
+  *) return 1 ;;
+  esac
+}
+
+_freebuff_package_json() {
+  local bin candidate
+  if bin="$(command -v freebuff 2>/dev/null)" && [[ -n "$bin" ]]; then
+    bin="$(readlink -f -- "$bin" 2>/dev/null || printf '%s' "$bin")"
+    candidate="$(dirname -- "$bin")/package.json"
+    if [[ -f "$candidate" ]]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  fi
+  candidate="$(karnel_npm root -g 2>/dev/null | tail -n 1)/freebuff/package.json"
+  if [[ -f "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+    return 0
+  fi
+  return 1
+}
+
+# Downloads and checksum-verifies the published runtime, then moves it into
+# place. The archive digest comes from the npm package's own binaryChecksums
+# map, so a substituted download is rejected before anything is executed.
+_fetch_freebuff_binary() {
+  local dest="$1"
+  local pkg_json version key expected url archive stage
+  pkg_json="$(_freebuff_package_json)" || {
+    log_error "freebuff package metadata not found"
+    return 1
+  }
+  version="$(node -p "require('$pkg_json').version" 2>/dev/null)"
+  [[ -n "$version" ]] || {
+    log_error "Could not read the freebuff version"
+    return 1
+  }
+  key="$(_freebuff_target_key)" || {
+    log_error "Freebuff has no runtime for $(uname -m)"
+    return 1
+  }
+  expected="$(node -p "(require('$pkg_json').binaryChecksums||{})['$key']||''" 2>/dev/null)"
+  [[ "$expected" =~ ^[0-9a-f]{64}$ ]] || {
+    log_error "No published checksum for freebuff $key"
+    return 1
+  }
+  url="$FREEBUFF_ORIGIN/api/releases/download/$version/freebuff-$key.tar.gz"
+  archive="$(mktemp "${TMPDIR:-$PREFIX/tmp}/freebuff.XXXXXX")" || return 1
+  if ! curl --fail --silent --show-error --location --retry 3 "$url" \
+    -o "$archive" &>>"$LOG_FILE"; then
+    rm -f -- "$archive"
+    log_error "Failed to download the Freebuff runtime"
+    return 1
+  fi
+  if ! verify_sha256 "$archive" "$expected"; then
+    rm -f -- "$archive"
+    return 1
+  fi
+  stage="$(mktemp -d "${TMPDIR:-$PREFIX/tmp}/freebuff-stage.XXXXXX")" || {
+    rm -f -- "$archive"
+    return 1
+  }
+  if ! safe_extract_tar "$archive" "$stage"; then
+    rm -rf -- "$stage" "$archive"
+    return 1
+  fi
+  rm -f -- "$archive"
+  if [[ ! -f "$stage/freebuff" ]]; then
+    rm -rf -- "$stage"
+    log_error "Freebuff runtime missing from the archive"
+    return 1
+  fi
+  chmod 755 -- "$stage/freebuff" || {
+    rm -rf -- "$stage"
+    return 1
+  }
+  if [[ -e "$dest" || -L "$dest" ]]; then
+    rm -f -- "$dest" "$dest.karnel-real" || {
+      rm -rf -- "$stage"
+      return 1
+    }
+  fi
+  mv -f -- "$stage/freebuff" "$dest" || {
+    rm -rf -- "$stage"
+    return 1
+  }
+  rm -rf -- "$stage"
+  return 0
+}
+
+# Swaps a runtime that no longer runs for a freshly verified copy.
+_replace_freebuff_binary() {
+  local data_bin="$1"
+  local staging
+  staging="$(mktemp -d "${TMPDIR:-$PREFIX/tmp}/freebuff-repair.XXXXXX")" || return 1
+  if ! _fetch_freebuff_binary "$staging/freebuff"; then
+    rm -rf -- "$staging"
+    return 1
+  fi
+  rm -f -- "$data_bin" "$data_bin.karnel-real" || {
+    rm -rf -- "$staging"
+    return 1
+  }
+  mv -f -- "$staging/freebuff" "$data_bin" || {
+    rm -rf -- "$staging"
+    return 1
+  }
+  rm -rf -- "$staging"
+  compat_adapt "$data_bin"
+  return 0
+}
+
+# npm links $PREFIX/bin/freebuff to a launcher that derives its release
+# target from `process.platform`, which Node reports as "android" here - so it
+# refuses every download with `Unsupported platform: android arm64` before the
+# runtime is ever spawned. The launcher already honours FREEBUFF_BINARY_TARGET,
+# so the entry is replaced by a wrapper that exports the supported key; no
+# launcher code is patched and the real entry point keeps working.
+_install_freebuff_entry() {
+  local entry="$PREFIX/bin/freebuff" key real tmp
+  key="$(_freebuff_target_key)" || {
+    log_error "Freebuff has no runtime for $(uname -m)"
+    return 1
+  }
+  if [[ -L "$entry" ]]; then
+    real="$(readlink -f -- "$entry")"
+  elif [[ -f "$entry" ]] && head -n 4 -- "$entry" | grep -qF "$FREEBUFF_ENTRY_MARKER"; then
+    real="$(sed -n 's/^# real: //p' -- "$entry" | head -n 1)"
   else
-    sed -i '1s|#!/usr/bin/env|#!/data/data/com.termux/files/usr/bin/env|' "$binary" || return 1
+    real="$(karnel_npm root -g 2>/dev/null | tail -n 1)/freebuff/index.js"
   fi
+  if [[ -z "$real" || ! -f "$real" ]]; then
+    log_error "The freebuff launcher was not found"
+    return 1
+  fi
+  tmp="$entry.tmp.$$"
+  {
+    printf '%s\n' "#!$PREFIX/bin/bash"
+    printf '%s\n' "$FREEBUFF_ENTRY_MARKER"
+    printf '%s\n' "# real: $real"
+    printf '%s\n' "# Node reports process.platform \"android\" on Termux, so the launcher"
+    printf '%s\n' "# resolves its release target to android-arm64 and no build is published"
+    printf '%s\n' "# for it. The launcher honours this override, so no code is patched."
+    printf 'export FREEBUFF_BINARY_TARGET=%q\n' "$key"
+    printf 'exec %q %q "$@"\n' "$PREFIX/bin/node" "$real"
+  } >"$tmp" || {
+    rm -f -- "$tmp"
+    return 1
+  }
+  chmod 755 -- "$tmp" || {
+    rm -f -- "$tmp"
+    return 1
+  }
+  mv -f -- "$tmp" "$entry" || {
+    rm -f -- "$tmp"
+    return 1
+  }
+  return 0
 }
 
 uninstall_freebuff() {
@@ -69,6 +287,8 @@ _do_update_freebuff() {
     return 1
   }
   _fix_freebuff_shebang
+  _fix_freebuff_runtime
+  _install_freebuff_entry
 }
 
 reinstall_freebuff() {

package/karnel/utils/compat.sh

@@ -0,0 +1,550 @@
+#!/usr/bin/env bash
+
+# Android <-> glibc compatibility layer.
+#
+# Termux runs bionic, has no /usr and cannot start a stock Linux ELF: the
+# PT_INTERP recorded in the binary (/lib/ld-linux-aarch64.so.1) does not
+# exist, execve() answers ENOENT and the shell reports 127. The glibc-repo
+# package ships a full aarch64 glibc under $PREFIX/glibc whose loader is an
+# ordinary executable, so the very same binary starts natively when it is
+# handed to that loader instead of to the kernel:
+#
+#   ld-linux-aarch64.so.1 --library-path <sysroot>/lib:<dir of binary> <binary> [args]
+#
+# That form is preferred over `patchelf --set-interpreter`: patchelf grows Bun
+# standalone builds by a PT_LOAD segment and they then SIGSEGV, while the
+# loader form leaves the file byte-identical, needs no re-patching on upgrade
+# and is reversible. Everything below is idempotent so installers can call it
+# after install, after update and from doctor without bookkeeping.
+#
+# A bare loader is not always enough, so a wrapper can be escalated through
+# three tiers and the cheapest one that actually starts the binary wins:
+#
+#   2  loader        hand the ELF to the glibc loader. No userland, no
+#                    proot, no download. Covers most standalone binaries.
+#   3  glibc userland  same, plus $PREFIX/glibc/bin (383 glibc tools) in
+#                    PATH and the glibc termux-exec preload so that child
+#                    processes the tool spawns resolve the same way.
+#   4  proot         a synthetic FHS root assembled from the sysroot that
+#                    is already installed, bound at /lib, /usr and /etc.
+#                    This is what a tool needs when it hardcodes
+#                    /usr/share or /etc/... -- and unlike
+#                    `proot-distro install ubuntu` it downloads nothing.
+#
+# compat_adapt probes after wrapping and climbs the ladder; every step is
+# reversible through compat_unwrap.
+
+# Marker written on line 2 of every generated wrapper, tier on line 3.
+COMPAT_WRAPPER_MARKER="# karnel-compat-wrapper"
+COMPAT_WRAPPER_TIER_MARKER="# karnel-compat-tier:"
+COMPAT_TIER_LOADER=2
+COMPAT_TIER_USERLAND=3
+COMPAT_TIER_PROOT=4
+
+compat_glibc_root() { printf '%s\n' "${KARNEL_GLIBC_ROOT:-$PREFIX/glibc}"; }
+
+compat_glibc_libdir() { printf '%s\n' "$(compat_glibc_root)/lib"; }
+
+compat_glibc_bindir() { printf '%s\n' "$(compat_glibc_root)/bin"; }
+
+# Prints the path of a usable glibc dynamic loader, if one is installed.
+compat_glibc_loader() {
+  local libdir candidate
+  libdir="$(compat_glibc_libdir)"
+  [[ -d "$libdir" ]] || return 1
+  for candidate in "$libdir"/ld-*.so*; do
+    [[ -f "$candidate" && -x "$candidate" ]] || continue
+    printf '%s\n' "$candidate"
+    return 0
+  done
+  return 1
+}
+
+compat_glibc_ready() {
+  compat_glibc_loader >/dev/null || return 1
+  [[ -e "$(compat_glibc_libdir)/libc.so.6" ]]
+}
+
+# Installs the glibc sysroot on demand. Safe to call repeatedly.
+compat_glibc_ensure() {
+  compat_glibc_ready && return 0
+  if ! command -v pkg >/dev/null 2>&1; then
+    log_error "pkg is required to install the glibc compatibility layer"
+    return 1
+  fi
+  if [[ ! -f "$PREFIX/etc/apt/sources.list.d/glibc.list" ]]; then
+    if ! yes | pkg install glibc-repo &>>"${LOG_FILE:-/dev/null}"; then
+      log_error "Failed to install glibc-repo"
+      return 1
+    fi
+  fi
+  if [[ ! -e "$(compat_glibc_libdir)/libc.so.6" ]]; then
+    if ! yes | pkg install glibc &>>"${LOG_FILE:-/dev/null}"; then
+      log_error "Failed to install glibc"
+      return 1
+    fi
+  fi
+  if ! compat_glibc_ready; then
+    log_error "glibc sysroot is still missing after installation"
+    return 1
+  fi
+  return 0
+}
+
+compat_is_elf() {
+  local file="$1" magic
+  [[ -f "$file" && -r "$file" ]] || return 1
+  magic="$(head -c 4 -- "$file" 2>/dev/null)" || return 1
+  [[ "$magic" == $'\x7fELF' ]]
+}
+
+# Prints the PT_INTERP of an ELF, or nothing when it is statically linked.
+# readelf (binutils) rejects a bare `--`, so the path is normalised instead.
+compat_elf_interp() {
+  local file="$1" real
+  command -v readelf >/dev/null 2>&1 || return 1
+  real="$(readlink -f -- "$file" 2>/dev/null || printf '%s' "$file")"
+  readelf -l "$real" 2>/dev/null |
+    awk '/Requesting program interpreter/ { gsub(/\].*/, "", $NF); print $NF; exit }'
+}
+
+# glibc binaries link libc.so.6; bionic links libc.so. A fully static ELF has
+# neither and runs anywhere, so it is not classified as glibc.
+compat_is_glibc_elf() {
+  local file="$1" real
+  compat_is_elf "$file" || return 1
+  command -v readelf >/dev/null 2>&1 || return 1
+  real="$(readlink -f -- "$file" 2>/dev/null || printf '%s' "$file")"
+  readelf -d "$real" 2>/dev/null | grep -q 'Shared library: \[libc\.so\.6\]'
+}
+
+# native | glibc | script | missing | unknown
+compat_classify() {
+  local file="$1" first
+  [[ -e "$file" ]] || { printf 'missing\n'; return 0; }
+  if compat_is_elf "$file"; then
+    if compat_is_glibc_elf "$file"; then
+      printf 'glibc\n'
+    else
+      printf 'native\n'
+    fi
+    return 0
+  fi
+  if [[ -f "$file" && -r "$file" ]]; then
+    IFS= read -r first <"$file" || true
+    if [[ "$first" == '#!'* ]]; then
+      printf 'script\n'
+      return 0
+    fi
+  fi
+  printf 'unknown\n'
+}
+
+# Search path handed to the loader: the glibc sysroot first (proven to work),
+# then the binary's own directory so bundled shared objects still resolve. The
+# directory is skipped when it ships its own libc.so.6, which would be a bionic
+# libc and would take the glibc loader down with it.
+compat_library_path() {
+  local real="$1" sysroot dir out
+  sysroot="$(compat_glibc_libdir)"
+  dir="$(dirname -- "$real")"
+  out="$sysroot"
+  if [[ "$dir" != "$sysroot" && ! -e "$dir/libc.so.6" ]]; then
+    out="$out:$dir"
+  fi
+  printf '%s\n' "$out"
+}
+
+# Runs a tool through whichever layer can actually execute it. Used by the
+# generated wrappers and by doctor probes; never mutates the file.
+compat_exec() {
+  local file="$1"
+  shift
+  local kind real loader
+  kind="$(compat_classify "$file")"
+  case "$kind" in
+  missing)
+    log_error "compat: $file does not exist"
+    return 127
+    ;;
+  glibc)
+    loader="$(compat_glibc_loader)" || {
+      log_error "compat: no glibc loader; run 'pkg install glibc-repo glibc'"
+      return 127
+    }
+    real="$(readlink -f -- "$file" 2>/dev/null || printf '%s' "$file")"
+    exec "$loader" --library-path "$(compat_library_path "$real")" "$real" "$@"
+    ;;
+  *)
+    exec "$file" "$@"
+    ;;
+  esac
+}
+
+_compat_is_wrapper() {
+  local file="$1"
+  [[ -f "$file" ]] || return 1
+  head -n 2 -- "$file" 2>/dev/null | grep -qF "$COMPAT_WRAPPER_MARKER"
+}
+
+# The tier recorded on line 3 of a wrapper, or 0 when it predates tiers.
+compat_wrapper_tier() {
+  local file="$1" line
+  _compat_is_wrapper "$file" || { printf '0\n'; return 1; }
+  line="$(sed -n '3p' -- "$file" 2>/dev/null || true)"
+  case "$line" in
+  "$COMPAT_WRAPPER_TIER_MARKER"*)
+    line="${line#*:}"
+    # ${line#*:} keeps the space after the colon; strip it or the caller
+    # compares " 2" against 2 and the tiers never match.
+    line="${line#"${line%%[![:space:]]*}"}"
+    printf '%s\n' "$line"
+    ;;
+  *)
+    printf '2\n'
+    ;;
+  esac
+}
+
+# Builds (once) a synthetic filesystem root out of the glibc sysroot that is
+# already on the device. proot then maps /lib, /usr and /etc onto it, which is
+# everything a binary that hardcodes those paths needs -- for a few kilobytes
+# of symlinks instead of the hundreds of megabytes of a distro image.
+compat_proot_root() {
+  local root glibc lib
+  [[ -n "${KARNEL_DATA:-}" || -n "${KARNEL_COMPAT_ROOT:-}" ]] || return 1
+  root="${KARNEL_COMPAT_ROOT:-$KARNEL_DATA/compat-root}"
+  glibc="$(compat_glibc_root)"
+  lib="$(compat_glibc_libdir)"
+  [[ -d "$lib" && -d "$glibc" ]] || return 1
+  if [[ ! -f "$root/.ready" ]]; then
+    # Plain directories, not symlinks: every one of them is a bind target and
+    # proot needs the mount point to exist before it can cover it.
+    mkdir -p -- "$root/lib" "$root/lib64" "$root/usr/lib" "$root/usr/bin" \
+      "$root/usr/share" "$root/etc" "$root/tmp" "$root/home" "$root/proc" \
+      "$root/dev" || return 1
+    # Overlay the sysroot onto every path a stock Linux ELF is likely to open.
+    # proot resolves these as binds, so the host directories stay
+    # authoritative and nothing is copied.
+    printf '%s\n' "$glibc" >"$root/.ready" || return 1
+  fi
+  printf '%s\n' "$root"
+}
+
+compat_proot_available() {
+  command -v proot >/dev/null 2>&1 || return 1
+  compat_proot_root >/dev/null || return 1
+  return 0
+}
+
+# 0 when the binary starts, 1 when it demonstrably does not.
+# A timeout counts as success: the process was created, it simply did not
+# exit, which is exactly what an interactive tool does with --version.
+compat_probe() {
+  local wrapper="$1" out rc
+  [[ -x "$wrapper" ]] || return 1
+  out="$(timeout "${COMPAT_PROBE_TIMEOUT:-15}" "$wrapper" --version 2>&1)"
+  rc=$?
+  if ((rc == 124)); then
+    return 0
+  fi
+  if ((rc == 125 || rc == 126 || rc == 127 || rc >= 128)); then
+    return 1
+  fi
+  if printf '%s' "$out" | grep -qiE \
+    'bad interpreter|error while loading shared libraries|cannot execute binary|exec format error'; then
+    return 1
+  fi
+  return 0
+}
+
+_compat_write_wrapper() {
+  local wrapper="$1" real="$2" loader="$3" tier="${4:-$COMPAT_TIER_LOADER}"
+  local libpath bash_bin root="" proot_bin=""
+  libpath="$(compat_library_path "$real")"
+  bash_bin="$(command -v bash 2>/dev/null)" || bash_bin="$PREFIX/bin/bash"
+  # Resolve every tier-4 dependency before the redirect opens, otherwise a
+  # refusal below would leave a half-written file behind at $wrapper.
+  if [[ "$tier" == "$COMPAT_TIER_PROOT" ]]; then
+    root="$(compat_proot_root)" || return 1
+    proot_bin="$(command -v proot 2>/dev/null)" || return 1
+  fi
+  {
+    printf '%s\n' "#!$bash_bin"
+    printf '%s\n' "$COMPAT_WRAPPER_MARKER"
+    printf '%s\n' "$COMPAT_WRAPPER_TIER_MARKER $tier"
+    case "$tier" in
+    "$COMPAT_TIER_USERLAND")
+      # The $root/$PATH/$LD_PRELOAD below must reach the wrapper verbatim.
+      # shellcheck disable=SC2016
+      printf '%s\n' "# Tier 3: the glibc loader plus the glibc userland, so the child"
+      printf '%s\n' "# processes this tool spawns find the same coreutils and exec shim."
+      # Everything below is emitted literally and expanded by the wrapper at
+      # runtime, where "root" is the assignment written on the previous line.
+      printf 'root=%q\n' "$(compat_glibc_root)"
+      # shellcheck disable=SC2016  # expands in the wrapper
+      printf 'export PATH="$root/bin:$PATH"\n'
+      # The glibc termux-exec shim is optional; a preload pointing nowhere
+      # makes ld.so complain on every start of the tool.
+      # shellcheck disable=SC2016  # expands in the wrapper
+      printf 'if [ -f "$root/lib/libtermux-exec.so" ]; then\n'
+      # shellcheck disable=SC2016  # expands in the wrapper
+      printf '  export LD_PRELOAD="$root/lib/libtermux-exec.so${LD_PRELOAD:+:$LD_PRELOAD}"\n'
+      printf 'fi\n' 
+      printf 'exec %q --library-path %q %q "$@"\n' "$loader" "$libpath" "$real"
+      ;;
+    "$COMPAT_TIER_PROOT")
+      printf '%s\n' "# Tier 4: a synthetic FHS root built from the installed glibc sysroot,"
+      printf '%s\n' "# for binaries that open /usr/... or /etc/... by absolute path."
+      printf 'exec %q -r %q \\
+  -b %q:/lib -b %q:/lib64 -b %q:/usr/lib -b %q:/usr/bin \\
+  -b %q:/usr/share -b %q:/etc -b %q -b /dev -b /proc \\
+  %q "$@"\n' \
+        "$proot_bin" "$root" \
+        "$(compat_glibc_libdir)" "$(compat_glibc_libdir)" "$(compat_glibc_libdir)" \
+        "$(compat_glibc_bindir)" "$(compat_glibc_root)/share" "$(compat_glibc_root)/etc" \
+        "$PREFIX" "$real"
+      ;;
+    *)
+      printf '%s\n' "# Tier 2: runs a glibc ELF through the Termux glibc loader. Android has"
+      printf '%s\n' "# no /lib/ld-linux-*.so.1, so the kernel cannot start this binary itself."
+      printf 'exec %q --library-path %q %q "$@"\n' "$loader" "$libpath" "$real"
+      ;;
+    esac
+  } >"$wrapper" || return 1
+  chmod 755 -- "$wrapper" 2>/dev/null || true
+  return 0
+}
+
+# Replaces a glibc ELF with a launcher that hands it to the glibc loader.
+# The original is kept beside it as <path>.karnel-real, so the change is
+# reversible and survives `head`/`file` style checks. Returns 1 when the file
+# is not a glibc ELF (nothing to adapt) and 0 when it is already adapted.
+compat_wrap() {
+  local target="$1" tier="${2:-$COMPAT_TIER_LOADER}"
+  local real stored loader current
+  [[ -e "$target" || -L "$target" ]] || return 1
+  real="$(readlink -f -- "$target" 2>/dev/null || printf '%s' "$target")"
+  [[ -f "$real" ]] || return 1
+  if _compat_is_wrapper "$real"; then
+    current="$(compat_wrapper_tier "$real")"
+    [[ "$current" == "$tier" ]] && return 0
+    # Re-tier an existing wrapper: the original is already parked next to it,
+    # so only the launcher changes.
+    stored="$real.karnel-real"
+    [[ -e "$stored" ]] || return 1
+    loader="$(compat_glibc_loader)" || loader="/lib/ld-linux-aarch64.so.1"
+    _compat_write_wrapper "$real" "$stored" "$loader" "$tier" || return 1
+    log_info "compat: $real retiered to level $tier"
+    return 0
+  fi
+  compat_is_glibc_elf "$real" || return 1
+  loader="$(compat_glibc_loader)" || return 1
+  stored="$real.karnel-real"
+  if [[ -e "$stored" ]]; then
+    log_error "compat: refusing to overwrite existing $stored"
+    return 1
+  fi
+  if ! mv -- "$real" "$stored"; then
+    log_error "compat: could not move $real aside"
+    return 1
+  fi
+  if ! _compat_write_wrapper "$real" "$stored" "$loader" "$tier"; then
+    mv -- "$stored" "$real" 2>/dev/null || true
+    log_error "compat: could not write wrapper for $real"
+    return 1
+  fi
+  log_info "compat: $real now runs through the glibc loader"
+  return 0
+}
+
+compat_unwrap() {
+  local target="$1" real stored
+  real="$(readlink -f -- "$target" 2>/dev/null || printf '%s' "$target")"
+  _compat_is_wrapper "$real" || return 1
+  stored="$real.karnel-real"
+  [[ -e "$stored" ]] || return 1
+  rm -f -- "$real" || return 1
+  mv -- "$stored" "$real" || return 1
+  log_info "compat: restored $real"
+  return 0
+}
+
+# One-shot adaptation used after every install: wraps glibc binaries, leaves
+# native binaries, scripts and text files untouched, and never fails an
+# install over a tool that does not need adapting.
+compat_adapt() {
+  local target="$1"
+  [[ -e "$target" ]] || return 0
+  compat_wrap "$target" || return 0
+  compat_escalate "$target"
+  return 0
+}
+
+# Probes a wrapped binary and climbs to the cheapest tier that starts it.
+# Tier 2 is the default because it is free and needs nothing installed; tier 3
+# only adds environment, tier 4 needs proot. Falls back to the best tier that
+# was reachable so the caller always ends with the least capable wrapper that
+# still has a chance. Never returns non-zero: adaptation must not fail an
+# install.
+compat_escalate() {
+  local target="$1" real tier="$COMPAT_TIER_LOADER"
+  real="$(readlink -f -- "$target" 2>/dev/null || printf '%s' "$target")"
+  _compat_is_wrapper "$real" || return 0
+
+  compat_probe "$real" && return 0
+
+  if compat_wrap "$real" "$COMPAT_TIER_USERLAND" && compat_probe "$real"; then
+    log_info "compat: $real needs the glibc userland"
+    return 0
+  fi
+
+  if compat_proot_available && compat_wrap "$real" "$COMPAT_TIER_PROOT" && compat_probe "$real"; then
+    log_info "compat: $real needs an FHS root, running it under proot"
+    return 0
+  fi
+
+  # Nothing higher worked; drop back to the plain loader so the tool is at
+  # least in its original, reversible state.
+  compat_wrap "$real" "$COMPAT_TIER_LOADER" || true
+  log_warn "compat: $real does not start at any tier"
+  return 0
+}
+
+# Rewrites an unrunnable shebang onto a Termux interpreter. Android has no
+# /usr/bin/env, so `#!/usr/bin/env node` dies with "bad interpreter" even
+# though node itself is installed.
+# Returns 0 when the file was changed, 2 when it already ran, 1 when no
+# interpreter could be resolved.
+compat_fix_shebang() {
+  local file="$1" link="$1" first line interp prog args resolved new real
+  [[ -f "$file" && -r "$file" ]] || return 2
+  # Edit the target of a symlink, never the link itself: `sed -i` unlinks and
+  # re-creates its argument, so running it on $PREFIX/bin/npm would replace
+  # that symlink with a detached copy of npm-cli.js whose relative
+  # require('../lib/cli.js') then resolves from $PREFIX/bin instead of
+  # node_modules/npm. The target is what carries the shebang anyway.
+  if real="$(readlink -f -- "$file" 2>/dev/null)" && [[ -n "$real" && -f "$real" ]]; then
+    file="$real"
+  fi
+  [[ -f "$file" && -r "$file" ]] || return 2
+  IFS= read -r first <"$file" || true
+  [[ "$first" == '#!'* ]] || return 2
+  line="${first#\#!}"
+  line="${line# }"
+  interp="${line%% *}"
+  args="${line#"$interp"}"
+  args="${args# }"
+  if [[ "$interp" == */env ]]; then
+    prog="${args%% *}"
+    args="${args#"$prog"}"
+    args="${args# }"
+  else
+    prog="$interp"
+  fi
+  [[ -n "$prog" ]] || return 0
+  if [[ "$interp" == /* && -x "$interp" ]]; then
+    return 2
+  fi
+  resolved="$(command -v -- "$prog" 2>/dev/null || true)"
+  if [[ -z "$resolved" && "$prog" == */* ]]; then
+    resolved="$(command -v -- "${prog##*/}" 2>/dev/null || true)"
+  fi
+  [[ -n "$resolved" && -x "$resolved" ]] || return 1
+  [[ "$resolved" == "$interp" ]] && return 2
+  new="#!$resolved"
+  [[ -n "$args" ]] && new="$new $args"
+  new="${new//\\/\\\\}"
+  new="${new//&/\\&}"
+  new="${new//|/\\|}"
+  sed -i "1s|.*|$new|" -- "$file" || return 1
+  log_info "compat: fixed shebang of $link -> $new"
+  return 0
+}
+
+# Counts entries directly inside a directory whose interpreter path does not
+# exist, which is the condition the kernel rejects with "bad interpreter" and
+# exit 126. Read-only: nothing is opened for writing.
+compat_count_broken_shebangs() {
+  local dir="${1:-$PREFIX/bin}" file first interp total=0
+  [[ -d "$dir" ]] || { printf '0\n'; return 0; }
+  for file in "$dir"/*; do
+    [[ -f "$file" && -r "$file" ]] || continue
+    IFS= read -r first <"$file" 2>/dev/null || continue
+    [[ "$first" == '#!'* ]] || continue
+    interp="${first#\#!}"
+    interp="${interp# }"
+    interp="${interp%% *}"
+    [[ "$interp" == /* ]] || continue
+    [[ -x "$interp" ]] || total=$((total + 1))
+  done
+  printf '%s\n' "$total"
+}
+
+# Repairs every shebang below a directory that cannot run on Android.
+# Prints the number of files actually changed.
+compat_fix_shebangs() {
+  local root="$1" file rc fixed=0
+  [[ -d "$root" ]] || { printf '0\n'; return 0; }
+  while IFS= read -r -d '' file; do
+    rc=0
+    compat_fix_shebang "$file" || rc=$?
+    if ((rc == 0)); then
+      fixed=$((fixed + 1))
+    fi
+  done < <(find "$root" -type f -size -2M -exec grep -IlZ '^#!' {} + 2>/dev/null)
+  printf '%s\n' "$fixed"
+}
+
+# Adapts whatever a tool has just put on PATH. Wraps a glibc ELF so the
+# kernel can start it; leaves native binaries, scripts and text files alone.
+# Always returns 0: adaptation is an optimisation, never a reason to fail an
+# install or an update.
+compat_adapt_installed() {
+  local tool="$1" path real
+  path="$(command -v -- "$tool" 2>/dev/null)" || return 0
+  [[ -n "$path" ]] || return 0
+  real="$(readlink -f -- "$path" 2>/dev/null || printf '%s' "$path")"
+  [[ -f "$real" && -x "$real" ]] || return 0
+  if _compat_is_wrapper "$real"; then
+    # Already wrapped: re-probe it, so a binary that later stops starting at
+    # this tier climbs instead of being handed to the user as-is. Escalation
+    # is what every installer reaches through this function; only freebuff
+    # calls compat_adapt() directly, so without this the glibc userland and
+    # proot tiers would stay unreachable for the rest of the catalog.
+    compat_escalate "$real" || true
+    return 0
+  fi
+  if compat_is_glibc_elf "$real"; then
+    compat_wrap "$real" || true
+    compat_escalate "$real" || true
+  fi
+  return 0
+}
+
+# Human-readable one-liner for doctor output.
+compat_describe() {
+  local file="$1" kind interp real
+  real="$(readlink -f -- "$file" 2>/dev/null || printf '%s' "$file")"
+  if _compat_is_wrapper "$real"; then
+    case "$(compat_wrapper_tier "$real")" in
+    "$COMPAT_TIER_USERLAND") printf 'glibc (wrapped, loader + glibc userland)\n' ;;
+    "$COMPAT_TIER_PROOT")    printf 'glibc (wrapped, proot FHS root)\n' ;;
+    *)                       printf 'glibc (wrapped, runs through the glibc loader)\n' ;;
+    esac
+    return 0
+  fi
+  kind="$(compat_classify "$file")"
+  case "$kind" in
+  glibc)
+    if interp="$(compat_elf_interp "$file")" && [[ -n "$interp" && ! -e "$interp" ]]; then
+      printf 'glibc (cannot run: missing interpreter %s)\n' "$interp"
+    else
+      printf 'glibc\n'
+    fi
+    ;;
+  native | script | missing | unknown)
+    printf '%s\n' "$kind"
+    ;;
+  esac
+}

package/karnel/utils/tools.sh

@@ -148,6 +148,9 @@ _run_tool_lifecycle_action() {
     if (( rc == 0 && protected )); then
       _mark_tool_owned "$module" "$tool" || return 1
     fi
+    if (( rc == 0 )); then
+      _tool_compat_adapt "$tool"
+    fi
     return "$rc"
   fi
 
@@ -164,9 +167,21 @@ _run_tool_lifecycle_action() {
       rm -f "$marker" || return 1
     fi
   fi
+  if (( rc == 0 )) && [[ "$action" == "install" || "$action" == "update" ]]; then
+    _tool_compat_adapt "$tool"
+  fi
   return "$rc"
 }
 
+# Runs the Android compatibility layer over a tool that was just installed or
+# updated, when the layer has been imported. glibc-only binaries cannot be
+# exec'd on Android (their PT_INTERP does not exist) until they are wrapped.
+_tool_compat_adapt() {
+  declare -f compat_adapt_installed >/dev/null 2>&1 || return 0
+  compat_adapt_installed "$1" || true
+  return 0
+}
+
 _register_safe_reinstall_handlers() {
   local module="$1"
   shift

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karnel-termux",
-  "version": "4.17.45",
+  "version": "4.18.1",
   "description": "Modular Dev Environment for Termux — install languages, databases, AI agents, editors, and more with one command",
   "bin": {
     "karnel": "karnel/bin/karnel"