karnel-termux 4.18.1 → 4.18.3

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.18.1-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.18.3-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.18.1
+version=4.18.3
 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,21 @@ layout: base
 
 # Documentation Changelog
 
+## 4.18.3
+
+- **Every command that installs something now adapts what it put on PATH.** The dispatcher brackets `install`, `update`, `upgrade`, `reinstall`, `restore`, `plugin`, `supabase`, `deploy`, `voice`, `robin`, `pg`, `open` and `init` with a snapshot of the writable parts of PATH (`path|size|mtime` per entry) and afterwards adapts exactly the entries that appeared or changed. That closes the gap the registries could never close: an installer that never calls the compatibility layer, one that names a command its registry does not mention, and a file restored from an archive with its original timestamp all end up wrapped anyway. Sweeping the prefix instead was measured on this device at 51 seconds of `readelf` over 800 entries (and 875 seconds with `readelf -l`); diffing a snapshot takes 60 ms and touches nothing the command did not write. The exit code of the command is taken before adaptation and returned unchanged.
+- **The AI reinstall fallback adapts what it installed.** `_run_ai_tool_action` called `$install_fn` and returned without passing through its adapt call, so those binaries stayed unwrapped.
+- **An install can no longer report success for a command that does not start.** A device audit of all 169 catalogued tools found 21 installed and 147 absent — and exactly one of them dead: `$PREFIX/bin/freebuff` had been left as npm's shim, which exits 1 on Termux with "Unsupported platform: android arm64", while `karnel install ai --freebuff` still reported "already installed". Both paths of `install_freebuff` now prove the entry runs before returning, the same way `_fix_freebuff_runtime` already proves the runtime does. The audit is green afterwards: freebuff `0.2.22`, bun `1.4.2`, supabase `2.20.8`, zero broken.
+- **The compatibility suite is part of the test run.** `tests/android-compat.sh` had never been listed in `tests/run.sh`, so its cases only ever ran by hand; it now runs in `npm test` and in CI, and every other file under `tests/` was checked against the list while adding it.
+- **Tests.** Five new cases in `tests/android-compat.sh` (a binary created during a command, a binary rewritten in place, only the entries that changed, an exit code that cannot change, and the dispatcher wiring itself) plus two in `tests/ai-installer-hardening.sh` (a dead freebuff entry fails, a live one is accepted), taking the suites to 28 and 11 cases. Every branch was proven to fail first: dropping the adapt call fails 1 case, dropping the snapshot fails 1, making `compat_adapt_since` a no-op fails 2, removing the AI fallback's adapt fails 1, removing the already-installed verification fails 1, and turning that verification into a no-op fails both new freebuff cases.
+
+## 4.18.2
+
+- **Wrappers no longer hand a preload to glibc.** `login(1)` exports `LD_PRELOAD=$PREFIX/lib/libtermux-exec-ld-preload.so`, a bionic object; glibc's `ld.so` cannot load it, so every wrapped tool died before `main()` with `.../glibc/lib/libc.so: invalid ELF header`. Tier 3's own preload was fatal in the other direction: exporting the glibc `libtermux-exec.so` shim left every bionic child of the tool failing with `library "libc.so.6" not found`. Every wrapper now starts with `unset LD_PRELOAD`, and tier 3 exports `PATH` only.
+- **Wrappers written by older Karnels are refreshed.** `compat_wrapper_is_current()` checks the invariants the current code emits; when one is missing the wrapper is rewritten in place before `compat_escalate` probes it, so a stale launcher can no longer keep a tool pinned to a tier it no longer reaches.
+- **An orphaned parked copy no longer blocks adaptation.** Freebuff's own entry re-extracts its runtime in place, dropping a raw ELF over the wrapper and leaving `.karnel-real` behind; `compat_wrap` refused to touch that file, so the tool could never be adapted again — which is how `karnel install ai --freebuff` ended in "does not start at any tier" and then "Freebuff runtime still does not run after repair". Identical bytes are dropped (a 130 MB runtime is not copied to prove a point) and a different copy is parked as `.karnel-real.stale`.
+- **Tests.** Four new cases pin the behaviour — no wrapper hands a preload to the loader on tier 2 or tier 3, a launcher from an older karnel is refreshed in place, an orphaned parked copy does not block adaptation — in a suite of 23 cases running in 8 seconds. Every branch was proven to fail first: removing the `unset` fails 2 cases, restoring the tier 3 preload fails 5, dropping the refresh fails 1, restoring the refusal fails 1, and always discarding the orphan fails 1.
+
 ## 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.

package/karnel/RELEASE_COMMIT

@@ -1 +1 @@
-a046270feccbad261fd440a040fb960250c8e699
+4f1840c76ffba58dde286b506142fa1f9e5ee1d8

package/karnel/cli/karnel.sh

@@ -2,6 +2,7 @@
 
 import "@/utils/log"
 import "@/utils/colors"
+import "@/utils/compat"
 
 : "${KARNEL_VERSION:=unknown}"
 
