fix: harden lifecycle checks and reduce redundant work

.github/workflows/ci.yml

@@ -37,11 +37,7 @@ jobs:
           if [[ "$EVENT_NAME" == workflow_dispatch ]]; then
             classification=$'runtime=true\nubuntu_container_e2e=true'
           else
-            # Run the classifier as it exists at $BASE_SHA, not the checked-out
-            # (possibly PR-modified) copy -- otherwise a PR could edit this
-            # script to always report "nothing changed" and suppress its own
-            # e2e coverage. $BASE_SHA predates the PR/push, so its content
-            # can't have been written by it.
+            # Use the base revision so a PR cannot change the classifier to skip its own E2E checks.
             classifier_script="$(mktemp)"
             git show "$BASE_SHA:scripts/classify-ci-changes.sh" >"$classifier_script"
             classification="$(bash "$classifier_script" "$BASE_SHA" "$GITHUB_SHA")"

bin/selfishell

@@ -2,11 +2,7 @@
 
 set -euo pipefail
 
-# Every command pays for this resolution, so strip the directory with
-# parameter expansion instead of an external `dirname`: that one process is
-# roughly a third of `selfishell version`'s runtime. `${path%/*}` leaves a bare
-# filename unchanged, and a path with no directory means the current one --
-# what `dirname` reports as ".".
+# Avoid spawning dirname on every invocation; a bare filename needs a "." fallback.
 SELFISHELL_SOURCE="${BASH_SOURCE[0]}"
 while [[ -L "$SELFISHELL_SOURCE" ]]; do
   SELFISHELL_SOURCE_DIR="${SELFISHELL_SOURCE%/*}"

config/macos/zshrc

@@ -1,7 +1,4 @@
-# --------------------------------------------------
-# Homebrew
 # Detect Homebrew even when a new Mac does not have it in PATH yet
-# --------------------------------------------------
 
 if ! command -v brew >/dev/null 2>&1; then
   if [[ -x /opt/homebrew/bin/brew ]]; then
@@ -11,21 +8,11 @@ if ! command -v brew >/dev/null 2>&1; then
   fi
 fi
 
-
-# --------------------------------------------------
-# PATH
 # Register paths before plugins look for commands such as kubectl
-# --------------------------------------------------
 
 typeset -U path PATH
 path=("$HOME/.local/bin" "$HOME/.rd/bin" $path)
 
-
-
-# --------------------------------------------------
-# Common settings
-# --------------------------------------------------
-
 COMMON_ZSH="${XDG_CONFIG_HOME:-$HOME/.config}/selfishell/zsh/common.zsh"
 
 if [[ -r "$COMMON_ZSH" ]]; then

config/shared/nvim/lua/config/autocmds.lua

@@ -1,14 +1,10 @@
 local group = vim.api.nvim_create_augroup("UserGeneralAutocmds", { clear = true })
 
--- Neovim 0.12 uses the built-in Tree-sitter highlighter. The current
--- nvim-treesitter plugin no longer enables it through setup()/opts.
+-- nvim-treesitter installs parsers; Neovim enables highlighting separately.
 vim.treesitter.language.register("terraform", "tf")
 
--- nvim-treesitter 1.0+ also dropped ensure_installed/auto_install, so
--- parsers install lazily on FileType. Neovim fires FileType more than once
--- per buffer, and a second install() before the first finishes blocks on a
--- nested vim.wait() -- observed to leave a highlighter never started -- so
--- track in-flight installs here rather than relying on its own guard.
+-- Repeated FileType events can nest install() waits and prevent highlighting.
+-- Track each in-flight language until installation finishes.
 local pending_installs = {}
 
 -- Suppresses a repeat notification only, never the retry: pending_installs
@@ -44,8 +40,6 @@ local function ensure_parser_installed(buf, lang)
     local buffers = pending_installs[lang]
     pending_installs[lang] = nil
     if not installed then
