karnel-termux 4.14.0 → 4.15.0

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="https://github.com/israelmarques1024-dotcom/karnel-termux">
-    <img src="https://img.shields.io/badge/version-4.14.0-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.15.0-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">
@@ -56,10 +56,15 @@ Created by **Israel Marques**.
 
 ## Installation
 
-### Via curl (recommended)
+### Via checksummed GitHub release (recommended)
 
 ```bash
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/israelmarques1024-dotcom/karnel-termux/main/install.sh)"
+version=4.15.0
+tmpdir=$(mktemp -d) && trap 'rm -rf "$tmpdir"' EXIT
+base="https://github.com/israelmarques1024-dotcom/karnel-termux/releases/download/v$version"
+curl -fsSL "$base/karnel-termux-install.sh" -o "$tmpdir/karnel-termux-install.sh"
+curl -fsSL "$base/karnel-termux-install.sh.sha256" -o "$tmpdir/karnel-termux-install.sh.sha256"
+(cd "$tmpdir" && sha256sum -c karnel-termux-install.sh.sha256) && bash "$tmpdir/karnel-termux-install.sh" --ref "v$version"
 ```
 
 ### Via npm
@@ -80,6 +85,10 @@ After installation, run:
 karnel
 ```
 
+In a terminal, running `karnel` without a command opens a curated menu for
+common workflows. The menu is not a complete inventory of CLI commands,
+aliases, or options; use `karnel help` and the CLI reference for the full set.
+
 ---
 
 ## Usage
@@ -104,7 +113,7 @@ karnel
 | `karnel start editor` | Start code-server (VS Code in browser) |
 | `karnel pg` | PostgreSQL manager |
 | `karnel init <template>` | Initialize projects with templates |
-| `karnel deploy` | Deploy projects (Vercel, Railway, Netlify, Supabase) |
+| `karnel deploy` | Run Vercel, Railway, Netlify, or Supabase CLI commands |
 | `karnel supabase` | Manage the Supabase CLI and remote-project helpers |
 | `karnel robin` | Manage the Robin OSINT service |
 | `karnel --version` | Show installed version |
@@ -363,7 +372,9 @@ karnel brain sync                  # Sync with private GitHub
 
 ## karnel voice
 
-Capture audio from microphone, review in editor, copy to clipboard, and dispatch any AI agent with the transcribed prompt.
+Capture audio from the microphone, optionally review it in an editor, copy it
+to the clipboard, and dispatch an AI agent with the transcribed prompt. If an
+editor is unavailable or no TTY is attached, Karnel uses the raw transcript.
 
 ```bash
 karnel voice opencode              # Record -> edit -> opencode run
@@ -415,7 +426,7 @@ Microphone -> termux-speech-to-text -> editor (edit) -> clipboard -> AI agent
 
 - Termux:API: `pkg install termux-api`
 - App Termux:API: https://karneltermux.vercel.app/termux/api
-- Editor: `karnel install editor`
+- Editor (optional): `karnel install editor`; otherwise use `--raw` or the automatic raw fallback
 
 ---
 
@@ -467,7 +478,8 @@ karnel env ls                        # List variables
 
 ## karnel deploy
 
