From 845bb527c833f4e2c66c0fdc1645ebea1e5489d8 Mon Sep 17 00:00:00 2001
From: John Trujillo <johnandrestrujillo@gmail.com>
Date: Mon, 20 Jul 2026 16:10:04 -0500
Subject: [PATCH 1/3] fix(ai-assistant): resolve file picker crashes and secure
 API key

- Fix file picker empty state and `BadTokenException` by using the correct project context (`IdeProjectService`) and moving I/O off the main thread.
- Secure Gemini API key with hardware-backed Keystore encryption (including legacy migration) and add a show/hide toggle.
- Improve UI by replacing emoji markers with vector drawables and extracting hardcoded strings to `strings.xml`.
---
 .../fragments/AiSettingsFragment.kt           |  65 ++++-
 .../aiassistant/fragments/ChatFragment.kt     |  13 +-
 .../fragments/FilePickerDialogFragment.kt     | 267 ++++++++++++------
 .../aiassistant/security/SecureApiKeyStore.kt | 114 ++++++++
 .../viewmodel/AiSettingsViewModel.kt          |  27 +-
 .../src/main/res/drawable/ic_check.xml        |  10 +
 .../src/main/res/drawable/ic_file.xml         |  10 +
 .../src/main/res/drawable/ic_folder.xml       |  10 +
 .../src/main/res/drawable/ic_visibility.xml   |  10 +
 .../main/res/drawable/ic_visibility_off.xml   |  10 +
 .../src/main/res/layout/item_file_picker.xml  |  34 +++
 .../res/layout/layout_settings_gemini_api.xml |  30 +-
 ai-assistant/src/main/res/values/strings.xml  |  16 ++
 .../plugins/aicore/GeminiBackend.kt           |   5 +-
 .../plugins/aicore/SecureApiKeyStore.kt       | 114 ++++++++
 15 files changed, 615 insertions(+), 120 deletions(-)
 create mode 100644 ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
 create mode 100644 ai-assistant/src/main/res/drawable/ic_check.xml
 create mode 100644 ai-assistant/src/main/res/drawable/ic_file.xml
 create mode 100644 ai-assistant/src/main/res/drawable/ic_folder.xml
 create mode 100644 ai-assistant/src/main/res/drawable/ic_visibility.xml
 create mode 100644 ai-assistant/src/main/res/drawable/ic_visibility_off.xml
 create mode 100644 ai-assistant/src/main/res/layout/item_file_picker.xml
 create mode 100644 ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt

diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
index 83c285c1..8c0686a4 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
@@ -5,6 +5,8 @@ import android.content.Context
 import android.content.Intent
 import android.net.Uri
 import android.os.Bundle
+import android.text.method.HideReturnsTransformationMethod
+import android.text.method.PasswordTransformationMethod
 import android.view.LayoutInflater
 import android.view.View
 import android.view.ViewGroup
