karnel-termux 4.17.21 → 4.17.23

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.17.21-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.17.22-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.21
+version=4.17.22
 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"
@@ -636,8 +636,9 @@ karnel update karnel     # Update the framework
 
 `karnel update` requires a target such as `karnel`, `ai`, or `security`.
 `karnel update karnel` first runs the official curl installer, then falls back to
-the local Git checkout and package-manager installs if needed. The curl installer
-is pinned to the latest GitHub release tag, and its SHA-256 checksum is verified
+the local Git checkout if needed. Package-manager fallback is used only when the
+active framework was installed by that package manager. The curl installer is
+pinned to the latest GitHub release tag, and its SHA-256 checksum is verified
 before it runs. The framework checks for a new version in the background at most
 once every 24 hours; the check can use npm or GitHub and writes state under
 `$KARNEL_CACHE`.

package/docs/CHANGELOG.md

@@ -6,6 +6,14 @@ layout: base
 
 # Documentation Changelog
 
+## 4.17.22
+
+- **Data safety and correctness (8):** restore rejects ambiguous multiple archives; Brain preserves same-day title collisions, uses file paths for AI context, initializes/pushes `main`, detects missing `origin`, and supports editors with arguments; PostgreSQL backup filenames are path-safe; AI-session persistence escapes JSON correctly.
+- **Agent safety (3):** positional prompts retain all words, zero-valued execution/context limits are rejected, and PLAN mode rejects shell syntax plus destructive `find`/in-place operations that bypassed its read-only contract.
+- **Installer reliability (1):** Bun proot installation/update no longer reject safe archives before extraction.
+- **Regression coverage:** added critical CLI contracts and strengthened Brain reciprocal-relation coverage; the isolated full suite passes.
+- Version references bumped to `4.17.22`.
+
 ## 4.17.21
 
 - **Official-site routing:** `karnel open`, npm package metadata, and the GitHub/npm README now point to the Vercel production site, `https://karneltermux.vercel.app`, rather than the secondary GitHub Pages mirror.

package/install.sh

@@ -147,7 +147,10 @@ bootstrap_dependencies() {
 
 	if [[ $needed_tput -eq 1 ]]; then
 		echo -e "  ${P_BORDER}→${P_NC}  Installing ncurses-utils..."
-		pkg install -y ncurses-utils &>/dev/null || true
+		if ! pkg install -y ncurses-utils &>/dev/null; then
+			log_fail "Failed to install ncurses-utils"
+			return 1
+		fi
 		echo -e "  ${P_OK}✔${P_NC}  ncurses installed"
 		echo
 	fi
@@ -155,7 +158,10 @@ bootstrap_dependencies() {
 	if [[ $needed_git -eq 1 ]]; then
 		log_info "Installing git..."
 		progress_bar 0 10
-		pkg install -y git &>/dev/null || true
+		if ! pkg install -y git &>/dev/null; then
+			log_fail "Failed to install git"
+			return 1
+		fi
 		progress_bar 10 10
 		echo
 		log_ok "git installed"
@@ -164,7 +170,10 @@ bootstrap_dependencies() {
 	if [[ $needed_glow -eq 1 ]]; then
 		log_info "Installing glow..."
 		progress_bar 0 10
-		pkg install -y glow &>/dev/null || true
+		if ! pkg install -y glow &>/dev/null; then
+			log_fail "Failed to install glow"
+			return 1
+		fi
 		progress_bar 10 10
 		echo
 		log_ok "glow installed"
@@ -173,7 +182,10 @@ bootstrap_dependencies() {
 	if [[ $needed_gh -eq 1 ]]; then
 		log_info "Installing gh (GitHub CLI)..."
 		progress_bar 0 10
-		pkg install -y gh &>/dev/null || true
+		if ! pkg install -y gh &>/dev/null; then
+			log_fail "Failed to install gh"
+			return 1
+		fi
 		progress_bar 10 10
 		echo
 		log_ok "gh installed"
@@ -182,7 +194,10 @@ bootstrap_dependencies() {
 	if [[ $needed_rg -eq 1 ]]; then
 		log_info "Installing ripgrep..."
 		progress_bar 0 10
-		pkg install -y ripgrep &>/dev/null || true
+		if ! pkg install -y ripgrep &>/dev/null; then
+			log_fail "Failed to install ripgrep"
+			return 1
+		fi
 		progress_bar 10 10
 		echo
 		log_ok "ripgrep installed"

package/karnel/RELEASE_COMMIT

@@ -1 +1 @@
-6b13b468f425a13040e4dac77eef1b449a553ea8
+9e1cc56cd0e413f5135180c07ae5c9cea021e4ba

package/karnel/cli/commands/agent.sh

@@ -255,10 +255,11 @@ agent_parse_args() {
 	AGENT_PROMPT=""
 	AGENT_SHOW_HELP=0
 	AGENT_YES=0
-	local prev=""
+	local prev="" prompt_set=0
+	local -a positional=()
 	for arg in "$@"; do
 		case "$prev" in
-		-p | --prompt) AGENT_PROMPT="$arg"; prev=""; continue ;;
+		-p | --prompt) AGENT_PROMPT="$arg"; prompt_set=1; prev=""; continue ;;
 		-m | --model) AGENT_MODEL="$arg"; prev=""; continue ;;
 		-u | --endpoint) AGENT_ENDPOINT="$arg"; prev=""; continue ;;
 		-t | --temperature) AGENT_TEMPERATURE="$arg"; prev=""; continue ;;
@@ -267,7 +268,7 @@ agent_parse_args() {
 		--max-tokens) AGENT_MAX_TOKENS="$arg"; prev=""; continue ;;
 		esac
 		case "$arg" in
-		-p=* | --prompt=*) AGENT_PROMPT="${arg#*=}" ;;
+		-p=* | --prompt=*) AGENT_PROMPT="${arg#*=}"; prompt_set=1 ;;
 		-m=* | --model=*) AGENT_MODEL="${arg#*=}" ;;
 		-u=* | --endpoint=*) AGENT_ENDPOINT="${arg#*=}" ;;
 		-t=* | --temperature=*) AGENT_TEMPERATURE="${arg#*=}" ;;