-Deploy your projects directly from terminal:
+Run an installed platform CLI through Karnel; arguments after the tool name are
+forwarded unchanged:
 
 ```bash
 karnel deploy vercel                  # Deploy to Vercel

package/docs/ARCHITECTURE.md

@@ -83,6 +83,11 @@ import "@/cli/commands/doctor/code"
 
 The `@` symbol is replaced with `$KARNEL_PATH`. This avoids hardcoded paths.
 
+`import()` is not an idempotent module loader: it calls `source` on every import
+and does not track files already loaded. Top-level assignments and other side
+effects therefore run again when the same file is imported more than once;
+imported files must tolerate repeated evaluation where callers can repeat them.
+
 ### Critical Scope Implication
 
 Because `import()` calls `source` from within a function, any `declare` statement

package/docs/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Documentation Changelog
 
+## 4.15.0 - 2026-08-14
+
+- Replaced the unavailable GGA fork with the official Gentleman Guardian
+  Angel v2.10.1, pinned by commit, with Termux-safe staging, ownership
+  verification, rollback, and non-destructive uninstall.
+- Made backup/restore transactional: staged configs, ancestor symlink
+  rejection, signal-safe rollback, concurrent backup isolation, validated
+  snapshot names, and explicit package/configuration phase separation.
+- Hardened lifecycle ownership so pre-existing installs are never adopted,
+  arbitrary handler exit codes are treated as failures, and stale or empty
+  locks are recovered safely.
+- Pinned release/npm/installer together: the npm package carries a validated
+  `RELEASE_COMMIT`, the release workflow is serialized per tag and refuses
+  divergent partial publications, and the installer activates only a verified,
+  clean checkout.
+- Authenticated security and AI installers with fixed versions and official
+  SHA-256 checksums, safe archive extraction, staging, and rollback; unverifiable
+  upstream assets now fail closed instead of executing unauthenticated bytes.
+- Fixed the npm postinstall to distinguish the npm bin symlink from a complete
+  managed installation, and removed the deprecated `curl | bash` guidance.
+- Updated ShellCheck/syntax/test gates to 294 scripts and added regression
+  suites for backup, lifecycle, installer integrity, and AI installer hardening.
+
 ## 4.14.0 - 2026-08-14
 
 - Added tested Cactus 2.0.1 support on ARM64 through Ubuntu Proot with an

package/docs/cli/README.md

@@ -4,8 +4,9 @@
 karnel <command> [arguments]
 ```
 
-With no command, Karnel opens its interactive interface (TUI) when a terminal is
-available and prints help in noninteractive contexts.
+With no command, Karnel opens a curated interactive menu (TUI) when a terminal
+is available and prints help in noninteractive contexts. The menu exposes common
+workflows, not every command, alias, or option documented below.
 
 ---
 
@@ -442,8 +443,9 @@ karnel env ls
 karnel voice [agent] [options]
 ```
 
-Captures audio via `termux-speech-to-text`, opens the transcript in `$EDITOR`,
-copies to clipboard, and dispatches the AI agent.
+Captures audio via `termux-speech-to-text`, optionally opens the transcript in
+`$EDITOR`, copies it to the clipboard, and dispatches the AI agent. If no editor
+is installed or no TTY is available, Karnel continues with the raw transcript.
 
 ### Agent targets
 
@@ -539,18 +541,21 @@ cd . && karnel init                   # Auto-detect
 
 ---
 
-## deploy — Deploy projects
+## deploy — Run deployment CLIs
 
 ```bash
 karnel deploy <tool> [args...]
 ```
 
-| Tool | Platform |
-|------|----------|
-| `vercel` | Vercel (passes remaining args to `vercel`) |
-| `railway` | Railway |
-| `netlify` | Netlify |
-| `supabase` | Supabase |
+`deploy` checks that the selected executable exists, then replaces Karnel with
+that CLI and forwards all remaining arguments.
+
+| Tool | Executable |
+|------|------------|
+| `vercel` | `vercel` |
+| `railway` | `railway` |
+| `netlify` | `netlify` |
+| `supabase` | `supabase`; this is a generic CLI pass-through, not a deployment action by itself |
 
 ```bash
 karnel deploy vercel
@@ -568,19 +573,19 @@ karnel deploy supabase
 karnel supabase <subcommand> [options]
 ```
 
-The top-level command manages Supabase CLI installation and remote-project
-workflows. It does not start the local Supabase stack on Termux; that requires
-Docker on a Linux host.
+The top-level command manages the pinned Supabase CLI installation and provides
+thin wrappers for linked-project workflows. It does not start the local Supabase
+stack on Termux; `supabase start` requires Docker on a Linux host.
 
 | Subcommand | Description |
 |------------|-------------|
-| `doctor` | Check CLI, project configuration, and API reachability |
-| `types` | Generate TypeScript types for a linked project |
-| `migrate` | Run `supabase db <args>` |
-| `link` | Run `supabase link <args>` |
-| `remote-start` / `remote` | Show the remote-development guide |
-| `remote-status` / `status` | Check Supabase status |
-| `install` / `uninstall` | Install or remove the Supabase CLI |
+| `doctor` | Check the CLI, `supabase/config.toml`, Docker expectations, and API reachability |
+| `types` | Run `supabase gen types typescript --linked`; extra arguments are not forwarded |
+| `migrate` | Forward arguments to `supabase db` |
+| `link` | Forward arguments to `supabase link` |
+| `remote-start` / `remote` | Print a guide for running the Docker-backed local stack on a Linux host |
+| `remote-status` / `status` | Run `supabase status`, which reports the local stack rather than hosted-project health |
+| `install` / `uninstall` | Install or remove Karnel's pinned Supabase CLI binary |
 
 ```bash
 karnel supabase install