@@ -67,8 +68,23 @@ _karnel_dispatch() {
 
   if [[ -f "$command_file" ]]; then
     import "@/cli/commands/$cmd"
+    # Every command that can put a binary on PATH is bracketed by a snapshot
+    # of PATH, and whatever changed inside it is adapted afterwards. That is
+    # what makes the layer cover *all* tools: an installer that never calls
+    # compat itself, one that names a command its registry does not mention,
+    # and one that restores a file from an archive all end up here anyway.
+    local compat_snap=""
+    case "$cmd" in
+    install | update | upgrade | reinstall | restore | plugin | supabase | deploy | voice | robin | pg | open | init)
+      compat_snap="$(compat_path_snapshot 2>/dev/null)" || compat_snap=""
+      ;;
+    esac
     "${cmd}_main" "$@"
-    return $?
+    local cmd_rc=$?
+    if [[ -n "$compat_snap" ]]; then
+      compat_adapt_since "$compat_snap" || true
+    fi
+    return "$cmd_rc"
   fi
 
   import "@/tools/plugins/install"

package/karnel/tools/ai/all.sh

@@ -230,6 +230,13 @@ _run_ai_tool_action() {
     return "$uninstall_rc"
   fi
   "$install_fn"
+  local install_rc=$?
+  # The fallback path never passes through _run_ai_tool_action's adapt call,
+  # so the binaries this install just wrote would stay unwrapped.
+  if ((install_rc == 0)); then
+    _ai_tool_compat_adapt "$id"
+  fi
+  return "$install_rc"
 }
 
 _all_ai_tools_action() {

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

@@ -23,6 +23,7 @@ install_freebuff() {
     log_info "Freebuff is already installed"
     _fix_freebuff_runtime || true
     _install_freebuff_entry || true
+    _verify_freebuff_entry || return 1
     return 2
   fi
 
@@ -42,6 +43,7 @@ install_freebuff() {
   _fix_freebuff_shebang || return 1
   _fix_freebuff_runtime || return 1
   _install_freebuff_entry || return 1
+  _verify_freebuff_entry || return 1
   log_success "Freebuff installed"
 }
 
@@ -96,6 +98,25 @@ _freebuff_binary_runs() {
   ((rc == 0))
 }
 
+# npm recreates its shim at $PREFIX/bin/freebuff on every global operation, and
+# that shim cannot start on Android - so an install can look successful while
+# the command itself is dead. Every path therefore proves the entry runs before
+# reporting success, the same way _fix_freebuff_runtime proves the runtime does.
+_verify_freebuff_entry() {
+  local entry rc=0
+  entry="$(command -v freebuff 2>/dev/null)"
+  if [[ -z "$entry" || ! -e "$entry" ]]; then
+    log_error "Freebuff is not on PATH after install"
+    return 1
+  fi
+  { timeout 30 "$entry" --version >/dev/null 2>&1; rc=$?; } 2>/dev/null
+  if ((rc != 0)); then
+    log_error "Freebuff does not run after install (exit $rc)"
+    return 1
+  fi
+  return 0
+}
+
 _freebuff_target_key() {
   case "$(uname -m)" in
   aarch64 | arm64) printf 'linux-arm64\n' ;;

package/karnel/utils/compat.sh

@@ -206,6 +206,19 @@ compat_wrapper_tier() {
   esac
 }
 
+# A wrapper written by an older karnel is still a wrapper, but it may hand
+# LD_PRELOAD straight to the glibc loader and die in a login shell. Returns 0
+# only when the launcher carries every invariant the current code emits.
+compat_wrapper_is_current() {
+  local file="$1"
+  _compat_is_wrapper "$file" || return 1
+  grep -qF 'unset LD_PRELOAD' -- "$file" 2>/dev/null || return 1
+  if grep -qF 'export LD_PRELOAD' -- "$file" 2>/dev/null; then
+    return 1
+  fi
+  return 0
+}
+
 # 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
@@ -273,24 +286,23 @@ _compat_write_wrapper() {
     printf '%s\n' "#!$bash_bin"
     printf '%s\n' "$COMPAT_WRAPPER_MARKER"
     printf '%s\n' "$COMPAT_WRAPPER_TIER_MARKER $tier"
+    # login(1) exports LD_PRELOAD=$PREFIX/lib/libtermux-exec-ld-preload.so,
+    # a bionic object. glibc's ld.so cannot load it and dies with
+    # "libc.so: invalid ELF header" on every start. The glibc termux-exec
+    # shim is equally unusable: every bionic child this tool spawns then
+    # fails with "library libc.so.6 not found". So no preload survives.
+    printf '%s\n' "unset LD_PRELOAD"
     case "$tier" in
     "$COMPAT_TIER_USERLAND")
-      # The $root/$PATH/$LD_PRELOAD below must reach the wrapper verbatim.
+      # The $root/$PATH 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."
+      printf '%s\n' "# processes this tool spawns find the same coreutils."
       # 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")
@@ -328,22 +340,43 @@ compat_wrap() {
   [[ -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.
+    if [[ "$current" == "$tier" ]] && compat_wrapper_is_current "$real"; then
+      return 0
+    fi
+    # Re-tier an existing wrapper, or refresh one written by an older karnel:
+    # 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"
+    if [[ "$current" == "$tier" ]]; then
+      log_info "compat: $real wrapper refreshed"
+    else
+      log_info "compat: $real retiered to level $tier"
+    fi
     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
+    # The file on disk is a real ELF, not our wrapper, while a parked copy is
+    # already sitting beside it: something outside karnel replaced the
+    # launcher (freebuff's node entry re-extracts its runtime in place) and
+    # orphaned the copy. The file on disk is authoritative now, so the parked
+    # copy is stale. A refusal here would leave the tool permanently
+    # unrunnable, so the copy is dropped when it is the same bytes and kept
+    # as .karnel-real.stale otherwise - a 130 MB runtime must not be copied
+    # just to prove a point.
+    if cmp -s -- "$stored" "$real" 2>/dev/null; then
+      rm -f -- "$stored" || return 1
+      log_warn "compat: dropped a stale parked copy for $real"
+    elif ! mv -f -- "$stored" "$stored.stale" 2>/dev/null; then
+      log_error "compat: could not move the stale parked copy for $real"
+      return 1
+    else
+      log_warn "compat: replaced a stale parked copy for $real"
+    fi
   fi
   if ! mv -- "$real" "$stored"; then
     log_error "compat: could not move $real aside"
@@ -392,6 +425,11 @@ compat_escalate() {
   real="$(readlink -f -- "$target" 2>/dev/null || printf '%s' "$target")"
   _compat_is_wrapper "$real" || return 0
 
+  # Refresh a launcher written by an older karnel before probing it: the probe
+  # has to exercise the wrapper we are about to ship, not the stale one.
+  compat_wrapper_is_current "$real" ||
+    compat_wrap "$real" "$(compat_wrapper_tier "$real")" || true
+
   compat_probe "$real" && return 0
 
   if compat_wrap "$real" "$COMPAT_TIER_USERLAND" && compat_probe "$real"; then
@@ -496,13 +534,11 @@ compat_fix_shebangs() {
   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
+# Adapts one resolved 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.
+_compat_adapt_path() {
+  local path="$1" real
   [[ -n "$path" ]] || return 0
   real="$(readlink -f -- "$path" 2>/dev/null || printf '%s' "$path")"
   [[ -f "$real" && -x "$real" ]] || return 0
@@ -522,6 +558,57 @@ compat_adapt_installed() {
   return 0
 }
 
+# Adapts whatever a tool has just put on PATH.
+compat_adapt_installed() {
+  local tool="$1" path
+  path="$(command -v -- "$tool" 2>/dev/null)" || return 0
+  [[ -n "$path" ]] || return 0
+  _compat_adapt_path "$path"
+}
+
+# Records every direct entry of the writable parts of PATH as
+# "path|size|mtime", printed to a temporary file. Taken before a command runs
+# so the layer can afterwards adapt exactly what that command touched.
+#
+# Sweeping the whole prefix instead would need readelf on every ELF, which
+# measures 60+ seconds over a Termux bin directory of 800 entries; diffing a
+# snapshot adapts only the handful of files that actually changed. It also
+# means no installer has to declare its binary names: a tool that installs a
+# command its registry does not mention is still covered, and a file restored
+# from an archive with its original mtime is caught by being a new path.
+compat_path_snapshot() {
+  local dir tmp
+  tmp="$(mktemp "${TMPDIR:-${KARNEL_CACHE:-/tmp}}/karnel-compat-snap.XXXXXX" 2>/dev/null)" || return 1
+  local IFS=':'
+  for dir in $PATH; do
+    [[ -n "$dir" && -d "$dir" && -w "$dir" ]] || continue
+    find "$dir" -maxdepth 1 \( -type f -o -type l \) -printf '%p|%s|%T@\n' 2>/dev/null || true
+  done | sort >"$tmp" || true
+  printf '%s\n' "$tmp"
+}
+
+# Adapts every PATH entry that appeared or changed since a snapshot, then
+# removes both files. Returns 0 unconditionally.
+compat_adapt_since() {
+  local snap="$1" tmp dir path
+  [[ -f "$snap" ]] || return 0
+  tmp="$(mktemp "${TMPDIR:-${KARNEL_CACHE:-/tmp}}/karnel-compat-now.XXXXXX" 2>/dev/null)" || {
+    rm -f -- "$snap"
+    return 0
+  }
+  local IFS=':'
+  for dir in $PATH; do
+    [[ -n "$dir" && -d "$dir" && -w "$dir" ]] || continue
+    find "$dir" -maxdepth 1 \( -type f -o -type l \) -printf '%p|%s|%T@\n' 2>/dev/null || true
+  done | sort >"$tmp" || true
+  while IFS= read -r path; do
+    [[ -n "$path" ]] || continue
+    _compat_adapt_path "$path" || true
+  done < <(comm -13 -- "$snap" "$tmp" 2>/dev/null | cut -d'|' -f1)
+  rm -f -- "$snap" "$tmp"
+  return 0
+}
+
 # Human-readable one-liner for doctor output.
 compat_describe() {
   local file="$1" kind interp real

package/package.json

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