@@ -280,9 +281,12 @@ agent_parse_args() {
 		-y | --yes) AGENT_YES=1 ;;
 		-h | --help) AGENT_SHOW_HELP=1 ;;
 		-*) log_warn "Unknown option: $arg" ;;
-		*) [[ -z "$AGENT_PROMPT" ]] && AGENT_PROMPT="$arg" ;;
+		*) positional+=("$arg") ;;
 		esac
 	done
+	if (( ! prompt_set && ${#positional[@]} )); then
+		AGENT_PROMPT="${positional[*]}"
+	fi
 }
 readonly AGENT_ASK_SYSTEM="You are a concise chat assistant. Reply in the SAME LANGUAGE the user writes in. Be direct and practical; use markdown, and put code in fenced blocks. <attached_file path=\"...\">...</attached_file> blocks hold real file contents (action=\"no-read\" = path only). <compacted_summary>...</compacted_summary> blocks are condensed summaries of earlier turns — treat them as ground truth."
 
@@ -846,4 +850,4 @@ agent_run_loop() {
 	_ems=$(agent_timer_ms)
 	echo
 	printf '    %s[context %s]%s\n' "$D_GRAY" "$(agent_context_footer "$AGENT_REPL_HISTORY" "$_ems")" "$NC"
-}
+}

package/karnel/cli/commands/brain.sh

@@ -349,7 +349,7 @@ brain_init() {
 	log_info "Creating private repo: ${D_CYAN}$gh_user/$repo_name${D_NC}..."
 	if gh repo create "$repo_name" --private &>/dev/null; then
 		(
-			git -C "$BRAIN_DIR" init &>/dev/null
+			git -C "$BRAIN_DIR" init -b main &>/dev/null || exit 1
 			echo "# Karnel Brain" >"$BRAIN_DIR/README.md"
 			git -C "$BRAIN_DIR" add -A
 			git -C "$BRAIN_DIR" commit -m "init brain" &>/dev/null
@@ -474,6 +474,10 @@ brain_save() {
 	# ── Write file ──
 	mkdir -p "$BRAIN_DIR/$category"
 	local filepath="$BRAIN_DIR/$category/${date_prefix}_${slug}.md"
+	if [[ -e "$filepath" ]]; then
+		log_error "A memory with this title already exists today: ${date_prefix}_${slug}.md"
+		return 1
+	fi
 
 	{
 		_brain_frontmatter "$title" "$tags_formatted" "$category" "$related_str"
@@ -576,6 +580,10 @@ brain_add() {
 
 	mkdir -p "$BRAIN_DIR/$category"
 	local filepath="$BRAIN_DIR/$category/${date_prefix}_${slug}.md"
+	if [[ -e "$filepath" ]]; then
+		log_error "A memory with this title already exists today: ${date_prefix}_${slug}.md"
+		return 1
+	fi
 
 	{
 		_brain_frontmatter "$title" "$tags_formatted" "$category" ""
@@ -928,7 +936,7 @@ brain_sync() {
 	local branch
 	branch=$(git -C "$BRAIN_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null)
 
-	if ! git -C "$BRAIN_DIR" remote -v &>/dev/null; then
+	if ! git -C "$BRAIN_DIR" remote get-url origin &>/dev/null; then
 		log_info "No remote configured — local commit only"
 		list_item "Set up GitHub sync with: ${D_CYAN}karnel brain init${D_NC}"
 		separator
@@ -1231,22 +1239,18 @@ brain_edit() {
 		return 0
 	fi
 
-	local editor="${EDITOR:-}"
-	local editor_bin
-	editor_bin="${EDITOR:-nano}"
-	editor_bin="${editor_bin%% *}"
-	if command -v "$editor_bin" &>/dev/null; then
-		editor="${EDITOR:-nano}"
-	elif [[ -z "$editor" ]] || ! command -v "$editor" &>/dev/null; then
+	local -a editor_cmd=()
+	read -r -a editor_cmd <<< "${EDITOR:-nano}"
+	if ! command -v "${editor_cmd[0]}" &>/dev/null; then
 		for e in vim nano vi; do
 			if command -v "$e" &>/dev/null; then
-				editor="$e"
+				editor_cmd=("$e")
 				break
 			fi
 		done
 	fi
 
-	if [[ -z "$editor" ]]; then
+	if [[ ${#editor_cmd[@]} -eq 0 ]] || ! command -v "${editor_cmd[0]}" &>/dev/null; then
 		log_error "No editor found"
 		list_item "Install one: ${D_CYAN}karnel install editor${D_NC}"
 		return 1
@@ -1255,7 +1259,7 @@ brain_edit() {
 	echo
 	log_info "Opening: ${D_CYAN}$(_brain_title "$file")${D_NC}"
 
-	"$editor" "$file"
+	"${editor_cmd[@]}" "$file"
 
 	log_success "Memory updated"
 	echo
@@ -1543,7 +1547,7 @@ EOF
 		if [[ -n "$f" ]]; then
 			matching_files+=("$f")
 		fi
-	done < <(_brain_rg -i "$clean_query" | head -n 5 || true)
+	done < <(_brain_rg -l -i "$clean_query" | head -n 5 || true)
 
 	if [[ ${#matching_files[@]} -eq 0 ]]; then
 		local -a words=($clean_query)
@@ -1562,7 +1566,7 @@ EOF
 				if [[ -n "$f" ]]; then
 					matching_files+=("$f")
 				fi
-			done < <(_brain_rg -i -e "$word_regex" | head -n 5 || true)
+			done < <(_brain_rg -l -i -e "$word_regex" | head -n 5 || true)
 		fi
 	fi
 

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

@@ -342,10 +342,11 @@ _fix_script_symlinks() {
       local tool_name
       tool_name=$(basename "$tool_dir")
       local bin_names
-      bin_names=$(grep -E '^local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
+      bin_names=$(grep -E '^[[:space:]]*local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
       [[ -z "$bin_names" ]] && bin_names="$tool_name"
       for bin_name in $bin_names; do
         local expected="$tool_dir/$bin_name.py"
+        [[ -f "$expected" ]] || continue
         local link="$PREFIX/bin/$bin_name"
         if [[ -L "$link" ]]; then
           local target
@@ -403,15 +404,14 @@ _fix_script_missing() {
       local module_name
       module_name=$(basename "$module_dir")
       local bin_names
-      bin_names=$(grep -E '^local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
+      bin_names=$(grep -E '^[[:space:]]*local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
       [[ -z "$bin_names" ]] && bin_names="$tool_name"
       for bin_name in $bin_names; do
         ((total++))
         if ! command -v "$bin_name" &>/dev/null; then
           karnel install "$module_name" "--$tool_name" &>/dev/null && ((fixed++))
         fi
-      done
-    done < <(find "$module_dir" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
+      done    done < <(find "$module_dir" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
   done < <(find "$KARNEL_PATH/tools/" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
   [[ $fixed -gt 0 ]] && log_success "Reinstalled $fixed/$total missing tool(s)"
   return 0

package/karnel/cli/commands/doctor.sh

@@ -671,7 +671,7 @@ doctor_termux() {
       [[ -f "$installer" ]] || continue
 
       local bin_names
-      bin_names=$(grep -E '^local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
+      bin_names=$(grep -E '^[[:space:]]*local BIN_NAME=' "$installer" 2>/dev/null | head -1 | sed "s/.*BIN_NAME=\"\?//;s/\"\?$//")
       [[ -z "$bin_names" ]] && bin_names="$tool_name"
 
       for bin_name in $bin_names; do
@@ -684,12 +684,14 @@ doctor_termux() {
           if [[ "$target" == "$tool_script" ]]; then
             log_success "$module_name/$tool_name → $bin_name (OK)"
             ((script_ok++))
+          elif [[ ! -f "$tool_script" ]]; then
+            log_info "$bin_name: managed outside Karnel python payloads (→ $target)"
           else
             log_warn "$bin_name: symlink target changed (→ $target, expected $tool_script)"
             ((script_warn++)); found_symlink_issues=true
           fi
 
-          if [[ -f "$bin_path" ]] && head -1 "$bin_path" 2>/dev/null | grep -q "^#!/usr/bin/env"; then
+          if [[ -f "$tool_script" ]] && [[ -f "$bin_path" ]] && head -1 "$bin_path" 2>/dev/null | grep -q "^#!/usr/bin/env"; then
             log_warn "$bin_name: uses #!/usr/bin/env — will fail on Termux"
             ((script_warn++)); found_shebang_issues=true
           fi

package/karnel/cli/commands/ia.sh

@@ -420,7 +420,11 @@ PY
 		ts_raw=$(echo "$session" | cut -d'|' -f2)
 		name=$(echo "$session" | cut -d'|' -f3-)
 		local escaped_name
-		escaped_name=$(printf '%s' "$name" | sed 's/"/\\"/g' | sed "s/'/\\\\'/g")
+		escaped_name=${name//\\/\\\\}
+		escaped_name=${escaped_name//\"/\\\"}
+		escaped_name=${escaped_name//$'\n'/\\n}
+		escaped_name=${escaped_name//$'\r'/\\r}
+		escaped_name=${escaped_name//$'\t'/\\t}
 		if [[ $first -eq 1 ]]; then
 			first=0
 		else

package/karnel/cli/commands/pg.sh

@@ -514,7 +514,10 @@ pg_backup() {
 	log_info "Creating compressed backup for '$db_name'..."
 	local backup_dir="$KARNEL_DATA/pg_backups"
 	mkdir -p "$backup_dir"
-	local file_name="${db_name}_$(date +%Y%m%d_%H%M%S).backup.gz"
+	local safe_db_name
+	safe_db_name=$(printf '%s' "$db_name" | tr -c '[:alnum:]_.-' '_')
+	[[ -n "$safe_db_name" ]] || { log_error "Invalid database name"; return 1; }
+	local file_name="${safe_db_name}_$(date +%Y%m%d_%H%M%S).backup.gz"
 	local file_path="$backup_dir/$file_name"
 
 	if loading "Running backup dump" _run_backup_cmd "$db_name" "$file_path"; then
@@ -522,7 +525,7 @@ pg_backup() {
 		log_success "Backup created successfully:"
 		list_item "$file_path"
 		list_item "Checksum generated: $(cat "${file_path}.sha256")"
-		_pg_cleanup_old_backups "$db_name"
+		_pg_cleanup_old_backups "$safe_db_name"
 	else
 		log_error "Failed to create backup"
 		rm -f "$file_path"

package/karnel/cli/commands/restore.sh

@@ -51,6 +51,9 @@ restore_main() {
             log_error "File not found: $arg"
             return 1
           fi
+        else
+          log_error "Restore accepts exactly one backup file"
+          return 1
         fi
         ;;
     esac

package/karnel/cli/commands/update.sh

@@ -357,8 +357,18 @@ _npm_installed_version() {
   printf '%s' "${v:-unknown}"
 }
 
+_update_global_package_is_active() {
+  local manager="${1:-npm}" root
+  root=$("$manager" root -g 2>/dev/null) || return 1
+  [[ "$KARNEL_PATH" == "$root/karnel-termux/karnel" ]]
+}
+
 _update_try_npm() {
   command -v npm &>/dev/null || return 1
+  if ! _update_global_package_is_active; then
+    log_info "Skipping npm update: the active Karnel framework is not npm-managed"
+    return 1
+  fi
   log_info "Trying npm update..."
   if npm update -g karnel-termux --ignore-scripts 2>/dev/null; then
     local new_ver
@@ -372,6 +382,10 @@ _update_try_npm() {
 
 _update_try_npm_install() {
   command -v npm &>/dev/null || return 1
+  if ! _update_global_package_is_active; then
+    log_info "Skipping npm install: the active Karnel framework is not npm-managed"
+    return 1
+  fi
   log_info "Trying npm install..."
   if npm install -g karnel-termux@latest --ignore-scripts 2>/dev/null; then
     local new_ver
@@ -384,6 +398,10 @@ _update_try_npm_install() {
 
 _update_try_pnpm() {
   command -v pnpm &>/dev/null || return 1
+  if ! _update_global_package_is_active pnpm; then
+    log_info "Skipping pnpm update: the active Karnel framework is not pnpm-managed"
+    return 1
+  fi
   log_info "Trying pnpm..."
   if pnpm add -g karnel-termux@latest 2>/dev/null; then
     log_success "Updated via pnpm"

package/karnel/cli/commands/upgrade.sh

@@ -15,11 +15,14 @@ upgrade_main() {
     return 1
   fi
 
+  if ! _upgrade_fix_symlink; then
+    log_error "Karnel upgrade could not activate its command"
+    return 1
+  fi
+
   source "$KARNEL_PATH/utils/env.sh" 2>/dev/null
   log_success "Karnel upgraded to v$KARNEL_VERSION"
 
-  _upgrade_fix_symlink
-
   echo
   log_info "Running cleanup..."
   import "@/cli/commands/cleanup"
@@ -30,6 +33,10 @@ upgrade_main() {
 }
 
 _upgrade_fix_symlink() {
+  if [[ -e "$PREFIX/bin/karnel" && ! -L "$PREFIX/bin/karnel" ]]; then
+    log_error "Refusing to replace existing non-symlink: $PREFIX/bin/karnel"
+    return 1
+  fi
   if [[ ! -L "$PREFIX/bin/karnel" ]] || [[ "$(readlink "$PREFIX/bin/karnel")" != "$KARNEL_PATH/bin/karnel" ]]; then
     ln -sf "$KARNEL_PATH/bin/karnel" "$PREFIX/bin/karnel" 2>/dev/null
     log_success "Symlink updated"

package/karnel/cli/commands/voice.sh

@@ -107,7 +107,9 @@ voice_main() {
     fi
   fi
 
-  if ! command -v "${EDITOR:-nano}" &>/dev/null && [[ "$skip_edit" == "false" ]]; then
+  local -a editor_cmd=()
+  read -r -a editor_cmd <<< "${EDITOR:-nano}"
+  if ! command -v "${editor_cmd[0]}" &>/dev/null && [[ "$skip_edit" == "false" ]]; then
     log_warn "${EDITOR:-nano} not installed — falling back to --raw mode"
     skip_edit=true
   fi
@@ -154,7 +156,7 @@ voice_main() {
     tmpfile="$(mktemp "${TMPDIR:-${KARNEL_CACHE:-$HOME/.cache/karnel}}/karnel-XXXXXX")"
     echo "$raw" >"$tmpfile"
     $is_text || log_info "Review the prompt in ${EDITOR:-nano}, fix mistakes, then save and quit"
-    ${EDITOR:-nano} "$tmpfile" </dev/tty >/dev/tty || true
+    "${editor_cmd[@]}" "$tmpfile" </dev/tty >/dev/tty || true
     prompt="$(< "$tmpfile")"
     rm -f "$tmpfile"
   elif [[ "$skip_edit" == "false" ]] && ! { [[ -t 0 ]] && [[ -t 1 ]]; }; then

package/karnel/modules/voice.sh

@@ -4,6 +4,7 @@ import "@/utils/log"
 import "@/utils/colors"
 
 LOG_FILE="$KARNEL_CACHE/install_voice.log"
+VOICE_MARKER="${KARNEL_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/karnel-data}/voice/.termux-api-managed"
 
 install_voice() {
   separator
@@ -41,8 +42,10 @@ install_voice() {
 }
 
 _install_voice_deps() {
-  pkg install termux-api -y &>>"$LOG_FILE"
-  return $?
+  if ! pkg install termux-api -y &>>"$LOG_FILE"; then
+    return 1
+  fi
+  mkdir -p "$(dirname "$VOICE_MARKER")" && : >"$VOICE_MARKER"
 }
 
 _install_voice_shell() {
@@ -122,7 +125,7 @@ reinstall_voice() {
 }
 
 _reinstall_voice_wrapper() {
-  import "@/tools/voice/all"
-  reinstall_all_voice_components
-  return $?
+  _uninstall_voice_wrapper || return $?
+  _install_voice_deps || return $?
+  _install_voice_shell
 }

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

@@ -9,6 +9,8 @@ LOG_FILE="$KARNEL_CACHE/install_ai.log"
 CODEBUFF_DATA_DIR="$HOME/.local/share/karnel-data/codebuff"
 CODEBUFF_MARKER=".karnel-managed"
 CODEBUFF_WRAPPER_MARKER="$CODEBUFF_DATA_DIR/.karnel-wrapper"
+CODEBUFF_PREVIOUS_DATA=""
+CODEBUFF_STAGED_WRAPPER=""
 
 _codebuff_detect_ubuntu_root() {
   local root
@@ -115,14 +117,44 @@ _download_codebuff_binary_impl() {
   fi
 
   chmod +x "$staging_dir/codebuff"
-  replace_managed_directory "$staging_dir" "$CODEBUFF_DATA_DIR" "$CODEBUFF_MARKER"
+  if ! _activate_codebuff_payload "$staging_dir"; then
+    rm -rf "$staging_dir"
+    return 1
+  fi
 }
 
-_compile_codebuff_helper() {
-  loading "Compiling helper" _compile_codebuff_helper_impl
+_activate_codebuff_payload() {
+  local staging_dir="$1" backup=""
+  printf '%s\n' 'karnel-managed-v1' >"$staging_dir/$CODEBUFF_MARKER" || return 1
+  if [[ -e "$CODEBUFF_DATA_DIR" ]]; then
+    if [[ ! -f "$CODEBUFF_DATA_DIR/$CODEBUFF_MARKER" ]]; then
+      log_error "Refusing to replace unowned installation: $CODEBUFF_DATA_DIR"
+      return 1
+    fi
+    backup=$(mktemp -d "$(dirname "$CODEBUFF_DATA_DIR")/.codebuff-previous.XXXXXX") || return 1
+    rmdir "$backup" || return 1
+    mv "$CODEBUFF_DATA_DIR" "$backup" || return 1
+  fi
+  if ! mv "$staging_dir" "$CODEBUFF_DATA_DIR"; then
+    [[ -z "$backup" ]] || mv "$backup" "$CODEBUFF_DATA_DIR"
+    return 1
+  fi
+  if [[ -n "$backup" && -f "$backup/.karnel-wrapper" ]] &&
+    ! cp "$backup/.karnel-wrapper" "$CODEBUFF_WRAPPER_MARKER"; then
+    rm -rf "$CODEBUFF_DATA_DIR"
+    mv "$backup" "$CODEBUFF_DATA_DIR"
+    return 1
+  fi
+  CODEBUFF_PREVIOUS_DATA="$backup"
+}
+
+_restore_codebuff_payload() {
+  rm -rf "$CODEBUFF_DATA_DIR"
+  [[ -z "$CODEBUFF_PREVIOUS_DATA" ]] || mv "$CODEBUFF_PREVIOUS_DATA" "$CODEBUFF_DATA_DIR"
+  CODEBUFF_PREVIOUS_DATA=""
 }
 
-_compile_codebuff_helper_impl() {
+_stage_codebuff_helper() {
   local HELPER_SRC="$KARNEL_PATH/tools/ai/codebuff/helper/codebuff_helper.c"
   if [ ! -f "$HELPER_SRC" ]; then
     log_error "Helper source not found at $HELPER_SRC"
@@ -130,22 +162,50 @@ _compile_codebuff_helper_impl() {
   fi
 
   local staged_wrapper
+  if [[ -e "$PREFIX/bin/codebuff" || -L "$PREFIX/bin/codebuff" ]] &&
+    ! installer_file_owned "$PREFIX/bin/codebuff" "$CODEBUFF_WRAPPER_MARKER"; then
+    log_error "Refusing to replace an existing Codebuff wrapper not owned by Karnel"
+    return 1
+  fi
   staged_wrapper=$(mktemp "$PREFIX/bin/.codebuff.XXXXXX") || return 1
   if ! cc -O2 -o "$staged_wrapper" "$HELPER_SRC" &>>"$LOG_FILE"; then
     rm -f "$staged_wrapper"
     log_error "Failed to compile codebuff helper"
     return 1
   fi
+  chmod +x "$staged_wrapper" || { rm -f "$staged_wrapper"; return 1; }
+  CODEBUFF_STAGED_WRAPPER="$staged_wrapper"
+}
 
-  chmod +x "$staged_wrapper"
-  mv "$staged_wrapper" "$PREFIX/bin/codebuff" || return 1
-  record_managed_file "$PREFIX/bin/codebuff" "$CODEBUFF_WRAPPER_MARKER"
+_activate_codebuff_wrapper() {
+  activate_installer_file "$CODEBUFF_STAGED_WRAPPER" "$PREFIX/bin/codebuff" "$CODEBUFF_WRAPPER_MARKER"
+}
+
+_compile_codebuff_helper() {
+  loading "Compiling helper" _stage_codebuff_helper || return 1
+  if ! _activate_codebuff_wrapper; then
+    rm -f "$CODEBUFF_STAGED_WRAPPER"
+    return 1
+  fi
+  CODEBUFF_STAGED_WRAPPER=""
 }
 
 _install_codebuff_native() {
+  CODEBUFF_PREVIOUS_DATA="" CODEBUFF_STAGED_WRAPPER=""
   _codebuff_install_deps_native || return 1
-  _download_codebuff_binary || return 1
-  _compile_codebuff_helper || return 1
+  loading "Compiling helper" _stage_codebuff_helper || return 1
+  if ! _download_codebuff_binary; then
+    rm -f "$CODEBUFF_STAGED_WRAPPER"
+    return 1
+  fi
+  if ! _activate_codebuff_wrapper; then
+    rm -f "$CODEBUFF_STAGED_WRAPPER"
+    _restore_codebuff_payload
+    return 1
+  fi
+  CODEBUFF_STAGED_WRAPPER=""
+  [[ -z "$CODEBUFF_PREVIOUS_DATA" ]] || rm -rf "$CODEBUFF_PREVIOUS_DATA"
+  CODEBUFF_PREVIOUS_DATA=""
   log_success "Codebuff installed natively"
   return 0
 }

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

@@ -2,6 +2,7 @@
 
 import "@/utils/log"
 import "@/utils/version"
+import "@/utils/npm-shebang"
 
 LOG_FILE="$KARNEL_CACHE/install_ai.log"
 
@@ -39,6 +40,7 @@ _install_codex_npm_impl() {
 		log_error "Failed to install Codex CLI"
 		return 1
 	fi
+	_fix_npm_shebang "codex"
 
 	return 0
 }
@@ -90,6 +92,7 @@ _update_codex_impl() {
 		log_error "Failed to update Codex CLI"
 		return 1
 	fi
+	_fix_npm_shebang "codex"
 	return 0
 }
 

package/karnel/tools/ai/gemini-cli/install.sh

@@ -2,6 +2,7 @@
 
 import "@/utils/log"
 import "@/utils/version"
+import "@/utils/npm-shebang"
 
 LOG_FILE="$KARNEL_CACHE/install_ai.log"
 
@@ -42,6 +43,7 @@ _install_gemini_cli_npm_impl() {
     log_error "Failed to install Gemini CLI"
     return 1
   fi
+  _fix_npm_shebang "gemini"
 
   return 0
 }
@@ -97,6 +99,7 @@ _update_gemini_cli_impl() {
     log_error "Failed to update Gemini CLI"
     return 1
   fi
+  _fix_npm_shebang "gemini"
   return 0
 }
 

package/karnel/tools/ai/kimi-code/install.sh

@@ -2,6 +2,7 @@
 
 import "@/utils/log"
 import "@/utils/version"
+import "@/utils/npm-shebang"
 
 LOG_FILE="$KARNEL_CACHE/install_ai.log"
 
@@ -39,6 +40,7 @@ _install_kimi_code_npm_impl() {
     log_error "Failed to install Kimi Code"
     return 1
   fi
+  _fix_npm_shebang "kimi"
 
   return 0
 }
@@ -92,6 +94,7 @@ _update_kimi_code_impl() {
     log_error "Failed to update Kimi Code"
     return 1
   fi
+  _fix_npm_shebang "kimi"
   return 0
 }