-      -- Report once per language per session rather than leaving
-      -- highlighting silently missing.
       if not notified_failures[lang] then
         notified_failures[lang] = true
         vim.notify(
@@ -96,8 +90,7 @@ vim.api.nvim_create_autocmd("VimResized", {
   end,
 })
 
--- A motion yank shows nothing, and 'report' (default 2) silences short ones
--- too, so flash the range to catch an off-by-one text object before paste.
+-- Highlight yanks that Vim's normal change reporting does not show.
 vim.api.nvim_create_autocmd("TextYankPost", {
   group = group,
   callback = function()

config/shared/nvim/lua/config/keymaps.lua

@@ -1,7 +1,6 @@
 local map = vim.keymap.set
 local M = {}
 
--- Clear search highlighting
 map("n", "<Esc>", "<cmd>nohlsearch<CR>", {
   silent = true,
   desc = "Clear search highlight",
@@ -37,15 +36,13 @@ end, {
   desc = "Delete buffer",
 })
 
--- Keep the selection active while adjusting indentation.
 map("x", "<", "<gv", {
   desc = "Indent left and reselect",
 })
 map("x", ">", ">gv", {
   desc = "Indent right and reselect",
 })
 
--- Diagnostic navigation
 map("n", "[d", function()
   vim.diagnostic.jump({ count = -1, float = true })
 end, { desc = "Previous diagnostic" })

config/shared/nvim/lua/config/options.lua

@@ -1,15 +1,13 @@
 local opt = vim.opt
 
--- Floating windows (diagnostics, hover, signature help, ...)
 vim.o.winborder = "rounded"
 
 -- UI
 opt.number = true
 opt.relativenumber = true
 opt.hlsearch = true
 opt.ruler = false
--- lualine renders the mode in its first section; leaving showmode on
--- prints "-- INSERT --" on the command line right below it as well.
+-- lualine already displays the mode.
 opt.showmode = false
 opt.termguicolors = true
 opt.signcolumn = "yes"
@@ -43,12 +41,9 @@ opt.fileencodings = { "utf-8", "euc-kr" }
 
 -- Completion menu behavior
 opt.completeopt = { "menu", "menuone", "noselect" }
--- nvim-cmp reads this for its own menu and treats 0 as "no limit", which
--- makes the menu as tall as the number of candidates -- easily most of the
--- screen for an LSP source.
+-- Also caps nvim-cmp's menu; 0 leaves it unlimited.
 opt.pumheight = 10
 
--- Diagnostic display
 vim.diagnostic.config({
   virtual_text = {
     prefix = "●",

config/shared/nvim/lua/config/plugin_versions.lua

@@ -2,9 +2,7 @@ local M = {}
 local revisions = {}
 local manifest = vim.fn.stdpath("config") .. "/plugin-versions.conf"
 
--- io.lines throws on a missing manifest (a partial install, or Neovim run
--- straight against this config), crashing `require` with a raw traceback.
--- Degrade to empty: callers already report each missing revision clearly.
+-- A missing manifest must not crash require; callers report missing revisions.
 local file = io.open(manifest, "r")
 if file then
   for line in file:lines() do

config/shared/nvim/lua/plugins/completion.lua

@@ -12,8 +12,6 @@ return {
       local cmp = require("cmp")
 
       cmp.setup({
-        -- Neovim 0.12's native snippet engine replaces LuaSnip; it expands
-        -- the same LSP snippet syntax cmp already hands it.
         snippet = {
           expand = function(args)
             vim.snippet.expand(args.body)
@@ -26,8 +24,7 @@ return {
           ["<C-f>"] = cmp.mapping.scroll_docs(4),
           ["<C-Space>"] = cmp.mapping.complete(),
 
-          -- Preserves the existing behavior: Enter accepts the first item
-          -- even when it has not been explicitly selected.
+          -- Enter accepts the first item even without an explicit selection.
           ["<CR>"] = cmp.mapping.confirm({ select = true }),
 
           ["<Tab>"] = cmp.mapping(function(fallback)

config/shared/nvim/lua/plugins/editor.lua

@@ -1,7 +1,6 @@
 local plugin = require("config.plugin_versions").spec
 
 return {
-  -- Automatic bracket/quote pairs.
   plugin("windwp/nvim-autopairs", {
     event = "InsertEnter",
     opts = {},
@@ -18,7 +17,6 @@ return {
     end,
   }),
 
-  -- VS Code-style colored delimiters.
   plugin("HiPhish/rainbow-delimiters.nvim", {
     -- Load before the initial buffer's FileType event so the plugin can attach.
     event = { "BufReadPre", "BufNewFile" },
@@ -34,14 +32,11 @@ return {
     end,
   }),
 
-  -- Keymap guide: helpful for Space leader mappings.
   plugin("folke/which-key.nvim", {
     event = "VeryLazy",
     opts = {
       icons = {
-        -- Disable per-mapping filetype/devicons icon lookups; which-key
-        -- deep-merges `keys` with its Nerd Font defaults, so every key
-        -- must be listed here explicitly or it keeps its default glyph.
+        -- which-key deep-merges keys, so every Nerd Font default needs an override.
         mappings = false,
         keys = {
           Up = "Up ",

config/shared/nvim/lua/plugins/lsp.lua

@@ -29,7 +29,6 @@ return {
       plugin("hrsh7th/cmp-nvim-lsp"),
     },
     config = function()
-      -- Apply completion capabilities to every LSP config.
       vim.lsp.config("*", {
         capabilities = require("cmp_nvim_lsp").default_capabilities(),
       })

config/shared/nvim/lua/plugins/ui.lua

@@ -49,7 +49,6 @@ local function lualine_mode_color()
 end
 
 return {
-  -- Theme: must be available during startup.
   plugin("mofiqul/vscode.nvim", {
     lazy = false,
     priority = 1000,
@@ -58,7 +57,6 @@ return {
     end,
   }),
 
-  -- File explorer: loaded only when its command or keymap is used.
   plugin("nvim-tree/nvim-tree.lua", {
     main = "nvim-tree",
     cmd = {
@@ -98,8 +96,6 @@ return {
         git_ignored = false,
       },
       renderer = {
-        -- Keep folders distinct without spending the narrow tree's width on
-        -- icons, and show native branch guides for nested directories.
         add_trailing = true,
         group_empty = true,
         highlight_git = "name",
@@ -138,8 +134,6 @@ return {
     },
   }),
 
-  -- Buffer tabs: keep the critical startup path clear and hide the bar when a
-  -- single buffer is open.
   plugin("akinsho/bufferline.nvim", {
     event = "VeryLazy",
     keys = {
@@ -157,8 +151,7 @@ return {
     opts = {
       options = {
         always_show_bufferline = false,
-        -- Disabling this avoids ever touching nvim-web-devicons: it's
-        -- checked before the (also pcall-guarded) require.
+        -- Disable icon lookups to avoid loading nvim-web-devicons.
         show_buffer_icons = false,
         close_command = function(bufnr)
           Snacks.bufdelete(bufnr)
@@ -279,7 +272,6 @@ return {
     },
   }),
 
-  -- Statusline: not required for the critical startup path.
   plugin("nvim-lualine/lualine.nvim", {
     event = "VeryLazy",
     opts = {
@@ -346,11 +338,7 @@ return {
     },
   }),
 
-  -- Scope comes from the node's ancestry rather than a per-language
-  -- node-type whitelist, falling back to indentation when Tree-sitter finds
-  -- nothing. Loaded eagerly because Snacks defers indent to BufReadPost,
-  -- which never fires for BufNewFile or the initial unnamed buffer; the
-  -- direct indent.enable() below covers those and is idempotent.
+  -- Load eagerly and enable directly: Snacks' BufReadPost hook misses new and unnamed buffers.
   plugin("folke/snacks.nvim", {
     lazy = false,
     priority = 1000,
@@ -464,9 +452,7 @@ return {
       },
     },
     opts = {
-      -- ripgrep is guaranteed by the developer profile; fd is not, so the
-      -- picker shouldn't vary by what's personally installed. No source shows
-      -- a file icon: without nvim-web-devicons there's no icon set to use.
+      -- The developer profile guarantees ripgrep, but not fd.
       picker = {
         ui_select = false,
         sources = {
@@ -480,13 +466,10 @@ return {
           buffers = {
             icons = { files = { enabled = false } },
           },
-          -- Telescope's diagnostics picker showed the whole workspace, not
-          -- just the cwd; Snacks defaults to cwd-only.
+          -- Include diagnostics across the whole workspace.
           diagnostics = {
             filter = { cwd = false },
           },
-          -- Both reach the same filename formatter as the sources above. The
-          -- git log pickers don't -- their commit glyph is Snacks' own.
           git_status = {
             icons = { files = { enabled = false } },
           },
@@ -528,7 +511,6 @@ return {
     end,
   }),
 
-  -- Git changes, hunk actions, and blame information.
   plugin("lewis6991/gitsigns.nvim", {
     event = { "BufReadPre", "BufNewFile" },
     opts = {
@@ -567,7 +549,6 @@ return {
           end
         end, "Previous Git change")
 
-        -- Hunk actions.
         map("n", "<leader>hp", gitsigns.preview_hunk, "Preview Git hunk")
         map("n", "<leader>hi", gitsigns.preview_hunk_inline, "Preview Git hunk inline")
         map("n", "<leader>hs", gitsigns.stage_hunk, "Stage Git hunk")
@@ -587,7 +568,6 @@ return {
           })
         end, "Reset selected Git lines")
 
-        -- Blame and diff.
         map("n", "<leader>hb", function()
           gitsigns.blame_line({ full = true })
         end, "Show Git blame")
@@ -598,26 +578,21 @@ return {
           gitsigns.diffthis("~")
         end, "Diff against previous commit")
 
-        -- Optional visual features.
         map("n", "<leader>ub", gitsigns.toggle_current_line_blame, "Toggle Git blame")
         map("n", "<leader>uw", gitsigns.toggle_word_diff, "Toggle Git word diff")
 
-        -- Git hunk text object.
         map({ "o", "x" }, "ih", gitsigns.select_hunk, "Select Git hunk")
       end,
     },
   }),
 
-  -- Scrollbar with the current viewport and diagnostics.
   plugin("petertriho/nvim-scrollbar", {
     main = "scrollbar",
     event = { "BufReadPost", "BufNewFile" },
     opts = {
       show_in_active_only = true,
       hide_if_all_visible = true,
-      -- The default handle color (linked to CursorColumn) is nearly
-      -- indistinguishable from vscode.nvim's background. Use VS Code's own
-      -- scrollbar slider color/opacity instead of a fully opaque gray.
+      -- The default CursorColumn color is hard to see against this theme.
       handle = {
         blend = 60,
         color = "#797979",
@@ -631,9 +606,7 @@ return {
         "mason",
         "help",
       },
-      -- gitsigns is off: the sign column already shows these hunks, and
-      -- mirroring them doubled the redraw triggers. cursor is off to drop the
-      -- CursorMoved-driven redraw on every cursor move.
+      -- Avoid duplicate hunk redraws and a redraw on every cursor move.
       handlers = {
         cursor = false,
         diagnostic = true,
@@ -644,7 +617,6 @@ return {
     },
   }),
 
-  -- Inline document preview.
   plugin("OXY2DEV/markview.nvim", {
     ft = { "markdown", "quarto", "rmd", "typst", "asciidoc" },
     keys = {
@@ -656,7 +628,6 @@ return {
     },
     opts = {
       preview = {
-        -- Avoid nvim-web-devicons, as elsewhere in this file.
         icon_provider = "internal",
       },
     },