@@ -290,6 +292,7 @@ class AiSettingsFragment : DialogFragment() {
     private fun setupGeminiApiUi(view: View) {
         val apiKeyLayout = view.findViewById<LinearLayout>(R.id.gemini_api_key_layout)
         val apiKeyInput = view.findViewById<EditText>(R.id.gemini_api_key_input)
+        val toggleVisibilityButton = view.findViewById<ImageButton>(R.id.btn_toggle_api_key_visibility)
         val saveButton = view.findViewById<Button>(R.id.btn_save_api_key)
         val editButton = view.findViewById<Button>(R.id.btn_edit_api_key)
         val clearButton = view.findViewById<Button>(R.id.btn_clear_api_key)
@@ -328,37 +331,69 @@ class AiSettingsFragment : DialogFragment() {
             if (timestamp > 0) {
                 val sdf = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault())
                 val savedDate = sdf.format(Date(timestamp))
-                statusTextView.text = "API Key saved on: $savedDate"
+                statusTextView.text = getString(R.string.msg_api_key_saved_on, savedDate)
             } else {
-                statusTextView.text = "API Key is saved"
+                statusTextView.text = getString(R.string.msg_api_key_is_saved)
             }
         }
 
-        saveButton.setOnClickListener {
-            val apiKey = apiKeyInput.text.toString()
-            if (apiKey.isNotBlank()) {
-                viewModel.saveGeminiApiKey(apiKey)
-                Toast.makeText(requireContext(), "API Key saved", Toast.LENGTH_SHORT).show()
+        toggleVisibilityButton.setColorFilter(apiKeyInput.currentHintTextColor)
 
-                updateUiState(isEditing = false)
-                val timestamp = viewModel.getGeminiApiKeySaveTimestamp()
-                val sdf = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault())
-                val savedDate = sdf.format(Date(timestamp))
-                statusTextView.text = "API Key saved on: $savedDate"
+        var isKeyVisible = false
+
+        fun applyKeyVisibility() {
+            apiKeyInput.transformationMethod = if (isKeyVisible) {
+                HideReturnsTransformationMethod.getInstance()
             } else {
-                Toast.makeText(requireContext(), "API Key cannot be empty", Toast.LENGTH_SHORT).show()
+                PasswordTransformationMethod.getInstance()
             }
+            toggleVisibilityButton.setImageResource(
+                if (isKeyVisible) R.drawable.ic_visibility_off else R.drawable.ic_visibility
+            )
+            toggleVisibilityButton.contentDescription = getString(
+                if (isKeyVisible) R.string.cd_hide_api_key else R.string.cd_show_api_key
+            )
+            toggleVisibilityButton.setColorFilter(apiKeyInput.currentHintTextColor)
+            apiKeyInput.setSelection(apiKeyInput.text?.length ?: 0)
+        }
+
+        applyKeyVisibility()
+
+        toggleVisibilityButton.setOnClickListener {
+            isKeyVisible = !isKeyVisible
+            applyKeyVisibility()
+        }
+
+        saveButton.setOnClickListener {
+            val apiKey = apiKeyInput.text.toString().trim()
+            if (apiKey.isBlank()) {
+                Toast.makeText(requireContext(), getString(R.string.msg_api_key_empty), Toast.LENGTH_SHORT).show()
+                return@setOnClickListener
+            }
+            if (!viewModel.saveGeminiApiKey(apiKey)) {
+                Toast.makeText(requireContext(), getString(R.string.msg_api_key_save_failed), Toast.LENGTH_LONG).show()
+                return@setOnClickListener
+            }
+            Toast.makeText(requireContext(), getString(R.string.msg_api_key_saved), Toast.LENGTH_SHORT).show()
+
+            updateUiState(isEditing = false)
+            val timestamp = viewModel.getGeminiApiKeySaveTimestamp()
+            val sdf = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault())
+            val savedDate = sdf.format(Date(timestamp))
+            statusTextView.text = getString(R.string.msg_api_key_saved_on, savedDate)
         }
 
         editButton.setOnClickListener {
             updateUiState(isEditing = true)
-            apiKeyInput.setText("••••••••••••••••")
+            apiKeyInput.setText(viewModel.getGeminiApiKey().orEmpty())
+            isKeyVisible = false
+            applyKeyVisibility()
             apiKeyInput.requestFocus()
         }
 
         clearButton.setOnClickListener {
             viewModel.clearGeminiApiKey()
-            Toast.makeText(requireContext(), "API Key cleared", Toast.LENGTH_SHORT).show()
+            Toast.makeText(requireContext(), getString(R.string.msg_api_key_cleared), Toast.LENGTH_SHORT).show()
             updateUiState(isEditing = true)
             apiKeyInput.setText("")
         }
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
index a293646f..881c8a69 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
@@ -15,9 +15,11 @@ import androidx.recyclerview.widget.LinearLayoutManager
 import com.google.android.material.chip.Chip
 import com.itsaky.androidide.plugins.PluginContext
 import com.itsaky.androidide.plugins.aiassistant.adapters.ChatAdapter
+import com.itsaky.androidide.plugins.aiassistant.tool.handlers.PathGuard
 import com.itsaky.androidide.plugins.aiassistant.databinding.FragmentChatBinding
 import com.itsaky.androidide.plugins.aiassistant.models.AgentState
 import com.itsaky.androidide.plugins.aiassistant.viewmodel.ChatViewModel
+import com.itsaky.androidide.plugins.services.IdeProjectService
 import io.noties.markwon.Markwon
 import kotlinx.coroutines.launch
 import java.io.File
@@ -334,9 +336,16 @@ class ChatFragment : Fragment() {
         dialog.show(parentFragmentManager, "approval_dialog")
     }
 
+    /**
+     * Opens the file picker rooted at the open project. The host's
+     * [IdeProjectService] is the source of truth for the project root; the
+     * `System.getProperty` chain in [PathGuard] resolves to "/" at runtime (the
+     * IDE process cwd), which lists nothing, so it is only a last-resort fallback.
+     */
     private fun showFilePicker() {
-        // Start from AndroidIDE projects directory by default
-        val startPath = "/storage/emulated/0/AndroidIDEProjects"
+        val projectService = getPluginContext()?.services?.get(IdeProjectService::class.java)
+        val startPath = projectService?.getCurrentProject()?.rootDir?.absolutePath
+            ?: PathGuard.projectRoot()
 
         val dialog = FilePickerDialogFragment.newInstance(startPath) { files ->
             addContextFiles(files)
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
index bc7e2dfa..cba1cfbb 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
@@ -1,143 +1,232 @@
 package com.itsaky.androidide.plugins.aiassistant.fragments
 
 import android.app.Dialog
+import android.content.Context
 import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
 import android.widget.ArrayAdapter
+import android.widget.ImageView
 import android.widget.ListView
+import android.widget.TextView
+import androidx.appcompat.app.AlertDialog
+import androidx.appcompat.view.ContextThemeWrapper
+import androidx.core.view.isVisible
 import androidx.fragment.app.DialogFragment
+import androidx.lifecycle.lifecycleScope
 import com.google.android.material.dialog.MaterialAlertDialogBuilder
+import com.itsaky.androidide.plugins.aiassistant.R
+import com.itsaky.androidide.plugins.aiassistant.tool.handlers.PathGuard
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
 import java.io.File
 
 /**
- * Dialog for picking files to add as context.
+ * Dialog for picking project files to add as chat context.
+ *
+ * The dialog is created once and refreshed **in place** as the user navigates
+ * or toggles selection. It never dismisses-and-recreates itself: doing so
+ * detaches the fragment from its context, after which a follow-up
+ * `requireContext()` throws `IllegalStateException: not attached to a context`
+ * (previously crashed on the second "Toggle All").
+ *
+ * Navigation is confined to the start path supplied by the caller (the open
+ * project root), so the picker can't be used to reach arbitrary files on the
+ * device. All disk I/O runs off the main thread; see [computeListing].
  */
 class FilePickerDialogFragment : DialogFragment() {
 
     private var onFilesSelected: ((List<File>) -> Unit)? = null
-    private var currentDirectory: File? = null
     private val selectedFiles = mutableSetOf<File>()
 
+    /** Root the picker is confined to; navigation can never go above this. */
+    private lateinit var rootDirectory: File
+    private lateinit var currentDirectory: File
+
+    // Reused across in-place refreshes so we never rebuild the Dialog/Fragment.
+    private val rows = mutableListOf<FileRow>()
+    private lateinit var listAdapter: FileRowAdapter
+    private var alertDialog: AlertDialog? = null
+
     companion object {
         private const val ARG_START_PATH = "start_path"
+        private const val PARENT_NAME = ".."
 
         fun newInstance(
             startPath: String? = null,
             onSelected: (List<File>) -> Unit
         ): FilePickerDialogFragment {
             return FilePickerDialogFragment().apply {
+                // Default to the current project root when no path is given.
                 arguments = Bundle().apply {
-                    // Use provided path or default to storage root
-                    val path = startPath ?: "/storage/emulated/0"
-                    putString(ARG_START_PATH, path)
+                    putString(ARG_START_PATH, startPath ?: PathGuard.projectRoot())
                 }
                 onFilesSelected = onSelected
             }
         }
     }
 
-    override fun onCreateDialog(savedInstanceState: Bundle?): Dialog {
-        val startPath = arguments?.getString(ARG_START_PATH) ?: "/storage/emulated/0"
-        currentDirectory = File(startPath)
+    /** One navigable entry: a directory to descend into or a selectable file. */
+    private data class FileRow(
+        val file: File,
+        val displayName: String,
+        val isDirectory: Boolean,
+    )
 
-        if (!currentDirectory!!.exists()) {
-            // Fallback to root if start path doesn't exist
-            currentDirectory = File("/storage/emulated/0")
+    /** Result of a directory scan, computed off the main thread. */
+    private data class Listing(val rows: List<FileRow>, val directory: File)
+
+    override fun onCreateDialog(savedInstanceState: Bundle?): Dialog {
+        val context = ContextThemeWrapper(requireContext(), R.style.PluginTheme)
+        listAdapter = FileRowAdapter(context)
+        val listView = ListView(context).apply {
+            adapter = listAdapter
+            setOnItemClickListener { _, _, position, _ -> onItemClicked(position) }
         }
 
-        if (!currentDirectory!!.exists()) {
-            return MaterialAlertDialogBuilder(requireContext())
-                .setTitle("Error")
-                .setMessage("Storage directory not found")
-                .setPositiveButton("OK") { _, _ -> dismiss() }
-                .create()
+        val dialog = MaterialAlertDialogBuilder(context)
+            .setTitle(R.string.file_picker_title)
+            .setView(listView)
+            .setPositiveButton(R.string.file_picker_add_selected) { _, _ ->
+                onFilesSelected?.invoke(selectedFiles.toList())
+            }
+            .setNegativeButton(android.R.string.cancel, null)
+            // Wired in setOnShowListener so the click doesn't auto-dismiss the dialog.
+            .setNeutralButton(R.string.file_picker_toggle_all, null)
+            .create()
+
+        dialog.setOnShowListener {
+            dialog.getButton(AlertDialog.BUTTON_NEUTRAL)?.setOnClickListener {
+                toggleAllInCurrentDirectory()
+            }
         }
+        alertDialog = dialog
+        loadInitial()
+        return dialog
+    }
 
-        return showDirectoryPicker(currentDirectory!!)
+    /**
+     * Resolve the confined root from the start path and load its listing.
+     * The start path passed by the caller IS the confinement root — the picker
+     * confines navigation to the open project and starts there.
+     */
+    private fun loadInitial() {
+        val rootPath = arguments?.getString(ARG_START_PATH) ?: PathGuard.projectRoot()
+        lifecycleScope.launch {
+            val listing = withContext(Dispatchers.IO) {
+                rootDirectory = File(rootPath).canonicalOrAbsolute()
+                if (!rootDirectory.exists()) {
+                    null
+                } else {
+                    currentDirectory = rootDirectory
+                    computeListing(rootDirectory)
+                }
+            }
+            if (listing == null) {
+                alertDialog?.setTitle(getString(R.string.file_picker_error_not_found))
+            } else {
+                applyListing(listing)
+            }
+        }
     }
 
-    private fun showDirectoryPicker(directory: File): Dialog {
-        val files = directory.listFiles()?.sortedWith(
-            compareBy<File> { !it.isDirectory }
-                .thenBy { it.name }
-        ) ?: emptyList()
+    /** Recompute the listing for [directory] off-thread and apply it in place. */
+    private fun populate(directory: File) {
+        lifecycleScope.launch {
+            val listing = withContext(Dispatchers.IO) {
+                currentDirectory = directory
+                computeListing(directory)
+            }
+            applyListing(listing)
+        }
+    }
 
-        val items = mutableListOf<String>()
-        val fileList = mutableListOf<File>()
+    /** Pure disk I/O — must run on a background dispatcher. */
+    private fun computeListing(directory: File): Listing {
+        val newRows = mutableListOf<FileRow>()
 
-        // Add parent directory option if not at root
-        if (directory.parentFile != null && directory.parentFile!!.exists()) {
-            items.add("📁 ..")
-            fileList.add(directory.parentFile!!)
+        // Offer ".." only while the parent is still inside the confined root.
+        val parent = directory.parentFile
+        if (parent != null && parent.exists() && isWithinRoot(parent) &&
+            canonical(directory) != canonical(rootDirectory)
+        ) {
+            newRows.add(FileRow(parent, PARENT_NAME, isDirectory = true))
         }
 
-        // Add directories and files
-        files.forEach { file ->
-            val prefix = if (file.isDirectory) "📁 " else "📄 "
-            val suffix = if (selectedFiles.contains(file)) " ✓" else ""
-            items.add("$prefix${file.name}$suffix")
-            fileList.add(file)
-        }
+        directory.listFiles()
+            ?.sortedWith(compareBy<File> { !it.isDirectory }.thenBy { it.name.lowercase() })
+            ?.forEach { file -> newRows.add(FileRow(file, file.name, file.isDirectory)) }
+
+        return Listing(newRows, directory)
+    }
 
-        val adapter = ArrayAdapter(
-            requireContext(),
-            android.R.layout.simple_list_item_1,
-            items
-        )
+    /** Swap in a freshly computed [listing] — main thread only. */
+    private fun applyListing(listing: Listing) {
+        rows.clear()
+        rows.addAll(listing.rows)
+        listAdapter.notifyDataSetChanged()
+        alertDialog?.setTitle(titleFor(listing.directory))
+    }
 
-        val listView = ListView(requireContext()).apply {
-            this.adapter = adapter
-            choiceMode = ListView.CHOICE_MODE_MULTIPLE
+    private fun onItemClicked(position: Int) {
+        val row = rows[position]
+        if (row.isDirectory) {
+            populate(row.file)
+        } else {
+            if (!selectedFiles.remove(row.file)) selectedFiles.add(row.file)
+            listAdapter.notifyDataSetChanged()
         }
+    }
 
-        return MaterialAlertDialogBuilder(requireContext())
-            .setTitle("Select Files: ${directory.name}")
-            .setView(listView)
-            .setPositiveButton("Add Selected") { _, _ ->
-                onFilesSelected?.invoke(selectedFiles.toList())
-                dismiss()
-            }
-            .setNegativeButton("Cancel") { _, _ -> dismiss() }
-            .setNeutralButton("Toggle All") { _, _ ->
-                // Toggle all files in current directory
-                val currentFiles = files.filter { it.isFile }
-                if (selectedFiles.containsAll(currentFiles)) {
-                    selectedFiles.removeAll(currentFiles.toSet())
-                } else {
-                    selectedFiles.addAll(currentFiles)
-                }
-                // Refresh dialog
-                dismiss()
-                showDirectoryPicker(directory).show()
-            }
-            .create().apply {
-                listView.setOnItemClickListener { _, _, position, _ ->
-                    val file = fileList[position]
-
-                    if (file.isDirectory) {
-                        // Navigate to directory
-                        dismiss()
-                        showDirectoryPicker(file).show()
-                    } else {
-                        // Toggle file selection
-                        if (selectedFiles.contains(file)) {
-                            selectedFiles.remove(file)
-                        } else {
-                            selectedFiles.add(file)
-                        }
-                        // Refresh display
-                        items[position] = if (selectedFiles.contains(file)) {
-                            "📄 ${file.name} ✓"
-                        } else {
-                            "📄 ${file.name}"
-                        }
-                        adapter.notifyDataSetChanged()
-                    }
-                }
-            }
+    private fun toggleAllInCurrentDirectory() {
+        val currentFiles = rows.filter { !it.isDirectory }.map { it.file }
+        if (currentFiles.isEmpty()) return
+        if (selectedFiles.containsAll(currentFiles)) {
+            selectedFiles.removeAll(currentFiles.toSet())
+        } else {
+            selectedFiles.addAll(currentFiles)
+        }
+        listAdapter.notifyDataSetChanged()
+    }
+
+    private fun titleFor(dir: File): String =
+        getString(R.string.file_picker_title_current, dir.name)
+
+    private fun isWithinRoot(dir: File): Boolean {
+        val root = canonical(rootDirectory)
+        val path = canonical(dir)
+        return path == root || path.startsWith(root + File.separator)
     }
 
+    private fun canonical(f: File): String =
+        try { f.canonicalPath } catch (e: Exception) { f.absolutePath }
+
+    private fun File.canonicalOrAbsolute(): File =
+        try { canonicalFile } catch (e: Exception) { absoluteFile }
+
     override fun onDestroyView() {
         super.onDestroyView()
         onFilesSelected = null
+        alertDialog = null
+    }
+
+    /** Binds each [FileRow] to [R.layout.item_file_picker]; the check reflects selection. */
+    private inner class FileRowAdapter(context: Context) :
+        ArrayAdapter<FileRow>(context, 0, rows) {
+
+        override fun getView(position: Int, convertView: View?, parent: ViewGroup): View {
+            val view = convertView
+                ?: LayoutInflater.from(parent.context).inflate(R.layout.item_file_picker, parent, false)
+            val row = getItem(position) ?: return view
+
+            view.findViewById<ImageView>(R.id.file_picker_row_icon)
+                .setImageResource(if (row.isDirectory) R.drawable.ic_folder else R.drawable.ic_file)
+            view.findViewById<TextView>(R.id.file_picker_row_name).text = row.displayName
+            view.findViewById<ImageView>(R.id.file_picker_row_check).isVisible =
+                selectedFiles.contains(row.file)
+            return view
+        }
     }
 }
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
new file mode 100644
index 00000000..fe42be23
--- /dev/null
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
@@ -0,0 +1,114 @@
+package com.itsaky.androidide.plugins.aiassistant.security
+
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import android.util.Log
+import java.security.GeneralSecurityException
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * AES/GCM encryption for sensitive settings (currently the Gemini API key),
+ * keyed by a hardware-backed Android Keystore secret. Only ciphertext is
+ * written to SharedPreferences, so a copied prefs file (root, `adb backup`,
+ * forensic dump) is useless without this device's Keystore.
+ *
+ * The alias and transform below are mirrored verbatim in ai-core's
+ * `SecureApiKeyStore` so a key written here can be decrypted there — both
+ * plugins run in the host app's process (same UID) and therefore share one
+ * Android Keystore. Keep the two copies in sync.
+ */
+object SecureApiKeyStore {
+    private const val TAG = "SecureApiKeyStore"
+    private const val KEYSTORE = "AndroidKeyStore"
+    private const val ALIAS = "cotg_ai_gemini_key_v1"
+    private const val TRANSFORM = "AES/GCM/NoPadding"
+    private const val IV_LEN = 12
+    private const val TAG_BITS = 128
+
+    /** Marks a stored value as ciphertext; anything without it is treated as legacy plaintext. */
+    const val ENC_PREFIX = "enc:v1:"
+
+    private fun getOrCreateKey(): SecretKey {
+        val ks = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+        (ks.getEntry(ALIAS, null) as? KeyStore.SecretKeyEntry)?.let { return it.secretKey }
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+        generator.init(
+            KeyGenParameterSpec.Builder(
+                ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .build()
+        )
+        return generator.generateKey()
+    }
+
+    private fun deleteKey() {
+        try {
+            KeyStore.getInstance(KEYSTORE).apply { load(null) }.deleteEntry(ALIAS)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to delete Keystore alias $ALIAS", e)
+        }
+    }
+
+    private fun encryptWith(key: SecretKey, plain: String): String {
+        val cipher = Cipher.getInstance(TRANSFORM)
+        cipher.init(Cipher.ENCRYPT_MODE, key)
+        val iv = cipher.iv
+        val ciphertext = cipher.doFinal(plain.toByteArray(Charsets.UTF_8))
+        val combined = ByteArray(iv.size + ciphertext.size)
+        System.arraycopy(iv, 0, combined, 0, iv.size)
+        System.arraycopy(ciphertext, 0, combined, iv.size, ciphertext.size)
+        return ENC_PREFIX + Base64.encodeToString(combined, Base64.NO_WRAP)
+    }
+
+    /**
+     * Encrypt [plain] into a self-describing string: [ENC_PREFIX] + base64(iv | ciphertext).
+     *
+     * If the Keystore key has been permanently invalidated (e.g. the lock-screen credentials
+     * changed, or the entry is corrupt) the stale alias is dropped and a fresh key generated
+     * once before retrying. Any other Keystore/cipher failure is surfaced as a
+     * [GeneralSecurityException] so the caller can inform the user instead of crashing — the
+     * previous version let these propagate uncaught and take the IDE down on Save.
+     */
+    @Throws(GeneralSecurityException::class)
+    fun encrypt(plain: String): String {
+        return try {
+            encryptWith(getOrCreateKey(), plain)
+        } catch (e: KeyPermanentlyInvalidatedException) {
+            Log.w(TAG, "Keystore key invalidated; regenerating and retrying encrypt", e)
+            deleteKey()
+            encryptWith(getOrCreateKey(), plain)
+        }
+    }
+
+    /**
+     * Return the plaintext for a stored value, handling both formats transparently:
+     * an [ENC_PREFIX] value is decrypted; anything else is returned unchanged as
+     * legacy plaintext (it gets migrated to ciphertext on the next save). Returns
+     * null if a ciphertext value can't be decrypted — e.g. the Keystore key was
+     * lost or invalidated — in which case the user must re-enter the key.
+     */
+    fun decrypt(stored: String?): String? {
+        if (stored == null) return null
+        if (!stored.startsWith(ENC_PREFIX)) return stored
+        return try {
+            val combined = Base64.decode(stored.removePrefix(ENC_PREFIX), Base64.NO_WRAP)
+            val iv = combined.copyOfRange(0, IV_LEN)
+            val ciphertext = combined.copyOfRange(IV_LEN, combined.size)
+            val cipher = Cipher.getInstance(TRANSFORM)
+            cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(), GCMParameterSpec(TAG_BITS, iv))
+            String(cipher.doFinal(ciphertext), Charsets.UTF_8)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to decrypt stored API key", e)
+            null
+        }
+    }
+}
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
index 0ca9b3c1..22ea0c41 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
@@ -5,6 +5,7 @@ import androidx.lifecycle.LiveData
 import androidx.lifecycle.MutableLiveData
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import com.itsaky.androidide.plugins.aiassistant.security.SecureApiKeyStore
 import com.itsaky.androidide.plugins.services.LlmInferenceService
 import com.itsaky.androidide.plugins.services.SharedServices
 import kotlinx.coroutines.Dispatchers
@@ -188,21 +189,33 @@ class AiSettingsViewModel(
     }
 
     /**
-     * Persists the Gemini API key in this plugin's private SharedPreferences.
-     * The store is app-sandboxed (not world-readable) but NOT encrypted at rest;
-     * it is recoverable on a rooted/compromised device. Use [clearGeminiApiKey]
-     * to remove it. See the plugin README "Security" section for the tradeoff.
+     * Persists the Gemini API key in this plugin's private SharedPreferences,
+     * encrypted at rest with a hardware-backed Android Keystore secret (see
+     * [SecureApiKeyStore]). Only ciphertext is written, so the prefs file alone
+     * (root, `adb backup`, forensic dump) does not disclose the key. Use
+     * [clearGeminiApiKey] to remove it.
+     *
+     * Returns false (persisting nothing) if encryption fails — e.g. a hardware Keystore
+     * fault the automatic key-regeneration retry couldn't recover — so the caller can warn
+     * the user instead of the whole IDE crashing on Save.
      */
-    fun saveGeminiApiKey(apiKey: String) {
+    fun saveGeminiApiKey(apiKey: String): Boolean {
+        val encrypted = try {
+            SecureApiKeyStore.encrypt(apiKey.trim())
+        } catch (e: Exception) {
+            android.util.Log.e(TAG, "Failed to encrypt Gemini API key", e)
+            return false
+        }
         getPluginPrefs()?.edit()?.apply {
-            putString("gemini_api_key", apiKey)
+            putString("gemini_api_key", encrypted)
             putLong("gemini_api_key_timestamp", System.currentTimeMillis())
             apply()
         }
+        return true
     }
 
     fun getGeminiApiKey(): String? {
-        return getPluginPrefs()?.getString("gemini_api_key", null)
+        return SecureApiKeyStore.decrypt(getPluginPrefs()?.getString("gemini_api_key", null))
     }
 
     fun getGeminiApiKeySaveTimestamp(): Long {
diff --git a/ai-assistant/src/main/res/drawable/ic_check.xml b/ai-assistant/src/main/res/drawable/ic_check.xml
new file mode 100644
index 00000000..9368bf87
--- /dev/null
+++ b/ai-assistant/src/main/res/drawable/ic_check.xml
@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorPrimary">
+  <path
+      android:fillColor="@android:color/white"
+      android:pathData="M9,16.17L4.83,12l-1.42,1.41L9,19 21,7l-1.41,-1.41z"/>
+</vector>
diff --git a/ai-assistant/src/main/res/drawable/ic_file.xml b/ai-assistant/src/main/res/drawable/ic_file.xml
new file mode 100644
index 00000000..f239f312
--- /dev/null
+++ b/ai-assistant/src/main/res/drawable/ic_file.xml
@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorControlNormal">
+  <path
+      android:fillColor="@android:color/white"
+      android:pathData="M14,2H6c-1.1,0 -1.99,0.9 -1.99,2L4,20c0,1.1 0.89,2 1.99,2H18c1.1,0 2,-0.9 2,-2V8l-6,-6zM16,18H8v-2h8v2zM16,14H8v-2h8v2zM13,9V3.5L18.5,9H13z"/>
+</vector>
diff --git a/ai-assistant/src/main/res/drawable/ic_folder.xml b/ai-assistant/src/main/res/drawable/ic_folder.xml
new file mode 100644
index 00000000..dc6b0802
--- /dev/null
+++ b/ai-assistant/src/main/res/drawable/ic_folder.xml
@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorControlNormal">
+  <path
+      android:fillColor="@android:color/white"
+      android:pathData="M10,4H4c-1.1,0 -1.99,0.9 -1.99,2L2,18c0,1.1 0.9,2 2,2h16c1.1,0 2,-0.9 2,-2V8c0,-1.1 -0.9,-2 -2,-2h-8l-2,-2z"/>
+</vector>
diff --git a/ai-assistant/src/main/res/drawable/ic_visibility.xml b/ai-assistant/src/main/res/drawable/ic_visibility.xml
new file mode 100644
index 00000000..a3e222a2
--- /dev/null
+++ b/ai-assistant/src/main/res/drawable/ic_visibility.xml
@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorControlNormal">
+  <path
+      android:fillColor="@android:color/white"
+      android:pathData="M12,4.5C7,4.5 2.73,7.61 1,12c1.73,4.39 6,7.5 11,7.5s9.27,-3.11 11,-7.5c-1.73,-4.39 -6,-7.5 -11,-7.5zM12,17c-2.76,0 -5,-2.24 -5,-5s2.24,-5 5,-5 5,2.24 5,5 -2.24,5 -5,5zM12,9c-1.66,0 -3,1.34 -3,3s1.34,3 3,3 3,-1.34 3,-3 -1.34,-3 -3,-3z"/>
+</vector>
diff --git a/ai-assistant/src/main/res/drawable/ic_visibility_off.xml b/ai-assistant/src/main/res/drawable/ic_visibility_off.xml
new file mode 100644
index 00000000..92c48569
--- /dev/null
+++ b/ai-assistant/src/main/res/drawable/ic_visibility_off.xml
@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorControlNormal">
+  <path
+      android:fillColor="@android:color/white"
+      android:pathData="M12,7c2.76,0 5,2.24 5,5 0,0.65 -0.13,1.26 -0.36,1.83l2.92,2.92c1.51,-1.26 2.7,-2.89 3.43,-4.75 -1.73,-4.39 -6,-7.5 -11,-7.5 -1.4,0 -2.74,0.25 -3.98,0.7l2.16,2.16C10.74,7.13 11.35,7 12,7zM2,4.27l2.28,2.28 0.46,0.46C3.08,8.3 1.78,10.02 1,12c1.73,4.39 6,7.5 11,7.5 1.55,0 3.03,-0.3 4.38,-0.84l0.42,0.42L19.73,22 21,20.73 3.27,3 2,4.27zM7.53,9.8l1.55,1.55c-0.05,0.21 -0.08,0.43 -0.08,0.65 0,1.66 1.34,3 3,3 0.22,0 0.44,-0.03 0.65,-0.08l1.55,1.55c-0.67,0.33 -1.41,0.53 -2.2,0.53 -2.76,0 -5,-2.24 -5,-5 0,-0.79 0.2,-1.53 0.53,-2.2zM11.84,9.02l3.15,3.15 0.02,-0.16c0,-1.66 -1.34,-3 -3,-3l-0.17,0.01z"/>
+</vector>
diff --git a/ai-assistant/src/main/res/layout/item_file_picker.xml b/ai-assistant/src/main/res/layout/item_file_picker.xml
new file mode 100644
index 00000000..20efc497
--- /dev/null
+++ b/ai-assistant/src/main/res/layout/item_file_picker.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:minHeight="48dp"
+    android:gravity="center_vertical"
+    android:orientation="horizontal"
+    android:paddingHorizontal="16dp"
+    android:paddingVertical="12dp">
+
+    <ImageView
+        android:id="@+id/file_picker_row_icon"
+        android:layout_width="24dp"
+        android:layout_height="24dp"
+        android:importantForAccessibility="no" />
+
+    <TextView
+        android:id="@+id/file_picker_row_name"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:layout_weight="1"
+        android:layout_marginStart="16dp"
+        android:textAppearance="?attr/textAppearanceBodyLarge"
+        android:textColor="?attr/colorOnSurface" />
+
+    <ImageView
+        android:id="@+id/file_picker_row_check"
+        android:layout_width="24dp"
+        android:layout_height="24dp"
+        android:layout_marginStart="8dp"
+        android:src="@drawable/ic_check"
+        android:importantForAccessibility="no"
+        android:visibility="gone" />
+</LinearLayout>
diff --git a/ai-assistant/src/main/res/layout/layout_settings_gemini_api.xml b/ai-assistant/src/main/res/layout/layout_settings_gemini_api.xml
index 179cbb56..5a5819b7 100644
--- a/ai-assistant/src/main/res/layout/layout_settings_gemini_api.xml
+++ b/ai-assistant/src/main/res/layout/layout_settings_gemini_api.xml
@@ -27,13 +27,33 @@
             android:textAppearance="?android:attr/textAppearanceSmall"
             android:paddingBottom="4dp"/>
 
-        <EditText
-            android:id="@+id/gemini_api_key_input"
+        <LinearLayout
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
-            android:inputType="textPassword"
-            android:hint="Enter your Gemini API key"
-            android:maxLines="1" />
+            android:gravity="center_vertical"
+            android:orientation="horizontal">
+
+            <EditText
+                android:id="@+id/gemini_api_key_input"
+                android:layout_width="0dp"
+                android:layout_height="wrap_content"
+                android:layout_weight="1"
+                android:inputType="textPassword"
+                android:hint="@string/hint_gemini_api_key"
+                android:maxLines="1" />
+
+            <ImageButton
+                android:id="@+id/btn_toggle_api_key_visibility"
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:layout_marginStart="4dp"
+                android:background="?android:attr/selectableItemBackgroundBorderless"
+                android:contentDescription="@string/cd_show_api_key"
+                android:minWidth="0dp"
+                android:minHeight="0dp"
+                android:padding="4dp"
+                android:src="@drawable/ic_visibility" />
+        </LinearLayout>
     </LinearLayout>
 
     <LinearLayout
diff --git a/ai-assistant/src/main/res/values/strings.xml b/ai-assistant/src/main/res/values/strings.xml
index b9695d93..c199a12a 100644
--- a/ai-assistant/src/main/res/values/strings.xml
+++ b/ai-assistant/src/main/res/values/strings.xml
@@ -92,6 +92,15 @@
 
     <!-- Settings -->
     <string name="settings_title">AI Settings</string>
+    <string name="cd_show_api_key">Show API key</string>
+    <string name="cd_hide_api_key">Hide API key</string>
+    <string name="hint_gemini_api_key">Enter your Gemini API key</string>
+    <string name="msg_api_key_saved">API Key saved</string>
+    <string name="msg_api_key_saved_on">API Key saved on: %s</string>
+    <string name="msg_api_key_is_saved">API Key is saved</string>
+    <string name="msg_api_key_empty">API Key cannot be empty</string>
+    <string name="msg_api_key_cleared">API Key cleared</string>
+    <string name="msg_api_key_save_failed">Couldn\'t save the API key on this device. Please try again.</string>
     <string name="settings_backend">Backend</string>
     <string name="settings_model">Model</string>
     <string name="settings_temperature">Temperature</string>
@@ -105,4 +114,11 @@
     <string name="experimental_ai_use_at_your_own_risk">⚠️ Experimental AI. Use at your own risk.</string>
     <string name="current_ai_backend">Current AI backend</string>
     <string name="send">Send</string>
+
+    <!-- File picker -->
+    <string name="file_picker_title">Select Files</string>
+    <string name="file_picker_title_current">Select Files: %s</string>
+    <string name="file_picker_add_selected">Add Selected</string>
+    <string name="file_picker_toggle_all">Toggle All</string>
+    <string name="file_picker_error_not_found">Project directory not found</string>
 </resources>
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
index 081488b8..a15ec634 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
@@ -73,7 +73,8 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
             context.logger.error("GeminiBackend: Error getting preferences", e)
             null
         }
-        return prefs?.getString("gemini_api_key", null)?.trim()?.takeIf { it.isNotBlank() }
+        val stored = prefs?.getString("gemini_api_key", null)
+        return SecureApiKeyStore.decrypt(stored)?.trim()?.takeIf { it.isNotBlank() }
     }
 
     override fun getId(): String = "gemini"
@@ -81,7 +82,7 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
     override fun getName(): String = "Gemini API"
 
     override fun isAvailable(): Boolean {
-        // Available once an API key is configured.
+        // Available once a (decryptable) API key is configured.
         val apiKey = readGeminiApiKey()
         context.logger.debug("GeminiBackend.isAvailable() - API key configured: ${!apiKey.isNullOrBlank()}")
         return !apiKey.isNullOrBlank()
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
new file mode 100644
index 00000000..1e31a7fc
--- /dev/null
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
@@ -0,0 +1,114 @@
+package com.itsaky.androidide.plugins.aicore
+
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import android.util.Log
+import java.security.GeneralSecurityException
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * AES/GCM encryption for sensitive settings (currently the Gemini API key),
+ * keyed by a hardware-backed Android Keystore secret. Only ciphertext is
+ * written to SharedPreferences, so a copied prefs file (root, `adb backup`,
+ * forensic dump) is useless without this device's Keystore.
+ *
+ * The alias and transform below are mirrored verbatim in ai-assistant's
+ * `SecureApiKeyStore` so a key written there can be decrypted here — both
+ * plugins run in the host app's process (same UID) and therefore share one
+ * Android Keystore. Keep the two copies in sync.
+ */
+object SecureApiKeyStore {
+    private const val TAG = "SecureApiKeyStore"
+    private const val KEYSTORE = "AndroidKeyStore"
+    private const val ALIAS = "cotg_ai_gemini_key_v1"
+    private const val TRANSFORM = "AES/GCM/NoPadding"
+    private const val IV_LEN = 12
+    private const val TAG_BITS = 128
+
+    /** Marks a stored value as ciphertext; anything without it is treated as legacy plaintext. */
+    const val ENC_PREFIX = "enc:v1:"
+
+    private fun getOrCreateKey(): SecretKey {
+        val ks = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+        (ks.getEntry(ALIAS, null) as? KeyStore.SecretKeyEntry)?.let { return it.secretKey }
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+        generator.init(
+            KeyGenParameterSpec.Builder(
+                ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .build()
+        )
+        return generator.generateKey()
+    }
+
+    private fun deleteKey() {
+        try {
+            KeyStore.getInstance(KEYSTORE).apply { load(null) }.deleteEntry(ALIAS)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to delete Keystore alias $ALIAS", e)
+        }
+    }
+
+    private fun encryptWith(key: SecretKey, plain: String): String {
+        val cipher = Cipher.getInstance(TRANSFORM)
+        cipher.init(Cipher.ENCRYPT_MODE, key)
+        val iv = cipher.iv
+        val ciphertext = cipher.doFinal(plain.toByteArray(Charsets.UTF_8))
+        val combined = ByteArray(iv.size + ciphertext.size)
+        System.arraycopy(iv, 0, combined, 0, iv.size)
+        System.arraycopy(ciphertext, 0, combined, iv.size, ciphertext.size)
+        return ENC_PREFIX + Base64.encodeToString(combined, Base64.NO_WRAP)
+    }
+
+    /**
+     * Encrypt [plain] into a self-describing string: [ENC_PREFIX] + base64(iv | ciphertext).
+     *
+     * If the Keystore key has been permanently invalidated (e.g. the lock-screen credentials
+     * changed, or the entry is corrupt) the stale alias is dropped and a fresh key generated
+     * once before retrying. Any other Keystore/cipher failure is surfaced as a
+     * [GeneralSecurityException] so the caller can inform the user instead of crashing — the
+     * previous version let these propagate uncaught and take the IDE down on Save.
+     */
+    @Throws(GeneralSecurityException::class)
+    fun encrypt(plain: String): String {
+        return try {
+            encryptWith(getOrCreateKey(), plain)
+        } catch (e: KeyPermanentlyInvalidatedException) {
+            Log.w(TAG, "Keystore key invalidated; regenerating and retrying encrypt", e)
+            deleteKey()
+            encryptWith(getOrCreateKey(), plain)
+        }
+    }
+
+    /**
+     * Return the plaintext for a stored value, handling both formats transparently:
+     * an [ENC_PREFIX] value is decrypted; anything else is returned unchanged as
+     * legacy plaintext (it gets migrated to ciphertext on the next save). Returns
+     * null if a ciphertext value can't be decrypted — e.g. the Keystore key was
+     * lost or invalidated — in which case the user must re-enter the key.
+     */
+    fun decrypt(stored: String?): String? {
+        if (stored == null) return null
+        if (!stored.startsWith(ENC_PREFIX)) return stored
+        return try {
+            val combined = Base64.decode(stored.removePrefix(ENC_PREFIX), Base64.NO_WRAP)
+            val iv = combined.copyOfRange(0, IV_LEN)
+            val ciphertext = combined.copyOfRange(IV_LEN, combined.size)
+            val cipher = Cipher.getInstance(TRANSFORM)
+            cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(), GCMParameterSpec(TAG_BITS, iv))
+            String(cipher.doFinal(ciphertext), Charsets.UTF_8)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to decrypt stored API key", e)
+            null
+        }
+    }
+}

From c25ee891bc3b7ce8f9a8a838038d837acc8a26ab Mon Sep 17 00:00:00 2001
From: John Trujillo <johnandrestrujillo@gmail.com>
Date: Thu, 23 Jul 2026 15:23:33 -0500
Subject: [PATCH 2/3] fix(ai-assistant,ai-core): secure Gemini API key at rest
 and confine the file picker

Encrypt the key with AES/GCM under an Android Keystore secret and run all crypto off the UI thread; confine the context-file picker to the open project via normalized canonical-path checks with off-thread listing and no fallback root.
---
 ai-assistant/README.md                        |  41 +++-
 ai-assistant/src/main/AndroidManifest.xml     |   3 +-
 ai-assistant/src/main/assets/docs/index.html  |  32 +++
 .../plugins/aiassistant/AiAssistantPlugin.kt  | 195 +++++++++++++++++-
 .../aiassistant/adapters/ChatAdapter.kt       |  12 ++
 .../fragments/AiSettingsFragment.kt           | 123 ++++++++---
 .../aiassistant/fragments/ChatFragment.kt     |  58 +++++-
 .../fragments/FilePickerDialogFragment.kt     |  91 +++++---
 .../aiassistant/security/SecureApiKeyStore.kt |  39 +++-
 .../viewmodel/AiSettingsViewModel.kt          |  95 ++++++---
 ai-assistant/src/main/res/values/strings.xml  |   2 +
 .../plugins/aicore/GeminiBackend.kt           |  88 ++++++--
 .../plugins/aicore/LocalLlmBackend.kt         |  36 +++-
 .../plugins/aicore/SecureApiKeyStore.kt       |  39 +++-
 14 files changed, 717 insertions(+), 137 deletions(-)

diff --git a/ai-assistant/README.md b/ai-assistant/README.md
index 5a01ae6b..e3e09f7a 100644
--- a/ai-assistant/README.md
+++ b/ai-assistant/README.md
@@ -58,19 +58,40 @@ The build resolves `plugin-api.jar` from the repo-root `../libs/`.
 
 ## Security
 
-- **Gemini API key at rest.** When you use the Gemini backend, the API key is
-  stored in this plugin's private `SharedPreferences` (`AgentSettings`). That
-  store is **app-sandboxed** — other apps cannot read it — but it is **not
-  encrypted at rest**, so it is recoverable on a rooted or otherwise compromised
-  device. Remove it any time from **AI Settings** (or `clearGeminiApiKey()`).
-  Encryption is deliberately not layered on here: the key is shared at runtime
-  with the sibling `ai-core` plugin (which performs the Gemini calls), and
-  `EncryptedSharedPreferences` would force both independent plugins to agree on a
-  master-key alias and crypto library version — a fragile cross-plugin coupling.
-  A host-provided secure-storage service is the correct long-term fix.
+- **Gemini API key at rest.** The key is encrypted with AES/GCM under a
+  hardware-backed Android Keystore secret and only the ciphertext is written to
+  this plugin's private `SharedPreferences` (`AgentSettings`), as
+  `enc:v1:` + base64(iv‖ciphertext). A copied prefs file — root, `adb backup`,
+  forensic dump — is useless without this device's Keystore. Remove the key any
+  time from **AI Settings** (or `clearGeminiApiKey()`).
+  - A key stored before this plugin encrypted them is still plaintext on disk;
+    it is re-encrypted in place the first time it's read
+    (`SecureApiKeyStore.readAndMigrate`), so no user action is needed.
+  - The key is **not** bound to user authentication
+    (`setUserAuthenticationRequired` is not set), so it stays usable for
+    background inference and a lock-screen credential change does not invalidate
+    it. If the Keystore entry is lost anyway — the app's data is cleared, or an
+    OEM Keystore drops the alias — the stored key can no longer be decrypted and
+    must be re-entered; **Edit** says so instead of presenting an empty field.
+    Saving surfaces a failure message rather than silently storing nothing.
+  - Encryption at rest defends against *offline* recovery of the prefs file. It
+    does not defend against code already running as the host IDE's UID, which can
+    simply call `decrypt` — that would need a host-provided secure-storage
+    service with per-plugin isolation.
+- **Shared crypto across two plugins.** `ai-core` performs the Gemini calls and
+  therefore has to read the same key. Both plugins run in the host IDE's process
+  (same UID) and so share one Android Keystore; each ships an identical copy of
+  `SecureApiKeyStore` pinned to the alias `cotg_ai_gemini_key_v1`. The two copies
+  must stay byte-identical apart from their package line — if `ALIAS`,
+  `TRANSFORM`, `IV_LEN` or `ENC_PREFIX` drift, `ai-core` silently fails to
+  decrypt and Gemini reports "backend not available". A host-provided
+  secure-storage service would remove the duplication.
 - **Gemini API key in transit.** The key is sent to Google as an `x-goog-api-key`
   request header (and via the SDK on the chat path), never in a URL query string.
 - **File tools are confined to the project root** — see the in-IDE help page.
+- **The context-file picker is confined to the open project** and fails closed:
+  with no project open it refuses to open rather than falling back to a broader
+  root.
 
 ## License
 
diff --git a/ai-assistant/src/main/AndroidManifest.xml b/ai-assistant/src/main/AndroidManifest.xml
index f50acac3..7cdab370 100644
--- a/ai-assistant/src/main/AndroidManifest.xml
+++ b/ai-assistant/src/main/AndroidManifest.xml
@@ -40,9 +40,10 @@
             android:name="plugin.editor_tabs"
             android:value="1" />
 
+        <!-- ide.settings: AiAssistantPlugin's migration reads the host store. No network.access: ai-core makes the Gemini calls. -->
         <meta-data
             android:name="plugin.permissions"
-            android:value="filesystem.read,filesystem.write,system.commands,project.structure" />
+            android:value="filesystem.read,filesystem.write,system.commands,project.structure,ide.settings" />
 
         <meta-data
             android:name="plugin.main_class"
diff --git a/ai-assistant/src/main/assets/docs/index.html b/ai-assistant/src/main/assets/docs/index.html
index 6bef0c06..c17a60a8 100644
--- a/ai-assistant/src/main/assets/docs/index.html
+++ b/ai-assistant/src/main/assets/docs/index.html
@@ -64,6 +64,38 @@ <h2>What the agent can do</h2>
     device.
   </div>
 
+  <h2>Attaching context files</h2>
+  <ul>
+    <li>Tap the <b>attach</b> button beside the prompt to pick files whose
+      contents are sent with your next message.</li>
+    <li>The picker is rooted at the project you have open and cannot browse
+      above it. With no project open it declines to open at all.</li>
+    <li><b>Toggle All</b> selects every file in the folder you are viewing;
+      <b>Add Selected</b> attaches them as chips above the prompt.</li>
+    <li>On the Gemini backend, attached file contents leave the device.</li>
+  </ul>
+
+  <h2>Your Gemini API key</h2>
+  <p>The key is encrypted with AES/GCM under a hardware-backed Android Keystore
+  secret, and only the ciphertext is written to the plugin's private storage —
+  a copied preferences file is useless without this device's Keystore. Clear it
+  any time from <b>Settings</b>. If the Keystore entry is ever lost — clearing the
+  app's data, for example — the stored key can no longer be read and will need to
+  be entered again; tapping <b>Edit</b> tells you when that has happened.</p>
+
+  <h2>Reading the conversation</h2>
+  <ul>
+    <li><b>Retry</b> appears on a message whose reply failed, and re-sends the
+      same prompt with the same attached files rather than adding a new one.</li>
+    <li><b>Open AI Settings</b> appears instead when the agent has not been
+      configured yet — no local model chosen, or no Gemini key saved.</li>
+    <li><b>System log</b> rows are collapsed records of the agent's internal
+      steps: tools run, files touched, backend errors. Tap the header to expand
+      one. They are saved with the session but are not sent to the model.</li>
+    <li>Long-press a message to copy its text, or to edit and re-send one of
+      your own.</li>
+  </ul>
+
   <h2>Troubleshooting</h2>
   <ul>
     <li><b>"No model configured"</b> — select a <code>.gguf</code> file (Local)
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/AiAssistantPlugin.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/AiAssistantPlugin.kt
index 7138429b..813c7518 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/AiAssistantPlugin.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/AiAssistantPlugin.kt
@@ -28,10 +28,25 @@ class AiAssistantPlugin : IPlugin, UIExtension, DocumentationExtension {
 
         const val TOOLTIP_TAG_TAB = "agent_chat_tab"
 
+        // Tags for the interactive controls on the Agent chat screen (see ChatFragment).
+        const val TOOLTIP_TAG_CONTEXT_FILES = "agent_context_files"
+        const val TOOLTIP_TAG_CHAT_INPUT = "agent_chat_input"
+        const val TOOLTIP_TAG_CHAT_SEND = "agent_chat_send"
+        const val TOOLTIP_TAG_CHAT_MENU = "agent_chat_menu"
+
+        // Tags for the controls rendered inside chat messages (see ChatAdapter).
+        const val TOOLTIP_TAG_MESSAGE_RETRY = "agent_message_retry"
+        const val TOOLTIP_TAG_MESSAGE_OPEN_SETTINGS = "agent_message_open_settings"
+        const val TOOLTIP_TAG_SYSTEM_LOG = "agent_system_log"
+
         // Tags for the interactive controls on the AI Settings dialog (see AiSettingsFragment).
+        const val TOOLTIP_TAG_SETTINGS_BACK = "ai_settings_back"
         const val TOOLTIP_TAG_SETTINGS_BACKEND = "ai_settings_backend"
         const val TOOLTIP_TAG_SETTINGS_LOCAL_MODEL = "ai_settings_local_model"
+        const val TOOLTIP_TAG_SETTINGS_LOCAL_SHA = "ai_settings_local_model_sha"
+        const val TOOLTIP_TAG_SETTINGS_SIMPLE_PROMPT = "ai_settings_simple_prompt"
         const val TOOLTIP_TAG_SETTINGS_GEMINI_KEY = "ai_settings_gemini_key"
+        const val TOOLTIP_TAG_SETTINGS_GEMINI_MODEL = "ai_settings_gemini_model"
 
         @Volatile
         private var pluginContext: PluginContext? = null
@@ -135,6 +150,126 @@ class AiAssistantPlugin : IPlugin, UIExtension, DocumentationExtension {
                 )
             )
         ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_CONTEXT_FILES,
+            summary = "Attach project files so the agent sees their contents with your next message.",
+            detail = """
+                <p>Opens a picker rooted at the <b>currently open project</b>; you
+                can browse subfolders but not above the project root, and the
+                picker won't open at all when no project is open.</p>
+                <p>Tap files to select them, <b>Toggle All</b> to select every file
+                in the folder you're viewing, then <b>Add Selected</b>. Attached
+                files appear as chips above the prompt — remove a chip to drop the
+                file again.</p>
+                <p>Contents are sent with your message, so on the Gemini backend
+                they leave the device.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_CHAT_INPUT,
+            summary = "Type your request here — questions, or instructions to change the project.",
+            detail = """
+                <p>Ask a question ("what does this class do?") or give an
+                instruction ("add a Room dependency"). Plain read-only requests
+                such as <i>open</i>, <i>read</i>, <i>list</i> and <i>search</i>
+                are recognised directly and run without going through the model,
+                so they work on every backend.</p>
+                <p>Anything that writes to the project asks for your approval
+                first.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_CHAT_SEND,
+            summary = "Send the prompt — turns into Stop while the agent is working.",
+            detail = """
+                <p>Sends your message to the selected backend. It stays disabled
+                until you type something.</p>
+                <p>While the agent is thinking or running tools this same button
+                becomes <b>Stop</b>: tapping it cancels the current turn, ends any
+                in-progress reply and discards the remaining tool steps.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_CHAT_MENU,
+            summary = "Agent menu: open AI Settings or start a new chat session.",
+            detail = """
+                <p>Opens the Agent's overflow menu:</p>
+                <ul>
+                  <li><b>Settings</b> — choose the backend (Local or Gemini),
+                      pick a model and manage your Gemini API key.</li>
+                  <li><b>Clear chat</b> — starts a fresh session. The previous
+                      conversation stays on disk in the plugin's own storage.</li>
+                </ul>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_MESSAGE_RETRY,
+            summary = "Send that message again after a failed reply.",
+            detail = """
+                <p>Appears on a message whose reply failed — a dropped network
+                request, a model that wasn't loaded, or a turn you stopped.</p>
+                <p><b>Retry</b> re-sends the same prompt with the same attached
+                context files; it does not add a new message to the conversation.
+                If it keeps failing, check the backend and model under
+                <b>Settings</b>.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_MESSAGE_OPEN_SETTINGS,
+            summary = "Jump to AI Settings to fix the problem this message reports.",
+            detail = """
+                <p>Shown when the agent could not run because it is not configured
+                yet — no local model selected, or no Gemini API key saved.</p>
+                <p>Opens <b>AI Settings</b> so you can choose a backend, pick a
+                <code>.gguf</code> model or enter a key, then return and send your
+                message again.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_SYSTEM_LOG,
+            summary = "Collapsed system log — tap to expand the agent's internal steps.",
+            detail = """
+                <p>System entries record what the agent did behind the scenes: the
+                tools it ran, the files it touched and any errors the backend
+                reported.</p>
+                <p>They stay collapsed to keep the conversation readable — tap the
+                header to expand or collapse one. They are part of the saved
+                session, not messages sent to the model.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_SETTINGS_BACK,
+            summary = "Close AI Settings and return to the Agent chat.",
+            detail = """
+                <p>Closes this dialog. Every setting here is saved as you change
+                it, so there is nothing to confirm — the Agent picks up the new
+                backend and model as soon as you return.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
         PluginTooltipEntry(
             tag = TOOLTIP_TAG_SETTINGS_BACKEND,
             summary = "Choose which model powers the Agent: on-device Local (llama.cpp) or cloud Gemini.",
@@ -166,14 +301,68 @@ class AiAssistantPlugin : IPlugin, UIExtension, DocumentationExtension {
                 PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
             )
         ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_SETTINGS_LOCAL_SHA,
+            summary = "Optional SHA-256 of your .gguf file, checked when the model is loaded.",
+            detail = """
+                <p>Paste the expected SHA-256 hash of the model file. It is stored
+                with the model path and compared on load, so a truncated download
+                or a swapped file is reported instead of failing deep inside
+                llama.cpp.</p>
+                <p>Leave it empty to skip the check. The value is saved when the
+                field loses focus.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_SETTINGS_SIMPLE_PROMPT,
+            summary = "Send small local models a plainer prompt with no tool instructions.",
+            detail = """
+                <p>Small on-device models (roughly 1B parameters and under) tend to
+                ramble or echo the prompt when handed the full tool-calling system
+                prompt. With this on they get a short, plain instruction instead.</p>
+                <p>The trade-off: the model won't emit tool calls, so it answers
+                questions but won't edit your project. The direct
+                <i>open/read/list/search</i> commands still work either way. Turn
+                it off for a larger instruct model.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
+        PluginTooltipEntry(
+            tag = TOOLTIP_TAG_SETTINGS_GEMINI_MODEL,
+            summary = "Pick which Gemini model to call; Refresh lists the ones your key can access.",
+            detail = """
+                <p><b>Refresh Models</b> asks Google which models your API key can
+                actually use and fills the list from the response. Until then the
+                list shows a small built-in set of known-good defaults.</p>
+                <p>Selecting a model saves it immediately. If a previously saved
+                model has since been retired, refreshing moves you to the first
+                model in the live list rather than leaving a name that returns
+                404.</p>
+            """.trimIndent(),
+            buttons = listOf(
+                PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
+            )
+        ),
         PluginTooltipEntry(
             tag = TOOLTIP_TAG_SETTINGS_GEMINI_KEY,
             summary = "Enter your Google Gemini API key. It is stored only on this device.",
             detail = """
                 <p>Paste a Gemini API key to enable the cloud backend. The key is
-                kept in this plugin's private preferences on-device and is sent
-                only to Google's API over HTTPS. Requests (your prompts and
-                project context) leave the device when Gemini is selected.</p>
+                encrypted with a key held in this device's hardware-backed Android
+                Keystore before it is written to this plugin's private preferences,
+                and is sent only to Google's API over HTTPS. Requests (your prompts
+                and project context) leave the device when Gemini is selected.</p>
+                <p>Use the eye button to check what you typed, <b>Save</b> to store
+                it, <b>Edit</b> to change it later and <b>Clear</b> to remove it
+                from the device.</p>
+                <p>If the Keystore entry is ever lost — clearing the app's data,
+                for instance — the stored key can no longer be decrypted and must
+                be re-entered here.</p>
             """.trimIndent(),
             buttons = listOf(
                 PluginTooltipButton(description = "AI Assistant guide", uri = "index.html", order = 0)
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
index fd94569e..384220d5 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
@@ -16,6 +16,7 @@ import android.widget.Toast
 import androidx.recyclerview.widget.DiffUtil
 import androidx.recyclerview.widget.ListAdapter
 import androidx.recyclerview.widget.RecyclerView
+import com.itsaky.androidide.plugins.aiassistant.AiAssistantPlugin
 import com.itsaky.androidide.plugins.aiassistant.R
 import com.itsaky.androidide.plugins.aiassistant.models.ChatMessage
 import com.itsaky.androidide.plugins.aiassistant.models.MessageStatus
@@ -26,8 +27,14 @@ import java.text.SimpleDateFormat
 import java.util.Date
 import java.util.Locale
 
+/**
+ * @param wireTooltip attaches this plugin's long-press help for a tag to a view. Supplied by
+ *   ChatFragment, which owns the [com.itsaky.androidide.plugins.services.IdeTooltipService]
+ *   lookup, so the adapter stays free of service plumbing. Defaults to a no-op for tests.
+ */
 class ChatAdapter(
     private val markwon: Markwon,
+    private val wireTooltip: (View, String) -> Unit = { _, _ -> },
     private val onMessageAction: (action: String, message: ChatMessage) -> Unit
 ) : ListAdapter<ChatMessage, RecyclerView.ViewHolder>(DiffCallback) {
 
@@ -207,11 +214,15 @@ class ChatAdapter(
                     holder.btnRetry.setOnClickListener {
                         onMessageAction(ACTION_OPEN_SETTINGS, message)
                     }
+                    // Re-wired per bind: the same recycled button plays both roles, so the
+                    // tag has to follow the role it currently has.
+                    wireTooltip(holder.btnRetry, AiAssistantPlugin.TOOLTIP_TAG_MESSAGE_OPEN_SETTINGS)
                 } else {
                     holder.btnRetry.text = "Retry"
                     holder.btnRetry.setOnClickListener {
                         onMessageAction(ACTION_RETRY, message)
                     }
+                    wireTooltip(holder.btnRetry, AiAssistantPlugin.TOOLTIP_TAG_MESSAGE_RETRY)
                 }
                 updateMessageMetadata(holder, message)
             }
@@ -231,6 +242,7 @@ class ChatAdapter(
                 notifyItemChanged(pos)
             }
         }
+        wireTooltip(holder.messageHeader, AiAssistantPlugin.TOOLTIP_TAG_SYSTEM_LOG)
     }
 
     private fun updateSystemMessageExpansion(holder: SystemMessageViewHolder, message: ChatMessage) {
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
index 8c0686a4..4aaf09b1 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
@@ -10,10 +10,12 @@ import android.text.method.PasswordTransformationMethod
 import android.view.LayoutInflater
 import android.view.View
 import android.view.ViewGroup
+import android.view.WindowManager
 import android.widget.*
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.fragment.app.DialogFragment
 import androidx.lifecycle.ViewModelProvider
+import androidx.lifecycle.lifecycleScope
 import com.itsaky.androidide.plugins.PluginContext
 import com.itsaky.androidide.plugins.aiassistant.AiAssistantPlugin
 import com.itsaky.androidide.plugins.aiassistant.R
@@ -23,6 +25,7 @@ import com.itsaky.androidide.plugins.aiassistant.viewmodel.AiBackend
 import com.itsaky.androidide.plugins.aiassistant.viewmodel.AiSettingsViewModel
 import com.itsaky.androidide.plugins.aiassistant.viewmodel.EngineState
 import com.itsaky.androidide.plugins.aiassistant.viewmodel.ModelLoadingState
+import kotlinx.coroutines.launch
 import java.text.SimpleDateFormat
 import java.util.Date
 import java.util.Locale
@@ -54,6 +57,8 @@ class AiSettingsFragment : DialogFragment() {
                 ?.get(IdeTooltipService::class.java)
         } catch (e: Exception) {
             // Tooltip help is optional; long-press simply shows nothing when it's unavailable.
+            AiAssistantPlugin.getContext()?.logger
+                ?.warn("AiSettingsFragment: tooltip service unavailable", e)
         }
     }
 
@@ -143,6 +148,7 @@ class AiSettingsFragment : DialogFragment() {
             // Close the dialog
             dismiss()
         }
+        wireTooltip(backButton, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_BACK)
     }
 
     private fun setupBackendSelector() {
@@ -214,6 +220,8 @@ class AiSettingsFragment : DialogFragment() {
                 viewModel.loadModelFromUri(savedPath, requireContext())
             }
         }
+        // Same concept as Browse — choosing which local model to run.
+        wireTooltip(loadSavedButton, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_LOCAL_MODEL)
 
         shaInput?.apply {
             setText(viewModel.getLocalModelSha256().orEmpty())
@@ -223,12 +231,16 @@ class AiSettingsFragment : DialogFragment() {
                 }
             }
         }
+        // On the labelled wrapper, not the field: long-press there is the paste menu.
+        view.findViewById<View>(R.id.local_model_sha_layout)
+            ?.let { wireTooltip(it, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_LOCAL_SHA) }
 
         simplePromptCheckbox?.apply {
             isChecked = viewModel.isUseSimpleLocalPromptEnabled()
             setOnCheckedChangeListener { _, isChecked ->
                 viewModel.setUseSimpleLocalPrompt(isChecked)
             }
+            wireTooltip(this, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_SIMPLE_PROMPT)
         }
 
         // Observe engine state
@@ -298,9 +310,9 @@ class AiSettingsFragment : DialogFragment() {
         val clearButton = view.findViewById<Button>(R.id.btn_clear_api_key)
         val statusTextView = view.findViewById<TextView>(R.id.gemini_api_key_status_text)
 
-        // Offer help on the API-key controls in both the editing and saved states.
-        wireTooltip(apiKeyInput, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_GEMINI_KEY)
-        wireTooltip(editButton, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_GEMINI_KEY)
+        // Not on apiKeyInput: long-press there is the paste menu, and a key is pasted.
+        listOf(toggleVisibilityButton, saveButton, editButton, clearButton, statusTextView)
+            .forEach { wireTooltip(it, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_GEMINI_KEY) }
 
         // Create model selection container
         val modelContainer = createModelSelectionUi(view)
@@ -321,19 +333,14 @@ class AiSettingsFragment : DialogFragment() {
             }
         }
 
-        val savedApiKey = viewModel.getGeminiApiKey()
-        if (savedApiKey.isNullOrBlank()) {
-            updateUiState(isEditing = true)
-            apiKeyInput.setText("")
-        } else {
-            updateUiState(isEditing = false)
-            val timestamp = viewModel.getGeminiApiKeySaveTimestamp()
-            if (timestamp > 0) {
-                val sdf = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault())
-                val savedDate = sdf.format(Date(timestamp))
-                statusTextView.text = getString(R.string.msg_api_key_saved_on, savedDate)
+        viewLifecycleOwner.lifecycleScope.launch {
+            val savedApiKey = viewModel.getGeminiApiKey()
+            val hasKey = !savedApiKey.isNullOrBlank()
+            updateUiState(isEditing = !hasKey)
+            if (hasKey) {
+                statusTextView.text = savedApiKeyStatusText()
             } else {
-                statusTextView.text = getString(R.string.msg_api_key_is_saved)
+                apiKeyInput.setText("")
             }
         }
 
@@ -355,6 +362,7 @@ class AiSettingsFragment : DialogFragment() {
             )
             toggleVisibilityButton.setColorFilter(apiKeyInput.currentHintTextColor)
             apiKeyInput.setSelection(apiKeyInput.text?.length ?: 0)
+            setSecureWindow(isKeyVisible)
         }
 
         applyKeyVisibility()
@@ -370,27 +378,54 @@ class AiSettingsFragment : DialogFragment() {
                 Toast.makeText(requireContext(), getString(R.string.msg_api_key_empty), Toast.LENGTH_SHORT).show()
                 return@setOnClickListener
             }
-            if (!viewModel.saveGeminiApiKey(apiKey)) {
-                Toast.makeText(requireContext(), getString(R.string.msg_api_key_save_failed), Toast.LENGTH_LONG).show()
-                return@setOnClickListener
+            saveButton.isEnabled = false
+            viewLifecycleOwner.lifecycleScope.launch {
+                val saved = try {
+                    viewModel.saveGeminiApiKey(apiKey)
+                } finally {
+                    saveButton.isEnabled = true
+                }
+                if (!saved) {
+                    Toast.makeText(requireContext(), getString(R.string.msg_api_key_save_failed), Toast.LENGTH_LONG).show()
+                    return@launch
+                }
+                Toast.makeText(requireContext(), getString(R.string.msg_api_key_saved), Toast.LENGTH_SHORT).show()
+                updateUiState(isEditing = false)
+                statusTextView.text = savedApiKeyStatusText()
             }
-            Toast.makeText(requireContext(), getString(R.string.msg_api_key_saved), Toast.LENGTH_SHORT).show()
-
-            updateUiState(isEditing = false)
-            val timestamp = viewModel.getGeminiApiKeySaveTimestamp()
-            val sdf = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault())
-            val savedDate = sdf.format(Date(timestamp))
-            statusTextView.text = getString(R.string.msg_api_key_saved_on, savedDate)
         }
 
-        editButton.setOnClickListener {
+        // Reveal the (already-fetched) key in an editable, focused field. Kept separate from
+        // the click handler so the listener does one thing: fetch, then hand off.
+        fun revealEditMode(apiKey: String) {
+            apiKeyInput.setText(apiKey)
+            apiKeyInput.setSelection(apiKey.length)
             updateUiState(isEditing = true)
-            apiKeyInput.setText(viewModel.getGeminiApiKey().orEmpty())
             isKeyVisible = false
             applyKeyVisibility()
             apiKeyInput.requestFocus()
         }
 
+        editButton.setOnClickListener {
+            editButton.isEnabled = false
+            viewLifecycleOwner.lifecycleScope.launch {
+                val apiKey = try {
+                    viewModel.getGeminiApiKey()
+                } finally {
+                    editButton.isEnabled = true
+                }
+                // null = a key IS stored but won't decrypt; an empty box alone looks like data loss.
+                if (apiKey == null) {
+                    Toast.makeText(
+                        requireContext(),
+                        getString(R.string.msg_api_key_unreadable),
+                        Toast.LENGTH_LONG
+                    ).show()
+                }
+                revealEditMode(apiKey.orEmpty())
+            }
+        }
+
         clearButton.setOnClickListener {
             viewModel.clearGeminiApiKey()
             Toast.makeText(requireContext(), getString(R.string.msg_api_key_cleared), Toast.LENGTH_SHORT).show()
@@ -402,6 +437,37 @@ class AiSettingsFragment : DialogFragment() {
         setupGeminiModelSelection(modelContainer)
     }
 
+    /**
+     * Add or clear [WindowManager.LayoutParams.FLAG_SECURE] on this dialog's window.
+     *
+     * Set while the API key is displayed in clear text: without it the key is captured by
+     * screenshots, screen recordings and the recents-screen thumbnail, which would undo the
+     * point of encrypting it at rest. The window may not exist yet on the first call (this runs
+     * from view setup, before onStart), which is safe — the initial state is masked, so there is
+     * no flag to apply until the user actually reveals the key.
+     *
+     * @param secure true to block capture, false to allow it again
+     */
+    private fun setSecureWindow(secure: Boolean) {
+        val window = dialog?.window ?: return
+        if (secure) {
+            window.setFlags(
+                WindowManager.LayoutParams.FLAG_SECURE,
+                WindowManager.LayoutParams.FLAG_SECURE
+            )
+        } else {
+            window.clearFlags(WindowManager.LayoutParams.FLAG_SECURE)
+        }
+    }
+
+    /** Status line for a stored key: dated when the save time is known, generic otherwise. */
+    private fun savedApiKeyStatusText(): String {
+        val timestamp = viewModel.getGeminiApiKeySaveTimestamp()
+        if (timestamp <= 0) return getString(R.string.msg_api_key_is_saved)
+        val savedDate = SimpleDateFormat("MMMM d, yyyy", Locale.getDefault()).format(Date(timestamp))
+        return getString(R.string.msg_api_key_saved_on, savedDate)
+    }
+
     private fun createModelSelectionUi(parent: View): LinearLayout {
         val context = requireContext()
         val container = LinearLayout(context).apply {
@@ -460,6 +526,9 @@ class AiSettingsFragment : DialogFragment() {
 
         if (modelSpinner == null || refreshButton == null) return
 
+        wireTooltip(modelSpinner, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_GEMINI_MODEL)
+        wireTooltip(refreshButton, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_GEMINI_MODEL)
+
         // Track real user taps so programmatic selection changes never persist a model.
         var userTouchedSpinner = false
 
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
index 881c8a69..9dc94021 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/ChatFragment.kt
@@ -13,13 +13,17 @@ import androidx.lifecycle.lifecycleScope
 import androidx.lifecycle.repeatOnLifecycle
 import androidx.recyclerview.widget.LinearLayoutManager
 import com.google.android.material.chip.Chip
+import com.google.android.material.snackbar.Snackbar
 import com.itsaky.androidide.plugins.PluginContext
+import com.itsaky.androidide.plugins.aiassistant.AiAssistantPlugin
+import com.itsaky.androidide.plugins.aiassistant.R
 import com.itsaky.androidide.plugins.aiassistant.adapters.ChatAdapter
-import com.itsaky.androidide.plugins.aiassistant.tool.handlers.PathGuard
 import com.itsaky.androidide.plugins.aiassistant.databinding.FragmentChatBinding
 import com.itsaky.androidide.plugins.aiassistant.models.AgentState
 import com.itsaky.androidide.plugins.aiassistant.viewmodel.ChatViewModel
+import com.itsaky.androidide.plugins.base.PluginFragmentHelper
 import com.itsaky.androidide.plugins.services.IdeProjectService
+import com.itsaky.androidide.plugins.services.IdeTooltipService
 import io.noties.markwon.Markwon
 import kotlinx.coroutines.launch
 import java.io.File
@@ -37,6 +41,26 @@ class ChatFragment : Fragment() {
     private lateinit var markwon: Markwon
     private val contextFiles = mutableListOf<File>()
 
+    private val tooltipService: IdeTooltipService? by lazy {
+        try {
+            PluginFragmentHelper.getServiceRegistry(AiAssistantPlugin.PLUGIN_ID)
+                ?.get(IdeTooltipService::class.java)
+        } catch (e: Exception) {
+            AiAssistantPlugin.getContext()?.logger
+                ?.warn("ChatFragment: tooltip service unavailable; long-press help disabled", e)
+            null
+        }
+    }
+
+    /** Shows this plugin's tooltip for [tag] when [view] is long-pressed (Tier 1/2 + guide). */
+    private fun wireTooltip(view: View, tag: String) {
+        view.setOnLongClickListener { anchor ->
+            val service = tooltipService ?: return@setOnLongClickListener false
+            service.showTooltip(anchor, AiAssistantPlugin.TOOLTIP_CATEGORY, tag)
+            true
+        }
+    }
+
     companion object {
         // Test prompt injection (for E2E testing via broadcast receiver)
         @Volatile
@@ -179,7 +203,7 @@ class ChatFragment : Fragment() {
     private fun setupRecyclerView() {
         // The adapter inflates item views from parent.context (the RecyclerView's theme-aware
         // Context), so it no longer needs a Context passed in.
-        chatAdapter = ChatAdapter(markwon) { action, message ->
+        chatAdapter = ChatAdapter(markwon, ::wireTooltip) { action, message ->
             onMessageAction(action, message)
         }
         binding.chatRecyclerView.apply {
@@ -212,6 +236,7 @@ class ChatFragment : Fragment() {
             }
             popup.show()
         }
+        wireTooltip(binding.btnOverflowMenu, AiAssistantPlugin.TOOLTIP_TAG_CHAT_MENU)
     }
 
     private fun setupInputArea() {
@@ -239,6 +264,12 @@ class ChatFragment : Fragment() {
         binding.btnAddContext.setOnClickListener {
             showFilePicker()
         }
+
+        // Anchored on the bar, not promptInputEdittext: long-press there is the paste menu.
+        wireTooltip(binding.btnAddContext, AiAssistantPlugin.TOOLTIP_TAG_CONTEXT_FILES)
+        wireTooltip(binding.inputBarCard, AiAssistantPlugin.TOOLTIP_TAG_CHAT_INPUT)
+        wireTooltip(binding.sendButton, AiAssistantPlugin.TOOLTIP_TAG_CHAT_SEND)
+        wireTooltip(binding.backendStatusText, AiAssistantPlugin.TOOLTIP_TAG_SETTINGS_BACKEND)
     }
 
     private fun setupStatusBar() {
@@ -337,15 +368,19 @@ class ChatFragment : Fragment() {
     }
 
     /**
-     * Opens the file picker rooted at the open project. The host's
-     * [IdeProjectService] is the source of truth for the project root; the
-     * `System.getProperty` chain in [PathGuard] resolves to "/" at runtime (the
-     * IDE process cwd), which lists nothing, so it is only a last-resort fallback.
+     * Opens the file picker rooted at the open project. The host's [IdeProjectService] is the
+     * only source of truth for that root — PathGuard's `System.getProperty` fallback resolves
+     * to "/" in the IDE process, which would root the picker at the device filesystem instead
+     * of the project. With no project open there is nothing to confine the picker to, so this
+     * fails closed and says so rather than opening an unconfined browser.
      */
     private fun showFilePicker() {
         val projectService = getPluginContext()?.services?.get(IdeProjectService::class.java)
         val startPath = projectService?.getCurrentProject()?.rootDir?.absolutePath
-            ?: PathGuard.projectRoot()
+        if (startPath.isNullOrBlank()) {
+            showInfoSnackbar(getString(R.string.file_picker_error_no_project))
+            return
+        }
 
         val dialog = FilePickerDialogFragment.newInstance(startPath) { files ->
             addContextFiles(files)
@@ -413,12 +448,17 @@ class ChatFragment : Fragment() {
      */
     private fun showErrorSnackbar(message: String) {
         val binding = _binding ?: return
-        com.google.android.material.snackbar.Snackbar
-            .make(binding.root, message, com.google.android.material.snackbar.Snackbar.LENGTH_LONG)
+        Snackbar
+            .make(binding.root, message, Snackbar.LENGTH_LONG)
             .setAction("Settings") { openSettingsFragment() }
             .show()
     }
 
+    private fun showInfoSnackbar(message: String) {
+        val binding = _binding ?: return
+        Snackbar.make(binding.root, message, Snackbar.LENGTH_LONG).show()
+    }
+
 }
 
 /**
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
index cba1cfbb..475fb366 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/FilePickerDialogFragment.kt
@@ -16,8 +16,10 @@ import androidx.core.view.isVisible
 import androidx.fragment.app.DialogFragment
 import androidx.lifecycle.lifecycleScope
 import com.google.android.material.dialog.MaterialAlertDialogBuilder
+import com.itsaky.androidide.plugins.aiassistant.AiAssistantPlugin
 import com.itsaky.androidide.plugins.aiassistant.R
-import com.itsaky.androidide.plugins.aiassistant.tool.handlers.PathGuard
+import com.itsaky.androidide.plugins.base.PluginFragmentHelper
+import com.itsaky.androidide.plugins.services.IdeTooltipService
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
@@ -32,9 +34,11 @@ import java.io.File
  * `requireContext()` throws `IllegalStateException: not attached to a context`
  * (previously crashed on the second "Toggle All").
  *
- * Navigation is confined to the start path supplied by the caller (the open
- * project root), so the picker can't be used to reach arbitrary files on the
- * device. All disk I/O runs off the main thread; see [computeListing].
+ * Navigation is confined to [startPath] — the open project root, which the
+ * caller must supply — so the picker can't be used to reach arbitrary files on
+ * the device. There is deliberately no fallback root: an unresolvable path
+ * shows the not-found message rather than defaulting to somewhere broader.
+ * All disk I/O runs off the main thread; see [computeListing].
  */
 class FilePickerDialogFragment : DialogFragment() {
 
@@ -43,31 +47,58 @@ class FilePickerDialogFragment : DialogFragment() {
 
     /** Root the picker is confined to; navigation can never go above this. */
     private lateinit var rootDirectory: File
-    private lateinit var currentDirectory: File
 
     // Reused across in-place refreshes so we never rebuild the Dialog/Fragment.
     private val rows = mutableListOf<FileRow>()
     private lateinit var listAdapter: FileRowAdapter
     private var alertDialog: AlertDialog? = null
+    private var tooltipService: IdeTooltipService? = null
 
     companion object {
         private const val ARG_START_PATH = "start_path"
         private const val PARENT_NAME = ".."
 
+        /**
+         * @param startPath the project root to browse; navigation is confined to it.
+         */
         fun newInstance(
-            startPath: String? = null,
+            startPath: String,
             onSelected: (List<File>) -> Unit
         ): FilePickerDialogFragment {
             return FilePickerDialogFragment().apply {
-                // Default to the current project root when no path is given.
-                arguments = Bundle().apply {
-                    putString(ARG_START_PATH, startPath ?: PathGuard.projectRoot())
-                }
+                arguments = Bundle().apply { putString(ARG_START_PATH, startPath) }
                 onFilesSelected = onSelected
             }
         }
     }
 
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        try {
+            tooltipService = PluginFragmentHelper.getServiceRegistry(AiAssistantPlugin.PLUGIN_ID)
+                ?.get(IdeTooltipService::class.java)
+        } catch (e: Exception) {
+            // Tooltip help is optional; long-press simply shows nothing when it's unavailable.
+            AiAssistantPlugin.getContext()?.logger
+                ?.warn("FilePickerDialogFragment: tooltip service unavailable", e)
+        }
+    }
+
+    /** Shows this plugin's context-files tooltip when [view] is long-pressed (Tier 1/2 + guide). */
+    private fun wireTooltip(view: View) {
+        view.setOnLongClickListener { anchor -> showTooltip(anchor) }
+    }
+
+    private fun showTooltip(anchor: View): Boolean {
+        val service = tooltipService ?: return false
+        service.showTooltip(
+            anchor,
+            AiAssistantPlugin.TOOLTIP_CATEGORY,
+            AiAssistantPlugin.TOOLTIP_TAG_CONTEXT_FILES
+        )
+        return true
+    }
+
     /** One navigable entry: a directory to descend into or a selectable file. */
     private data class FileRow(
         val file: File,
@@ -84,6 +115,7 @@ class FilePickerDialogFragment : DialogFragment() {
         val listView = ListView(context).apply {
             adapter = listAdapter
             setOnItemClickListener { _, _, position, _ -> onItemClicked(position) }
+            setOnItemLongClickListener { _, itemView, _, _ -> showTooltip(itemView) }
         }
 
         val dialog = MaterialAlertDialogBuilder(context)
@@ -101,6 +133,11 @@ class FilePickerDialogFragment : DialogFragment() {
             dialog.getButton(AlertDialog.BUTTON_NEUTRAL)?.setOnClickListener {
                 toggleAllInCurrentDirectory()
             }
+            listOf(
+                AlertDialog.BUTTON_POSITIVE,
+                AlertDialog.BUTTON_NEGATIVE,
+                AlertDialog.BUTTON_NEUTRAL
+            ).mapNotNull { dialog.getButton(it) }.forEach(::wireTooltip)
         }
         alertDialog = dialog
         loadInitial()
@@ -111,18 +148,20 @@ class FilePickerDialogFragment : DialogFragment() {
      * Resolve the confined root from the start path and load its listing.
      * The start path passed by the caller IS the confinement root — the picker
      * confines navigation to the open project and starts there.
+     *
+     * Fails closed: a missing, blank, or non-directory path leaves [rootDirectory]
+     * unset and shows the not-found message, so the picker can never silently widen
+     * to a broader root (`/` in particular) when the project can't be resolved.
      */
     private fun loadInitial() {
-        val rootPath = arguments?.getString(ARG_START_PATH) ?: PathGuard.projectRoot()
+        val rootPath = arguments?.getString(ARG_START_PATH)
         lifecycleScope.launch {
             val listing = withContext(Dispatchers.IO) {
-                rootDirectory = File(rootPath).canonicalOrAbsolute()
-                if (!rootDirectory.exists()) {
-                    null
-                } else {
-                    currentDirectory = rootDirectory
-                    computeListing(rootDirectory)
-                }
+                if (rootPath.isNullOrBlank()) return@withContext null
+                val root = File(rootPath).canonicalOrAbsolute()
+                if (!root.isDirectory) return@withContext null
+                rootDirectory = root
+                computeListing(root)
             }
             if (listing == null) {
                 alertDialog?.setTitle(getString(R.string.file_picker_error_not_found))
@@ -135,10 +174,7 @@ class FilePickerDialogFragment : DialogFragment() {
     /** Recompute the listing for [directory] off-thread and apply it in place. */
     private fun populate(directory: File) {
         lifecycleScope.launch {
-            val listing = withContext(Dispatchers.IO) {
-                currentDirectory = directory
-                computeListing(directory)
-            }
+            val listing = withContext(Dispatchers.IO) { computeListing(directory) }
             applyListing(listing)
         }
     }
@@ -156,6 +192,7 @@ class FilePickerDialogFragment : DialogFragment() {
         }
 
         directory.listFiles()
+            ?.filter { isWithinRoot(it) }
             ?.sortedWith(compareBy<File> { !it.isDirectory }.thenBy { it.name.lowercase() })
             ?.forEach { file -> newRows.add(FileRow(file, file.name, file.isDirectory)) }
 
@@ -194,10 +231,12 @@ class FilePickerDialogFragment : DialogFragment() {
     private fun titleFor(dir: File): String =
         getString(R.string.file_picker_title_current, dir.name)
 
-    private fun isWithinRoot(dir: File): Boolean {
-        val root = canonical(rootDirectory)
-        val path = canonical(dir)
-        return path == root || path.startsWith(root + File.separator)
+    /** True if [file] resolves (symlinks included) to a path at or below [rootDirectory]. */
+    private fun isWithinRoot(file: File): Boolean = try {
+        val root = rootDirectory.canonicalFile.toPath().normalize()
+        file.canonicalFile.toPath().normalize().startsWith(root)
+    } catch (e: Exception) {
+        false
     }
 
     private fun canonical(f: File): String =
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
index fe42be23..21b42928 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
@@ -1,5 +1,6 @@
 package com.itsaky.androidide.plugins.aiassistant.security
 
+import android.content.SharedPreferences
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
@@ -72,11 +73,12 @@ object SecureApiKeyStore {
     /**
      * Encrypt [plain] into a self-describing string: [ENC_PREFIX] + base64(iv | ciphertext).
      *
-     * If the Keystore key has been permanently invalidated (e.g. the lock-screen credentials
-     * changed, or the entry is corrupt) the stale alias is dropped and a fresh key generated
-     * once before retrying. Any other Keystore/cipher failure is surfaced as a
-     * [GeneralSecurityException] so the caller can inform the user instead of crashing — the
-     * previous version let these propagate uncaught and take the IDE down on Save.
+     * The key is not auth-bound, so a credential change does not invalidate it; an alias an
+     * OEM Keystore drops anyway is regenerated once before retrying.
+     *
+     * @param plain the value to encrypt
+     * @throws GeneralSecurityException on any other Keystore/cipher failure, so the caller can
+     *   inform the user instead of crashing the IDE on Save
      */
     @Throws(GeneralSecurityException::class)
     fun encrypt(plain: String): String {
@@ -92,7 +94,7 @@ object SecureApiKeyStore {
     /**
      * Return the plaintext for a stored value, handling both formats transparently:
      * an [ENC_PREFIX] value is decrypted; anything else is returned unchanged as
-     * legacy plaintext (it gets migrated to ciphertext on the next save). Returns
+     * legacy plaintext (use [readAndMigrate] to upgrade it in place). Returns
      * null if a ciphertext value can't be decrypted — e.g. the Keystore key was
      * lost or invalidated — in which case the user must re-enter the key.
      */
@@ -111,4 +113,29 @@ object SecureApiKeyStore {
             null
         }
     }
+
+    /**
+     * Read [key] from [prefs], upgrading a legacy plaintext value to ciphertext in place.
+     *
+     * Keys written before this store existed are still plaintext on disk, and [decrypt] alone
+     * hands them back unchanged forever — so an install that configured its key earlier would
+     * never actually gain encryption. Re-encrypting on the first read closes that gap without
+     * making the user re-enter the key.
+     *
+     * Keystore IPC + AES/GCM, so call this off the main thread.
+     *
+     * @return the plaintext value, or null when nothing is stored or decryption failed.
+     */
+    fun readAndMigrate(prefs: SharedPreferences?, key: String): String? {
+        val stored = prefs?.getString(key, null) ?: return null
+        if (stored.startsWith(ENC_PREFIX)) return decrypt(stored)
+        if (stored.isBlank()) return stored
+        try {
+            prefs.edit().putString(key, encrypt(stored)).apply()
+            Log.i(TAG, "Upgraded legacy plaintext value for '$key' to ciphertext")
+        } catch (e: Exception) {
+            Log.w(TAG, "Could not upgrade legacy plaintext value for '$key' to ciphertext", e)
+        }
+        return stored
+    }
 }
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
index 22ea0c41..96d50ed0 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
@@ -8,8 +8,11 @@ import androidx.lifecycle.viewModelScope
 import com.itsaky.androidide.plugins.aiassistant.security.SecureApiKeyStore
 import com.itsaky.androidide.plugins.services.LlmInferenceService
 import com.itsaky.androidide.plugins.services.SharedServices
+import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import com.itsaky.androidide.plugins.PluginContext
 
 /**
  * State for the model file loading.
@@ -49,7 +52,8 @@ enum class AiBackend(val displayName: String) {
 data class GeminiModelOptions(val models: List<String>, val isLive: Boolean)
 
 class AiSettingsViewModel(
-    private val getContext: () -> com.itsaky.androidide.plugins.PluginContext?
+    private val getContext: () -> PluginContext?,
+    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
 ) : ViewModel() {
 
     companion object {
@@ -189,33 +193,39 @@ class AiSettingsViewModel(
     }
 
     /**
-     * Persists the Gemini API key in this plugin's private SharedPreferences,
-     * encrypted at rest with a hardware-backed Android Keystore secret (see
-     * [SecureApiKeyStore]). Only ciphertext is written, so the prefs file alone
-     * (root, `adb backup`, forensic dump) does not disclose the key. Use
-     * [clearGeminiApiKey] to remove it.
+     * Encrypts [apiKey] via [SecureApiKeyStore] and persists only the ciphertext to private
+     * prefs, off the main thread (Keystore IPC + AES/GCM). Nothing is written on failure.
      *
-     * Returns false (persisting nothing) if encryption fails — e.g. a hardware Keystore
-     * fault the automatic key-regeneration retry couldn't recover — so the caller can warn
-     * the user instead of the whole IDE crashing on Save.
+     * @param apiKey the plaintext key to store (trimmed before encryption)
+     * @return true only if the key was both encrypted and persisted
      */
-    fun saveGeminiApiKey(apiKey: String): Boolean {
+    suspend fun saveGeminiApiKey(apiKey: String): Boolean = withContext(ioDispatcher) {
+        // Checked first: returning true here would have the UI claim an unwritten key was saved.
+        val prefs = getPluginPrefs()
+        if (prefs == null) {
+            android.util.Log.e(TAG, "Cannot save Gemini API key: plugin preferences unavailable")
+            return@withContext false
+        }
         val encrypted = try {
             SecureApiKeyStore.encrypt(apiKey.trim())
         } catch (e: Exception) {
             android.util.Log.e(TAG, "Failed to encrypt Gemini API key", e)
-            return false
-        }
-        getPluginPrefs()?.edit()?.apply {
-            putString("gemini_api_key", encrypted)
-            putLong("gemini_api_key_timestamp", System.currentTimeMillis())
-            apply()
+            return@withContext false
         }
-        return true
+        prefs.edit()
+            .putString("gemini_api_key", encrypted)
+            .putLong("gemini_api_key_timestamp", System.currentTimeMillis())
+            .apply()
+        true
     }
 
-    fun getGeminiApiKey(): String? {
-        return SecureApiKeyStore.decrypt(getPluginPrefs()?.getString("gemini_api_key", null))
+    /**
+     * Decrypt the stored key off the main thread (Keystore IPC + AES/GCM), upgrading a
+     * pre-encryption plaintext key to ciphertext in passing so existing installs actually
+     * end up encrypted rather than waiting for the user to re-enter the key.
+     */
+    suspend fun getGeminiApiKey(): String? = withContext(ioDispatcher) {
+        SecureApiKeyStore.readAndMigrate(getPluginPrefs(), "gemini_api_key")
     }
 
     fun getGeminiApiKeySaveTimestamp(): Long {
@@ -273,16 +283,7 @@ class AiSettingsViewModel(
                     return@launch
                 }
 
-                // listModels() lives in the ai-core plugin and isn't part of the shared
-                // LlmBackend interface, so reach it reflectively across the plugin
-                // classloader boundary. It reads the saved key itself and returns the live
-                // v1beta catalog (empty when unavailable).
-                val method = geminiBackend.javaClass.getMethod("listModels")
-                val futureResult = method.invoke(geminiBackend)
-
-                @Suppress("UNCHECKED_CAST")
-                val models: List<String> =
-                    (futureResult as? java.util.concurrent.CompletableFuture<List<String>>)?.get().orEmpty()
+                val models = listModelsViaBackend(geminiBackend)
                 if (models.isEmpty()) {
                     android.util.Log.w(TAG, "Live model list empty; showing fallback models")
                     _geminiModels.postValue(GeminiModelOptions(FALLBACK_MODELS, isLive = false))
@@ -299,6 +300,42 @@ class AiSettingsViewModel(
         }
     }
 
+    /**
+     * Ask ai-core's Gemini backend for its live model catalog.
+     *
+     * `listModels()` isn't on the shared [LlmInferenceService.LlmBackend] interface, so reflection
+     * is the only way across the plugin classloader boundary — an unchecked contract, hence the
+     * loud log when it breaks rather than a silent fall back to [FALLBACK_MODELS].
+     *
+     * @param backend the resolved "gemini" backend instance from [SharedServices]
+     * @return the live catalog, or an empty list when unavailable
+     */
+    private fun listModelsViaBackend(backend: Any): List<String> {
+        val method = try {
+            backend.javaClass.getMethod("listModels")
+        } catch (e: NoSuchMethodException) {
+            android.util.Log.e(
+                TAG,
+                "ai-core's ${backend.javaClass.name} has no listModels(): the cross-plugin " +
+                    "contract changed. Expected `fun listModels(): CompletableFuture<List<String>>`.",
+                e
+            )
+            return emptyList()
+        }
+        val result = method.invoke(backend)
+
+        @Suppress("UNCHECKED_CAST")
+        val future = result as? java.util.concurrent.CompletableFuture<List<String>>
+        if (future == null) {
+            android.util.Log.e(
+                TAG,
+                "listModels() returned ${result?.javaClass?.name}, expected CompletableFuture"
+            )
+            return emptyList()
+        }
+        return future.get().orEmpty()
+    }
+
     /**
      * Load a model from URI.
      * In the plugin context, we just save the path - the actual loading
diff --git a/ai-assistant/src/main/res/values/strings.xml b/ai-assistant/src/main/res/values/strings.xml
index c199a12a..a669d8c3 100644
--- a/ai-assistant/src/main/res/values/strings.xml
+++ b/ai-assistant/src/main/res/values/strings.xml
@@ -101,6 +101,7 @@
     <string name="msg_api_key_empty">API Key cannot be empty</string>
     <string name="msg_api_key_cleared">API Key cleared</string>
     <string name="msg_api_key_save_failed">Couldn\'t save the API key on this device. Please try again.</string>
+    <string name="msg_api_key_unreadable">The stored API key could not be read on this device. Please enter it again.</string>
     <string name="settings_backend">Backend</string>
     <string name="settings_model">Model</string>
     <string name="settings_temperature">Temperature</string>
@@ -120,5 +121,6 @@
     <string name="file_picker_title_current">Select Files: %s</string>
     <string name="file_picker_add_selected">Add Selected</string>
     <string name="file_picker_toggle_all">Toggle All</string>
+    <string name="file_picker_error_no_project">Open a project first — context files are picked from the project you have open.</string>
     <string name="file_picker_error_not_found">Project directory not found</string>
 </resources>
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
index a15ec634..d0f15016 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
@@ -1,5 +1,7 @@
 package com.itsaky.androidide.plugins.aicore
 
+import android.content.SharedPreferences
+import android.os.Looper
 import com.itsaky.androidide.plugins.PluginContext
 import com.itsaky.androidide.plugins.services.LlmInferenceService
 import com.itsaky.androidide.plugins.services.LlmInferenceService.*
@@ -10,6 +12,7 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlin.coroutines.coroutineContext
 import org.json.JSONArray
@@ -35,10 +38,21 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
     @Volatile
     private var currentJob: Job? = null
 
+    /**
+     * Last decryption, as (value on disk -> plaintext). Decrypting costs a Keystore IPC round
+     * trip and [isAvailable] runs on every generate, so caching against the raw stored value
+     * pays that cost once and re-decrypts only when the stored key actually changes.
+     */
+    @Volatile
+    private var keyCache: Pair<String, String?>? = null
+
     companion object {
         /** Current default model. gemini-1.5-* is retired on v1beta and now 404s. */
         const val DEFAULT_MODEL = "gemini-2.5-flash"
 
+        /** Pref key holding the (encrypted) Gemini API key, written by ai-assistant. */
+        private const val KEY_API_KEY = "gemini_api_key"
+
         /** Base URL for the v1beta models API (ListModels, generateContent, streaming). */
         private const val MODELS_BASE_URL =
             "https://generativelanguage.googleapis.com/v1beta/models"
@@ -50,31 +64,61 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
         private const val METHOD_STREAM_GENERATE_CONTENT = "streamGenerateContent"
     }
 
+    /** ai-assistant's shared prefs, where the Gemini settings live, or null if unreachable. */
+    private fun agentPrefs(): SharedPreferences? = try {
+        SharedServices.get(PluginContext::class.java)
+            ?.getPluginSharedPreferences("AgentSettings")
+    } catch (e: Exception) {
+        context.logger.error("GeminiBackend: Error getting preferences", e)
+        null
+    }
+
     /**
      * Get the model name from preferences, or use the current default.
      */
-    private fun getModelName(): String {
-        val prefs = try {
-            val aiAssistantContext = SharedServices.get(PluginContext::class.java)
-            aiAssistantContext?.getPluginSharedPreferences("AgentSettings")
-        } catch (e: Exception) {
-            context.logger.error("GeminiBackend: Error getting preferences", e)
-            null
-        }
-        return prefs?.getString("gemini_model", DEFAULT_MODEL) ?: DEFAULT_MODEL
-    }
+    private fun getModelName(): String =
+        agentPrefs()?.getString("gemini_model", DEFAULT_MODEL) ?: DEFAULT_MODEL
 
-    /** Read the saved Gemini API key from ai-assistant's shared prefs, or null. */
+    /**
+     * Read the saved Gemini API key from ai-assistant's shared prefs, or null.
+     *
+     * Decryption is Keystore IPC + AES/GCM and must not run on the main thread. Every caller
+     * today reaches this from [Dispatchers.IO], but [LlmBackend.isAvailable] is a synchronous
+     * interface method a future caller could invoke from the UI thread — so instead of relying
+     * on that, a main-thread call answers from the cache and kicks off a background refresh
+     * rather than blocking. Worst case it reports "no key" once and is correct thereafter.
+     */
     private fun readGeminiApiKey(): String? {
-        val prefs = try {
-            SharedServices.get(PluginContext::class.java)
-                ?.getPluginSharedPreferences("AgentSettings")
-        } catch (e: Exception) {
-            context.logger.error("GeminiBackend: Error getting preferences", e)
-            null
+        val stored = agentPrefs()?.getString(KEY_API_KEY, null)
+        if (stored.isNullOrBlank()) {
+            keyCache = null
+            return null
         }
-        val stored = prefs?.getString("gemini_api_key", null)
-        return SecureApiKeyStore.decrypt(stored)?.trim()?.takeIf { it.isNotBlank() }
+        keyCache?.let { (raw, plain) -> if (raw == stored) return plain }
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            context.logger.warn("GeminiBackend: API key read on the main thread; refreshing off-thread")
+            // close() cancels scope, so without this guard the launch is a silent no-op.
+            if (scope.isActive) {
+                scope.launch { refreshKeyCache() }
+            } else {
+                context.logger.warn("GeminiBackend: backend already closed; not refreshing key cache")
+            }
+            return null
+        }
+        return refreshKeyCache()
+    }
+
+    /**
+     * Decrypt the stored key — upgrading a pre-encryption plaintext value in passing — and
+     * cache the result. Off-main-thread only; see [readGeminiApiKey].
+     */
+    private fun refreshKeyCache(): String? {
+        val prefs = agentPrefs()
+        val plain = SecureApiKeyStore.readAndMigrate(prefs, KEY_API_KEY)
+            ?.trim()?.takeIf { it.isNotBlank() }
+        val raw = prefs?.getString(KEY_API_KEY, null)
+        keyCache = raw?.let { it to plain }
+        return plain
     }
 
     override fun getId(): String = "gemini"
@@ -394,10 +438,16 @@ User: $userPrompt"""
     /**
      * Release all resources: cancel the backend scope and any in-flight
      * request. Called from AiCorePlugin.dispose().
+     *
+     * [keyCache] holds the *decrypted* API key, so it is dropped here too — otherwise the
+     * plaintext stays reachable on the host process heap for as long as the IDE runs, long
+     * after the plugin was unloaded, which is exactly what encrypting at rest is meant to
+     * prevent.
      */
     fun close() {
         currentJob?.cancel()
         scope.cancel()
+        keyCache = null
     }
 
     /**
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
index 6ce44eb4..30b6a0bd 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
@@ -8,8 +8,11 @@ import com.itsaky.androidide.plugins.services.SharedServices
 import com.itsaky.androidide.plugins.PluginContext
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeoutOrNull
 import java.io.File
 import java.io.FileOutputStream
 import java.util.concurrent.CompletableFuture
@@ -32,6 +35,15 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
     private val llama by lazy { LLamaAndroid.instance() }
     private val scope = CoroutineScope(Dispatchers.IO)
 
+    /**
+     * Separate from [scope] because [close] cancels [scope] and then has to run the unload —
+     * work submitted to a cancelled scope never starts.
+     */
+    private val teardownScope = CoroutineScope(Dispatchers.IO)
+
+    /** The [close] teardown, retained so [awaitClose] can join it. */
+    @Volatile private var teardownJob: Job? = null
+
     @Volatile private var modelLoaded = false
     @Volatile private var currentModelPath: String? = null
 
@@ -392,10 +404,15 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
      * can block while inference is in flight, so it must never run via runBlocking
      * on Main. Cancel generation, then unload on a background thread, then stop
      * the Llm-RunLoop thread so it doesn't outlive the plugin.
+     *
+     * Teardown runs on [teardownScope] rather than a throwaway `CoroutineScope(...)` so the
+     * work has an owner: the returned [Job] is retained in [teardownJob], letting a caller
+     * observe or await it via [awaitClose] instead of dispose() returning while native work is
+     * still in flight with no handle to it.
      */
     fun close() {
         scope.cancel()
-        CoroutineScope(Dispatchers.IO).launch {
+        teardownJob = teardownScope.launch {
             try {
                 unloadModelInternal()
             } catch (e: Exception) {
@@ -408,4 +425,21 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
             }
         }
     }
+
+    /**
+     * Block until the [close] teardown finishes, at most [timeoutMs].
+     *
+     * Intended for tests and for a host that wants unload to have completed before it drops the
+     * plugin's classloader. Never call from the main thread — that is the deadlock [close] exists
+     * to avoid.
+     *
+     * @param timeoutMs how long to wait before giving up
+     * @return true if teardown finished (or never started), false if it was still running
+     */
+    fun awaitClose(timeoutMs: Long = 10_000): Boolean {
+        val job = teardownJob ?: return true
+        return runBlocking {
+            withTimeoutOrNull(timeoutMs) { job.join() } != null
+        }
+    }
 }
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
index 1e31a7fc..c7c75c7d 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
@@ -1,5 +1,6 @@
 package com.itsaky.androidide.plugins.aicore
 
+import android.content.SharedPreferences
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
@@ -72,11 +73,12 @@ object SecureApiKeyStore {
     /**
      * Encrypt [plain] into a self-describing string: [ENC_PREFIX] + base64(iv | ciphertext).
      *
-     * If the Keystore key has been permanently invalidated (e.g. the lock-screen credentials
-     * changed, or the entry is corrupt) the stale alias is dropped and a fresh key generated
-     * once before retrying. Any other Keystore/cipher failure is surfaced as a
-     * [GeneralSecurityException] so the caller can inform the user instead of crashing — the
-     * previous version let these propagate uncaught and take the IDE down on Save.
+     * The key is not auth-bound, so a credential change does not invalidate it; an alias an
+     * OEM Keystore drops anyway is regenerated once before retrying.
+     *
+     * @param plain the value to encrypt
+     * @throws GeneralSecurityException on any other Keystore/cipher failure, so the caller can
+     *   inform the user instead of crashing the IDE on Save
      */
     @Throws(GeneralSecurityException::class)
     fun encrypt(plain: String): String {
@@ -92,7 +94,7 @@ object SecureApiKeyStore {
     /**
      * Return the plaintext for a stored value, handling both formats transparently:
      * an [ENC_PREFIX] value is decrypted; anything else is returned unchanged as
-     * legacy plaintext (it gets migrated to ciphertext on the next save). Returns
+     * legacy plaintext (use [readAndMigrate] to upgrade it in place). Returns
      * null if a ciphertext value can't be decrypted — e.g. the Keystore key was
      * lost or invalidated — in which case the user must re-enter the key.
      */
@@ -111,4 +113,29 @@ object SecureApiKeyStore {
             null
         }
     }
+
+    /**
+     * Read [key] from [prefs], upgrading a legacy plaintext value to ciphertext in place.
+     *
+     * Keys written before this store existed are still plaintext on disk, and [decrypt] alone
+     * hands them back unchanged forever — so an install that configured its key earlier would
+     * never actually gain encryption. Re-encrypting on the first read closes that gap without
+     * making the user re-enter the key.
+     *
+     * Keystore IPC + AES/GCM, so call this off the main thread.
+     *
+     * @return the plaintext value, or null when nothing is stored or decryption failed.
+     */
+    fun readAndMigrate(prefs: SharedPreferences?, key: String): String? {
+        val stored = prefs?.getString(key, null) ?: return null
+        if (stored.startsWith(ENC_PREFIX)) return decrypt(stored)
+        if (stored.isBlank()) return stored
+        try {
+            prefs.edit().putString(key, encrypt(stored)).apply()
+            Log.i(TAG, "Upgraded legacy plaintext value for '$key' to ciphertext")
+        } catch (e: Exception) {
+            Log.w(TAG, "Could not upgrade legacy plaintext value for '$key' to ciphertext", e)
+        }
+        return stored
+    }
 }

From 50908ea2dfbf03c10d3b8899f2b5516bf76cc2d7 Mon Sep 17 00:00:00 2001
From: John Trujillo <johnandrestrujillo@gmail.com>
Date: Wed, 29 Jul 2026 08:54:00 -0500
Subject: [PATCH 3/3] fix: secure Gemini API key at rest and confine the file
 picker

Encrypt the key with AES/GCM under an Android Keystore secret, migrating existing plaintext on first read; send it as a header, never a query string. Confine the context-file picker to the open project, failing closed on an unresolvable root, and fix the crash on a second "Toggle All".
---
 ai-assistant/src/main/AndroidManifest.xml     |  6 +-
 .../aiassistant/adapters/ChatAdapter.kt       | 65 +++++++++++++++----
 .../fragments/AiSettingsFragment.kt           |  8 +++
 .../aiassistant/security/SecureApiKeyStore.kt | 12 ++--
 .../viewmodel/AiSettingsViewModel.kt          | 34 +++++++++-
 ai-core/build.gradle.kts                      | 65 +++++++++++++++++++
 ai-core/src/main/AndroidManifest.xml          |  2 +-
 .../androidide/plugins/aicore/AiCorePlugin.kt |  2 +
 .../plugins/aicore/GeminiBackend.kt           | 21 +++++-
 .../plugins/aicore/LocalLlmBackend.kt         | 15 +++--
 .../plugins/aicore/SecureApiKeyStore.kt       | 12 ++--
 11 files changed, 209 insertions(+), 33 deletions(-)

diff --git a/ai-assistant/src/main/AndroidManifest.xml b/ai-assistant/src/main/AndroidManifest.xml
index 7cdab370..0f0e60ea 100644
--- a/ai-assistant/src/main/AndroidManifest.xml
+++ b/ai-assistant/src/main/AndroidManifest.xml
@@ -33,17 +33,17 @@
 
         <meta-data
             android:name="plugin.max_ide_version"
-            android:value="26.30" />
+            android:value="26.31" />
 
         <!-- Number of editor tabs contributed via getEditorTabs() (the "Agent" tab) -->
         <meta-data
             android:name="plugin.editor_tabs"
             android:value="1" />
 
-        <!-- ide.settings: AiAssistantPlugin's migration reads the host store. No network.access: ai-core makes the Gemini calls. -->
+        <!-- No network.access: ai-core makes the Gemini calls. No ide.settings: prefs reads aren't gated on it and nothing here modifies IDE settings. -->
         <meta-data
             android:name="plugin.permissions"
-            android:value="filesystem.read,filesystem.write,system.commands,project.structure,ide.settings" />
+            android:value="filesystem.read,filesystem.write,system.commands,project.structure" />
 
         <meta-data
             android:name="plugin.main_class"
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
index 384220d5..4aa61e8a 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/adapters/ChatAdapter.kt
@@ -62,6 +62,13 @@ class ChatAdapter(
         val generatingDots: TextView = view.findViewById(R.id.generating_dots)
         val messageDuration: TextView = view.findViewById(R.id.message_duration)
         val btnRetry: Button = view.findViewById(R.id.btn_retry)
+
+        /**
+         * Queued next step of the "..." animation, or null when it isn't running. Retained so
+         * [ChatAdapter.hideGeneratingDots] can cancel it: a Runnable left on the main looper
+         * would keep this holder, its views and their Context reachable after the row is gone.
+         */
+        var generatingDotsStep: Runnable? = null
     }
 
     class SystemMessageViewHolder(view: View) : MessageViewHolder(view) {
@@ -126,7 +133,7 @@ class ChatAdapter(
                     MessageStatus.LOADING -> {
                         holder.loadingIndicator.visibility = View.VISIBLE
                         holder.messageContent.visibility = View.GONE
-                        holder.generatingDots.visibility = View.GONE
+                        hideGeneratingDots(holder)
                     }
                     MessageStatus.SENT -> {
                         holder.loadingIndicator.visibility = View.GONE
@@ -137,19 +144,19 @@ class ChatAdapter(
                         if (message.sender == Sender.AGENT && message.durationMs == null) {
                             animateGeneratingDots(holder)
                         } else {
-                            holder.generatingDots.visibility = View.GONE
+                            hideGeneratingDots(holder)
                         }
                     }
                     MessageStatus.COMPLETED -> {
                         holder.loadingIndicator.visibility = View.GONE
                         holder.messageContent.visibility = View.VISIBLE
-                        holder.generatingDots.visibility = View.GONE
+                        hideGeneratingDots(holder)
                         markwon.setMarkdown(holder.messageContent, payload.text)
                     }
                     MessageStatus.ERROR -> {
                         holder.loadingIndicator.visibility = View.GONE
                         holder.messageContent.visibility = View.VISIBLE
-                        holder.generatingDots.visibility = View.GONE
+                        hideGeneratingDots(holder)
                         holder.messageContent.text = payload.text
                     }
                 }
@@ -180,6 +187,8 @@ class ChatAdapter(
                 holder.messageContent.visibility = View.GONE
                 holder.btnRetry.visibility = View.GONE
                 holder.messageMetadataContainer.visibility = View.GONE
+                // A row that goes back to LOADING after SENT still had a live dots loop.
+                hideGeneratingDots(holder)
             }
             MessageStatus.SENT -> {
                 holder.loadingIndicator.visibility = View.GONE
@@ -192,14 +201,14 @@ class ChatAdapter(
                 if (message.sender == Sender.AGENT && message.durationMs == null) {
                     animateGeneratingDots(holder)
                 } else {
-                    holder.generatingDots.visibility = View.GONE
+                    hideGeneratingDots(holder)
                 }
             }
             MessageStatus.COMPLETED -> {
                 holder.loadingIndicator.visibility = View.GONE
                 holder.messageContent.visibility = View.VISIBLE
                 holder.btnRetry.visibility = View.GONE
-                holder.generatingDots.visibility = View.GONE
+                hideGeneratingDots(holder)
                 markwon.setMarkdown(holder.messageContent, message.text)
                 updateMessageMetadata(holder, message)
             }
@@ -207,7 +216,7 @@ class ChatAdapter(
                 holder.loadingIndicator.visibility = View.GONE
                 holder.messageContent.visibility = View.VISIBLE
                 holder.btnRetry.visibility = View.VISIBLE
-                holder.generatingDots.visibility = View.GONE
+                hideGeneratingDots(holder)
                 holder.messageContent.text = message.text
                 if (message.sender == Sender.SYSTEM) {
                     holder.btnRetry.text = "Open AI Settings"
@@ -258,22 +267,50 @@ class ChatAdapter(
         }
     }
 
+    /**
+     * Starts — or restarts — the "..." animation, cancelling any step already queued for [holder]
+     * so repeated binds of one recycled row cannot stack loops. The step is posted on the dots
+     * view, not a bare main-looper Handler, so [hideGeneratingDots] can cancel it.
+     *
+     * @param holder the row whose dots should animate
+     */
     private fun animateGeneratingDots(holder: DefaultMessageViewHolder) {
+        hideGeneratingDots(holder)
         holder.generatingDots.visibility = View.VISIBLE
         val dotStates = arrayOf(".", "..", "...")
         var currentIndex = 0
 
-        val handler = android.os.Handler(android.os.Looper.getMainLooper())
-        val runnable = object : Runnable {
+        val step = object : Runnable {
             override fun run() {
-                if (holder.generatingDots.visibility == View.VISIBLE) {
-                    holder.generatingDots.text = dotStates[currentIndex]
-                    currentIndex = (currentIndex + 1) % dotStates.size
-                    handler.postDelayed(this, 500)
+                if (holder.generatingDots.visibility != View.VISIBLE) {
+                    holder.generatingDotsStep = null
+                    return
                 }
+                holder.generatingDots.text = dotStates[currentIndex]
+                currentIndex = (currentIndex + 1) % dotStates.size
+                holder.generatingDots.postDelayed(this, 500)
             }
         }
-        handler.post(runnable)
+        holder.generatingDotsStep = step
+        holder.generatingDots.post(step)
+    }
+
+    /**
+     * Hides the dots and cancels the animation. Visibility alone is not enough: the running step
+     * only notices it on its next tick, and never at all once the view is detached.
+     *
+     * @param holder the row whose dots should stop
+     */
+    private fun hideGeneratingDots(holder: DefaultMessageViewHolder) {
+        holder.generatingDotsStep?.let { holder.generatingDots.removeCallbacks(it) }
+        holder.generatingDotsStep = null
+        holder.generatingDots.visibility = View.GONE
+    }
+
+    /** Stops the dots animation of a row leaving the screen, so its step can't outlive the view. */
+    override fun onViewRecycled(holder: RecyclerView.ViewHolder) {
+        super.onViewRecycled(holder)
+        if (holder is DefaultMessageViewHolder) hideGeneratingDots(holder)
     }
 
     private fun createPreview(rawText: String): String {
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
index 4aaf09b1..145deb02 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/fragments/AiSettingsFragment.kt
@@ -341,6 +341,14 @@ class AiSettingsFragment : DialogFragment() {
                 statusTextView.text = savedApiKeyStatusText()
             } else {
                 apiKeyInput.setText("")
+                // A stored-but-undecryptable key also reads as null; warn as the Edit path does.
+                if (viewModel.hasStoredGeminiApiKey()) {
+                    Toast.makeText(
+                        requireContext(),
+                        getString(R.string.msg_api_key_unreadable),
+                        Toast.LENGTH_LONG
+                    ).show()
+                }
             }
         }
 
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
index 21b42928..91bbc0dc 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt
@@ -25,6 +25,7 @@ import javax.crypto.spec.GCMParameterSpec
  * Android Keystore. Keep the two copies in sync.
  */
 object SecureApiKeyStore {
+    // Drift in the constants below fails ai-core's verifySecureApiKeyStoreParity build task.
     private const val TAG = "SecureApiKeyStore"
     private const val KEYSTORE = "AndroidKeyStore"
     private const val ALIAS = "cotg_ai_gemini_key_v1"
@@ -122,20 +123,23 @@ object SecureApiKeyStore {
      * never actually gain encryption. Re-encrypting on the first read closes that gap without
      * making the user re-enter the key.
      *
+     * The value is trimmed on migration, so the stored, displayed and sent forms all agree.
+     *
      * Keystore IPC + AES/GCM, so call this off the main thread.
      *
-     * @return the plaintext value, or null when nothing is stored or decryption failed.
+     * @return the trimmed plaintext value, or null when nothing is stored or decryption failed.
      */
     fun readAndMigrate(prefs: SharedPreferences?, key: String): String? {
         val stored = prefs?.getString(key, null) ?: return null
         if (stored.startsWith(ENC_PREFIX)) return decrypt(stored)
-        if (stored.isBlank()) return stored
+        val plain = stored.trim()
+        if (plain.isEmpty()) return plain
         try {
-            prefs.edit().putString(key, encrypt(stored)).apply()
+            prefs.edit().putString(key, encrypt(plain)).apply()
             Log.i(TAG, "Upgraded legacy plaintext value for '$key' to ciphertext")
         } catch (e: Exception) {
             Log.w(TAG, "Could not upgrade legacy plaintext value for '$key' to ciphertext", e)
         }
-        return stored
+        return plain
     }
 }
diff --git a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
index 96d50ed0..be4e2b1c 100644
--- a/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
+++ b/ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/viewmodel/AiSettingsViewModel.kt
@@ -13,6 +13,9 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import com.itsaky.androidide.plugins.PluginContext
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
 
 /**
  * State for the model file loading.
@@ -62,6 +65,13 @@ class AiSettingsViewModel(
         /** Default selection; kept in sync with GeminiBackend.DEFAULT_MODEL. */
         private const val DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"
 
+        /**
+         * Failsafe cap on the cross-plugin model listing, above ai-core's own per-request budget
+         * (15 s connect + 15 s read, paginated) so a slow-but-live fetch is never truncated.
+         * Bounds a future that may never complete; it is not a network timeout.
+         */
+        private const val LIST_MODELS_TIMEOUT_SECONDS = 60L
+
         /** Shown only when the live catalog can't be fetched — current models, no retired ones. */
         private val FALLBACK_MODELS = listOf(
             "gemini-2.5-flash",
@@ -228,6 +238,14 @@ class AiSettingsViewModel(
         SecureApiKeyStore.readAndMigrate(getPluginPrefs(), "gemini_api_key")
     }
 
+    /**
+     * True when a Gemini key is present on disk, whether or not it can still be decrypted. Lets
+     * the UI tell "nothing was saved" from "the Keystore entry is gone" — [getGeminiApiKey] is
+     * null for both. Raw pref only, so no Keystore IPC and safe on the main thread.
+     */
+    fun hasStoredGeminiApiKey(): Boolean =
+        !getPluginPrefs()?.getString("gemini_api_key", null).isNullOrBlank()
+
     fun getGeminiApiKeySaveTimestamp(): Long {
         return getPluginPrefs()?.getLong("gemini_api_key_timestamp", 0L) ?: 0L
     }
@@ -325,7 +343,7 @@ class AiSettingsViewModel(
         val result = method.invoke(backend)
 
         @Suppress("UNCHECKED_CAST")
-        val future = result as? java.util.concurrent.CompletableFuture<List<String>>
+        val future = result as? CompletableFuture<List<String>>
         if (future == null) {
             android.util.Log.e(
                 TAG,
@@ -333,7 +351,19 @@ class AiSettingsViewModel(
             )
             return emptyList()
         }
-        return future.get().orEmpty()
+        // Bounded: a future from ai-core's already-cancelled scope would never complete.
+        return try {
+            future.get(LIST_MODELS_TIMEOUT_SECONDS, TimeUnit.SECONDS).orEmpty()
+        } catch (e: TimeoutException) {
+            future.cancel(true)
+            android.util.Log.e(
+                TAG,
+                "listModels() did not complete within ${LIST_MODELS_TIMEOUT_SECONDS}s; " +
+                    "is ai-core still active?",
+                e
+            )
+            emptyList()
+        }
     }
 
     /**
diff --git a/ai-core/build.gradle.kts b/ai-core/build.gradle.kts
index ff3a4772..43089d40 100644
--- a/ai-core/build.gradle.kts
+++ b/ai-core/build.gradle.kts
@@ -70,6 +70,71 @@ dependencies {
     testImplementation("io.mockk:mockk:1.13.8")
 }
 
+/**
+ * Fails the build when the crypto constants of ai-assistant's and ai-core's duplicated
+ * SecureApiKeyStore drift, which would otherwise surface only on a device as "backend not
+ * available". On preBuild, not `test`: CI runs assemblePlugin and never the unit tests.
+ */
+val verifySecureApiKeyStoreParity by tasks.registering {
+    group = "verification"
+    description = "Fails if ai-core and ai-assistant's SecureApiKeyStore crypto constants differ."
+
+    val ours = file("src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt")
+    val theirs = file(
+        "../ai-assistant/src/main/kotlin/com/itsaky/androidide/plugins/aiassistant/security/SecureApiKeyStore.kt"
+    )
+    // inputs.files (not inputs.file) so a missing sibling is an absent input, not a failure.
+    inputs.files(ours, theirs)
+
+    doLast {
+        if (!theirs.exists()) {
+            logger.warn(
+                "SecureApiKeyStore parity check skipped: ${theirs.path} not found. " +
+                    "Build ai-core from the plugin-examples repo to verify it."
+            )
+            return@doLast
+        }
+
+        val required = listOf("KEYSTORE", "ALIAS", "TRANSFORM", "IV_LEN", "TAG_BITS", "ENC_PREFIX")
+        val constant = Regex("""const\s+val\s+(\w+)\s*=\s*(.+)""")
+
+        fun constantsOf(source: File): Map<String, String> = source.readLines()
+            .mapNotNull { constant.find(it) }
+            .associate { it.groupValues[1] to it.groupValues[2].substringBefore("//").trim() }
+            .filterKeys { it in required }
+
+        val ourConstants = constantsOf(ours)
+        val theirConstants = constantsOf(theirs)
+
+        val missing = required.filter { it !in ourConstants || it !in theirConstants }
+        val drifted = required.filter {
+            it in ourConstants && it in theirConstants && ourConstants[it] != theirConstants[it]
+        }
+
+        if (missing.isNotEmpty() || drifted.isNotEmpty()) {
+            val details = buildString {
+                if (missing.isNotEmpty()) {
+                    appendLine("  missing from one or both copies: ${missing.joinToString()}")
+                }
+                drifted.forEach {
+                    appendLine("  $it: ai-core=${ourConstants[it]} ai-assistant=${theirConstants[it]}")
+                }
+            }
+            throw GradleException(
+                "SecureApiKeyStore crypto constants differ between ai-core and ai-assistant.\n" +
+                    details +
+                    "A key encrypted by one plugin would not decrypt in the other. " +
+                    "Keep both copies in sync:\n" +
+                    "  ${ours.path}\n  ${theirs.path}"
+            )
+        }
+    }
+}
+
+tasks.named("preBuild") {
+    dependsOn(verifySecureApiKeyStoreParity)
+}
+
 // AAR metadata checks are disabled by convention for these application-as-library
 // plugins. The prebuilt llama .aar carries a "core library desugaring required"
 // flag, but this module's minSdk (33) makes desugaring unnecessary at runtime,
diff --git a/ai-core/src/main/AndroidManifest.xml b/ai-core/src/main/AndroidManifest.xml
index d85f5827..4fdb1037 100644
--- a/ai-core/src/main/AndroidManifest.xml
+++ b/ai-core/src/main/AndroidManifest.xml
@@ -35,7 +35,7 @@
 
         <meta-data
             android:name="plugin.max_ide_version"
-            android:value="26.30" />
+            android:value="26.31" />
 
         <meta-data
             android:name="plugin.permissions"
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/AiCorePlugin.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/AiCorePlugin.kt
index 5f81c715..f0af47f2 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/AiCorePlugin.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/AiCorePlugin.kt
@@ -54,6 +54,8 @@ class AiCorePlugin : IPlugin, DocumentationExtension {
             // Create and register Gemini API backend
             geminiBackend = GeminiBackend(context)
             llmService.registerBackend(geminiBackend)
+            // Decrypt the key off-thread now, so a main-thread isAvailable() can't say "no key".
+            geminiBackend.warmKeyCache()
             context.logger.info("AiCorePlugin: Registered Gemini API backend")
 
             return true
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
index d0f15016..f0056540 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/GeminiBackend.kt
@@ -86,7 +86,7 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
      * today reaches this from [Dispatchers.IO], but [LlmBackend.isAvailable] is a synchronous
      * interface method a future caller could invoke from the UI thread — so instead of relying
      * on that, a main-thread call answers from the cache and kicks off a background refresh
-     * rather than blocking. Worst case it reports "no key" once and is correct thereafter.
+     * rather than blocking; [warmKeyCache] fills the cache first so that never reports "no key".
      */
     private fun readGeminiApiKey(): String? {
         val stored = agentPrefs()?.getString(KEY_API_KEY, null)
@@ -121,6 +121,25 @@ class GeminiBackend(private val context: PluginContext) : LlmBackend {
         return plain
     }
 
+    /**
+     * Warm [keyCache] off-thread, so the synchronous [isAvailable] never reports "no key" for a
+     * stored, decryptable key just because it was first called from the main thread. Invoked from
+     * AiCorePlugin.activate().
+     */
+    fun warmKeyCache() {
+        if (!scope.isActive) return
+        scope.launch {
+            try {
+                val warmed = refreshKeyCache() != null
+                context.logger.debug("GeminiBackend: key cache warmed (key present: $warmed)")
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                context.logger.warn("GeminiBackend: could not warm key cache: ${e.message}")
+            }
+        }
+    }
+
     override fun getId(): String = "gemini"
 
     override fun getName(): String = "Gemini API"
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
index 30b6a0bd..3e83461f 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/LocalLlmBackend.kt
@@ -10,6 +10,7 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withTimeoutOrNull
@@ -37,9 +38,10 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
 
     /**
      * Separate from [scope] because [close] cancels [scope] and then has to run the unload —
-     * work submitted to a cancelled scope never starts.
+     * work submitted to a cancelled scope never starts. Cancelled once its teardown job finishes;
+     * a `var` because that is terminal and a second [close] must re-create it to do any work.
      */
-    private val teardownScope = CoroutineScope(Dispatchers.IO)
+    @Volatile private var teardownScope = CoroutineScope(Dispatchers.IO)
 
     /** The [close] teardown, retained so [awaitClose] can join it. */
     @Volatile private var teardownJob: Job? = null
@@ -408,11 +410,14 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
      * Teardown runs on [teardownScope] rather than a throwaway `CoroutineScope(...)` so the
      * work has an owner: the returned [Job] is retained in [teardownJob], letting a caller
      * observe or await it via [awaitClose] instead of dispose() returning while native work is
-     * still in flight with no handle to it.
+     * still in flight with no handle to it, and is cancelled once that job completes.
      */
     fun close() {
         scope.cancel()
-        teardownJob = teardownScope.launch {
+        // A prior close() cancelled the scope on completion, and a dead scope never starts work.
+        val teardown = teardownScope.takeIf { it.isActive }
+            ?: CoroutineScope(Dispatchers.IO).also { teardownScope = it }
+        teardownJob = teardown.launch {
             try {
                 unloadModelInternal()
             } catch (e: Exception) {
@@ -424,6 +429,8 @@ class LocalLlmBackend(private val context: PluginContext) : LlmBackend {
                 llama.shutdown()
             }
         }
+        // Cancel the captured scope, not the field: a later close() may have replaced it.
+        teardownJob?.invokeOnCompletion { teardown.cancel() }
     }
 
     /**
diff --git a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
index c7c75c7d..229f17a3 100644
--- a/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
+++ b/ai-core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/SecureApiKeyStore.kt
@@ -25,6 +25,7 @@ import javax.crypto.spec.GCMParameterSpec
  * Android Keystore. Keep the two copies in sync.
  */
 object SecureApiKeyStore {
+    // Drift in the constants below fails ai-core's verifySecureApiKeyStoreParity build task.
     private const val TAG = "SecureApiKeyStore"
     private const val KEYSTORE = "AndroidKeyStore"
     private const val ALIAS = "cotg_ai_gemini_key_v1"
@@ -122,20 +123,23 @@ object SecureApiKeyStore {
      * never actually gain encryption. Re-encrypting on the first read closes that gap without
      * making the user re-enter the key.
      *
+     * The value is trimmed on migration, so the stored, displayed and sent forms all agree.
+     *
      * Keystore IPC + AES/GCM, so call this off the main thread.
      *
-     * @return the plaintext value, or null when nothing is stored or decryption failed.
+     * @return the trimmed plaintext value, or null when nothing is stored or decryption failed.
      */
     fun readAndMigrate(prefs: SharedPreferences?, key: String): String? {
         val stored = prefs?.getString(key, null) ?: return null
         if (stored.startsWith(ENC_PREFIX)) return decrypt(stored)
-        if (stored.isBlank()) return stored
+        val plain = stored.trim()
+        if (plain.isEmpty()) return plain
         try {
-            prefs.edit().putString(key, encrypt(stored)).apply()
+            prefs.edit().putString(key, encrypt(plain)).apply()
             Log.i(TAG, "Upgraded legacy plaintext value for '$key' to ciphertext")
         } catch (e: Exception) {
             Log.w(TAG, "Could not upgrade legacy plaintext value for '$key' to ciphertext", e)
         }
-        return stored
+        return plain
     }
 }