@@ -589,6 +594,43 @@ karnel supabase types
 karnel supabase migrate push
 ```
 
+The downloaded Linux binary may still fail on Android because of unsupported
+system calls. The wrapper reports a `SIGSYS` failure and recommends PRoot or a
+Linux host; installation alone does not guarantee native Android compatibility.
+
+---
+
+## plugin — Plugin manager
+
+```bash
+karnel plugin <subcommand> [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `search [query]` | Search the pinned approved registry snapshot |
+| `install <name>` | Install a plugin from that registry |
+| `install <owner/repo> --unsafe` | Install an unreviewed repository after confirmation |
+| `update <name>` | Atomically update an installed plugin |
+| `remove` / `uninstall <name>` | Remove an installed plugin |
+| `list` / `ls` | List installed plugins and their trust source |
+| `create` / `scaffold <name>` | Create and activate a validated local plugin scaffold |
+
+Search accepts `--command <name>`, `--compatible`, and `--capability <name>`.
+Capabilities are `network`, `filesystem-read`, `filesystem-write`, `process`,
+and `environment`. `--unsafe` applies only to `install` and `update`.
+
+Plugins are Bash code, run with the current user's permissions, and are not
+sandboxed. Registry review and manifest validation are not isolation boundaries.
+
+```bash
+karnel plugin search backup --compatible
+karnel plugin install karnel-hello
+karnel plugin install owner/repo --unsafe
+karnel plugin update karnel-hello
+karnel plugin remove karnel-hello
+```
+
 ---
 
 ## pg — PostgreSQL manager
@@ -659,23 +701,29 @@ karnel backup restore [file]
 ```
 
 Creates `$KARNEL_DATA/backups/termux-<timestamp>.tar.gz` with SHA256 checksum.
+Concurrent runs reserve distinct names atomically instead of overwriting a
+backup created in the same second.
 
 ### Included in backup
 
-- All packages (`dpkg --get-selections`)
-- Karnel tool manifest
-- Shell configs (`.bashrc`, `.zshrc`, `.profile`)
+- Package selections embedded under `metadata/packages.list` (`dpkg --get-selections`)
+- A catalog snapshot of tool installer directories, not a record of which tools are installed
+- Selected shell configs (`.bashrc`, `.zshrc`, `.profile`, `.zshenv`, `.inputrc`)
 - Termux configs (fonts, colors, properties)
-- SSH keys
-- `~/.config` app configs
-- APT repositories
+- SSH configuration, known hosts, authorized keys, and public keys; private keys are excluded
+- Selected `~/.config` application directories; `github-copilot`, `nvm`, `coc`, `Code`, and `yarn` are excluded, as are symbolic links and all `.env`, credential, auth, and token files matched by the backup filter
+- `$PREFIX/etc/apt/sources.list` only; files under `sources.list.d` and APT keys are not included
+
+Backups are gzip-compressed, not encrypted. API environment variables and SSH
+private keys are not exported, but copied application configuration can still
+contain credentials. Protect local and cloud copies as sensitive plaintext data.
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
-| `--cloud` | Upload via `rclone` (remote named `karnel`) |
-| `snapshot <name>` | Create a named snapshot |
+| `--cloud` | Legacy plaintext upload; requires explicit `KARNEL_ALLOW_PLAINTEXT_CLOUD_BACKUP=1` acknowledgement |
+| `snapshot <name>` | Create a timestamped named snapshot using the same contents and secret filter as a full backup; names accept 1-64 letters, numbers, dots, underscores, or hyphens |
 | `list` / `ls` | List full backups and snapshots |
 | `info` / `show [file]` | Show a backup's contents (latest if omitted) |
 | `--cron` | Schedule a daily backup at 3:00 AM |
@@ -689,6 +737,11 @@ karnel backup snapshot before-update
 karnel backup list
 ```
 
+Cloud backup is disabled by default because the archive is not encrypted or
+signed. The legacy opt-in uploads both archive and checksum, but they share the
+same remote trust boundary. Package selections and the informational tool
+catalog are embedded in the archive.
+
 ---
 
 ## restore — Full Termux restore
@@ -699,22 +752,28 @@ karnel restore [--cloud] [--list] [<file>]
 
 ### What it restores
 
-- Shell configs to `~/`
+- Selected shell configs to `~/`
 - Termux configs
-- SSH keys
-- `~/.config` directory
-- APT sources
-- Package list (via `dpkg --set-selections` + `apt-get dselect-upgrade`)
-- Karnel tools (from manifest)
-
-Verifies SHA256 checksum automatically if available.
+- SSH configuration and public keys (legacy archives may also contain private keys)
+- The selected `.config` directories present in the archive
+- `$PREFIX/etc/apt/sources.list` when present
+- Embedded package selections (via `dpkg --set-selections` + `apt-get dselect-upgrade`)
+- The tool catalog is retained as metadata only; Karnel does not incorrectly reinstall every tool in the source catalog
+
+Requires and verifies the SHA256 checksum before extraction. Restore rejects
+archives containing traversal paths, links, devices, or other unsafe entries.
+Configuration is first merged into staging so unrelated existing files remain
+in place, then committed with local backups. A copy, move, or package-restore
+failure rolls configuration back instead of reporting a partial success.
+Package-manager operations themselves are not transactionally reversible by
+Karnel if `apt-get` changes package state before returning an error.
 
 ### Options
 
 | Argument | Description |
 |----------|-------------|
 | `<file>` | Path to a specific backup file |
-| `--cloud` | Download and restore via the `karnel` rclone remote |
+| `--cloud` | Legacy unauthenticated cloud restore; requires `KARNEL_ALLOW_UNAUTHENTICATED_CLOUD_RESTORE=1` |
 | `--list`, `-l` | List available full backups and snapshots |
 | `--help`, `-h` | Show help |
 

package/install.sh

@@ -14,12 +14,17 @@ readonly P_NC='\e[0m'
 REPO="https://github.com/israelmarques1024-dotcom/karnel-termux"
 BRANCH="main"
 RELEASE_REF=""
+INSTALL_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RELEASE_COMMIT="${KARNEL_RELEASE_COMMIT:-}"
+if [[ -z "$RELEASE_COMMIT" && -f "$INSTALL_SCRIPT_DIR/karnel/RELEASE_COMMIT" ]]; then
+	read -r RELEASE_COMMIT <"$INSTALL_SCRIPT_DIR/karnel/RELEASE_COMMIT" || RELEASE_COMMIT=""
+fi
 KARNEL_DATA="${XDG_DATA_HOME:-$HOME/.local/share}/karnel-data"
 KARNEL_REPO="${XDG_DATA_HOME:-$HOME/.local/share}/karnel"
 KARNEL_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/karnel"
 KARNEL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/karnel"
 
-TOTAL_STEPS=6
+TOTAL_STEPS=4
 CURRENT_STEP=0
 
 _cols() {
@@ -66,26 +71,46 @@ log_info() {
 	echo -e "  ${P_BORDER}→${P_NC}  $1"
 }
 
-_INSTALL_CREATED_KARNEL_REPO=false
-_INSTALL_CREATED_KARNEL_SYMLINK=false
+_INSTALL_STAGING_ROOT=""
+_INSTALL_PREVIOUS_KARNEL_REPO=""
+_INSTALL_REPO_ACTIVATED=false
+_INSTALL_REPO_HAD_PREVIOUS=false
+_INSTALL_KARNEL_SYMLINK_CHANGED=false
 _INSTALL_PREVIOUS_KARNEL_SYMLINK=""
 
 _cleanup_failed() {
 	echo -e "\n  ${P_FAIL}✖${P_NC}  Installation failed at step ${CURRENT_STEP}. Cleaning up..."
-	if $_INSTALL_CREATED_KARNEL_REPO && [[ -d "$KARNEL_REPO" ]]; then
-		rm -rf "$KARNEL_REPO"
-	fi
-	if $_INSTALL_CREATED_KARNEL_SYMLINK && [[ -L "$PREFIX/bin/karnel" ]]; then
+	if $_INSTALL_KARNEL_SYMLINK_CHANGED; then
 		if [[ -n "$_INSTALL_PREVIOUS_KARNEL_SYMLINK" ]]; then
-			ln -sfn "$_INSTALL_PREVIOUS_KARNEL_SYMLINK" "$PREFIX/bin/karnel"
+			local rollback_link_dir
+			rollback_link_dir=$(mktemp -d "$PREFIX/bin/.karnel-rollback.XXXXXX")
+			ln -s "$_INSTALL_PREVIOUS_KARNEL_SYMLINK" "$rollback_link_dir/karnel"
+			mv -Tf "$rollback_link_dir/karnel" "$PREFIX/bin/karnel"
+			rmdir "$rollback_link_dir"
 		else
 			rm -f "$PREFIX/bin/karnel"
 		fi
 	fi
+	if $_INSTALL_REPO_ACTIVATED; then
+		rm -rf "$KARNEL_REPO"
+		if $_INSTALL_REPO_HAD_PREVIOUS && [[ -d "$_INSTALL_PREVIOUS_KARNEL_REPO" ]]; then
+			mv "$_INSTALL_PREVIOUS_KARNEL_REPO" "$KARNEL_REPO"
+		fi
+	fi
+	[[ -z "$_INSTALL_STAGING_ROOT" ]] || rm -rf "$_INSTALL_STAGING_ROOT"
 	echo -e "  ${P_DIM}Run install.sh again to retry${P_NC}"
 	exit 1
 }
 
+_finish_install() {
+	if $_INSTALL_REPO_HAD_PREVIOUS && [[ -d "$_INSTALL_PREVIOUS_KARNEL_REPO" ]]; then
+		rm -rf "$_INSTALL_PREVIOUS_KARNEL_REPO"
+	fi
+	[[ -z "$_INSTALL_STAGING_ROOT" ]] || rm -rf "$_INSTALL_STAGING_ROOT"
+	_INSTALL_REPO_ACTIVATED=false
+	_INSTALL_KARNEL_SYMLINK_CHANGED=false
+}
+
 separator() {
 	local cols=$(_cols)
 	local line=$(printf "%${cols}s")
@@ -178,7 +203,21 @@ install_dependencies() {
 setup_directories() {
 	log_step 2 "Setting up directories"
 
-	mkdir -p "$KARNEL_REPO" "$KARNEL_DATA" "$KARNEL_CACHE" "$KARNEL_CONFIG"
+	umask 077
+	local directory
+	for directory in "$KARNEL_DATA" "$KARNEL_CACHE" "$KARNEL_CONFIG"; do
+		if [[ -L "$directory" ]]; then
+			log_fail "Refusing symlink directory: $directory"
+			return 1
+		fi
+		mkdir -p -m 700 "$directory" || return 1
+		chmod 700 "$directory" || return 1
+	done
+	if [[ -L "$KARNEL_REPO" ]]; then
+		log_fail "Refusing symlink directory: $KARNEL_REPO"
+		return 1
+	fi
+	mkdir -p -m 700 "$(dirname "$KARNEL_REPO")" || return 1
 
 	log_info "Repo    $KARNEL_REPO"
 	log_info "Data    $KARNEL_DATA"
@@ -190,11 +229,10 @@ setup_directories() {
 clone_repo() {
 	log_step 3 "Cloning repository"
 
-	local script_dir
-	script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	local script_dir="$INSTALL_SCRIPT_DIR"
 	local is_dev_install=0
 
-	if [[ -d "$script_dir/.git" ]] && [[ "$script_dir" != "$KARNEL_REPO" ]]; then
+	if [[ "$script_dir" != "$KARNEL_REPO" ]] && git -C "$script_dir" rev-parse --is-inside-work-tree &>/dev/null; then
 		is_dev_install=1
 	fi
 
@@ -206,32 +244,38 @@ clone_repo() {
 		KARNEL_REPO="$script_dir"
 		log_info "Developer installation detected"
 		log_ok "Using local repository"
-	elif [[ -d "$KARNEL_REPO/.git" ]]; then
+	else
+		local existing_repo=0
+		if [[ -e "$KARNEL_REPO" ]]; then
+			if ! git -C "$KARNEL_REPO" rev-parse --is-inside-work-tree &>/dev/null; then
+				log_fail "Refusing to replace pre-existing non-repository: $KARNEL_REPO"
+				return 1
+			fi
+			existing_repo=1
+		fi
+
+		if [[ $existing_repo -eq 1 ]]; then
 		local origin_url
 		origin_url="$(git -C "$KARNEL_REPO" remote get-url origin 2>/dev/null)"
-		if [[ "$origin_url" != "$REPO" && "$origin_url" != "${REPO%.git}" ]]; then
+		if [[ "${origin_url%.git}" != "${REPO%.git}" ]]; then
 			log_fail "Existing Karnel repository has an unexpected origin"
 			return 1
 		fi
-		progress_bar 3 10
-		if [[ -n "$RELEASE_REF" ]]; then
-			if ! git -C "$KARNEL_REPO" fetch --depth=1 origin "refs/tags/$BRANCH" &>/dev/null ||
-				! git -C "$KARNEL_REPO" checkout --detach FETCH_HEAD &>/dev/null; then
-				log_fail "Failed to update existing repository"
-				return 1
-			fi
-		else
-			if ! git -c core.hooksPath=/dev/null -C "$KARNEL_REPO" pull origin "$BRANCH" &>/dev/null; then
-				log_fail "Failed to update existing repository"
-				return 1
-			fi
+		local worktree_status
+		if ! worktree_status=$(git -C "$KARNEL_REPO" status --porcelain --untracked-files=all); then
+			log_fail "Failed to inspect existing Karnel repository"
+			return 1
 		fi
-		progress_bar 10 10
-		echo
-		log_ok "Repository updated"
-	else
+		if [[ -n "$worktree_status" ]]; then
+			log_fail "Refusing to update a dirty Karnel repository"
+			return 1
+		fi
+		fi
+
+		_INSTALL_STAGING_ROOT=$(mktemp -d "$(dirname "$KARNEL_REPO")/.karnel-staging.XXXXXX")
+		local candidate_repo="$_INSTALL_STAGING_ROOT/repo"
 		progress_bar 0 10
-		git clone --depth=1 -b "$BRANCH" "$REPO" "$KARNEL_REPO" &>/dev/null &
+		git clone --depth=1 --branch "$BRANCH" "$REPO" "$candidate_repo" &>/dev/null &
 		local pid=$!
 		local dots=0
 		while kill -0 "$pid" 2>/dev/null; do
@@ -239,11 +283,42 @@ clone_repo() {
 			printf "\r  Cloning%s    " "$(printf '%*s' "$dots" '' | tr ' ' '.')"
 			sleep 0.5
 		done
-		wait "$pid" || { log_fail "Failed to clone repository"; _cleanup_failed; exit 1; }
-		_INSTALL_CREATED_KARNEL_REPO=true
+		if ! wait "$pid"; then
+			log_fail "Failed to clone repository"
+			return 1
+		fi
+		if [[ -n "$RELEASE_REF" ]]; then
+			local candidate_commit
+			candidate_commit=$(git -C "$candidate_repo" rev-parse HEAD 2>/dev/null) || return 1
+			if [[ "$candidate_commit" != "$RELEASE_COMMIT" ]]; then
+				log_fail "Release commit mismatch for $RELEASE_REF"
+				log_info "Expected $RELEASE_COMMIT, got $candidate_commit"
+				return 1
+			fi
+		fi
+
+		if [[ $existing_repo -eq 1 ]]; then
+			_INSTALL_PREVIOUS_KARNEL_REPO=$(mktemp -d "$(dirname "$KARNEL_REPO")/.karnel-previous.XXXXXX")
+			rmdir "$_INSTALL_PREVIOUS_KARNEL_REPO"
+			mv "$KARNEL_REPO" "$_INSTALL_PREVIOUS_KARNEL_REPO"
+			_INSTALL_REPO_HAD_PREVIOUS=true
+		fi
+		if ! mv "$candidate_repo" "$KARNEL_REPO"; then
+			if $_INSTALL_REPO_HAD_PREVIOUS; then
+				mv "$_INSTALL_PREVIOUS_KARNEL_REPO" "$KARNEL_REPO"
+				_INSTALL_REPO_HAD_PREVIOUS=false
+			fi
+			log_fail "Failed to activate repository"
+			return 1
+		fi
+		_INSTALL_REPO_ACTIVATED=true
 		progress_bar 10 10
 		echo
-		log_ok "Repository cloned"
+		if [[ $existing_repo -eq 1 ]]; then
+			log_ok "Repository updated"
+		else
+			log_ok "Repository cloned"
+		fi
 	fi
 
 	export KARNEL_REPO
@@ -263,20 +338,21 @@ create_symlink() {
 
 	[[ -z "$PREFIX" ]] && { log_fail "PREFIX is not set. Are you running in Termux?"; return 1; }
 
-	command -v termux-fix-shebang &>/dev/null && termux-fix-shebang "$KARNEL_REPO/karnel/bin/karnel" &>/dev/null
-
-	if [[ -e "$PREFIX/bin/karnel" && ! -L "$PREFIX/bin/karnel" ]]; then
+	if [[ ( -e "$PREFIX/bin/karnel" || -L "$PREFIX/bin/karnel" ) && ! -L "$PREFIX/bin/karnel" ]]; then
 		log_fail "Refusing to replace existing non-symlink: $PREFIX/bin/karnel"
 		return 1
 	fi
 	if [[ -L "$PREFIX/bin/karnel" ]]; then
 		_INSTALL_PREVIOUS_KARNEL_SYMLINK="$(readlink "$PREFIX/bin/karnel")"
 	fi
-	rm -f "$PREFIX/bin/karnel"
-	ln -sf "$KARNEL_REPO/karnel/bin/karnel" "$PREFIX/bin/karnel"
+	local link_staging
+	link_staging=$(mktemp -d "$PREFIX/bin/.karnel-link.XXXXXX")
+	ln -s "$KARNEL_REPO/karnel/bin/karnel" "$link_staging/karnel"
+	mv -Tf "$link_staging/karnel" "$PREFIX/bin/karnel"
+	rmdir "$link_staging"
+	_INSTALL_KARNEL_SYMLINK_CHANGED=true
 
 	if [[ -L "$PREFIX/bin/karnel" ]]; then
-		_INSTALL_CREATED_KARNEL_SYMLINK=true
 		log_ok "Symlink created: karnel → ${KARNEL_REPO}/karnel/bin/karnel"
 	else
 		log_fail "Failed to create symlink"
@@ -284,19 +360,6 @@ create_symlink() {
 	fi
 }
 
-save_config() {
-	log_step 5 "Saving configuration"
-
-	cat >"$KARNEL_CONFIG/config" <<EOF
-karnel_repo='$KARNEL_REPO'
-karnel_data='$KARNEL_DATA'
-karnel_cache='$KARNEL_CACHE'
-karnel_config='$KARNEL_CONFIG'
-EOF
-
-	log_ok "Configuration saved"
-}
-
 show_final_message() {
 	echo
 	separator
@@ -322,15 +385,33 @@ show_final_message() {
 }
 
 main() {
-	if [[ $# -eq 2 && "$1" == "--ref" ]]; then
-		if [[ ! "$2" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-			echo -e "\n  ${P_FAIL}✖${P_NC}  Invalid release ref: $2" >&2
-			return 1
-		fi
-		BRANCH="$2"
-		RELEASE_REF="$2"
-	elif [[ $# -ne 0 ]]; then
-		echo -e "\n  ${P_FAIL}✖${P_NC}  Usage: install.sh [--ref vX.Y.Z]" >&2
+	while [[ $# -gt 0 ]]; do
+		case "$1" in
+			--ref)
+				[[ $# -ge 2 && "$2" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+					echo -e "\n  ${P_FAIL}✖${P_NC}  Invalid or missing release ref" >&2
+					return 1
+				}
+				BRANCH="$2"
+				RELEASE_REF="$2"
+				shift 2
+				;;
+			--commit)
+				[[ $# -ge 2 && "$2" =~ ^[0-9a-f]{40}$ ]] || {
+					echo -e "\n  ${P_FAIL}✖${P_NC}  Invalid or missing release commit" >&2
+					return 1
+				}
+				RELEASE_COMMIT="$2"
+				shift 2
+				;;
+			*)
+				echo -e "\n  ${P_FAIL}✖${P_NC}  Usage: install.sh [--ref vX.Y.Z --commit SHA]" >&2
+				return 1
+				;;
+		esac
+	done
+	if [[ -n "$RELEASE_REF" && ! "$RELEASE_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
+		echo -e "\n  ${P_FAIL}✖${P_NC}  Release installation requires an immutable commit SHA" >&2
 		return 1
 	fi
 
@@ -346,7 +427,7 @@ main() {
   setup_directories
   clone_repo
   create_symlink
-  save_config
+  _finish_install
   show_final_message
 }
 

package/karnel/RELEASE_COMMIT

@@ -0,0 +1 @@
+0cb37fa9cbd9b82b371fdae9fd07c2041bfc4b19