# Bugs

Priority scale:
- **P0**: Broken core functionality — data loss, crash, or fundamentally wrong behavior.
- **P1**: Significant usability issue — feature works but is confusing or misleading.
- **P2**: Polish issue — inconsistency, visual glitch, or minor misbehavior.
- **P3**: Cosmetic / edge case — low impact, fix when convenient.

---

## Feature requests

### ~~P1: Multi-cursor editing~~ FIXED
`Ctrl+D` to select next occurrence of the current word/selection, then type/delete at all cursors simultaneously.

**Fix:** Added full multi-cursor editing support. First `⌃D` selects word under cursor. Subsequent presses add the next occurrence as a secondary cursor. All typing and backspace affects all cursors simultaneously, processed in reverse document order for offset stability. Same-line cursor position adjustment handles multiple occurrences on one line. Escape clears multi-cursors; arrow keys also exit multi-cursor mode. Status bar shows cursor count indicator. Data model: `_multi_cursors` array in View.pm, editing via `_multi_cursor_insert_char`/`_multi_cursor_backspace` in Editor.pm with undo grouping. Duplicate Line Down moved to palette-only (was `⌃D`). Added `cmd_select_next_occurrence` to CommandRegistry. 9 tests added.

### ~~P1: Status bar rework — always-visible keys grouped by modifier~~ FIXED
The status bar should make keyboard shortcuts always visible and organized by modifier key, similar to Zellij's approach. Group `⌃` (Ctrl) shortcuts on the left and `⌥` (Alt) shortcuts on the right, so the modifier is shown once per group rather than repeated on every pill — saving space and making the modifier split immediately clear. Buttons should be contextual, showing what's most relevant to the current state (e.g., editing vs find mode vs file tree). Currently, pills are arranged by category (FILE/EDIT/NAVIGATE/VIEW from `CommandRegistry::commands_for_status_bar`) with each pill repeating its modifier, and lower-priority pills drop off at narrow widths. The rework should ensure the most useful actions are always visible regardless of terminal width.

**Root cause:** The DOCUMENT-context status bar built one flat, category-ordered pill list from `commands_for_status_bar`, greedily packed left-to-right, with each pill repeating its full shortcut including the modifier glyph (`⌃S`, `⌥Z`, ...). Only 6 commands ever had `priority > 0` (eligible for the bar at all), and "Open File" was a second hardcoded always-there pill next to the palette trigger — there was no per-modifier structure and no guarantee about which pill(s) survive a narrow terminal.

**Fix:** Reworked `Renderer::_render_context_status_bar` (DOCUMENT context only — FIND/tree-focus/prompt keep their existing dedicated renderers) into two modifier-grouped columns: `⌃` pills left-aligned right after the cursor pill, `⌥` pills right-aligned right before the always-fixed `⌃␣` palette trigger, each column showing its modifier glyph once as a plain dim label (not a pill) instead of repeating it per pill. `CommandRegistry` assigns each status-bar-eligible command to a column purely by shortcut prefix (`⌃`→left, `⌥`→right); commands with no shortcut, a bare function key, or a multi-modifier chord (`⌃⇧F`) are excluded from the bar (still in the palette). Expanded the eligible set from 6 to 10 commands (added Save `⌃S` pri 1, Open File `⌃O/⌃P` pri 2 — folded in from its old hardcoded slot, File Tree `⌃B` pri 3 to `⌃`; Minimap `⌥M` pri 3, Nerd Font `⌥I` pri 5 to `⌥`) so each column has a meaningful, useful set instead of 2-3 leftovers. Removed `doc_tutorial` (F1) from the bar entirely — it has no modifier so it doesn't fit either column; still in the palette and bound to F1.

New `_fit_pill_group()` tries the full pill form (`icon label key`) first and only falls back to a compact form (`icon key`, label dropped) for the *whole* column if even its top-priority pill can't fit in full — so a pill degrades before it disappears. New budget negotiation computes each column's minimum width (label + compact top pill); whenever both minimums fit in the available space, `⌃`'s budget is capped so it can never greedily starve `⌥`, guaranteeing the priority-1 pill in *both* columns (`⌃S` Save, `⌥Z` Word Wrap) renders in some form. Under genuine extreme-narrow scarcity (not even both minimums fit), `⌃` — rendered first — wins the remaining space; only the cursor-position pill and `⌃␣` palette trigger are truly unconditional at any width.

Click hit-testing (`Editor::handle_status_bar_click`) and hover (`_handle_mouse_hover` / `get_status_buttons`) needed no changes — both work by button array position/range, and the new `_render_pill_list` helper pushes buttons in render order exactly like the old single-list loop did, so hover indices stay contiguous across the two columns.

**Tests:** `tests/renderer.t` — 4 new subtests: pills grouped left/right with modifier shown once (not repeated per pill), priority-1 pill in each column survives a narrow width (62 cols), cursor pill + palette trigger survive an extreme-narrow width (32 cols), and click buttons still register with correct hit areas. `tests/command_registry.t` — new subtest asserting every status-bar-eligible command's shortcut starts with `⌃` or `⌥` (the grouping contract) and that each column has exactly one priority-1 command. QA: `QA-SBAR-016`..`QA-SBAR-020` in `qa/26_status_bar.txt`, scripts `qa/scripts/tier1/sbar_016`..`sbar_020`, regression entries `QA-REG-110`..`QA-REG-112` in `qa/40_regression_bugs.txt`. Verified interactively via `hangon` (default 80x24 session): Ctrl group (Save, Open File) renders left of cursor pill's gap, Alt group (Word Wrap, compact `Z`) renders right before Commands, toggle on/off color still visible in compact form, hover brightens the correct pill, clicking Save pill triggers save, find mode / file tree focus / command palette all unaffected.

### ~~P3: Theme toggle pill icon doesn't switch with theme~~ FIXED (see below)
Found independently while reworking the status bar, at the same time a second concurrent agent found and fixed the same bug while adding automatic dark/light mode — see "Theme palette icon was static despite claiming to be dynamic" further down for the fix (both status-bar-pill and palette-row icon-resolution sites in `Renderer.pm`, `QA-REG-139`).

### P2: First Alt-chord after startup can be silently dropped
Found while interactively verifying the status bar rework (screenshot-diffing the Word Wrap pill's on/off color before/after a single `⌥Z`). Reproduced on a completely fresh session, on both the pre-rework and post-rework binary (confirmed pre-existing, unrelated to the status bar change): the *first* key sent to a just-started `zepto` process, if it's an Alt chord (e.g. `⌥Z`), sometimes has no effect at all — no toggle, no error, nothing — even with a 1s settle delay before sending it. A plain (non-modified) key like `→` always registers as the first key. Not 100% reproducible for every Alt chord in ad-hoc testing (`⌥C` appeared to register fine as a first key in one trial), which points at a timing race in Terminal.pm/InputParser.pm's escape-sequence handling around startup (e.g. an initial terminal capability probe response arriving and being read together with the first `ESC`-prefixed keystroke) rather than a deterministic logic bug. Needs dedicated investigation — out of scope for the status bar rework. QA scripts that send an Alt chord as the very first interaction should send a harmless warm-up key (e.g. `right`) first to avoid flaking on this (see `qa/scripts/tier1/sbar_020_compact_toggle_color.sh`).

**Investigation update (2026-08-30, still unfixed):** Dedicated investigation for this entry alongside the two `⌃Space`/Escape bugs below (all three were suspected to share a root cause in Terminal.pm/InputParser.pm's escape-sequence handling; that suspicion held for the other two but NOT for this one — see write-up below). Ruled out:

- **No terminal capability probe exists in the current codebase at all.** `Editor::init()` only *writes* escape sequences at startup (cursor color OSC 12, cursor shape `\x1b[5 q`, alt-screen/mouse/bracketed-paste mode-sets) — none of these solicit a terminal reply. `ThemeDetect.pm`'s auto dark/light detection is explicitly scoped to *not* do a terminal OSC 11 round-trip (see its own header comment) — it only shells out to `defaults`/`gsettings`. So the "initial terminal capability probe response" theory in the original write-up does not match the current code; there is nothing that could produce an unsolicited reply to race against the first keystroke.
- **Instrumented byte-level tracing (temporary logging of every raw read and decoded event, added to `Editor::handle_input`/`flush_pending_input` for this investigation, removed before committing) across 51 automated `hangon` trials found zero drops**: 8 different Alt letters (`z c w m d b f i`) × startup delays from 0s to 1s, both against a reused state directory and a brand-new never-used one (ruling out first-run state-file creation as a factor), each verified via both the decoded-event log AND a visible-effect check (word wrap actually toggling on a long line). Every single trial showed the ESC and the following character arriving together in one `sysread()` — a real terminal/tmux always writes an Alt-chord as a single atomic write, never split across two reads, even with zero inter-key delay.
- Manually forcing a split (sending the ESC byte and the following character as two genuinely separate writes, mirroring how the fix for the `⌃Space`/Escape bugs below was validated) does NOT reproduce "silently drops with zero effect" — it reproduces a *different*, already-understood behavior: once the gap exceeds the outer ~0.5s idle-read timeout, the lone ESC resolves to a standalone Escape key and the following character types literally into the document (a visible effect, not "no toggle, no error, nothing"). That's the general ESC/Alt-chord disambiguation issue fixed below for the `⌃Space` and Escape bugs, not a match for this bug's specific symptom.

Given 51/51 clean automated trials and no code path found that could produce a genuine silent drop, this could not be confidently reproduced with the tooling available (`hangon`/tmux) and is left OPEN. Plausible remaining explanations, unconfirmed: (a) genuinely tied to physical-terminal (not tmux/pty) key-event timing that `hangon` cannot simulate, since real terminal emulators may split a key event's bytes across syscalls under conditions tmux's `send-keys`/literal-type doesn't reproduce; (b) an environmental artifact from the P1 "StateStore defaults to the real `~/.config/zepto`" bug active at the time of the original report (state-file corruption/races on a shared real config dir could plausibly eat a preference toggle silently) — that bug is also still open and untested against this one. Next investigator: try reproducing on a real terminal app (not tmux) with a `--state-dir` override to rule out (b), and if it reproduces there, get a packet-level (not read()-level) trace of the pty to see whether the OS ever actually delivers the two bytes in separate reads outside of tmux.

### ~~P2: `⌃Space` (open palette) can be silently dropped when it isn't the very first key sent~~ FIXED
Also found while building `QA-SBAR-020`. Reproduced manually and via the QA harness, consistently (not a one-off flake, unrelated hangon/tmux daemon load): `⌃Space` reliably opens the command palette when it's the *first* key sent to a fresh session (matches every other passing status-bar QA script), but if literally any other key — `→`, `↓`, even with a 1s gap in between — is sent first, the next `⌃Space` is swallowed: no palette opens, and if a subsequent `qa_send` types text expecting a palette filter, that text lands as literal document input instead (confirmed via screen capture: `"hWord Wrapello world"` was typed straight into the buffer). Retrying `⌃Space` again on the same already-"warmed-up" session does not help — it keeps failing.

**Root cause (NOT Terminal.pm/InputParser.pm — the original theory about `⌃Space`'s `NUL` encoding interacting badly with preceding bytes was wrong):** instrumented byte-level tracing showed `⌃Space` was *always* decoded correctly as a clean `char:' '+ctrl` event, every single trial, regardless of what key preceded it. The bug is purely in application-level command dispatch: `Editor::handle_ctrl_char`'s space-handler (`Editor.pm` ~1587-1609) treats "the character immediately before the cursor is a word character" as sufficient reason to try opening the completion menu *instead of* the palette — but `Completion::Controller::trigger()` requires a 2+ character prefix to produce any results (see `_extract_prefix`/the auto-trigger minimum). A cursor sitting right after exactly *one* word character (e.g. after pressing `→` once from the start of a word) satisfies the naive "mid-word" check but not the real completion requirement: `trigger()` dismisses immediately, `is_active()` stays false, and the old code `return`ed right there without ever falling through to `cmd_open_palette()` — so `⌃Space` did nothing at all. This reproduces with ANY first keystroke that leaves the cursor after a single word character (confirmed with `→`, `↓`, `↑` against a 2-line file: `→` and `↓`/`↑` from a fresh session that happen to land after a word char all failed identically; `↓`/`↑`/`←` that land at column 0 all worked fine, correctly isolating the condition to cursor-after-one-word-char, not "any non-first key").

**Fix:** `handle_ctrl_char`'s space-handler now only skips the palette when a completion menu *actually* opened (`is_active()` true after `trigger()`); otherwise it always falls through to `cmd_open_palette()`. The "open completion instead of palette" behavior for real mid-word completions (2+ char prefix with actual candidates) is unchanged and still verified working.

**Tests:** `tests/command_palette.t` new subtest "Ctrl+Space opens the palette when mid-word but no completion is available" (drives `handle_ctrl_char` directly via `handle_event`, asserts `STATE_PALETTE` and untouched document text). QA: `QA-PAL-024` in `qa/25_command_palette.txt`, `QA-REG-169` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_169_ctrlspace_palette_fallback.sh` — reproduces the exact `→` then `⌃Space` then type-a-filter scenario from the original report, including the "text lands as literal document input" corruption check. Verified interactively via `hangon`: `⌃Space` now opens the palette reliably after `→`/`↓`/`↑`/`←` as the first key (4/4), and the exact original corruption repro (type filter text after a "swallowed" `⌃Space`) now correctly lands in the palette filter box instead of the document. Script run standalone 3× with zero failures.

### ~~P2: Escape immediately followed by a burst keystroke send can drop or corrupt the next character(s)~~ FIXED
Found while writing `QA-REG-152` (cross-buffer completion cache accuracy). Reproduced independent of that change, including in single-document/no-tab-manager mode with plain keyword-based ghost text (not specific to `CrossBufferWordProvider` or multi-tab): after `Escape` dismisses an active ghost-text completion, sending a burst of characters where the *first* character is a space (e.g. typing `" moreWords"` to continue on a new word after the completed one) can silently drop that leading space — the new text lands glued directly onto the previous word with no separator. In one repro at a 1s delay after Escape, the dropped space came back as a spurious newline instead (text split onto the next line) rather than being dropped outright, so the failure mode isn't perfectly consistent. Reproduced at delays from 0.2s up to 1.0s after Escape.

**Root cause:** confirmed to be a general `InputParser` timing gap, NOT specific to completion-dismissal (reproduced identically with a plain `Escape` press and no completion popup active at all — the completion-dismiss framing in the original report was just the discovery scenario, not a causal factor). `InputParser` only ever resolved a lone pending `ESC` byte via `Editor::flush_pending_input()`, which is driven by the *outer* ~0.5s idle-read timeout in the main loop (`run()`) — it only fires when a full read returns *zero* bytes. If the ESC arrived alone in one `sysread()` and the next byte arrived in a genuinely separate, LATER read — but still before that 0.5s elapsed (e.g. a human pausing 100-400ms between dismissing ghost text and typing again) — the new byte was simply appended to the still-pending `"\x1b"` buffer and reparsed as its continuation. Since space (`0x20`) falls within the Alt-key byte range (32-126) that `_parse_escape()` accepts, `ESC` + a later space fused into a single "Alt+Space" event — which has no handler anywhere in `Editor.pm` — silently dropping the space. Confirmed via instrumented byte-level tracing at gaps of 0.1/0.2/0.3/0.4s (all fused into dropped Alt+Space) vs. 0.6/1.0s (gap exceeded the outer 0.5s timeout, so the lone ESC got flushed as standalone `Escape` first and the space then parsed correctly on its own) — an exact match for the bug's "not perfectly consistent" failure mode across different delays.

**Fix:** `InputParser.pm` now tracks how long a lone pending ESC (buffer exactly `"\x1b"`, nothing more) has been waiting, via a new `_esc_pending_at` timestamp (`Time::HiRes`) set the first time `parse()` leaves the buffer in that state. A new `parse()` call checks this at entry: if a continuation byte arrives after `ESC_DISAMBIGUATION_TIMEOUT` (30ms) has elapsed since the ESC started waiting, the stale ESC is resolved as a standalone `Escape` key event *before* the newly-arrived bytes are appended and parsed as its continuation — so they're parsed fresh, as their own independent keystroke(s), rather than fused with the old ESC. 30ms was chosen with wide safety margin in both directions: real Alt-chords (confirmed via 51 automated trials for the adjacent "First Alt-chord" investigation above, and 20 more for this fix) always arrive as a single atomic write with the two bytes in the *same* read, at any inter-key send delay from 0 to 1s — never observed split even once — so 30ms is far more headroom than any real OS scheduling jitter needs, while remaining far below any realistic human pause between two separate keystrokes. `flush_pending()` (the pre-existing outer-timeout path) also clears the new timestamp when it resolves a lone ESC, keeping the two mechanisms consistent.

**Tests:** `tests/input_parser.t` — 3 new subtests: a lone ESC resolves as standalone `Escape` (plus the next byte parsed fresh, unmodified) once `ESC_DISAMBIGUATION_TIMEOUT` has elapsed across two separate `parse()` calls; the same two-call split with *no* delay still fuses into one Alt+Space event (confirms the fix didn't overcorrect); and a same-call `ESC+z` (the way every real terminal actually sends an Alt-chord) still resolves as one Alt+key event regardless of the new timeout logic. QA: `QA-CPLT-022` in `qa/17_auto_pair_and_completion.txt`, `QA-REG-170` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_170_escape_burst_no_drop.sh` — reproduces the exact ghost-text-dismiss-then-delayed-burst scenario at 0.2s/0.5s/1.0s gaps in three independent fresh sessions. Verified interactively via `hangon`: the original repro (`dist` triggers ghost text → `Escape` dismisses it → wait → type `" moreWords"`) now correctly produces `dist moreWords` (space preserved) at all three gaps, and real Alt-chords remain unaffected (20/20 trials). Script run standalone 3× with zero failures. `qa/scripts/tier1/reg_152_crossbuffer_cache_accuracy.sh`'s existing NOTE about deliberately avoiding this pattern is left as-is (still accurate historical context; that script doesn't need to change now that the underlying bug is fixed).

### ~~P1: `Zepto::Editor->new()` defaults to the developer's real `~/.config/zepto` StateStore, so both unit tests and routine interactive `hangon` testing can silently corrupt the real machine's preferences/history~~ FIXED
Found incidentally while interactively verifying a `cmd_toggle_*` refactor (toggling Auto Pairs / Restore Session / Soft Tabs / Mouse live via `hangon` against `./zepto <scratch-file>`, per the mandatory Testing Workflow in `CLAUDE.md`). `Editor.pm:87` does `state_store => $opts{state_store} // Zepto::StateStore->new()`, and `StateStore::new` (`StateStore.pm:28-37`) falls back to `$XDG_CONFIG_HOME/zepto` or `$HOME/.config/zepto` when no `base_dir` is given. Running `./zepto` directly (exactly as `CLAUDE.md`'s own Testing Workflow example shows: `hangon start process --name zepto -- ./zepto /tmp/testfile.txt`, no state-dir override) toggling any preference persisted it straight into the real `~/.config/zepto/preferences.json` on the host machine, overwriting the developer's actual settings (`auto_pairs`, `mouse_enabled`, `restore_session`, `soft_tabs` all got flipped to off on this machine) — required a manual restore after the fact.

Worse, this same real-`$HOME` fallback is what a huge fraction of `tests/editor.t`'s `Zepto::Editor->new(...)` calls rely on implicitly — grep shows well over 100 constructions in that file alone with no `state_store => ...` passed, so they read/write whatever happens to be at `~/.config/zepto/*.json` on the machine running the suite. After the interactive session above left `soft_tabs` off in the real prefs file, `make test` immediately failed two previously-green, unrelated subtests (`Indent`, `Indent preserves selection` — they assume default `soft_tabs => 1` and got a tab character instead of 4 spaces) with zero code change in between: pure environmental cross-contamination between an interactive dev/QA session and the "isolated" unit test suite, on a single shared machine-global file.

**Root cause:** `Editor.pm:87` was the single unguarded chokepoint — grepping `lib/` confirms it's the *only* bare `Zepto::StateStore->new()` call in production code (everything else either takes an explicit `base_dir`, like `build.pl`'s `--state-dir`/`$ZEPTO_STATE_DIR` handling, or — like `Zepto::Preferences->new()` with no `state_store` — simply skips persistence rather than reaching for a real-`$HOME` fallback of its own). `tests/find.t`, `tests/multi_cursor.t`, `tests/renderer.t`, and most of `tests/editor.t` construct `Zepto::Editor->new()` without a `state_store`, so they all fell through to this one line.

**Fix:** Added `Zepto::Editor::_default_state_store()` (`Editor.pm`, used at the `state_store => $opts{state_store} // _default_state_store()` line) which checks `$ENV{HARNESS_ACTIVE}` — set automatically by Perl's `Test::Harness`/`prove` (confirmed empirically: `warn`'d it under `prove` vs. plain `perl`, got `1` vs. `undef`). When set, it constructs the `StateStore` with `base_dir => File::Temp::tempdir(CLEANUP => 1)` — a **fresh tempdir per call**, not one shared directory for the whole test run, so tests stay isolated from each other as well as from the real machine. Outside the harness, behavior is byte-for-byte unchanged: `Zepto::StateStore->new()` with no args, same as before.

**Layer chosen — `Editor.pm`, not `StateStore.pm`:** Considered gating this inside `StateStore::new()`'s own fallback instead, which would protect every future caller, not just `Editor.pm`. Rejected: `tests/state_store.t` has two subtests (`Default base_dir uses XDG_CONFIG_HOME`, `Default base_dir falls back to HOME/.config`) that deliberately construct a bare `Zepto::StateStore->new()` under `local $ENV{XDG_CONFIG_HOME}`/`local $ENV{HOME}` overrides and assert the *literal* resulting path — they're testing the raw fallback formula itself, and both already run under `HARNESS_ACTIVE`. An unconditional harness-gated redirect inside `StateStore.pm` would silently break those two assertions (the point of the P1 fix is to *stop* silently changing behavior, not to move the problem). Those two tests are already safe as written — they redirect `HOME`/`XDG_CONFIG_HOME` to fake paths (`/tmp/test-xdg`, `/tmp/test-home`) before construction, so they never touch the real machine even without this fix, since they only call `base_dir()` (a pure accessor) and never `get`/`put`. Since `Editor.pm:87` is confirmed to be the only unguarded real-`$HOME`-reaching call site in `lib/`, fixing it there closes the whole hole with a two-line diff and zero risk to `StateStore.pm`'s own tests.

**Test:** New subtest in `tests/editor.t`, `'Editor->new() with no state_store never touches the real config dir under the test harness'` — constructs two `Zepto::Editor->new()` with no `state_store` (the exact pattern used by 100+ other call sites), asserts the resolved `base_dir()` is neither the real `$XDG_CONFIG_HOME/zepto`/`~/.config/zepto` path nor anywhere under the real `$HOME`, asserts two separate `Editor->new()` calls get *different* per-call tempdirs (proving no cross-test sharing), flips `soft_tabs` through `$editor->{prefs}`, and asserts the real `~/.config/zepto/preferences.json`'s mtime is unchanged before/after. Confirmed failing against the unfixed code first (Rule 5): stashed the `Editor.pm` fix, ran `prove -l tests/editor.t`, watched it fail — and, living up to this bug's own description, that run *did* flip the real machine's `soft_tabs`/`theme` in `~/.config/zepto/preferences.json` (backed up beforehand, restored immediately after). Re-applied the fix; `prove -l tests/editor.t` now passes all 143 subtests, and running it a second time immediately after with no environment reset in between still passes with the real prefs file's mtime unchanged both times — confirms isolation holds both from the real machine and across repeated runs. Full suite: `prove -l tests/*.t` — 1136 tests, 41 files, all pass, no new stdout/stderr noise (the pre-existing "Wide character in print" warnings in `highlighter.t`/`input_parser.t`/`wrapmap.t` were confirmed present on unmodified code too, unrelated to this change).

**Interactive verification:** Built `./zepto`, ran via `hangon` with an explicit `--state-dir` pointing at a scratch dir: toggled Soft Tabs off via the command palette, quit, confirmed the scratch dir's `preferences.json` recorded `soft_tabs: ""` (off) and the real `~/.config/zepto/preferences.json` was byte-identical to a pre-test backup; relaunched with the same `--state-dir`, confirmed the palette showed `[off]` (persisted across restart); toggled back on and quit. Separately confirmed — via a small standalone script, `HARNESS_ACTIVE` unset — that `Zepto::Editor->new()` with no `state_store` and no harness resolves `base_dir()` to the real `~/.config/zepto` exactly as before the fix (end-user runtime behavior unchanged), without writing to it (mtime unchanged before/after).

**Docs:** Updated `CLAUDE.md`'s Testing Workflow example (`hangon start process --name zepto -- ./zepto ...`) to include `--state-dir /tmp/zepto-qa-state`, so anyone following the doc literally no longer risks the same real-prefs corruption this bug describes. QA: `QA-REG-162` in `qa/40_regression_bugs.txt` / `qa/scripts/tier1/reg_162_statestore_default_isolation.sh`.

### ~~P2: Mouse hover effects~~ FIXED
When moving the mouse over interactive elements (status bar pills, tab bar tabs, file tree items), highlight the hovered element with a visual effect.

**Fix:** Switched mouse tracking from `?1002h` (button-event) to `?1003h` (any-event) in Terminal.pm to receive motion events without button press. Added `MOUSE_MOVE` action to InputParser.pm. Editor.pm tracks hover state (`_hover_tab_index`, `_hover_pill_index`, `_hover_tree_row`) via `_handle_mouse_hover()` hit-testing against stored button positions. Renderer applies hover colors (brighter bg/fg) to hovered tabs, status bar pills, and file tree items. Only re-renders when hover target changes (not on every pixel of motion). Added hover theme colors (`tab_hover_*`, `pill_hover_*`, `tree_hover_*`) for both dark and light themes.

### ~~P2: Markdown table pretty-rendering~~ FIXED
When viewing `.md` files, render tables with continuous Unicode box-drawing lines (e.g. `─`, `│`, `┌`, `┬`), striped row backgrounds for readability, and column alignment. Do not add any extra rows — render the same number of rows as the source. When the cursor enters a table region, switch to raw source mode so the original pipe-delimited Markdown is visible for editing and copying.

**Fix:** Added `_detect_markdown_tables()` in Renderer.pm that scans visible lines for pipe-delimited table blocks, parses cells, computes column widths and alignment (left/center/right from separator row). `_render_table_line()` produces box-drawing output: header rows with bold text and highlighted background, separator rows as `├───┼───┤`, data rows with alternating stripe backgrounds. When cursor enters any table, that table reverts to raw source for editing. Copy always gets raw source (document model is never modified). Toggleable via `render_markdown_tables` preference (on by default). Added theme colors: `table_border_fg`, `table_header_bg/fg`, `table_stripe_bg` for both dark and light themes. Table detection is cached by content version for performance.

### ~~P3: Dim Markdown formatting delimiters~~ FIXED
In Markdown files, emphasis delimiters (`**`, `*`, `_`, `~~`, `==`) are rendered as `TOKEN_PUNCTUATION` in `Syntax/Markdown.pm`, giving them the same visual weight as the styled text they surround. The delimiters should be rendered much fainter (dimmed/low-opacity) so the bold, italic, strikethrough, and highlighted text pops out visually. This is how many modern Markdown editors handle it — the formatting chars become near-invisible while the styled content stands out. Currently all delimiter tokens share the generic punctuation color in `Theme.pm`.

**Fix:** Added a dedicated `TOKEN_FORMATTING_DELIM` token type (`Syntax/Base.pm`) distinct from `TOKEN_PUNCTUATION`. `Syntax/Markdown.pm` now emits it for the `**`/`__`, `*`/`_`, `***`/`___`, `~~`, and `==` delimiter pairs surrounding bold/italic/bold-italic/strikethrough/highlight text — no other punctuation (headings, list markers, blockquotes, code fences, link brackets, thematic breaks) is affected. Added `syntax_formatting_delim` color to both themes in `Theme.pm`: a faint blue-gray close to the dark bg (`fg_rgb(70,75,100)` vs `bg(26,27,38)`) and a faint light gray close to the light bg (`fg_rgb(200,203,212)` vs `bg(255,255,255)`) — both measurably closer to their theme's background than `syntax_punctuation`. No characters are hidden or concealed — only the delimiter color changes. Non-Markdown grammars are unaffected (e.g. Perl's `**` exponentiation operator still tokenizes as `TOKEN_OPERATOR`).

### ~~P2: Buffer word completion~~ ALREADY IMPLEMENTED
Popup a menu of matching words from open buffers on a trigger key (e.g., `Ctrl+N` or `Tab` in context). No external dependencies needed — just scan tokens from open documents. Covers 80% of what developers use autocomplete for (variable names, function names already typed once). Reduces typos and memory load for long identifiers.

**Verified 2026-08-29:** Fully implemented, and the shipped design exceeds this entry's ask — `lib/Zepto/Completion/CrossBufferWordProvider.pm` scans **every open tab's document**, not just the active buffer (cached per-document by `content_version`, rebuilt only when something changed; words from the active document get a proximity score bonus). Confirmed interactively via hangon: typed a distinctive identifier in tab A, switched to tab B, typed a 2-char prefix — ghost text suggested the tab-A-only word, and Tab accepted it into tab B.

Shipped trigger model (`lib/Zepto/Completion/Controller.pm`, orchestrated from `Editor.pm`):
- **Auto-trigger**: ghost text appears automatically after typing 2+ word characters — no dedicated key needed for the common case (this entry's suggested `Ctrl+N`/`Tab` triggers were never implemented as such; auto-trigger plus the existing `⌃Space` below covers the same need without demanding a key to memorize).
- **`⌃Space`**: dual-purpose — if the cursor sits immediately after a word character, it explicitly opens the dropdown menu (multiple candidates) instead of the command palette; otherwise it opens the palette. This is intentional, pre-existing behavior, not new.
- **`Tab`**: accepts the full ghost-text completion.
- **`→` (Right arrow)**: accepts one character at a time, keeping the rest as ghost text.
- **`↑`/`↓`**: navigate the dropdown menu; `Enter` accepts the highlighted item.
- **`Esc`**: dismisses.
- **`⌥[` / `⌥]`**: cycle ghost-text alternatives.

Other providers already merged into the same ranked result set: `KeywordProvider` (language keywords), `SnippetProvider` (multi-line templates, e.g. Python `def`), `PathProvider`, `RecentProvider` (recently-accepted completions get a score boost), and AI completion (separate opt-in provider, rate-limited).

No gap found — nothing to implement. Added `QA-CPLT-021` (cross-buffer path specifically; existing `QA-CPLT-001`–`020` covered same-buffer, dropdown, accept/dismiss/navigate, undo/redo, snippets, recent-pick, AI, the off-toggle, and paste-doesn't-trigger, but none exercised a SECOND open tab as the completion source).

### ~~P2: Session restore~~ FIXED
Reopen the editor and get back exactly where you were: same tabs, cursor positions, scroll positions. The recent files infrastructure already exists (`~/.config/zepto/recent_files`). Extending to full session state eliminates the re-navigation tax every time the editor is restarted. Especially important for a terminal editor that gets opened/closed frequently.

**Fix:** Added session save/restore to `Zepto::Editor`, keyed **per working directory** (not global) — a terminal editor gets opened from many different projects, and one global "last session" would fight between them. Storage: StateStore category `history`, new key `sessions` → `{ "<abs cwd>": { active_index, tabs: [{ file_path, line, col, scroll_line, scroll_col }, ...] } }`, alongside the existing `recent_files` and `cursor_positions` keys.

Design decisions:
- **Restore only on a truly bare launch** — no file args AND no directory arg. A directory arg (`zepto .`) is tree-focus mode, not "no arguments," and doesn't fight with the saved session.
- **Save is gated by the same "bare launch" condition as restore**, tracked via `Editor->{_session_eligible}` (set once in `init()`). This was **not** the first design — an early version saved unconditionally at quit, which meant a one-off `zepto some_file.txt`, or just running `zepto .` to browse the tree and quitting immediately, would silently overwrite or clear a real saved session. Caught via interactive testing before release; see `QA-REG-115`/`QA-REG-116`.
- **Only file-backed tabs are saved/restored.** Unsaved `[untitled]` buffers are skipped — persisting their content would mean snapshotting unsaved text into StateStore, a bigger and riskier feature than "remember where I was."
- **Files deleted since the session was saved are skipped individually** at restore (not an error, and doesn't abort the rest of the session).
- **Cursor and scroll are restored exactly**: cursor line/col reuses the existing `cursor_positions` clamp logic (factored into a shared `_clamp_position($doc, $line, $col)` helper used by both features); `scroll_line`/`scroll_col` are set directly on the `View` before `ensure_cursor_visible()`, so it only adjusts them if the saved viewport no longer fits (e.g. terminal resized) rather than always re-centering on the cursor.
- **Saved only at well-defined quit points** (Ctrl+Q, and closing the last tab, which also quits) — not on every tab switch or save. Those are deliberate, infrequent actions, so the StateStore write (flock + read + encode + rename) is cheap relative to them; wiring it into tab-switch would add that cost to a much hotter path for no real benefit over a clean-quit save. A crash without a clean quit loses the latest session, same pre-existing limitation as cursor-position history.
- **Preference-gated**: new `restore_session` pref (default on), persisted/synced like other global preferences. Discoverable via the command palette ("Restore Session on Startup", ⌃Space) per Rule 2 — no dedicated shortcut, following the same no-shortcut pattern as Auto Pairs/Auto Complete.

### ~~P2: Persistent config file~~ FIXED (was already mostly true)
Original text: "Save preferences to `~/.config/zepto/config.toml` (or similar) so they survive restarts... Without this, users can't persist their theme choice, tab width, minimap preference, etc."

**Audit finding: this was stale.** `StateStore` + `preferences.json` under `~/.config/zepto/` (honoring `--state-dir` / `$ZEPTO_STATE_DIR`, see `build.pl`) has persisted global preferences all along — theme, nerd font, minimap, auto-complete, auto-pairs, AI URL/model already round-tripped across restarts with a working palette command, verified interactively. The file is pretty-printed JSON, so it's already hand-editable — a second config system (e.g. `config.toml`) would have been needless duplication and was deliberately **not** added. `preferences.json` *is* the persistent config file; QA-PREF-014 now documents this instead of the stale "no config file yet" claim.

**What was actually missing** (verified with `hangon`: toggle → quit → relaunch with the same `--state-dir`):

| Preference | Persist-eligible before | UI before | Fix |
|---|---|---|---|
| `tab_width` | yes (in `GLOBAL_PREFS`) | **none** | Added "Tab Width" palette action (footer-input prompt, validates 1-16) |
| `soft_tabs` | yes | **none** | Added "Soft Tabs (Spaces)" palette toggle |
| `auto_indent` | yes | **none** | Added "Auto Indent" palette toggle |
| `mouse_enabled` | yes | **none** (only set at startup) | Added "Mouse" palette toggle; also enables/disables mouse mode on the live terminal |
| `search_wrap` | no (real effect, used by find-next/prev) | **none** | Added "Search Wrap Around" palette toggle; added to `GLOBAL_PREFS` |
| `render_markdown_tables` | no (real effect, used by table rendering) | **none** | Added "Markdown Table Rendering" palette toggle; added to `GLOBAL_PREFS` |

**Fix:** `lib/Zepto/Preferences.pm` (`search_wrap`, `render_markdown_tables` added to `%GLOBAL_PREFS`), `lib/Zepto/CommandRegistry.pm` (6 new commands: `set_tab_width`, `toggle_soft_tabs`, `toggle_auto_indent`, `toggle_mouse`, `toggle_search_wrap`, `toggle_markdown_tables`), `lib/Zepto/Editor/Commands.pm` (handlers). QA: `qa/scripts/tier1/pref_015..020_*.sh`, `qa/36_preferences.txt` (QA-PREF-015 through 020, rewrote QA-PREF-014). Also fixed `qa/scripts/tier1/pref_001_defaults.sh`, `wrap_001_toggle.sh`, `wrap_012_per_window.sh` — they searched the palette for the bare word "wrap", which now also fuzzy-matches "Search Wrap Around" and could grab the wrong toggle's on/off state; narrowed to the exact label "Word Wrap".

**Deliberately left alone (documented, not fixed — out of scope):** `theme`, `nerd_font`, `show_minimap`, `auto_complete`, `auto_pairs`, `ai_api_url`/`ai_model` already had working UI + persistence. `word_wrap` and `show_tree` are intentionally per-window/session state (see `Preferences.pm` header comment and `_effective_word_wrap`'s override-precedence design, confirmed by existing QA-PREF-012) — their palette toggles change the current window only, by design, and should not be made to overwrite the global default. See also the new vestigial-preference bug below.

### P3: Several defined preferences have no effect (dead/vestigial)
Audit of every key in `Preferences.pm` (2026-08-29, alongside the Persistent config file fix above) found preferences that are defined with defaults, covered by unit tests asserting their default value, but never actually read by any behavior:

- `show_line_numbers` — gutter is rendered unconditionally; the renderer never checks this pref.
- `show_status_bar` — status bar is rendered unconditionally; never checked.
- `confirm_quit_unsaved` — `cmd_quit`/`_prompt_close_dirty_tabs` always prompt on dirty tabs regardless of this pref's value; it's never read.
- `scroll_margin` — not referenced anywhere outside `Preferences.pm`; scrolling logic doesn't use it.
- `backup_on_save` — no `.bak`-file-writing code exists anywhere.
- `trim_trailing_whitespace` — `Document::save()` never trims trailing whitespace.
- `ensure_final_newline` — `Document::save()` unconditionally appends a trailing newline; the pref's value is never consulted (so today, "off" is actually impossible to achieve).
- `search_case_sensitive`, `search_regex` — these top-level defaults are never read; the live find/file-search state is tracked separately per session (`find_case` in Editor.pm, `_file_search_regex`, `_file_search_case`) and always initializes to a hardcoded `0`, not from these prefs.

These weren't added to the palette or `GLOBAL_PREFS` in the config-file fix above because there's no working behavior to expose or persist yet — doing so would be misleading (a toggle that visibly does nothing). Each one is either a genuinely unimplemented feature (implement the behavior, then add UI + persistence) or dead code that should be deleted. Needs a product decision on which.

### P3: Tab Width's validation-error pattern exposed a pre-existing dead-code bug in Go to Line
While adding the new "Tab Width" palette command, invalid input was (in the first draft) reported via `$self->{status_msg}`, which turned out to be a field the renderer never displays — errors vanished silently. Fixed in Tab Width by switching to `show_error_message()` (see QA-REG-120). `cmd_goto_line` (`lib/Zepto/Editor/Commands.pm`) has the exact same bug for its "Invalid format. Use: line, line:col, or :col" message — typing a malformed Go to Line input fails silently today. Not fixed here (out of scope for this task) — it's the only other `status_msg` writer in the codebase (`grep -rn status_msg lib/`), so this is the complete list.

### ~~P2: Shortcut key for Duplicate Down~~ FIXED
Duplicate Down currently has no keyboard shortcut — it's palette-only. Should have a direct keybinding for quick access. `⌃D` is taken (Select Next Occurrence). Candidates: `⌃⇧D` (Shift=reverse already used for Duplicate Up as `⌃U`, but `⌃⇧D` is intuitive as "duplicate" with Shift for the pair), or find another mnemonic. Also consider giving Duplicate Up a matching shortcut if it doesn't have one.

**Fix:** `⌃⇧D` was rejected after checking `InputParser.pm`: classic terminals deliver Ctrl+letter as a single control byte (0x01-0x1a, `_parse_control`), which can only ever set `modifiers => ['ctrl']` — there is no wire representation of Shift for it, so Ctrl+D and Ctrl+Shift+D are indistinguishable in most terminals (confirmed interactively — `hangon`'s own key vocabulary has no `ctrl-shift-*` combos for exactly this reason). Bound `⌥U` instead (Alt+letter survives reliably as ESC+char). `⌥U` pairs mnemonically with the existing `⌃U` (Duplicate Up) — same letter, "up" vs "down" modifier — and doesn't collide with any other Alt+letter binding. Duplicate Up already had `⌃U` from the original multi-cursor work, so no change was needed there. Added to `CommandRegistry.pm` (`dup_line_down` shortcut) and `Editor.pm::handle_alt_char`. QA: `QA-LINE-010`, `QA-REG-125`.

### ~~P3: Automatic dark/light mode~~ FIXED
Detect the system theme (dark/light) on startup and choose the matching editor theme. Detect when the system theme changes at runtime and automatically switch. Auto mode is optional — users can still manually set dark or light via `Ctrl+T` or config.

**Fix:** The `theme` preference is now three-valued: `'auto' | 'dark' | 'light'` (`Preferences.pm`, default stays `'dark'` — auto is opt-in). New `Zepto::ThemeDetect` module (Perl core only, no CPAN) detects the OS appearance:
- **macOS**: `defaults read -g AppleInterfaceStyle` via list-form exec (no shell interpolation) — key present + matches `/dark/i` → dark; absent (nonzero exit) or anything else → light, matching the command's own semantics.
- **Linux**: `gsettings get org.gnome.desktop.interface color-scheme` if `gsettings` is on PATH — `prefer-dark` → dark, else light.
- **Linux without gsettings, and any other platform**: inconclusive → falls back to `dark` (the existing default). A terminal OSC 11 background-color-query fallback was considered but **deliberately scoped out of v1**: the editor sets the terminal cursor color via OSC 12 in `Editor::init()` *before* raw mode is enabled (needed so cursor color is set before the alt-screen transition), which means the theme must already be resolved before raw mode is available — but a synchronous OSC 11 query/response round-trip needs raw mode active to read the reply without local echo/line-buffering interference. Reordering startup to accommodate the round-trip was judged too much startup-path risk for a P3 feature affecting a narrow audience (Linux desktops without GNOME/gsettings). Detection there just reports inconclusive, same as today.
- Every detection function accepts injectable collaborators (`platform`, `run`, `command_exists`) so `tests/theme_detect.t` and the `Zepto::Editor->new(theme_detect_fn => ..., theme_poll_supported_fn => ...)` test hooks never shell out.

`⌃T` design decision: pressing `⌃T` always switches to the explicit opposite of whatever theme is *currently effective* (`$self->{theme}->name()`, which is always a concrete dark/light name even under auto) — and since that sets an explicit preference, it **leaves auto mode**. Re-entering auto requires the dedicated "Theme: Auto" palette command. This was chosen over "⌃T cycles auto→dark→light→auto" because "give me the other look right now" is the far more common intent behind a manual toggle, and a silent hop back into auto (which could then immediately re-flip based on the system) would be surprising.

Runtime change detection: the idle branch of `Editor::run()`'s main loop calls `_maybe_poll_system_theme()`, which is a no-op unless the preference is `'auto'` **and** `Zepto::ThemeDetect::platform_supports_polling()` says the platform is cheap to poll (macOS always; Linux only if `gsettings` exists — never on Linux without it, since there's no signal to poll). When active, it re-detects at most once per 5 seconds (`THEME_POLL_INTERVAL_SEC`) and swaps the live theme (plus re-applies the OSC 12 cursor color) only if the detected value actually changed. No per-keystroke cost — this only runs on the input-timeout ("nothing typed") path.

Discoverability: palette gained three new commands — "Theme: Auto" / "Theme: Dark" / "Theme: Light" (VIEW section, `theme_set_auto`/`theme_set_dark`/`theme_set_light`) that jump directly to a mode. The existing "Theme" row (`⌃T`) now displays `[auto]`/`[dark]`/`[light]` and its icon dynamically reflects the actual mode (see QA-REG-139 below).

**Verified interactively** (this Mac, real system theme was Dark at test time, confirmed via `defaults read -g AppleInterfaceStyle`): selecting "Theme: Auto" from the palette resolved the editor to the dark theme, matching reality — screenshot evidence taken. `⌃T` from that state switched to explicit light and the indicator changed from `[auto]` to `[light]`; a second `⌃T` went to `[dark]`, confirming "leaves auto" and normal two-way toggling afterward. Selecting "Theme: Light" from the palette also switched immediately (white background, dark text).

**Files:** `lib/Zepto/ThemeDetect.pm` (new), `lib/Zepto/Preferences.pm`, `lib/Zepto/Theme.pm` (doc only), `lib/Zepto/Editor.pm` (`_resolve_theme_name`, `_theme_polling_supported`, `_maybe_poll_system_theme`, theme init/cross-instance-sync call sites, idle-loop poll hook), `lib/Zepto/Editor/Commands.pm` (`_apply_theme_pref`, `cmd_toggle_theme` redesigned, `cmd_set_theme_auto/dark/light`), `lib/Zepto/CommandRegistry.pm` (three new commands), `lib/Zepto/Chars.pm` (`theme_auto` icon), `lib/Zepto/Renderer.pm` (dynamic theme-row icon — see QA-REG-139), `build.pl` (bundling order). Tests: `tests/theme_detect.t` (new), `tests/editor.t`, `tests/preferences.t`, `tests/command_registry.t`. QA: `QA-THM-012` through `QA-THM-014` in `qa/29_themes.txt`.

---

## Existing bugs

### ~~P1: Minimap eats scarce width at narrow terminal sizes~~ FIXED
Found via direct screenshot inspection at narrow terminal widths (2026-08-30). At 40 columns, the minimap (the zoomed-out dot-pattern column on the right showing the file's density) still rendered, eating a meaningful fraction of the already-scarce width — crowding out document content and status bar pills that matter more — while providing little value at that scale (a small file's minimap is barely legible when zoomed that far out anyway).

**Root cause:** `Renderer::get_minimap_width` and the inline duplicate check inside `render()` only ever gated the minimap on whether there was still *dynamic* room left after gutter/tree width (`MIN_TEXT_WIDTH`, 10 cols) — there was no hard floor for "is a minimap even worth it at this width." At 40 cols, that dynamic check still comfortably passed (`text_width ≈ 27 >= 10`), so the minimap kept rendering all the way down to genuinely unusable widths.

**Fix:** Added `MINIMAP_MIN_COLS` (60) — below this terminal width the minimap auto-hides entirely, regardless of how much room the dynamic check would otherwise leave it. 60 was chosen relative to the codebase's other documented narrow-width floor: `docs/UI_GUIDELINES.md` calls out "~40 cols" as the point essential chrome (status bar, tab bar hints) must still survive down to; 60 sits a tier above that, matching the existing pattern of reserving the tightest widths for must-survive elements and dropping purely-supplementary ones (the minimap) earlier. This is a fully automatic behavior — no new user-facing toggle. The existing manual "Minimap" preference (⌥M / command palette) is unrelated and continues to work normally above the threshold (confirmed via `hangon`: toggling off/on at 80 cols still works after this change).

**Tests:** `tests/renderer.t` — `get_minimap_width accounts for tree_width` updated (its magic-number example crossed the new threshold, so it was rebased to cols=70/tree=55); new subtests `get_minimap_width returns 0 below MINIMAP_MIN_COLS even with plenty of room`, `Minimap auto-hides via full render at narrow widths (QA-REG-177)`, `Manual minimap preference still works normally above MINIMAP_MIN_COLS (QA-REG-177)`. QA: `QA-GUT-020` in `qa/27_gutter_ruler_minimap.txt`, `QA-REG-177` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_177_minimap_narrow_hide.sh` — verified it actually catches the regression by reverting the fix and re-running (correctly fails at 40 and 59 cols against unpatched code). Verified interactively via `hangon` at 80×24 (minimap present), 60×20 (present, inclusive boundary), 59×20 (absent, no layout glitch — the reclaimed column goes straight to document text), 50×18 and 40×15 (absent, status bar renders cleanly), with both a trivial (`a.txt`) and realistic (~15-20 char) filename.

### ~~P1: Status bar can overflow the terminal width and corrupt the screen when the multi-cursor or column-select indicator is active~~ FIXED
Found via direct PNG screenshot inspection at narrow terminal widths (2026-08-30) — real, confirmed screen corruption, not an LLM-vision guess. At 40×15 with a realistic filename and the file tree closed, growing the multi-cursor count (`⌃D` "select next occurrence" a handful of times, then typing to reveal the persistent indicator rather than the transient confirmation message) or extending a column-select rectangle (`⌥C` + arrow keys) could push the assembled status bar line past 40 columns. With nothing left to shrink it, the terminal soft-wrapped the overflow onto a phantom row below — an actual terminal scroll the app's fixed-position redraw didn't account for. The tab bar and ruler disappeared from view, and a bare, unstyled text fragment (e.g. `8 cursors`) appeared at the bottom, overlapping what should have been document content.

**Investigation note:** the bug report's original repro framing (realistic filename + tree-closed at 40×15) doesn't, by itself, reproduce — the document status bar's left segment is a cursor-*position* pill, not a filename pill (filenames only appear in the tab bar, which is unrelated). Interactive testing traced the actual trigger to two supplementary inline segments that get appended to that pill when active: the multi-cursor count (`N cursors`) and the column-select rectangle size (`COL n` / `COL n×m`). This is also why one early interactive attempt at the literal repro looked deceptively clean: `⌃D` also fires a transient "N cursors" *confirmation message* (`show_message`, already correctly bounded per `QA-REG-126`) that visually masks the persistent pill underneath until the message is dismissed by further input — a red herring that cost real debugging time before a synthetic width sweep against `_render_context_status_bar` directly (bypassing the message layer) proved the persistent pill itself was the unbounded one.

**Root cause:** `Renderer::_render_context_status_bar`'s document-context branch built the left segment (cursor-position pill + optional COL/multi-cursor text) and pushed it straight into the output buffer *unconditionally*, before the fixed-width `Commands ⌃␣` palette pill's width was even known. The only width-aware logic in the function — the `⌃`/`⌥` modifier-grouped pill-group budget — could correctly shrink to zero pills when space ran out, but by then the damage (an already-too-wide left segment, emitted as raw bytes) was done; there was nothing left downstream that could un-emit it.

**Fix:** The palette pill's width is now computed *first*, before the left segment, so the left segment can check its own budget against it. The COL and multi-cursor segments are each only emitted if adding them still leaves room for the cursor pill + round cap + palette pill + gaps within `$cols` — otherwise they're dropped entirely (not truncated mid-text), the same progressive-disclosure idiom `_fit_pill_group` already uses for the modifier-grouped pills. As a last-resort backstop for pathological cases (e.g. a very long single line pushing the column number into the thousands, or a huge line count), the cursor-position pill's own text is now ellipsized (via the existing `_ellipsis` helper already used for transient messages, `QA-REG-126`) if it alone would blow the budget. Per `docs/UI_GUIDELINES.md`, the `Commands ⌃␣` palette trigger must never be droppable by width or context — the fix preserves that; only the supplementary indicators degrade.

**Tests:** `tests/renderer.t` — new property-sweep subtest exercising `_render_context_status_bar` directly across ~5,000 combinations of terminal width (25-120 cols), multi-cursor count (0-60), column-select state, and nerd-font mode, asserting the rendered line's printable width never exceeds `$cols`; a companion sweep across four filenames (short and realistic lengths) × five widths × four heights asserting *every row* of a complete rendered frame stays bounded, not just the status bar. (Below ~25 cols the fixed-width `Commands ⌃␣` pill alone cannot fit alongside anything else — a pre-existing structural floor matching the codebase's documented "~40 cols" minimum for essential chrome, not a regression claimed fixed here; the sweep intentionally starts above that.) QA: `QA-SBAR-022` in `qa/26_status_bar.txt`; `QA-REG-178` (column-select) and `QA-REG-179` (multi-cursor) in `qa/40_regression_bugs.txt`; scripts `qa/scripts/tier1/reg_178_statusbar_colselect_overflow.sh` and `qa/scripts/tier1/reg_179_statusbar_multicursor_overflow.sh` — both verified to actually catch the regression by reverting the fix and re-running against the unpatched binary (both correctly detect the resulting scroll corruption / tab-bar disappearance; an earlier draft of each script that didn't specifically target the persistent-indicator path passed vacuously against the buggy code, which is itself now called out in the scripts' comments as a lesson for future editors of them). Verified interactively via `hangon` at 80×24, 60×20, 50×18, and 40×15 with both a trivial and realistic filename: column-select and multi-cursor indicators render inline and bounded, degrade to a dropped indicator (not corruption) at the narrowest widths, and the palette pill never disappears.

### P3: Undo can leave the cursor column past the end of the (now shorter) line
Found incidentally while interactively testing session restore (2026-08-29): type past the end of a short line (e.g. line is `line5`, type extra characters after it so the cursor sits at column 11), then Ctrl+Z. The text reverts to `line5`, but the cursor column stays at 11 — visibly past the end of the now-5-character line — until the next cursor-moving action (arrow key, Home/End, click) snaps it back in bounds. Not a crash or data loss; purely a transient visual/positional glitch. Not fixed here — out of scope for the session-restore work that surfaced it, and `Editor::_clamp_position` (added for session restore, shared with the pre-existing cursor-position-history feature) already defends downstream consumers of a saved cursor position against exactly this kind of out-of-range value, so it doesn't propagate into persisted state.

### ~~P2: Binary file tab looks editable~~ FIXED
When opening a binary file, there was no visual indication that the file was read-only.

**Fix:** Added a "READ ONLY" indicator segment in the status bar for binary files (Renderer.pm), styled with warning colors. The indicator renders as a pill between the file path and the middle fill area, using the same arrow-transition pattern as the column selection indicator. Added regression test.

### ~~P1: Incorrect cursor placement in Open File dialog~~ FIXED
When opening the file picker (`⌃O`), the terminal cursor was not aligned with the text input position. The cursor appeared offset from where typed characters actually rendered in the filter field.

**Root cause:** The cursor positioning code in `Renderer.pm` (line ~475) only applied the wide 120-column palette width for `find_in_files` mode, but the rendering code (line ~4139) applied it for `find_in_files`, `files`, AND `recent_files`. The file picker rendered at 120 columns wide while the cursor was positioned using the command palette width (60 or 80 depending on terminal width), causing a 20-40 column offset.

**Fix:** Added `files` and `recent_files` to the wide-width condition in the cursor positioning code, matching the rendering code exactly.

### ~~P1: Editor becomes sluggish when opening large files~~ FIXED
Opening a ~1MB / 13K+ line file caused the editor to become sluggish — slow tab opening, laggy cursor navigation, general unresponsiveness.

**Root cause:** Three compounding bottlenecks: (1) `vcs_change_status()` and `vcs_deletion_status()` in Document.pm used O(n) linear array scans, called for every visible line every frame. (2) Renderer.pm rebuilt VCS lookup hashes from scratch every frame. (3) Minimap.pm cache key included `undo_size`/`redo_size` which change every keystroke, defeating the cache and causing full minimap recomputation on every frame.

**Fix:** (1) Added `_rebuild_vcs_lookup()` in Document.pm that builds O(1) hash lookups once when the VCS diff is computed, not per-frame. `vcs_change_status()` and `vcs_deletion_status()` are now single hash lookups. (2) Renderer.pm now uses Document's cached hashrefs directly instead of rebuilding per-frame. (3) Minimap cache key uses `content_version` (incremented only on edits) instead of undo/redo sizes. Also added adaptive VCS diff debounce: 1.0s for files >5000 lines vs 0.3s for smaller files.

### ~~P1: File tree doesn't always expand to opened file~~ FIXED
When opening a file or switching tabs, the file tree should always expand to and select the corresponding entry. Previously didn't work reliably — the tree showed stale selection or collapsed parents after opening a file via file picker, recent files, or find-in-files.

**Root cause:** Two missing tree-update sites: (1) `_load_file()` in Commands.pm created new tabs via `add_tab()` without calling `set_current_file()`/`expand_to_path()`. (2) `_jump_to_location()` in Editor.pm called non-existent `switch_to()` on TabManager instead of using `_switch_to_tab()`, so find-in-files tab switching silently failed AND the tree never updated.

**Fix:** Added `set_current_file()` + `expand_to_path()` after `add_tab()` in `_load_file()`. Changed `_jump_to_location()` to use `_switch_to_tab()` which already includes tree reveal logic. Added 2 tests verifying tree updates after both code paths.

### ~~P1: [Usability] Global shortcuts should work from any state~~ FIXED
Several core shortcuts were swallowed when in find/replace (`⌃F`), footer input, or other modal states.

**Fix:** Extended the global shortcut intercept in `handle_event()` to cover 6 additional shortcuts beyond the existing ⌃Q/⌃S/⌃T: `⌃O` (Open File), `⌃W` (Close Tab), `⌃N` (New File), `⌃E` (Recent Files), `⌃Space`/`⌃⇧P` (Command Palette), and `⌃⇧F` (Find in Files). All close the current modal first via `_close_any_modal()`, then execute. `⌃Space` toggles the palette (closes if already open). Removed `_in_modal_state()` guards from `cmd_open_file`, `cmd_recent_files`, `cmd_find_in_files`, and `cmd_open_palette`. Updated tests to reflect the new behavior.

### ~~P1: [Security] Shell injection in VCS/Git.pm via backtick execution~~ FIXED
`VCS/Git.pm` constructs shell commands as strings and executes via backticks (`\`$cmd\``). While `_shell_quote()` is used for arguments, the `cd ... && git ...` pattern with string interpolation is inherently risky. Should use git's `-C` flag and list-form execution (`open()` with pipes) to eliminate shell interpretation entirely. Same pattern appears in multiple functions (~lines 80, 101, 132, 200).

**Fix:** Replaced all 5 backtick executions with a `_run_git()` helper that uses `open(FH, '-|')` + `exec('git', @args)` list-form execution (no shell interpretation). Added `_git()` instance method that prepends `-C <repo_root>` to avoid `cd && git` pattern. Removed the now-unnecessary `_shell_quote()` function. All git operations (version check, ls-files, show, status) now use safe list-form exec.

### ~~P1: [Security] Shell injection in Terminal.pm clipboard and command detection~~ FIXED
`Terminal.pm` uses backtick execution in two places: `paste_from_clipboard()` (line ~524: `` `$self->{_clipboard_paste_cmd} 2>/dev/null` ``) and `_command_exists()` (line ~487: `` `which $cmd 2>/dev/null` ``). While the command strings are currently hardcoded, backtick execution is unsafe by default. Should replace with list-form `system()` or `open()` with pipes.

**Fix:** Added `_safe_backtick()` helper that uses `open(FH, '-|')` + list-form `exec()` (no shell interpretation). Converted `_command_exists()`, `paste_from_clipboard()`, `stty size`, and `tput cols/lines` to use it. Changed clipboard command storage from strings to arrayrefs so `copy_to_clipboard()` and `paste_from_clipboard()` can use list-form `open()`/`exec()`. Updated test to use `is_deeply` for arrayref comparison.

### ~~P1: [Documentation] Stale references to deleted TODO.md~~ FIXED
`TODO.md` was deleted in commit `90a4c38` but is still referenced in `CLAUDE.md` (line 143, "Keeping Docs Current" table) and `docs/CODE_QUALITY.md` (line 31, "Remove from `TODO.md` if listed"). Anyone following the documented workflow will try to update a non-existent file.

**Fix:** Removed `TODO.md` row from the "Keeping Docs Current" table in `CLAUDE.md` and removed step 6 "Remove from `TODO.md` if listed" from the feature completion checklist in `docs/CODE_QUALITY.md`.

### ~~P1: [Documentation] UI_GUIDELINES.md palette sections are wrong~~ FIXED
`UI_GUIDELINES.md` says palette sections are "DOCUMENT, APP, NAVIGATE, TOGGLES" but the actual sections in `CommandRegistry.pm` are FILE, EDIT, NAVIGATE, VIEW, DIAGNOSTICS. The sections were reorganized (see P2 "Command palette re-org" FIXED entry) but the guidelines were never updated.

**Fix:** Updated line 61 in `docs/UI_GUIDELINES.md` from "DOCUMENT, APP, NAVIGATE, TOGGLES" to "FILE, EDIT, NAVIGATE, VIEW, DIAGNOSTICS" to match the actual `@SECTION_ORDER` in `CommandRegistry.pm`.

### ~~P1: [Performance] Character width computed per-character with no caching~~ FIXED
`_char_display_width()` in `Renderer.pm` (130+ lines of Unicode range checks) is called for every character on every visible line on every frame. For a 40-line, 200-column viewport that's ~160,000 function calls per frame. Should memoize by codepoint or use a lookup table.

**Fix:** Added memoization cache (`%_cdw_cache`) keyed by codepoint. Extracted range-check logic into `_compute_char_width()` which is only called on cache miss. Added fast path: printable ASCII (0x20-0x7E) returns 1 immediately without cache lookup, covering ~99% of typical source code characters.

### ~~P2: [Bug] Shift+Tab does same thing as Tab in find-in-files palette~~ FIXED
`Palette.pm` lines 85-90: both Tab and Shift+Tab call `_file_search_cycle_scope()` with no direction parameter. Shift+Tab should cycle backward through scopes but currently cycles forward, identical to Tab.

**Fix:** Added `$direction` parameter to `_file_search_cycle_scope()`. Shift+Tab now passes -1 (backward), Tab passes no direction (forward). With the current 2-scope setup (project, file dir) the visible behavior is identical, but the code is now correct for future scope additions.

### ~~P2: [Bug] Missing `use File::Spec` in Palette.pm~~ FIXED
`Palette.pm` line 286 calls `File::Spec->rel2abs()` but never imports `File::Spec`. It works by accident because `Editor.pm` imports it, but this is fragile and violates the module's own import conventions.

**Fix:** Already fixed in commit 4f3c5a0 (Find in Files). `use File::Spec;` is now at line 20.

### ~~P2: [Security] ReDoS vulnerability via user search input~~ FIXED
User-supplied regex patterns are compiled dynamically in `FindEngine.pm` (line ~455) and `FileSearchEngine.pm` (line ~268, ~449) via `eval { qr/$query/ }`. A crafted pattern like `(a+)+$` could cause catastrophic backtracking and freeze the editor. Should add regex complexity validation or a timeout mechanism.

**Fix:** Added 1000-character pattern length limit to `FileSearchEngine.pm` (matching `FindEngine.pm`'s existing limit). Also fixed `_find_match_in_content` to use the pre-compiled regex from `_perl_regex` instead of re-compiling from the query string on every line match — this also fixes the P3 "regex recompilation in inner loop" bug.

### ~~P2: [Security] Predictable temp file names in Document.pm atomic save~~ FIXED
`Document.pm` line ~138 uses `"$path.zepto.tmp.$$"` (PID-based) for temp files during atomic save. On multi-user systems this is predictable and vulnerable to symlink attacks (TOCTOU). Should use `File::Temp` for secure temporary file creation.

**Fix:** Replaced PID-based temp filename with `File::Temp::tempfile()` which creates files with unpredictable names via exclusive `O_EXCL` open, preventing symlink attacks. Temp file is created in the same directory as the target file (required for same-filesystem `rename`).

### ~~P2: [Performance] Renderer uses 381+ string concatenations in hot path~~ FIXED
`Renderer.pm` used 391 `$output .=` operations per frame. In Perl, repeated string concatenation triggers reallocation.

**Fix:** Refactored all 19 render methods from `$output .= EXPR` to `push @_out, EXPR` with `join('', @_out)` at return. 426 lines changed across all render methods including `_render_command_palette` (87 concat ops), `_render_context_status_bar` (63), `_render_tree_node_content` (32), `_render_dialog` (30), `_render_tab_bar` (28), and 14 others. Array accumulation avoids per-append reallocation — Perl's `join()` pre-calculates total size and allocates once.

### ~~P2: [Documentation] CODE_QUALITY.md "Open Items" are all resolved~~ FIXED
`docs/CODE_QUALITY.md` lines 173-180 lists four items as "Open" (unified input widget, global nav keys audit, theme contrast, mouse parity) but all four are marked FIXED or AUDITED in bugs.md. The audit list is stale and creates a false impression of outstanding work.

**Fix:** Removed the entire "Open Items" section from `docs/CODE_QUALITY.md` since all four items are resolved in bugs.md.

### ~~P2: [Documentation] README.md lists zero features~~ FIXED
README.md is 32 lines with no feature list despite the editor having command palette, 52-language syntax highlighting, file tree, find/replace, git diff, minimap, tabs, etc. This violates CLAUDE.md Rule 7 which says to update README when features change.

**Fix:** Added a "Features" section to README.md with 12 bullet points covering command palette, syntax highlighting, find/replace, find in files, file tree, tabs, git integration, minimap, view modes, themes, shell transform, and zero-dependency architecture.

### ~~P2: [Build] build.pl not in Makefile dependency list~~ FIXED
`Makefile` line ~53: `zepto: $(MODULES)` doesn't depend on `build.pl`. Changing the build script won't trigger a rebuild. Should be `zepto: $(MODULES) build.pl`.

**Fix:** Added `build.pl` to the dependency list: `zepto: $(MODULES) build.pl`.

### P2: [Architecture] Editor is a 6000-line god object across 3 files — SKIPPED
`Editor.pm`, `Commands.pm`, and `Palette.pm` all declare `package Zepto::Editor;` and inject 162 methods into a single class. The class directly manages event loop, file I/O, find/replace, command palette, dialogs, tabs, mouse handling, VCS, and more. No encapsulation boundary — any method can mutate any `$self` field. State transitions are ad-hoc string assignments with no validation.

**Skipped — 6000 lines, 162 methods, 929 tests touching `$editor` objects directly. Extracting subsystems (find/replace, dialog management, scroll handling) requires defining stable interfaces, migrating shared `$self` state to composition, and updating tests. Multi-session project. Recommended approach: extract one subsystem at a time (start with dialog/prompt/footer — most self-contained), validate tests between each extraction.**

### ~~P2: [Code Quality] Inconsistent error handling across commands~~ FIXED
`cmd_save` showed raw `$@` with Perl stack traces to users. `cmd_transform` stripped location info. `_load_file` showed "Error opening file: $@" with internal paths.

**Fix:** Added `_user_error($action, $@)` helper that strips Perl file/line info from `$@` and formats as `"$action: $reason"`. Applied to all 5 error paths: Save As, Save, file open, transform, and file reload (2 locations in Editor.pm). All errors now use `show_error_message()` for consistent styling. Format: "Save failed: Permission denied", "Could not open file: No such file or directory", etc.

### ~~P3: [Security] Terminal escape sequence injection via filenames~~ FIXED
`Terminal.pm` line ~540 sanitizes titles by stripping `[\x00-\x1f]` (ASCII control chars only). UTF-8 sequences or characters outside this range could potentially manipulate terminal state. Should consider a whitelist of allowed characters.

**Fix:** Extended the title sanitizer to also strip DEL (0x7F) and C1 control characters (0x80-0x9F), which can trigger terminal-specific escape sequences.

### ~~P3: [Performance] Tab bar geometry recalculated every frame~~ FIXED
`Renderer.pm` recalculated tab pill widths, progressive name truncation, and tab range visibility every frame — even when only the cursor moved.

**Fix:** Added class-level cache for `_render_tab_bar()` keyed on tab count, active index, terminal width, and per-tab state (name, dirty, VCS). Cache includes both the rendered string and button positions for mouse clicks. Returns cached result on hit, skipping all geometry computation.

### ~~P3: [Performance] VCS status checked per visible line per frame~~ FIXED
`Renderer.pm` called `vcs_deletion_status()` and `vcs_change_status()` for every visible line on every frame. These methods do linear array scans, resulting in O(visible × changes) per frame.

**Fix:** Pre-build `%vcs_change` and `%vcs_deletion` lookup hashes from `$doc->{_vcs_diff}` arrays once before the rendering loop. Per-line lookups are now O(1) hash access instead of O(n) array scans.

### ~~P3: [Performance] Palette filtering rescans all files on every keystroke~~ FIXED
`_filter_recent_files` and `_filter_all_files` iterated the entire file list and called `_fuzzy_score` twice per item on every keystroke.

**Fix:** `_filter_all_files` already had incremental substring filtering and a 5000-item scoring cap. Extracted shared `_build_file_item()` and `_fuzzy_rank_file_items()` helpers, reducing code duplication and consolidating the scoring logic. The recent files list is typically <50 items so no further optimization needed.

### ~~P3: [Performance] Regex recompilation in FileSearchEngine inner loop~~ FIXED
`FileSearchEngine.pm` line ~449: `_find_match_in_content` compiles the search regex via `eval { qr/$query/ }` on every per-line match check. Should pre-compile once at search start.

**Fix:** Fixed as part of the P2 ReDoS fix. `_find_match_in_content` now uses the pre-compiled regex from `$self->{_perl_regex}` instead of re-compiling via `eval { qr/$query/ }` on every line.

### ~~P3: [Code Quality] _filter_recent_files and _filter_all_files are 90% identical~~ FIXED
`Palette.pm` lines 205-315: two ~55-line functions with nearly identical item-building and scoring logic. Only the data source differs. Should extract to a shared `_filter_file_items()` helper.

**Fix:** Extracted shared `_build_file_item()` and `_fuzzy_rank_file_items()` helpers. Both `_filter_recent_files` and `_filter_all_files` now use these for item construction and scoring, eliminating the duplicated logic. Fixed as part of the P3 palette filtering performance fix.

### P3: [Code Quality] Display path normalization duplicated in 5+ locations — NO LONGER APPLICABLE
The pattern `if (index($path, "$cwd/") == 0) { substr(...) }` appears in `Palette.pm`, `FileSearchEngine.pm` (`_parse_lines` twice, `_tick_perl`), and elsewhere. Should be a utility function.

**Resolution:** After the palette filter refactoring (P3 palette dedup fix), only 2 occurrences remain — not enough to justify extracting a utility function.

### ~~P3: [Code Quality] State guard clauses copy-pasted 4+ times~~ FIXED
`Commands.pm` repeats the same 4-line guard block (`return if $self->{state} eq 'footer_input'` etc.) in `cmd_open_file`, `cmd_recent_files`, `cmd_find_in_files`, and `_column_paste`. Should extract to `_in_modal_state()` helper.

**Fix:** Added `_in_modal_state()` helper that checks for footer_input, prompt, find, and dialog states. Replaced the 4-line guard blocks in `cmd_open_file`, `cmd_recent_files`, and `cmd_find_in_files` with single-line `return if $self->_in_modal_state()`. Note: `_column_paste` did not have the guard pattern.

### ~~P3: [Bug] No user feedback for invalid goto_line input~~ FIXED
`Commands.pm` lines ~682-699: if the user enters something like `abc` or `1:2:3` in the Go To Line input, the function silently returns with no message. Should display an error or hint about expected format.

**Fix:** Added status message "Invalid format. Use: line, line:col, or :col" when the input doesn't match any valid pattern.

### ~~P3: [Documentation] DESIGN.md architecture diagram is stale~~ FIXED
The architecture diagram references "Commands/Menu/Preferences" module layout and doesn't reflect the current pill-based status bar, progressive disclosure, or the FILE/EDIT/NAVIGATE/VIEW section organization.

**Fix:** Completely rewrote the architecture diagram to show all 22 modules in their correct layers. Updated the module responsibilities table from 9 to 21 entries (added CommandRegistry, FindEngine, Highlighter, FileTree, FileSearchEngine, Diff, InputWidget, WrapMap, LineMap, Minimap, Chars, Config). Updated the data flow diagram to include FileTree, FindEngine, and Diff.

### ~~P3: [Documentation] Unverified "95%+ coverage" claim in DESIGN.md~~ FIXED
DESIGN.md claims "95%+ automated test coverage" but no coverage metrics exist. Several modules (`Config.pm`, VCS integration paths) have little or no direct test coverage.

**Fix:** Replaced unsubstantiated "95%+ automated test coverage" with "comprehensive automated testing" — accurate without making a specific claim.

### ~~P3: [Tests] Tautological tests verify messages not behavior~~ FIXED
`editor.t` tests like `cmd_undo` check that a status message is set but don't verify the edit was actually reversed. If `cmd_undo()` is broken but still sets a message, the test passes.

**Fix:** Strengthened the undo/redo test in `editor.t` to verify actual document state changes: insert text → verify document changed → undo → verify document reverted to original → redo → verify document restored to edited state. Previously only checked that status messages were set.

### ~~P3: [Tests] Performance tests with hard timing thresholds are flaky~~ FIXED
`find_engine_perf.t` uses `ok($median < 5, ...)` which will fail on slow CI or loaded machines. Should use `diag()` to report timing without failing the test.

**Fix:** Relaxed the two hard timing thresholds from 10ms to 50ms. The actual times are typically 1-4ms, so 50ms gives ample headroom for slow CI machines while still catching genuine regressions. Timing details continue to be reported via `diag()`.

### ~~P3: [Tests] No test for CommandRegistry consistency~~ FIXED
No test verifies that all commands have unique IDs, all shortcuts are unique, or all section names in `@SECTION_ORDER` are valid. If someone breaks CommandRegistry, all 33 commands silently disappear from the palette.

**Fix:** Added two new subtests to `tests/command_registry.t`: "All shortcuts are unique" (verifies no two commands share a shortcut) and "All command sections are in SECTION_ORDER" (verifies every command's section is valid). Note: unique IDs were already tested.

### ~~P3: [Repo Hygiene] Junk files not gitignored~~ FIXED
11 `perflog*.txt` files, `foo.txt`, and `lib/Zepto/goo.js` are untracked in the working directory. These should be `.gitignore`d to prevent accidental commits.

**Fix:** Added `perflog*.txt` and `foo.txt` to `.gitignore`. `lib/Zepto/goo.js` was not present in working directory (already removed).

## ~~P3: long filenames in open file dialog~~ FIXED
Long filenames bust out of the box. Actually it's kinda useful to use more of the screenspace, but it leaves screen artifacts. Also useful to widen the picker, like with find across files picker.

**Fix:** Widened Open File and Recent Files pickers to 120 chars (matching Find in Files). Long directory paths (shortcuts) are now truncated from the start with ellipsis to prevent overflow past the box border.

### ~~P1: Search should jump to first~~ FIXED
When searching for a string that's not currently in view, screen/cursor should jump to match.

**Fix:** Removed `skip_jump` from `_find_value_changed()` so typing in the find bar triggers `_find_nearest_match()` on each keystroke. For matches outside the viewport, the background search completion in the main loop now also triggers a jump when it finds new matches that weren't available during the synchronous viewport-only search.

### ~~P3: Transform feature~~ FIXED
I'd like the ability to use cmd line tools to transform fragments of text. For example, select some text, press transform, type "sort | uniq", and have the selected text replaced with the result of piping it through those process. If no text selected, auto select current line (or maybe entire doc, WDYT?). Also give option to put output in clipboard instead of replacing inline. Give hints in UI as to how to use the functionality. e.g. "sort | uniq", "tac", "python3 -m json.tool"

**Fix:** Added `⌥T` "Transform via Shell" command. Opens a footer input with hint showing example commands (`sort | uniq`, `tac`, `python3 -m json.tool`). Pipes the selected text (or current line if no selection) through `sh -c "$command"` via `IPC::Open2` and replaces inline. Registered in command palette under EDIT section. **Decision:** No selection defaults to current line (not entire doc) — more predictable and less destructive. Clipboard output option deferred — users can use `pbcopy`/`xclip` in the command itself.

### ~~P2: Syntax highlighting misaligned on lines with ⌥, ⚠, and similar Unicode symbols~~ FIXED
`_char_display_width()` used overly broad Unicode ranges (U+231A-23FF, U+2600-27BF, U+2B50-2B55) that returned width 2 for hundreds of narrow (EAW=N) characters like ⌥ (U+2325), ⚠ (U+26A0), ✔ (U+2714). These are width 1 in terminals. On lines with these characters (common in bugs.md keyboard shortcuts), syntax tokens were shifted right by 1 per such char, word wrap broke at wrong positions, and the minimap viewport alignment was off.

**Fix:** Replaced the three broad ranges with precise sub-ranges listing only the characters that are actually East Asian Wide (EAW=W/F) per Unicode. For example, the Misc Technical range (U+231A-23FF) now only matches ⌚⌛ (U+231A-231B), 〈〉 (U+2329-232A), ⏩⏪⏫⏬ (U+23E9-23EC), ⏰ (U+23F0), ⏳ (U+23F3). Added regression tests for both the wide and narrow characters.

### ~~P2: Smart sort~~ FIXED
Sort files in tree/search results by human friendly numbers, not ascii. e.g. file7.txt, file8.txt, file9.txt, file10.txt (10 after 7).

**Fix:** Added `_natural_cmp()` function that splits filenames into text and numeric chunks and compares numbers numerically. Applied to all four sort locations: FileTree `_scan_dir_one_level` and `_walk_for_files`, FilePicker `_discover_files` and `_apply_filter`.

### ~~P0: Slight lag on typing~~ FIXED
I notice it when typing and it's annoying. Figure out the bottleneck. Particularly visible when holding down a key to repeat chars.

**Fix:** Multiple optimizations across several commits: (1) Debounced `head_changed()` file I/O to every 2s and `check_external_changes()` stat to every 1s. (2) Made WrapMap incremental — only rebuilds when content version changes, with content-keyed cache for full rebuilds. (3) Added minimap caching keyed on content version. (4) Implemented differential rendering — Renderer returns per-row array, Editor diffs against previous frame and only emits changed rows to terminal. Reduced terminal I/O from ~27KB to ~1-2KB per frame for typical edits. Net result: char/none frame times dropped from ~55ms to ~45ms median (~18% improvement).

### ~~P1: New files dont appear in tree.~~ FIXED
Open zepto, see tree. Create new tab. Save it. New file should be visible in tree.

**Fix:** Added `$self->{file_tree}->refresh()` call after successful Save As in `cmd_save()`. The file tree's `refresh()` method re-scans the filesystem while preserving expand/collapse state, so the newly saved file appears immediately.

### ~~P3: Ruler does not extend to width of screen~~ FIXED
Currently it stops 1 char short of end of screen. Particularly visible in light mode as it's a black filler.

**Fix:** Swapped `RESET . CLEAR_LINE` to `CLEAR_LINE . RESET` in `_render_ruler_bar`. Same fix pattern as the earlier screen-width fix — `CLEAR_LINE` must happen before `RESET` so it erases to end-of-line using the ruler's background color, not the terminal default.

### ~~P1: Cursor off by one in palette filter~~ FIXED
The cursor position is 1 char to the right of where it should be in palette filter. Actually, it may be correct, and the text rendering
is 1 to the left. Shouldn't this be using the standard input text widget, and if so, how is just this one broken?

**Fix:** The cursor positioning in `render()` used `$pal_x + 5` but the filter text renders at `$pal_x + 4` (box border + space + icon + space = 4 chars before query text). Changed to `$pal_x + 4` to align cursor with text.

### ~~P2: Diff view discoverability~~ FIXED
When in diff view, make it visible on screen how to move to next/prev diff. If attempting to diff on a line that has no diff, jump to next one (if exists). Put a green/yellow/red/grey indicator in the diff view button on the status bar that matches diff status of where line is currently placed (grey is none). This is a subtle indicator of what this button's for to help users discover it.

**Fix:** Three changes: (1) The Diff View pill in the status bar now changes color based on the current line's VCS status — green (added), amber (modified), red (deleted), or default grey (no change). Added `pill_diff_added/modified/deleted` theme colors for both dark and light themes. (2) Pressing ⌥D on a line with no change now auto-jumps to the next change instead of showing "No change at cursor". (3) Next/Prev Change commands (⌥N/⌥P) remain accessible via the command palette for discoverability.

### ~~P3: Tree hide~~ FIXED
Ability to competely hide tree. Sometimes I really just care about editing a single file and want minimal screen clutter. e.g. a git commit msg. There should be a cmd to completely toggle it. If using ctrl-o to open a file, the sidebar should vanish once the file is opened (assuming tree is meant to be hidden). Make it clear in UI how to toggle the tree - should be visible at all times. Add cli options to force opening mode. If opening a single file from CLI, default to tree hidden.

**Fix:** ⌃B now toggles tree visibility (show/hide) instead of just focus. When tree is hidden and ⌃O is pressed, tree temporarily appears with filter for file picking, then auto-hides after file selection or Esc. Opening specific files from CLI defaults to tree hidden; no-args or directory launch keeps tree visible. Added `--no-tree` CLI flag and `ZEPTO_TREE=0` env var for explicit control.

### ~~P1: Incorrect cursor placement in command palette~~ FIXED
When opening command paletted, terminal cursor is not placed in text field

**Fix:** The cursor positioning code in the renderer used hardcoded width (60) and height (20) values that didn't match the actual palette rendering, which uses responsive widths (120/80/60) based on terminal width and dynamic height based on terminal rows. Synchronized the cursor positioning calculations to match the palette rendering dimensions exactly.

### ~~P1: Clicking document editor should unfocus file tree~~ FIXED
If navigating file tree, and user clicks in main editor area, unfocus tree and return to editing.

**Fix:** Added tree unfocus check at the beginning of the "Click in text area" section of `handle_mouse_event`. When the file tree is focused and the user clicks anywhere in the document area (gutter or text), `_tree_unfocus()` is called to cancel any preview, restore the original tab, and unfocus the tree. The view reference is also refreshed after unfocus in case the active tab changed.

### ~~P3: Toggle comment enhancements~~ FIXED
Support HTML which is both prefix and suffix. <!-- xxx -->. In HTML be aware of nested script or style and switch commenting char appropriately. Move the comment
definitions outside of Base.pm into their respective syntax files.

**Fix:** Three changes: (1) Moved comment prefix definitions from the centralized `%COMMENT_PREFIX` hash in Base.pm to individual `sub line_comment_prefix` overrides in each of the 42 syntax files. Base.pm now returns `undef` by default. (2) Added `comment_style($state)` API to Base.pm that returns `{ prefix => ..., suffix => ... }` — suffix is optional for line-prefix comments. HTML.pm overrides this for context-aware commenting: normal HTML uses `<!-- -->`, `<script>` blocks use `//` (JavaScript), `<style>` blocks use `/* */` (CSS). CSS.pm overrides to use `/* */` block comments (was incorrectly mapped to `//`). (3) Updated `cmd_toggle_comment` in Commands.pm to handle prefix+suffix block comments: inserts/removes suffix at line end and prefix at indentation, with correct offset handling (processes end-to-start).

### ~~P2: Scroll wheel cannot scroll more than a page~~ FIXED
When using scroll wheel, the doc offset scrolls, but gets stuck when the selected line hits top or bottom, preventing scrolling more than a page at a time.

**Fix:** The `_explicit_scroll` flag was being consumed (deleted) on a single render cycle, so the viewport snapped back to the cursor as soon as scrolling stopped. Changed the flag to persist across renders until a non-scroll user event occurs. The flag is now cleared at the start of `handle_event()` in Editor.pm — scroll events immediately re-set it via `scroll_up`/`scroll_down`, so it persists during scrolling but clears on any other action (typing, arrow keys, clicking). This allows unlimited scrolling away from the cursor, with the viewport snapping back only when the user takes a non-scroll action.

### ~~P2: "More" home/end~~ FIXED
Pressing home once on line should jump to first non-whitespace char (e.g. where code is indented). Pressing again should jump to start of actual line (in front of whitespace). Pressing one more time should jump to start of doc (line 1). Similar for End.

**Fix:** Smart Home cycles three states: first-nonws → col 0 → document start. Smart End cycles: line end → document end. Both work in normal and word-wrap modes. Also fixed `do_enter()` to set cursor position directly instead of using `move_to_line_start()` (which now has smart cycling that would send the cursor to doc start on empty new lines).

### ~~P3: Move forward/back~~ FIXED
Keep a history of major locations visited across files and within files. Many editors support something like this. Keyboard shortcuts to quickly move back forward throught location histor.

**Fix:** Added location history with `⌥-` (Go Back) and `⌥=` (Go Forward) shortcuts. Uses dual-stack model: back stack and forward stack. Location is recorded automatically before major jumps: Go to Line, Find Next/Prev, Next/Prev Change, and file opens. Each entry stores file path + line + col. Back navigation pushes current position to forward stack and pops from back stack. Forward does the reverse. New jumps clear the forward stack (new branch of history). Cross-file navigation switches tabs or reopens files as needed. History limited to 100 entries. Both commands registered in command palette under NAVIGATE section.

### ~~P2: Recent files~~ FIXED
Like ^O open, but list of recently visited files. Sorted by most recent first.

**Fix:** Added `⌃E` shortcut for Recent Files. Files are tracked when opened (via file tree, command line, or the recent files picker itself) and persisted to `~/.config/zepto/recent_files`. The picker reuses the command palette overlay with mode-specific title ("⌃E Recent Files"), fuzzy filtering, and file-type icons. Files are shown with filename as label and directory as secondary text. Most recently opened file appears first. Registered in CommandRegistry under FILE section.

### ~~P0: Reports of sluggishness~~ FIXED
Some users have reported a delay between typing and seeing results on screen. Hard to reproduce. Go explore and figure out likely cause.

**Fix:** Found three per-render bottlenecks: (1) WrapMap was unconditionally invalidated and rebuilt from scratch on every render, even when content hadn't changed — added `_content_version` counter to Document so WrapMap auto-detects changes and only rebuilds when needed. (2) `head_changed()` did file I/O (open + read + stat on `.git/HEAD`) on every render — debounced to every 2 seconds. (3) `check_external_changes()` did `stat()` on the active file every render — debounced to every 1 second.

### ~~P3: Lightmode glitches~~ FIXED
In lightmode. On short docs, the space beyond the final line is grey and looks out of place.

**Fix:** Changed light theme `empty_line_bg` from `bg_rgb(225, 228, 235)` (grey) to `bg_rgb(250, 250, 252)` (near-white) so empty lines beyond the document blend with the white editor background.

### ~~P3: Screen width~~ FIXED
The ruler, minimap, and bottom status bar all stop one char short of the end of the window. The tab bar does not. Ensure all reach end of window so entire screen is filled.

**Fix:** Swapped the order of `RESET` and `CLEAR_LINE` escape sequences in all rendering functions (text rows, status bar, find bar, footer input, prompt). Previously `RESET . CLEAR_LINE` cleared the styling first, then erased to end-of-line using the terminal's default background — causing any residual gap to appear in the wrong color. Now `CLEAR_LINE . RESET` erases first using the editor's current background color, then resets. Applied to 8 locations across the renderer.

### ~~P3: Status bar spacing~~ FIXED
No space between the Line number pill (first in status bar) and word wrap, whereas all others have spaces.

**Fix:** Added explicit gap space before the first center pill in the status bar, matching the spacing between other pills. Also adjusted the available space calculation to account for the extra space.

### ~~P2: Go-to-line new UI~~ FIXED
The status bar starts with a line number pill, and also has a go to line pill. Collapse these into a single element.
The line number pill (first), should also sho the ^G shortcut. When pressing this key, or clicking the pill, the line:col
string should become editable. Initially the entire text should be selected, allowing user to start typing and replace selection, or to move the cursor and edit existing. User may end XX, XX:YY, or :YY to move line, line and col, or just col (on same line) respectively - there should be text hints displayed to explain this. Use standard text input component used elsewhere. Ensure this box is wide enough to support docs of at least 9999:999. Beyond that, ok to scroll.

**Fix:** Merged the separate "Go to Line" pill into the cursor position pill. The pill now shows `⌃G` shortcut and is clickable. Pressing ⌃G or clicking the pill opens an inline input pre-filled with the current `line:col` (all selected, so typing replaces). Hint text shows "line, line:col, or :col" format guide. Input is 10 chars wide (enough for 9999:999 with scrolling for larger). The "Go to Line" command remains in the command palette for discoverability.

### ~~P3: Theme ^T should be global shortcut~~ FIXED
For example, should work when in find dialog.

**Fix:** Added `⌃T` to the top-level global shortcuts in `handle_event()`, alongside `⌃Q` and `⌃S`. Theme toggle now works from any UI state: find bar, command palette, footer input, dialog, and prompt.

### ~~P2: Comment/uncomment line~~ FIXED
Ctrl+/ should comment or uncomment the current line. If no text selected, current line. If text selected, all lines this selection spans. Language specific comments, e.g. # or // or <!-- .. -->. For languages that support multiline comment blocks, dont use this, only single lines (e.g. yes on //, no on /* .. */). Handle cases for mixed language documents (e.g. HTML with embedded CSS or JS).

**Fix:** Added `line_comment_prefix()` to `Zepto::Syntax::Base` with a lookup table covering all 42 syntax languages. `cmd_toggle_comment` in Commands.pm detects the language from the active highlighter's grammar, determines the line range (single line or selection), checks if all non-blank lines are already commented, and toggles accordingly. Comments are aligned at the minimum indentation of the selected lines. Wired to `⌃/` (Ctrl+/) and registered in CommandRegistry under DOCUMENT section.

### ~~P3: Close empty start tab when opening first file.~~ FIXED
A common scenario is: open zepto (which shows an untitled empty tab), then navigate to a file to edit. In this case, if the initial empty tab has not been edited, automatically close it to reduce clutter.

**Fix:** Added `_empty_untitled_tab_index()` helper that checks if a tab is empty, unedited, and has no file. When opening a file via `_load_file()` (⌃O, recent files, command palette) or confirming a tree preview (Enter), if the previous tab was an empty untitled tab, it's automatically closed. Edited untitled tabs are preserved.

### ~~P2: Line by line scrolling in editor.~~ FIXED
When using mouse scrolling (wheel or touchpad gesture), the file tree scrolls item by item, which feels precise and smooth. However the editor has different behavior which feels janky. Make editor mouse scroll behave same way as tree.

**Fix:** Changed editor mouse scroll from 3 lines per event to 1 line per event, matching the file tree's behavior.

### ~~P3: Diff view does not preserve line wrap~~ FIXED
If word wrap enabled, and diffing a hunk with long line, the word wrap is disabled in the diff, which is jarring. Preserve word wrap settings.

**Fix:** Three changes: (1) Removed the conditional in Editor.pm that disabled WrapMap when diff hunks were expanded — word wrap now stays active in diff view. (2) Added a combined WrapMap+LineMap entry-building path in Renderer.pm: when both are active, LineMap provides the entry ordering (doc lines + old/base lines from expanded hunks) while WrapMap provides word wrapping for each entry. Old/base lines are wrapped using `wrap_line()` and doc lines use `segments_for_line()`. (3) Updated `_render_old_line_row` to handle wrap segments — continuation rows get indent prefix with `↪` indicator, and content is sliced to the segment's visual range instead of the full viewport width. Gutter markers extend across all wrap continuation rows of old lines.

### ~~P2: Find/replace pills should be clickable~~ FIXED
Regex, case sensitivie, ok, cancel: mouse clicks should activate.

**Fix:** Already implemented — `handle_find_bar_click()` in Editor.pm computes click regions matching the renderer layout and handles clicks on all four pills: regex toggle, case toggle, cancel (Esc), and OK (Enter). Click regions are calculated from the same layout formula as the renderer to stay in sync.

### ~~P3: Column mode mouse selection~~ FIXED
After activating col selection mode, dragging with mouse should select col based selection, but it defaults to line.

**Fix:** Updated the drag handler's "start selection on first drag" logic to check `$view->column_select()` in addition to the Alt modifier. When column mode is already active (via ⌥C toggle), dragging now starts a column selection instead of a linear one. Alt+drag continues to start column selection from scratch as before.

### ~~P2: Line number indicator resizing~~ FIXED
The left pill constantly resizes as moving across lines due to empty lines (e.g. :60 -> :1). This makes the whole bar jiggle.

**Fix:** Added minimum width padding to the cursor position pill so it doesn't shrink below a reasonable size. The pill text is right-padded with spaces to keep surrounding pills stable.

### ~~P2: More prominent ctrl-space hint~~ FIXED
This is the most important key to know about, but it's hidden in corner, with no real clue as to what it means. How to make this obvious for first time users?

**Fix:** Added "Commands" label to the palette pill in the status bar. Previously showed only `{icon} ⌃␣` — now shows `{icon} Commands ⌃␣`. Updated in both document-context and tree-context status bars. The pill already uses a distinctive blue background that differentiates it from other pills.

### ~~P3: Command palette too wide.~~ FIXED
Doesn't need to be as wide and ends up with shortcut keys too far from respective action. Pick a reasonable max width.

**Fix:** Reduced palette max width from 120 to 80 columns at wide terminals (>=120 cols). Standard terminals (<120 cols) keep the 60-column max. Removed the 160-col breakpoint that created an overly wide 120-column palette. Shortcuts now stay close to labels at all terminal widths.

### ~~P2: Non-obvious tab keys~~ FIXED
Close tab, next tab, prev tab are common actions. Succinctly display these hints somewhere, maybe in tab bar.

**Fix:** Added right-aligned tab navigation hints in the tab bar's remaining space: `⌃W × ⌥, ← ⌥. →` showing close tab, previous tab, and next tab shortcuts. Hints only appear when there's enough room, using the same dim shortcut color as the per-tab ⌥N hints.

### ~~P2: Command palette re-org~~ FIXED
Organize by:
- File: tree, new, open, save, close, quit, next/prev tab, etc
- Edit: cut, copy, paste, move line up/down, duplicate up/down
- Navigate...
- View: minimap, nerd, wrap
- etc.
Where should find/replace go

**Fix:** Reorganized command palette from DOCUMENT/APP/NAVIGATE/TOGGLES to FILE/EDIT/NAVIGATE/VIEW. FILE: New, Open, Save, Close Tab, Quit, Next/Prev Tab, File Tree. EDIT: Undo, Redo, Cut, Copy, Paste, Select All, Move/Duplicate Lines, Toggle Comment. NAVIGATE: Find/Replace, Go to Line, Find Next/Prev, Next/Prev Change. VIEW: Word Wrap, Column Mode, Diff View, Minimap, Nerd Font, Theme. Find/Replace goes in NAVIGATE (it's a search/navigation action).

### ~~P2: Command palette rendering~~ FIXED
Highlighted row in command palette extends too far on right, overlapping border.

**Fix:** Reset background to `$bg` before rendering the right border `$box_v` on each item row. The selection highlight (`$sel_bg`) was bleeding into the border character because only `$border_fg` (foreground) was set.

### ~~P3: Nerd icon overhaul~~ FIXED
Re-evaluate current icon selection. Many duplicates. Pick familiar feeling icons for actions.

**Fix:** Audited all 52 icon definitions in Chars.pm. Found 3 duplicate codepoints: (1) NF_CLOSE (\x{f00d}) duplicated NF_TIMES — removed NF_CLOSE (was unused in %CHARS mapping). (2) NF_WRAP (\x{f0ea}) duplicated NF_PASTE — changed NF_WRAP to \x{f036} (fa-align-left, text lines icon). (3) NF_PALETTE (\x{f0c9}) duplicates NF_MENU — left as-is since both semantically represent the same hamburger menu concept. No other icon issues found; existing selections are appropriate for their actions.

### ~~P2: Fuzzy find text overflow~~ FIXED
Open fuzzy find with ^O and type long string - it overflows out of tree into main doc. Ensure its constrained to text box.

**Fix:** Two changes in Renderer.pm: (1) When query exceeds available width, show the tail of the string (`substr($query, -$max_query_width)`) so the cursor stays visible. (2) Cap cursor position to panel width so it doesn't escape beyond the border.

### ~~P2: Save changes prompt: more prominent~~ FIXED
Often when closign a tab, the save changes prompt appears at bottom, but it's hard to notice. Make this harder to miss, e.g. with
a intense background color. Also make yes/no/cancel into pill buttons with icons.

**Fix:** Replaced plain-text prompt with pill-style buttons on an amber/warning background. Added prompt-specific theme colors (`prompt_bg`, `prompt_fg`, `prompt_pill_*`) for both dark and light themes. Buttons now show icons: Save (floppy), Discard (✗), Cancel. Added warning icon (⚠) to Chars.pm. Updated all three prompt call sites (close tab, quit with dirty tabs, file changed on disk).

### ~~P0: New file Enter key puts cursor at beginning of current line instead of next line~~ FIXED
Create new doc, type a line of text on the last line (which for a new doc is also the first line), press Enter. Cursor jumps to beginning of current line, not next line.

**Fix:** Invalidate WrapMap after inserting newline so `move_down()` sees the updated line count. Root cause was stale WrapMap state when word wrap is active.

### ~~P0: File tree click on tab should unfocus tree and focus document~~ FIXED
When file explorer or file fuzzy find is focused, clicking on a document/tab should unfocus the tree and focus on the document.

**Fix:** Added tree unfocus + preview cleanup at the start of `handle_tab_bar_click()`. Any click on the tab bar area now returns focus to the editor.

### ~~P0: File tree preview hides for certain files~~ FIXED
When exploring files in the zepto src dir, moving cursor over `lib/Zepto/Editor.pm` and `Renderer.pm` hides the preview. Other files seem fine.

**Fix:** Used `File::Spec->rel2abs()` with the tree's root_path when checking file size for the preview limit. The `-s` operator was failing on relative paths. **Note:** Large files (>100KB) are intentionally skipped for preview — Editor.pm (111KB) and Renderer.pm (147KB) will now correctly show "no preview" instead of glitching. Manual test: navigate to these files in the tree and verify they don't cause the preview to disappear entirely.

### ~~P0: Saving one new file also saves another new file~~ FIXED
Open editor, create new file, create another new file. Save the second file with a name. The first file also seems to be saved.

**Fix:** After Save As, update the tab's `file_path` and clear `untitled_name` so the tab manager correctly tracks which file belongs to which tab. Root cause was Document getting a path but the Tab staying as untitled. **Manual test:** Create two untitled tabs, save tab 2 as "test.txt", verify tab 1 still shows as [untitled].

### ~~P0: Editor does not detect or reload externally changed files~~ FIXED
When a file open in zepto is modified outside the editor (e.g. by `git checkout`, another editor, a build script, or `save` from a second zepto instance), the buffer keeps the stale content with no indication that the disk version has changed. This leads to silent data loss: the user overwrites the newer external changes on the next save.

**Expected behavior — no local modifications (clean buffer):**
Silently reload the file from disk on the next focus/interaction. Restore the cursor to the same line and column (clamping if the file shrank). No prompt needed since there is nothing to lose.

**Expected behavior — local modifications (dirty buffer):**
Show a persistent status bar message (not time-based) such as:
`File changed on disk. [R]eload  [K]eep local  [D]iff`
- **Reload** discards local edits and loads the disk version (cursor restored best-effort).
- **Keep local** dismisses the warning and keeps the in-memory buffer. The next save overwrites the disk version.
- **Diff** opens diff view between the local buffer and the disk version so the user can decide.

The warning should reappear on every subsequent focus until the user chooses an action. It must not auto-dismiss.

**Detection:** Poll `stat()` mtime on each render cycle or input event (cheap). Compare against the mtime recorded at last load/save. No filesystem watchers needed for a minimal editor.

**Fix:** Added mtime tracking to Document (captured at load and save). On each render cycle, check if the file's mtime has changed. Clean buffers are silently reloaded with cursor restored. Dirty buffers show a prompt: `[R]eload [K]eep local`. Undo/redo stacks are cleared on reload. **Decisions:** Skipped `[D]iff` option from the original spec to keep the prompt simple — can add later. **Manual test:** Open a file, modify it externally (e.g. `echo "new" > file`), press any key in zepto — should reload silently if clean, or prompt if dirty.

### ~~P1: Diff gutter markers should extend across wrapped continuation lines~~ FIXED
When word wrap is enabled, diff gutter markers only appear on the first display row of a wrapped line. They should extend across all continuation lines.

**Fix:** Updated wrap_cont gutter rendering in Renderer.pm to check VCS change status for the underlying doc line and apply the same diff markers (added/modified/modified_whitespace). **Manual test:** Open a git-tracked file, make changes, enable word wrap — diff markers should now extend across all wrapped rows of changed lines.

### ~~P2: Mouse scroll in editor is janky compared to file tree~~ FIXED
When using mouse scroll wheel (macOS touchpad) in file tree it's buttery smooth, but in the editor it seems janky and skips lines, often gets caught in a loop.

**Fix:** Changed mouse scroll from `move_up()`/`move_down()` (cursor movement with viewport recalc) to `scroll_up(3)`/`scroll_down(3)` (viewport-only scrolling). This avoids moving the cursor and recalculating the viewport 3 times per scroll event. **Manual test:** Open a long file and scroll with the trackpad — should now be smooth, matching the file tree behavior.

### ~~P2: `^O` in fuzzy find search does not match status bar styling~~ FIXED
The `^O` label in the fuzzy file search does not match the visual styling of status bar pills.

**Fix:** Replaced all caret notation (`^O`, `^R`, `^C`) with compact glyph notation (`⌃O`, `⌃R`, `⌃C`) using `SYM_CTRL` constant from CommandRegistry. Updated in Renderer.pm for the file tree header, Find bar regex toggle, and Find bar case toggle.

### ~~P2: Don't show diff gutter markers in new files~~ FIXED
New untitled files show diff gutter markers even though there is no baseline to diff against.

**Fix:** In `_compute_vcs_diff()`, return early with `_vcs_diff = undef` when `_vcs_base` is undefined or empty. New untitled files have no VCS base content, so the diff computation is skipped entirely. **Manual test:** Create a new file (⌃N), type some text — no diff gutter markers should appear.

### ~~P3: Column selection should skip continuation lines when word wrap is enabled~~ FIXED
When word wrap and column selection are both enabled, column selection should skip over continuation lines (both mouse and arrow-based selections).

**Fix:** Updated `do_column_select_up/down` in Editor.pm to move by document line instead of visual row. Updated Renderer.pm `_render_line_with_highlights` to accept an `$is_wrap_cont` parameter — column selection rendering now skips wrap continuation rows entirely. **Manual test:** Enable word wrap (⌥Z) on a long file, enter column select mode (⌥C), use ⌥↓/⌥↑ — selection should skip continuation lines and select from real document lines only.

---

## UI guideline audit bugs

Bugs found by auditing the running UI against `docs/UI_GUIDELINES.md`.

### ~~P1: Time-based temporary messages violate "no time-based messages" rule~~ FIXED
**Guideline**: "No time-based temporary messages. Messages persist until user dismisses them or they are replaced by a newer message."

Multiple status bar messages disappear after ~3 seconds with no user interaction:
- "No change at cursor" (from Diff View toggle when no git changes)
- "Nothing to undo" (from Ctrl+Z when undo stack is empty)
- "Saved: README.md" (from Ctrl+S after successful save)

These should persist until dismissed by the user or replaced by a newer message.

**Fix:** Removed MESSAGE_DISPLAY_SEC timer. Messages now persist until the next user input clears them or a new message replaces them. **Decision:** Messages clear on any user input (keystroke or mouse) so the status bar returns to normal once the user takes any action.

### ~~P1: Esc does not open command palette as final fallback~~ FIXED
**Guideline**: "Esc priority: close palette, exit column mode, clear selection, collapse diff, open command palette (final fallback when nothing to cancel)."

When nothing is open (no palette, no selection, no column mode, no diff), pressing Esc does nothing. It should open the command palette as the documented last-resort fallback.

**Fix:** Added `cmd_open_palette()` call as the else-branch in the Escape key handler. Esc priority is now: exit column mode → clear selection → collapse diff → open command palette.

### ~~P2: Inconsistent shortcut notation — `^O`/`^R`/`^C` vs `⌃O`/`⌃R`/`⌃C`~~ FIXED
**Guideline**: "Use compact, single-glyph modifiers in UI labels: `⌃` for Ctrl, `⌥` for Alt, `⇧` for Shift, `␣` for Space. Use the same label format everywhere."

The tab bar shows `^O` (caret notation) instead of `⌃O`. The Find bar shows `^R` and `^C` instead of `⌃R` and `⌃C`. The status bar and command palette correctly use `⌃` notation. These should all use the same compact glyph format.

**Fix:** See "`^O` in fuzzy find search" fix above — same change covers all instances.

### ~~P2: Powerline toggle has no keyboard shortcut~~ FIXED
**Guideline**: "Every command has: a Nerd Font icon, a shortcut label, and a human-readable label."

In the command palette, "Powerline" shows `[on]` with no keyboard shortcut. Every other toggle (Theme, Minimap, File Tree, Word Wrap, Column Mode, Diff View) has a shortcut. Powerline is only accessible via the command palette with mouse or arrow navigation.

**Fix:** Added `⌥I` as the keyboard shortcut for Powerline toggle. Registered in CommandRegistry.pm (`shortcut => SYM_ALT . 'I'`) and handled in Editor.pm `handle_alt_char`. **Manual test:** Press ⌥I — should toggle Powerline on/off. Command palette should show `⌥I` next to Powerline.

### ~~P2: Command palette has no section headers~~ FIXED
**Guideline**: "Sections group commands in the palette: DOCUMENT, APP, NAVIGATE, TOGGLES."

The palette displays a flat list of 30 commands with no visible section headings or separators. Commands are loosely grouped by category but there are no "DOCUMENT", "APP", "NAVIGATE", or "TOGGLES" labels. This hurts scannability for users looking for a specific category.

**Fix:** When no filter query is active, section header rows are injected into the palette list (DOCUMENT, APP, NAVIGATE, TOGGLES). Headers render as dimmed label with horizontal rule fill. Arrow navigation skips headers automatically. Headers are removed when the user types a filter query (fuzzy matching only returns commands). **Manual test:** Open palette (⌃␣) — should see section headings. Type a letter — headers disappear. Backspace to clear — headers return.

### ~~P2: Minimap does not drop off at narrow terminal widths~~ FIXED
**Guideline**: "Layout adapts to constrained sizes using priority-based progressive disclosure: lower-priority status bar pills drop off first, then minimap, then file tree."

At 25 columns the minimap is still visible and consumes roughly half the editor area. The file tree drops off correctly, but the minimap persists at all widths. Per the guideline, minimap should disappear before the file tree.

**Fix:** Reversed the priority order in the layout calculation: tree width is now computed first (has priority to stay visible), minimap is computed second using remaining space. The minimap now correctly drops before the file tree at narrow widths. Updated in both Renderer.pm `render()` and Editor.pm word wrap width calculation. `get_minimap_width()` now accepts an optional `tree_width` parameter. **Manual test:** Open zepto, toggle file tree on, shrink terminal width — minimap should disappear first, then file tree.

### ~~P2: File tree status bar hints are plain text, not pills~~ FIXED
**Guideline**: "The status bar shows context-specific interactive pills. Every pill has: a Nerd Font icon, a label or value, a key shortcut — and is clickable."

When the file tree is focused the status bar shows plain text hints (`↑↓ nav  ←→ fold  Enter open  / filter  Esc back`) instead of styled pills with icons, rounded shape, and consistent padding. This is a different visual treatment from the DOCUMENT-mode status bar.

**Fix:** Replaced the plain text hint string with styled pills using the same rendering pattern as the document-context status bar. Each hint (↑↓, ←→ fold, ↵ open, / filter, Esc back) is now a separate pill with background color, rounded caps, and consistent padding. Pills drop off progressively if the terminal is too narrow. **Manual test:** Focus the file tree (⌃B) — status bar should show styled pills instead of plain text.

### ~~P2: `⌃⇧↑`/`⌃⇧↓` (Duplicate Up/Down) uses Shift for non-selection purpose~~ FIXED
**Guideline**: "Shift is only used with navigation keys to extend selection or reverse direction."

Duplicate Up (`⌃⇧↑`) and Duplicate Down (`⌃⇧↓`) use Shift+arrow to duplicate lines, not to extend a selection or reverse a direction. This contradicts the documented Shift modifier policy.

**Fix:** Changed duplicate line shortcuts to `⌃U` (duplicate up) and `⌃D` (duplicate down). Removed the `Ctrl+Shift+Arrow` bindings. Updated CommandRegistry.pm shortcut labels and Editor.pm keybindings. **Decision:** Chose `⌃U`/`⌃D` as mnemonic (U=up, D=down) and consistent with Ctrl+letter pattern. **Manual test:** Place cursor on a line, press ⌃D — should duplicate the line below. Press ⌃U — should duplicate above.

### ~~P3: Command palette does not use multi-column layout at wide terminals~~ FIXED
**Guideline**: "The palette adapts its layout (multi-column vs single-column) based on terminal width."

At 160 columns the palette remains single-column with the same width as at 100 columns. No multi-column layout is ever triggered.

**Fix:** Made palette width adaptive based on terminal width: 60 cols (standard), 80 cols at 120+ terminal width, 120 cols at 160+. Full multi-column layout was avoided as the 2D cursor navigation complexity outweighs the benefit. **Decision:** Single-column with wider box is simpler and still provides better use of space. **Manual test:** Open command palette at different terminal widths — palette should be wider at wider terminals.

---

## Open bugs

### ~~P2: Unified input widget missing~~ FIXED

Find bar, Go To Line, Save As prompt, and command palette filter are separate input implementations with inconsistent editing semantics. They should share a common input widget supporting: left/right, word left/right, home/end, select all, selection with Shift, cut/copy/paste, mouse click to place cursor.

**Guideline**: `docs/UI_GUIDELINES.md` → Inputs And Text Editing.

**Fix:** Created `Zepto::InputWidget` — a shared text input widget with full editing semantics. All three input surfaces (footer input / Go To Line / Save As, Find/Replace bar, command palette filter) now delegate to this widget. New features added to all inputs: Alt+Left/Right word movement, Shift+arrow/home/end selection, Ctrl+A select all, Ctrl+X cut, Ctrl+V paste (find bar keeps Ctrl+C as "toggle case" per its context-specific shortcut). Visual selection highlight is functional at the state level; selection-aware editing (replace-on-type, backspace/delete selection) works in all inputs. **Decision:** Mouse click cursor placement within input fields left as a P3 item (tracked separately). **Manual test:** Open find bar (⌃F), type "hello world", press Alt+Left — cursor should jump to "world". Press Ctrl+A — selects all. Open Go to Line (⌃G), type text, use Home/End/word movement — all consistent.

### ~~P2: Global navigation keys not audited across all UI states~~ FIXED

Core shortcuts (⌃Q, ⌃S, Esc) may not work from every UI state (dialogs, prompts, find mode, file tree, palette). An audit is needed to verify each one works from every surface.

**Guideline**: `docs/UI_GUIDELINES.md` → Navigation And Focus: "Core global shortcuts work in every UI state."

**Fix:** Added early interception in `handle_event()` — ⌃Q and ⌃S are now caught before routing to any state-specific handler, so they work in PALETTE, PROMPT, FOOTER_INPUT, FIND, and DIALOG states. Also removed the Esc-opens-palette fallback per user request (was triggering accidentally). **Manual test:** Open find bar (⌃F), press ⌃Q — quits. Open command palette (⌃␣), press ⌃Q — quits.

### ~~P3: Mouse parity incomplete~~ FIXED

~~Double-click word selection, triple-click line selection~~, and ~~mouse cursor placement inside input fields (find/replace, go to line)~~ are not implemented.

**Guideline**: `docs/UI_GUIDELINES.md` → Mouse And Keyboard Behavior.

**Fix (partial):** Added multi-click detection in the document area press handler. Tracks last click time, line, and click count. Double-click (within 400ms on same line) calls `select_word()` to select the word under cursor. Triple-click calls `select_line()` to select the entire line including newline. Click count cycles back to 1 after triple.

**Fix (complete):** Mouse cursor placement in input fields was already implemented for find/replace bar and footer input (Go to Line, Save As, Transform). Added the missing piece: command palette filter input now supports mouse click cursor placement via `get_palette_geometry()` in Renderer.pm and click detection in `_handle_palette_mouse()` in Palette.pm.

### ~~P3: Light theme `status_accent` used `bg_rgb` instead of `fg_rgb`~~ FIXED

`status_accent` in the light theme was defined with `bg_rgb(30, 102, 245)` — a background color escape sequence — when it is semantically a foreground accent color (consistent with the dark theme's `fg_rgb(125, 207, 255)`). Any future use of this color for text rendering would have produced an invisible or incorrectly styled result.

**Fix:** Changed to `fg_rgb(30, 102, 245)`. Added a regression test to `tests/theme.t` asserting that `status_accent` produces a foreground escape sequence (`ESC[38;2;...`) in the light theme.

### ~~P3: Theme contrast not verified~~ AUDITED — OK

Dark and light themes have not been formally audited for readability or contrast. Non-color cues (icons, text) for state changes (VCS markers, selection, errors) should be verified in both modes.

**Guideline**: `docs/UI_GUIDELINES.md` → Colors And Readability.

**Audit result:** Both themes pass contrast review. Dark theme uses light text (192,202,245) on deep blue-black (26,27,38) — excellent contrast. Light theme uses dark text (76,79,105) on white — excellent contrast. Syntax colors are deep/saturated in both themes for readability. Intentionally subdued elements (gutter line numbers, VCS indicator blocks) have lower contrast by design to avoid distraction. Non-color cues are present: VCS uses colored block shapes (▎), errors use warning icon (⚠), status bar uses text labels + keyboard shortcuts, selections use cursor position + background color.

### ~~P1: Shift+Alt+Left/Right should select by word, not column select~~ FIXED
Alt+Left/Right moves by word. The expected behavior for Shift+Alt+Left/Right is word movement with selection (standard across most editors). Instead, it triggers column selection mode. Column selection needs an alternative keybinding.

**Fix:** Removed all modifier-combo triggers for column selection from arrow handling. Column selection now works exclusively through toggle: press `⌥C` to enter column mode, then plain arrows extend the rectangular selection. Press `⌥C` or `Esc` to exit. In normal mode, arrows behave as standard: bare arrows move cursor, `Shift+Arrow` extends selection, `Alt+Left/Right` moves by word, `Shift+Alt+Left/Right` selects by word, `Alt+Up/Down` moves line. Also fixed a latent bug in `View::enter_column_mode` where `clear_selection()` was resetting `column_select` back to 0 (reordered so the flag is set after the clear). **Manual test:** `⌥C` then arrows → column rect selection shown in status bar as `COL RxC`. `Shift+Alt+Right` without column mode → word selection. `Esc` from column mode → exits column mode.

### ~~P3: Add Shift+Ctrl+D for duplicate line up~~ WON'T FIX
Ctrl+D duplicates the current line down. Shift+Ctrl+D should duplicate the line up — easy to remember since Shift is the "reverse direction" modifier.

**Resolution:** Terminals cannot distinguish `Ctrl+D` from `Ctrl+Shift+D` — both send byte `0x04`. This is documented in `docs/UI_GUIDELINES.md`: "Do not depend on `Shift+letter` or `Ctrl+Shift+letter`." Duplicate-up already exists as `⌃U` (mnemonic: U=up) paired with `⌃D` (D=down). Both are visible in the command palette under DOCUMENT section.

---

## UI guideline audit bugs

### ~~P3: Rename "Powerline" to "Nerd Font" throughout the codebase~~ FIXED
The feature that toggles Nerd Font glyph rendering is called "Powerline" everywhere — command palette label, preference key, variable names, CLI flags, comments, docs, and tests. The correct term is "Nerd Font" (Powerline refers specifically to the status line plugin whose glyph range is a small subset of Nerd Fonts). Occurrences span:
- **UI-visible**: command palette label (`Powerline`), `README.md` references, `UI_GUIDELINES.md`, `website/src/index.html`
- **Preferences/config**: `powerline` pref key, `--no-powerline` CLI flag, `ZEPTO_POWERLINE` env var
- **Code internals**: `Zepto::Chars` (`$_powerline_enabled`, `powerline_round_left/right`), `Zepto::Preferences` (`powerline`/`set_powerline`), `Zepto::CommandRegistry` (`toggle_powerline`), `Zepto::Editor::Commands` (`cmd_toggle_powerline`), `Zepto::Renderer` (many local `$powerline` variables and comments), `Zepto::Theme` (comments), `build.pl` (`$no_powerline`, `$powerline`)
- **Tests**: `tests/chars.t`, `tests/renderer.t`, `tests/syntax_rendering.t`

**Fix:** Renamed across all files: command palette label now says "Nerd Font", preference key is `nerd_font`, CLI flag is `--no-nerd-font` (with `--no-powerline` kept as backwards-compat alias), env var is `ZEPTO_NERD_FONT`, all internal variables/methods/comments updated. Also fixed a latent bug in Renderer.pm where `Zepto::Chars->get('powerline_round_left')` referenced a non-existent key (should be `round_left`). **Manual test:** Open command palette — should show "Nerd Font" not "Powerline". Run `./zepto --no-nerd-font` — should start without nerd font glyphs.

### ~~P1: [Bug] Ctrl+O file open doesn't unfocus file tree~~ FIXED
When launching zepto in directory mode (`./zepto .`), the file tree gets focus. After pressing Ctrl+O and selecting a file from the palette, focus remains on the file tree instead of transferring to the document. The status bar continues showing tree navigation hints instead of document editing pills.

**Fix:** Added tree unfocus logic to `_load_file()` in Commands.pm. After opening a file, if the file tree is focused, `set_focused(0)` is called to transfer focus back to the document editor.

### ~~P2: Markdown underscore emphasis renders inside identifiers~~ FIXED
Text like `NF_CLOSE (\x{f00d}) duplicated NF_TIMES` renders the substring between underscores as italic. Per CommonMark spec, `_` emphasis delimiters must not be intraword — an opening `_` must not be preceded by an alphanumeric character, and a closing `_` must not be followed by one. Only `*` allows intraword emphasis.

**Fix:** Split the combined `(\*|_)` emphasis regexes in Markdown.pm into separate `*` and `_` branches. The `_`, `__`, and `___` branches now check that the character before the opening delimiter and after the closing delimiter are not `\w` (word characters), matching CommonMark's intraword restriction. `*` branches remain unrestricted.

### ~~P2: [Bug] Binary files should not be previewed or naively opened~~ FIXED
Binary files (images, executables, .o files, etc.) currently get previewed in the file tree and can be opened as a tab, displaying garbage. Preview should detect binary content (e.g. NUL bytes in the first few KB) and show a "Binary file — cannot preview" message instead. Opening a binary file should show a read-only notice rather than dumping raw bytes into an editable buffer.

**Fix:** Added `_is_binary_file()` check in `Document::load()` that reads the first 8KB of raw bytes and looks for NUL characters. Binary files load a placeholder "(Binary file — size)" instead of the actual content. Insert and delete operations are blocked on binary documents. Save is blocked with "Cannot save binary file" error. Tree preview shows the placeholder. Pressing Enter on a binary file in the tree shows "Binary file — read only" status message. Added `_format_file_size()` helper for human-readable sizes.

### ~~P2: [Feature] Render images in terminal via Kitty graphics protocol~~ FIXED
On terminals that support the Kitty graphics protocol (e.g. Ghostty, Kitty), previewing or opening an image file (PNG, JPEG, GIF, BMP, SVG, etc.) should render the image inline in the terminal instead of showing binary garbage or a "cannot preview" message. Detect protocol support via the `TERM`/`TERM_PROGRAM` env var or a DA1/graphics query. Fall back gracefully to a text placeholder on unsupported terminals.

**Fix:** Added Kitty graphics protocol support to Terminal.pm: `supports_kitty_graphics()` detects support via `TERM_PROGRAM` (ghostty, kitty) and `TERM`/`KITTY_WINDOW_ID` env vars. `kitty_display_image()` transmits PNG/JPEG images using chunked base64 APC escape sequences (4096-byte chunks). `kitty_clear_image()` clears specific or all images. Image files are detected by extension (png, jpg, jpeg, gif, bmp, webp, svg, ico, tiff) on binary files. Editor renders images in the text area after the regular frame, with caching to avoid re-transmission when image/size hasn't changed. Images are cleared on tab switch and editor cleanup. Uses MIME::Base64 (Perl core module). Falls back to "(Image file — size)" placeholder on unsupported terminals.

### ~~P2: Syntax highlighting doesn't activate after Save As on new file~~ FIXED
Creating a new file and using Save As with a file extension didn't activate syntax highlighting.

**Fix:** Added `$self->active_highlighter()->set_file($filename)` in the Save As callback in `Commands.pm:65`, triggering grammar detection for the new filename. Added regression test.

### ~~P1: File picker (`⌃O`) doesn't find untracked files~~ FIXED
The Open File picker only showed git-tracked files. Untracked files (new images, scratch files) were invisible.

**Fix:** Added a second `git ls-files --others --exclude-standard` call in `FileTree::_build_all_files_list()` alongside the existing `git ls-files` for tracked files. Both results are combined. The two commands produce non-overlapping sets by design (tracked vs untracked-but-not-ignored).

### ~~P1: Native terminal paste (Cmd+V) causes cascading indentation~~ FIXED
When pasting multiline text from an external program using the terminal's native paste (Cmd+V), each line got progressively more indented due to auto-indent compounding.

**Fix:** Enabled bracketed paste mode. Added `enable_bracketed_paste()` / `disable_bracketed_paste()` to Terminal.pm (using the existing PASTE_MODE_ON/OFF constants). Added `paste_start` / `paste_end` key event detection in InputParser.pm for `\x1b[200~` / `\x1b[201~` sequences. Editor.pm tracks `_bracketed_paste` flag — `do_enter()` skips auto-indent while the flag is set. Added tests for both the escape sequence parsing and the auto-indent suppression.

### ~~P1: Pasting from system clipboard corrupts Unicode characters~~ FIXED
When pasting text containing non-ASCII characters (accented characters, CJK, emoji) via `⌃V`, the characters appear corrupted — multi-byte UTF-8 sequences are treated as individual bytes instead of proper characters.

**Root cause:** `paste_from_clipboard()` in `Terminal.pm:539-554` reads raw bytes from the clipboard command pipe (`pbpaste`, `xclip`, etc.) with no UTF-8 decoding. The copy direction (`copy_to_clipboard()`) correctly uses `utf8::encode()`, but the paste direction had no corresponding decode.

**Fix:** Added `binmode($fh, ':raw')` on the clipboard read pipe and `utf8::decode($text)` on the returned string, matching the encode/decode symmetry with `copy_to_clipboard()`. Added test verifying UTF-8 round-trip through the system clipboard (box drawing, emoji).

### ~~P1: Clicking previewed file content dismisses it instead of opening it~~ FIXED
When launching zepto with no args, clicking a file in the tree shows a preview. Clicking the previewed content in the main editor area dismissed the preview instead of confirming it.

**Fix:** Changed the document-area click handler in `handle_mouse_event()` to check for `preview_active` on the tree. When a preview is active, the click now confirms the preview (initializes VCS, cleans up preview state, closes empty untitled pre-preview tab) instead of calling `_tree_unfocus()` which cancelled it. Added regression test.

### ~~P2: [Bug] YAML syntax highlighting matches literals inside bare words~~ FIXED
In YAML files, substrings like `on`, `no`, `off` were incorrectly highlighted as keyword literals when inside unquoted bare words (e.g. `region`, `information`).

**Fix:** Added a bare word consumer rule `[a-zA-Z_][a-zA-Z0-9_.-]*` before the `$pos++` fallback in `Syntax/YAML.pm`. This consumes entire bare words in one go, preventing the tokenizer from creating substrings that partially match literals. Standalone literals (`on`, `true`, `false`) are still correctly matched since the `$LITERALS` check comes earlier. Regenerated YAML expected tokens. Added regression tests.

### P3: [Feature] Inline image rendering in Markdown preview — SKIPPED
On Kitty-protocol-capable terminals (e.g. Ghostty, Kitty), Markdown files containing image references (`![alt](path)`) should render the referenced images inline when the file is being previewed or edited. Images should be rendered at a reasonable size within the text flow. Fall back to showing the Markdown syntax as-is on unsupported terminals.

**Skipped — requires significant renderer architecture changes. Inline images interleaved with text need: (1) Markdown parser extension for `![alt](path)` tokens, (2) image row height calculation that displaces subsequent text rows, (3) per-image Kitty graphics ID management for multiple images on screen, (4) scroll-aware image repositioning. The P2 Kitty graphics fix handles whole-file image tabs, but inline images in flowing text is architecturally different. Recommend as a separate dedicated feature.**

### ~~P0: [Crash] Copying double-width characters crashes editor~~ FIXED
Copying text containing double-width characters (CJK, emoji) crashes with `Wide character in subroutine entry`. Reported crash in `copy_to_clipboard` when base64-encoding wide character strings for OSC 52.

**Root cause:** `MIME::Base64::encode_base64()` expects raw bytes, but `copy_to_clipboard()` passed Perl's internal wide-character strings directly. The pipe write to clipboard commands (`print $pipe $text`) had the same issue.

**Fix:** Added `utf8::encode()` to convert wide-character strings to UTF-8 bytes before passing to `encode_base64()` and the clipboard pipe. Added `binmode($pipe, ':raw')` on the clipboard command pipe. Added tests for CJK characters and emoji.

---

## Scorecard audit bugs (2026-03-06)

Bugs found by running `/scorecard` codebase audit.

### ~~P2: [Bug] `_char_to_visual_col()` doesn't handle wide characters~~ FIXED
`Renderer.pm:224` — increments `$visual_col` by 1 for all non-tab characters instead of calling `_char_display_width()`. Cursor positioning is wrong for lines containing CJK or emoji characters.

**Fix:** Replaced `$visual_col++` with `$visual_col += _char_display_width($char)` in both `_char_to_visual_col()` and `visual_to_char_col()`. Both functions now correctly handle CJK characters (width 2) and emoji. Added 15 tests covering CJK, emoji, and mixed ASCII+wide content in both directions.

### ~~P2: [Security] Symlink traversal in FileTree and FilePicker~~ FIXED
`FileTree.pm:123-547`, `FilePicker.pm` — `-d` and `-f` operators follow symlinks without `realpath()` bounds checking. A symlink inside the project directory could point outside the project root (e.g. `/etc/passwd`).

**Fix:** Added `_path_within_root()` helper to FileTree.pm that resolves symlinks via `Cwd::realpath()` and verifies the resolved path starts with the root. Applied to both `_scan_dir_one_level()` and `_walk_for_files()`. FilePicker.pm gets the same check in its `_discover_files()` walk. Root paths are resolved with `realpath()` at construction time. Symlinks that stay within the project root are preserved. Added test with escape symlink and safe symlink.

### ~~P2: [Security] ReDoS protection is length-only, no timeout~~ FIXED
`FindEngine.pm:455`, `FileSearchEngine.pm:296` — user regex patterns are compiled via `eval { qr/$pattern/ }` with a 1000-character length limit but no execution timeout.

**Fix:** Added `alarm(1)` (1-second SIGALRM) timeout around regex compilation in both `FindEngine::_compile_regex()` and `FileSearchEngine` startup. The alarm is cancelled on success and guaranteed cancelled on exception via a post-eval `alarm(0)`. Combined with the existing 1000-char length limit, this provides defense-in-depth against catastrophic backtracking.


### ~~P2: [DRY] Truncate-with-ellipsis duplicated 7+ times~~ FIXED
`Renderer.pm` — the ellipsis truncation pattern appeared 7+ times across tree nodes, palette items, and status bar elements.

**Fix:** Extracted `_ellipsis($str, $max_width, $mode)` helper supporting both end-truncation (default) and start-truncation (`'start'` mode). Replaced 5 of 7 occurrences — 2 remain where the truncation is interleaved with other calculations (`$trim_offset` tracking, `$ELLIPSIS` constant in progressive tab name truncation).

### ~~P3: [Bug] Scrollbar thumb boundary inconsistency~~ FIXED
`Renderer.pm` — one scrollbar rendering path used `<` (exclusive) while another used `<=` (inclusive) for `thumb_end`.

**Fix:** `thumb_end` is computed as `thumb_start + thumb_size - 1` (inclusive), so `<=` is correct. Changed the filter-flat tree scrollbar path to use `<=` to match the normal tree path.

### ~~P3: [Tests] Tautological test in terminal.t~~ FIXED
`terminal.t:346` — `ok(1, 'Kitty graphics detection exists')` always passed regardless of actual behavior.

**Fix:** Replaced with actual assertion: calls `supports_kitty_graphics()` and verifies it returns a defined 0/1 value. Note: `syntax_samples.t:120` and `syntax_samples.t:195` use `pass()` inside conditional branches (with `fail()` on the other branch) and are NOT tautological — the audit agent misidentified them.

### ~~P3: [Tests] Config.pm has no dedicated test~~ FIXED
`Config.pm` had implicit coverage through Document loading but no direct test file.

**Fix:** Added `tests/config.t` with 5 subtests covering `skip_directories()`, `skip_directories_hash()`, `max_files()`, `max_depth()`, and `picker_visible_rows()` — verifying both return types and default values.

### ~~P3: [Tests] Missing coverage for complex interactions~~ PARTIALLY FIXED
Palette header-skipping navigation now tested (5 new subtests in command_palette.t). WrapMap invalidation already well-covered (wrapmap.t:269-406). Mouse coordinate mapping and file tree preview→open→tab transitions skipped — require full integration test setup, not suitable for bug bash.

### ~~P3: [Documentation] TabManager.pm missing from DESIGN.md module inventory~~ FIXED
`DESIGN.md` module table omitted `TabManager.pm` and `FilePicker.pm`.

**Fix:** Added both TabManager and FilePicker to the Module Responsibilities table in DESIGN.md.

### ~~P2: [Bug] Light mode: tab bar stays dark after theme switch~~ FIXED
Switching from dark to light mode with `⌃T` leaves the tab bar rendered with dark theme colors. The tab bar appears visually dark against the light editor background.

**Root cause:** The tab bar cache in `Renderer.pm` (line ~722) builds its cache key from `$cols`, `$tree_width`, `$active_idx`, tab count, and per-tab state (display name, dirty flag, VCS changes) — but does not include the current theme. When the user toggles themes, the cache key is unchanged, so `_tab_bar_cache_get()` returns the stale dark-themed rendering.

**Fix:** Added `$theme->name()` as the first component of the tab bar cache key. Theme changes now cause a cache miss, triggering a full re-render with the correct theme colors. Added regression test verifying dark and light theme tab bars produce different output.

---

## TUI usability testing bugs (2026-03-23)

Bugs found during hands-on TUI usability testing via tmux session.

### ~~P1: [Usability] Enter in Find mode triggers Replace All — no separate find-only mode~~ FIXED
When opening Find with `⌃F`, the Replace field was always visible and pressing Enter always executed Replace All.

**Fix:** Restored find-only vs find-and-replace mode distinction per the spec. `⌃F` now opens find-only mode (no Replace field). Enter dismisses find and keeps cursor on current match. Tab activates the Replace field. Only when in Replace mode does Enter trigger Replace All. Added `↑↓` navigation hint to match count display. Added "Find and Replace" as separate command in palette. Updated renderer to conditionally show/hide Replace field and adjusted all click region calculations.

### ~~P2: [Bug] Auto-pair quote skip-over is disabled — typing closing quote adds duplicate~~ FIXED
Typing `"hello"` produced `"hello""` because quote skip-over was explicitly disabled.

**Fix:** Removed the `!_is_quote($char)` exclusion from the skip-over logic. For quotes, uses an odd-count heuristic: counts occurrences of the same quote character before the cursor on the current line. If the count is odd (cursor is inside an unclosed string), the closing quote is skipped over. If even (cursor is outside a string), a new quote is inserted normally. Brackets continue to always skip over.

### ~~P2: [Usability] Find bar text field doesn't clear or select-all on reopen~~ FIXED
Reopening `⌃F` kept previous text but didn't select it, requiring manual deletion before typing a new search.

**Fix:** `enter_find_mode()` now pre-selects all text in the find widget when reopening with a previous search term. Typing immediately replaces the selection (like VS Code).

### ~~P3: [Cosmetic] Find bar "$0" label: shown when regex off, and capture group replacement not discoverable~~ PARTIALLY FIXED
`$0` label appeared even when regex mode was off and there were no capture groups.

**Fix:** Capture group hints (`$0 $1 $2...`) now only appear when regex mode is ON AND the search pattern contains capture groups. Updated both the cursor positioning code and `_render_find_bar` in Renderer.pm. The hints use color-coded `$N` tokens matching the capture group colors in the find input. **Remaining:** A more explicit tooltip explaining how to use `$1` in the replace field would improve discoverability further.

### ~~P2: [Usability] Right arrow accepts entire ghost text completion — unexpected behavior~~ FIXED
Right arrow accepted the entire ghost text suggestion at once, which was unexpected (VS Code dismisses ghost text on Right arrow).

**Fix:** Changed Right arrow from accepting the entire ghost text to accepting one character at a time (like GitHub Copilot). Added `accept_char()` method to `Completion::Controller` that advances the prefix by one character while keeping the ghost active for the remaining text. When the last character is accepted, the completion is dismissed and recorded for RecentProvider. Tab continues to accept the full suggestion.

### ~~P3: [Usability] Ghost text completion does not re-trigger after undo~~ FIXED
After accepting ghost text and pressing `⌃Z` to undo, the ghost text did not reappear.

**Fix:** Added `_retrigger_completion_if_word()` helper that checks if the cursor is at a word character and sets `_completion_pending_at` to trigger the debounced completion. Called after both `cmd_undo()` and `cmd_redo()`. Ghost text now reappears after undo if the cursor position warrants it.

### ~~P0: [Bug] Perl warning on undo/redo near end-of-line~~ FIXED
`Use of uninitialized value $char_before in pattern match` printed to stderr after undo when cursor was at/past the line length boundary.

**Root cause:** `_retrigger_completion_if_word()` did not check that the cursor column was within the actual line length before calling `substr()`.

**Fix:** Added `return unless $col <= length($line)` guard and `defined $char_before` check.

### ~~P2: [Bug] history.json recent_files cluttered with temp files~~ FIXED
`_track_recent_file` in Editor.pm records every file opened — including temp files from test runs (`/tmp/...`, `/private/tmp/...`). The recent files list (max 50) gets filled with ephemeral files that no longer exist, pushing out real files.

**Fix:** Added early return in `_track_recent_file()` for paths matching `/tmp/`, `/private/tmp/`, and `/var/folders/` (macOS per-user temp). Added regression test. Updated existing tests to use non-temp paths.

### ~~P2: [Bug] Screen artifacts remain above cursor position after quitting~~ FIXED
When quitting zepto (`⌃Q`), everything above the cursor's vertical position remains visible on the terminal — the upper portion of the editor's alternate screen buffer content bleeds into the main screen.

**Root cause:** `leave_alt_screen()` in Terminal.pm only sent `ALT_SCREEN_OFF` (`\x1b[?1049l`). Some terminals don't fully restore the main screen buffer from the saved state, leaving alternate screen content visible.

**Fix:** Added `CLEAR_SCREEN` + `CURSOR_HOME` before `ALT_SCREEN_OFF` in `leave_alt_screen()`. This clears the alternate screen buffer before switching back to the main screen, so even terminals with imperfect `?1049l` handling show a clean exit.

### ~~P2: [Tests] diff_constraint.t spews debug output to console~~ FIXED
`tests/diff_constraint.t` prints `# Added: [...]`, `# Modified: [...]`, `# Deleted: [...]` lines to stdout during `make test`. These are debug/diagnostic prints left in the test, not TAP comments. They produce ~99 noise lines in the test output, making it harder to spot real issues.

**Fix:** Guarded the three `diag()` calls behind `$ENV{VERBOSE}`. Debug output now only appears when running with `VERBOSE=1 prove -v tests/diff_constraint.t`.

### ~~P1: [Bug] Undo of move-line corrupts buffer~~ FIXED
Moving a line with `⌥↓` or `⌥↑` then pressing `⌃Z` to undo corrupts the buffer — only one line remains visible, others disappear. Root cause: `_move_lines()` performs delete + insert as two separate undo actions; undoing only reverses the insert, leaving the delete in place.

**Fix:** Wrapped the delete and insert calls in `_move_lines()` with `$doc->begin_undo_group()` / `$doc->end_undo_group()` so the entire move is one atomic undo operation. QA-LINE-009 unskipped.

### ~~P2: [Bug] File tree Page Down/Up and Home/End don't trigger preview~~ FIXED
In the file tree, pressing Page Down, Page Up, Home, or End moves the cursor but doesn't show the preview of the newly highlighted file. Regular Up/Down arrows do trigger preview correctly. The `pageup`/`pagedown`/`home`/`end` handlers in `handle_tree_event()` (`Editor.pm:4215-4218`) call the tree navigation methods but omit `$self->_tree_preview_current()` which Up/Down include.

**Fix:** Added `$self->_tree_preview_current()` to all four handlers. QA-TREE-024 and QA-TREE-025 verify the fix.

## QA test suite discoveries (2026-05-03)

Bugs and observations found while expanding QA test coverage from 129 to 205+ scripts.

### ~~P3: Regex mode defaults to ON in find bar~~ FIXED
The find bar starts with regex mode enabled by default. Most editors (VS Code, Sublime, etc.) default to literal search. This means typing `foo.bar` matches `fooXbar` on first use, which is unexpected for most users. Toggle with ⌃R. Confirmed via QA-FIND-009.

**Fix:** `find_regex` now initializes to 0 in Editor.pm — literal search by default, ⌃R toggles regex on. The `qa/09_find_replace.txt` spec already described this behavior ("Without regex: literal `\d+` is searched"); only the code disagreed. Updated `tests/find.t` default assertion and `reg_049_find_regex_pipe.sh` (which assumed regex-on default; it now presses ⌃R first, preserving its original pipe-handling regression intent). All other find/replace QA scripts pass unchanged. Test: `reg_105_find_literal_default.sh` (QA-REG-105) — written first, verified failing ("3 of 3" via regex dot) before the fix.

### ~~P3: Find match counter not clamped when match count shrinks~~ FIXED
Noticed while writing QA-REG-105: with 3 matches and the cursor on match 3, toggling regex off (matches drop to 1) briefly shows "↑↓ 3 of 1" in the find bar — the current-match index isn't clamped to the new match count. Cosmetic; the next navigation normalizes it.

**Fix:** New `_clamp_find_current()` resets the index when it exceeds the new match count, called at both sites that replace `find_matches` without re-jumping (`_update_find_matches`, which the ⌃R/⌃C toggles use with skip_jump, and the background-search completion in `run()`). Tests: `tests/find.t` "find_current clamped when matches shrink" and `reg_107_find_count_clamp.sh` (QA-REG-107) — both written first and verified failing ("3 of 1" on screen) before the fix. Side discovery captured in the QA script: Enter in the find bar closes it; ↑↓ navigate matches.

### ~~P3: No "Save As" command in palette~~ FIXED
The command palette has "Save" (⌃S) and "Save and Close Tab" (⌃W) but no "Save As" / "Save to different location" command. File→Save As is a standard editor operation. Users can only save to the original path.

**Fix:** Added `cmd_save_as` (FILE section, no default shortcut) that always opens the footer input prompt — unlike `cmd_save`, which only prompts when the document has no path yet — prefilled with the document's current path (select-all active so retyping is quick). Confirms via `open_prompt` (Yes/No) before overwriting an existing file that isn't the document's own current path. On submit, writes via `Document::save()` (plain file I/O, no shell), updates the tab's `file_path`/`untitled_name`, and calls `active_highlighter()->set_file($filename)` to activate syntax highlighting for the new extension — same plumbing `cmd_save`'s inline "no path yet" flow already used, now shared via a `_finish_save_as` helper. **Security:** pure `open`/`rename`-based file I/O via the existing `Document::save()` path (already atomic: write to temp file, then rename) — no shell exec, no new attack surface; reviewed against `docs/SECURITY.md`.

**Bug found along the way:** while testing Save As with a long absolute path, the status bar message ("Saved: /very/long/path...") was never truncated to the terminal width in `Renderer.pm` (`_render_status_bar` and `_render_context_status_bar`). A message longer than the terminal width wrapped onto the next real terminal row, scrolling the whole screen and corrupting everything above the status bar (tab bar disappeared, ruler/gutter misrendered) until a forced full redraw. Not specific to Save As — any long `show_message`/`show_error_message` call could trigger it — but Save As surfaces it easily since users often save to long paths. **Fixed** by truncating the message with `_ellipsis($message, $cols - 1, 'start')` (truncate-from-start, matching the existing path-truncation convention elsewhere in Renderer.pm) at both message render sites. QA: `QA-FILE-*` (Save As), `QA-REG-126` (message truncation).

### ~~P3: Preference state persists between sessions~~ NO LONGER A TEST HAZARD
Toggle states (minimap, word wrap, nerd font, etc.) persist to preferences. This means QA tests that toggle features can affect subsequent tests. Tests must save and restore state. Not a bug per se, but a testing hazard worth documenting.

**Resolution (2026-08-29):** Persisting preferences is intended product behavior; the test hazard is gone since QA sessions run with a per-test `--state-dir` (QA-REG-106) — toggles land in an isolated temp dir, never in shared or real state.

### ~~P3: Transform (Alt+T) is shell-pipe only~~ FIXED
The transform feature (Alt+T) opens a shell command prompt. There are no built-in text transforms (uppercase, lowercase, sort, etc.) — users must type shell commands like `tr '[:lower:]' '[:upper:]'` or `sort`. This works but is not discoverable for users unfamiliar with Unix pipes.

**Fix:** Added 5 built-in, pure-Perl transforms in a new TRANSFORM palette section: Uppercase, Lowercase, Sort Lines, Reverse Lines, Unique Lines (first-occurrence order preserved, unlike shell `sort -u` which reorders). All operate on the current selection, or the whole document if nothing is selected — same auto-select-all scoping `cmd_transform` (⌥T) already uses. No shell exec: `cmd_transform_uppercase`/`cmd_transform_lowercase` call `_apply_text_transform`, a shared engine that reads the selected text, applies a coderef, and writes it back via `Document::replace()` (single undo entry; no-op — no undo entry, no dirty flag — if the transform doesn't change anything). `cmd_transform_sort_lines`/`cmd_transform_reverse_lines`/`cmd_transform_unique_lines` go through `_apply_line_transform`, which layers line-splitting on top (preserves whether the original text ended with a trailing newline). ⌥T / "Transform via Shell" is completely unchanged — still in the EDIT section, still shell-pipe. **Behavioral discovery along the way:** `⌃Space` is dual-purpose — if the cursor sits immediately after a word character, it's routed to the completion-trigger path instead of opening the palette (see `Editor.pm::handle_ctrl_char`, char `' '` case). This is intended, pre-existing behavior (not something this change touched), but it means interactive testing of a selection ending mid-word needs the cursor moved off the word boundary (e.g. `Home`, or extend the selection one more character past the word) before pressing `⌃Space`, or the palette won't open.

## Live debugging session (2026-08-28)

Reported by user while editing in Ghostty: keyboard cursor movement intermittently unresponsive, typing "really laggy" on small files, clicking the mouse un-sticks everything.

### ~~P0: Renders suppressed after any mouse motion — typed text and cursor moves invisible until next click~~ FIXED
`_last_event_was_hover` in Editor.pm is set by mouse events (`= 1` on motion, `= 0` on press/release/scroll) but **never reset by keyboard events**. After any hover-motion event with no target change, the main loop's render-skip branch (`Editor.pm` `run()`, ~line 702) stays active for ALL subsequent keyboard input: characters are inserted into the document and arrow keys move the cursor internally, but the screen never redraws. The next mouse press/scroll (or hover-target change) finally renders, revealing all the "missing" edits at once. With `?1003h` any-motion tracking enabled, merely brushing the mouse over the window arms this state, so it happens constantly in real use. (Side note: word characters looked merely "laggy" instead of frozen because the completion debounce fired a render ~100ms later; non-word characters and arrow keys never rendered at all.)

**Repro (verified in hangon session):** inject SGR motion `ESC[<35;30;5M`, then type `Z` → screen still shows old content, no modified indicator. Inject a click → `Z` appears (it was in the document all along). The render-skip decision uses only the *last* event's hover-ness instead of "did this batch contain anything render-worthy".

**Fix:** Replaced the last-event flag with a per-batch decision. `handle_input()` resets `_hover_changed`/`_batch_renderable` at batch start; `handle_event()` sets `_batch_renderable` for every event except idle hover motion; new `_input_needs_render()` returns true if the batch changed a hover target OR contained any non-hover event. `run()` consults that instead of `_last_event_was_hover` (now removed). The motion-flood optimization is preserved: batches of pure target-unchanged motion still skip rendering. Tests: `tests/editor.t` "Typing after hover motion still renders", QA `reg_101_hover_type_render.sh` (QA-REG-101, QA-MS-021) — both written first and verified failing against the unfixed build.

### ~~P1: InputParser stalls event queue after unknown/discarded escape sequences~~ FIXED
`InputParser::parse()` stops its event loop whenever `_parse_one()` returns `EVT_NONE`, but `EVT_NONE` conflates two cases: (a) incomplete sequence, need more bytes — correct to stop; (b) complete-but-unknown sequence already *consumed* from the buffer (`_decode_csi` unknown final, `_parse_csi` sanity limit, `_parse_ss3` unknown final, CSI-u codepoints outside 32–126) — wrong to stop. In case (b) any events already in the buffer behind the junk stay unparsed until the *next* input arrives, so keys lag one event behind (press Up → nothing; press another key → the Up fires).

**Repro (verified):** `parse("\x1b[I\x1b[A")` returns 0 events with 3 bytes stuck in the buffer; a subsequent `parse("x")` returns `key:up` + `char:'x'`.

**Fix:** In `InputParser::parse()`, on `EVT_NONE` the loop now continues when bytes were consumed (discarded junk) and stops only when the buffer is unchanged (truly incomplete sequence awaiting more bytes). Tests: 4 new subtests in `tests/input_parser.t` (unknown CSI/SS3/CSI-u followed by real events; incomplete sequences still wait), QA `reg_102_unknown_seq_stall.sh` (QA-REG-102, QA-EDIT-022) — all written first and verified failing against the unfixed code.

### ~~P2: Hover highlight paints one event late~~ FIXED (misdiagnosis — hover color was dimmer than bright pills)
Originally logged as "the render paints the previous hover state, one event late". Instrumenting `_handle_mouse_hover()` and the status bar paint proved that diagnosis **wrong**: hover state is hit-tested, stored, and painted in the same frame, correctly. The real bug: the flat `pill_hover_bg` (dark: rgb 62,69,100) sat *between* the pill category colors — brighter than toggle-off/action pills but **dimmer than toggle-on (52,79,138) and palette (86,119,252) pills**. Hovering a bright pill therefore DIMMED it, which reads as a de-highlight and mimics stale state (the pill "lights up" only when the mouse leaves and it reverts to its bright normal color). Light theme had the same inversion vs its lavender pills.

**Fix:** `pill_hover_bg/fg/edge` are now brighter than every pill category: dark rgb(110,140,255) with white text, light rgb(90,110,240) with white text. Tab and tree hover colors were audited and are correct (hover sits between normal and active). Tests: `tests/theme.t` asserts pill hover luminance exceeds all four pill category backgrounds (dark) and is visibly distinct (light) — verified failing against the old colors; tier-2 visual `ms_022_pill_hover_bright.sh` (QA-MS-022) plus QA-REG-104.

### ~~P0: QA suite commits junk into the real repository (sandbox escape in qa-helpers)~~ FIXED
`qa_project()` in `qa/lib/qa-helpers.sh` did its `cd` inside the function but every caller invoked it via command substitution — `dir=$(qa_git_repo)` — which runs in a subshell, so the `cd` was silently lost. The 10 scripts using `qa_git_repo` then ran `git init -q` (a silent no-op inside an existing repo), `git config user.name/email` (rewriting the REAL repo's local config to "Test <test@test.com>"), and `git add`/`git commit` **in the zepto checkout itself**. Every full `make qa` run stacked ~10 junk "init"/"initial" commits onto main, sweeping up whatever was in the working tree — this is also the origin of the historical "init/initial" commits in the repo's log, the leaked `test.txt`/test files (commit "Remove leaked test files"), and the polluted local git identity. The 9 scripts using bare `qa_project` similarly created their "project" files in the repo root instead of a temp dir, so several tree/picker tests were unknowingly running against the real repo.

**Found:** 2026-08-28, when three full QA runs added 30 junk commits on top of main mid-session (recovered via `git reset` to the pre-run commit; working tree was unaffected). Bisected by running each `vcs_*` script serially and watching `git rev-parse HEAD`.

**Fix:** `qa_project`/`qa_git_repo` now set `QA_PROJECT_DIR` instead of echoing it, and all 19 call sites (18 tier-1 + 1 tier-2) changed from `dir=$(qa_project)` to `qa_project; dir="$QA_PROJECT_DIR"`. Two guards make the mistake impossible to repeat silently: (1) qa_project aborts the whole script (`kill -TERM $$`) if called from a subshell — detected via `BASH_SUBSHELL`, since macOS bash 3.2 has no `BASHPID`; (2) `qa_git_repo` refuses to `git init` anywhere that is already inside a work tree. Repo damage repaired: branch reset to the last real commit, local `user.name`/`user.email` pollution removed. Test: `reg_103_qa_repo_isolation.sh` (QA-REG-103) builds a victim repo and asserts correct usage lands in the temp dir, legacy misuse aborts, and the victim stays byte-for-byte untouched — verified failing against the old helpers.

### ~~P2: A few QA scripts are flaky under full-suite parallel load~~ FIXED (root cause: session isolation never worked)
`edit_020_bracket_pair` failed in 3/3 full `make qa` runs but passes standalone; `ms_012_drag_tree_border`, `clip_009_paste_replaces`, `gut_012_minimap`, `col_005_column_cut` failed in some full runs only. The "slow renders under load" theory was only part of the story — failure screenshots from a full-detail run revealed **cross-test interference**:

1. **State-dir isolation was a no-op.** hangon sessions do NOT inherit the client's environment, so the `ZEPTO_STATE_DIR` that qa_setup exported never reached zepto (verified: `VAR=x hangon start -- sh -c 'echo $VAR'` prints empty). Every QA zepto ran against the user's REAL `~/.config/zepto` — tests polluted each other's prefs AND the user's actual editor settings. Smoking gun: `cplt_007_pair_off` toggles auto-pair off in the shared prefs, and `edit_020` (launching concurrently) reads them → screen literally shows `(` with no auto-close. Explains why edit_020 failed in *every* full run (alphabetical scheduling put them adjacent) but never standalone.
2. **System clipboard shared across parallel sessions (and with the user).** `clip_009`'s failure screen showed it pasting `aaaa/bbbb/cccc` — `col_005_column_cut`'s cut text. QA runs also clobbered the user's real clipboard on every copy test.
3. Secondary: fixed `sleep`-based waits genuinely flake under load, and `ms_012`'s measurement pipeline died under `set -e` when a grep matched nothing.

**Fix:** (1) Isolation now travels as CLI flags — `qa_start` passes `--state-dir "$QA_STATE_DIR"` plus new `--no-system-clipboard`; the three scripts that invoke `hangon start` directly were updated too. (2) New `--no-system-clipboard` flag (build.pl → Editor → Terminal) skips OSC 52 and pbcopy/xclip entirely so copy/paste use the internal per-process clipboard. (3) `qa_wait_screen`/`qa_assert_expect` helpers poll the rendered screen with a deadline (NOT `hangon expect`, which matches the raw escape-code stream where patterns like `()` never appear adjacent); edit_020, clip_009, ms_012, gut_012 rewritten onto them, and ms_012's pipelines guarded with `|| true`. Verified: pref-toggling test leaves the real `~/.config/zepto` mtimes untouched; two parallel sessions no longer share a clipboard. Test: `reg_106_session_isolation.sh` (QA-REG-106).

Note: months of QA runs may have already drifted the user's real `~/.config/zepto/preferences.json` (auto-pair/minimap/theme toggles) — worth a manual review.

### ~~P3: Remaining sleep-based QA scripts occasionally flake under full-suite load~~ FIXED (2026-08-29)
The 2026-08-28 isolation fixes eliminated the systematic cross-test failures, but a long tail of scripts still used fixed `sleep` + `qa_assert_screen` instead of the deadline-polling `qa_wait_screen`/`qa_assert_expect` helpers, occasionally flaking when the parallel suite starved a render.

**Migration result: 315 of 579 tier1 scripts (54%) now use `qa_assert_expect`/`qa_wait_screen`.** Done across several passes (one solo, then a 4-way parallel sweep over the full remaining directory, each agent assigned a disjoint file list). The other 264 scripts were surveyed and deliberately left on `qa_assert_screen`/fixed sleeps because they don't fit the mechanical polling pattern without weakening the assertion: `qa_assert_not_screen` checks (polling would invert their meaning), `qa_alive`/cursor-position/before-after-screen-equality comparisons, dual-branch fallback logic (`if X qa_pass else qa_pass "weaker claim"` — several of these were also tautological before-the-fact and are tracked separately, not by this item), and security tests where an agent judged the wait mechanism change risked altering what was actually being asserted. This is a legitimate stopping point, not an abandoned migration — forcing the remaining 264 would trade coverage for false confidence.

**Bugs found and fixed in the mechanical migration itself, via a full-suite verification run after merging (not caught by individual per-script testing, only by running everything together):**
- `reg_053_auto_pair_undo`: pattern `'\\(\\)'` (double-escaped) doesn't match literal `()` in ERE — should be `'\(\)'`. The original script used `grep -qF "()"` (fixed-string, no escaping needed at all); migrating to `qa_assert_expect` (which greps `-E`) required escaping parens, and one extra backslash was added instead of the needed single one.
- `prmt_002_discard`, `reg_037_multi_dirty_prompt`, `reg_046_palette_width`: original scripts used `grep -qiE` (case-insensitive) to match UI text like "Save changes to...?" against a lowercase pattern; `qa_assert_expect`/`qa_wait_screen` only grep `-E` (case-sensitive, matching `qa_assert_screen`'s existing behavior), so migrating away from `-i` without adjusting the pattern broke the match. Fixed by spelling out the actual capitalization with bracket expressions (`[Ss]ave`) rather than adding a new case-insensitive helper variant.
- Audited all 20 scripts whose pre-migration version used `-qi`; the 16 not listed above still pass because their specific patterns happened to be case-invariant (e.g., matching digits or already-lowercase rendered text) — verified individually, not assumed.
- `thm_014_ctrl_t_leaves_auto`'s single failure in the verification run was a transient `hangon` state-file corruption from concurrent load (many parallel QA-running agents hammering `~/.hangon/state.json` that day), not a script or migration bug — passes cleanly standalone and confirmed unrelated.

Full suite (579 scripts) green after these fixes. QA runner concurrency-safety (`QA-REG-108`, below) means future full-suite runs sharing this machine with other agents won't corrupt each other's hangon state.

### ~~P2: QA runner killed all hangon sessions on the machine~~ FIXED (2026-08-29)
`qa/runner.pl` ran `hangon stopall` before and after every suite run and deleted `~/.hangon/state.json` — fatal when multiple runners or concurrent agents share the machine's hangon server (each run killed everyone else's live sessions). Replaced with `cleanup_stale_qa_sessions()`: stops only `zqa_<pid>*` sessions whose owning script PID is dead. Test: `reg_108_runner_concurrent.sh` (QA-REG-108) — a live foreign session and a live zqa session survive a runner invocation; a stale one is reaped.

### ~~P1: InputParser mis-parses OSC escape sequences as Alt+']' + garbage keystrokes~~ FIXED (2026-08-29)
Found while building auto dark/light theme detection: `InputParser::_parse_escape()` had no case for `ESC ]` (the introducer for OSC — Operating System Command — sequences, e.g. a terminal's reply to a background-color query). It fell into the generic "Alt+key" branch, which only looks at the byte immediately after ESC: `]` (ord 93, within the 32–126 "printable" range the Alt+key branch accepts) was consumed as Alt+']', and every subsequent byte of the OSC payload and its terminator was then parsed one at a time as ordinary, unmodified character events. If focus was in the document, an unsolicited OSC reply from the terminal (which can arrive asynchronously — nothing requires the application to have just asked for it) would have been typed straight into the buffer as garbage text. This is the same failure class as QA-REG-102 (unknown/unrecognized sequences must be cleanly discarded, not misinterpreted as something else that leaks bytes downstream) — QA-REG-102 fixed the "stall" half of that contract; this fixes a "corruption" half that QA-REG-102's fix didn't cover, because OSC wasn't unrecognized-and-discarded, it was actively misidentified as a *different*, valid sequence (Alt+key) with content following it.

**Fix:** Added `InputParser::_parse_osc()`, dispatched from `_parse_escape()` before the generic Alt+key fallback whenever the second byte is `]`. It scans for a terminator — BEL (`\x07`) or ST (`ESC \`) — and consumes the whole sequence without emitting any character events (mirrors the existing "unknown CSI/SS3 discarded, parsing continues" pattern from QA-REG-102, so queued input behind an OSC reply is never stalled either). A capped scan (`OSC_MAX_LEN` = 512 bytes) discards a runaway/unterminated OSC body instead of buffering forever or wedging the parser. `flush_pending()` (the idle-timeout path that turns a lone `ESC` into the Escape key) got a matching case: a lone `"ESC ]"` with nothing following within the timeout — indistinguishable from the start of an OSC sequence until proven otherwise — resolves to Alt+']', preserving that as a legitimate keystroke. Tests: `tests/input_parser.t` (BEL-terminated, ST-terminated, split-across-reads, runaway body, the Alt+']' flush case — each verified failing against the pre-fix code first). QA: `QA-REG-138` (`reg_138_osc_no_corruption.sh`), verified failing against the pre-fix `InputParser.pm` before the fix landed.

### ~~P3: Theme palette icon didn't reflect actual dark/light state~~ FIXED (2026-08-29)
The `toggle_theme` command's `icon` field was hardcoded to `theme_dark` (a moon) with a comment claiming it was "dynamic: theme_dark or theme_light" — but nothing anywhere actually swapped it. The palette and status-bar pill showed a moon even in light mode, unlike the adjacent `[dark]`/`[light]` state text (via `get_toggle_display`), which was already correct. Found incidentally while adding the third `auto` state (which needed its own icon anyway, making the static-icon gap obvious).

**Fix:** Both icon-resolution sites in `Renderer.pm` (status bar pill, palette row) now special-case `$cmd->{pref} eq 'theme'` and pick `theme_auto`/`theme_dark`/`theme_light` from `CommandRegistry->get_toggle_state()`, the same source the state text already used. Added a `theme_auto` icon (`NF_ADJUST`, a half-filled circle) to `Chars.pm`. QA: `QA-REG-139` (`reg_139_theme_icon_reflects_state.sh`) — asserts the rendered Theme row's icon prefix (state-bracket text stripped) differs between dark and light modes; verified failing against the pre-fix code (identical prefixes in both modes).

### ~~P1: Light-theme tab "unsaved" dot has ~1.2-1.8:1 contrast, nearly invisible~~ FIXED (2026-08-30)
User-reported: in light theme, the unsaved-changes dot icon in the document tab bar is hard to make out against the tab background. `tab_modified_fg` (`fg_rgb(223, 142, 29)`, a light yellow) rendered against `tab_active_bg` (1.22:1), `tab_hover_bg` (1.57:1), and `tab_inactive_bg` (1.80:1) — all far below WCAG's 3:1 minimum for UI components. The dark theme's equivalent was fine (3.99-6.91:1 against the same three surfaces) — this was a light-theme-only regression, the color was clearly tuned by eye against a dark backdrop and never re-checked against light.

**Fix:** Darkened to a burnt-amber `fg_rgb(95, 40, 0)` — same warm hue family (still reads as "amber/orange dot"), but dark enough to clear 3:1 against all three tab-bar surfaces the icon can render on (active/inactive/hover), verified by direct WCAG contrast computation and by capturing the actual emitted ANSI bytes on a dirty tab (`38;2;95;40;0` on `48;2;114;135;253`).

**Infrastructure (the actual ask — prevent this class of bug systematically):** Added `tests/theme_contrast.t`, a WCAG 3:1 contrast audit over every themed fg/bg color pair in both themes, run automatically in `make test`. Pairing is inferred from naming convention (`X_fg`/`X_bg` siblings) for self-contained components; a small `%SURFACE_OVERRIDE` table handles roles that render on more than one background (e.g. this exact bug — a tab icon can sit on 3 different tab-state backgrounds) or on the base editor surface. This is a heuristic, not formal verification — documented in the test file's header, and extensible via the override table when a future role renders somewhere unexpected.

**First run surfaced 41 additional pre-existing violations** (see below) beyond the one reported — confirming this is systemic, not a one-off. These are tracked as `%KNOWN_DEBT` in the test (rendered as TAP `TODO`, visible in verbose output, never silently passing) so the new gate is live for all *future* colors without retroactively failing the build on undecided pre-existing debt. QA: `qa/scripts/tier1/reg_140_tab_modified_contrast.sh` (`QA-REG-140`).

### ~~P2: Pre-existing theme contrast debt found by tests/theme_contrast.t~~ FIXED (2026-08-30)
42 fg/bg pairs across both themes (15 dark, 27 light — not 41/26 as originally miscounted) failed the WCAG 3:1 UI-component contrast minimum, discovered by the `tests/theme_contrast.t` audit built while fixing the tab-modified-dot bug. All 42 are now fixed in `lib/Zepto/Theme.pm`; `%KNOWN_DEBT` in `tests/theme_contrast.t` is now empty (left as `my %KNOWN_DEBT = ();` rather than deleted, per the file's own convention, with a comment explaining why) and `prove -lv tests/theme_contrast.t` shows 79 genuine `ok`s across both themes with zero `TODO`s.

**Approach:** for each pair, lightened (dark theme) or darkened (light theme) the foreground within its existing hue family until it cleared 3.0:1 against every background surface that role can render on (some orphan roles like `tab_close_fg` render on 3 different tab-state backgrounds simultaneously — the fix had to satisfy the hardest of the three). Two roles whose fg was already at/near pure white and couldn't be brightened further (`status_pos_fg`, `dropdown_selected_fg`) were fixed by adjusting the background instead (`status_pos_bg`/`status_pos_edge` darkened as a matched pair; `dropdown_selected_fg` pushed to pure white, which was still enough headroom). A handful of roles that shared an identical RGB value for an explicit, commented design reason (`gutter_fg`/`ruler_fg`/`table_border_fg` — "matches gutter"/"like line numbers") were fixed to the same new shared value in each theme, rather than drifting independently.

**Notable finding — two roles are dead code:** `menu_active_fg` (light theme's 1.00:1 pair — fg literally identical to its own bg, the single worst ratio in the whole audit) and `menu_pill_fg` are both defined in `Theme.pm` but never consumed by `Renderer.pm` (confirmed via `grep -rn` across `lib/`) — the actual text color rendered inside those pills is `menu_active_text`/`menu_pill_text` (already fine, both white). So the "selected menu item's text is the same color as its own background" framing in the original report was inaccurate — no user ever saw that specific pair. Both were fixed anyway for correctness/consistency and in case they're ever wired up as real border/text colors, but the real user-visible "worst offender" is `dropdown_selected_fg/dropdown_selected_bg` (2.81:1, command-palette/dropdown selected-row text) — covered by `QA-REG-160`.

**Full before/after table** (theme: role, old ratio → new ratio, old RGB → new RGB):

Dark theme (15):
| Role / bg | Old ratio | New ratio | Old RGB | New RGB |
|---|---|---|---|---|
| `completion_border_fg` / `dropdown_bg`+`menu_bg` | 1.48 | 3.10 | (61,66,91) | (111,115,134) |
| `gutter_fg` / `gutter_bg` | 2.91 | 3.16–3.19 | (86,95,137) | (100,108,146) |
| `menu_pill_fg` / `menu_pill_bg` | 1.40 | 3.15 | (65,72,104) | (122,127,149) |
| `minimap_text_fg` / `bg` | 2.10 | 3.06 | (70,78,110) | (96,103,130) |
| `ruler_fg` / `ruler_bg` | 2.61 | 3.16–3.19 | (86,95,137) | (100,108,146) |
| `tab_close_fg` / active+hover+inactive `_bg` | 1.50 (worst) | 3.07+ | (100,106,134) | (156,160,178) |
| `tab_shortcut_fg` / `tab_active_bg` | 2.12 | 3.08+ | (120,130,170) | (152,160,190) |
| `table_border_fg` / `bg` | 2.76 | 3.16–3.19 | (86,95,137) | (100,108,146) |
| `tree_border_fg` / `tree_bg` | 1.80 | 3.23 | (61,66,91) | (100,104,124) |
| `tree_indent_fg` / `tree_bg` | 1.80 | 3.23 | (61,66,91) | (100,104,124) |
| `tree_scrollbar_fg` / `tree_scrollbar_bg` | 2.88 | 3.15 | (86,95,137) | (93,101,142) |
| `wrap_indicator_fg` / `bg` | 1.91 | 3.16 | (65,72,104) | (99,105,131) |

Light theme (27):
| Role / bg | Old ratio | New ratio | Old RGB | New RGB |
|---|---|---|---|---|
| `completion_border_fg` / `dropdown_bg`+`menu_bg` | 1.78 / 1.91 | 3.15+ | (172,176,190) | (127,130,141) |
| `completion_ghost_fg` / `bg` | 2.46 | 3.15 | (160,165,180) | (141,145,158) |
| `dropdown_selected_fg` / `dropdown_selected_bg` | 2.81 | 3.18 | (239,241,245) | (255,255,255) |
| `gutter_fg` / `gutter_bg` | 2.60 | 3.10 | (156,160,176) | (128,131,144) |
| `menu_active_fg` / `menu_active_bg` | **1.00** (worst overall; dead code) | 3.16 | (114,135,253) | (52,62,116) |
| `menu_pill_fg` / `menu_pill_bg` | 1.40 (dead code) | 3.16 | (172,176,190) | (110,113,122) |
| `minimap_text_fg` / `bg` | 2.19 | 3.07 | (170,175,190) | (143,147,160) |
| `ruler_fg` / `ruler_bg` | 2.14 | 3.10 | (156,160,176) | (128,131,144) |
| `status_modified_fg` / `status_bg` | 1.98 | 3.12 | (223,142,29) | (174,111,23) |
| `status_pos_fg` / `status_pos_bg`+`_edge` | 2.60 | 3.05 | bg/edge (156,160,176) | bg/edge (144,147,162) (fg unchanged, already white) |
| `tab_close_fg` / active+hover+inactive `_bg` | 1.22 (worst tab pair) | 3.09+ | (156,160,176) | (66,67,74) |
| `tab_shortcut_fg` / active+hover+inactive `_bg` | 1.11 | 3.05+ | (130,136,156) | (65,68,78) |
| `tab_vcs_fg` / `tab_active_bg` | 1.84 | 3.05 | (140,90,20) | (95,61,14) |
| `table_border_fg` / `bg` | 2.60 | 3.05 | (156,160,176) | (128,131,144) |
| `tree_border_active_fg` / `tree_bg` | 2.84 | 3.06 | (114,135,253) | (109,130,243) |
| `tree_border_drag_fg` / `tree_bg` | 2.84 | 3.06 | (114,135,253) | (109,130,243) |
| `tree_border_fg` / `tree_bg` | 1.93 | 3.12 | (172,176,190) | (134,137,148) |
| `tree_indent_fg` / `tree_bg` | 1.93 | 3.12 | (172,176,190) | (134,137,148) |
| `tree_scrollbar_fg` / `tree_scrollbar_bg` | 2.33 | 3.08 | (156,160,176) | (134,138,151) |
| `warning_fg` / `bg`+`status_bg` | 2.62 / 1.98 | 4.13 / 3.12 | (223,142,29) | (174,111,23) |
| `wrap_indicator_fg` / `bg` | 1.82 | 3.11 | (188,192,204) | (143,146,155) |

(`status_modified_fg` and `warning_fg` intentionally share one new value — they were already the same amber and both needed the same fix.)

**Verification:** `prove -lv tests/theme_contrast.t` — 79/79 checks pass, zero `TODO`s, both subtests green. `make check`, `make build`, `make test` all pass with zero noise (`1111` tests, `Result: PASS`). Interactive verification via `hangon` across both themes covering gutter/ruler numbers, tab bar (dirty dot, close icon, shortcut hint on active/inactive/hover), file tree panel, command palette / dropdown selected-row text, and completion ghost text — all read correctly, still recognizably the same muted/subtle hue family as before, not garish. QA: `qa/scripts/tier1/reg_160_dropdown_selected_contrast.sh` (`QA-REG-160`, the real "worst offender" — selected palette-row text) and `qa/scripts/tier1/reg_161_tab_close_shortcut_contrast.sh` (`QA-REG-161`, tab close/shortcut icons on the active tab, the worst *live* tab pair at 1.11–1.22:1), alongside the pre-existing `QA-REG-140`.

**Incidental fix:** `tests/syntax_rendering.t` had a stale assertion (`Comment color (gray) found in output` checking for raw bytes `38;2;86;95;137`) that was never actually testing `syntax_comment` (dark theme's real value is `fg_rgb(150,175,200)`) — it was coincidentally matching `gutter_fg`'s old shared muted-blue-gray value, which also appears in the same combined render output via the line-number gutter. Changing `gutter_fg` broke this mislabeled assertion; fixed the test to check the actual `syntax_comment` color it was always supposed to verify.

**Incidental finding — see new bug below (not fixed here, out of scope for a color-values task).**

### P2: Stale-theme partial redraw after theme change or panel toggle (2026-08-30, not yet fixed)
Found incidentally while interactively verifying the contrast fixes above with `hangon` — not caused by, or related to, the color-value changes themselves (confirmed: a subsequent full repaint always shows the *correct* new-theme colors, proving the underlying theme data is right).

Reproduced twice:
1. Switch theme (e.g. dark → light via the command palette's "Theme: Light"), then open the file tree (`⌃B`). The tree panel renders using the *previous* theme's colors (e.g. still dark-navy background/text) while the main editor pane correctly shows the new theme — a visible split down the middle of the screen. Confirmed NOT a screenshot/capture artifact: reproduced 3 times across separate screenshots with settle time in between, and resolved instantly once any dialog (e.g. the command palette) is opened and closed, which forces a full-screen repaint.
2. Open a new empty/`[untitled]` tab (`⌃N`) in light theme: the single content row renders correctly (light bg), but the empty rows below it render dark instead of `empty_line_bg`'s light value — again fixed by any action that forces a full repaint.

Both point to the same root cause: some code path that invalidates/repaints on theme change or tab/panel switch is only repainting the region it thinks changed, not the whole screen, leaving stale previous-theme pixels in untouched regions until an unrelated full-repaint event (opening a dialog) papers over it. Not investigated further — likely in `Renderer.pm`'s dirty-region tracking or wherever `cmd_toggle_theme`/tab-creation triggers a redraw. Cosmetic (self-correcting on the next full repaint) but visible and worth a dedicated fix; flagging for the next bug-bash pass rather than fixing here, since this task's scope was `Theme.pm` color values only and this is a `Renderer.pm` invalidation-logic bug.

### ~~P1: Discoverability Contract gaps found by manual visual sweep (2026-08-30, not yet fixed)~~ FIXED (2026-08-30)
While building `docs/UI_GUIDELINES.md`'s new "Discoverability Contract" section (user-requested: at all times, the most relevant actions and shortcuts should be visible on screen, including core navigation — not just document-editing commands — with a clear fallback for anything that doesn't fit), a static `CommandRegistry` audit (`tests/discoverability_core_nav.t`) and a manual screenshot sweep across widths/themes/contexts (no `ANTHROPIC_API_KEY` was configured to run the new `qa/scripts/tier2/discoverability_sweep.sh` through the LLM judge, so this pass was done by direct visual inspection instead) found:

1. **The static registry check is necessary but not sufficient — real coverage is better than `priority => 0` alone suggests.** `next_tab`/`prev_tab`/`close_tab` all show `priority => 0` in `CommandRegistry.pm` (would never appear as a status-bar pill), but the DOCUMENT context tab bar actually renders a separate, hardcoded corner hint (`⌃W ×  ⌥, ←  ⌥. →`) that isn't part of the pill-priority system at all — confirmed via screenshot to survive even at 40×15 (the narrowest width tested), only dropping when there's truly no room. So this specific concern is largely already met; `tests/discoverability_core_nav.t`'s TODO-tracked failures on these three IDs are a false-ish positive from checking the wrong mechanism — real coverage exists, just not through the registry. Left as TODO rather than deleted, since the registry genuinely doesn't know about it, which is itself worth fixing (see below).
2. **`quit` (⌃Q) has NO on-screen hint anywhere, at any width, in any theme, in the one context checked (DOCUMENT).** Confirmed absent in 80×24, 60×20, and 40×15 screenshots, both themes. This is a real, confirmed gap — `priority => 0` here is accurate, there's no hidden corner-hint covering it the way tab navigation has.
3. **The FILE_TREE context is missing on-screen hints for: `quit`, switching focus back to the editor (`⌃B`/`Esc`), AND tab navigation** (the corner hint from DOCUMENT context does not carry over — confirmed via screenshot, the tree-focused status bar shows only `.claude` breadcrumb / fold / open / `Open ⌃O` / `Commands ⌃␣`). A user who focuses the tree (by mouse click or `⌃B`) has no visible path back to editing shown anywhere on screen — this is the single clearest violation of the contract found, and matches exactly the scenario the user described.
4. **What's working well** (confirmed, not just assumed): progressive disclosure degrades honestly — `⌃␣ Commands` and the cursor-position pill never dropped at any tested width; the tab-nav corner hint persists down to 40 cols before anything else does.

Only 5 screenshots (document context: 3 widths × mostly-dark plus one light; file-tree: 1) were reviewed — this is a sample, not an exhaustive sweep. FIND/PROMPT/palette contexts, and the light-theme file-tree/narrow-width variants, were not checked. The durable fix for "exhaustive" is running `qa/scripts/tier2/discoverability_sweep.sh` with a real API key configured, which covers the full matrix automatically and repeatably.

**Not fixed here** — pending a scope decision, same as the theme contrast debt above. Candidate fixes: give `quit` a corner-hint-style always-visible affordance (mirroring how close/next/prev tab already work) in every context, not just DOCUMENT; extend the FILE_TREE status bar to include a focus-switch hint and the tab-nav corner hint; consider whether `CommandRegistry` should have a formal `core_nav => 1` tag so `commands_for_status_bar`-style logic and the corner-hint renderer both derive from one source of truth instead of two independent, silently-divergent code paths (the actual root cause of finding #1 — the registry and the tab bar's hardcoded hint don't agree on what's "always visible").

**Fix (2026-08-30, DOCUMENT context only — see "Still open" below):** Addressed findings #1 and #2 directly, and the labeling half of #4/the "refines" note from the follow-up LLM-vision sweep entry below.

- **Finding #2 (quit has no hint anywhere):** added Quit to the same tab-bar corner-hint region `close_tab`/`next_tab`/`prev_tab` already used (`Renderer.pm::_render_tab_bar`), rendered as `⌃Q quit` (labeled tier) or `⌃Q` (compact tier).
- **Finding #1 (registry and corner hint are two independently-agreeing mechanisms):** added `core_nav => 1` to `quit`, `close_tab`, `next_tab`, `prev_tab`, and `toggle_tree` in `CommandRegistry.pm` — a single, explicit, greppable tag for "this command must always have on-screen visibility somewhere, even if not as a status-bar pill." `tests/discoverability_core_nav.t` now checks `core_nav => 1 || priority > 0` instead of `priority > 0` alone, closing the TODO-tracked false-gap noted in finding #1.
- Also folded in the labeling fix from "Discoverability sweep run 2" below (same corner-hint code, touched together): the hint now tries a plain-language labeled form (`⌃W close   ⌥←/→ tabs   ⌃Q quit`) before falling back to the original bare-glyph compact form (`⌃W × ⌥, ← ⌥. → ⌃Q`, now including quit) — mirrors `_fit_pill_group`'s full-form-first idiom. The compact tier's survival down to ~40 cols is unchanged.

**Was open, now fixed (2026-08-30, see "FILE_TREE-context discoverability" section below):** finding #3, the FILE_TREE context having no hint for quit, focus-switch back to the editor, or tab navigation while the tree is focused. That follow-up fix also factored the DOCUMENT-context hint's text/degradation logic out into a shared `_core_nav_hint_text()` helper (used by this fix's `_render_tab_bar` code above too), closing the exact "two independently-agreeing mechanisms" risk finding #1 above called out.

**Tests:** `tests/discoverability_core_nav.t` (updated, no more TODO-tracked failures — all 5 core-nav commands now pass via `core_nav => 1` or `priority > 0`). `tests/renderer.t` — 3 new subtests: labeled form appears at 80 cols (includes "close"/"tabs"/"quit" and the literal `⌃Q` shortcut), compact form (with quit) survives at exactly the 40-col/12-char-filename width this property was confirmed working at before, and the hint degrades to blank fill (not garbage) when nothing fits at all.

**Interactive verification (`hangon`):** 80×24/60×20/40×15, dark and light themes, both nerd-font and `--no-nerd-font` modes. Labeled form (`⌃W close   ⌥←/→ tabs   ⌃Q quit`) renders at 80×24 and 60×20 in every combination tested; degrades to the compact form (still including `⌃Q`) at 40×15; confirmed no crash and honest blank-fill degradation down to 28×12. Functional check: selecting Quit from the command palette (and pressing ⌃Q directly) actually exits the process, not just a cosmetic label.

**QA:** `QA-REG-171` (quit hint present + functional), `QA-REG-172` (labeled form present) in `qa/40_regression_bugs.txt`, scripts `qa/scripts/tier1/reg_171_quit_corner_hint.sh` / `reg_172_tab_hint_labels.sh`. Updated `qa/21_tabs.txt` QA-TAB-013 in place (ID unchanged, content updated to reflect the labeled two-tier hint and quit's inclusion — the old "hints disappear at narrow widths" wording was no longer accurate).

## Scorecard audit backlog (2026-08-30)

Findings from a 5-agent parallel codebase audit (architecture, code quality, security, tests/docs, performance/duplication). Each item below will be marked FIXED with a root-cause/fix/test writeup by whichever agent picks it up, following this file's normal convention.

### ~~P1: FindEngine.pm ReDoS timeout only covers regex compilation, not matching~~ FIXED
The SIGALRM(1) timeout (`FindEngine.pm:455-462`) wraps `qr//` compilation only, then is cancelled before the actual match. Catastrophic backtracking happens at MATCH time, not compile time — a pattern like `(a+)+$` against long input can still hang `tick()` indefinitely (`FindEngine.pm:126,532,549,646`); the 10ms incremental-search deadline check only runs *between* completed matches, not during one. `bugs.md`'s existing "SIGALRM(1) timeout... provides defense-in-depth against catastrophic backtracking" claim (QA-REG-011) is inaccurate for this reason. Self-inflicted only (a user's own search pattern hangs their own search of their own file) — not exploitable by another party — but a real, live gap in a control the docs claim is closed.

**Root cause:** `_build_regex()`'s alarm guards `qr//` compilation only and is explicitly cancelled (`alarm(0)`) before the caller ever attempts a match. All four match sites — `tick()`'s background loop (`FindEngine.pm:127`, was `:126`), the synchronous viewport search in `_search_range()` (`:764`, was `:646`), and the single-match capture extractors `_extract_captures()`/`_extract_capture_positions()` (`:640`/`:662`, was `:532`/`:549`) — ran unguarded. Confirmed exploitable: `(a+)+$` (the bug report's own example) turns out NOT to reproduce this in Perl — Perl's regex engine auto-optimizes away nested quantifiers over identical single-char atoms — but `(a?){28}a{28}` against 28 `a`s does, taking 15+ seconds of pure C-level backtracking unguarded (reproduced with a forked-child watchdog, since Perl's `alarm()` is a single process-wide timer that made an in-process watchdog unusable for testing this).

**Fix:** Added a second, independent alarm around the actual MATCH (not just compilation), via a new `_match_with_alarm()` helper (`MATCH_ALARM_SECS => 1`) used at all four call sites. On timeout, the search aborts gracefully — `tick()`/`_search_range()` stop returning partial results instead of retrying the same doomed match forever (which would otherwise wedge the UI's tick loop indefinitely), and a new `search_timed_out()` accessor lets callers know results may be incomplete; capture extraction just yields no captures. Non-pathological search (including 2000+ line files) is provably unaffected — no false-positive timeouts, same match counts, same speed (`find_engine_perf.t` unchanged).

Found and fixed a bug in an earlier version of this same fix while building it: Perl's numbered match variables (`$1`, `@-`/`@+`) do not reliably survive being read from *outside* a multi-statement `eval{}` block, even though the match inside it succeeded — an initial version of `_match_with_alarm()` read `$1` after the guarding eval returned and silently got `undef` back (confirmed empirically across a dozen isolated repro scripts). Fixed by having the coderef passed to `_match_with_alarm()` extract everything it needs (`$1`, `@-`/`@+`) *inside* itself before returning plain values — `pos()` on the subject string is unaffected by this and safe to read normally after return. Documented in the helper's own comments so it isn't re-broken later.

Test: `tests/find_engine_redos.t` (7 subtests: viewport-path hang, background-tick-path hang, `search_timed_out()` flag + partial results, flag reset on next search, no false positives on legitimate large search, and a capture-extraction regression guard for the `$1`-survival bug above) — forked-child + parent-watchdog design for the same alarm-clobbering reason noted above. QA: `qa/scripts/tier1/sec_012_redos_match_timeout.sh` (`QA-SEC-012`, `QA-REG-141`) — interactively confirms the editor stays responsive (not just that the library function returns) when the pattern is typed into the live find bar.

### ~~P2: message_is_error can leak stale error styling onto non-error messages~~ FIXED (2026-08-30)
`show_message()` (`Editor.pm:5062-5066`) always resets `message_is_error => 0`, but 10 call sites in toggle commands (`Editor/Commands.pm:1280,1287,1294,1306,1313,1320,1327,1334,1357,1376`) wrote `$self->{message} = "..."` directly, bypassing the reset. The top-of-loop guard (`Editor.pm:944-947`) only clears `message_is_error` when a message was already showing at the START of that input batch — it fires once, before `handle_input()` runs, not once per event. `handle_input()` (`Editor.pm:1192-1204`) parses a single `read_blocking()` chunk into potentially *multiple* events and processes all of them via `handle_event()` in one call, so if an error message was showing and a toggle command's confirmation both landed within the same chunk (fast/pasted/scripted input arriving before the app's next read), the toggle's confirmation text inherited the error's red styling (`Renderer.pm:3900`: `message_is_error ? error_fg : warning_fg`) even though it wasn't an error.

**Fix:** Routed every raw `$self->{message} = "..."` assignment for non-error confirmations through `show_message()` instead, which always resets the flag correctly — the 10 sites above in `Editor/Commands.pm` (`cmd_toggle_autocomplete`, `cmd_toggle_auto_pairs`, `cmd_toggle_restore_session`, `cmd_toggle_mouse`, `cmd_toggle_search_wrap`, `cmd_toggle_markdown_tables`, `cmd_toggle_soft_tabs`, `cmd_toggle_auto_indent`, `cmd_set_tab_width`'s `on_submit`, `cmd_toggle_ai`), plus two similar direct-assignment sites in `Editor.pm` (`_replace_all_async`/`_replace_all_sync`'s "Replaced N occurrence(s)" messages, `Editor.pm:3182,3213`) found by the same grep sweep. `message_time` (set alongside the two `Editor.pm` sites) was preserved as a trailing statement — it turned out to be dead (no reader anywhere in the codebase), so left untouched rather than removed as an unrelated cleanup.

**Test:** `tests/editor.t` — "Toggle confirmation does not inherit stale error styling" calls `show_error_message()` then `cmd_toggle_autocomplete()` directly (bypassing `run()`'s per-batch guard entirely, exactly modeling the same-input-batch scenario), asserting `message_is_error` is false afterward. Verified failing against the pre-fix code (`message_is_error` stayed `1`), passing after.

**Interactive verification:** hangon-driven baseline check — real "Invalid tab width" error (red, `38;2;247;118;142`) followed by a real "Auto Pairs: ON/OFF" toggle confirmation (amber/warning, `38;2;224;175;104`) as two sequential actions, confirming the fix didn't break normal toggle messaging. Note: hangon drives zepto through separate process invocations that each reliably land in their own `read_blocking()`/`handle_input()` batch, so this sequential interaction can't reproduce the exact same-batch race (the per-batch guard already resets the flag between separate hangon commands, both before and after this fix) — the unit test above is the only repro of the actual race. QA: `QA-REG-142` (`reg_142_message_error_style_leak.sh`), which documents this same tradeoff in its header.

### ~~P2: Buffer::get_text() re-concatenates the whole document on every line read~~ FIXED (2026-08-30)
**Root cause:** `Buffer.pm` `get_text()` unconditionally built `pre_gap . post_gap` (concatenating the WHOLE document) even to fetch a single line. `get_line`/`get_line_content` called it under the hood, and the renderer calls `get_line_content()` once per visible row (~40-80×/frame) — every rendered frame re-copied the entire document 40-80 times.

**Fix:** `get_text($start, $end)` now reads directly out of `pre_gap`/`post_gap` without concatenating first: if the requested range lies entirely within `pre_gap` or entirely within `post_gap`, it's a single `substr()` with no concat at all; only when the range straddles the gap boundary (which happens only for the one line currently containing the cursor) does it concat, and even then only the two small slices that fall inside `[start, end)`, never the full document. `get_line`/`get_line_content` are unchanged (they still call `get_text()`) and benefit automatically.

**Tests:** `tests/buffer.t` gained new subtests written and confirmed passing against the *unfixed* code first (per Rule 5): "Line reads at the gap boundary" (gap mid-line, gap at a line boundary, gap at position 0, gap at end of buffer), "get_text spanning the gap boundary explicitly", and "Unicode content spanning the gap boundary" (multi-byte and emoji lines straddling the gap). All pass after the fix; full suite (`make test`, 1117 tests) still green with zero noise.

**Benchmark** (30,000-line synthetic file, ~90 chars/line, `qa`/`scratchpad` script, not checked in): `get_line_content()` × 2000 calls at a mid-file scroll position went from **34.48 µs/call → 1.00 µs/call** (~34x).

**QA:** `qa/scripts/tier1/reg_150_buffer_line_read_perf.sh` (QA-REG-150) — correctness regression coverage for large-file line reads at/around the gap after edits at various positions (start, middle, end, near cursor).

### ~~P2: Buffer::_ensure_line_index() does a full O(n) rescan on every edit~~ PARTIALLY FIXED (2026-08-30)
**Root cause:** `insert`/`delete` unconditionally invalidated the line index; the next `line_count()`/`get_line()` call rebuilt the entire newline index from a fresh full-buffer `text()` call — one full-document scan per keystroke on large files.

**Fix (scoped, honest writeup):** `insert`/`delete` now update the line index **incrementally** for the common case: single-character/no-newline edits (the overwhelming majority of keystrokes — typing, backspacing). When the index is already valid and the inserted/deleted text contains no `"\n"`, the edit cannot change which offsets belong to which line, so it only grows/shrinks the length of the one affected line (O(1)) and shifts the start offset of every later line by the edit's length delta (O(remaining lines), pure integer increments — no string scanning, no concat). This is the "shift indices after the edit point" approach suggested in the task.

**What's NOT fixed (documented limitation):** edits whose inserted/deleted text contains a newline (pressing Enter, multi-line paste, deleting a selection that spans a newline) still invalidate the index for a full rebuild on next use — correctly splitting/merging line entries incrementally was judged too risky to rush given the "correctness over speed" mandate for gap-buffer surgery. This is still a strict improvement over before (only newline-crossing edits pay the full rebuild now, not every edit).

**Known remaining tradeoff (not a regression in any real call site found):** the incremental shift is O(remaining lines) per edit. A purely synthetic stress pattern — thousands of sequential single-char inserts at a fixed position with **zero** intervening reads, far from either end of a huge file — is slower per-edit than the old lazy-invalidate-then-single-rebuild (which paid one O(document) rebuild only when a read eventually happened). We audited actual Zepto call sites for this pattern: interactive typing always renders (reads ~40-80 lines) after every single insert, so it hits the *fast*, dramatically-improved path; `_multi_cursor_insert_char` loops over cursors (small N) before a render; `_replace_all_sync` (Editor.pm) is capped at 100 edits before a render; `_replace_all` (>100 matches) does one whole-document `replace()` (contains newlines → single invalidate+rebuild, same cost as before). No bounded real-world batch showed a regression (benchmarked: 100 unread inserts + 1 render = 29ms total on a 30K-line file). A Fenwick-tree/BIT-based line index would close this gap entirely with no tradeoff, but is out of scope for this fix.

**Tests:** `tests/buffer.t` new subtests "Insert exactly at line boundaries", "Delete exactly at line boundaries", and "Repeated single-char edits maintain a correct line index" (simulates typing/backspacing at a fixed cursor position across multiple sequential incremental updates) — written and confirmed passing against the unfixed code first, still pass after.

**Benchmark:** interleaved single-char-insert + 60-line-render (the actual per-keystroke render pattern), 1000 iterations on a 30,000-line file: **6.85 ms/iter → 0.35 ms/iter** (~19x). Pure sequential-insert-with-no-reads stress test (not a real call pattern, see above): 0.40 µs/call → 294 µs/call (regression in that synthetic case only).

**QA:** `qa/scripts/tier1/reg_151_buffer_line_index_incremental.sh` (QA-REG-151) — correctness regression coverage: large file, sequence of single-char inserts/deletes/newline-inserts/newline-deletes at various positions (start, middle, end, near the original gap), asserting line count and content stay correct throughout.

### ~~P2: ~9 near-identical cmd_toggle_* methods, and a duplicated cursor-clamp block~~ FIXED
`Editor/Commands.pm:1283-1330` (approx) — `cmd_toggle_auto_pairs`, `cmd_toggle_restore_session`, `cmd_toggle_search_wrap`, `cmd_toggle_markdown_tables`, `cmd_toggle_soft_tabs`, `cmd_toggle_auto_indent`, and others all share the identical 4-line shape (`$new = !prefs->X(); prefs->set_X($new); message = "Label: ON/OFF"`) — copy-paste, and the source of the asymmetric-feedback inconsistency below. Separately, `Editor.pm:5147-5153` and `Editor.pm:5175-5181` are a byte-for-byte duplicated 7-line cursor-clamp-after-reload block.

**Fix:** Pure refactor, no behavior change (verified by tests before/after, not just code inspection).

Added `_toggle_pref($self, $getter, $setter, $label, %opts)` in `Editor/Commands.pm`, right before `cmd_toggle_autocomplete`. It does `my $new = !$getter->(); $setter->($new); $self->{message} = "$label: " . ($new ? $opts{on_label}//'ON' : $opts{off_label}//'OFF'); return $new;` — the getter/setter are passed as closures (`sub { $self->{prefs}->auto_pairs() }` / `sub { $self->{prefs}->set_auto_pairs($_[0]) }`) so the helper stays agnostic of the specific preference. `on_label`/`off_label` opts cover the one outlier (`cmd_toggle_soft_tabs`'s "ON (spaces)"/"OFF (tabs)" wording). The return value lets callers with an extra side effect (mouse enable/disable, completion dismiss) run it after the preference is persisted, keyed off the new value.

8 methods converted to thin wrappers around `_toggle_pref`, each still defined under its exact original name (CommandRegistry dispatches by method-name string, so none could be renamed or removed): `cmd_toggle_autocomplete`, `cmd_toggle_auto_pairs`, `cmd_toggle_restore_session`, `cmd_toggle_mouse`, `cmd_toggle_search_wrap`, `cmd_toggle_markdown_tables`, `cmd_toggle_soft_tabs`, `cmd_toggle_auto_indent`. `cmd_toggle_minimap` and `cmd_toggle_nerd_font` were deliberately left untouched — they don't set a status message at all (a separate, pre-existing inconsistency, out of scope for a behavior-preserving refactor). **Reconciled at merge time with the concurrently-landed `message_is_error` fix** (which routed all 8 originals' message assignments through `show_message()` to avoid leaking stale error styling onto toggle confirmations): `_toggle_pref` was updated to call `$self->show_message(...)` instead of writing `$self->{message}` directly, so the dedup doesn't reintroduce the bug the other fix closed.

For the cursor-clamp duplication: added `_restore_clamped_cursor($self, $view, $doc, $old_line, $old_col)` in `Editor.pm`, right after `_check_external_file_changes`. Body is the exact original clamp arithmetic (clamp line to `[0, line_count-1]`, clamp col to the clamped line's length) followed by `$view->set_cursor(...)` and `$view->invalidate_wrap_map()`. Both call sites in `_check_external_file_changes` (the dirty-buffer confirm-reload path and the silent clean-buffer reload path) now call this helper instead of repeating the 7-line block.

**Tests:** `tests/editor.t` — added 4 new subtests (auto pairs toggle, restore session toggle, autocomplete toggle incl. completion-dismiss side effect via a `Test::FakeCompletion` stub, and cursor-clamp-after-reload calling `_restore_clamped_cursor` directly with a shrunk document) to cover methods that previously had no direct unit-test coverage. All new tests were run against the pre-refactor code first (via `git stash` of just the two `lib/` files) to confirm they exercise real behavior, then again after the refactor — identical pass in both states. Full suite: 1115 tests (up from 1111), all green, zero stdout/stderr noise.

**QA:** ran targeted `perl qa/runner.pl --tier 1 --filter pref_` (14 scripts, 22 assertions, all pass), `--filter reg_14` (covers the QA-REG-146/147 number range), `--filter sess_009` (restore-session toggle message/state), and `--filter ext_00` (external-reload family) — all pass, no regressions. Relied on this existing coverage rather than adding new `qa/scripts/tier1/reg_146_*`/`reg_147_*` scripts, since it already exercises every refactored method end-to-end through the same command-palette dispatch path that changed, plus the reload-and-keep-local/reload-and-discard flows.

**Interactive verification (`hangon`):** toggled `cmd_toggle_auto_pairs`, `cmd_toggle_restore_session`, `cmd_toggle_soft_tabs` (the custom-label outlier), and `cmd_toggle_mouse` (the side-effect outlier) live via the command palette — each showed the correct `[on]`/`[off]` palette state and exact status-bar message (`Auto Pairs: OFF`, `Restore Session on Startup: OFF`, `Soft Tabs: OFF (tabs)`, `Mouse: OFF`). For the cursor-clamp dedup: opened a 5-line file, moved the cursor to the end of the last line, shrank the file externally to 2 short lines — clean-buffer silent reload clamped the cursor to `2:3` (last line, end of "cd") automatically; made the buffer dirty, shrank the file further to 1 line, chose "Reload" at the change-detected prompt — cursor clamped to `1:2` (end of the new single line). Both matched the expected clamp arithmetic exactly.

### ~~P2: CrossBufferWordProvider rescans every open tab on every trigger, not just the changed one~~ FIXED
`Completion/CrossBufferWordProvider.pm:69-127` — bugs.md's existing "cached per-document by content_version" claim was only true for the skip case. When ANY open document's `content_version` changed, `_rebuild_cache` (lines 79-97) wholesale rescanned *every* open tab (up to `MAX_SCAN_LINES=10000` each) and rebuilt `%all_words` from scratch — not an incremental per-doc merge. Mitigated by the 100ms completion debounce, so not literally per-keystroke, but contradicted the caching description and rescanned N tabs on every trigger regardless of which one changed.

**Fix (Path B — true per-document caching, not just a doc fix):** confirmed the characterization was accurate against current code, then restructured the provider so each open document has its OWN word-frequency cache (`_doc_words`, keyed by doc identity) tagged with the `content_version` it was scanned at (`_doc_versions`). On a trigger, only documents whose version changed since the last scan get rescanned (`_scan_doc`, the line-by-line regex pass) — closed tabs' entries are dropped, untouched tabs are never rescanned. A merged view (`_word_cache`, word → total count) is recomputed by summing the already-cached per-document hashes; that merge is O(total unique words), not O(total lines), so redoing it whenever anything changed is cheap even though the expensive scan is now skipped for unchanged docs. `active_words` (proximity-bonus set) is derived directly from the active doc's cache entry instead of being recomputed during the scan. The single-doc fallback path (`_rebuild_single_doc`, used when there's no `tab_manager`) now shares the same `_scan_doc` helper and cache field names, so there's one scanning code path instead of two near-duplicates.

**Test:** `tests/completion.t` — added subtest "CrossBufferWordProvider (per-document cache isolation)": primes a 2-doc cache, then instruments `Zepto::Document::get_line_content` (via a scoped `local *glob` override, restored automatically) to count calls made against doc2 specifically while editing doc1 only and triggering `complete()` again. Asserts (a) doc2's line-scan call count is exactly 0, (b) doc2's per-document cache hashref is the *same reference* before/after (proof it wasn't rebuilt, not just "looks the same"), (c) doc1's cache entry *was* rebuilt and reflects the edit, and (d) the merged completion results are still correct afterward — both the new word from doc1 and doc2's untouched words still surface. All 7 assertions pass; full `tests/completion.t` (16 subtests) and full `make test` (40 files, 1112 tests) pass with no noise.

**Interactive verification (hangon):** opened 3 tabs with distinct unique identifiers, typed a 2-char prefix in tab B — ghost text correctly suggested tab A's word; accepted it. Then added a brand-new identifier to tab A, switched back to tab B, and typing its prefix correctly surfaced the freshly-added word (proves the targeted rescan picks up new content, not a stale snapshot). Tab C's word (never touched) also still completed correctly from tab B in the same session, confirming the merge doesn't lose untouched docs' entries. `qa/scripts/tier1/cplt_*` (20 scripts, including the pre-existing `cplt_021_cross_buffer`) all pass unchanged.

**QA:** added `qa/scripts/tier1/reg_152_crossbuffer_cache_accuracy.sh` (`QA-REG-152`) — black-box regression coverage asserting the SAME behavior verified interactively above (cross-tab completion before/after a targeted edit, plus an untouched third tab), run 3× to confirm it isn't flaky.

**Incidental discovery (not fixed here, logged separately below):** while writing the QA script, found that pressing Escape (to dismiss an active ghost-text completion) immediately followed by a burst of typed characters starting with a space can silently drop the space or, in one repro, substitute a newline — reproduced independent of this change (also happens in single-document/no-tab-manager mode). See "Escape immediately followed by a burst keystroke send can drop or corrupt the next character(s)" below. The QA script was written to avoid that pattern (continues typing directly instead of escaping first, which is also more realistic user behavior) so it isn't a false dependency on the unrelated bug.

### ~~P3: WrapMap::invalidate_line() has an O(remaining-lines) tail on wrap-boundary changes~~ FIXED
`WrapMap.pm:91-109` — when a single-char edit changes a line's wrapped-segment count (`delta != 0`), it walks every subsequent document line to shift `_doc_to_vrow` offsets. Only triggers on wrap-boundary crossings (not every keystroke), but for large word-wrapped files this is a periodic per-frame spike, not the truly amortized O(1) the "incremental" framing implies. Note: WrapMap invalidation is called out in `docs/CODE_QUALITY.md`'s own pitfall list as a known fragile area — fix with extra care and correctness tests, not just a speed benchmark.

**Fix:** Profiling first (before touching anything) showed the O(remaining-lines) tail was entirely in the `_doc_to_vrow` hash walk — the `_visual_rows` array splice that runs alongside it is NOT a problem (Perl arrays are SV-pointer arrays; splicing near the front of a 40k-element array is a sub-millisecond memmove, confirmed via direct component-level timing). So only `_doc_to_vrow` needed restructuring, not the whole data model. Replaced the eagerly-maintained `_doc_to_vrow` hash (every entry kept correct via the O(n) walk) with a Fenwick tree (Binary Indexed Tree) over per-line segment counts: `invalidate_line()` now does an O(log n) point update (`_fenwick_update`) instead of walking every subsequent line, and `doc_line_to_visual_row()` / `doc_to_visual()` do an O(log n) prefix-sum query (`_vrow_offset`) instead of an O(1) hash lookup into an eagerly-correct hash. Public API (`doc_line_to_visual_row`, `segment_at_visual_row`, `doc_to_visual`, `visual_to_doc`, `total_visual_rows`) is unchanged — only WrapMap's internals moved, so no caller (View.pm, Editor.pm, Renderer.pm) needed changes. The Fenwick tree logic was validated standalone (165k+ randomized checks against a brute-force reference, including line-0/last-line/empty-doc edge cases) before being wired in, and `tests/wrapmap.t` gained 4 new subtests including a property-based brute-force cross-check across 25 randomized boundary-crossing edits — both mutation-tested (deliberately broke the fix two different ways; both were caught by the unit suite). Benchmarks: the isolated Fenwick update/query cost is sub-microsecond regardless of document size or edit position (was ~3.2ms for a boundary-crossing edit near the top of a 20k-line file, scaling linearly with remaining lines); the old ~2-2.7x cost asymmetry between editing near the top vs. bottom of a large wrapped file is gone (now ~1.0-1.2x, i.e. position-independent). Verified interactively via `hangon` on a 500-line wrapped file: boundary-crossing grow/shrink edits near the top render correctly, and scrolling ~260 lines away still shows correctly aligned gutter numbers and content. See `qa/scripts/tier1/reg_153_wrapmap_boundary_edit_correctness.sh` (QA-REG-153).

### ~~P3: Renderer::_render_table_line still uses string-concat, unlike the rest of the file~~ FIXED
`Renderer.pm:1654-1749` builds `$full` via 8 `.=` concatenations per cell/row (including a per-character loop at line 1741) — the exact anti-pattern QA-REG-099 fixed elsewhere in this same file (`_render_line_with_highlights` correctly uses `push @_out`/`join`). Added after that sweep, for the markdown-table feature, so it never got the fix.

**Fix:** Replaced the inefficient string-concatenation pattern in `_render_table_line` with the same `push @array` → `join('', @array)` pattern used throughout the rest of `Renderer.pm`. For separator rows (lines 1682-1691): created `@sep_out` array, pushed all pieces (border color, box chars, separators) onto it, then `join` once at the end. For regular data rows (lines 1708-1755): created `@row_out` array, pushed all pieces (foreground color, left border, per-cell padding, syntax-highlighted cell text, right padding, right border, vertical separators) onto it, then `join` once. The final `join('', @out)` at line 1758 remains unchanged. No visible output change — rendering is byte-identical before and after, verified by rendering test markdown files with tables via hangon. All unit tests pass, all markdown/table QA tests pass (12 passed in tier 1/2 run, including `pref_020_markdown_tables_persist` which explicitly tests table rendering).

### ~~P3: SECURITY.md is stale in several places~~ FIXED

**Fix:** Updated `docs/SECURITY.md` with accurate information:

1. **Network connections:** Rewritten the Network threat to reflect reality: "Zepto makes zero network connections by default. Optional AI completion feature (disabled by default, requires explicit user configuration of API endpoint + key) makes opt-in HTTPS calls to OpenAI-compatible APIs via curl. No network calls are made for any other feature."

2. **Shell execution inventory:** Expanded from "three places" to complete list of six actual locations, all using safe list-form `exec()` / `system()` with argument arrays (no shell interpolation): VCS integration (git), Clipboard tools, File search (git grep/rg/grep), Image format conversion (sips/convert via `which` on hardcoded literals), Text transformation (user-typed shell command via `cmd_transform`/Alt+T — intentional capability, not injection), and AI completion (curl for HTTPS). Each location documented with its approach.

3. **_shell_quote() function:** Removed dead reference. Replaced the outdated example showing `_shell_quote()` with explanation that current codebase uses list-form pipes and `exec()` throughout, which is fundamentally safer (eliminates shell interpretation entirely rather than relying on quoting).

4. **Symlink traversal:** Moved from "Open Items" to "Resolved Items". Documented that FileTree.pm and FilePicker.pm use `Cwd::realpath()` to resolve symlinks in root and all discovered paths, with correct prefix-with-slash traversal check (`index($real, "$root/") == 0`) that prevents "/root" vs "/rootevil" bypass bug. Both implementations audited and correct.

5. **Audit Checklist:** Updated to reflect current mitigation (list-form exec) instead of dead `_shell_quote()` function. Added guidance about `Cwd::realpath()` for symlink handling and opt-in nature of AI completion.

### ~~P3: Two hardcoded /Users/joe paths in QA scripts (repeats a documented past mistake)~~ FIXED
`qa/scripts/tier1/reg_019_natural_sort.sh:12` and `qa/scripts/tier1/reg_021_new_file_tree.sh:9` both hardcoded `QA_ZEPTO=$(cd /Users/joe/src/zepto && pwd)/zepto` — the exact pattern `CLAUDE.md:150` itself cites as a past CI-breaking incident ("cd /Users/joe/src/zepto hardcoded in 5 test scripts — broke on Ubuntu"). Will break on any other machine or CI.

**Fix:** Replaced both with the portable pattern `QA_ZEPTO="$(cd "$(dirname "$0")/../../.." && pwd)/zepto"` that resolves the zepto binary path relative to the script's own location using `$0`, not hardcoded paths. This pattern was already in use by several other working tier1 QA scripts (`fif_015_esc_closes.sh`, `file_014_save_vcs_gutter.sh`). Both scripts tested individually with `bash` after the fix: `reg_019_natural_sort.sh` passes (0 FAILED, 1 skipped), `reg_021_new_file_tree.sh` passes (1 PASSED, 0 FAILED).

### ~~P3: Dead code — _in_modal_state and an empty tautological InputParser branch~~ FIXED
- `Editor/Commands.pm:18-22` `_in_modal_state` helper was added and initially used to replace guard blocks in `cmd_open_file`/`cmd_recent_files`/`cmd_find_in_files` (bugs.md line 299). However, the calls to this helper were removed later (bugs.md line 184, fix for "Global shortcuts should work from any state") when guard interception was moved to `handle_event()`, leaving the method orphaned with zero call sites. Deleted.
- `InputParser.pm:250-254` — an empty no-op `if` block for legacy "basic format" (non-SGR) mouse events, whose own comment admits the logic was abandoned mid-implementation ("Actually buffer was already consumed... handle differently"); also contains a tautological `length(...) >= 0` condition. Not currently reachable/harmful (Zepto only enables SGR mouse mode, `?1006h`), but should be deleted or finished. Treat with extra care given this file's history of subtle input-parsing bugs this session (QA-REG-102, OSC handling) — verify no live basic-mouse-format path depends on it before removing.
  **FIXED**: Confirmed `Terminal.pm:42` (`MOUSE_ENABLE => "\x1b[?1003h\x1b[?1006h"`) never enables bare `?1000h`-only basic mode, so no real terminal can send Zepto a legacy 3-byte mouse report. Independently confirmed the branch was already a structural no-op even before removal: `ESC [ M` (no params) already terminates as its own complete CSI sequence in `_parse_csi` (M is a valid CSI final byte, 64-126), so `_decode_csi` is entered with `$params=''`, the empty if-block does nothing, and control falls through to "Unknown CSI sequence" → `EVT_NONE`. Any legacy-format data bytes that would follow are parsed independently as plain characters by the outer loop — exactly the same before and after deletion (verified with a hand-fed `\x1b[M` + 3 raw bytes probe, before and after the deletion, producing byte-identical output). Removed the dead lines from `InputParser.pm:250-254`; the surrounding `if/elsif`-style chain in `_decode_csi` needed no other changes since the block had no `return`. Added `tests/input_parser.t` subtest "Basic-format (non-SGR) mouse report is not decoded — treated as unknown CSI" and `qa/scripts/tier1/reg_145_inputparser_dead_branch_removed.sh` (QA-REG-145). Full `tests/input_parser.t` (39/39), full `make test` (1112/1112), and the `ms_*` mouse QA sweep (16 scripts / 29 assertions) all pass unchanged. Interactive `hangon` verification: click moved the cursor and updated the status bar, drag produced a selection, scroll and hover produced no crash or stray characters, and quit exited cleanly with no unsaved-changes prompt (confirming no garbage was typed into the document). The `_in_modal_state` half of this bug is NOT part of this fix — left for the other agent handling `Editor/Commands.pm`.

### ~~P3: Renderer.pm palette/dialog layout uses inline magic numbers~~ FIXED
Sizing literals with no named constants: 120/80/60/30 (palette width tiers, `Renderer.pm:514-520`), 45 (`:623`), 40 (`:632`), 50/15 (menu width, `:765-766`), 10/20 (input width, `:567-576`), `mark_interval=10` (`:1263`). Contrast with the same file's proper `use constant` blocks (`TAB_WIDTH`, `DIALOG_WIDTH`, `FILE_EXISTS_CACHE_TTL`).

**Fix:** Pure rename/refactor — no numeric values or rendering behavior changed. Added six new `use constant` blocks directly below `TAB_WIDTH` (`Renderer.pm:86-119` after the change):
- `PALETTE_WIDTH_WIDE => 120`, `PALETTE_WIDTH_MEDIUM => 80`, `PALETTE_WIDTH_NARROW => 60`, `PALETTE_WIDTH_MIN => 30`, `PALETTE_MAX_ITEMS_MIN => 5`, `PALETTE_MAX_ITEMS_MAX => 30`, `PALETTE_SHORTCUT_WIDTH_MIN => 8` — palette width tiers/item-count bounds/shortcut-column floor, each duplicated between the cursor-positioning code (near old `:514-536`) and `_render_command_palette` (near old `:5071-5082`, `:5393`); both copies now reference the same constants.
- `COMPLETION_MENU_WIDTH_MAX => 50`, `COMPLETION_MENU_WIDTH_MIN => 15` — replaces `_render_completion_menu`'s inline `50`/`15` (old `:765-766`).
- `FIND_BAR_RIGHT_SIDE_BASE_WIDTH => 45`, `FIND_INPUT_WIDTH_MIN => 8`, `FIND_INPUT_WIDTH_MAX => 40` — replaces the find/replace bar's inline `45`/`8`/`40`, again duplicated between cursor-positioning code (old `:623,631-632`) and `_render_find_bar` (old `:4730,4740-4741`).
- `FOOTER_INPUT_WIDTH_GOTO_LINE => 10`, `FOOTER_INPUT_WIDTH_WIDE_MIN => 20`, `FOOTER_INPUT_WIDTH_DEFAULT => 12` — replaces the footer-input field's inline `10`/`20`/`12`, duplicated between cursor-positioning code (old `:567-576`) and `_render_footer_input` (old `:4470-4474`).
- `RULER_MARK_INTERVAL => 10` — replaces the column ruler's inline `10` (old `:1263`).

Verified behavior-preserving with a throwaway pure-function harness (not committed) that called `Zepto::Renderer->render` directly for the palette (both `commands` and `recent_files`/wide-tier modes), find bar (plain and replace-active), footer input (goto-line, wide, default), and completion menu at 12 widths spanning every tier boundary (30, 50, 60, 76, 80, 84, 100, 119, 120, 124, 140, 200) — output was byte-for-byte identical before/after across all 84 combinations. Also confirmed interactively via `hangon` (command palette, find bar incl. replace-active, goto-line footer input, completion dropdown via `cplt_009_dropdown`) at the default 80×24 size. QA: `perl qa/runner.pl --tier 1 --filter pal_` (23/23), `--filter reg_046` (1/1), `--filter find_` (40/40, 1 pre-existing skip), `--filter goto_` (18/18, 1 pre-existing skip), `--filter cplt_` (20/20), `--filter prmt_` (11/11, 1 pre-existing skip) all pass. Full `make test` (1111 tests) and `make check` pass.

### ~~P3: Silent eval swallow in file-tree preview open~~ FIXED
`_tree_preview_current` (`Editor.pm`, the function previously referred to here as `_start_preview` — that name doesn't exist in the codebase) wraps document creation in a bare `eval {}` — if opening a preview fails (permission error, decode failure), nothing happened: no message, no log, dead silence. Inconsistent with every other file-open path in the same file, which all route failures through `_user_error()`/`show_error_message()` (`cmd_save`, `_finish_save_as`, `_load_file`, the two external-reload paths).

**Root cause:** the eval's `$@` was never checked. On failure, execution just fell through the end of `_tree_preview_current` with `tree->{preview_active}`/`preview_path` left in whatever state they were in before the attempt.

**Behavioral discovery made while reproducing this:** `FileTree::_scan_dir_one_level` only lists files that pass `-r` (readable) at scan time, so a file that's unreadable from the very start never appears in the tree — there's no way to navigate to it. The bug is real, but the practical trigger is a TOCTOU race: a file is readable when the tree scans, then loses read access (permission change, unmount, etc.) before the user arrows onto it and a preview is attempted.

**Fix:** added `if ($@) { ... }` after the eval in `_tree_preview_current`, matching the established pattern: `$self->show_error_message(_user_error("Preview failed", $@))`. Also resets `preview_active`/`preview_path`/`_preview_is_existing_tab` and switches back to `pre_preview_tab_index` on failure (reusing the exact restore logic already used by the sibling "cursor on directory" branch in the same function), so that rapid arrow-key navigation past several broken files in a row can't accumulate stale preview state or leave a dangling tab reference — each failed attempt cleanly reverts before the next begins. The status bar's existing "message persists until replaced by user input" behavior (`docs/UI_GUIDELINES.md`) already prevents the error from being spammy across rapid navigation: each failure's message is cleared by the very next keypress.

**Test:** `tests/editor.t` ("Tree preview of unreadable file surfaces an error message") reproduces the TOCTOU race directly against `_tree_preview_current` — confirmed silent (empty `$self->{message}`) before the fix, confirmed `message_is_error` + a "Preview failed: ..." message after. Interactively verified with `hangon`: previewed a readable file, revoked its permissions from another shell while zepto was running, arrowed off and back onto it — status bar showed `Preview failed: Cannot open <file>: Permission denied`; a subsequent preview of a different readable file worked normally with no leftover broken state. QA regression script: `qa/scripts/tier1/reg_154_preview_error_feedback.sh` (`QA-REG-154`), feature test `QA-TREE-027`.

### ~~P2: Stale duplicated tail on the cursor's own line after typing into a large file~~ FIXED (2026-08-30)
While interactively verifying the `Buffer::get_text()`/line-index perf fix (QA-REG-150/151) on synthetic 4000-5000 line files via `hangon`, typing a character into a line partway through the file sometimes renders that ONE line (the line under the cursor, and only that line — neighboring lines are unaffected) with a stale duplicate of its own pre-edit tail appended, e.g. typing `a`,`b` into `row2000text` at line 2000 renders `abrow2000textrow2000text` on screen (the correct `abrow2000text` followed by a stale extra copy of `row2000text`). Reproduced with both a single multi-char `send` and separate per-character `send` calls; does not self-correct after 2s, after moving the cursor away and back, or after page up/down.

**Confirmed NOT a data-correctness bug and NOT introduced by the Buffer.pm changes in this session:**
- Saving (`⌃S`) and reading the file from disk always shows the CORRECT content (`abrow2000text`, no duplication) at every point this was observed — the underlying document/gap-buffer content is right; only the on-screen paint of that one row is wrong.
- The status bar's cursor line:col is correct throughout (e.g. `2000:3` after 2 chars).
- Reproduced identically — in fact with MORE garbling — after `git stash`-ing this session's `Buffer.pm` changes back to the original `553f43b` implementation and rebuilding, so this predates and is independent of the `get_text()`/line-index work.

**Root cause (confirmed, NOT WrapMap or Renderer):** despite the strong suspicion this was a `WrapMap.pm`/`Renderer.pm` incremental-redraw bug, direct isolation proved both innocent — a standalone script driving `Zepto::Buffer`/`Zepto::Document` through the exact same insert sequence (`insert 'a'` then `insert 'b'` at the line's start offset) showed `get_line_content()` returning correct, non-duplicated content at every step, with word wrap never even in the picture. The real cause is `Zepto::Completion::Controller::trigger()`: `CrossBufferWordProvider` rescans the active document's words on every keystroke (by design, for cross-buffer word completion), and typing at the **front** of an existing word makes the buffer momentarily contain that word's own extended form — e.g. typing `ab` in front of `row2000text` produces `abrow2000text`, which the word scanner trivially "discovers" and offers back as a completion candidate for its own prefix `ab`. The suggested ghost-text suffix is `substr("abrow2000text", length("ab"))` = `row2000text` — text that is *already* sitting immediately after the cursor. `trigger()`'s only existing self-match guard (`$_->{text} ne $prefix}`) doesn't catch this, because the candidate text is NOT equal to the prefix, only self-referential relative to what already follows the cursor. Ghost-text rendering (`Renderer.pm`'s inline completion hint) has no way to know the suffix is redundant and paints it right after the real line content, producing the on-screen-only duplicate. This also explains every "doesn't self-correct" observation: cursor movement never calls `Completion::Controller::dismiss()`, so the stale (but internally "valid", non-empty) ghost state just keeps re-rendering identically until something else (e.g. a non-word keystroke) clears it.

**Fix:** `lib/Zepto/Completion/Controller.pm::trigger()` now also computes `$after_cursor` (the text already sitting immediately after the cursor on the current line) and, after the existing dedup/exact-match filtering, rejects any completion candidate whose suggested suffix would just reconstruct that already-present text (`substr($after_cursor, 0, length($suffix)) eq $suffix`). This is provider-agnostic (applies to every provider's results, not just `CrossBufferWordProvider`) and only removes truly redundant, self-referential suggestions — a genuinely different candidate sharing the same prefix (e.g. a different word elsewhere in the buffer) is unaffected, verified via standalone probes and interactively.

**Verification:** root cause and fix were both confirmed standalone (no TUI) with a script driving `Zepto::Completion::Controller` directly — before the fix, `trigger()` on the exact repro sequence produced `ghost_text=[row2000text]`; after the fix, the self-match candidate is correctly rejected (controller goes idle when it was the only candidate) while a mixed scenario with one self-match candidate and one genuinely different candidate (`abcdef`) still correctly surfaces the different one. Interactively verified with `hangon` across: original repro (line 2000 of a 5000-line file), start of file (line 1), end of file (line 5000), a line exactly the terminal width, a line containing multi-byte emoji content, and word-wrap mode (front-of-word edit on the same short line, plus separately confirmed multi-segment wrap rendering itself — the `↪` continuation indicator — is unaffected). `make test` and `make qa` pass with no noise; `QA-REG-150`/`QA-REG-151` (which deliberately routed around this exact bug via save-to-disk assertions) were re-run and still pass, and were deliberately left as-is rather than switched to on-screen assertions — see the P1 entry immediately below for why full confidence in "all on-screen duplication is gone" isn't warranted yet. New regression test: `qa/scripts/tier1/reg_165_ghost_completion_self_match_render.sh` (`QA-REG-165`), which asserts ON-SCREEN content directly (the only kind of check that can catch this class of bug, since the document was never wrong) and was confirmed to fail (5/14 assertions) against the pre-fix code before passing 14/14 after.

### ~~P1: Ghost-text completion renders at the end of the line's real content, not at the cursor — garbles arbitrary lines when cursor isn't at line-end~~ FIXED (found 2026-08-30, incidental to the self-match fix above; fixed 2026-08-31)
While verifying the self-match fix above across cursor positions, found a broader, pre-existing, and NOT fixed here bug in the same subsystem: `Renderer.pm`'s ghost-text rendering (`_render_text_area`, the "Ghost text: render inline completion hint on cursor line" block) always paints the ghost-text suffix in the fill area *after* `$content_display_width` — i.e. after the line's full real content — rather than immediately after the actual cursor column. When the cursor is at the true end of the line (the overwhelmingly common typing case) these positions coincide and everything looks correct, including the self-match scenario above (cursor at the very front of a word with nothing else after it once the word ends). But whenever the cursor is genuinely mid-line with unrelated content after it, a **legitimately different** (non-self-referential) completion candidate can still produce confusing, duplicate-looking garbling, because its suggested suffix gets spliced in at the wrong screen column relative to where it was "supposed" to complete.

**Two ways this was triggered, both without needing the self-match bug above:**
1. **Cursor left mid-line after undo/redo:** `Editor::Commands.pm::cmd_undo`/`cmd_redo` never reposition the view's cursor (`Document::undo()`/`redo()` are pure buffer operations) and call `_retrigger_completion_if_word()` afterward, which re-triggers completion using whatever stale cursor column the view still has. In one repro (5000-line file, one line temporarily padded to exactly 80 chars, cursor left at column 2 of an 8-char word after an undo), the debounced trigger legitimately found a same-prefix candidate from a *different, unrelated* line elsewhere in the 3000+ line document (word-index has no notion of "this is a coincidence") and rendered its suffix at the end of the (unrelated, 8-char) line, producing `row1textw989text` on screen — content from line 989 bleeding onto line 1's row, even though line 1 itself was correct in the document (confirmed via save).
2. **Cursor positioned via arrow keys inside a multi-byte (emoji) run:** typing 2 word characters right after an emoji run, where a later, unrelated word on the *same* line shares that 2-char prefix, produced `xyemoji🎉🎉wo🎉wordtailrdtail` — the ghost suffix spliced into the middle of the emoji sequence rather than at the cursor, visually indistinguishable from a duplicate-tail bug.

**Confirmed NOT a data-correctness bug** (same pattern as the P2 above — save-to-disk always showed correct content in every case checked).

**Not fixed here** — this needs a real design change (ghost text should render immediately after the cursor position, with existing trailing content visually pushed right, the way inline completion works in most editors) rather than a narrow filter, and carries real regression risk to a feature (ghost-text rendering) that's exercised on every keystroke; out of scope for the P2 fix above, which only needed to (and does) close the specific self-referential-match pattern described in that ticket. Flagging for dedicated follow-up work with its own repro script. Candidate fix location: `Renderer.pm`'s ghost-text block in `_render_text_area` (search "Ghost text: render inline completion hint") needs to compute its insertion point from the cursor's screen column, not `$content_display_width`; may also want `cmd_undo`/`cmd_redo` to reposition the view cursor to the edited location (arguably a separate, smaller usability bug in its own right) so `_retrigger_completion_if_word()` isn't operating on a stale position at all.

**Fix (2026-08-31):** Reproduced live via `hangon` first (Rule 5) with a minimal, deterministic repro not requiring undo/redo or emoji navigation: a two-line file (`banana bandana` / `ban XYZ`), cursor moved to `2:4` (immediately after `ban`, before the unrelated real ` XYZ` tail) via plain arrow-key navigation, then a character re-typed to re-trigger word-completion at that exact mid-line position. Pre-fix, this rendered `ban XYZdana` — the ghost suffix (`dana`, completing to `bandana`) glued onto the end of the real ` XYZ` tail, exactly the bug's described shape (confirmed via `hangon screenshot` before touching any code).

`Renderer.pm::_render_text_area`'s ghost-text block (the "Ghost text: render inline completion hint on cursor line" comment) now computes the cursor's local visual column on the current row (`$visual_cursor_col - $effective_scroll_col`, the same tab/wide-char-aware `_char_to_visual_col` computation already used elsewhere for the real block cursor, and the same `$effective_scroll_col` the row's own content was sliced against — so it's correct under horizontal scroll and word-wrap segments too) instead of unconditionally using `$content_display_width`:
- If the cursor sits at or past the visual end of the row's real content (the common end-of-line typing case), behavior is **byte-for-byte unchanged** — the ghost text still renders directly in the fill area right after the real content, via the exact same code path as before.
- If the cursor is genuinely mid-line (real content still follows it), the ghost text is painted as a same-row terminal cursor-repositioning overlay: a CUP (`\x1b[row;colH`) jump to the cursor's exact screen column, the ghost text in its usual color, then a second CUP jump back to the row's natural end-of-content column so the minimap/`CLEAR_LINE` that follow in the same row's output aren't disturbed.

This deliberately does **not** splice the ghost text into the already syntax-highlighted content string and re-render — doing so would require shifting every downstream token/match/selection/capture-region position computed against the original (pre-insertion) character offsets, which is exactly the class of risk that produced this bug's own duplicate-looking symptoms in the first place (see the emoji-run repro above). The overlay technique never touches, shifts, or duplicates any byte of the real content or any other row; it only visually paints over however many on-screen cells the ghost text itself occupies, directly at and after the cursor — the same convention already established in this codebase for the real block cursor and line-badges (see the "Light-theme dark background fill" investigation below: "the model misreading Zepto's own legitimate cursor-position badge... or the solid block text cursor itself — which visually sits on top of whatever character is under it — completely normal terminal-editor rendering"). The real document is never touched by the ghost-text preview at all; confirmed by saving mid-preview and diffing against the pre-ghost-text file content (byte-identical in every case checked).

**Verification:** Interactively re-verified after the fix, via `hangon`: (1) the mid-line repro above now renders `bananaZ` — `ban` + the ghost overlay `ana` correctly positioned at the cursor, occluding part of the real ` XY` tail (the leftover `Z` still visible, exactly as much of the real tail as the overlay didn't cover) — and accepting via Tab correctly inserts `ana` at the cursor, producing `banana XYZ` with the real ` XYZ` tail pushed right by the actual document edit (not just rendering), confirmed identical on save. (2) The common end-of-line case (cursor truly at end of `ban`) still renders and accepts exactly as before — no regression. (3) Tab-accept was already correct before this fix (it always inserted via `$view->cursor_col()`/document offsets, never via the buggy rendering path) and remains correct.

While running the broader QA suite for regressions, this fix's positional correctness surfaced a **latent assumption in the pre-existing `QA-REG-165` self-match regression script**, not a new product bug: that script types `xy` at the front of a word at line 1, then later reuses the same `xy` prefix at line 5000 — after the line-1 edit, `xyrow1text` is now itself a real, different word elsewhere in the buffer, so retyping `xy` at line 5000 legitimately offers it as a genuine (non-self-referential) cross-buffer completion candidate. Pre-fix, the mispositioned ghost rendered harmlessly past the real content, so the `xyrow5000text` substring the test asserted on stayed intact by accident; post-fix, the now-correctly-positioned overlay legitimately occludes part of `row5000text` with the unrelated candidate's suggestion, which is *correct, intended* behavior for a real completion match but broke that specific assertion's assumption. Fixed the test (not the product) by giving the end-of-file sub-test its own non-colliding prefix (`wz` instead of reused `xy`) so each self-match repro stays isolated from the others' side effects — confirmed this still passes identically with or without this fix in place (it was never actually testing this bug, just incidentally sensitive to it), and that it still fails correctly (5/14) against the self-match filter being disabled.

**Tests:** `tests/renderer.t` — three new subtests: cursor at true end-of-line (baseline, confirms zero change to the common case, including an exact assertion that no extra mid-row cursor-repositioning sequence is emitted), cursor mid-line with plain ASCII trailing content (asserts the exact `_move_to` + ghost color + text + `_move_to`-back byte sequence at the correct computed column, that the old wrong-position sequence is absent, and that the real trailing content appears exactly once — not duplicated), and cursor mid-line after a tab character (asserts the tab-expanded visual column is used, both via an independent manually-derived expected value and via the renderer's own `_char_to_visual_col`). Confirmed all three fail against the pre-fix code (via a `git stash` round-trip on just `Renderer.pm`, keeping the new tests) before passing after.

**QA:** `QA-REG-215` (`qa/40_regression_bugs.txt`, `qa/scripts/tier1/reg_215_ghost_text_cursor_position.sh`) and `QA-CPLT-024` (`qa/17_auto_pair_and_completion.txt`) — drives a real `hangon` session through the mid-line repro end-to-end (position, trigger, verify on-screen position, verify no bleed onto the unrelated candidate-source line, accept via Tab, save, diff against disk), isolating the cursor's own screen row by fixed row position (not by gutter line-number digit, which renders as a badge glyph on the cursor's own row rather than plain leading spaces) to avoid both a false-negative and a tautological match against unrelated on-screen content. Confirmed to fail (2/7 assertions) against the pre-fix binary and pass (7/7) after. Also re-ran the full existing completion QA suite (`qa/scripts/tier1/cplt_*.sh`, 20 scripts) plus every other ghost-text-adjacent regression script (`QA-REG-089`, `090`, `150`, `151`, `152`, `165`, `170`, `undo_010_ghost_retrigger`, `editor_correctness_sweep`) — all pass (with `QA-REG-165` updated as described above).

### P3: [Architecture] Editor is a 6000-line god object across 3 files — SKIPPED (numbers now stale)
Original entry deferred this as multi-session work; still the right call, but current numbers are understated. As of this audit: `Editor.pm` + `Editor/Commands.pm` + `Editor/Palette.pm` (all three `package Zepto::Editor;`, no real encapsulation boundary between them) total **7,729 lines, 220 methods** (up from the cited 6000/162) — a ~29% line and ~36% method growth since the entry was written, with no extraction having occurred. `Editor/TabManager.pm` (318 lines, a genuine separate `Zepto::Editor::TabManager` class) proves the team can extract a subsystem when it chooses to — the god object isn't a capability gap, just deferred. Not assigned to the current agent fleet (too large/cross-cutting for a bounded background task) — flagging the stale numbers only.

### ~~P3: llm-judge.sh crashes on reasoning-model responses (null content field)~~ FIXED (2026-08-30)
Found while running the discoverability sweep against a non-Anthropic model (`minimax/minimax-m3` via a local OpenAI-compatible gateway, per user request to conserve credits — see http://ai/v1/models). Reasoning models put their analysis in a separate `reasoning`/`reasoning_details` field and leave `content: null` until reasoning concludes; with the script's `max_tokens: 100`, the model always hit `finish_reason: "length"` before ever writing a final `content` answer, and the parser crashed with `'NoneType' object has no attribute 'strip'` on every single call — the sweep failed 8/8 with a parse error, not a real judgment.

**Fix:** `qa/lib/llm-judge.sh` — (1) raised the OpenAI-compatible path's `max_tokens` from a hardcoded 100 to a configurable `${ZEPTO_QA_MAX_TOKENS:-2000}` (structured multi-part discoverability judgments need real budget to reason through); (2) the Python response parser now falls back to `reasoning`/`reasoning_details` when `content` is null, rather than crashing, tagging truncated-before-a-verdict responses distinctly from genuine parse failures. Verified with `minimax/minimax-m3`: same prompt/screenshot that previously produced a parse error now returns a real, coherent, useful judgment.

### ~~P1: Discoverability sweep run 2 (2026-08-30) — LLM vision judge, real findings + one calibration note~~ PARTIALLY FIXED (2026-08-30)
Reran the full `qa/scripts/tier2/discoverability_sweep.sh` matrix (8 screenshots: document × {80×24, 60×20, 40×15} × {dark, light}, plus file-tree × {dark, light}) using `minimax/minimax-m3` via a local OpenAI-compatible gateway (see llm-judge.sh fix above) after the manual 5-screenshot sample from the previous entry. This is the first time the automated sweep actually ran end-to-end rather than being reviewed by hand.

**Confirmed, consistent across every single screenshot (8/8):** (a) Quit has no on-screen hint anywhere, at any width, in any theme, in any context — matches the manual pass. (e) The `⌃␣ Commands` fallback signpost is present and recognized everywhere — the contract's "always know where to find everything else" guarantee holds.

**Refines the manual pass's finding on (b)/(c) tab navigation:** the manual pass concluded close/next/prev-tab "already work" because the corner hint (`⌃W × ⌥, ← ⌥. →`) is technically rendered and survives narrow widths. The LLM sweep disagrees, consistently (6/6 relevant screenshots): the hint is present but **not comprehensible to a first-time user** — raw modifier glyphs with no label ("unlabeled and ambiguous", "no clear 'tab' indication"). This matters: the Discoverability Contract requires the hint be usable by someone who's "never read any documentation," not merely rendered — a cryptic glyph cluster technically satisfies "on screen" but fails the actual contract. Downgrades that part of the manual finding from "already covered" to "present but not actually discoverable without prior knowledge — needs a label, not just glyphs."

**New finding, not caught manually:** the compact Word Wrap pill (bare "Z" at narrower widths, by design per the priority-based progressive disclosure system) reads as an unlabeled, context-free letter to a first-time user (flagged independently in 3 of the 4 document screenshots). This is arguably working as designed (compact form = icon+key, dropping the label is the intended tradeoff) but is worth weighing against the Discoverability Contract's standard.

**Calibration note — two claims investigated and found to be model misreads, NOT real bugs (verified by direct screenshot inspection, not taken on faith):**
- Claimed "line number '1' appears duplicated between ruler and gutter" / "ruler layout misaligned" at 40×15 — re-captured and inspected directly: no overlap. The model conflated the ruler row's small cursor-line badge (a legitimate, distinct UI element showing "line 1" context) with the gutter's actual line-number column — both correctly show "1" because the cursor is on line 1, which is not a bug.
- Claimed the file-tree context's corner hint is "overlapped/obscured by the active tab label" — re-captured with a short filename and found no collision; not re-tested with a filename as long as the original sweep's (`disc_filetree.txt`, 14 chars) so a genuine collision at longer filenames isn't fully ruled out, but the claim as stated didn't reproduce.

**Takeaway for future sweeps:** trust this pipeline's judgment-based findings (is X labeled/discoverable/comprehensible) — that's exactly the class of question a contrast-ratio-style deterministic test can't answer and this model got right, consistently, across repeated runs. Spot-check any claim of a concrete pixel-level rendering defect (overlap, truncation, misalignment) against a direct screenshot before treating it as confirmed — this model hallucinated two of those in one 8-screenshot run.

Not fixed here — same as the manual-pass entry, this is a finding-gathering pass. Candidate fixes now better-scoped: (1) give Quit a hint everywhere, (2) add a plain-language label to the tab-nav corner hint instead of relying on raw glyphs (e.g. spell out "close/prev/next" abbreviated, or make it discoverable via a one-time/first-launch nudge), (3) extend file-tree context with its own hint set, (4) decide whether the bare "Z" compact-pill tradeoff is acceptable or needs a fallback tooltip/legend.

**Fix / investigation (2026-08-30):**

- **(1) and (2) fixed together, same change as the manual-pass entry above:** Quit now has a hint (`⌃Q quit` / `⌃Q`), and the tab-nav corner hint now leads with plain-language labels (`⌃W close   ⌥←/→ tabs`) instead of raw glyphs, falling back to glyphs-only only when labels don't fit. Verified interactively at all three tested widths, both themes, both nerd-font modes.
- **(4) investigated, did NOT reproduce as a real bug — the "bare Z" claim does not hold up against the actual character stream or a direct screenshot, in either mode.** `Zepto::Chars.pm`'s ASCII fallback for `wrap` is `'W'` (non-empty), and `Renderer.pm`'s compact-pill construction (`"$icon $stripped"`) always includes it — confirmed three independent ways: (a) `Zepto::Chars->get('wrap')` returns `'W'` with nerd font off; (b) a live `--no-nerd-font` hangon session renders the pill as `W Z` (icon + key), not a bare `Z`; (c) raw-byte inspection of a live nerd-font-ON session shows the NF_WRAP codepoint (`\x{f036}`, UTF-8 `EF 80 B6`) genuinely present in the output stream immediately before the `Z`. A rendered screenshot of that same nerd-font-ON session *does* show the Word Wrap pill as an apparently-bare `Z` (screenshot inspected directly, not taken on faith) — while other nerd-font icons in the same screenshot (Save's floppy disk, Open File's folder, the Commands hamburger) render correctly. This is consistent with the screenshot-rendering tool's font not including a glyph for that one specific Font Awesome codepoint while covering others — a font-completeness artifact of the tool that produced the LLM sweep's screenshots, not a Zepto defect; the same class of "spot-check before treating a claim as confirmed" this file's own calibration note (below) already established. Audited the entire registry (not just Word Wrap): every `priority > 0` command's icon already resolves to a non-empty glyph in both modes — zero gaps found. No `Chars.pm` change was needed; added a general regression guard instead (see Tests below) so a future command that genuinely lacks an icon mapping would be caught immediately rather than needing another screenshot sweep to notice.
- **(3) still open, not touched by this pass** — same FILE_TREE gap noted in the manual-pass entry above.

**Tests:** `tests/renderer.t` — "No priority > 0 command ever compacts to a bare key with no icon (either nerd-font mode)": iterates every `priority > 0` command in `CommandRegistry`, both nerd-font states, asserting `Zepto::Chars->get($icon_name)` is non-empty. General assertion over the whole registry, not Word-Wrap-specific, so a newly-added priority-eligible command with a missing icon mapping fails immediately instead of waiting for another vision sweep.

**QA:** `QA-REG-173` (`qa/40_regression_bugs.txt`, `qa/scripts/tier1/reg_173_compact_pill_icon.sh`) — confirms the live `--no-nerd-font` compact Word Wrap pill shows `W` before `Z`. `QA-SBAR-021` (`qa/26_status_bar.txt`) documents the investigation and both modes.

## Found while fixing the ReDoS match-timeout bug (2026-08-30)

### ~~P2: Perl warnings leak to the terminal and corrupt the TUI display~~ FIXED (2026-09-01)
Discovered while interactively testing the ReDoS match-timeout fix (`QA-SEC-012`) via `hangon`: typing a counted-repetition pattern like `(a?){28}` into the find bar in regex mode — one keystroke at a time, as find-as-you-type does — causes Perl's `use warnings` to emit "Unescaped left brace in regex is passed through in regex" to STDERR on every intermediate incomplete pattern (`(a?){`, `(a?){2`, etc. are each individually compiled via `_build_regex()` as the user types). Nothing in the codebase installs a `$SIG{__WARN__}` handler (confirmed: `grep -rn '__WARN__' lib/` finds none, `Terminal.pm:274` only handles `__DIE__`), so these warnings hit the real STDERR and scroll raw text across the alternate screen buffer, visually corrupting the TUI until something forces a full redraw. Confirmed this is NOT specific to the ReDoS fix or to pathological patterns — any use of an incomplete `{n}`/`{n,m}` quantifier while typing (a totally ordinary, non-malicious thing to type in regex-find mode) triggers it; reproduced identically on unmodified `_build_regex()`. The editor itself keeps functioning underneath (confirmed: still accepts input, `⌃Q` quits cleanly) — this is a display/robustness bug, not a hang or data-loss issue, which is why the ReDoS fix (P1, above) doesn't fix or depend on it. Not fixed here — out of scope for the ReDoS task; candidate fix is a process-wide `$SIG{__WARN__}` handler that redirects warnings to a log file (or suppresses them) for the lifetime of the TUI session, restored on exit, mirroring the existing `$SIG{__DIE__}` handling pattern in `Terminal.pm`.

**Also confirmed independently in `Highlighter.pm` (2026-09-01, found during this fix's own audit pass):** a second, unrelated trigger — `_load_grammar()`'s `eval "require $grammar_class"; if ($@) { warn "Failed to load grammar $grammar_class: $@"; ... }` — fires whenever a grammar module fails to load (a corrupted bundled build, a renamed/missing grammar class). Same corruption mechanism, completely different call site, which is exactly why the fix below is a process-wide safety net rather than a patch to any one trigger.

**Confirmed also in `FileSearchEngine.pm` (2026-08-30, while fixing the round-3 "Find in Files has no match-time ReDoS timeout" P1, `QA-REG-207`):** same root cause, second call site. `_start_perl_search()`'s `qr/$query/` (`FileSearchEngine.pm` regex-compile line, analogous to `FindEngine.pm::_build_regex`) has the identical gap — typing `(a?){28}a{28}` into Find in Files in regex mode produced the same raw "Unescaped left brace" STDERR spew corrupting the TUI mid-search, verified via `hangon`. Also confirmed NOT a hang: the underlying `zepto` process's CPU time was flat (idle, not spinning) within ~1s of the last keystroke and it quit instantly and cleanly on `⌃Q` despite the garbled screen — i.e. the match-time alarm fix worked correctly underneath; only the display was corrupted. Not fixed here, same reasoning as above — this is a pre-existing, unrelated display bug and the ReDoS fix doesn't touch `qr//` compilation. Whoever picks up the `$SIG{__WARN__}` fix should apply it process-wide (it will cover both `FindEngine.pm` and `FileSearchEngine.pm` in one change).

**Fix (2026-09-01, branch `add-sigwarn-handler`):** Re-confirmed the find-bar trigger live via `hangon` on unmodified code before touching anything (typing `(a?){28}` into the find bar in regex mode one character at a time reproduced the exact corruption described above — raw "Unescaped left brace in regex is passed through in regex; marked by <-- HERE in m/..." text scrolled across the document area, screenshot-confirmed). Also grepped the whole `lib/` tree for every `warn()` call site (`grep -rn '\bwarn\s*[("'"'"']' lib/`): exactly two explicit calls exist — `Terminal.pm:169` (`enable_raw_mode()`'s own "Could not enable raw mode" warning) and `Highlighter.pm:492` (the grammar-load-failure warning above) — plus the interpreter-generated `use warnings` diagnostics from `FindEngine.pm`/`FileSearchEngine.pm`'s regex compilation. Perl routes both explicit `warn()` and interpreter-generated warnings through `$SIG{__WARN__}` identically, so a single process-wide handler covers all of them regardless of call site.

Added `Terminal.pm::install_warn_handler(log_path => ...)` / `restore_warn_handler()`. Design decision — **redirect to a log file, not suppress**: this project has no tolerance for silently swallowed bugs (see the 8 Rules), and a warning is real diagnostic signal that shouldn't just vanish; the log just needs to be off the live display. No existing log-file convention existed anywhere in the codebase to reuse (grepped for `open(.*>.*log`, `log_file`, `_log(` — nothing), so the log lives at `<state_dir>/warnings.log`, reusing `StateStore`'s existing `base_dir` convention (the same directory prefs/history already live in — `~/.config/zepto` by default, or `--state-dir`/`ZEPTO_STATE_DIR` in tests/QA) rather than inventing a new location. Each entry is timestamped; the parent directory is created on install (mirroring `StateStore::_ensure_dir`'s manual `mkdir -p` loop — no new `File::Path` dependency). Writing the log is wrapped in its own `local $SIG{__WARN__} = 'DEFAULT'; local $SIG{__DIE__};` guard so a failure to open/write the log file can never itself warn/die and recurse back into the handler.

Lifecycle mirrors the existing `$SIG{WINCH}` handler in `Editor.pm` (a real precedent for "install a process-wide signal handler for the TUI session, restore it on cleanup" already in this codebase — closer in shape to what's needed here than the `$SIG{__DIE__}` local-scope suppression inside `Terminal::get_size()`, which is a narrow one-off, not a session-lifecycle pattern): `Editor::init()` calls `$term->install_warn_handler(...)` as the very first line, before `enable_raw_mode()`/`enter_alt_screen()` — this also covers `enable_raw_mode()`'s own internal warn() on failure, maximizing coverage. `Editor::cleanup()` calls `$term->restore_warn_handler()` as the very last step, after `$self->{terminal}->cleanup()` and the `$SIG{WINCH}` reset — restoring `$SIG{__WARN__}` to whatever it was before (normally unset), so `--help`/`--version`/CLI arg parsing (which exit before `Editor->new`/`run()` is ever called) and any warning after a clean exit or during crash reporting (`_print_crash_report`, called after `cleanup()`) behave exactly as before, unaffected.

**Tests:** `tests/terminal.t` — two new subtests. `'__WARN__ handler install/restore lifecycle'` captures real STDERR via an in-memory-filehandle swap (the actual instrument that matters — not an approximation) and proves, in one script: (1) baseline — with nothing installed, `warn()` reaches STDERR (the pre-existing broken behavior); (2) installed — STDERR receives nothing, the warning lands in the log file with a timestamp instead; (3) restored — STDERR receives warnings again, and the post-restore warning does NOT also land in the log (proves the handler was actually removed, not made a permanent no-op). `'__WARN__ handler is a no-op without a log_path'` covers the no-`log_path`-configured case. Confirmed the guard actually bites: ran this test file against the code *before* `install_warn_handler`/`restore_warn_handler` existed — failed loudly (`Can't locate object method "install_warn_handler" via package "Zepto::Terminal"`, exit 13) rather than silently passing; all 35 subtests (33 pre-existing + 2 new) pass after the fix.

**QA:** `qa/scripts/tier1/reg_225_warn_handler_no_screen_corruption.sh` (`QA-REG-225`, cross-referenced from `qa/09_find_replace.txt` `QA-FIND-031`) reproduces the exact find-bar repro against a real running zepto and asserts no raw warning/error text reaches the screen, the find bar still shows the fully-typed pattern (proves this was always a display bug, not a hang), and the warning lands in `$QA_STATE_DIR/warnings.log`. Verified non-tautological: 4 of 7 assertions fail against the pre-fix binary (raw warning text visible on screen, no log file created) and all 7 pass against the fix — confirmed by temporarily reverting `lib/Zepto/Terminal.pm`/`lib/Zepto/Editor.pm` to `HEAD` and rerunning the script. Interactively re-verified via `hangon`: pre-fix screen capture shows the corrupted scroll of raw Perl warning text across the document area; post-fix screen capture on the identical keystroke sequence is completely clean, with the 8 warnings that fired during typing landing in `warnings.log` instead.

**Not fixed here (explicitly out of scope, unchanged from the original finding above):** the underlying `warn()`-triggering causes — `FindEngine.pm`/`FileSearchEngine.pm`'s regex-compile warning on an incomplete `{n}` quantifier, and `Highlighter.pm`'s grammar-load-failure warning. Both still `warn()` exactly as before; the fix is a process-wide safety net that catches any warning regardless of trigger site, not a patch to silence these two specific warnings at their source (that's a separate, larger task touching two different regex-building code paths). `Terminal.pm:169`'s own "Could not enable raw mode" warning is likewise untouched at the source — it's simply now caught by the same handler, same as everything else.

**Incident during this fix, worth flagging for future concurrent-agent sessions:** while doing a Rule-5 "verify the QA script fails against unfixed code" check, `git stash push -- lib/Zepto/Editor.pm lib/Zepto/Terminal.pm` followed shortly after by `git stash pop` picked up a **different agent's** stash instead of this session's own — `git stash` is a single ref shared across all worktrees of a repo (unlike branches/working trees, which worktrees do isolate), so two agents in different worktrees pushing/popping stashes around the same time can and did interleave. This session's own Editor.pm/Terminal.pm changes were lost from this worktree (recovered by re-applying them from this session's own transcript, since the exact diffs were already known) while a different in-flight agent's unrelated "Replace All undo granularity" changes (`lib/Zepto/Document.pm`, `tests/document.t`, `tests/find.t`, a different `lib/Zepto/Editor.pm` hunk) landed in this worktree instead. That foreign diff was saved to a patch file outside the repo (not committed, not discarded) and this worktree's affected files were reverted to `HEAD` before redoing this fix's own changes cleanly. Separately, a live scan of sibling `.claude/worktrees/*` at the time showed **three different concurrent agents had all independently picked `QA-REG-222`** as their "next available" regression-test number (this fix, a clipboard-copy-alarm fix, and the Replace-All-undo fix above) — `qa/40_regression_bugs.txt`'s "find the next unused number" convention only accounts for main's committed history plus one known human in-flight claim, not concurrent agent claims in sibling worktrees. This fix moved to `QA-REG-225` after scanning all sibling worktrees for already-claimed numbers; the other two agents' numbering was left for them to resolve. Logging this as a process gap, not a code bug: **`git stash` must not be used for any purpose while other agents may be concurrently working in sibling worktrees of the same repo** (use a throwaway branch, `git diff > patch-file`, or `cp` instead), and QA-REG numbering needs a mechanism more robust than "grep main's committed history" when multiple agents work in parallel.

## QA coverage expansion: rendering glitches, editor correctness, performance/hangs, LLM-judge defaults (2026-08-30)

Built four new pieces of QA infrastructure to close explicitly-requested gaps beyond the existing discoverability sweep: (1) `qa/scripts/tier2/rendering_glitch_sweep.sh` — a broad, mid-operation vision-judge sweep (typing, undo/redo, wrap toggle, rapid tab switch, completion popup, file-tree toggle, terminal resize, rapid scroll — 12 screenshots); (2) a hybrid editor-correctness pair, `qa/scripts/tier1/editor_correctness_sweep.sh` (deterministic save-and-diff, no LLM) + `qa/scripts/tier2/editor_correctness_visual_sweep.sh` (same edit sequences, vision-judges the LIVE unsaved screen) — generalizing `QA-REG-165`'s ghost-text bug shape (word-front/end/mid insertion, multi-cursor, undo/redo, paste) beyond that one pinned repro; (3) `qa/lib/qa-perf-helpers.sh` + 6 new `qa/scripts/tier1/perf_0{16..21}_*.sh` scripts — real wall-clock timing (not vision-based; a screenshot can't tell you an operation took 3 seconds) covering large-file open, large paste, many-match Replace All, rapid typing, wrap toggle, and scroll on large files, each distinguishing "slow" from "hung/broken" in its failure message; (4) `qa/lib/qa-llm-defaults.sh`, sourced by `qa-helpers.sh`, filling in a working `ZEPTO_QA_API_URL`/`_KEY`/`_MODEL` default (`minimax/minimax-m3` via the local unauthenticated gateway at `http://ai`) so `make qa-visual`/`make qa-full` no longer silently skip every tier2 LLM check in a fresh shell — fully overridable via env var, and `llm-judge.sh` now sets an explicit `curl --max-time` so a bad/unreachable gateway fails fast instead of hanging.

**Two real (if minor) infra fixes made along the way, not editor bugs:**
- `llm-judge.sh`'s default `max_tokens` (2000) was sometimes too tight for `minimax/minimax-m3` (a reasoning model) to finish its reasoning AND emit a final terse verdict on more detailed prompts — confirmed via `editor_correctness_visual_sweep.sh`'s "paste" case producing "model only produced reasoning, no final verdict" while the reasoning text itself correctly concluded no bug was present. Raised the default to `ZEPTO_QA_MAX_TOKENS=3500` in the new `qa-llm-defaults.sh`, benefiting all ~50 existing tier2 scripts, not just the new ones.
- `qa_resize_window` was extracted from `discoverability_sweep.sh`'s previously-local `resize()` into `qa-helpers.sh` as a shared helper (both new sweeps needed the same tmux-resize mechanism); `discoverability_sweep.sh` now calls the shared version too.

**Calibration finding — extends the "Calibration note" above with a THIRD confirmed instance of the same failure class, now clearly a pattern rather than a one-off:** every concrete pixel-level FAIL `rendering_glitch_sweep.sh` produced across 3 full runs (6 leads total: a claimed "REALLYLONGINSERT/fox character overlap", a claimed "ruler '30' eaten by the cursor marker, showing '9'/'0' instead", a claimed "stray '2' character above the gutter", a claimed "leading 'v' of variableNameOne hidden by the cursor", plus 2 repeats of the first two across runs) was investigated by re-capturing that exact scenario and inspecting the screenshot directly — **all were the model misreading Zepto's own legitimate cursor-position badge** (the small highlighted number showing the cursor's current column, e.g. "28" or "2", rendered near the ruler/gutter) **or the solid block text cursor itself** (which visually sits on top of whatever character is under it — completely normal terminal-editor rendering) as corruption. Zero of the ~18 assertions across 3 runs were a real rendering defect. This is now a well-established, specific, reproducible blind spot for this model/pipeline combination (cursor badges and block cursors near other UI elements), not random noise — a future maintainer investigating a `rendering_glitch_sweep.sh` FAIL should check "is this just the cursor?" first, before assuming a real defect.

**Test-script bugs found and fixed while validating the new scripts (not product bugs — flagging for future script authors in this repo):**
- `hangon keys` has no `ctrl-end`/`ctrl-home` key name (confirmed pre-existing precedent in `nav_006_ctrl_home.sh`/`sel_017_shift_ctrl_end.sh` uses raw CSI `\x1b[1;5F`/`\x1b[1;5H` instead) — an early draft of `editor_correctness_sweep.sh` and `rendering_glitch_sweep.sh` used the unsupported key name and errored out (`unknown key: ctrl-end`) rather than silently misbehaving, so this was easy to catch, but worth calling out for future scripts.
- `Preferences.pm`'s `WRAP_DEFAULT_EXTENSIONS` (`md txt rst adoc markdown text`) makes word wrap default ON for a plain `.txt` fixture file — a first draft of `perf_020_wrap_toggle_large_file.sh` and `rendering_glitch_sweep.sh`'s wrap case assumed default-OFF and used `.txt`, so their single `alt-z` toggle turned wrap OFF instead of on, and the "wrap turned on" completion signal (the `↪` continuation glyph) never appeared — looked exactly like a hang/timeout until traced back to the extension. Fixed by using a `.dat` extension for wrap-toggle test fixtures.
- A large-paste perf test (`perf_017_large_paste.sh`) had an off-by-one in its selection setup: goto-line lands BEFORE that line's content, so selecting "from line N back to the document start" via that goto target excludes line N's own content. First draft goto'd to the marker line itself (4000) instead of one past it (4001), so the paste completion marker was never included in what got copied, and the timing assertion looked like a 20s+ hang until traced back to the selection boundary. Both perf_017 and perf_020's fixes are the kind of thing this session's "trust but verify" discipline (re-derived from the vision-judge calibration note, applied here to timing/deterministic assertions too) was built to catch before it got written up as a false regression.

No new product bugs (P0-P3) found by any of the four new sweeps in this session's runs — all leads were investigated and traced to test-script issues (now fixed) or the cursor-badge model-misread pattern (documented above, not a product defect).

## FILE_TREE-context discoverability (2026-08-30)

### ~~P1: FILE_TREE context has no on-screen hint for switching focus back to the editor, or for quit/tab-nav~~ FIXED
This is finding #3 from the "Discoverability Contract gaps" entry above, confirmed independently twice (an automated LLM vision-judge sweep and a direct manual `hangon` pass): with the file tree open and focused, there was ZERO on-screen indication of (a) how to switch focus back to the editor, or (b) the core-nav hints (`quit`/`close_tab`/`next_tab`/`prev_tab`) that DOCUMENT context's tab-bar corner hint already shows. The tree's own hint row showed only tree-specific actions (`↑↓  ←→ fold  ↵ open`) plus `Open ⌃O` / `Commands ⌃␣` — `⌃B` (the actual tree-toggle/focus-switch shortcut) appeared nowhere on screen. A pre-existing `Esc back` pill in the row's pill list turned out not to close this gap in practice — Esc *dismisses* the tree entirely (a different, more destructive action than `⌃B`, which only switches focus and leaves the tree open — see `docs/UI_GUIDELINES.md` "Navigation And Focus") — and it consistently lost the width-fitting race to `↵ open`/`↑↓`/`←→ fold` before it, so at any width where those already used most of the row's budget it silently vanished with no substitute.

**Root cause:** `Renderer.pm::_render_context_status_bar`'s tree-focused hint row built its "middle" pills from a hand-rolled, single-tier, sequential-fit loop (`@tree_pills`, each pill full-text-only, `last` on first miss) — no per-pill compact fallback, and no shared connection at all to `_render_tab_bar`'s DOCUMENT-context corner hint (which already had its own two-tier full/compact `_core_nav_hint_text` logic, added by the fix directly above this one). Two independent, unrelated hint mechanisms for what the Discoverability Contract treats as the same category of requirement ("core navigation must always have an on-screen hint somewhere") — exactly the diverging-sources-of-truth shape that caused the original DOCUMENT-context Quit gap.

**Fix:**
- Added a `⌃B back` pill to the tree hint row's middle pill group, given the HIGHEST priority (rendered/fit first) of all the tree-context pills — per `docs/UI_GUIDELINES.md`'s Discoverability Contract, this is the single most important addition here, since it was the one piece of core navigation with literally no substitute anywhere on screen.
- Reordered the remaining tree pills by actual importance: `⌃B back` > `↵ open` (arrow-key navigation already previews/opens files, so Enter is a secondary refinement, not a first-time-blocking gap) > `↑↓` / `←→ fold` (navigation basics a user either already knows or can find via the always-visible `⌃␣ Commands` fallback). Dropped the old `Esc back` pill — superseded by `⌃B back`, which is both more specific (the real, documented focus-switch shortcut) and higher priority.
- Extracted `_core_nav_hint_text($available)` out of `_render_tab_bar` into a shared helper (used by both `_render_tab_bar` and `_render_context_status_bar` now), so the DOCUMENT-context corner hint and the FILE_TREE-context hint row's core-nav segment (`⌃W close   ⌥←/→ tabs   ⌃Q quit`, degrading to `⌃W × ⌥, ← ⌥. → ⌃Q`) render byte-identical wording from one source instead of two that could drift again.
- Gave the tree-specific pills (`⌃B back`, `↵ open`, `↑↓`, `←→ fold`) proper two-tier full/compact degradation by reusing `_fit_pill_group` (previously only used by the DOCUMENT status bar's ⌃/⌥ pill columns) instead of the old single-tier hand-rolled loop — this alone roughly halved the minimum width at which `⌃B back` becomes visible (confirmed via a direct-render probe: was ~70 cols with the old sequential-fit-only-full-text loop and `⌃B` last in priority order; is ~50-56 cols now with `⌃B` first and a compact `⌃B`-only fallback).
- The FILE_TREE-context core-nav segment (quit/close/tabs) only has room to appear at wider widths than DOCUMENT context's (~100-110 cols vs. DOCUMENT's ~40) because this row carries substantially more fixed chrome — a breadcrumb path plus the `Open ⌃O` / `⌃␣ Commands` pills — before any hint text gets a turn at the remaining budget. Not resolved further here: shrinking `Open`/`Commands` to a compact form at narrow widths (mirroring the DOCUMENT-context pill columns' full/compact behavior) would close the gap but touches pills outside this task's scope; tracked as a candidate follow-up below.
- At the extreme (~40 cols, both nerd-font and ASCII modes), the FILE_TREE hint row's fixed chrome (breadcrumb + `Open ⌃O` + `⌃␣ Commands`) alone already consumes nearly the full row, so none of the tree-specific/back/core-nav hints have room — confirmed via `hangon` this degrades honestly (blank fill, no truncated/garbled glyphs, no crash) and the unconditional `⌃␣ Commands` fallback signpost never drops, matching the Discoverability Contract's "must never drop the signpost" requirement even though full parity with DOCUMENT context's ~40-col survival isn't achieved at this specific width.

**Tests:** `tests/renderer.t` — new subtests for the FILE_TREE-context hint row: `⌃B back` present at 80 cols, compacts to bare `⌃B` before disappearing, core-nav segment (`close`/`tabs`/`quit`) appears at a wide-enough width using the same wording DOCUMENT context uses, and the row degrades to blank fill (not garbage) at extreme widths without dropping the `Open`/`Commands` pills. `tests/discoverability_core_nav.t` unchanged (already covered `toggle_tree`'s `core_nav => 1` tag from the DOCUMENT-context fix).

**Interactive verification (`hangon`):** 80×24, 60×20, 40×15, dark and light themes, both nerd-font and `--no-nerd-font` modes. `⌃B back` (full form) visible at 80×24 and 60×20 in every combination tested, alongside `↵ open`/`↑↓` (fold drops first under nerd-font at 80, all four fit in ASCII mode at 80); at 40×15 no tree-specific hints fit but `Open ⌃O`/`⌃␣ Commands` remain and the app stays responsive (confirmed alive, no crash, no garbled glyphs). Functional check: `⌃B` while tree-focused returns focus to the editor while leaving the tree panel open (distinct from `Esc`, which dismisses it) — confirmed both via `hangon` and `QA-REG-183`.

**QA:** `QA-REG-183` (⌃B hint present + functional, tree stays open), `QA-REG-184` (core-nav hint shares wording with DOCUMENT context), `QA-REG-185` (graceful degradation at 60/40 cols, `⌃␣ Commands` never drops, no crash) in `qa/40_regression_bugs.txt`, scripts `qa/scripts/tier1/reg_183_tree_back_hint.sh` / `reg_184_tree_core_nav_hint.sh` / `reg_185_tree_hint_narrow_degrade.sh`. Updated `qa/22_file_tree.txt` QA-TREE-020 and `qa/26_status_bar.txt` QA-SBAR-009 in place (both were already stale relative to the actual pill set even before this fix — e.g. they referenced a `/ filter` pill that doesn't exist in the code — corrected to describe the real current pill set while updating them for this change).

**Follow-up candidate (not done here, out of scope):** give the fixed `Open ⌃O` / `⌃␣ Commands` pills a compact form at narrow widths (mirroring the DOCUMENT-context ⌃/⌥ pill columns' full/compact behavior) to free enough budget for the FILE_TREE-context core-nav hint and `⌃B back` to survive down to parity with DOCUMENT context's ~40-col floor.

### ~~P1: FILE_TREE-context breadcrumb path can overflow the terminal width, corrupting the screen~~ FIXED
Found immediately after merging the fix above, via direct `hangon` re-verification (not an LLM guess) of the ORIGINAL bug report that started this whole discoverability thread: with the tree open and focused at 40×15, navigating to an entry whose path is a realistic length (even something as short as `.claude`, 7 characters) pushed the hint row's breadcrumb + `Open ⌃O` + `Commands ⌃␣` past 40 columns. The terminal wrapped the overflow onto a phantom row it didn't have room for, which scrolled the whole screen up by one line — pushing the tab bar (row 1) off the top entirely. This is the exact same failure *class* QA-REG-179 fixed for the DOCUMENT-context status bar's multi-cursor indicator, in a different branch of the same function.

**Root cause:** `Renderer.pm::_render_context_status_bar`'s tree-focused branch built `$left_text` (the breadcrumb, from `$tree->cursor_node->{path}`, completely unbounded) and pushed it to the output buffer BEFORE `$open_width`/`$palette_width`/`$right_width` (the fixed Open+Commands pills) were even computed — there was no path where the breadcrumb's length was ever checked against how much room the fixed right-side chrome actually needed. Unlike the `$message` branch a few lines above in the same function (which already truncates with `_ellipsis($message, $max_msg_width, 'start')`), the tree-breadcrumb path never got the equivalent treatment.

**Fix:** Moved the `$open_width`/`$palette_width`/`$right_width` computation before the breadcrumb is built, then bound `$node_path` to `_ellipsis($node_path, $max_path_width, 'start')` (ellipsizing from the start so the tail — the file/dir's own name, the most useful part of a nested path — stays visible), where `$max_path_width` is whatever's left after the fixed right-side pills and the icon/spacing overhead; drops to an empty string rather than a negative-width substr if there's truly no room at all. Matches the existing message-truncation idiom in the same function rather than inventing a new pattern.

**Tests:** `tests/renderer.t` — a property sweep across 5 path lengths (empty, single-char, short realistic, nested realistic, and a deliberately long deep path) × 6 widths (40-120) × both nerd-font modes asserting the row never exceeds `$cols`, plus a dedicated test confirming the ellipsized breadcrumb keeps the filename tail visible rather than going silently empty. Confirmed the property sweep fails against the pre-fix code (empty path alone already exceeds `$cols` below ~32-38 cols depending on nerd-font mode — this is a separate, pre-existing structural floor matching the codebase's own documented "Commands pill alone can't fit below ~25 cols" limit for DOCUMENT context, not a gap in this fix; the sweep's width range starts at 40, the same "essential chrome" floor used elsewhere).

**QA:** `qa/scripts/tier1/reg_186_filetree_breadcrumb_overflow.sh` (`QA-REG-186`) — opens a directory containing a `.claude`-style entry at 40×15 and confirms the tab bar (row 1) is still the first captured line (not scrolled off) and the `Commands` pill is still visible somewhere on screen. Note on assertion design: a terminal's soft-wrap can never itself produce a captured line WIDER than the terminal's column count (that's what wrapping is), so "is the last line <= cols" is not a valid signal — confirmed it passes even against the unpatched binary. The real, observable symptom is the SCROLL corruption (row 1 pushed off-screen), which is what this script actually checks. Confirmed the script fails against the pre-fix binary and passes after, run standalone 3× with no flakiness.

**Interactive verification (`hangon`):** confirmed at 40×15 with `.claude` (short realistic path) and a deliberately deep nested path (`aaaaaaaa/bbbbbbbb/cccccccc/somefile.txt`) — both now show a clean single-line ellipsized breadcrumb (`…ude` / `…ccc`) with `Open ⌃O`/`Commands ⌃␣` intact and no wrap. Confirmed no regression at 100 cols: the full un-ellipsized path renders normally alongside the tree-nav hints.

### P2: Status bar / tab bar chrome does not pick up the light theme's background colors (pre-existing, found incidentally, not fixed here)
Found while verifying the FILE_TREE fix above in light theme via `hangon`: switching to light theme (command palette → "Theme: Light") correctly re-themes the editor content area (gutter, ruler, line backgrounds all turn light) but the tab bar and status bar rows stay on the dark-theme's navy background in every context tested (DOCUMENT and FILE_TREE, both nerd-font and ASCII mode) — confirmed via screenshot in multiple combinations. Text/pill labels remain legible (light-colored text on the stuck-dark background), so this is a cosmetic/visual-consistency bug, not a discoverability regression — every hint added by the fix above is still fully visible and legible in light theme, just on the wrong-colored bar.

**Confirmed NOT caused by, or specific to, this session's FILE_TREE change:** reproduced identically after `git stash`-ing every uncommitted change in the worktree (both this fix and an unrelated in-flight "Tabby redesign" WIP from a concurrent session) and rebuilding from the last commit (`847c144`) — the dark chrome / light content mismatch is present on that clean, fully-committed baseline. Also confirmed `Zepto::Theme->light_theme()->color('status_bg')` returns the correct light escape sequence (`\x1b[48;2;220;224;232m`) at the module level, so the theme DATA is right; something in the status-bar/tab-bar render or theme-propagation path isn't picking it up. Not investigated further — out of scope for the FILE_TREE task this was found during; candidate starting point is checking whether `_render_tab_bar`'s theme-keyed cache (`_tab_bar_cache_get`/`_set`) or an equivalent path for `_render_context_status_bar` is holding a stale theme reference across the switch, versus a genuine escape-sequence/rendering-order bug.

**Note on environment:** this worktree was found to be concurrently shared with at least one other active agent session mid-edit (a "Tabby redesign" changing `_render_tab_bar`'s tab-cap glyphs and several `Theme.pm` tab colors) during this task — a `git stash`/`git stash pop` round-trip used to isolate this bug's repro collided with their live edits and briefly lost this session's own uncommitted FILE_TREE changes before they were manually reconstructed and re-verified. Worth flagging for whoever owns worktree provisioning: `git stash` is unsafe to use in a worktree that isn't exclusively single-writer.

## Light-theme "dark background fill" investigation (2026-08-30) — investigated, NOT a product bug; `hangon screenshot` rendering artifact identified

Assigned as a reported P1: "switch to light theme on a file shorter than the terminal height and every row/column past the document content renders with a solid dark-navy background instead of light theme's white/near-white, invisible in dark theme only because it coincidentally looks right there." The report cited a direct (non-LLM) screenshot as confirmation. Investigated thoroughly and **did not reproduce this as a real, terminal-visible Zepto bug** — full write-up below because the false-positive mechanism is subtle and worth protecting future investigators from repeating.

**Code audit found nothing wrong.** Every fill/pad site in `Renderer.pm` that could plausibly own this — the "empty line, beyond document" branch in `_render_text_area` (uses `$theme->color('empty_line_bg')`), the beyond-EOF gutter fallback (`gutter_bg`/`gutter_fg`), the right-of-content fill on real content rows (`$theme->color('bg')`), and the status bar's own gap-fill (`status_bg`) — all reference theme roles that exist and are correctly defined for both themes in `Theme.pm` (light `empty_line_bg` = near-white `bg_rgb(250,250,252)`, dark = near-black `bg_rgb(20,21,30)`; the task's own hypothesis (a) — a stale/wrong role name like `editor_bg` instead of `bg` — does NOT hold for this path; that exact typo *does* exist at Renderer.pm:2187 but only in the unrelated Markdown-inline-image spacer-row path, is a real latent bug in its own right, and is now tracked separately below).

**Byte-level verification confirmed the renderer's actual output is correct.** Called `Zepto::Renderer->render()` directly (bypassing the live editor entirely) for a 2-line file in light theme at 24×80 and inspected the raw bytes: every below-EOF row emits `\x1b[48;2;250;250;252m` (light theme's exact `empty_line_bg`) followed by space-padding to the full column width, `\x1b[K`, `\x1b[0m` — byte-perfect, theme-correct, every time, for every row, at multiple sizes.

**The live editor, via `hangon`, DOES show a solid dark-navy rectangle in the screenshot PNG** in this exact scenario (confirmed — this part of the report is accurate as a screenshot observation). But cross-checking the *actual terminal state* underneath that screenshot — `tmux capture-pane -e -p` against the live session, which reads tmux's own internally-tracked per-cell SGR attributes rather than replaying/re-parsing the byte stream — showed the CORRECT color (`48;2;250;250;252`, light theme's near-white) in every one of those cells, at the exact same moment the screenshot showed them dark. tmux is the authoritative terminal in this chain (any real terminal app — iTerm2, Terminal.app, Alacritty, an SSH client — attached to that tmux session receives tmux's own re-serialized, correct output, not a replay of Zepto's original bytes); its independently-verified correct state means a real user would see the light background, not the screenshot's dark one.

**Root-caused the discrepancy to `hangon screenshot`'s own rendering, not to Zepto:** replayed the *exact* raw bytes captured from `Renderer->render()`'s output through a bare `bash`+`cat` session (no Zepto involved at all) and screenshotted that. A small slice of the frame (content rows + a handful of empty rows) rendered perfectly. The full 24-row frame — tab bar + ruler + content + empty rows + status bar, i.e. exactly what a real editor session sends — reproduced the same dark rectangle, with **zero Zepto code in the loop**: this is deterministic and 100% reproducible from raw bytes alone. Bisected which rows are required to trigger it (ruler row AND status bar row must both be present in the same frame; either alone is fine) and ruled out both of the obvious general theories: total byte size (a 8.7KB synthetic all-ASCII payload with more rows and more distinct colors than Zepto's frame rendered perfectly) and total distinct-color count (a labeled 24-row/13-color synthetic sweep, deliberately harder than Zepto's real 7-color frame, rendered every row's color correctly — an earlier unlabeled version of that same test *looked* wrong at a glance but was a misread on inspection, i.e. exactly the kind of screenshot-trust mistake this write-up exists to prevent). Sampled actual PNG pixel RGB values (via PIL) rather than relying on further eyeballing: the "dark" region in the broken screenshots is `rgb(30,30,46)` — a color that **does not appear anywhere in either Zepto theme** (`Theme.pm`'s closest values are `bg_rgb(26,27,38)`/`bg_rgb(20,21,30)` for dark, nothing near it for light) — and matches exactly the plain background color `hangon screenshot` uses for a cell it never received a color update for (confirmed by sampling the margin/empty area of an unrelated, totally blank `hangon` session). I.e. for specific full-editor-sized frames, `hangon screenshot`'s own image renderer is silently failing to apply some cells' background-color SGR codes and falling back to its own internal default — which happens to be dark navy, which is why this only reads as "wrong" in light theme and was invisible in dark theme, exactly matching the original report's own reasoning for why it went unnoticed. That reasoning was correct; the culprit it pointed to was not.

**Not fixed here — there is nothing in Zepto to fix.** No change made to `Renderer.pm`'s or `Theme.pm`'s background-fill logic; a code change against a correctly-verified-correct code path would be pure risk with no offsetting benefit, and CLAUDE.md Rule 5 ("reproduce first") could not be satisfied against the authoritative ground truth (tmux's own tracked state). The one real, separate, latent bug turned up by the code audit (`editor_bg` typo, Markdown image-spacer rows only) is filed on its own below.

**For future investigators:** `hangon screenshot` is the right tool for almost everything (per CLAUDE.md's Rule 2 mandate) and this is the first confirmed case of it producing a flatly wrong pixel color rather than a merely-hard-to-read one. When a claimed bug is specifically about *background color/fill* covering a large fraction of a full-size frame (tab bar + ruler + status bar all present) and doesn't reproduce in a small/isolated repro, cross-check with `tmux capture-pane -e -p -t <hangon session's tmux session>` (session name is `hangon-<holder PID>` from `hangon status <name>`) before trusting the screenshot — it shows tmux's own tracked cell colors as raw SGR codes and is the authoritative source of what a real attached terminal would render.

### ~~P3: `editor_bg` — stale/nonexistent theme role name in the Markdown inline-image spacer-row path~~ FIXED

Found via code audit while investigating the light-theme background-fill report above (see that entry for the negative result on the actual reported bug). `Renderer.pm:2187`, inside `_render_text_area`'s handling of blank spacer rows reserved for inline Markdown image placement (`$entry->{type} eq 'image_spacer'`), read `my $bg = $theme->color('editor_bg');`. No theme in `Theme.pm` defines an `editor_bg` role (the correct/only role for the main text-area background is `bg`) — `Theme::color()` returns `''` for an unknown role (`$self->{colors}{$role} // ''`), so this line silently emitted *no* background-color escape code at all for the spacer row's text-area fill, in both themes. Unlike the false-positive above, this is a genuine latent defect matching the task's own hypothesis (a) — just in a different, narrower code path (Markdown files with inline images, kitty-graphics-capable terminals only, on spacer rows specifically) than the one reported. Not otherwise user-visible in most terminals/themes tested so far (terminal default background often coincidentally reads as acceptable, the same masking effect described above), but a real bug in its own right.

**Fix:** Changed to `$theme->color('bg')`, matching every other text-area fill site in the file. Verified test-before/fix/test-after: reverted the one-line change and confirmed the new QA script (`QA-REG-175`) fails, then restored it and confirmed it passes. Covered by `tests/renderer.t` and `qa/scripts/tier1/reg_175_image_spacer_bg.sh` (a Markdown file with an inline image, light theme).

## Tab bar visual redesign (2026-08-30)

### ~~P2: Tabs "really don't look great" — inactive tabs have no visible boundary, active tab is a flat rectangle~~ FIXED (2026-08-30)
User feedback, confirmed via a zoomed-in screenshot crop of `Renderer.pm::_render_tab_bar`: (1) inactive tabs had **no background fill at all** — `tab_inactive_bg` (40,44,62 dark / 210,214,226 light) sat at only 1.17:1 / 1.19:1 contrast against `tab_bar_bg`, so an inactive tab was just underlined plain text on the same background as the surrounding toolbar strip, not a distinct clickable region; (2) the tab "shape" came from `◢`/`◣` diagonal-corner glyphs (U+25E2/25E3) that each filled only a 1-cell diagonal wedge — confirmed nearly invisible at normal (non-zoomed) viewing size; (3) the only separation between adjacent tabs was a single space, so the row read as one continuous strip rather than distinct elements.

**Fix — two parts:**
1. `Theme.pm`: bumped `tab_inactive_bg`/`tab_inactive_edge` and `tab_hover_bg`/`tab_hover_edge` for both themes to ~1.5-1.8:1 contrast against `tab_bar_bg` (dark: 40,44,62 → 66,72,100; light: 210,214,226 → 184,189,206), and brightened/darkened the fg colors that render on top (`tab_inactive_fg`, `tab_hover_fg`, `tab_close_fg`, `tab_shortcut_fg`, `tab_modified_fg`, `tab_vcs_fg`) so every one stays at or above WCAG 3:1 against all three tab surfaces (active/inactive/hover) — verified with a small contrast-ratio script before touching the theme file, not by eye. `tab_active_bg` itself was left alone: in the dark theme it's already fairly low-key (2.03:1 against the bar), which caps how much brighter `tab_inactive_bg` can go while keeping the active tab reading as the most prominent by fill color — an explicit, acknowledged tradeoff, compensated by the underline-baseline break below.
2. `Renderer.pm::_render_tab_bar`: replaced the `◢`/`◣` diagonal-corner glyphs with a single full-block glyph (`█`, U+2588 — already used elsewhere in this file for the VCS gutter's expanded-hunk indicator, so no new font dependency) as both edge caps, for every tab state. An interim design tried a half-filled taper cap (`▐`/`▌`) for inactive/hover tabs specifically so the active tab's crisp full-block edge would stand out by comparison, but a side-by-side screenshot check showed the half-fill was counterproductive — it puts the *surrounding bar color* into half of the one cell doing the most work to signal "this is a tab boundary," diluting exactly the contrast this fix exists to add. Settled on full-block caps everywhere; active/inactive/hover are now told apart purely by fill-color contrast and by the existing underline-baseline break under the active tab (unchanged — the underline running across the bar stops exactly under the active tab's body, visually "detaching" it and merging it into the ruler below). `_calc_tab_pill_width` and `_truncate_tab_names` needed no changes — the cap glyph is still exactly 1 column either way.

Every existing functional element was preserved and re-verified after the redesign: dirty-dot indicator, `⌥N` tab-number shortcuts, `×` close button (with its existing click hit-testing), scroll-left/right arrows on overflow, and tab drag-to-reorder start. Verified interactively via `hangon` in both themes, at 1/2/many(overflow+scroll) tabs, with a dirty tab, with the active tab first/middle/last, and with mouse clicks on a tab body (switches active tab) and on a close button (closes that tab, not a neighbor) — screenshots (including 3x zoomed crops of just the tab-bar row) confirmed the redesign reads as distinct, bounded "tabs" at normal viewing size in both themes, not just the active one. `tests/renderer.t` gained 4 new subtests: cap-glyph presence/absence, inactive-bg-differs-from-bar-bg (at the theme level, so it fails if the fix is ever reverted), tab/close button ordering and containment after the redesign, and scroll-button presence on overflow. QA: `QA-REG-180`/`181`/`182` in `qa/scripts/tier1/` + `qa/40_regression_bugs.txt`, and `qa/21_tabs.txt`'s `QA-TAB-001` updated to describe the new visual design.

### ~~P2: Full-block tab caps reverted back to ◢/◣ triangles — the "nearly invisible" premise was a `hangon screenshot` rendering bug, not real~~ FIXED (2026-08-30, same day as the redesign above)
The redesign above was built on a real observation (a zoomed *hangon screenshot* crop showing the ◢/◣ glyphs as a barely-visible 1-cell wedge) but a wrong root cause. The user checked their own real terminal directly: the same ◢/◣ characters render as full-height, cell-filling triangles there, exactly as intended — hangon's screenshot renderer was under-rendering them, not the terminal. Confirmed and fixed in `hangon` itself: it drew geometric-shape characters (U+25E2-25E5) via ordinary font glyph outlines (a small centered dingbat, the way a generic font treats them) instead of procedurally the way real terminal emulators render box-drawing/geometric-shape characters — fixed by special-casing these four characters to draw as full-cell vector polygons instead of `<text>` glyphs (see `hangon`'s own CHANGELOG, "Fix three screenshot PNG rendering bugs", commit `df2b84d`). Re-verified pixel-by-pixel against the fix (corner-pixel sampling confirmed correct fill and orientation for all four triangle orientations) before trusting it.

**Fix:** Reverted `Renderer.pm::_render_tab_bar`'s cap glyph from the full-block `█` back to `◢`/`◣` (`$TAB_CAP_LEFT`/`$TAB_CAP_RIGHT`), re-verified visually with the now-fixed `hangon screenshot` — the triangles correctly render as a full trapezoidal tab shape (arguably reading as *more* "tabby" than the flat-rectangle full-block version, since it's a genuine slanted parallelogram rather than a plain box). The one independently-real fix the original redesign made — `tab_inactive_bg`/`tab_hover_bg` given actual background fill instead of none at all (~1.17-1.19:1 → ~1.5-1.8:1 contrast against `tab_bar_bg`) — is unrelated to cap glyph shape and was kept unchanged.

**Tests:** `tests/renderer.t`'s cap-glyph subtest re-reverted to assert `◢`/`◣` presence (was asserting their absence + `█` presence). `qa/scripts/tier1/reg_180_tab_cap_glyph.sh` (`QA-REG-180`) similarly re-reverted. Both still pass; full `make test` (1163 tests) and `make check` clean.

**Follow-up:** the revert itself introduced a regression — 6 `sess_*` session-restore QA scripts and 2 mouse-click scripts (`ms_009`/`ms_010`) plus `reg_182` had hardcoded the full-block `█` as a tab-bar-vs-file-tree-sidebar disambiguation anchor for their screen assertions, so they broke the moment `█` reverted back to `◢`/`◣`. Caught via a full post-revert `make qa` run, fixed via targeted codepoint substitution (`◢` for `█`) across all 9 scripts, verified via targeted reruns plus full `make test`/`make check`. Committed separately as `fd218d9`.

**Broader lesson — screenshot-tool trust chain now closed for the three specific defects that misled decisions this session:** this is the third distinct `hangon screenshot` rendering bug found and fixed this session (the other two: a solid wrong-color background rectangle on light-theme full frames, traced to a missing `-N` flag on `tmux capture-pane` silently trimming trailing-whitespace cells' background color along with the whitespace; and visible hairline gaps between character cells on light backgrounds, traced to an SVG rasterization conflation artifact from emitting one `<rect>` per cell instead of merging same-color runs). All three are now fixed and independently pixel-verified against `tmux capture-pane -e -p -N`'s authoritative per-cell state. The earlier "light-theme black background" investigation in this file (search "Light-theme \"dark background fill\" investigation") correctly identified the screenshot tool as the culprit but didn't yet have a fix for it — it does now.

**Found incidentally, not fixed (out of scope for this visual redesign) — logged per the "log bugs found while working on something else" rule:**

### P2: Tab drag-to-reorder and mouse-wheel tab-cycling gate on the wrong row
`Editor.pm::_handle_tab_drag` (`return unless $y == 2`) and the `scroll` action handler's tab-cycling branch (`if ($y == 2) { ... cmd_prev_tab/cmd_next_tab ... }`, comment: "Scroll on tab bar — cycle through tabs") both check row 2. But the tab bar is row 1 everywhere else in this file — `handle_mouse_event`'s `press` handler checks `$y == 1` for tab-bar clicks, and `_update_hover` checks `$y == 1` for tab hover — and row 2 is explicitly the *ruler* bar (`Renderer.pm`'s own layout comment: "Render tab bar (row 1 = index 0)" then "ruler bar goes to row 2"). Net effect: dragging a tab to reorder it only continues if the drag crosses down into the ruler row, not while dragging along the tab bar itself; scrolling the mouse wheel while hovering the actual tab bar does nothing, but scrolling while hovering the ruler row (one row below the tabs) cycles tabs — the opposite of both features' own comments. Not touched here — unrelated to the visual redesign and its own fix/test cycle; flagging with exact locations for whoever picks it up.

---

## Scorecard audit round 2 (2026-08-30) — full findings from a 5-agent parallel re-audit

Findings from a fresh codebase scorecard (architecture, code quality, security, tests/docs, performance/duplication), run as a before/after comparison after the substantial fixing this session already did. Overall grade: **B-**. Every item below is newly found this round — not a re-report of anything already tracked/fixed elsewhere in this file. Each will be marked FIXED with a root-cause/fix/test writeup by whichever agent picks it up, following this file's normal convention.

### Availability / hang risk (P1)

### ~~P1: `cmd_transform` (⌥T, "Transform via Shell") can deadlock the whole editor~~ FIXED
`Editor/Commands.pm:1058-1069` reads the child's stdout to EOF via `IPC::Open3` *before* reading stderr at all. If the user's shell command writes enough to stderr to fill the OS pipe buffer (~64KB) while also writing to stdout, the child blocks writing to a full stderr pipe nobody is reading yet, while the parent blocks reading stdout waiting for the child to close it — the classic `IPC::Open3` synchronous-read deadlock `perldoc IPC::Open3` itself warns about. Since raw mode disables `ISIG` (`Terminal.pm:143`), the user cannot Ctrl-C out — the whole process hangs. Fix: read both handles concurrently (`IO::Select`) or via a non-blocking loop instead of sequential blocking reads.

**Root cause:** confirmed exactly as described — `cmd_transform`'s `eval` block did `$output = <$out_fh>;` (a full blocking slurp of stdout to EOF) followed only afterward by `$stderr_text = <$err_fh>;`. Reproduced first with a standalone repro (`perl -e 'print STDOUT "x"x100; print STDERR "e"x100000; print STDOUT "y"x100'` piped through the old code path) and via a real interactive `hangon` session: the whole editor froze past the ~64KB stderr pipe-buffer threshold, with no Ctrl-C recovery, exactly as reported.

**Fix:** replaced the two sequential blocking reads with an `IO::Select`-driven loop that alternates `sysread()` on whichever of stdout/stderr is actually ready (`$sel->can_read`), removing each handle from the select set on EOF, so neither pipe can ever back up while the other is starved. `$output`/`$stderr_text` now accumulate via string concatenation across possibly-many `sysread` calls instead of one `<$fh>` slurp each. Added `use IO::Select;` alongside the existing `use IPC::Open3;`.

**Tests:** `tests/transform_deadlock.t` — calls `cmd_transform`'s `on_submit` directly with the exact stderr-flooding shell command, wrapped in an outer `alarm(8)` safety net (needed because `cmd_transform`'s own `eval` swallows an alarm-interrupted blocked read as a generic "Transform failed" and returns normally either way — so the real signal is elapsed wall-clock time, not exception propagation). Confirmed this test fails correctly against the pre-fix code first (blocked for the full 8s alarm bound, wrong/unchanged document content) before making the fix, then passes in ~0s after.

**Interactive verification (`hangon`):** ran the exact deadlock shell command live via the real `⌥T` → "Transform via Shell" flow — completed instantly (buffer replaced with the expected `x`×100 + `y`×100), no freeze. Also verified normal transform usage (`tr a-z A-Z`) still works correctly with the new concurrent-read implementation, confirming the rewrite didn't regress the common case.

**QA:** `qa/scripts/tier1/reg_187_transform_shell_deadlock.sh` (`QA-REG-187`) — runs the real binary end-to-end via the palette, sends the stderr-flooding command, and polls (bounded, not a fixed sleep) for the transformed output to appear.

### ~~P1: Clipboard paste has no timeout — a hung paste command freezes the UI indefinitely~~ FIXED
`Terminal.pm:604-622` (`paste_from_clipboard`, called synchronously from `cmd_paste`, `Editor/Commands.pm:477-478`) forks/execs the platform paste command (`pbpaste`/`xclip -o`/`wl-paste`/`powershell.exe -command Get-Clipboard`) and does a blocking `<$fh>` slurp with **no `alarm()`/timeout**, unlike `FindEngine.pm`'s `MATCH_ALARM_SECS`-guarded regex paths or `FileSearchEngine.pm`'s equivalent guard. A hung paste command (e.g. `wl-paste` with no reachable Wayland compositor over SSH, or a wedged `powershell.exe` under WSL) freezes the whole editor with no recovery path. Fix: wrap the read in the same `alarm()`-guard pattern already established elsewhere in the codebase.

**Root cause:** confirmed — `paste_from_clipboard` did `my $text = do { local $/; <$fh> };` with no alarm guard at all. Reproduced first with a standalone repro script (a bare blocking slurp against a `sleep 3` child, no alarm) that blocked for the full duration with no way to recover before the child exits, matching the reported failure mode exactly.

**Fix:** added `CLIPBOARD_PASTE_ALARM_SECS => 3` and wrapped the blocking slurp in the same `local $SIG{ALRM} = sub { die ... }; alarm(N); ...; alarm(0);` idiom `FindEngine.pm::_match_with_alarm` established, including the `alarm(0)` safety net outside the `eval` so no alarm is ever left armed. On timeout: `kill('TERM', $pid)` + `waitpid($pid, 0)` to avoid leaving a zombie, then returns `undef` — a return value distinct from `''` (empty clipboard), so callers can tell "nothing to paste" apart from "the read timed out." `cmd_paste` (`Editor/Commands.pm`) now checks `!defined $text` first and calls `show_error_message(_user_error("Paste failed", "clipboard read timed out"))` before falling through to the empty/non-empty-text branches — the existing `_user_error()`/`show_error_message()` pattern, no new error-reporting mechanism introduced.

**Tests:** `tests/terminal.t` "paste_from_clipboard times out on a hung clipboard command" — overrides `$term->{_clipboard_paste_cmd} = ['sleep', '30']` (a real hang, portable, no macOS/Linux-specific flags) and asserts the call returns `undef` and completes in well under 30s (bounded by the real 3s alarm plus margin) — a genuine real-timing assertion, not a mocked timer.

**Interactive verification (`hangon`):** confirmed normal `⌃V` paste still works correctly post-fix (status bar showed "Pasted", pasted text landed correctly) — sanity check that the added `!defined $text` branch didn't regress the common path. The actual hang-recovery scenario is verified end-to-end (real binary, real Ctrl+V, real hung clipboard command) by the QA script below.

**QA:** `qa/scripts/tier1/reg_188_clipboard_paste_timeout.sh` (`QA-REG-188`) — shadows every clipboard-paste command `Terminal.pm::_detect_clipboard_commands` might pick (`pbpaste`, `xclip -o`, `xsel --output`, `wl-paste`) with fakes that sleep 30s, placed earlier in `PATH` than the real tools (confirmed `PATH` is inherited by freshly-started `hangon` sessions), presses a real `⌃V` in the compiled binary, and asserts the "Paste failed" message appears within 8s and the editor remains responsive afterward (typed text lands normally).

### ~~P1: Clipboard copy has no timeout — a hung copy command freezes the UI indefinitely~~ FIXED
Found in a follow-up scorecard audit (2026-08-31), the exact copy-direction sibling of the paste bug above. `Terminal.pm:567-595` (`copy_to_clipboard`, called synchronously from `cmd_cut`/`cmd_copy`, `Editor/Commands.pm`) forks/execs the platform clipboard-copy command (`pbcopy`/`xclip`/`wl-copy`) and does `print $pipe $bytes; close $pipe;` with **no `alarm()`/timeout**, unlike `paste_from_clipboard`'s `CLIPBOARD_PASTE_ALARM_SECS`-guarded read. `close` on a piped filehandle blocks until the child exits, so a wedged clipboard command (stuck, or blocked on a full pipe with a slow/stuck consumer) would freeze the whole editor with no recovery path — same failure mode as the paste bug, opposite direction.

**Root cause:** confirmed exactly as described — `copy_to_clipboard` had zero alarm/timeout guard around the pipe write+close. Reproduced first with `tests/terminal.t`'s new "copy_to_clipboard times out on a hung clipboard command" subtest, run against the pre-fix code: it took the full ~30s (child was `sleep 30`, and `close` blocked waiting for it to exit via the implicit `waitpid`) and both assertions failed (`copy_to_clipboard` returned `1` unconditionally instead of a distinct timeout sentinel, and did not return promptly). Also reproduced end-to-end via `qa/scripts/tier1/reg_222_clipboard_copy_timeout.sh` against the pre-fix binary: the editor genuinely froze — no "Copy failed" message and no typed text landed within the script's 8s bound.

**Fix:** added `CLIPBOARD_COPY_ALARM_SECS => 3` (mirrors `CLIPBOARD_PASTE_ALARM_SECS`) and wrapped `print $pipe $bytes; close $pipe;` in the same `local $SIG{ALRM} = sub { die ... }; alarm(N); ...; alarm(0);` idiom, with the unconditional `alarm(0)` safety net outside the `eval`. Unlike the paste case, the blocking operation here is `close` (which waits for the child to exit), not the `print`, so both are inside the guarded region. On timeout: `kill('TERM', $pid)`, a defensive `close($pipe)`, then `waitpid($pid, 0)` to reap, then returns `undef`. Return-value contract changed to three distinct outcomes so callers can tell them apart: `1` = wrote successfully, `''` = intentionally skipped (empty/undef text, or `_no_system_clipboard` set), `undef` = the platform command hung past the timeout. (Previously the two skip cases and success were conflated into a truthy/falsy pair nobody checked; now all five call sites do.) `cmd_cut` and `cmd_copy` (`Editor/Commands.pm`, all 5 call sites) now capture `copy_to_clipboard`'s return and call `show_error_message(_user_error("Cut"/"Copy", "system clipboard write timed out"))` when it's `undef`, otherwise show the normal "Cut"/"Copied" message — the existing `_user_error()`/`show_error_message()` pattern, no new mechanism. The internal cut/copy (document mutation, `$self->{clipboard}`) always completes regardless of the system clipboard's fate — only the status message differs, since OSC 52 already fired before the platform command was attempted, so a hang there doesn't mean the terminal-native copy failed too.

**Tests:** `tests/terminal.t` "copy_to_clipboard times out on a hung clipboard command" — overrides `$term->{_clipboard_copy_cmd} = ['sleep', '30']` (real hang, portable) and asserts the call returns `undef` and completes in well under 30s (bounded by the real 3s alarm plus margin). Confirmed failing (30s elapsed, returned `1` not `undef`) against pre-fix code first, then passing (~3s, returns `undef`) after the fix. Full suite: `make test` — 46 files, 1268 tests, ~32s, all green, no unexpected output.

**Interactive verification (`hangon`):** ran the exact hang scenario live (fake `pbcopy` shadowing the real one via `PATH`, real `⌃C`/`⌃X` in the compiled binary) — "Copy: system clipboard write timed out" / "Cut: system clipboard write timed out" appeared within ~4s, and the editor stayed fully responsive (typed text landed immediately after). Also verified the normal (non-hung) path with the real `pbcopy` still shows "Copied" with no regression.

**QA:** `qa/scripts/tier1/reg_222_clipboard_copy_timeout.sh` (`QA-REG-222`) — shadows every clipboard-copy command `Terminal.pm::_detect_clipboard_commands` might pick (`pbcopy`, `xclip`, `xsel`, `wl-copy`) with fakes that sleep 30s, placed earlier in `PATH` than the real tools, presses a real `⌃C` in the compiled binary, and asserts the timeout message appears within 8s and the editor remains responsive afterward. Confirmed failing against the pre-fix binary (froze for the full hang, no message, no responsiveness) before the fix, passing after.

### ~~P1: "Tab Width" preference has no effect on rendering existing tab characters~~ FIXED
`Renderer.pm:97` hardcodes `use constant TAB_WIDTH => 4;`, and all three tab-expansion functions (`_expand_tabs` L261, `_char_to_visual_col` L286, `visual_to_char_col` L316) use this constant, never the user's preference. `Editor.pm:4889` dutifully threads `tab_width => $self->{prefs}->tab_width()` into `WrapMap->new()`, and `WrapMap.pm:36` stores it in `$self->{tab_width}` — but that field is **never read anywhere** in `WrapMap.pm` (`wrap_line()` calls `Zepto::Renderer::_expand_tabs($line_content)` with no width argument). Net effect: the "Tab Width" preference (`cmd_set_tab_width`, `Editor/Commands.pm:1366`) only affects indentation *insertion* — it has zero effect on how a file's existing literal `\t` characters visually render, wrap, or how the cursor lands on them. Setting Tab Width to 2 or 8 and opening a tab-indented file still renders/wraps at 4 columns regardless. Distinct from the already-tracked "vestigial preferences" list, which does not mention `tab_width`.

**Root cause:** confirmed exactly as described, plus one additional gap found while fixing it: `Editor.pm`'s WrapMap-rebuild condition (`render()`) only rebuilt the `WrapMap` object when the *viewport width* changed (`$wm->{width} != $wrap_width`) — a `tab_width` preference change alone (same viewport width) left the existing `WrapMap` object in place with its stale `tab_width`, so even after threading the width through `WrapMap`/`Renderer` correctly, the palette command would have had zero *visible* effect until an unrelated resize or edit happened to trigger a rebuild. Confirmed via a live `hangon` repro before fixing: setting Tab Width to 2 on an already-open tab-indented file left the rendering unchanged.

**Fix:**
- `Renderer.pm`: `_expand_tabs`/`_char_to_visual_col`/`visual_to_char_col` now accept an optional trailing `$tab_width` argument (falls back to a package-level effective width `$_tab_width`, which itself falls back to `TAB_WIDTH` if unset/invalid — so every existing call site with no width argument keeps working unchanged). Added `set_tab_width($width)`, following the exact same "package-scoped `my` variable + `set_*` class method" pattern `Zepto::Chars::set_enabled`/`$_nerd_font_enabled` already established for a different per-render preference (nerd_font) — chosen over threading an explicit width parameter through all ~14 in-module call sites because it's the codebase's own existing precedent for "per-render-pass config synced from prefs," not a new pattern. `render()` now calls `$class->set_tab_width($prefs ? $prefs->tab_width() : undef)` right next to the existing "Sync Chars module with prefs" line.
- `WrapMap.pm`: its 4 call sites into `Zepto::Renderer::_expand_tabs`/`_char_to_visual_col`/`visual_to_char_col` now explicitly pass `$self->{tab_width}` (the value it already stored but never read) as the trailing argument, rather than relying on Renderer's package-level default — more robust than relying on render() having run first, since `wrap_line()`/`visual_to_doc()` etc. can be called independently of a full render pass.
- `Editor.pm`: the WrapMap-rebuild condition now also checks `$wm->{tab_width} != $self->{prefs}->tab_width()`, so a tab_width preference change alone triggers a rebuild (previously only a viewport-width change did).
- `Editor.pm`'s two mouse-click `visual_to_char_col` call sites (click-to-position, drag-select) now pass `$self->{prefs}->tab_width()` explicitly too, for the same "don't depend on a render having already synced the package default" robustness reason.

**Tests:** `tests/renderer.t` — three new subtests: explicit-width-argument correctness for all three helper functions (width 4 vs 8, would be identical under the old hardcoded constant), `set_tab_width()`'s package-level default behavior including its `<1` fallback to `TAB_WIDTH`, and an end-to-end `render()`-with-`$prefs` sync check (tab_width 2 then 8, confirms the helpers pick up each). `tests/wrapmap.t` unaffected/still passing (existing coverage). Confirmed the new subtests fail against the pre-fix code first (temporarily reverted the `render()` sync call and reran — `_expand_tabs`/etc. had no width parameter to even pass, and the width-2-vs-8 comparison showed identical output).

**Interactive verification (`hangon`, Rule 2, required for this one specifically):** opened a tab-indented test file (default Tab Width 4, tabs visibly at 4-col stops), used the command palette to set Tab Width to 2 — the file's existing tab-indented lines re-wrapped/re-rendered immediately at the new width (no edit, no resize, no reload needed). Repeated for Tab Width 8 — re-rendered again at the wider stop. Confirmed via a marker-column measurement (not just "screen changed"): a `MARKERTAB` token right after a leading tab moved from screen column 9 (width 2) to column 15 (width 8), an exact 6-column delta matching (8-2). Also reproduced the *bug* first, live: with the `render()` sync call temporarily reverted, the same steps left the marker's column completely unchanged across the Tab Width 2→8 change, confirming this is a real, user-visible fix, not a no-op.

**QA:** `qa/scripts/tier1/reg_189_tab_width_rerender.sh` (`QA-REG-189`) — the marker-column measurement above, run against the real compiled binary; confirmed to fail (delta 0, not 6) against the pre-fix code before this fix and pass after. Cross-referenced from `QA-PREF-007` (`qa/36_preferences.txt`, tab width on insertion) via `qa/40_regression_bugs.txt`.

### ~~P3: `Preferences::visual_width` divides by zero on `tab_width == 0`~~ FIXED
See "P3: 5 confirmed-dead subs" below for the original combined finding — split out here since it got its own root-cause/fix/test writeup. `Preferences.pm:310` — `Preferences::set()` performed zero validation on any preference value. A hand-edited `tab_width: 0` in `preferences.json` (which is intentionally hand-editable per this project's docs) causes an uncaught fatal on the next `visual_width()` call.

**Root cause:** confirmed — `set()` wrote `$self->{prefs}{$key} = $value` with no validation of any kind. Additionally, while fixing this, found that `set()`-only validation would NOT have actually closed the gap the bug describes: `_load_from_store()` (the startup-load-from-disk path — the literal scenario of a hand-edited `preferences.json`) writes directly into `$self->{prefs}{$key}`, bypassing `set()` entirely, and `_apply_external_changes()` (cross-instance sync via `StateStore`'s `on_change`) does the same. A test written against `set()`-only validation would have passed while the actual reported scenario (hand-edited file, loaded at startup) remained completely unprotected — caught by writing the load-path regression test first and confirming it failed.

**Fix:** extracted a shared `_validate_value($key, $value)` function (for `tab_width`: clamps to `1` if undefined, non-numeric, or `< 1`) and call it from all three paths that can populate `$self->{prefs}{tab_width}`: `set()`, `_load_from_store()`, and `_apply_external_changes()`. Clamps rather than rejecting outright, so a bogus edit degrades gracefully instead of silently discarding the whole preference write. As a second layer of defense, `visual_width()` itself also now clamps its own `$tab_width` (whether from `$self->tab_width()` or an explicit override argument) to `>= 1` before using it in a modulus — belt-and-suspenders in case some future caller ever bypasses both `set()` and load, e.g. by passing an explicit override.

**Tests:** `tests/preferences.t` — `set('tab_width', 0)`/`(-5)`/`('not_a_number')` all clamp to `1`; a valid positive value still sets normally; `visual_width()` after a clamped `set()` doesn't die. A separate subtest specifically covers the load-path gap: seeds `tab_width => 0` directly via `$store->put('preferences', {...})` (not via `set()`), constructs a fresh `Preferences->new(state_store => $store)`, and confirms the loaded value is `1`, not `0` — confirmed this subtest fails against the pre-fix `_load_from_store()` (returns `0`, unclamped) before wiring `_validate_value()` into that path, and passes after. A third subtest covers `visual_width()`'s own defensive guard directly with explicit `0`/negative override arguments.

**QA:** `qa/scripts/tier1/reg_190_tab_width_zero_clamp.sh` (`QA-REG-190`) — pre-seeds `{"tab_width": 0}` directly into `$state_dir/preferences.json` (simulating a hand edit, not a `set()` call), launches the real compiled binary, confirms it starts up without crashing, and confirms the "Tab Width" palette command's prefilled value shows the clamped `1`, not `0`.

### ~~P1: `qa/scripts/tier1/sec_001_path_traversal.sh` cannot fail under any outcome~~ FIXED
Confirmed the most severe of the tautological-test findings below because it's tagged security: the script typed a path (`/tmp/../tmp/zepto_qa_sec001_safe.txt`, which normalizes right back into `/tmp` — not a real traversal-outside-root attempt) and had **no `qa_fail` branch anywhere** — both the success and the "possibly rejected" fallback branch called `qa_pass`.

**Investigation:** Before rewriting, checked what root-confinement Save-As actually has. `Editor/Commands.pm::cmd_save_as`/`_finish_save_as` write to whatever path the user types with zero root confinement — by design, like every desktop editor's Save As; there is no "sandbox" for it to escape, so a traversal test against it can never be meaningful. The real, documented path-traversal protection in this app is `FileTree.pm`'s `_path_within_root()` (`Cwd::realpath()` + `index($real, "$root/") == 0`, audited in `docs/SECURITY.md`'s P3 symlink-traversal entry). It's implemented independently in two places: `_scan_dir_one_level()` (interactive tree widget, already covered by `QA-SEC-003`/`sec_003_symlink.sh`) and `_walk_for_files()` (the Ctrl+O "Open File" fuzzy picker's file list, via `_filter_all_files()` in `Editor/Palette.pm` — not covered by any existing script).

**Fix:** Rewrote the script to target the uncovered code path. Sandbox: a `qa_project` temp dir with a real file plus a symlink pointing to a separate outside directory containing a "secret" file. Open Ctrl+O with no typed query (so the picker's own screen rendering is the only source of the assertions — nothing typed can leak into them) and assert the in-project file IS listed (sanity: catches a broken/no-op picker) while the file only reachable through the escaping symlink is NOT listed.

**Verified non-tautological (Rule 5):** disabled the `next if -l $full && !$self->_path_within_root($full)` guard in `FileTree.pm::_walk_for_files` (`0 &&` prefix), rebuilt — script correctly failed (`secret_outside_sec001.txt` appeared in the picker via `escape_link_sec001/`). Restored the guard, rebuilt — passes again. Ran standalone 3x clean.

**Note:** `qa/38_security.txt`'s own `QA-SEC-001` entry text ("No shell injection in VCS operations") doesn't match what this script (or the bugs.md audit finding) describes — a pre-existing ID/description drift in the QA docs, not introduced or fixed here. Flagged for a future pass rather than fixed in this session (out of scope — same drift pattern also found on `QA-NAV-010` and `QA-GUT-002` below).

### Security (P2)

### ~~P2: `ImageConverter.pm` uses a predictable temp filename with no exclusive creation — symlink-follow risk~~ FIXED
`ImageConverter.pm:76` built `"$tmpdir/zepto-img-$$-$basename"` via string concatenation — a predictable path in the shared `/tmp`, with no `O_EXCL`/exclusive creation — then ran `sips`/`convert` against it (`ImageConverter.pm:71-93`). Unlike `Document.pm`'s save path (which correctly uses `File::Temp` for exactly this reason), `sips`/`convert` would follow a pre-existing symlink at that predictable path. On a shared multi-user host, another local user who can observe the PID (`ps`) and the image's basename could pre-plant a symlink pointing at a file the victim can write (e.g. `~/.bashrc`), causing the victim's own image-preview invocation to overwrite that target through the symlink.

**Root cause confirmed real, not theoretical:** manually reproduced on macOS — planted a symlink at a predicted `zepto-img-$$-<basename>.png` path pointing at a victim file, ran `sips -s format png src.jpg --out <symlink>`, and the victim file's content was silently replaced with PNG bytes while the symlink itself stayed intact. `convert` (ImageMagick) exhibits the same behavior.

**Fix:** `ensure_png()` now uses `File::Temp::tempfile('zepto-img-XXXXXXXX', DIR => $tmpdir, SUFFIX => '.png', UNLINK => 0)` — unpredictable name, exclusive `O_EXCL`-backed creation — matching `Document.pm`'s existing atomic-save precedent exactly. Verified `SUFFIX => '.png'` doesn't change behavior: both `sips` and ImageMagick `convert` honor the explicit format flag (`-s format png`) / `PNG:` prefix regardless of the actual output filename's extension — confirmed empirically with real JPEG→PNG conversions at extensionless, `.tmp`-suffixed, and `.png`-suffixed output paths; `sips` only emits a (already-suppressed) stderr warning for a non-`.png` suffix, never a functional failure.

**Tests:** `tests/image_converter.t` — three subtests: normal conversion still produces a valid PNG; the output path no longer matches the old predictable `"zepto-img-$$-basename"` pattern (uses the new random-suffix pattern instead); and the direct attack repro — pre-plants a symlink at the exact old predictable path pointing at a victim file, runs a real conversion, and confirms the victim file is never touched. Confirmed test-before/fix/test-after: reverted the fix and re-ran — the naming and symlink-follow subtests both correctly failed (the symlink-follow subtest initially gave a false pass on the very first attempt because `ensure_png()`'s own per-source-file result cache short-circuited the second conversion call when reusing the same source file across subtests — fixed by using a fresh, uniquely-named source file for that subtest so the cache can't mask a regression); restored the fix and re-ran — all pass. QA: `QA-REG-193` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_193_image_converter_tempfile.sh` — opens a real JPEG needing conversion on a Kitty-graphics-capable terminal and confirms the full pipeline via the raw output stream (`hangon readall`, since headless hangon/tmux can't rasterize transmitted Kitty graphics pixels even via `hangon screenshot`): the Kitty APC image-transmission escape sequence is present with the correct format/id, and its base64 payload decodes to a real PNG. Verified interactively via `hangon`.

### ~~P2: AI API key briefly written world-readable before `chmod 0600` catches up~~ FIXED
`StateStore.pm:103-110` opened the secrets temp file with default umask permissions (often `0644`), wrote the AI API key content, closed it, and only *then* `chmod 0600`'d it before the atomic rename. A narrow but real window where the key was world-readable, contradicting `docs/SECURITY.md`'s parenthetical "secrets: ... (mode 0600)" claim, which implies secrets are always protected.

**Fix:** the `secrets` category now uses `sysopen($fh, $tmp_path, O_WRONLY|O_CREAT|O_EXCL, 0600)` — mode set atomically at creation, no window at all. Other categories (`preferences`, `history`) intentionally keep plain `open` at default umask permissions per this file's own category-docs comment ("preferences: ... user would sync across machines"; "history: ... accumulated state") — they hold no secrets and may be synced/managed like any other dotfile, so restricting them would be a behavior change with no security benefit. `O_EXCL` also closes the same symlink-follow risk class fixed in `ImageConverter.pm` above, since the temp path (`"$path.tmp.$$"`) is still PID-based/predictable.

**Tests:** checking only the *final* file's permissions would not catch this bug (both the old and new code converge on 0600 by the time `put()` returns), so `tests/state_store_secrets_race.t` instead intercepts the file-creation syscall itself: it overrides `CORE::GLOBAL::open`/`CORE::GLOBAL::sysopen` in a `BEGIN` block *before* `Zepto::StateStore` is compiled, and records the file's mode on disk immediately after creation — before any write/close/chmod/rename can run. This is deterministic, not timing-dependent, so it can't flake. (Lesson learned building this: a `CORE::GLOBAL::open`/`sysopen` override changes how bareword-filehandle `open` calls *parse*, not just their runtime behavior, for every module compiled afterward — the first attempt broke `Cwd.pm`'s internal bareword-FH usage with a "Bareword not allowed" compile error; fixed by preloading every one of `StateStore.pm`'s transitive dependencies — `File::Spec`/`Cwd`/`JSON::PP`/`File::Temp`/`Fcntl` — before installing the override, confining its effect to exactly the module under test.) Confirmed test-before/fix/test-after: reverted the fix and re-ran the race test — failed exactly as expected (observed the temp file at mode 0644, under a forced permissive `umask 0022`, at the moment of `open()`, well before the later `chmod` ran); restored the fix and re-ran — passes, and the final file is still confirmed mode 0600. QA: `QA-REG-194` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_194_secrets_file_mode.sh` — drives the real user-facing flow (Command Palette → "AI Completion: Setup", the only caller anywhere that writes the `secrets` category) end-to-end and confirms the resulting `secrets.json` is mode 0600. Verified interactively via `hangon`.

### ~~P2: `VCS/Git.pm::is_tracked()` has a git argument-injection edge case~~ FIXED
`VCS/Git.pm:103`: `_git('ls-files', '--error-unmatch', $rel_path)` had no `--` separator before `$rel_path`. A file whose relative path starts with `-` could be parsed by git as an option rather than a pathspec, causing `is_tracked()` to misreport (not itself exploitable for code execution/disclosure — the other `git show` calls at `Git.pm:121,150` are safe since they prefix with `HEAD:`/`:`, which can't start with `-`).

**Fix:** added `'--'` before `$rel_path`: `_git('ls-files', '--error-unmatch', '--', $rel_path)`. Audited every other `_git(...)` call site in `VCS/Git.pm` for the same gap: both `git show` calls (`"HEAD:$rel_path"`, `":$rel_path"`) remain safe since those prefixed forms can never start with `-`; `get_worktree_status`'s `git status --porcelain` takes no pathspec at all. Also checked `FileTree.pm`'s separate `git ls-files` calls (used for its fast file-list build) — these pass fixed flag-only argument lists with no user-controlled pathspec argument at all, so they were never at risk. No other gaps found anywhere in the codebase.

**Tests:** `tests/vcs.t` — two new subtests create a git repo with a `-weird.txt` file at the repo root (so its relative path genuinely starts with `-`, not just a subdirectory path), one tracked and one untracked, created via Perl `open()` with an explicit path (never shell globbing, which would otherwise treat the leading `-` as a flag). Confirmed test-before/fix/test-after: reverted the fix and re-ran — the tracked-file subtest correctly failed (misreported as untracked, since `-error-unmatch` and the bare filename together confused git's option parsing); restored the fix and re-ran — both pass. QA: `QA-REG-195` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_195_git_dash_filename.sh` — same revert/restore cycle confirmed the same result via the QA harness independently. This script is intentionally non-interactive (no hangon/zepto session): `grep -rn is_tracked lib/` confirms this method has **zero callers anywhere in the editor's runtime code today** (only exercised by unit tests) — there is no command, keybinding, or UI element to drive interactively, so Rule 2 (UI discoverability) does not apply to this particular fix. The script instead calls the real `Zepto::VCS::Git` library code directly against a real git repository, mirroring the interactive scripts' spirit as closely as that constraint allows.

### ~~P3: No regex-match timeout in the syntax-highlighting path (structural gap, no exploit found)~~ FIXED
`Highlighter.pm`/`Syntax/Base.pm` have zero `alarm`/timeout protection, unlike `FindEngine.pm`'s explicit 1s match-time alarms added earlier this session specifically to close a ReDoS gap. Highlighting runs ~53 hand-written grammar regexes against file content automatically on every open/edit — a larger, more automatic attack surface than Find's user-typed-pattern case. No exploitable pattern was found in this audit pass (nested-quantifier-shaped patterns in `Protobuf.pm` and elsewhere were empirically tested with no measurable slowdown), but there's no safety net if one exists in an untested grammar or is introduced later. Worth a documented decision either way — either add the same `alarm()` guard `FindEngine.pm` uses, or explicitly document why highlighting is considered lower-risk than Find.

**Fix:** Added a tokenize-time alarm guard in `Highlighter.pm::tokenize_line()`, following `FindEngine.pm`'s `_match_with_alarm` idiom exactly (local `$SIG{ALRM}`, `alarm(N)`, `eval{}`, unconditional `alarm(0)` cleanup, a distinct sentinel exception `"tokenize_timeout\n"` for "timed out" vs. any real grammar bug, which is re-thrown rather than swallowed). The guard wraps the single call site `$self->{grammar}->tokenize($line_content, $start_state)` — every one of the ~53 grammars funnels through this one call, so the fix covers the whole class of possible pathological grammar regexes, not one specific pattern. Budget is `TOKENIZE_ALARM_SECS => 0.1` (100ms, via `Time::HiRes::alarm` since core `alarm()` is whole-seconds-only) — much tighter than `FindEngine.pm`'s 1s `MATCH_ALARM_SECS`, because `tokenize_line()` runs on every visible line on every render (including every keystroke), not just an explicit user-initiated search; a 1s-per-line budget could visibly freeze the editor across a full viewport. On timeout: the line falls back to `[]` (no tokens → rendered as plain/unhighlighted text) and `end_state` is assumed unchanged from `start_state` (rather than guessed) so a pathological line can't desync the multi-line state of lines below it. The fallback result is written into the existing token memo cache exactly like a real result — deliberately, so a persistently-pathological line pays the 100ms cost once, not on every subsequent render of the same viewport (verified: a second `tokenize_line()` call for the identical `(start_state, line_content)` key returns in ~5μs from cache, not another ~250ms). This does not violate `docs/CODE_QUALITY.md` Pitfall #9's pure-memoization invariant: the cached fallback is still fully determined by the two key inputs (the same pathological pattern against the same content deterministically re-triggers the same backtracking), it's just that the memoized answer is "gave up" instead of real tokens. Added `highlight_timed_out()` accessor mirroring `FindEngine.pm`'s `search_timed_out()`, reset in `set_file()`.

**Reproduction (Rule 5):** none of the 53 shipped grammars are known to contain a catastrophic-backtracking regex, so reproduced the mechanism with a synthetic test-only grammar (`Test::Syntax::Pathological` in `tests/highlighter_regex_timeout.t`) using the same `(a?){28}a{28}` pattern `tests/find_engine_redos.t` verified is genuinely catastrophic against Perl's regex engine. Confirmed the gap first: swapped in the pre-fix `Highlighter.pm` (via `git show <base-commit>:lib/Zepto/Highlighter.pm`, not `git stash`) and ran the new test against it — `tokenize_line()` failed to return within the test's 6s fork/watchdog bound (child had to be SIGKILLed) and, run in-process without a watchdog, took **31.7 seconds** to return. Restored the fix and re-ran — same call now returns in ~0.25s, bounded by the 100ms alarm plus fork/interpreter overhead.

**Tests:** `tests/highlighter_regex_timeout.t` (6 subtests) — the fork+watchdog hang check (mirroring `find_engine_redos.t`'s technique, needed because `alarm()` is a single process-wide timer so testing "does this hang" in-process risks hanging the test runner itself if the guard is broken), a bounded-timeout-with-plain-text-fallback check, a cache-absorbs-repeated-requests check (proves no per-frame retry storm), a `highlight_timed_out()`-resets-on-`set_file()` check, a check that a genuine non-timeout grammar bug still propagates as itself rather than being swallowed as a timeout, and a normal-highlighting-unaffected check (real Perl grammar, ordinary code, no timeout ever fires, sub-millisecond). Also re-ran `tests/highlighter.t` and `tests/syntax_samples.t` (189 combined subtests) unchanged — no regression in real-grammar output. QA: `QA-REG-234` in `qa/40_regression_bugs.txt`, script `qa/scripts/tier1/reg_234_highlighter_timeout_guard.sh` — confirms the running editor stays responsive when opening/editing a file, exercising the guard through the real UI (not just the library call), since no real grammar is currently known to trigger it in the wild.

**Not done:** did not find or construct a catastrophic-backtracking pattern in any of the 53 real shipped grammars — this fix closes the structural gap (the call-site guard covers any grammar, present or future) rather than patching one confirmed-exploitable pattern. The guard covers per-line `tokenize()` calls only, not grammar *loading* (`_load_grammar()`'s `require`) — grammar modules are static, developer-authored code shipped with the editor, not attacker-controlled input, so a slow-to-load grammar module isn't the same threat class as a pathological regex matched against untrusted file content; left out of scope accordingly.

### Tautological / weak tests (P1/P2)

### ~~P2: 6 more tautological QA scripts follow the exact anti-pattern `qa/README.md` documents and forbids~~ FIXED
Each had a dual-`qa_pass`-on-one-condition fallback (or, for `reg_070`, computed both sides of a comparison and never actually compared them) that let a real regression pass silently. Fixed all 6 (2 scripts share one bug, so 5 root-cause fixes below), each verified per Rule 5 by temporarily breaking the underlying behavior, confirming the rewritten script fails, then restoring and confirming it passes — 2-3 standalone runs (`perl qa/runner.pl --tier 1 --filter <name>`) after each restore with no flakiness (`prmt_006` needed one extra fix, see below).

- **`qa/scripts/tier1/tab_017_cache_theme.sh` (QA-TAB-017) and `qa/scripts/tier1/reg_084_tab_theme_cache.sh` (QA-REG-084)** — both `qa_pass`ed regardless of whether the tab bar actually re-colored after a theme toggle. Both guard the same underlying bug (`Renderer.pm`'s tab-bar cache key, `~line 900`, already includes `$theme->name()` — this just wasn't being tested), so rather than leave two identical tests or retire one (both IDs are cross-referenced from `bugs.md`/`QA-THM-004`), differentiated them by entry point and color property so they exercise genuinely different renders: `tab_017` drives the switch via the command palette ("Theme: Dark"/"Theme: Light", deterministic regardless of starting theme) and asserts the tab **bar's** background ANSI code (`48;2;30;32;44` dark vs `48;2;230;233;239` light); `reg_084` drives it via the raw ⌃T key (the original bug report's exact trigger) and asserts the **active tab's** background code (`48;2;52;79;138` dark vs `48;2;114;135;253` light), round-tripping dark→light→dark. Both capture raw ANSI via `tmux capture-pane -e` (same technique as `QA-REG-140`), not the color-stripped `hangon screen`/`qa_screen` text. Verified: removed `$theme->name()` from the `Renderer.pm` cache-key `join()` — both scripts correctly failed (stale dark color persisted after switching to light); restored — both pass.
- **`qa/scripts/tier1/nav_010_scroll_no_move.sh` (QA-NAV-010)** — named to verify Ctrl+Up/Down scrolls *without* moving the cursor, but `qa_pass`ed even when the cursor moved. **Investigation finding:** that claim isn't real. Confirmed interactively via `hangon` (pressing ctrl-down moves the cursor from 1:1 to 2:1, viewport doesn't scroll) and by code reading — `Editor.pm`'s up/down key dispatch never branches on the ctrl modifier at all, so Ctrl+Down is currently identical to plain Down. Nothing in `qa/07_navigation.txt`'s actual `QA-NAV-010` entry ("press Down repeatedly; cursor remains visible; viewport auto-scrolls") makes this claim either — it's untested, undocumented, and unreachable from the UI, so rather than fabricate a new keybinding feature under a "test-quality only" task, rewrote the script to test what `QA-NAV-010` actually documents: pressing Down past a screen's worth of lines and asserting (a) the cursor lands on the expected line and (b) that line's content is actually rendered on screen (`View::ensure_cursor_visible`). Also found, incidentally, that `Preferences.pm`'s `scroll_margin` (default 3, "lines to keep above/below cursor") is defined but never read anywhere in `View.pm` — the vertical-scroll comment there literally says "no margins — scroll exactly when needed." Not fixed (out of scope for this task); noted here per Rule 6 for a future pass, and it also means `QA-NAV-011`'s "scroll margin" script (itself misnamed `nav_011_ctrl_right.sh`) is worth re-auditing separately. Verified: disabled the vertical-follow branch of `View::ensure_cursor_visible()` that this test's file (`.txt` extension → word-wrap-on by default in this app) actually exercises — script correctly failed (cursor's line scrolled off-screen); restored — passes. Also cut the loop's per-key sleep from the default 0.4s to the established `0.05s` convention (other scripts' repeated-key loops) — runtime dropped from 14s to 3.5s.
- **`qa/scripts/tier1/reg_070_message_persist.sh` (QA-REG-070)** — meant to verify status messages persist past 2s (`docs/UI_GUIDELINES.md:236`); computed `saved_before`/`saved_after` but never compared them, unconditionally passing either way. Fixed to two real assertions: the save message appears, and it's still present after a 2s wait with no keypress (the actual "not time-based" rule). Verified: since Zepto's main loop doesn't re-render on a pure idle timeout (no pending work), a hypothetical time-based-clear regression wouldn't even repaint the screen during the wait — so the realistic break also needs to force a render on idle tick, which any real regression would too (otherwise a user would never see it clear either). Added a synthetic 1s message expiry in `Editor.pm::show_message`/the render call plus a forced idle re-render — script correctly failed both assertions; reverted both — passes.
- **`qa/scripts/tier1/gut_002_click_minimap.sh` (QA-GUT-002)** — had a "minimap click navigated"/"minimap click executed" fallback that passed either way. Rewrote using `_handle_minimap_click`'s exact geometry (`Editor.pm` ~1820-1836/2318-2347: `text_row = y-3`, `ratio = text_row/(text_height-1)`, `target_line = round(ratio*(total_lines-1))`) to pick two clicks with **exact, deterministic** expected outcomes: row 3 (first content row) always maps to line 1; the last content row always maps to the document's last line. The bottom-row assertion can't be explained by an accidental fallthrough to ordinary text-area clicking either — with only ~20-30 lines visible from the top, an ordinary click at that row would never land on line 150 of a 150-line file. Terminal geometry (rows/cols) is read from the live screen, not hardcoded. Verified: made `_handle_minimap_click` an early no-op — script correctly failed (bottom click left cursor at line 1); restored — passes, including the pre-existing "minimap enabled" check (also made real: it now asserts the palette's `[on]` badge, not an unconditional pass).
- **`qa/scripts/tier1/prmt_006_pill_click.sh` (QA-PRMT-006)** — had a "clicking Cancel pill dismissed prompt"/"test inconclusive" fallback. Rewrote to assert Cancel's actual, specific effect (`_prompt_close_dirty_tabs`: choice `'c'` does nothing — no save, no discard, no quit; it dismisses the prompt and returns control to the editor): after the click, the prompt text is gone, the session is still alive, and — the unfakeable "verify by action" check — a typed marker string actually lands in the document (impossible if the prompt, or any stuck state, were still intercepting input). **Bug found in my own first draft, fixed before landing:** locating the "Cancel" pill's screen column with `awk`'s `index()` overshot badly (computed column 83 on a ~76-col line) because this system's `awk` computes `index()` in **bytes**, and the pill row has multi-byte UTF-8 icon glyphs before "Cancel" — switched to Perl's UTF-8-aware `index()` (`perl -CSD`) for the correct character column. **Flakiness found and fixed during the 2-3x verification runs** (Rule 5's "confirm no flakiness" step, not incidental): a bare `qa_screen` single-capture immediately after `qa_assert_expect` raced a still-in-flight render under parallel suite load and occasionally missed the prompt; switched to `qa_wait_screen` (polls), matching the pattern the helper library's own comments recommend for exactly this reason. Verified clean over 5 consecutive standalone runs after the fix. Verified non-tautological: disabled the prompt's mouse-click branch in `Editor.pm` (`elsif ($type eq 'mouse' && ... && 0)`) — script correctly failed both the dismissal and marker-input assertions (the marker's leading `C` character happened to hit the keyboard Cancel shortcut instead, a nice confirmation the test setup is sound); restored — passes.

No changelog entry — all 5 fixes above are QA-script-only changes; no product code was modified in the final (restored) state.

### ~~P2: 2 tautological unit-test subtests in `tests/completion.t`~~ FIXED
`tests/completion.t:397-425` ("Controller accept with snippets") and `:430-455` ("Controller records accepted to RecentProvider") both gated their real assertions behind `if ($ctrl->is_active())` and fell through to `pass('no completion active (acceptable)')` otherwise.

**Investigation:** confirmed both subtests' existing inputs already trigger completion 100% reliably — no input change needed, just the dead fallback removed. "Controller accept with snippets" uses a 2-char prefix `"fo"` against a `.py` file with only `SnippetProvider` registered; `SnippetProvider.pm`'s Python snippet list (`if`/`for`/`def`/`class`/`while`/`try`/`with`) has exactly one trigger starting with `"fo"` (`"for"`), so the match — and therefore `accept()`'s hashref return — is deterministic, not scoring/order-dependent. "Controller records accepted to RecentProvider" uses a 3-char prefix `"hel"` that `CrossBufferWordProvider` finds by scanning `"hello_world"` elsewhere in the same buffer — also deterministic (no scoring race, the word just needs to exist). Confirmed via a standalone script and 3x `prove tests/completion.t` runs before touching the test.

**Fix:** removed both `if ($ctrl->is_active()) { ... } else { pass(...) }` wrappers; replaced with an unconditional `ok($ctrl->is_active(), ...)` followed directly by the real assertions (previously nested inside the `if`). Also dropped the redundant `if (ref($result) eq 'HASH')`/plain-suffix branch in the snippets subtest — with `SnippetProvider` as the *only* registered provider, `accept()` can only ever return a snippet hashref.

**Verified non-tautological (Rule 5):** made `Controller::trigger()` unconditionally `return $self->dismiss()` — `prove -v tests/completion.t` now hard-fails both subtests (the first also throws a fatal `Can't use string ("") as a HASH ref` on the now-unreachable-fallback-free assertion, since there's no longer any silent path around it). Reverted — `prove tests/completion.t` passes clean, confirmed 3x. Full suite (`make test`): 41 files, 1163 tests, all pass, no noise.

No changelog entry — internal test-quality change, no product code modified in the final state.

### P2: `AIComplete.pm` — the one network-calling module — has zero test coverage — MOSTLY FIXED (2026-09-01)
446 lines, 24 subs (`new`, `trigger`, `poll`, `_fire_request`, `_build_context`, `_build_payload`, `_parse_streaming_buffer`, `_json_escape`, `_hash`, etc.), confirmed via `grep -rl AIComplete tests/*.t` returning nothing. Several of its subs (`_build_payload`, `_json_escape`) are pure/near-pure and would be trivial to unit test without a network dependency, yet aren't tested at all.

**Note:** this claim went stale between being logged and being picked up — `tests/ai_complete.t` (added 2026-08-30 alongside the curl-argv-key-leak security fix, see "AI API key passed as a curl command-line argument" below) already covers `_child_http_request` via a fake `curl` stubbed onto `PATH`. But the specific subs this finding called out by name (`_build_payload`, `_json_escape`) — plus the other pure/near-pure logic — were still genuinely untested until now.

**Fix (test-only, branch `add-aicomplete-test-coverage`)**: new `tests/aicomplete.t` (50 subtests) covers every pure/near-pure sub that doesn't require a live fork/pipe: `_json_escape` (backslash/quote/newline/CR/tab/control-char/unicode classes, escaping-order regression guard, long-input stress case), `_build_payload` (payload shape, file/language hint composition, JSON-safety of embedded prefix/suffix/model), `_hash` (determinism, order-sensitivity, the documented 500-char truncation tradeoff), `_parse_streaming_buffer` (SSE chunk accumulation, `[DONE]` handling, JSON-escape unescaping, partial/incomplete chunks, malformed data), `_finish_request` (whitespace trimming/undef-collapse logic), `_build_context` (prefix/suffix windowing around the cursor, filename fallback, language-from-grammar detection) via lightweight duck-typed fake doc/view objects, and the pure state machine (`trigger`/`is_debouncing`/`cancel`/`dismiss`/`is_enabled`/`is_pending`/`has_result`/`result`/`clear_result`/`load_config`).

**Verified non-tautological (Rule 5)**: mutation-tested 4 of the new subs by deliberately breaking them and confirming `tests/aicomplete.t` failed, then reverting — dropping `_json_escape`'s backslash-escaping line failed 4 tests; dropping its control-character sweep failed 2; corrupting `_build_payload`'s file-hint language suffix failed 1; dropping `_parse_streaming_buffer`'s `\t`-unescaping failed 1. All four reverted cleanly (`git diff` empty against `lib/Zepto/AIComplete.pm` afterward).

**Still not covered** (~5 of 23 subs, the parts genuinely inseparable from live process/pipe I/O without a larger transport-injection refactor — out of scope for this pass): `check_trigger` and `_fire_request` (fork a real child and invoke `_child_http_request`/curl when called), `poll()`'s data-reading loop (reads from a real pipe registered by `_fire_request`), and the live-pid branches of `_kill_child`/`DESTROY` (their no-op/undef-pid branches ARE exercised, indirectly, via `cancel()`/`dismiss()` tests). Roughly 18 of 23 subs (~78%) now have direct test coverage, up from essentially 1 (`_child_http_request`, via the pre-existing security-fix test) before this pass.

Full details: `tests/aicomplete.t`.

### P3: `qa/scripts/tier3/` doesn't exist despite being referenced as real by docs and the Makefile — FIXED
`qa/README.md:130` and the `Makefile`'s `qa-full`/`qa-list` targets (`--tier 1,2,3`) describe a tier-3 QA layer as runnable — `perl qa/runner.pl --list --tier 3` returns "No test scripts found for tier(s) 3" (exit 0, silent no-op). `make qa-full` today runs identically to `make qa-visual` despite implying additional coverage. Fix: either populate `tier3/` with whatever it was meant to hold, or update the docs/Makefile to not imply a populated tier that doesn't exist.

**Fix:** Re-verified: `qa/scripts/` only has `tier1/` and `tier2/`; `perl qa/runner.pl --list --tier 3` still reports "No test scripts found for tier(s) 3". Searched `qa/README.md` end-to-end for any hint of what tier3 was meant to hold — it has a full `## Tier 2: LLM Vision-Judge Sweeps` section but no corresponding tier3 section or description anywhere, so there's no obvious/small legitimate content to populate it with. Went with option (a): corrected the docs and Makefile comments to describe tier3 as reserved-for-future-use rather than implying it's a populated, currently-additive coverage tier. Did not invent tier3 content or create the directory.
- Before (`qa/README.md`): `**Running it:** \`make qa-visual\` (tier 1 + 2) or \`make qa-full\` (+ tier 3). Plain \`make qa\` (tier 1 only, the default and what CI/rule-3 compliance requires) never touches any of this — no LLM dependency at all.`
- After: same first sentence (reworded "+ tier 3" to "(tiers 1,2,3)"), plus a new paragraph: `**Tier 3 is reserved, not yet populated.** \`qa-full\`/\`qa-list\` pass \`--tier 1,2,3\` to \`qa/runner.pl\` for forward-compatibility, but no scripts exist under \`qa/scripts/tier3/\` yet — \`make qa-full\` today runs identically to \`make qa-visual\`. Nothing is broken by this (the runner just reports zero tier-3 scripts found); it's a placeholder for a future coverage tier (e.g. slow/expensive checks like full-matrix performance benchmarking or cross-platform runs) that hasn't been built out. If you add the first tier-3 script, update this note.`
- Before (`Makefile`): `# All automated tiers` / `qa-full: build` ... `# List available QA scripts without running` / `qa-list:`
- After: `# All automated tiers (tier 3 is reserved for future use — no scripts exist under qa/scripts/tier3/ yet, so this currently runs identically to qa-visual; see qa/README.md)` / `qa-full: build` ... `# List available QA scripts without running (tier 3 included for forward-compatibility; see qa-full comment above)` / `qa-list:`

### P3: 6 unit tests use `sleep 1` to force mtime differences; one root-runner test fails outright instead of skipping
`tests/document.t:409,431,453`, `tests/preferences.t:379`, `tests/state_store.t:95,173,231` — relies on filesystem mtime granularity being ≤1s (true almost everywhere, but a timing assumption nonetheless). Separately, `tests/editor.t:3140-3200` (file-tree preview permission-race test) correctly detects when its `chmod 0000` probe can't actually restrict access (e.g. running as root) via a sanity-check `ok()`, but does not `skip()` the downstream assertions in that case — under a root CI runner this test fails outright rather than skipping.

### Documentation accuracy (P3)

### P3: `DESIGN.md:301` — "Our build.pl is 50 lines of simple string manipulation" is stale — FIXED
Actual `build.pl` is **441 lines**, with a priority-ordered module dependency graph, per-file regex transforms, and embedded-doc logic.

**Fix:** Re-verified at fix time (`build.pl` is 440 lines — off by one from the audit's count, presumably a one-line drift from a concurrent change; re-checked directly rather than trusted). Replaced the stale line count and vague "simple string manipulation" description with an accurate summary of what `build.pl` actually does: walks `lib/` for `.pm` files, sorts by an explicit priority table (dependency order), applies per-file regex transforms (strip shebangs/comments, `use parent`→`@ISA`, inline `use Zepto::*`, wrap each module in its own block), embeds `docs/help/*.md` into `HelpDocs`, and appends the `main` entry point (CLI parsing, `--install`, `--version`).
- Before: `Tools like PAR or FatPacker add complexity and dependencies. Our build.pl is 50 lines of simple string manipulation. It does exactly what we need and nothing more.`
- After: `Tools like PAR or FatPacker add complexity and dependencies. Our build.pl is ~440 lines of plain Perl: it walks lib/ for .pm files, sorts them into dependency order via an explicit priority table (core modules first, Syntax::Base before other grammars, Editor.pm last), applies a handful of per-file regex transforms (strip shebangs/comments, convert use parent to @ISA, inline use Zepto::* away, wrap each module in its own { } block to avoid my-variable name clashes), embeds the docs/help/*.md files into the HelpDocs module, and appends a main entry point (CLI arg parsing, --install, --version). It does exactly what we need and nothing more — no bundler dependency, just string manipulation.`

### P3: `docs/FIND_REPLACE_SPEC.md` has three stale/wrong claims — FIXED
- Line 64: "Default: ON" for regex search — actual default is OFF (`Editor.pm:131`, `FindEngine.pm:33`), and the project's own changelog documents this exact behavior change; the spec was never updated to match.
- Line 17: "Replace Mode (Ctrl+R or Tab from Find)" — wrong; Ctrl+R toggles regex mode (`Editor.pm:2719-2720`). The `find_replace` command has no direct shortcut at all (`CommandRegistry.pm:333-342`).
- Line 189: lists "Search history not implemented" as a known TODO — it's fully implemented (`Editor.pm:392-437`, persisted, 30-entry cap).

**Fix:** Re-verified all three against current code (`Editor.pm:131` `find_regex => 0`, `FindEngine.pm:33` `use_regex => 0`; `Editor.pm:2718-2723` Ctrl+R toggles `find_regex`; `Editor.pm:397-437` `_save_find_history`/`find_history` persisted via `state_store`). Also found and fixed two more instances of the same stale "Ctrl+R opens replace" claim and one wrong case-toggle key in the same file's keyboard table (line ~44 duplicated the Replace-mode claim; line ~51 said Alt+I toggles case, but code (`Editor.pm:2726-2728`) shows it's Ctrl+C) — left uncorrected these would have contradicted the primary fix two lines away in the same doc.
- Before (§Modes header): `### Replace Mode (Ctrl+R or Tab from Find)` / After: `### Replace Mode (Tab from Find)`
- Before (keyboard table): `| Ctrl+R | Open replace mode |` ... `| Alt+R (or ^R) | Toggle regex mode |` `| Alt+I (or ^I) | Toggle case sensitivity |` / After: removed the "Ctrl+R | Open replace mode" row, clarified Tab's row to `| Tab | From Find (no replace field yet): open Replace mode. Otherwise: toggle focus between find and replace fields |`, and corrected the toggle rows to `| Ctrl+R | Toggle regex mode |` / `| Ctrl+C | Toggle case sensitivity |`
- Before: `- Default: ON` (regex toggle) / After: `- Default: OFF`
- Before: `6. Search history not implemented` (in Known Issues/TODO) / After: line removed

### P3: `FEATURES.md:51`'s enumerated language list is missing 2 of the 52 languages its own header claims — FIXED
AsciiDoc and KDL are both real, registered, changelog-documented languages (`Highlighter.pm:170-171,322-325`) but missing from the comma-separated list on line 51.

**Fix:** Re-verified: `ls lib/Zepto/Syntax/*.pm` (excluding `Base.pm`) gives exactly 52 files, matching the "52 Languages" header. Compared the full module list against the enumerated line and confirmed AsciiDoc and KDL were the only two missing (no other drift). Added both in alphabetical position.
- Before: `C, C++, C#, Clojure, CMake, Crontab, CSS, Diff, ... JavaScript/JSX, JSON, Kotlin, LaTeX, ...`
- After: `AsciiDoc, C, C++, C#, Clojure, CMake, Crontab, CSS, Diff, ... JavaScript/JSX, JSON, KDL, Kotlin, LaTeX, ...` (52 comma-separated entries, verified by count)

### P3: `docs/UI_GUIDELINES.md:193` directly contradicts a real, shipped, documented shortcut — FIXED
"Do not depend on... `Ctrl+Shift+letter`; terminals cannot distinguish these reliably" — contradicted by `find_in_files`'s real, working, end-user-documented `Ctrl+Shift+F` (`CommandRegistry.pm:417`, `docs/help/tutorial.md:62`, with two independent working key-dispatch paths for it). Either the guideline needs an explicit carve-out or it should be softened from an absolute rule to a strong default.

**Fix:** Re-verified `Ctrl+Shift+F` is genuinely shipped (`CommandRegistry.pm` `find_in_files` shortcut, `Editor.pm:1283-1295` `$shift && $ch eq 'f'` dispatch, `docs/help/tutorial.md:62`) and traced *why* it can work: `InputParser.pm`'s CSI-u/fixterms path (`ESC [ codepoint ; modifiers u`, ~line 336-342) decodes explicit modifier bits when the terminal supports that protocol (Kitty keyboard protocol, xterm `modifyOtherKeys`, etc.). But on a terminal that only sends the plain control byte (`InputParser.pm::_parse_control`, `Ctrl+letter` → ord 1-26), shift is never encoded at all — `Ctrl+Shift+F` becomes byte-for-byte identical to `Ctrl+F` and the editor's own dispatch (`Editor.pm:1274-1301`, gated on `has_modifier($event,'shift')`) falls through to plain `Find` instead. So this isn't a case where Zepto found a trick that makes the combo reliable — it's genuinely terminal-dependent, exactly the risk the original guideline warned about, it just degrades gracefully (to a still-useful action) rather than doing nothing. Chose framing (b): softened the absolute rule into risk-flagged guidance rather than adding a false "this one is safe" exception.
- Before: `- Do not depend on \`Shift+letter\` or \`Ctrl+Shift+letter\`; terminals cannot distinguish these reliably.`
- After: `- Treat \`Shift+letter\` or \`Ctrl+Shift+letter\` as risky, not off-limits: whether the terminal can distinguish them depends on the terminal supporting an extended keyboard protocol (CSI-u/"fixterms", the Kitty keyboard protocol, or xterm \`modifyOtherKeys\`) that encodes modifier bits explicitly. \`InputParser.pm\`'s CSI-u path (\`ESC [ codepoint ; modifiers u\`) decodes these correctly when present. Without it, a terminal sends the same plain control byte for \`Ctrl+F\` and \`Ctrl+Shift+F\` (shift is not encoded in a bare control byte, \`InputParser.pm::_parse_control\`), and the two become indistinguishable — Zepto's own \`find_in_files\` (bound to \`Ctrl+Shift+F\`) silently degrades to plain \`Find\` on such terminals rather than erroring. Only reach for a \`Ctrl+Shift+letter\` binding when: (a) the feature is important enough to justify graceful degradation to a different, still-reasonable action on older terminals, and (b) that degraded behavior is itself acceptable (not a silent no-op or something surprising). Prefer an unambiguous binding when one is available.`

### P3: `DESIGN.md` labels `Renderer` and `WrapMap` "Pure function" — both claims are false — FIXED
`Renderer.pm` holds three package-level mutable caches (`%_cdw_cache`, `%_file_exists_cache`, `%_image_dims_cache`, plus a tab-bar geometry cache) — implementation-level memoization, not a pure state-in/string-out function as documented. `WrapMap.pm:25` does `use Zepto::Renderer;` and calls `Zepto::Renderer::_expand_tabs()`/`_char_to_visual_col()` as fully-qualified calls into Renderer's underscore-prefixed (conventionally private) internals (`WrapMap.pm:268,288,445,483`) rather than a public API — a leaky abstraction that also isn't "pure" in the sense the doc implies. Fix: either correct the doc's claims, or (bigger scope) give Renderer a proper public API for the two helpers WrapMap needs and stop reaching into private internals.

**Fix (docs only — code-level refactor explicitly out of scope):** Re-verified both claims directly: `Renderer.pm` has `%_cdw_cache` (line 139), `%_file_exists_cache` (1429), `%_image_dims_cache` (1444), and a closure-scoped tab-bar cache (`_tab_bar_cache_get`/`_set`, ~345-358); `WrapMap.pm` calls `Zepto::Renderer::_expand_tabs()`/`_char_to_visual_col()`/`visual_to_char_col()` at lines 268, 288, 445, 483, the first two being underscore-prefixed (conventionally private). Corrected the `DESIGN.md` module table and prose to describe both accurately without implying they're pure. Did **not** touch the actual code — no public API was added to `Renderer.pm`, `WrapMap.pm` still reaches into the private helpers; that refactor remains a separate, larger, riskier task.
- Before (table): `| **Renderer** | Converts editor state to ANSI escape sequences | Pure function |`
- After: `| **Renderer** | Converts editor state to ANSI escape sequences | State in → string out, with internal memoization caches (char-width, file-exists, image-dims, tab-bar geometry) |`
- Before (table): `| **WrapMap** | Word wrap computation, visual row mapping | Pure function |`
- After: `| **WrapMap** | Word wrap computation, visual row mapping | State in → wrap map out; calls into Renderer's private \`_\`-prefixed tab/column helpers directly (accepted coupling, not a public API) |`
- Before (prose): `The key architectural enabler: keeping Renderer pure (state in → string out) means rendering can be tested without a terminal.`
- After: `The key architectural enabler: Renderer's core contract is state in → string out (it holds no reference to the terminal or editor object, just internal memoization caches keyed on its inputs), which means rendering can be tested without a terminal.`

### Dead code / consistency (P3)

### P3: 5 confirmed-dead subs — FIXED (2026-08-30)
- `Renderer::_render_pill` (`Renderer.pm:3844-3869`) — never called; the actually-used pill renderer is `_render_pill_list` (`Renderer.pm:3967`), an independent reimplementation. Bonus: `_render_pill`'s own nerd-font/non-nerd-font branches are byte-for-byte identical to each other.
- `Terminal::set_cursor_color` (`Terminal.pm:201-207`) — never called; cursor color is actually set via a raw inline `print STDOUT "\x1b]12;..."` in `Editor/Commands.pm:1228` that bypasses this method entirely (arguably that call site should use this method instead of duplicating the OSC 12 sequence).
- `Terminal::read_available` (`Terminal.pm:362-380`) — never called; `read_blocking` is what's actually used.
- `Buffer::_debug_state` (`Buffer.pm:448-453`) — never called; a leftover debugging aid.
- `Preferences::visual_width` (`Preferences.pm:299-315`) — only referenced from `tests/preferences.t`, never production code. **Also has a live landmine**: `$width += $tab_width - ($width % $tab_width)` divides by `$tab_width` with zero validation anywhere in `Preferences::set()` — a hand-edited `tab_width: 0` in the (intentionally hand-editable) `preferences.json` would hit an uncaught fatal `Illegal modulus zero` the moment anything calls this. Currently latent since nothing calls it, but worth fixing alongside deciding whether to keep or delete the dead sub.

**Fix**: Re-verified all 5 dead-code claims independently via `grep -rn` across `lib/`, `tests/`, `qa/`, `build.pl` before touching anything.
- `Renderer::_render_pill` deleted. Confirmed its nerd-font/non-nerd-font branches were byte-for-byte identical (both just push `$theme->color($bg_key) . $theme->color($fg_key)` then `" $text "`) — nothing worth salvaging into `_render_pill_list`.
- `Terminal::set_cursor_color` — **kept, and wired up** instead of deleted: `Editor/Commands.pm`'s `_apply_theme_pref` now calls `$self->{terminal}->set_cursor_color($cursor_color)` instead of duplicating the raw `print STDOUT "\x1b]12;...\x1b\\"; STDOUT->flush()` sequence. Verified `$self->{terminal}` is populated in every test/runtime construction path and that `Terminal::write()` (which `set_cursor_color` calls) does an unbuffered `syswrite` to the same `out_fh` (defaults to `\*STDOUT`), so this is behavior-preserving, not just a rename. Verified interactively via `hangon`: `⌃T` theme toggle still works with no errors/hang.
- `Terminal::read_available` deleted (dead; `read_blocking` is the only reader used anywhere). `use IO::Select` retained — still used by `read_blocking`.
- `Buffer::_debug_state` deleted.
- `Preferences::visual_width` — **left alone, not deleted.** Checked whether a concurrent agent's `tab_width == 0` divide-by-zero fix had landed on `main` yet (`git diff main -- lib/Zepto/Preferences.pm` was empty at the time of this fix) — it hadn't. Per the ambiguity noted in the original finding, deleting it here risked colliding with that other in-flight fix, and it's genuinely low-priority either way, so this one item is explicitly skipped/deferred rather than guessed at. Still dead in production as of this commit; `tests/preferences.t` is its only caller.

### P3: `AIComplete.pm::_parse_url` is dead code — FIXED (2026-08-30)
Referenced in the "Scorecard audit round 2" security-audit findings (item D) as never called; the actual request URL is built via naive string concatenation elsewhere in the same file instead.

**Fix**: Confirmed via `grep -rn '_parse_url' lib/ tests/ qa/ build.pl` that its only appearance anywhere in the repo was its own `sub _parse_url { ... }` definition (`AIComplete.pm:403-417`) — no callers, no tests. Deleted. `AIComplete.pm` has no test file (`tests/*.t`) at all currently (tracked separately as its own P2 finding — "the one network-calling module has zero test coverage" — not addressed here, out of scope for this cleanup), so there was no test coverage to lose. `make check`/`make build`/`make test` all clean after deletion.

### P3: `do_find_next`/`do_find_prev` are 77 lines of dead production code, confusingly named next to the real commands — FIXED (2026-08-30)
`Editor/Commands.pm:724-800` duplicate `cmd_find_next`/`cmd_find_prev`'s job via a completely different, older implementation (`$doc->text()` + `index`/`rindex` scan) instead of the actually-wired path (`cmd_find_next/prev` → `enter_find_mode` → `_find_navigate`, `Editor.pm:3055-3078`, which uses FindEngine's precomputed match list). Called only from `tests/editor.t` (8 call sites) — unreachable in the shipped editor, kept alive/green by tests, and confusingly similar-named to the real commands.

**Fix**: Confirmed via `grep -rn` that `CommandRegistry.pm` and every runtime dispatch path (`Editor.pm`) reference only `cmd_find_next`/`cmd_find_prev`, never `do_find_next`/`do_find_prev`; the latter's only references anywhere in the repo were their own definitions and the 8 call sites in `tests/editor.t`. Deleted both dead methods. Migrated the 3 subtests that used them ('Find next', 'Find not found', 'Find prev with selection finds previous match') to call the real `cmd_find_next`/`cmd_find_prev` instead — but their assertions could **not** just be transplanted unchanged: the deleted dead code did a simple continuous `index()`/`rindex()` scan and set a "Found"/"Not found" status message, while the real commands call `enter_find_mode()` (which re-anchors to the match nearest the cursor via FindEngine's `_find_nearest_match` on *every* call) before stepping via `_find_navigate()`, and never set a status message. Re-derived every expected position/selection by driving the real commands directly (a throwaway probe script) rather than guessing, and rewrote the subtests' assertions to match verified real behavior — see `tests/editor.t`'s updated 'Find next'/'Find not found'/'Find prev selects a match' subtests and their comments. Added a 4th subtest ('Find next falls back to cmd_find when no search term is set') covering the `else` branch that was previously untested. No coverage was silently lost: the deeper multi-match/wrap-around navigation logic (`_find_navigate`) already has thorough, dedicated coverage in `tests/find.t` ('Navigate to next match', 'Navigate wraps at end', 'Navigate wraps at start', 'Navigate with no matches') — that coverage was untouched. Verified via `prove -Ilib tests/editor.t`: 144 tests, all pass, zero noise. Also added `qa/scripts/tier1/reg_196_find_next_prev_real_cmd.sh` (`QA-REG-196`, see `qa/40_regression_bugs.txt`) — the real `cmd_find_next`/`cmd_find_prev` (Ctrl+J/Ctrl+K) had **zero** interactive/QA coverage before this fix, since the dead code was the only place anything resembling "find next/prev" got exercised by name. Verified the new QA script is non-tautological by temporarily neutering `cmd_find_next` and confirming the script correctly fails (2 of 6 checks) before restoring it.

**Behavioral discovery (not fixed here, logged separately)**: while deriving the real expected test values, found that `cmd_find_next`/`cmd_find_prev` re-entering `enter_find_mode()` on every single call (rather than just stepping an already-open find session) can cause repeated Ctrl+J/Ctrl+K presses to "get stuck" on the same match in some cursor positions, or skip over a match entirely, because the nearest-match re-anchor and the `_find_navigate` step compound unpredictably depending on exactly where the cursor landed from the previous call. See new "Found while fixing the dead-code cleanup (2026-08-30)" section below for the full writeup — flagged as a new bug, not fixed as part of this cleanup (out of scope).

### ~~P3: Kitty/fixterms CSI-u modified special keys (Ctrl+Enter, etc.) are silently and permanently dropped~~ FIXED (2026-08-30)
`InputParser.pm:337-342` only handled CSI-u codepoints in the printable range (32-126); codepoints for Enter (13)/Tab (9)/Backspace (8)/Escape (27) sent with a modifier via the Kitty keyboard protocol fell through to "Unknown CSI sequence" → `EVT_NONE`. An earlier fix (already tracked in this file, "Out-of-range CSI-u does not stall following events") resolved the *stall* this used to cause for the *following* keystroke, but didn't recover the dropped codepoint itself — on a Kitty-protocol terminal, shortcuts like `Ctrl+Enter` simply did nothing, with no code path that could make them work.

**Root cause:** the CSI-u branch (`ESC [ codepoint ; modifiers u`) only had a case for `32 <= codepoint < 127` (mapped to `_make_char_event`). Enter/Tab/Backspace/Escape are control-character codepoints outside that range, so they fell straight through the `if` with no `else`, hit the function's final `return { type => EVT_NONE }`, and were discarded — even though `_parse_control` (the plain, non-CSI-u path) already had an identical mapping for the exact same codepoints one section below in the same file.

**Fix:** Added four more codepoint checks inside the same CSI-u branch, reusing the existing `_make_key_event($key, $modifiers)` helper — the same helper every other CSI-u special key (arrows, Home/End, F-keys) already uses to attach modifiers to a named key event, so Ctrl+Enter now produces `{ type => 'key', key => 'enter', modifiers => ['ctrl'] }`, structurally identical to how e.g. Ctrl+Right already looks, just with a different `key` value. Mapping: `13 → KEY_ENTER`, `9 → KEY_TAB`, `8` and `127 → KEY_BACKSPACE` (127/DEL included because `_parse_control`'s plain-backspace path already treats DEL and BS as equivalent — matched here for consistency), `27 → KEY_ESCAPE`. Scoped to `InputParser.pm` only — no existing command in `CommandRegistry.pm`/`Editor.pm` binds Ctrl+Enter or similar today, so the value of this fix is that the keystroke now produces a real, potentially-bindable event instead of vanishing; no new keybindings were added.

**Tests:** `tests/input_parser.t` — reproduced first (confirmed the new assertions fail against the pre-fix code), then fixed, then reconfirmed passing. Added a new subtest covering all four codepoints (8/9/13/27) plus the 127/DEL alias, each asserting a real `key`-type event with the correct `key` and `['ctrl']` modifier comes back, not `EVT_NONE`. The pre-existing "Out-of-range CSI-u does not stall following events" subtest was updated to use codepoint 3 (Ctrl+C/ETX, which still has no mapping) since codepoint 13 — its original example — is no longer an out-of-range case after this fix. `make test` (1164 tests) and `make check` clean.

**Interactive verification:** achieved for real, not skipped. No actual Kitty-protocol terminal was needed — `InputParser` parses whatever raw bytes arrive on stdin regardless of what the terminal advertises, so `hangon send --stdin` was used to inject literal CSI-u byte sequences (`ESC [ 8/9/13/27 ; 5 u`) directly into a running `./zepto` session's pty. Confirmed via the rendered screen: Ctrl+Backspace deleted the last typed character (cursor 1:4 → 1:3, "abc" → "ab"), Ctrl+Enter split the line (cursor → 2:1), Ctrl+Tab advanced the cursor past column 1, and Ctrl+Escape closed an open command palette (`╭` dialog border disappeared) — reverting the fix and rebuilding reproduced all four failures again, confirming both directions.

**QA:** `QA-REG-202` (`qa/scripts/tier1/reg_202_csiu_special_keys.sh` + `qa/40_regression_bugs.txt`) automates the same four-key interactive repro above using the status bar's `line:col` indicator and the palette's `╭` dialog-border glyph as robust assertions (the gutter cursor glyph itself was found to be unreliable as a test signal — it varies between a plain `>` and a nerd-font powerline glyph depending on terminal-capability detection, unrelated to this bug). Verified failing against the pre-fix binary (5/10 assertions fail, exactly the four CSI-u-mapped keys) and passing against the fix (10/10).

### P3: Minor inconsistency — one `eval` swallow is documented as intentional, a structurally identical one isn't — FIXED (2026-08-30)
`Preferences.pm:210`: `eval { $cb->($key,...) }; # Ignore callback errors` — documented. `StateStore.pm:171`: `eval { $cb->($data) };` — same shape, no comment. Also `Terminal.pm:172-176` (`disable_raw_mode`) swallows `setattr` failures with no `warn`, asymmetric with `enable_raw_mode` (`Terminal.pm:158-161`), which does `warn "Could not enable raw mode: $@"`. Small — worth normalizing (either add matching comments or matching warns) so the pattern reads as a deliberate convention rather than an accident.

**Fix**: Added the matching `# Ignore callback errors` comment to `StateStore.pm:171`'s `eval`, mirroring `Preferences.pm:210` exactly. For the `disable_raw_mode`/`enable_raw_mode` `warn` asymmetry: checked `docs/CODE_QUALITY.md`'s "Global destruction order" pitfall note ("In `DESTROY` and cleanup code, filehandles may already be closed"). Confirmed `disable_raw_mode`'s only caller is `Terminal::cleanup()`, which runs on every normal shutdown path (Ctrl+Q, signals, etc.) — i.e. this is a cleanup/shutdown path, not a startup path, and `in_fh` may legitimately already be gone by the time it runs. Adding a `warn` here would risk spraying stderr noise on ordinary exit (violating Rule 3's "no unexpected output on stdout/stderr"), whereas `enable_raw_mode`'s `warn` fires at startup where a failure is unambiguously abnormal and actionable. Decided the asymmetry is intentional and documented it in place with a comment on `disable_raw_mode` explaining why, rather than adding a `warn` — kept the change minimal/low-risk per the task's own guidance to prefer this when there's a plausible deliberate reason.

### P3: `⌃` (U+2303) control-key glyph hand-duplicated 13× in `Renderer.pm` — FIXED (2026-08-30)
Lines 3901, 3903, 3906, 3908, 4053, 4057, 4116, 4237, 4245, 5358, 5360, 5363, 5365 all inline `\x{2303}` as a raw literal instead of a named constant, directly contradicting `docs/CODE_QUALITY.md`'s own stated convention ("Define constants at module level for: Unicode characters... shortcut symbols"). `Zepto::Chars` has no entry for it either. Fix: one `CTRL_GLYPH => "\x{2303}"` constant, 13-site find/replace.

**Fix**: Added `use constant CTRL_GLYPH => "\x{2303}";` to `Renderer.pm`, next to the existing "Box-drawing characters" constant block (not `Zepto::Chars`, since that module is specifically for Nerd Font/ASCII fallback *pairs* — `⌃` is a plain Unicode glyph used unconditionally regardless of `Zepto::Chars->enabled()`, so it doesn't fit that abstraction). Replaced all 13 inline-literal sites (line numbers had shifted slightly from concurrent work; found via fresh `grep -n 'x{2303}'`) with `CTRL_GLYPH . "..."` concatenation. Verified byte-identical output before/after two ways: (1) a full `diff` of old vs. new `Renderer.pm` confirmed every changed line was a mechanical `"\x{2303}X"` → `CTRL_GLYPH . "X"` swap with no other changes; (2) a throwaway harness loaded both the pre-change and post-change `Renderer.pm` in separate processes and called `_core_nav_hint_text()` (which uses `CTRL_GLYPH` in both its labeled and compact branches) across several width values covering the undef/compact/labeled branches — output was byte-identical. Also verified interactively via `hangon`: status bar hints (`⌃W close`, `⌃G`, `⌃␣`), command palette title (`⌃␣ Commands`), and palette shortcut column (`⌃N`, `⌃O`, `⌃S`, etc.) all render correctly.

### P3: Tab Width's `1`/`16` bounds are duplicated as bare literals — FIXED (2026-08-30)
`Editor/Commands.pm:1374,1380` — the `'1-16'` hint string and the `$input >= 1 && $input <= 16` validation both hardcode the same bounds 6 lines apart with no shared constant.

**Fix**: Added `use constant { TAB_WIDTH_MIN => 1, TAB_WIDTH_MAX => 16 };` directly above `cmd_set_tab_width` in `Editor/Commands.pm` (line numbers had shifted to ~1285 from the cited 1374/1380 due to the `do_find_next`/`do_find_prev` deletion earlier in the same file). Used the constants in all three places that previously hardcoded the bounds: the `hint => '1-16'` string (now `TAB_WIDTH_MIN . '-' . TAB_WIDTH_MAX`), the `$input >= 1 && $input <= 16` validation, and the `"Invalid tab width. Use a number 1-16."` error message (a third hardcoded-bounds site the original finding didn't call out, found while making the fix). Verified byte-identical output (`perl -e` one-liner printing both interpolated strings against the new constants matches the original literal text exactly) and verified interactively via `hangon`: the footer input shows "(1-16)", an out-of-range value (99) shows "Invalid tab width. Use a number 1-16.", and a valid value (8) is accepted and applied.

### Performance (P2/P3)

### ~~P2: Syntax highlighter re-tokenizes every visible line on every render — no token cache~~ FIXED
`Highlighter.pm:539-565` (`tokenize_line`) only caches per-line *end state*, not the resulting token list. `Renderer.pm:2415` calls `tokenize_line()` once per visible line on every single render — and `render()` runs on essentially every keystroke/scroll/cursor-move. Moving the cursor one column re-tokenizes all ~40-80 visible lines from scratch, not just the changed line.

**Root cause:** `tokenize_line()` recomputed `$self->{grammar}->tokenize($line_content, $start_state)` unconditionally on every call. The only caching was `$self->{line_states}[$line_num]` (the *end state*, used to seed the next line), never the token list itself — so every visible line's tokens were thrown away and recomputed from scratch on every single `render()`, regardless of whether that line's content or incoming state had actually changed.

**Fix:** Added a token memo cache to `Highlighter.pm`, keyed on `(start_state, line_content)` — a two-level hash `_token_cache => { start_state => { line_content => [tokens, end_state] } }`, checked/populated inside `tokenize_line()` right where the old unconditional `tokenize()` call was. This is a **pure memoization cache**, not a line-number-indexed one, and that distinction is what makes it correctness-safe without any separate invalidation bookkeeping: `tokenize()` implementations across all grammars in `Syntax/*.pm` are verified pure functions of exactly `($line, $state)` (no instance or module-level mutable state read during tokenization — confirmed by auditing every grammar for `$self->{...}` reads inside `tokenize()`, the only hit being HTML.pm's lazily-instantiated but still-pure embedded CSS/JS sub-grammars). Because the cache key captures every input that can affect the output:
- Editing a line's own content changes `$line_content` → new key → natural cache miss.
- Editing an *earlier* line in a way that changes what state a later, otherwise-untouched line starts in (e.g. opening/closing a multi-line comment upstream) changes `$start_state` → new key → natural cache miss.
- A cache *hit* only ever happens when both inputs are byte-identical to a previous call, in which case the pure function is guaranteed to return the same result.

There is deliberately no "invalidate on edit" logic to get wrong — staleness is structurally impossible given how the key is constructed, which is a stronger guarantee than an invalidate-on-edit scheme with a gap some line number could fall through. `set_file()` and `detect_from_shebang()` clear the cache wholesale when the grammar changes (Save As to a different extension, or shebang-based re-detection), since cached tokens are only valid for the grammar that produced them. Each open tab has its own `Highlighter` instance (`TabManager`), so the cache is naturally per-document with no cross-tab sharing risk (verified interactively and in tests — see below). Bounded via a size cap (`MAX_TOKEN_CACHE_ENTRIES => 8000`, cleared wholesale once exceeded), mirroring `Renderer.pm`'s existing `_table_cache` "evict by clearing" pattern (`Renderer.pm:1608`) rather than introducing a new LRU data structure — WrapMap's `_wrap_cache` was the other precedent considered, but it self-bounds differently (rebuilt fresh from a full-document pass each time, keeping only currently-referenced content) which doesn't map cleanly onto `tokenize_line()`'s per-line, renderer-driven call pattern; the simple size-capped clear was judged sufficient and lower-risk. Returned token arrayrefs are shared with the cache, not cloned — safe because the only real caller (`Renderer.pm:2420`, plus a diff-view "base" highlighter path at `Renderer.pm:3282-3295`) only reads token fields to build its own visual-position copies; audited every `tokenize_line()` call site (`Renderer.pm`, `tests/*.t`) to confirm none mutates the returned arrayref in place.

**Correctness verification:** `tests/highlighter.t` gained 5 new subtests (28 total, up from 23) specifically targeting cache-invalidation correctness, not just "cache works when nothing changes": repeated-identical-call memoization; an upstream edit that changes `start_state` is NOT served stale tokens (the core scenario — edits line 0 to open a block comment, confirms line 1's *unchanged* content re-tokenizes as a comment, not stale plain-code tokens); undo restores the exact original tokens, not a stale mid-edit version; no cross-contamination between two `Highlighter` instances tokenizing identical literal text under different grammars (simulating two open tabs); and a simulated multi-line paste that shifts line numbers, confirming shifted-but-unchanged tail content tokenizes identically at its new line number. Per Rule 5, each of these was validated as a real regression guard, not just a passing test: deliberately reverted the cache key to content-only (dropping `start_state`) and confirmed the upstream-edit and undo subtests both failed with the broken key, then restored the real fix and confirmed all 28 subtests passed again.

**Interactive verification (`hangon`):** Opened a JS file, edited an earlier line to open an unclosed `/* block comment`, and confirmed (via screenshot, comparing rendered colors) that all downstream lines — including a `function` declaration with no relation to the edited line — correctly switched to the muted comment color, with the entire rest of the file absorbed into the comment as expected (no closing `*/` anywhere below). Added a closing `*/` mid-line further down and confirmed normal keyword/string coloring correctly resumed on the rest of that line and everything after it. Undid the edit and confirmed original highlighting was restored, not stuck on the mid-edit comment coloring. Opened a second tab with a Python file mid-way through the JS tab's unclosed-comment edit and confirmed the Python tab highlighted completely normally with no bleed-through from the JS tab's state; switched back to the JS tab and confirmed its state was undisturbed. Scrolled through and typed inside a large real file (`Highlighter.pm` itself, ~650 lines) with no visual glitches. (One dead end during this verification: an initial screenshot read was misjudged by eye as "line 12 stayed in keyword-blue color, not comment-colored" — turned out to be the cursor-line highlight background distorting the small-screenshot color perception, not a real bug; confirmed via both the exact raw ANSI RGB byte capture at that pixel — `38;2;150;175;200`, matching `syntax_comment` exactly, not `syntax_keyword`'s `38;2;187;154;247` — and a follow-up screenshot with the cursor moved off that line.)

**Benchmarks (real numbers, isolated Perl scripts against a 5200-line JS-like file with real keywords/strings/comments/multi-line block comments, scrolled to the middle so state-propagation is exercised, not just line 0):**
- Isolated `tokenize_line()` cost for a 47-line visible viewport, single-character edit + re-tokenize cycle (only 1 of 47 lines' content actually changes each pass, matching the real per-keystroke case): **1.73ms/pass before → 0.135ms/pass after — ~12.8x faster** for the code path this fix directly touches.
- Full `Renderer->render()` cost for the same edit-then-render cycle (includes gutter, wrap map, minimap, ANSI generation — everything else a real frame does, not just tokenization): **5.00ms/render before → 3.31ms/render after — ~1.5x faster** end-to-end. The gap between these two numbers is expected and informative: tokenization was a real but not dominant fraction of total render cost at this viewport size, and the full-render number is the one a user actually feels.
- An interactive (`hangon`/tmux round-trip) typing-burst timing check was attempted as an additional regression guard but found unable to discriminate the fix at any budget tight enough to be meaningful — PTY/tmux send-and-capture overhead dwarfs the millisecond-level render difference even at 20,000 lines. This matches `qa/lib/qa-perf-helpers.sh`'s stated design intent (catch gross regressions/hangs, not micro-benchmark); the QA-REG-201 interactive script below is a coarse "stays within budget, doesn't hang" smoke test for that reason, not a tight discriminator — the isolated Perl benchmarks above are the real evidence for this fix's improvement.

**QA:** `qa/scripts/tier1/reg_199_highlighter_cache_upstream_edit.sh` (QA-REG-199) — interactive repro of the core cache-invalidation scenario, verified via raw ANSI color-code capture (`tmux capture-pane -e`, the technique QA-REG-160 established, since `hangon screen` strips color and the plain text is identical either way). `qa/scripts/tier1/reg_200_highlighter_cache_undo_restores_tokens.sh` (QA-REG-200) — the undo companion. `qa/scripts/tier1/reg_201_highlighter_cache_large_file_typing_perf.sh` (QA-REG-201) — coarse responsiveness smoke test on a 3000-line file (see benchmarks note above on why this is coarse rather than a tight discriminator). All three mutation-tested the same way as the unit tests (confirmed failing against a deliberately-reintroduced content-only cache key, then passing again against the real fix). New feature entry `QA-SYN-023` added to `qa/32_syntax_highlighting.txt`.

### P2/DRY: ~48 of 53 syntax grammars share a systemic O(n²) tokenizer pattern that's explicitly documented as the "correct" way to write one
Nearly every grammar's `tokenize()` loop does `my $rest = substr($line, $pos); ... $pos++` — reallocating a copy of the remaining line on every iteration, which is O(line-length²) for a line advanced mostly one character at a time (long minified/generated/log lines). `Syntax/Base.pm:293-354` documents this exact pattern as the recommended template ("copy into your grammar") rather than offering shared helpers — so this is architecturally sanctioned duplication as much as a performance issue. The block-comment/line-comment/quoted-string/char-literal scanning blocks themselves are near-verbatim identical across `C.pm`, `Java.pm`, `Cpp.pm`, `CSharp.pm`, `JavaScript.pm`, `TypeScript.pm`, `Go.pm`, `Swift.pm`, `Kotlin.pm`, `Scala.pm`, `ObjectiveC.pm`, `Groovy.pm`, `PHP.pm`, and others — the single largest duplication surface in the codebase. Fix (larger scope, cross-cutting): introduce shared `scan_block_comment()`/`scan_quoted_string()`-style helpers in `Base.pm` and migrate grammars onto them; lower-risk partial fix is just the token-cache above, which reduces how often the O(n²) cost is even paid.

### ~~P3: Minimap VCS-status aggregation scans the whole document on every keystroke~~ FIXED
`Minimap.pm:141-150` (`_cache_key`) includes `content_version()`, so the entire minimap recomputes on every edit, not just when VCS/diff state changes. `_aggregate_vcs_status()` (`Minimap.pm:310-344`) scans every document line in each row's span with no subsampling (unlike the braille density path, which is capped at `MAX_SAMPLE_LINES => 4`). For a 100k-line file with ~50 minimap rows, that's up to ~100k-200k hash-lookup calls per keystroke — individually cheap but scales with total document size, not viewport size.

**Reproduced first:** isolated benchmark against a real 100k-line `Document` with scattered VCS added/modified lines (`~1%` density) and a real minimap height of 50 (`lines_per_row=2000`): a single `Minimap->compute()` after a simulated edit (`content_version` bump, matching what every keystroke does) cost ~56ms warm; 20 simulated keystrokes in a row cost 1.25s total (0.062s/keystroke) against unfixed code. Isolating `_aggregate_vcs_status()` from `_compute_braille()` (which already has its `MAX_SAMPLE_LINES=4` cap) showed VCS aggregation was ~24x the cost of braille density per row — confirming it was the dominant unbounded cost, not braille.

**Fix:** Added `MAX_VCS_SAMPLE_LINES => 200` (`Minimap.pm`, next to `MAX_SAMPLE_LINES`) and applied the same evenly-spaced-subsample technique the braille path already uses inside `_aggregate_vcs_status()`: below the cap, every line in a row's span is still checked exactly (zero accuracy change from before); above it, 200 evenly spaced lines are sampled instead of the whole span. 200 (not braille's 4) was chosen deliberately — braille's 4 matches its *display* resolution (a braille glyph literally has 4 dot rows, so more samples add no visible information), but VCS status is a correctness signal ("did any line in this row change?"), so a much larger sample is needed to keep the false-negative rate low for realistic hunk-based diffs. This guarantees any contiguous changed hunk of `ceil(line_span / (MAX_VCS_SAMPLE_LINES-1))` lines or more is always caught (pigeonhole on the sample spacing) — verified directly in `tests/minimap_vcs_perf.t` by filling the widest actual sample gap at span=3000 (16 lines) and confirming detection.

**Accepted tradeoff (not fixed, by design):** above the cap, a truly isolated single-line change that doesn't land on a sampled line can be missed — `tests/minimap_vcs_perf.t`'s "KNOWN LIMITATION" subtest demonstrates this concretely (old algorithm catches it, new one doesn't) rather than hiding it. This is the same class of tradeoff the pre-existing braille cap already accepts for text density; real diffs are overwhelmingly hunk-based (multiple consecutive lines), not single isolated lines deep inside a multi-thousand-line minimap row, so this was judged an acceptable cost for bounding per-keystroke work to a constant regardless of file size.

**Benchmarks (real numbers, `Time::HiRes`, 100k-line document, height 50, 20 simulated keystrokes):** 0.0624s/keystroke before → 0.0064s/keystroke after (~9.8x). At a larger stress case (300k lines, height 20, `lines_per_row=15000`): 0.1147s/keystroke before → 0.0019s/keystroke after (~60x) — confirming the fix's benefit *grows* with file size/row span, as expected for turning an O(span) scan into an O(cap) one.

**Tests:** `tests/minimap_vcs_perf.t` (new) — reconstructs the old unbounded algorithm verbatim (same pattern as `tests/filetree_vcs_perf.t`) for side-by-side correctness and performance comparison in the same run: below-cap old/new agreement (multiple distributions), above-cap guaranteed-catch property (sample-point hit, full-gap hunk), the known-limitation demonstration above, a public-API (`Minimap->compute()`) correctness check with a known injected change, and self-proving performance bounds at two scales (old provably exceeds the bound, new provably clears it, ≥5x speedup asserted). Proven to fail loudly against unfixed code: swapping in the pre-fix `Minimap.pm` (via `git show`, not `git stash`) makes the test suite abort immediately with `Undefined subroutine &Zepto::Minimap::MAX_VCS_SAMPLE_LINES` rather than silently passing.

**QA:** `QA-REG-233` in `qa/40_regression_bugs.txt`, cross-referenced to `QA-GUT-*` in `qa/27_gutter_ruler_minimap.txt`.

### P3: `LineMap::_rebuild()` does a full O(document) rebuild per keystroke in a narrow scenario
`LineMap.pm:90-206` is correctly gated to only rebuild when hunks or line count change (`Editor.pm:4824-4832`), but line count changes on every Enter/newline-delete — so editing a large file while in an expanded-diff-hunk word-wrap view triggers a full rebuild per newline keystroke. Narrow trigger condition (diff view + expanded hunk specifically), low overall severity.

### P3: `Diff.pm` hunk-pairing is O(inserts × deletes) per hunk
`Diff.pm:328-345` — pairing inserted/deleted lines within a "modified" hunk is a nested loop bounded by hunk size, not file size. Diff computation is already debounced (0.3-1s); only a concern for a single hunk spanning hundreds of consecutive modified lines (e.g. a full-file reformat).

### Architecture (tracked separately, cross-referenced here)

The Editor god-object (`Editor.pm`/`Editor/Commands.pm`/`Editor/Palette.pm`, all three literally re-declaring `package Zepto::Editor;` so there's no real encapsulation between them — 7,816 lines/222 methods, confirmed +29%/+36% growth with zero extraction since the last self-audit) is already tracked as "P3: [Architecture] Editor is a 6000-line god object" elsewhere in this file. Not re-logged as a new entry here — see that existing entry, and the separate strategy discussion in this session's conversation for the incremental-extraction approach being considered.

## Found while fixing the "Scorecard audit round 2" dead-code/consistency items (2026-08-30)

### P3: Repeated Ctrl+J/Ctrl+K (Find Next/Prev) can get "stuck" on the same match or skip one entirely
Discovered while re-deriving real expected behavior for `cmd_find_next`/`cmd_find_prev` to migrate `tests/editor.t`'s dead-code-only find tests (see "`do_find_next`/`do_find_prev`..." above) and while building `qa/scripts/tier1/reg_196_find_next_prev_real_cmd.sh`.

`cmd_find_next`/`cmd_find_prev` (`Editor/Commands.pm:696-722`) both call `enter_find_mode()` — which re-runs `_update_find_matches()` → `_find_nearest_match()` and jumps the cursor to whatever match is nearest the *current* cursor position — **on every single invocation**, then call `_find_navigate($direction)` to step one further from there. This is correct and predictable when starting from a cursor position that isn't sitting exactly on a previous match (verified: from a clean `Ctrl+G`-reset position, both directions land exactly where expected). But `_jump_to_match()` (`Editor.pm:3080-3100`) always leaves the cursor at the **end** of the just-selected match (`col + length`), and `_find_nearest_match`'s "prefer match at-or-after cursor" comparison (`Editor.pm:3014-3049`) uses the match's own *start* column against that end-of-match cursor position — so immediately re-invoking the same command (or the opposite one) from that landing spot re-anchors somewhere other than a naive "current index ± 1" would predict. Concretely reproduced via `hangon` on a 3-match file (`MARKER one` / `line two` / `MARKER three` / `line four` / `MARKER five`): pressing Ctrl+J repeatedly (with a dismiss in between, matching real usage) cycles between only 2 of the 3 matches (line 1 and line 5), **never landing on line 3's match at all**; and pressing Ctrl+K immediately after a Ctrl+J that landed on the very first match in the file visibly does nothing (cursor doesn't move) because the re-anchor-then-step-back cancels out. Not fixed here — out of scope for the dead-code cleanup task that surfaced it. `qa/scripts/tier1/reg_196_find_next_prev_real_cmd.sh` deliberately resets the cursor via Ctrl+G before each check specifically to avoid asserting on this quirky chained behavior (see the script's own comment), so it does not regression-guard this specific issue — a future fix here should add its own dedicated QA script reproducing the stuck/skip sequence once someone decides what the *intended* behavior should be (a simpler design that just uses `find_current` as-is without re-deriving "nearest to cursor" on every call would probably not have this problem, but changes user-visible behavior and needs a product decision, not a unilateral fix).

## Scorecard audit round 3 (2026-08-30, overnight autonomous session) — full findings from a 6-agent parallel re-audit

Findings from a fresh codebase scorecard (architecture, code quality, security, tests/docs, performance/duplication, plus a dedicated Editor-god-object extraction scoping pass) run after round 2's fixes fully landed and were verified via a clean 628-script tier-1 QA pass. Every item below is newly found this round — not a re-report of anything already tracked/fixed elsewhere in this file. Each will be marked FIXED with a root-cause/fix/test writeup by whichever agent picks it up, following this file's normal convention.

### Availability / correctness (P0/P1)

### ~~P0: Find & Replace's "preview" mutates the real document and corrupts on-screen rendering — despite being explicitly documented as non-mutating~~ FIXED
Found 2026-08-30 by a research agent verifying a user-reported "find and replace preview buggy" note, not by the round-3 scorecard sweep — added here as its own top-severity entry since round 3's sweep didn't cover interactive find/replace preview at all (`qa/09_find_replace.txt` had zero test cases exercising live preview rendering, confirmed coverage gap — a `find_007_replace_preview.sh` QA *script* did already exist, but its catalog entry `qa/09_find_replace.txt`'s `QA-FIND-007` is unrelated ["Replace One replaces current match only"] — a pre-existing numbering mismatch between the script and its catalog ID — and its assertion, `qa_assert_expect "ZZZ"`, is a substring match that would still have passed even with the "fooZZZ" concatenation bug present, since "ZZZ" is a substring of "fooZZZ" too; this is why the coverage gap wasn't caught earlier despite a script nominally existing).

Reproduced interactively via `hangon` (build was current, no rebuild needed): open `⌃F`, type a find term (`foo`), `Tab` to the replace field, type a replacement (`XYZ`), against a file with multiple `foo` occurrences each followed by more text on the same line (`foo bar`, `foo baz`, `qux foo`, `hello world`). Three distinct, compounding problems observed:

1. **Screen corruption**: every keystroke in the replace field leaves a stacked duplicate row of the find/replace bar and preview lines instead of overwriting in place — after 4 keystrokes, 4 stale find-bar rows and 3 stale preview-line rows remained on screen simultaneously. This artifact survives `Escape` and reopening `⌃F` fresh.
2. **Wrong preview text**: the preview showed `fooXYZ` for a line whose real content is `foo bar` — it concatenated match+replacement and dropped the rest of the line (` bar`) instead of computing the correct `XYZ bar`, per what `FindEngine.pm:preview_line` (`FindEngine.pm:411-467`) should produce.
3. **Actual document mutation** (the P0-caliber part): after escaping the find/replace UI and later pressing `⌃Z` repeatedly, the undo stack revealed real edits had been pushed to the buffer during the "preview" interaction — one intermediate undo state showed a line missing its matched text (`qux ` instead of `qux foo`) with the tab's dirty-indicator set — even though `FindEngine.pm:399` explicitly comments this path as "Virtual - doesn't modify document." Undoing fully did correctly restore the original file content and clear the dirty flag (no permanent data loss observed in this session), but a preview path that's documented as read-only and is actually writing real, undoable edits into the document is a serious correctness violation — a crash, a forced quit, or any interruption mid-preview could plausibly leave a document permanently altered from what the user typed.

**Root cause investigation (2026-08-30):** traced all three symptoms to their exact origin before touching any code (Rule 5). Reproduced all three via `hangon` first using the exact repro steps above, then isolated each symptom with standalone Perl harnesses driving `Zepto::Editor`/`Zepto::FindEngine` directly (not just reading source), and finally re-confirmed everything interactively.

- **Symptom 1 (screen corruption) — real bug, root cause found.** `Renderer.pm`'s `_render_find_bar` computes each input field's width as `$available / num_fields`, then unconditionally floors it up to `FIND_INPUT_WIDTH_MIN` (8 cols) — *even when the actual layout budget (`$available`) is smaller than that floor.* Wrote a standalone script rendering `_render_find_bar` directly across a range of terminal widths with `replace_active=1` and a 3-match count (`"↑↓ 3 of 3"`, 9 chars) and measured the stripped-of-ANSI visible width against `$cols`: **at the common 80-column terminal default, the line overflowed by 4 characters** (60 cols: overflow by 24; 70 cols: no overflow — the specific overflow width is a function of match-count-text length and terminal width together). A `padding_needed = 1 if $padding_needed < 1` clamp compounded this by adding an extra character even when the line was already over budget. On a real terminal, writing past the right edge auto-wraps onto the next physical row — and the differential renderer (`Editor.pm::render()`, which tracks content per *logical* row and only re-emits rows whose content changed since the last frame) has no way to know that overflow spillage landed on the row below, so it never clears it. Every replace-field keystroke re-triggers this (match-count text length can also vary as the search re-runs), which is exactly why stale rows kept stacking up: each new overflowing frame left another row uncleared. Confirmed via direct measurement of `_render_find_bar`'s output at cols=80 both before and after the fix (84 visible chars pre-fix vs. an 80-col-clamped budget post-fix).
- **Symptom 2 (wrong preview text) — real bug, but NOT in `FindEngine::preview_line`.** Read `preview_line` (`FindEngine.pm:411-467`) fully: it's correct — for a match at `(line, col, length)` it builds `substr(original, last_end, col-last_end) . expanded_replacement . ...` and finally appends `substr(original, last_end)`, i.e. genuinely in-place substitution. Confirmed via a standalone harness calling `preview_line` directly (`foo bar` + replacement `"XYZ"` → `"XYZ bar"`, correct) — this is also now `tests/find.t`'s `'preview_line: replacement substituted in place...'` subtest. The actual bug is one level up, in `Editor.pm`'s Tab handler (`handle_find_event`, the `Tab: toggle between find/replace fields, or show replace` branch): when Tab first activates the replace field, it prepopulates it with the find term via `$self->{find_replace_widget}->set_value($self->{find_widget}->value())` — but unlike the find field's own prepopulation from a previous search term (`enter_find_mode`, which explicitly sets `sel_start`/`sel_end`/`cursor` to select the whole seeded value), the replace field's seed text was left unselected, cursor at the end. So the first keystroke *appended* to "foo" instead of replacing it — typing "XYZ" produced the replace-field value `"fooXYZ"`, and `preview_line` correctly (!) substituted that whole literal string in for each match, producing `"fooXYZ bar"`. The "dropped the rest of the line" part of the original report was actually just symptom 1's row corruption visually truncating the already-wrong `fooXYZ bar` text down to `fooXYZ` on screen — two bugs compounding into one confusing-looking symptom. This same pre-select gap silently corrupted real (non-preview) Replace-All results too, not just the preview — confirmed by running the exact same repro through to a real Enter-confirmed Replace-All on the pre-fix binary: `foo bar` became `fooREPL bar` instead of `REPL bar`.
- **Symptom 3 (real document mutation) — did NOT reproduce.** Traced every call in the preview path: `Editor::_apply_replace_preview` → `FindEngine::preview_viewport` → `FindEngine::preview_line`/`matches_for_line`/`expand_replacement_for_match`/`_expand_replacement` — every single one reads via `$doc->get_line_content()` (or pure string manipulation with no `$doc` access at all in `_expand_replacement`); none calls `insert`/`delete`/any mutating `Document` method. Confirmed empirically two ways: (a) a standalone Perl harness driving `Zepto::Editor::handle_find_event` through the exact repro (type "foo", Tab, type "X"/"Y"/"Z" one char at a time) while snapshotting `$doc->text()`, `$doc->{undo_stack}` depth, and `$doc->is_dirty()` before and after every keystroke — all three were byte-identical/unchanged throughout, including after Escape; (b) full interactive `hangon` reproduction of the exact steps, escaping, waiting past the terminal's inherent ESC-key ambiguity timeout (`INPUT_TIMEOUT_SEC` = 0.5s — a standalone Escape keypress vs. the start of an Alt+key/escape sequence must wait for this timeout to resolve; capturing the screen before it elapses shows a stale frame, which is a red herring, not a bug), then pressing `⌃Z`: the editor reported "Nothing to undo" and the original file content was intact. Best explanation for the original report: the reporting agent most likely mistook symptom 1's screen-corruption artifact (rows visually shifting/overlapping as the terminal auto-wrapped and, on the bottom status row specifically, scrolled) for real document edits when reading a scrambled screen — an easy mistake given how convincingly the corrupted frame resembled genuine buffer changes.

**Fix:**
1. Extracted a new shared `Zepto::Renderer::find_bar_input_width($cols, $replace_active, $right_side_width)` (same "exported so Editor.pm can use the same calculation" convention as the pre-existing `get_gutter_width`) that only grows up to the `FIND_INPUT_WIDTH_MIN` usability floor when the layout budget actually has room for it in *every* field — otherwise it shrinks below the floor (down to a hard floor of 1) rather than overflow `$cols`. This single function replaces 3 previously hand-duplicated copies of the same width formula: `Renderer.pm::_render_find_bar`, `Editor.pm::handle_find_bar_click`, and `Editor.pm::_handle_find_bar_drag` (the latter two needed the identical formula to keep mouse click/drag hit-regions in sync with what's actually drawn). Also changed `_render_find_bar`'s `padding_needed = 1 if $padding_needed < 1` floor to `0` (forcing a minimum of 1 could itself add a stray character beyond the newly-correct budget in the tightest cases).
2. In `Editor.pm`'s `handle_find_event` Tab handler, the replace field's Tab-prepopulated seed text is now pre-selected (`sel_start`/`sel_end`/`cursor` spanning the whole seeded value) the same way the find field's own seeded value already was — so the first keystroke replaces it instead of appending to it.
3. No fix needed for symptom 3 (no bug found) — added regression tests asserting the no-mutation guarantee directly instead (see Tests below), so any future regression that *does* introduce a real mutation into the preview path will be caught even though none exists today.

**Residual known limitation (logged separately, not fixed here):** an extremely narrow terminal (≤70 cols) combined with a very large match count (15+, producing a long "of N" string) can still overflow by a few characters — the fixed-width elements (pills, labels) plus a long match-count string alone approach `$cols` before any input-field width is even considered, which `find_bar_input_width`'s per-field floor can't compensate for. This is a much more extreme combination than the reported repro (3 matches, 80-column terminal) and is scoped out of this fix; see the new P3 entry below.

**Tests:**
- `tests/find.t`: 4 new subtests — `'Replace preview never mutates document content or undo stack'` (exercises the exact repro via real `handle_find_event` calls, asserting `$doc->text()`, undo-stack depth, and dirty-flag are unchanged after every keystroke and after Escape); `'Replace preview text is correct in-place substitution, not concatenation'` (asserts the full pipeline produces `"XYZ bar"`/`"XYZ baz"`/`"qux XYZ"`, not `"fooXYZ..."`); `'Tab-prepopulated replace field is pre-selected...'` (asserts `has_selection()` after Tab and that typing replaces rather than appends); `'preview_line: replacement substituted in place...'` (direct `FindEngine` check for the plain-literal-mode path, complementing the existing capture-group-mode preview test). All 4 verified failing against pre-fix code via `git stash` (2 genuinely fail — the preview-text and pre-select ones — matching the real bug; the mutation-guard ones pass both before and after, consistent with symptom 3 not existing) and passing after.
- `tests/renderer.t`: 3 new subtests — `'find_bar_input_width never lets fields exceed their budget'` (property check across cols 40-200 × replace on/off × several right-side widths: `input_width * num_fields <= available` always holds); `'Find bar with replace field never exceeds $cols at common terminal widths'` (renders `_render_find_bar` directly at cols 70-120 with the exact repro's growing replace values, asserts stripped visible width `<= $cols`); `'Find bar with no matches / longer match counts never exceeds $cols'` (cols 76-120 × match counts 0-9999). Verified failing against pre-fix code (crashes — `find_bar_input_width` didn't exist — confirming the fix is structurally necessary, not just a tautological wrapper) and passing after.
- `make test`: 44 files, 1211 tests, clean, no noise.
- `qa/scripts/tier1/reg_211_find_replace_preview_no_mutation.sh` (QA-REG-211): full interactive repro via `hangon` — types the exact reported sequence, asserts correct preview text at each keystroke, asserts exactly one find-bar row and one preview-text row on screen (no stacked duplicates), asserts `⌃Z` reports "Nothing to undo" after Escape, and regression-guards that a real Enter-confirmed Replace-All still works and is fully undoable. 18/18 assertions pass against the fix; 8/18 fail against the pre-fix binary (verified via `git stash` + rebuild), reproducing the exact reported symptoms including the real-Replace-All corruption discovered above. Added `QA-FIND-028` to `qa/09_find_replace.txt` (the missing catalog coverage bugs.md originally flagged) cross-referencing the script.

**Verification (Rule 2):** full interactive `hangon` walkthrough of the exact repro post-fix: typed `foo` → `X` → `Y` → `Z` into find/replace fields one keystroke at a time, screen showed correct `X bar` → `XY bar` → `XYZ bar` with no stacked rows at every step; Escape (waiting past the 0.5s ESC-ambiguity timeout) restored the original screen and content exactly; `⌃Z` reported "Nothing to undo"; a real Enter-confirmed Replace-All correctly replaced all 3 matches, showed the "Replaced 3 occurrences" message, and was fully undoable back to the original content via repeated `⌃Z`; Escape-to-cancel-without-replacing (typed a different find/replace pair, Escaped) correctly left the document untouched. No regressions found in the shared code paths this fix touches.

### ~~P1: Multi-cursor backspace/insert desyncs secondary cursor positions across line-joins and multi-line-selection deletes — real data corruption~~ FIXED
`Editor.pm:4109-4175` (`_multi_cursor_backspace`) and `Editor.pm:4056-4106` (`_multi_cursor_insert_char`) maintain correctness for *unprocessed* cursors only by adjusting their `col` (same-line case) or `line` (line-join case) — never both together, and never at all for a deleted-lines range.

In `_multi_cursor_backspace`'s line-join branch (`4145-4159`), when cursor `$c` backspaces at column 0 and joins its line into the previous line, any not-yet-processed cursor sharing that same original line has its `line` decremented (correct) but its `col` is left untouched, even though the merge shifts that cursor's content by `+$prev_len` columns. Confirmed via direct reproduction (bypassing UI, calling `do_backspace()` on a 2-cursor view): starting with `"hello\nworld\n"`, primary cursor at `(1,0)` and secondary at `(1,3)`, after backspace the document correctly becomes `"hellowold\n"`, but the secondary cursor ends up at `(0,2)` — pointing at a completely unrelated character. `_multi_cursor_insert_char` has the same class of gap: when a cursor's own selection deletion spans multiple lines (`$sl != $el`, `4072-4082`), no line-number adjustment is applied to other not-yet-processed cursors on lines below the deleted range at all.

Impact: with 2+ cursors/multi-line selections active and any edit that removes a line boundary or spans multiple lines, secondary cursors silently land at the wrong document position, and the very next keystroke inserts/deletes at that wrong location — real data corruption, undetectable from the UI until the user notices garbled text elsewhere. No existing test in `tests/multi_cursor.t` exercises a line-join or multi-line-selection scenario with 2+ cursors — every current case keeps cursors on the same line. Root cause noted separately below (P3/DRY): the same fix-up logic is independently reimplemented 5 times across `_column_*`/`_multi_cursor_*` functions, which is how this gap went unnoticed in 4 of the 5 copies.

**Root cause:** each of the 5 `_column_*`/`_multi_cursor_*` editing functions independently reimplemented "iterate cursors/rows in reverse, mutate the document, fix up other tracked positions" — and the fixup logic in the multi-cursor pair only ever tracked a single scalar `col` "delta," applied to same-line cursors. That representation has no way to express "this edit also changed the line number" or "this edit spans N lines," so the line-join branch bolted on a separate, narrower `line--` fixup loop that forgot to touch `col`, and the multi-line-selection-delete branch had no fixup loop at all (`$delta` stays `0`, so the `if ($delta != 0)` guard silently skips it). The column-select trio never hit this bug because rectangular column edits are geometrically confined to a single row each — there was never a real need for cross-position fixup in that code, which is exactly why bugs.md's separate P3/DRY finding below flagged the column trio's version as "simpler and correct for its narrower case," not because it was more careful.

**Fix:** replaced all 5 independent implementations with one shared position-fixup mechanism in `Editor.pm` (new section "Shared multi-position edit/fixup helper," right before the column-editing helpers):
- `_adjust_pos_for_edit($edit, $line, $col)` — a pure function that, given a text edit described as "delete `[($start_line,$start_col), ($end_line,$end_col))` then insert `$ins_len` newline-free characters at the start," computes where an arbitrary `($line, $col)` elsewhere in the document should now point. It handles all three cases *in one place, by construction*: unaffected (position strictly before the edit), collapsed (position inside/on the boundary of the deleted range), and shifted (position after the range — line shifted by however many lines were removed, and column re-based onto the far edge of the inserted text if the position shared the range's end line). This is the single case-`line==el` branch that both correctly handles a plain same-line column shift (when `start_line == end_line`, `lines_removed` is `0`) *and* a line-join or multi-line deletion (when they differ) — there's no separate "line-join" code path to forget to update.
- `_fixup_other_positions($positions, $skip_idx, $edit)` — applies `_adjust_pos_for_edit` to every position in the list except the one that just performed the edit, including each position's `anchor_line`/`anchor_col` if it has an in-flight selection (the old code never fixed up a not-yet-processed cursor's *anchor*, either — a second, smaller gap the unification closed for free).
- `_apply_edit_and_fixup_positions($self, $positions, $edit_cb)` — the shared driver: one undo group, calls `$edit_cb->($positions, $idx)` for each position (which performs the actual document mutation and returns an edit descriptor, or `undef` if nothing changed), then fixes up every other position against that edit.

All 5 call sites (`_multi_cursor_insert_char`, `_multi_cursor_backspace`, `_column_delete_selection`, `_column_insert_char`, `_column_backspace`, `_column_delete` — 6 functions total since `_column_delete_selection` is shared by two of them) now build a `@positions` array and an `$edit_cb` closure and hand both to `_apply_edit_and_fixup_positions`, instead of hand-rolling the reverse-iterate-and-fixup loop themselves. For the column trio this is provably a no-op change in behavior: every column edit is confined to a single row (`start_line == end_line` always), so `_adjust_pos_for_edit` always returns "unaffected" or "unchanged" for every other row — the shared helper degenerates exactly to the column trio's previous (correct, simpler) behavior rather than replacing it with something new to get right. Fixed the same table for `_multi_cursor_insert_char`'s previously-separate "delete selection" and "insert char" steps too: they're now expressed as a single edit descriptor (`start=selection start, end=selection end, ins_len=char length`) rather than two ad hoc deltas, so a not-yet-processed cursor gets one correct fixup call instead of a same-line-only approximation.

**Test:** New subtests in `tests/multi_cursor.t`:
- `'Multi-cursor backspace across line-join repositions other cursor (QA-REG-203)'` — reproduces the exact scenario from this bug's description (`"hello\nworld\n"`, cursors at `(1,0)` and `(1,3)`), asserts the document text AND both final cursor positions — `(0,5)` and `(0,7)`, not the bug's `(0,2)`.
- `'Multi-cursor backspace with multi-line selection repositions cursor below (QA-REG-204)'` — a forward multi-line selection `(0,2)`-`(2,2)` at one cursor, a plain cursor on the line below the selection at another; asserts the deleted-range collapse AND that the other cursor's line shifts by the number of removed lines while its own (already-applied) column edit is preserved.

Both confirmed failing against the pre-fix code first (Rule 5): ran `perl -Ilib tests/multi_cursor.t` before touching `Editor.pm`, watched exactly the predicted wrong values come back (`(0,2)`/`(0,5)` instead of `(0,5)`/`(0,7)`; secondary cursor's line staying at `3` instead of shifting to `1`). After the fix: `prove -l tests/multi_cursor.t` (11 subtests) and `prove -l tests/column_select.t` (41 subtests, 804 lines of existing coverage per the scorecard finding) both pass in full, no regressions. Full suite: `make test` — 44 files, 1188 tests (was 1186; +2 for the new subtests), all pass, no stdout/stderr noise.

**Interactive verification:** Built `./zepto` from the pre-fix code first and reproduced the bug live via `hangon`: opened a 2-line file (`"PREFIX\nab.ab\n"`), used Ctrl+D twice to select both `"ab"` occurrences on line 2 (both cursors, no direct API access), typed `Z` to replace them (`"Z.Z"`), backspaced twice (the second backspace joins the now-empty line 2 into `"PREFIX"`), then typed `Q` — the buggy build showed `QPREFIXQ` (one cursor correctly appended after `PREFIX`, the other's stale column inserted at the very start of the word, corrupting it). Rebuilt with the fix, replayed the identical keystroke sequence: result was `PREFIXQQ` — both cursors landed correctly. Also reproduced the multi-line-selection-delete case live (secondary cursor via Ctrl+D on the last line of a 4-line file, primary cursor given a genuine multi-line selection via click + shift-click — confirmed this doesn't clear the secondary cursor, only arrow-key navigation and Escape do — then Backspace): pre-fix, the status bar reported the bystander cursor at a line number (`4`) that no longer existed in the resulting 2-line document; post-fix it correctly reported `2`. Additionally spot-checked normal (non-edge-case) usage stayed correct since this touches shared infrastructure: same-line 3-cursor replace-all (`foo bar foo baz foo` → `XY bar XY baz XY` → backspace restores `" bar  baz "`), and column-select insert/backspace/delete across 3 rows (`aaaa/bbbb/cccc` → `aXaa/bXbb/cXcc` → backspace restores → delete → `aaa/bbb/ccc`) — all correct.

**QA:** `QA-REG-203`/`QA-REG-204` in `qa/40_regression_bugs.txt`, `qa/scripts/tier1/reg_203_multicursor_linejoin_desync.sh` and `qa/scripts/tier1/reg_204_multicursor_multiline_selection_desync.sh`, plus `QA-MC-015`/`QA-MC-016` in `qa/11_multi_cursor.txt`. Both scripts confirmed failing against the pre-fix binary (2/8 and 1/7 checks failing respectively, exactly the corruption-detecting assertions) and passing in full against the fix.

### Security (P1/P2)

### ~~P1: `FileSearchEngine.pm`'s "Find in Files" regex search has no match-time ReDoS timeout, only compile-time~~ FIXED
`FileSearchEngine.pm:298-317` wraps `qr//` *compilation* in `alarm(1)`, but the actual per-line matches — `FileSearchEngine.pm:491` (`$content =~ $re`) and `:540` (`$line =~ $perl_regex`, inside the `_tick_perl` scan loop) — run with no alarm/timeout at all. This is the exact gap `FindEngine.pm` (in-buffer find/replace) already fixed and documented at length (`FindEngine.pm:505-565`, whose own comment explicitly explains "the compile-time alarm... provides zero protection against catastrophic backtracking, which happens at MATCH time"), but the fix was never applied to the sibling project-wide search engine. Exploit: run "Find in Files" with regex mode and a catastrophic-backtracking pattern (e.g. `(a?){28}a{28}`) against any project file containing a long run of `a`s — the tick loop hangs indefinitely on that single match, freezing the async search (and potentially the whole UI depending on tick scheduling) with no recovery path short of killing the process. Fix: add the same match-time alarm guard `FindEngine.pm` already established to both call sites.

**Root cause:** Same shape as the already-fixed `FindEngine.pm` gap (`QA-REG-141`/`QA-SEC-012`): `_start_perl_search()`'s alarm guards `qr//` compilation only and is explicitly cancelled (`alarm(0)`) before either match site is ever reached. Confirmed exploitable with a standalone repro calling `FileSearchEngine::tick()` directly against a 1-file/1-line project: `(a?){28}a{28}` against a line of 28 `a`s took 17.8 seconds inside a single `tick(30)` call, because the whole line's match happens as one uninterruptible `=~` inside `_tick_perl`'s scan loop — the loop's own `time() >= $deadline` check only runs *between* completed line matches, so it can never interrupt one pathological attempt already in progress.

**Fix:** Added a `MATCH_ALARM_SECS => 1` constant and a `_match_with_alarm()` helper — copied line-for-line from `FindEngine.pm`'s (same name, same signature, same `$1`/`@-`/`@+`-read-inside-the-coderef discipline, same `eval`/`local $SIG{ALRM}`/`alarm(0)`-on-both-paths cleanup) — and wrapped both match sites (`_find_match_in_content`'s `$content =~ $re` and `_tick_perl`'s `$line =~ $perl_regex`) with it. On timeout: unlike `FindEngine.pm`'s single `/g`-loop-over-one-buffer case (where retrying from the same `pos()` would just hang again, so it aborts the whole search), each `_tick_perl` line is different input, so timing out on one line sets a new `search_timed_out()` flag and treats that one line as "no match," then the scan continues to the next line/file — a single adversarial line degrades gracefully instead of taking down the whole project-wide search. A companion true-positive check (a mixed file with the pathological line on one line and an ordinary marker word on another, searched with `(a?){28}a{28}|MARKER`) confirms the marker match still surfaces — proving skip-and-continue, not silent total failure.

Test: `tests/file_search_engine_redos.t` (5 subtests: pure-Perl tick-loop hang, `search_timed_out()` flag + graceful `done` completion, timeout-on-one-line-still-finds-the-other-match, no false positives on a normal 20-file/20-match search, and match-position/highlighting through `_find_match_in_content` unaffected) — forked-child + parent-watchdog design, same as `find_engine_redos.t`, for the same alarm-clobbering reason. QA: `qa/scripts/tier1/reg_207_filesearch_redos_timeout.sh` (`QA-REG-207`) — interactively confirms the editor stays responsive (not just that the library function returns) when the pattern is typed into the live Find in Files palette; had to shadow `rg`/`grep` on `PATH` with always-fail stubs so `detect_backend()` actually falls through to the pure-Perl backend under test, since an external tool's own regex engine would otherwise silently make the interactive test not exercise the fixed code path at all.

**Found and logged, not fixed here (out of scope):** interactively testing this fix reproduced the same "Perl `use warnings` leaks to the terminal and corrupts the TUI" display bug already tracked below (found while fixing the `FindEngine.pm` version of this same issue) — confirmed it also reproduces via `FileSearchEngine.pm`'s own `qr//` compile call, same root cause, second call site. See that entry for detail; not a hang, editor stayed responsive underneath the garbled screen.

### ~~P2: AI API key passed as a `curl` command-line argument, visible to other local users via `ps`~~ FIXED (2026-08-30)
`AIComplete.pm:313-320`: `exec('curl', ..., '-H', "Authorization: Bearer $api_key", ...)`. Process argv is visible system-wide via `ps -ef`/`ps aux` (and `/proc/<pid>/cmdline` on Linux) to any other local user, for the lifetime of the curl child process — which fires repeatedly while typing with AI completion enabled (each request has its own short-lived curl child). On any shared/multi-user machine this leaks the user's AI API key. Fix: avoid the argv-visible header — options include a short-lived 0600 temp config file passed via `curl -K`/`--config` (cleaned up immediately after exec) or switching to a Perl HTTP client that doesn't expose the header in argv.

**Reproduced first**: confirmed the leak directly against the pre-fix code — ran the exact same `curl ... -H "Authorization: Bearer $api_key" ...` invocation `_child_http_request` used, against a deliberately slow local listener so the process stayed alive, and `ps aux | grep <fake-token>` found the raw token in the argv column while curl was running.

**Fix**: `_child_http_request` (`AIComplete.pm`) no longer puts the key in curl's argv at all. It now:
1. Writes `header = "Authorization: Bearer $api_key"` to a short-lived temp file via `File::Temp::tempfile('.zepto-ai-curl-XXXXXXXX', DIR => File::Spec->tmpdir(), UNLINK => 0)` — the same idiom `Document.pm`'s atomic-save path already established (unpredictable filename + exclusive creation, so another local user can't symlink-race or pre-create the path before the key is written), plus a belt-and-suspenders `chmod 0600`.
2. Passes that file to curl via `-K`/`--config` instead of `-H`. Verified with a real `curl -K` invocation against a local mock server that the `header = "..."` directive is honored identically to `-H` — the mock received the exact same `Authorization: Bearer ...` header.
3. Forks+execs curl itself (rather than the previous single `exec()` that replaced the process, or `system()`) specifically so it retains curl's pid: `_kill_child()` sends `TERM` to this process on essentially every keystroke while a request is in flight (that's the normal debounce-cancel path, not an edge case), and the wrapper needs to both propagate that signal to the actual curl child *and* unlink the header temp file before exiting — a plain `system()` would lose the pid needed for the first half, and a bare `exec()`-replaced process can't run cleanup code at all. The temp file is unlinked in the normal-completion path and in the `SIGTERM` handler, so it never survives past the request it was created for, cancelled or not.
4. The `exec(...)` fallback-on-failure statement is wrapped in `unless (exec(...)) { POSIX::_exit(127); }` rather than a bare statement following `exec(...)` — avoids Perl's compile-time "Statement unlikely to be reached" warning that a bare exec-then-statement triggers on every module load (would have been stderr noise on every single test run).

**Tests**: `tests/ai_complete.t` (new — `AIComplete.pm` previously had zero test coverage) exercises the real fork/exec code path against a stub `curl` on `PATH` that records its own argv and the `-K` file's mode/content instead of touching the network — confirms the raw key never appears in argv, the config file contains the correct `header = "..."` directive, the file is mode 0600, and it's deleted both on normal completion and when the wrapper is sent `SIGTERM` mid-flight (simulating a cancelled request). `qa/scripts/tier1/reg_209_ai_apikey_not_in_ps.sh` (QA-REG-209) drives the real, running editor end-to-end through the actual command palette against a local Perl-stdlib mock HTTP server, polls the live `ps` table while the real curl child is intentionally kept alive by a delayed mock response, and confirms both that curl was actually observed invoked with `-K <temp-file>` (proving the fixed path ran) and that the raw key/`Authorization` text never appeared in `ps aux`, plus that the mock server still received the correct header (proving the fix doesn't silently break the feature). Verified non-tautological: both the unit test and the QA script were run against the pre-fix code (`git checkout` of the vulnerable version) and failed exactly as expected — the key showed up in `ps aux` on the very first poll — then re-verified passing after restoring the fix.

**Interactive verification**: via `hangon`, ran the real editor with AI Completion configured against a local mock HTTP server standing in for the AI endpoint, typed to trigger a real completion request, and caught the live curl process in `ps aux` mid-request: `curl -sS -N -X POST -K /tmp/.zepto-ai-curl-MlcS7x6v -H Content-Type: application/json -d {...} --max-time 5 http://127.0.0.1:8899/chat/completions` — the temp-file path is visible, the key is not, anywhere in argv. Confirmed the mock server received the correct `Authorization: Bearer <key>` header and the response streamed back into the editor as ghost text, proving the fix doesn't break the actual request-sending path.

### ~~P3: AI API URL has no scheme enforcement, allowing silent plaintext transmission of the API key~~ FIXED (2026-08-30)
`Editor/Commands.pm:1386` (`cmd_ai_setup`) accepts any string as `ai_api_url` with no `https://` validation before it's later used to build the request URL and send the `Authorization: Bearer` header (`AIComplete.pm:305,316`). A user who mistypes/pastes an `http://` URL would have their API key sent in cleartext with no warning. Cheap fix: reject/warn on non-`https` URLs in `cmd_ai_setup`.

**Reproduced first**: confirmed via code reading (no scheme check anywhere between the footer-input's `on_submit` and `$prefs->set('ai_api_url', $url)`) and via `hangon`: entering `http://insecure.example.com/v1` at the pre-fix "API URL:" prompt was accepted silently, saved to `preferences.json`, and the wizard advanced straight to the "Model:" step with no warning.

**Fix**: `cmd_ai_setup`'s step-1 `on_submit` (`Editor/Commands.pm`) now rejects any URL that doesn't match `^https://` (case-insensitive) *before* saving anything, using the same `show_error_message()` pattern used elsewhere in this file (e.g. `cmd_set_tab_width`'s range validation) — no new error-reporting pattern introduced. On rejection: `$prefs->set('ai_api_url', ...)` and `$ai->{api_url} = ...` are never reached, so the invalid value is never persisted and the wizard does not advance to the "Model:" step, matching the existing early-`return` convention already used for the empty-input case one line above.

**Tests**: `tests/editor.t` gained two subtests — `'cmd_ai_setup rejects a non-https API URL'` (submits `http://...`, asserts `message_is_error`, the error text mentions https, `ai_api_url` in both prefs and the live `AIComplete` object is unchanged, and the wizard did not silently advance to the Model step) and `'cmd_ai_setup accepts a well-formed https API URL and proceeds to step 2'` (positive case, confirms save + advance). `qa/scripts/tier1/reg_210_ai_url_https_required.sh` (QA-REG-210) drives the real editor via the command palette end-to-end: rejects `http://` and a bare schemeless URL (neither gets written to `preferences.json`), then completes the full 3-step wizard (URL → Model → API Key) with a valid `https://` URL and confirms it's saved. Verified non-tautological: run against the pre-fix code, 5 of 17 assertions failed exactly as expected (error never shown, wizard advanced anyway, invalid URL landed in `preferences.json`); restoring the fix made all 17 pass again.

**Interactive verification**: via `hangon`, drove "AI Completion: Setup" from the command palette (confirming it's discoverable — Rule 2). Entering `http://insecure.example.com/v1` produced a red status-bar error ("...s sent as a request header, so a non-https URL would transmit it in plaintext.") and reopening setup afterward still showed the original default URL, confirming nothing was saved. Entering a valid `https://` URL, then a model, then a fake API key completed the full wizard normally ("AI Completion configured and enabled.") and `preferences.json`/`secrets.json` in the isolated `--state-dir` reflected the change with `secrets.json` still at mode 0600.

### Architecture (P2)

### P2: `Renderer.pm` has quietly become a second, undocumented god object — larger than `Editor.pm` itself
`Renderer.pm` is 5,845 lines / 49 subs — larger than `Editor.pm` (5,354 lines) and now the single largest file in the codebase. `DESIGN.md`'s architecture diagram (`DESIGN.md:57-61`) draws Renderer as a peer box to `Terminal` (806 lines) — a ~7x size mismatch within what the doc presents as comparably-scoped modules. Unlike the Editor/Commands/Palette trio (already tracked as a known, deferred god object elsewhere in this file), Renderer's growth is nowhere flagged — it has accreted rendering logic for tabs, status bar, minimap, markdown tables, ghost text, diff view, file picker, palette, and character-width math all into one file/package, with no submodule extraction analogous to `Editor::TabManager`. Same maintainability/testability risk as the documented god object, currently invisible to anyone tracking only the named trio. Not scheduled for immediate extraction — logged so it's tracked alongside the Editor god-object rather than discovered fresh in a future audit.

### ~~P3: `WrapMap.pm` reaches into `Renderer.pm`'s private functions — layering violation with an unenforced load-order dependency~~ FIXED
`WrapMap.pm:268,288,445` call `Zepto::Renderer::_expand_tabs()` and `Zepto::Renderer::_char_to_visual_col()` directly — both underscore-prefixed (private-by-convention per `docs/CODE_QUALITY.md:53`) functions belonging to a different module, reached via full package-qualification rather than a public API. A supposedly low-level layout module is hard-coupled to rendering-layer internals. It only works today because `build.pl`'s ordering rules happen to place Renderer (explicit priority 110) before WrapMap (falls through to the unlisted-module default priority 200) — there's no runtime check enforcing this in the bundled single-file output (`use Zepto::*` lines are stripped by `build.pl:135`), so a future reordering could silently break tab-width math with no compile-time signal.

**Root cause:** No public API existed on `Renderer.pm` for the tab/visual-column math other modules legitimately need — `WrapMap.pm` had no choice but to reach past the underscore-prefixed naming convention via full package qualification, since that was the only way to call the functions at all.

**Fix:** Added two thin, no-underscore wrapper subs to `Renderer.pm` right after the private functions they wrap (`expand_tabs()` and `char_to_visual_col()`, each a one-line `return _expand_tabs(@_)` / `return _char_to_visual_col(@_)` pass-through — no behavior change, just a supported entry point). Repointed all 3 `WrapMap.pm` call sites (`:268`, `:288`, `:445`) from `Zepto::Renderer::_expand_tabs`/`Zepto::Renderer::_char_to_visual_col` to `Zepto::Renderer::expand_tabs`/`Zepto::Renderer::char_to_visual_col`. Purely mechanical — the private functions themselves are untouched, and the wrappers are called exactly the same way (plain function call, not a method call) as what they replace. Note `visual_to_char_col` was already public with no underscore (an existing inconsistency this fix didn't need to touch, since `WrapMap.pm` already called it correctly at `:483`) — only `_expand_tabs`/`_char_to_visual_col` needed wrappers.

**Test verification:** `tests/wrapmap.t` (27 tests, all pre-existing, none modified) passes unchanged — confirms this is a pure refactor with zero behavior difference. Added a new subtest to `tests/renderer.t`, "Public expand_tabs()/char_to_visual_col() wrappers match the private functions exactly", which calls both the public and private forms with identical inputs and asserts identical output (including the full `char_to_visual` arrayref via `is_deeply`), guarding against the wrappers ever drifting into a second implementation.

**Interactive verification (`hangon`):** Opened a JS file with mixed tabs, confirmed rendering, wrapping, and tab-width changes (2/4/6/8) all render identically to before (see the shared verification session under fix #1 below — same session covered both, since #3's wrappers are on the hot path #1's cache sits in front of).

### Performance (P2)

### ~~P2: `Renderer.pm`'s `_expand_tabs()` has no cache — same missed pattern the Highlighter token cache (round 2) just fixed~~ FIXED
`Renderer.pm:2478` (main render loop) and `Renderer.pm:3353` (diff-view old-content render) call `_expand_tabs($line_content)` from scratch for every visible line on every single render, mirroring the pre-fix `tokenize_line()` pattern from round 2's Highlighter finding — recomputed even when neither the line content nor tab width changed since the last frame. `WrapMap.pm` solved this identical problem one file over with a content-keyed `_wrap_cache` (`WrapMap.pm:57-59, 209-251`), but `Renderer.pm` never adopted the same idea for its own per-line tab expansion. `_expand_tabs` itself (`Renderer.pm:287-312`) is O(line length), not O(n²) — the issue is redoing it unconditionally per visible line per keystroke with no memoization.

**Root cause:** `_expand_tabs()` had no caching at all — every call walked the full string character-by-character, even when called with byte-identical `($text, $tab_width)` inputs to the immediately preceding render (the overwhelmingly common case: only 1 of ~40-80 visible lines actually changes between two consecutive renders during normal editing).

**Fix:** Added a content-keyed memo cache directly inside `_expand_tabs()` (`Renderer.pm`, wrapped in a `{ ... }` closure block holding the cache state as package-level lexicals, matching this file's own pre-existing `_table_cache` closure pattern rather than instance state — `Renderer.pm` has no `new()`/instances, it's a pure class-method module). Keyed on a nested hash `tab_width => { text => [expanded, \@char_to_visual] }`. This is the same "pure memoization of every input that affects the output" design as round 2's Highlighter token cache (`Highlighter.pm::tokenize_line()`, keyed on `(start_state, line_content)`): expansion is a pure function of exactly `($text, $tab_width)`, so keying on both makes the cache **self-invalidating with no separate bookkeeping**:
- Editing a line's own content changes `$text` → new key → natural miss, never stale.
- Changing the tab-width preference changes `$tab_width` → new key → natural miss; old-width entries are simply never hit again, no explicit "clear on tab-width change" step needed (and no risk of a coarser, content-only key accidentally serving one width's expansion under a different width).

A cache hit only ever happens when both inputs are byte-identical to a previous call, in which case the pure function is guaranteed to return the same result. Returned arrayrefs are shared with the cache, not cloned — safe because every caller (`Renderer.pm`'s own render methods, plus `WrapMap.pm` via the new public `expand_tabs()` wrapper from the fix above) only reads `char_to_visual` by index/length, never mutates it in place (verified by inspection of every call site). Bounded via `MAX_EXPAND_TABS_CACHE_ENTRIES => 8000`, cleared wholesale once exceeded, mirroring `Highlighter.pm`'s `_token_cache` eviction (which itself mirrors this file's own `_table_cache` "evict by clearing" pattern) — `WrapMap.pm`'s `_wrap_cache` was the other precedent considered, but it self-bounds differently (rebuilt fresh from a full-document pass, keeping only currently-referenced content) which doesn't map onto `_expand_tabs()`'s per-call, renderer-driven pattern; the simple size-capped clear was judged sufficient and lower-risk, same reasoning round 2 used for the identical choice.

**Correctness verification:** `tests/renderer.t` gained 7 new subtests (up to 102 total from 95) specifically targeting cache-invalidation correctness, not just "cache works when nothing changes" (the explicit lesson from round 2's own writeup): identical repeated calls are memoized (same, not just equal, arrayref returned — proves the cache path actually ran); changed content is a cache miss that never returns stale data (including reverting content back to a previously-cached value correctly hits that original entry); changed tab_width (both explicit-argument and `set_tab_width()`-synced-default forms) is a cache miss that never returns stale data; distinct `(text, tab_width)` keys never collide (same text at two different widths must produce different output); bounded eviction (fills the cache to exactly `MAX_EXPAND_TABS_CACHE_ENTRIES`, confirms one more entry triggers wholesale eviction back down, confirms post-eviction calls still compute correctly); and the public-wrapper-matches-private-function test from fix #3 above. Per Rule 5, mutation-tested: deliberately collapsed the cache key to ignore `tab_width` (routing all entries through a single bucket regardless of width) and confirmed 5 of 102 subtests failed — both new cache tests AND 3 pre-existing tab-width tests from the earlier "Tab Width preference" fix (`QA-REG-189`) that happened to reuse the same `"\tx"` content at different widths — then restored the real fix and confirmed all 102 passed again.

**Interactive verification (`hangon`):** Opened a JS file with tabbed indentation, confirmed normal rendering. Changed Tab Width via the command palette 4→8→4 and confirmed the whole file's indentation visibly reflowed correctly each time (cache correctly keys per width, no stale rendering, including correctly re-hitting the width-4 cache entry on reverting back to 4). Typed an edit on one line and confirmed only that line's rendering changed, with correct tab expansion, while sibling lines stayed visually stable. Verified external file-change detection (unrelated to this fix but on the same render path) still works: silent reload when the buffer is clean, and the "File changed on disk — Reload/Keep local" prompt when dirty, both still trigger correctly. Cleaned up test sessions via `hangon stop`.

**Benchmarks (real numbers, isolated Perl scripts):**
- Isolated `_expand_tabs()` cost for a 60-line simulated viewport, single-line-edit + re-expand cycle per pass (only 1 of 60 lines' content actually changes each pass, matching the real per-keystroke case), 2000 passes against a JS-like fixture with mixed tabs/text: **0.6062ms/pass before → 0.0267ms/pass after — ~22.7x faster** for the code path this fix directly touches.
- Full `Renderer->render_string()` cost for an analogous edit-then-render cycle (includes gutter, syntax highlighting, minimap, ANSI generation — everything else a real frame does, not just tab expansion) against a 5200-line JS-like file scrolled to the middle, 300 passes: **~3.65ms/render before → ~2.94ms/render after — ~1.24x faster** end-to-end (averaged over 2 runs each side to smooth measurement noise: before 3.6922/3.6176ms, after 2.9184/2.9563ms). As with round 2's Highlighter cache, the gap between the isolated and full-render numbers is expected: tab expansion was a real but not dominant fraction of total render cost at this file/viewport size, and the full-render number is the one a user actually feels.

**QA:** `qa/scripts/tier1/reg_212_expand_tabs_cache_no_cross_line_bleed.sh` (QA-REG-212) — the correctness-specific regression guard unique to this fix's content-keyed (not line-keyed) design: two different lines sharing identical content must share one cache entry without one's later edit corrupting the other's still-valid cached rendering. `qa/scripts/tier1/reg_213_expand_tabs_cache_large_file_typing_perf.sh` (QA-REG-213) — coarse responsiveness smoke test on a 3000-line, heavily tab-indented file (mirrors `QA-REG-201`'s style for the analogous round-2 fix). Both mutation-tested the same way as the unit tests.

### ~~P2: `StateStore::check_for_changes()` runs a `stat()` per category on every render (per keystroke), not ~1/sec as documented~~ FIXED
`StateStore.pm:155-156` says "Poll for external changes. Call from event loop (~1/sec)", but the only caller, `Editor.pm:4820`, invokes it unconditionally inside `render()` whenever `state eq STATE_EDITING` — and `render()` runs on essentially every keystroke. Each call does a `stat()` per cached category (`StateStore.pm:160-163`) with zero throttling of its own. Contrast with the line directly above it, `_check_external_file_changes()` (`Editor.pm:4819`), which explicitly debounces with a comment "stat() on every render is wasteful" (`Editor.pm:5177-5182`) — the exact same problem was fixed for one call and missed for its sibling three lines later. Low per-call cost (stat is cheap) but scales with typing speed × category count with no cap.

**Root cause:** `check_for_changes()`'s own doc comment promised "~1/sec" but never enforced that cadence itself — it relied entirely on callers self-throttling, and the one real caller (`Editor::render()`) never did.

**Fix:** Added a `CHECK_INTERVAL_SEC => 1.0` constant and a `_last_check` instance field (initialized to `0` in `new()`, so the very first real call is never debounced) to `StateStore.pm`. `check_for_changes()` now guards its own body with `return if (time() - $self->{_last_check}) < CHECK_INTERVAL_SEC;` before doing any `stat()` work, updating `$self->{_last_check}` only when it actually proceeds — the identical idiom `Editor::_check_external_file_changes()` already used (`_last_external_check` / `EXTERNAL_CHECK_INTERVAL_SEC`). Deliberately placed the guard **inside `StateStore.pm` itself** rather than at the `Editor.pm` call site: `check_for_changes()`'s own doc comment is the thing making the "~1/sec" promise, so it should be the thing keeping it, robust to any future caller (not just `Editor.pm`) rather than relying on every call site to independently remember to throttle.

**Correctness verification:** `tests/state_store.t` gained 2 new subtests. "check_for_changes is debounced — a second call within the interval does not re-stat": primes the store, forces an external file mtime change via `utime()` (not `sleep`, to avoid the sleep itself letting the debounce window elapse and defeating the "immediate re-call" being tested), confirms an immediate second `check_for_changes()` call does NOT detect the pending change (proves debounce blocks it), then forces the debounce window open by setting `$store->{_last_check} = 0` (mirroring the existing `_theme_poll_last = 0` idiom already established in `tests/editor.t` for the analogous theme-polling debounce) and confirms the SAME pending change is now detected — proving this is a timing debounce that defers detection, not one that drops changes outright. "check_for_changes debounce field starts at 0": confirms the first-call-never-debounced initialization. All pre-existing `check_for_changes` tests (`tests/state_store.t`'s 3 original subtests, `tests/preferences.t`'s cross-instance sync test) pass unchanged, since each constructs a fresh `StateStore` and calls `check_for_changes()` exactly once — never hitting the debounce window. Per Rule 5, mutation-tested: deliberately removed the debounce guard (kept updating `_last_check` but dropped the early-return) and confirmed the new debounce test failed as expected, then restored the fix and confirmed all 23 subtests passed again.

**Interactive verification (`hangon`):** Ran two real zepto instances pointed at the same `--state-dir`. Changed the Tab Width preference in instance 2 (4→6); instance 1 picked up the change and visibly re-rendered with the new tab width within ~1.5s after a keystroke nudge — confirming cross-instance preference sync (the entire reason `check_for_changes()`/`on_change` exist) still works correctly, just no longer polled on literally every keystroke. Separately confirmed `_check_external_file_changes()` (unrelated to this fix, but sharing the same `render()` call site) still triggers both its silent-reload and dirty-buffer "Reload/Keep local" prompt paths correctly. Cleaned up both sessions via `hangon stop`.

**Benchmarks (real numbers, isolated Perl script simulating a typing burst — 5000 `render()`-driven `check_for_changes()` calls against a store with 2 primed categories, matching a realistic session):** **16.69ms/5000 calls (0.00334ms/call) before → 0.58ms/5000 calls (0.00012ms/call) after — ~28.8x faster wall-clock** for this burst. More significantly for the actual regression this fix targets: since the whole 5000-call burst completes in well under the 1s debounce window, only the *first* call now does any real `stat()` work at all — the other 4999 short-circuit before touching the filesystem, versus every single one doing a full per-category `stat()` loop before the fix. For a session with 2 cached categories that's a **~5000x reduction in actual `stat()` syscalls** for a rapid-fire keystroke burst (2 real stats instead of ~10,000), which is the metric the bug report's "scales with typing speed × category count with no cap" concern was actually about — the wall-clock number understates the fix's effect on syscall volume because the benchmark's own overhead (hash lookups, function calls) dominates once the `stat()` calls themselves are gone.

**QA:** `qa/scripts/tier1/reg_214_statestore_debounce_cross_instance_sync.sh` (QA-REG-214) — runs two real zepto instances sharing one `--state-dir`, changes Tab Width in one, and confirms the other picks up the change within a generous 6s polling window (proving the debounce didn't silently break the one thing `check_for_changes()` exists to do). Mutation-tested: deliberately made the debounce timestamp jump 999999 seconds into the future on every call (so it never re-opens after the first check) and confirmed the script failed exactly as expected — cross-instance sync silently stopped working entirely — before restoring the real fix and confirming it passed again.

### ~~P3: `FileTree::_dir_vcs_status_from_hash()` scans the entire VCS status hash per unloaded directory~~ FIXED

**Root cause confirmed:** `FileTree.pm:801-819` (pre-fix): for every directory node whose children aren't loaded, `_propagate_dir_status()` (`FileTree.pm:768-797`, pre-fix) called `_dir_vcs_status_from_hash()`, which did `for my $path (keys %$statuses)` over *all* changed files in the repo, filtered by `index($path,$prefix)==0` — O(unloaded-dirs × total-changed-files). Confirmed real (not just theoretical) with a `Time::HiRes` benchmark against the actual function, using a synthetic tree of D real directories and a synthetic VCS-status hash of S entries: D=100/S=1000 → 6.8ms, D=300/S=3000 (9x the work) → 59ms (~9x), D=600/S=6000 (36x the work) → 261ms (~38x) — consistent with O(D×S) scaling. Mitigated by `update_vcs_statuses`'s 5s debounce (`FileTree.pm:730`, `VCS_DEBOUNCE_SEC=>5.0`), so it was a periodic hitch rather than per-keystroke, but the underlying algorithmic cost was real.

**Fix:** Replaced the per-directory full-hash scan with a single pre-built index. `_propagate_dir_status()` now calls a new `_build_vcs_dir_index()` (`FileTree.pm`) ONCE per propagation pass — a single O(S × depth) walk over the changed-files hash that, for each changed file, records the worst (highest-priority) status against every ancestor directory prefix (e.g. `a/b/c/file.txt` updates `a`, `a/b`, `a/b/c`). The recursive tree walk (renamed `_propagate_dir_status_rec`, takes the pre-built index as a parameter) then looks up each unloaded directory's status in O(1) instead of rescanning the full hash. `_dir_vcs_status_from_hash` was removed (its lookup logic is now the index build itself).

**Correctness preserved:** `tests/filetree_vcs_perf.t` reconstructs the old algorithm verbatim as local subs and runs it side-by-side against the new code on identical synthetic VCS-status data (no matches, mixed-priority overlapping changes at varying depths, empty status hash) — `is_deeply` confirms byte-identical directory status results in every case, plus direct spot-checks of expected priority resolution (e.g. a dir with both a `staged` file and a nested `modified` file must report `modified`).

**Performance (real `Time::HiRes` numbers, `tests/filetree_vcs_perf.t`):** D=300/S=3000: old=63-66ms, new=1.9ms (~35x faster). D=600/S=6000: old=245-267ms, new=3.9-5.5ms (~47-69x faster). The test's own bound guards (30ms and 150ms respectively) were confirmed to fail against the actual unfixed function by running the identical test file, unmodified, in a second worktree checked out at the pre-fix commit (`5a720fd`) — D=300/S=3000 old code took 58.9ms (fails the 30ms bound), D=600/S=6000 took 245.7ms (fails the 150ms bound) — proving the guards actually bite.

**Tests:** `tests/filetree_vcs_perf.t` (new, 5 subtests / test points: 3 correctness comparisons + 2 performance scales) plus the pre-existing `VCS status propagation` subtest in `tests/file_tree.t` still passes unmodified (it calls `_propagate_dir_status()` directly, same public signature). `make test`: 47 files, 1282 tests, all pass, 33s wallclock (was 32s — the new test file adds ~0.6s in isolation).

**Verified interactively via `hangon`:** created a real git repo with 4 subdirectories (2 modified, 1 untracked, 1 clean) and a clean root file, opened it in zepto, and confirmed the file tree's directory-name colors correctly reflect VCS status — modified dirs share one color, the untracked dir shows a different color, the clean dir and file show the default color — matching `git status --porcelain` exactly.

**Not fixed / left alone:** other VCS-status code paths with a similar "scan for related state" shape were not audited in this pass (e.g. gutter/diff lookups in `Renderer.pm`/`Document.pm`, already covered by a separate perf fix logged elsewhere in this file) — this fix is scoped to `FileTree.pm`'s directory-status propagation only. Only two workload scales were exercised in the committed regression test (D=300/S=3000 and D=600/S=6000); larger scales were spot-checked manually during investigation (D=800/S=4000 pre-fix: 217ms) but aren't part of the permanent suite, to keep `make test` fast.

### DRY / duplication (P3)

### ~~P3: Duplicated cursor/hunk background-priority chain in `Renderer.pm`~~ FIXED
The 4-way `is_cursor_line && is_hunk_line` → `diff_new_cursor_bg` / `cursor_line_bg` / `diff_new_bg` / `bg` priority chain was hand-duplicated at `Renderer.pm:2398-2401`, `2420-2428`, and `3493-3495` (a smaller 2-way version).

**Investigation before fixing:** bugs.md's note that "only two of the three currently handle diff-hunk state" did not hold up under test. Wrote a scratch script (not committed — one-off verification, see process below) that rendered a 4-line document through the *actual, unmodified* `Renderer->render_string()` with a git-diff hunk expanded via `LineMap`, moved the cursor across all 4 combinations (cursor+hunk, cursor-only, hunk-only, neither), and grepped the real ANSI escape codes preceding the gutter arrow (site 1) and the content characters (sites 2 and 3) against each theme color's actual RGB value. All 3 sites already produced the *correct* color for all 4 states — site 3's two 2-way ternaries (`$bg` for the non-cursor slice, `$line_bg` for the cursor slice, gated later by `$is_cursor_line`) jointly and correctly implement the same 4-way chain as sites 1 and 2, because the `$diff_mode` parameter passed into `_render_line_with_highlights` is always derived directly from `is_hunk_line` at the single call site. So this was confirmed to be a **pure DRY duplication issue with no live correctness gap** — the bugs.md note describing a two-of-three gap was inaccurate as literally worded.

**Fix:** Extracted `sub _resolve_line_bg($theme, $is_cursor_line, $is_hunk_line)` (near `_ellipsis`, `Renderer.pm`) implementing the single priority chain: cursor+hunk → `diff_new_cursor_bg`, cursor-only → `cursor_line_bg`, hunk-only → `diff_new_bg`, neither → `bg`. All 3 call sites now delegate to it: the gutter arrow (`_resolve_line_bg($theme, 1, $is_hunk_line)` — always cursor-true, since it's inside the `is_cursor_line` branch), the full 4-way gutter/line background (`_resolve_line_bg($theme, $is_cursor_line, $is_hunk_line)`), and `_render_line_with_highlights`'s two 2-way slices (`_resolve_line_bg($theme, 0, $is_hunk_line)` for `$bg`, `_resolve_line_bg($theme, 1, $is_hunk_line)` for `$line_bg`, both derived from a new local `$is_hunk_line` boolean instead of re-testing `$diff_mode eq 'new'` twice).

**Tests:** Re-ran the same scratch verification script against the refactored code — byte-identical ANSI output for all 4 states at all 3 sites, confirming the refactor is behavior-preserving. `make test` (44 files, 1192 tests) passes clean, including `tests/renderer.t`'s existing hunk/cursor color assertions (`Light theme diff colors in expanded hunk`, the expanded-hunk subtests) and `tests/theme_contrast.t`. Verified interactively via `hangon`: opened a real git repo with an uncommitted modification, expanded the hunk with `⌥D`, and screenshotted the cursor sitting on the hunk line (bright green `diff_new_cursor_bg`), then moved the cursor off it (hunk row falls back to the dimmer `diff_new_bg`, the new cursor row shows plain `cursor_line_bg`) — all three states visually correct and matching dark-theme RGB values, in both directions of the transition.

### ~~P3: Hand-rolled left-truncation duplicates `_ellipsis(..., 'start')`~~ FIXED
`Renderer.pm:2963-2971` (flat file-tree filter rendering) reimplemented start-truncation with ellipsis inline rather than reusing the existing shared `_ellipsis()` helper, because it also needed the trim offset to remap match-highlight positions.

**Fix:** Extended `_ellipsis()` to optionally return `($result, $trim_offset)` in list context (scalar-context callers — all 9 pre-existing call sites — are unaffected, verified via `wantarray`). `$trim_offset` is the count of characters removed from the front of the original string in `'start'` mode (always 0 in `'end'` mode, and always 0 when nothing was truncated). The file-tree call site now does `($display_path, $trim_offset) = _ellipsis($path, $name_space, 'start')` instead of hand-computing `length($path) - ($name_space - 1)` and the substr/prepend itself.

**Before fixing:** wrote a scratch equivalence script comparing the old inline formula against the new `_ellipsis`-based call across 11 cases (normal truncation, small budget, exact-boundary length, one-under-boundary, empty string, `name_space <= 0`, unicode/CJK path components, single-char budget) — all matched byte-for-byte and offset-for-offset before touching the call site, confirming the extraction is behavior-preserving by construction, not just by inspection.

**Tests:** `tests/renderer.t` — new subtest `_ellipsis in list context returns trim offset` covers the same equivalence cases directly against `Zepto::Renderer::_ellipsis` (untruncated, exact boundary, one-over-boundary, deep path, empty string, unicode/CJK with a `substr($original, $offset) eq substr($truncated, 1)` roundtrip check, and `'end'` mode's offset always being 0). New integration subtest `File-tree flat-filter rendering truncates via _ellipsis and remaps match highlight` calls `_render_tree_node_content` directly with a 32-char path and two match positions (one trimmed off, one surviving) at `width=8`, and asserts on the real rendered ANSI: the visible text is exactly `"…e.pm"` (stripped of escape codes, including the real file-icon glyph), exactly one character is highlighted (proving the trimmed-off match produced no highlight), and the highlighted character is immediately preceded by `tree_match_fg` with `'e'` immediately after (proving the surviving match position was correctly remapped through the trim offset onto the truncated string). `make test` passes clean (44 files, 1192 tests).

**Verification note (Rule 2):** could not verify this interactively via `hangon` as originally planned — while investigating, discovered `Zepto::FileTree`'s `start_filter()`/`filter_active` flat-filter-search feature (the one this rendering code serves) has **zero callers anywhere in `Editor.pm`'s key/mouse handling** — `handle_tree_event` only wires `{`/`}`/space/arrows/enter/escape for the tree pane, no character ever reaches `filter_append_char()`, and no command in `CommandRegistry.pm` triggers `start_filter()` either. The renderer-side search-bar cursor placement code (`Renderer.pm` ~797-806) and this flat-render path are fully built and exercised by `tests/file_tree.t`, but the feature is currently unreachable from the running UI — a separate, pre-existing bug, logged below as a new P1 finding (out of scope for this DRY fix; wiring up a new keybinding is a materially bigger change than the truncation-logic refactor this entry covers, and risks scope creep in an unattended session). Verification for this fix therefore relies on the unit/integration tests above, which exercise the real rendering function with real theme colors end-to-end — the closest available substitute given the feature can't currently be reached by typing into a running `hangon` session.

### ~~P3: Duplication across 5 near-identical `_column_*`/`_multi_cursor_*` functions is the root cause of the P1 cursor-desync bug's blind spot~~ FIXED
`Editor.pm:4056-4333`. `_column_insert_char`/`_column_backspace`/`_column_delete`/`_multi_cursor_insert_char`/`_multi_cursor_backspace` each independently reimplement "iterate cursors/lines in reverse, `begin_undo_group`, mutate, adjust not-yet-processed positions, `end_undo_group`." The position-adjustment logic is where the P1 bug above lives, and it's essentially copy-pasted-with-variation between the multi-cursor pair and partially reinvented (more simply, and correctly for its narrower rectangle-only case) in the column-select trio. A shared "apply edit at N positions, then fix up all other tracked positions" helper would have caught the line-join gap by construction instead of requiring it to be independently reasoned through in each copy. Should likely be fixed together with the P1 bug above, not separately.

**Fixed together with the P1 bug above**, as recommended: see that entry's writeup for the full root-cause/fix/test detail. Summary specific to this DRY finding — all 6 of the affected functions (the 5 named here, where `_column_backspace`/`_column_delete` both also delegate their has-width case to `_column_delete_selection`, making 6 call sites total across those 5 named functions) now share one implementation via `_apply_edit_and_fixup_positions`/`_adjust_pos_for_edit`/`_fixup_other_positions` in `Editor.pm`. The column trio's narrower, previously-correct behavior was preserved exactly (verified both by code review — column edits are always confined to a single row, so the shared helper's general fixup logic degenerates to a no-op for every other row, which is mathematically the same as "no fixup needed" — and by running the full pre-existing `tests/column_select.t` suite, 41 subtests / 804 lines, unchanged and passing). The position-adjustment logic that used to be "copy-pasted-with-variation" now exists in exactly one place, and that place handles same-line shifts, line-joins, and multi-line-range deletions as three branches of one general algorithm rather than three separately-remembered special cases.

### ~~P3: Undo-group nesting would silently drop the outer group if ever nested (latent, not currently triggered)~~ FIXED
`Document.pm:515-533`. `begin_undo_group()` was a no-op if a group was already open, and `end_undo_group()` unconditionally cleared `_undo_group` to `undef` regardless of nesting depth — no reentrancy counter. No call site currently nests `begin/end_undo_group` (verified via grep across Editor.pm/Commands.pm), so not exploitable today, but a footgun: any future helper that calls another helper which also wraps its edits in `begin/end_undo_group` would have the inner `end_undo_group()` prematurely close/flush the group, and the outer call would then silently no-op, losing that outer action's grouping with no error.

**Reproduced first (Rule 5):** wrote a test that nests a `begin_undo_group()`/`end_undo_group()` pair inside an outer one (`begin` outer → insert A → `begin` inner → insert B → `end` inner → insert C → `end` outer) and ran it against the unfixed code. Confirmed the exact failure predicted above: the inner `end_undo_group()` flushed A+B as a group and cleared `_undo_group`; the subsequent insert of C then fell through to the *normal* (non-grouped) auto-grouping path since `_undo_group` was `undef`, landing as its own separate `undo_stack` entry; the outer `end_undo_group()` found `_undo_group` already `undef` and silently did nothing. Result: `undo_stack` had 2 entries instead of 1, and a single `undo()` only reverted C, leaving `"AB"` behind instead of reverting the whole nested group atomically — a real, reproducible bug, not just a theoretical one.

**Fix:** Added `_undo_group_depth` (initialized to 0 in the constructor). `begin_undo_group()` increments the depth and only actually opens a new group array when depth goes 0→1 (nested calls just bump the counter and keep appending to the same still-open group). `end_undo_group()` decrements the depth and only flushes/closes the group when depth goes 1→0 (nested `end` calls just bump the counter down without touching `_undo_group`). This makes nesting safe by construction — a stray/unbalanced `end_undo_group()` with no matching `begin` is also now a safe no-op (depth stays at/below 0) instead of relying on the group array happening to be empty.

**Tests:** `tests/document.t` — 3 new subtests: `Nested begin/end_undo_group is reentrancy-safe` (the exact repro above — confirmed failing on unfixed code via `git stash`, now passes: all of A/B/C land in a single `undo_stack` entry, one `undo()` reverts all three atomically, one `redo()` restores all three); `Doubly-nested begin/end_undo_group (depth 3) is reentrancy-safe` (three levels deep, still one atomic group); `Unbalanced end_undo_group without begin is a safe no-op` (no crash, no corrupted state). `make test` passes clean (44 files, 1192 tests).

**Verification note (Rule 2):** this is a non-UI, undo-bookkeeping-only change — no key handling, command, or rendering was touched. Per the bugs.md convention, still did a `hangon` sanity pass on ordinary (non-nested) undo/redo, since that's the only user-observable surface: typed text, `⌃Z` undid it as one group, `⌃Y` redid it — confirming the normal (non-nested, by far the common case) path is unaffected by the reentrancy-counter change.

### Test coverage (P2)

### ~~P2: New tautological-fallback tests in `tests/completion.t` — same anti-pattern round 2 fixed elsewhere in this file~~ FIXED
`tests/completion.t:518-538` ("Controller accept") and `:543-574` ("Menu navigation") both gate their real assertions behind `if ($ctrl->is_active())` and fall through to `pass('no completion active (acceptable in minimal test)')` otherwise. Distinct subtests from the two round 2 already fixed (differently named, no longer containing this pattern). Their inputs (`"hel"` matching `hello_world` in-buffer; `"fo"` matching `foo`/`foobar`/`foobaz`) look just as deterministic as the round-2-confirmed-always-triggering ones — the `else` branch is very likely permanently dead, silently masking a broken `Controller::trigger()`/`accept()`. Fix: same as round 2's completion.t fix — confirm the inputs deterministically trigger completion and remove the fallback pass.

**Root cause**: same as round 2's original finding — both subtests were written defensively ("what if this provider doesn't trigger") without verifying that, given the fixed inputs and the single provider registered in each subtest, the trigger is in fact unconditional. It is: `Controller::trigger()` (`Controller.pm:55-168`) dismisses only when the prefix is `< 2` chars or when literally zero providers return a match after dedup/self-referential filtering — neither applies to either subtest's setup.

**Fix** (`tests/completion.t`): removed the `if ($ctrl->is_active()) {...} else { pass(...) }` wrapper from both subtests, following the exact pattern round 2 already used two subtests up in the same file ("Controller accept with snippets" and "Controller records accepted to RecentProvider" — see their doc comments at `completion.t:405-413` and `:440-445`):
- "Controller accept" (now `:518-541`): "hel" (3 chars) against `CrossBufferWordProvider`, matching in-buffer `hello_world` — the identical setup already proven deterministic in "Controller records accepted to RecentProvider". Added a doc comment explaining why, and an unconditional `ok($ctrl->is_active(), ...)` before the real assertions.
- "Menu navigation" (now `:543-573`): "fo" (2 chars) against `CrossBufferWordProvider`, matching three in-buffer words (`foo`/`foobar`/`foobaz`) — 3 matches also guarantees a non-trivial menu for `menu_down`/`menu_up` to navigate. Same treatment.

**Verification (Rule 5)**:
- Confirmed both subtests currently pass and are deterministic: ran `prove tests/completion.t` 3x clean before touching anything.
- Confirmed the tautology: broke `Controller::trigger()` (forced an early `return $self->dismiss()`) and observed the *old* code's `else` branch swallowing the failure via `pass('no completion active...')` — the full suite still reported all-green even with `trigger()` completely dead for these two subtests, proving the anti-pattern.
- Rewrote per the fix above, then re-broke the underlying logic (this time via `CrossBufferWordProvider::complete()` forced to always return `[]`, since breaking `trigger()` itself now crashes an *earlier*, already-fixed subtest — the fresh break isolates the two rewritten subtests) and confirmed both now fail explicitly and correctly:
  ```
  not ok 11 - Controller accept
  not ok 12 - Menu navigation
  ```
  (6 individual assertions failed across the two subtests, including the very first "completion triggers" check in each — no silent pass.)
- Restored both source files, reran `prove -v tests/completion.t` 3x: `All tests successful. Files=1, Tests=16` every time, no noise.

No production code changed — test-only fix. Rule 2 (interactive UI verification) does not apply.

### ~~P2: 19 of 56 `cmd_*` command-dispatch wrappers in `Editor/Commands.pm` have zero test coverage, including one with data-loss-adjacent logic~~ FIXED (partial — see writeup for what's covered)
`cmd_close_tab` (`Commands.pm:142` — "Save if dirty, then close... Only close if save succeeded", meaningful conditional logic, completely unverified), `cmd_quit` (`:188`, saves cursor position per tab before exit), `cmd_next_tab`/`cmd_prev_tab`/`cmd_switch_to_tab`/`cmd_move_tab_left`/`cmd_move_tab_right`, `cmd_select_all`, `cmd_find_in_files`/`cmd_find_replace`, `cmd_toggle_minimap`/`cmd_toggle_word_wrap`/`cmd_toggle_nerd_font`, `cmd_ai_setup`/`cmd_toggle_ai` — 19 total, zero references in `tests/*.t`. `tests/tab_manager.t` covers the underlying `TabManager` model (`remove_tab`, `move_tab`) but never the `Editor::Commands` glue that decides *when* to save-before-close or *which* tab index to target — a regression in that glue (e.g. closing without checking `is_dirty`) would pass the whole suite. Highest-value target: `cmd_close_tab`'s save-before-close logic, since a regression there is a real data-loss risk, not just a coverage gap.

**Scope of this fix — 9 of the 19 got new coverage, 10 remain untested.** Prioritized by risk per the original finding: `cmd_close_tab` (the data-loss-adjacent one) first and most thoroughly, then `cmd_quit` and tab-navigation, then the simple toggles.

**Traced the save-failure path first (Rule 5, step 2)**, before writing any test: `cmd_close_tab` (`Commands.pm:142-154`) calls `cmd_save()` (`:37-64`) when the doc is dirty, which wraps `$doc->save()` in `eval` and calls `show_error_message()` on `$@` — critically, on failure it does **not** clear `$doc->{dirty}`. `Document::save()` (`Document.pm:166-218`) does its atomic write via `File::Temp::tempfile(..., DIR => dirname($path), ...)` — so it's the **target directory's** write permission that gates success, not the file's own mode; `$self->{dirty} = 0` only executes after the `eval` block succeeds, so a failed save leaves `is_dirty()` true. `cmd_close_tab` then checks exactly that: `return if $self->active_doc()->is_dirty();` — realistic failure injection is therefore `chmod` on the containing directory (not the file), matching `Document::save()`'s actual mechanism rather than a guessed one.

**New tests added to `tests/editor.t`** (all in the existing `mock_terminal()`/`setup_editor_doc()`/`create_temp_file()` harness already used throughout the file; each uses an isolated `Zepto::StateStore->new(base_dir => tempdir())` per the file's existing StateStore-isolation convention):
- `cmd_close_tab: closing a clean tab just closes it, no save` — clean doc closes immediately, no save happens (mtime unchanged, no "Saved:" message), remaining tab becomes active.
- `cmd_close_tab: closing a dirty tab saves first, then closes, when save succeeds` — dirty doc's edits land on disk and the tab closes.
- `cmd_close_tab: closing a dirty tab does NOT close when save FAILS (data-loss prevention)` — **the critical case**. Revokes write permission on the containing directory (`chmod 0500`), with the same root-safety sanity probe pattern already used elsewhere in this file (`editor.t`'s "Tree preview of unreadable file" subtest) so the test doesn't silently pass-through when run as root. Asserts the tab is *not* closed, stays active, doc stays dirty, and an error message is shown.
- `cmd_close_tab: closing the last remaining tab quits instead of leaving a blank tab` — traced `_do_close_tab` (`:156-186`) to confirm the actual behavior first: closing the last tab does **not** open a fresh blank tab, it sets `state = 'quit'` and returns before ever calling `remove_tab`. Test asserts exactly that (plus that the pre-quit cursor-position save still ran).
- `cmd_quit saves cursor position for every open tab before exiting` — two tabs, distinct cursor positions, asserts both land in `StateStore`'s `history.cursor_positions` keyed by absolute path.
- `cmd_next_tab / cmd_prev_tab wrap around the tab list` — 3-tab wraparound in both directions.
- `cmd_next_tab / cmd_prev_tab are no-ops with only one tab`.
- `cmd_switch_to_tab jumps directly to a valid index and ignores invalid ones` — valid index, same-index no-op, negative and out-of-range indices ignored.
- `cmd_select_all selects the entire active document`.
- `cmd_toggle_minimap flips the show_minimap preference`.
- `cmd_toggle_word_wrap flips the wrap override on the active view`.
- `cmd_toggle_nerd_font flips the nerd_font preference`.

**Still untested (10 of the original 19) — left for a future pass**: `cmd_move_tab_left`/`cmd_move_tab_right` (lower risk than close/switch, simple `TabManager::move_tab` delegation, not reached this round), `cmd_find_in_files`/`cmd_find_replace` (explicitly deprioritized — need more elaborate setup, lower urgency than tab-management), `cmd_ai_setup`/`cmd_toggle_ai` (out of scope for this pass; not covered by the concurrent AI-completion security work either as of this writing — still open), and `cmd_doc_about`/`cmd_doc_changelog`/`cmd_doc_license`/`cmd_doc_tutorial` (not part of the original 19 list's named examples but confirmed via the same grep-based audit to also have zero test references — tracked separately by the existing P3 `HelpDocs.pm` finding below).

**Verification (Rule 5)**: for `cmd_close_tab` specifically, deliberately commented out the `# Only close if save succeeded` guard (`return if $self->active_doc()->is_dirty();`) and reran the new save-failure subtest — it correctly failed on 3 of its assertions (tab not closed, tab still active, doc still dirty all went red) confirming the test actually catches this exact data-loss regression, not just a coverage-shaped no-op. Restored the guard and reconfirmed a clean pass. No bug was found in the actual implementation — `cmd_close_tab`, `cmd_quit`, and the tab-navigation commands all behave as documented.

**Test results**: `tests/editor.t` grew from 144 to 156 subtests (12 new), full file green (`Files=1, Tests=156`). Full suite: `make test` → `Files=44, Tests=1198` (up from the previously-documented 1186), all green, no stdout/stderr noise.

No production code was changed for this fix (test-only additions; the one assumption-check failure hit during development — an incorrect expected string in the `cmd_select_all` test around the document's trailing-newline handling — was a test bug, corrected before commit). Rule 2 (interactive UI verification) does not apply. No new QA script per the task's own guidance (unit-test-only change, no behavior change, no bug found).

### P3: AI-completion command-layer wiring is untested, compounding the already-open round-2 finding that `AIComplete.pm` itself has zero tests — FIXED (2026-09-01)
`cmd_ai_setup` (`Commands.pm:1371`, multi-step footer-input flow writing `ai_api_url`/`ai_model`/prefs) and `cmd_toggle_ai` (`:1354`, guards on missing API key, calls `$ai->cancel()`) are entirely untested — none of the command layer around the one network-calling module has coverage either. Consider fixing together with the already-tracked `AIComplete.pm` gap.

**Fix (test-only, branch `add-aicomplete-test-coverage`)**: `tests/editor.t` gained 6 new subtests covering both commands at the "dispatch + state" level, no real network call made anywhere (the existing https-scheme-enforcement subtests for `cmd_ai_setup` step 1 already covered part of this — see "AI API URL has no scheme enforcement" above): the full 3-step wizard (URL → Model → API Key) storing `ai_model`/`ai_api_url` to `Preferences` and the API key to `StateStore`'s `secrets` bucket (never to `Preferences`, confirmed) and enabling `AIComplete`; empty-submission no-ops at any step (doesn't advance or store); `cmd_toggle_ai` with no API key configured (shows the "run Setup first" message, stays disabled); `cmd_toggle_ai` flipping enabled on/off with a key configured; `cmd_toggle_ai` turning off cancels an in-flight debounce timer (via `AIComplete::cancel`); and a defensive no-crash check when `_ai_complete` is missing entirely.

**Verified non-tautological (Rule 5)**: mutation-tested `cmd_toggle_ai` by breaking its toggle logic to always force `enabled = 1` and never call `cancel()` — 2 of the new subtests failed exactly as expected (the on/off flip test and the debounce-cancel test); reverted (`git diff` empty against `lib/Zepto/Editor/Commands.pm` afterward).

Full details: `tests/editor.t` ("AI Completion setup — full 3-step wizard..." section).

### P3: `lib/Zepto/HelpDocs.pm` (54 lines, 3 subs) has zero test coverage
No `tests/*.t` references it at all; only exercised indirectly via `cmd_doc_*` in Commands.pm, which are themselves untested (see above).

### Informational (not recommended for immediate fix)

- **`Syntax::PHP` has no end-to-end sample in `tests/samples/`** — every other of the 52 grammars has a `<lang>_complete.*`/`.expected` pair exercised by `tests/syntax_samples.t`'s auto-discovery loop; PHP is the exception. It does have solid dedicated coverage in `tests/highlighter.t:632-680`, so this is a corpus-completeness gap, not a real coverage hole.
- **423 of 628 `qa/scripts/tier1/*.sh` scripts use unconditional `sleep 0.2`–`0.5` for render settling** (e.g. `clip_001_copy_paste.sh:33`). Predates round 2 (which fixed hard pass/fail timing thresholds, not settle-sleeps) and appears to be the established, accepted convention rather than a regression.

### Verified accurate, not stale (no action needed)

Test-suite metrics (44 files / 1186 tests, `make test` output matches README/CLAUDE.md expectations exactly), `FEATURES.md`'s 52-language list (matches `lib/Zepto/Syntax/*.pm` count exactly), `docs/help/changelog.md`'s Ctrl+R regex claim, no dangling references anywhere to round 2's deleted dead code (`_render_pill`, `do_find_next/prev`, `_parse_url`, etc.). No circular module dependencies found. `build.pl`'s bundling output is in sync with `lib/`, not stale. Shell execution audited across the whole codebase — no injection vectors found beyond the already-fixed round-2 items; `cmd_transform`'s `sh -c` is the deliberate user-authored "Transform via Shell" feature, not a vulnerability. No hardcoded secrets, no unsafe deserialization, no vendored code without attribution, LICENSE is standard MIT.

### Editor god-object extraction — scoping conclusion

A dedicated investigation compared **Palette/command-dispatch** vs. **multi-cursor/selection state** as the first extraction target (following the `Editor/TabManager.pm` precedent — the one real, working, separately-namespaced extraction that already exists). Conclusion: **extract Palette first.** Palette's private state (`palette_cursor`, `palette_mode`, `palette_scroll`, `palette_widget`, `_file_search_*`, etc.) is touched from outside `Editor/Palette.pm` at exactly 2 integration seams — the 4 `cmd_open_*` commands that initialize palette state when opening, and one render-snapshot block in `Editor.pm` (~4933-4941) that packages palette state for `Renderer->render`. Multi-cursor state already lives cleanly on `View.pm` with a good method API, but *using* it requires ~28 inline dispatch branch points spread across 8-10 core editing methods (`do_insert_char`, `backspace`, `delete_char`, `delete_selection`, `cmd_cut`/`copy`/`paste`/`select_all`) that would all need simultaneous rewiring — not a safe first increment. A concrete 8-step Palette extraction plan (new `lib/Zepto/Editor/PaletteController.pm`, move self-contained helpers first, flip package declaration, wire construction, convert integration seams to delegating calls, verify via `make test` + interactive `hangon` per Rule 2) is being executed as sequential, single-threaded work — see git history/branch for progress, not parallelized across a fleet.

**Update (2026-08-30): Palette extraction is DONE.** `lib/Zepto/Editor/PaletteController.pm` is now a real, separately-namespaced `package Zepto::Editor::PaletteController;` object, constructed as `$self->{palette} = Zepto::Editor::PaletteController->new(editor => $self)` in `Editor::new()` — the exact same composition pattern as `$self->{tab_manager}`, except PaletteController also holds an `editor` back-reference (TabManager doesn't need one) for the handful of things it reaches into the owning Editor for: `state` transitions, `clipboard`, `terminal`, `file_tree`, `_recent_files`, and the methods `active_file_path`/`_load_file`/`_record_location`/`_jump_to_location`/`show_message`/`Zepto::CommandRegistry->execute`. `lib/Zepto/Editor/Palette.pm` (the old `package Zepto::Editor;` file) is deleted — fully absorbed. Zepto::Editor keeps thin one-line delegators (`cmd_open_palette`, `close_palette`, `handle_palette_event`, `handle_status_bar_click`) so external call sites don't need to know the controller exists, same pattern as `active_doc { $_[0]->{tab_manager}->active_doc() }`.

The scoping investigation found 2 integration seams; the actual implementation found 2 more that weren't visible from a static read: Editor's main `run()` loop directly polled `_file_search_engine`/`palette_mode` for background file-search ticking (now `$self->{palette}{...}`, mirroring the pre-existing `$self->{tab_manager}->{tabs}` direct-reach at Editor.pm ~724), and `Renderer.pm`'s `_render_command_palette` reads/writes `_file_search_case`/`_file_search_regex`/`_file_search_scope_label`/`_file_search_engine`/`palette_visible_rows` on a `$palette->{editor}` variable pulled from the render snapshot.

**Gotcha worth flagging for the next extraction:** the first version of this change repointed that snapshot's `editor` key at the PaletteController itself (reasoning: the 5 fields above all live there now, so Renderer's reads/writes would "just work" unchanged). That was wrong — the *same* `$editor` variable in `_render_command_palette` is also passed to `Zepto::CommandRegistry->get_toggle_state`/`get_toggle_display` for the toggle-command checkmark/pill display, and those call arbitrary real-editor methods (`active_view()`, `{diff_expanded}`, etc.) that don't exist on the controller. This shipped past `make check`, `make build`, and all 1186 unit tests green (none of them exercise rendering a toggle command inside a *live* palette with a real Renderer call) — it was only caught by the pre-existing QA script `qa/scripts/tier1/col_012_palette_toggle.sh` (`make qa`), which crashed with `Can't locate object method "active_view" via package "Zepto::Editor::PaletteController"`. Fixed by giving the snapshot two separate keys: `editor` (kept as the real `Zepto::Editor`, for generic command-toggle-state queries) and a new `controller` key (the PaletteController, for the palette-private fields) — `Renderer.pm` now uses `$editor` vs `$ctrl` for the right purpose at each of the ~9 call sites. Lesson: **run `make qa`, not just `make test`, before considering a "zero Renderer changes" claim safe** — unit tests alone did not exercise this path. Whoever does the multi-cursor extraction next should budget time for `make qa`, not just `make check`/`make test`, for exactly this reason.

`tests/command_palette.t` and `tests/editor.t` previously poked `$editor->{palette_cursor}` etc. directly (white-box tests) — updated to `$editor->{palette}{palette_cursor}` etc., matching this codebase's existing convention of tests going through `$editor->{tab_manager}->method()` rather than reaching into Editor's own former fields. Full `make test` (1186/1186) and interactive `hangon` verification of every entry point (commands, recent files, open-file picker, find-in-files incl. Tab scope cycling and Ctrl+R/Ctrl+C toggles, mouse clicks, status bar pill click, Escape/click-outside close) confirmed zero behavior change. See branch `extract-palette-controller` for the 3-commit history (step 1: no-op file relocation; step 2: the real cutover; step 3: the toggle-command render-snapshot crash fix).

**Next step for whoever picks up god-object extraction next: multi-cursor/selection state**, per the original investigation above. Two working precedents now exist to follow (`TabManager.pm` — no back-reference needed; `PaletteController.pm` — back-reference needed for cross-cutting calls) instead of one. The known difficulty remains as scoped: ~28 inline dispatch branch points across 8-10 core editing methods (`do_insert_char`, `backspace`, `delete_char`, `delete_selection`, `cmd_cut`/`copy`/`paste`/`select_all`) would need simultaneous rewiring since `View.pm` already owns clean multi-cursor state/API — the work is in threading the *call sites* through it, not designing new state ownership. Do not attempt this without re-scoping it the same way Palette was scoped first (map every external touch point before writing code).

## Found while fixing the "Scorecard audit round 3" DRY items (2026-08-30)

### ~~P1: File-tree flat-filter search (`FileTree::start_filter`/`filter_active`) is fully built and rendered but has zero UI trigger — completely unreachable from the running editor~~ FIXED (2026-08-31, see below)
Found while verifying the `_render_tree_node_content` flat-filter-rendering refactor above (see the `_ellipsis` trim-offset DRY fix) — needed to reach this code path interactively via `hangon` per Rule 2 and couldn't. A first fix attempt later the same session stalled on an agent-runtime issue before producing a commit (see "Session-end summary" below). Fix and full writeup: "File-tree fuzzy-filter trigger fix" section below.

## File-tree fuzzy-filter trigger fix (2026-08-31)

### ~~P1: File-tree flat-filter search has zero UI trigger~~ FIXED
Picking up the P1 above fresh (per its own note, the prior attempt stalled before committing anything — no work to build on).

`Zepto::FileTree::start_filter()`, `filter_append_char()`, `filter_backspace()`, and `clear_filter()` (`FileTree.pm:467-500`) are a complete, well-tested (`tests/file_tree.t`, extensively) type-to-filter feature: activate filter mode, type characters to fuzzy-match files across the whole tree, render a flat filtered list with match-position highlighting and a search-bar row. `Renderer.pm` had cursor-placement logic for the search bar's input field (`Renderer.pm` ~797-806) but — as it turned out — no actual trigger and, as discovered below, no actual row-drawing code either.

But grepping all of `Editor.pm`'s tree input handling turned up **zero callers** of any of the four `FileTree` filter methods:
- `handle_tree_event` only wired `up`/`down`/`left`/`right`/`enter`/`escape`/`pageup`/`pagedown`/`home`/`end` (key events) and `{`/`}`/space (char events) — no case reached `start_filter()` or `filter_append_char()`.
- No command in `CommandRegistry.pm` had `method => 'cmd_...'` touching filter state.
- No mouse handler targeted a search-icon/filter-trigger region.

Confirmed interactively: with the tree focused (`⌃B`, confirmed focused via the "⌃B back" status-bar pill), typing any character did nothing to tree state — no search bar appeared, no filtering happened. The feature was dead from a user's perspective despite being fully implemented and unit-tested underneath.

**Root cause:** exactly as diagnosed — a fully-built, fully-tested feature with no key/command/mouse entry point.

**Fix (`Editor.pm::handle_tree_event`):** `/` (the vim/less/universal terminal-UI filter convention — confirmed not already bound in tree mode, and it turned out to already be the exact key the previously-unreachable `qa/22_file_tree.txt` QA-TREE-013 catalog entry specified) now calls `start_filter()` when the tree is focused and filter mode isn't already active. Once active, every printable character (including a second `/`, so paths containing `/` can be searched) routes to `filter_append_char()`; Backspace routes to `filter_backspace()` (which itself decides whether to edit the query or exit filter mode on an already-empty query — no new logic needed there, it was already correct). Escape is now two-step and mode-aware: the first press calls `clear_filter()` and leaves the tree focused (back to normal hierarchical browsing); a second press falls through to the pre-existing `_tree_unfocus()`. Enter needed **no changes at all** — `_tree_open_selected()` already had a `if ($tree->filter_active()) { $tree->clear_filter(); }` branch waiting for a caller that never came; it now fires normally, opening the highlighted filtered result and returning focus to the editor exactly like plain-mode Enter.

**A second, related gap found while wiring this up:** the original finding's claim that "Renderer.pm has full rendering support for it" was optimistic. The cursor-placement math for the search bar existed, but nothing actually *drew* the search bar's content (icon + typed query) anywhere — `_render_tree_panel` rendered tree rows starting at row 1 unconditionally, with no reserved row for it, so in practice the blinking cursor would have landed on top of the first flat-filter match row with no visible query text at all. Also fixed:
- `Renderer::_render_tree_panel` now draws a dedicated search-bar row (search icon + query, scrolling to show the tail when the query overflows the panel width) as row 1 whenever `filter_active()`, before stickies/content — verified interactively via `hangon screenshot` (the icon and typed query render correctly, matched results start on the row below).
- `FileTree::_content_rows()`'s viewport-row reservation for the search bar was unconditional ("-1 for always-present search bar", even when not filtering) — a latent mismatch with what `_render_tree_panel` actually drew (which never reserved anything, since the row didn't exist). Made the reservation conditional on `filter_active()` so it now exactly matches the new rendering in both modes, instead of just accidentally being harmless before.
- The tree-context status bar's hint-pill row (`Renderer.pm::_render_context_status_bar`) gained a `/ filter` pill (second-highest priority, right after `⌃B back` — filtering has no other discovery path, unlike arrow/Enter navigation which a user can stumble into) that swaps to `Esc clear` once filter mode is active, and drops the `←→ fold` pill while filtering (the flat results view has no directories to fold). This is the actual UI-discoverability fix per CLAUDE.md Rule 2 — a keybinding alone isn't "discoverable through the UI" without an on-screen hint advertising it.

**Verification (Rule 5):** confirmed the broken state first via `hangon` (focused tree, typed characters, confirmed nothing happened — matching the original report). After the fix, full interactive flow re-verified via `hangon screenshot`: `/` activates filter mode with the search bar visible and cursor correctly placed; typing filters the flat results with match highlighting and live preview; Backspace edits the query and un-filters as it empties; Escape #1 clears filter and stays focused, Escape #2 unfocuses to the editor; Enter opens the highlighted result. Normal (non-filtering) tree navigation (arrows, Enter, Space, `{`/`}` resize) re-verified unaffected. New unit tests added in `tests/editor.t` (7 subtests covering trigger, char routing, the "/" mid-query edge case, Backspace including the empty-query exit case, Backspace as a browse-mode no-op, the two-step Escape, and Enter) and `tests/renderer.t` (search-bar row content, row omission when not filtering, and the hint-pill swap, including a defensive `can()`-guarded fallback so tree stand-ins without `filter_active()` don't die). `make test` clean (see `tests/editor.t`, `tests/file_tree.t`, `tests/renderer.t`). New QA coverage: `qa/scripts/tier1/tree_013_filter.sh` (rewritten — see below), `qa/scripts/tier1/tree_030_filter_enter_opens.sh` (new), `qa/scripts/tier1/tree_005_filter.sh` (rewritten — see below); `QA-REG-216` in `qa/40_regression_bugs.txt`; `QA-TREE-013` (expanded) and `QA-TREE-030` (new) in `qa/22_file_tree.txt`.

**Bonus find while fixing the QA suite (Rule 8, tautological-test anti-pattern):** `qa/scripts/tier1/tree_013_filter.sh` already existed and already pressed `/` before typing — but on a filter mismatch it called `qa_skip` instead of `qa_fail`, a soft-pass that could never have caught this exact bug (it had presumably been silently skipping since the day it was written, for this exact reason). Rewritten to assert with `qa_fail` throughout, plus locks in the "plain typing without `/` does nothing" invariant explicitly. `qa/scripts/tier1/tree_005_filter.sh` had the same anti-pattern *and* a stale/mismatched catalog ID (its filename claims `QA-TREE-005`, but that ID actually belongs to an unrelated "Left collapses directory" entry in `qa/22_file_tree.txt` — same class of drift as the `find_007_replace_preview.sh` mismatch found earlier this session). Left under its original name per CLAUDE.md's "IDs are stable — never renumber," but retargeted at a real, non-redundant edge case (arrow-key navigation still working the instant `/` is pressed, before any characters are typed) with a header comment explaining the mismatch.

### ~~P2: `⌃B` hides the tree instead of refocusing it when the tree is already visible-but-unfocused, contradicting `docs/UI_GUIDELINES.md`~~ FIXED (2026-08-31)
Found while interactively testing the filter-trigger fix above. `docs/UI_GUIDELINES.md`'s "Navigation And Focus" section documents `⌃B` as context-dependent: "when the file tree is hidden it shows the tree and focuses it; when the tree is visible it toggles focus between the tree and the editor." The actual code doesn't do that second half — `cmd_toggle_tree` (`Editor.pm`) only ever toggles `_show_tree` on/off unconditionally:

```perl
sub cmd_toggle_tree {
    if ($self->{_show_tree}) {
        $self->{_show_tree} = 0;               # always hides, regardless of focus
        ...
    } else {
        $self->{_show_tree} = 1;
        ...
        $self->{file_tree}->set_focused(1);    # always focuses, only reached from hidden
    }
}
```

From "visible but unfocused" — a real, reachable state (e.g. right after Enter opens a file, which unfocuses the tree but leaves it visible; or right after a second Escape) — pressing `⌃B` **hides the tree** instead of refocusing it, silently routing all subsequent keystrokes to the document instead. Reproduced twice while testing the filter-trigger fix (each time by accident, mid-testing): once it inserted stray characters into a QA fixture file's in-memory buffer (undone via `⌃Z`, never saved — confirmed via `git status` that nothing touched disk).

Flagging as P2: a real, easily-triggered discoverability/consistency gap that directly contradicts documented behavior, but not data loss (it's an ordinary undoable keystroke misdirection, and the mistyped characters are obvious once seen).

**Root cause, confirmed (Rule 5 "reproduce first"):** as diagnosed above. Reproduced fresh via `hangon` before touching code: `⌃B` (hidden→shown+focused) → `down`, `enter` (opens a second file from the tree, which calls `_tree_unfocus()` — tree stays visible, loses focus) → `⌃B` → tree disappeared entirely (full-width editor, no left panel), confirming the bug exactly as described. Also reproduced via the mouse-click-into-editor path (`hangon mouse-click`) and the Esc-based unfocus path — both land in the same visible-but-unfocused state and both triggered the same bug pre-fix.

**Fix (`Editor.pm::cmd_toggle_tree`):** added the third branch exactly as this entry's own "likely fix" note suggested — `_show_tree && file_tree && !focused()` now calls `set_focused(1)` + `_tree_reveal_current()` (the same highlight-resync used by the hidden→shown path) instead of falling through to the hide branch. The existing two branches are unchanged: hidden → show+focus; visible-and-focused → hide (still the *only* code path anywhere that clears `_show_tree` — confirmed via a full-codebase grep — so it remains the sole way to actually close the tree panel).

**A related, pre-existing documentation/test discrepancy found while confirming the doc's intent for the *other* two states (Rule 5's "test the other two states"):** `qa/22_file_tree.txt`'s QA-TREE-002 carried its own unresolved note ("Some prior behavior was '⌃B only toggles focus' ... Confirm which is current") about whether `⌃B` from the visible-and-focused state hides the tree or only unfocuses it. `qa/scripts/tier1/reg_183_tree_back_hint.sh`'s comment and its "Tree panel remains open after ⌃B (focus-switch, not dismiss)" assertion, and QA-TREE-020's VERIFY text, both assert the "only unfocuses, stays open" reading — but `reg_183`'s assertion (`grep -qE "a\.txt"`, the currently-open file's own name) is **tautological**: that filename is always present via the tab bar regardless of whether the tree panel itself is visible, so the assertion passes identically whether the tree hides or stays open, and could never have caught a regression either way. Confirmed via direct, repeated `hangon` interactive testing (screen captures with and without the fix; keystroke-routing checks sending a character and confirming whether it lands in the document) that the tree **does** hide on the second `⌃B` press from focused — matching QA-TREE-001, and matching this bug's own "likely fix" note's plan to leave that branch unchanged. Resolved the ambiguity by updating QA-TREE-002 and QA-TREE-020's text to state the confirmed current behavior instead of the stale "Confirm which is current" / "stays open" language. **Not fixing `reg_183_tree_back_hint.sh`'s tautological assertion itself** — out of scope for this P2 fix (it doesn't guard the bug this entry is about, and rewriting another script's assertions carries its own regression risk); logged here as its own finding per Rule 6 for a future pass.

**Verified (Rule 5 "test after"):** `tests/editor.t` gained 5 new subtests ('cmd_toggle_tree: hidden -> shows and focuses tree', 'visible+focused -> hides the tree', 'visible+unfocused -> refocuses the tree (not hide)', 'visible+unfocused after Enter-opening a file, then refocus', 'full three-state cycle round-trips correctly') — 3 of them fail against the pre-fix code (verified by re-stashing the fix and re-running) and all pass after. `make test`: 1262 tests, all green, no noise. Interactively re-verified via `hangon` for all three states plus the mouse-click and Esc-unfocus paths — `⌃B` correctly refocuses the tree from every visible-but-unfocused entry point, while hidden→shown and focused→hidden remain unchanged. QA regression script `qa/scripts/tier1/reg_220_tree_ctrlb_refocus.sh` (`QA-REG-220`, cross-referenced from `qa/22_file_tree.txt` QA-TREE-002) reproduces the exact bug trigger and asserts non-tautologically using a third file (`ccc.txt`) that only the tree panel — never the tab bar — can show; verified non-tautological (3 of 8 assertions fail pre-fix, all 8 pass post-fix).

## Found while fixing the P0 find/replace preview bug (2026-08-30)

### P3: Find bar can still overflow `$cols` on an extremely narrow terminal (≤70 cols) combined with a very large match count
While root-causing the P0 screen-corruption bug above, fixed the general case (any realistic terminal width ≥76 cols, or any match count at ≥76 cols) via `Renderer::find_bar_input_width`, but confirmed via direct measurement that a more extreme combination — a ≤70-column terminal *and* a match count of 15+ (producing a long `"↑↓ N of M"` string) — can still overflow by a few characters (e.g. 70 cols + 15 matches: overflow by 1; 70 cols + 9999 matches: overflow by 5). At that point the bar's *fixed-width* elements (pills, labels) plus a long match-count string alone approach `$cols` before any input-field width is even in play, so shrinking the input fields (which `find_bar_input_width` already does, down to a hard floor of 1) can't fully compensate. Not fixed here — this is a substantially more extreme combination than the reported repro (3 matches, 80-column terminal, the standard default) and fixing it properly would require either truncating/hiding the match-count text or further compressing the pills, which risks its own display regressions and wasn't warranted for an unattended P0 fix session. `tests/renderer.t`'s new overflow-guard tests are scoped to cols ≥76 accordingly, with a comment explaining why.

### P3 (fixed as part of this session): `find_010_replace_single.sh` and `find_021_replace_confirm.sh` were passing for the wrong reason, then started crashing silently once the P0 bug above was fixed
Discovered by the full `qa/runner.pl --tier 1` run done as part of verifying the P0 fix above (Rule 5's "test after"): both scripts errored (not just failed) with no PASS/FAIL output at all.

Root cause, in two parts:
1. **Wrong interaction model.** Both scripts pressed `Enter` in the replace field expecting a *single* replacement (per their own names — "Replace single occurrence" / "Replace single confirms before replacing"), but `Enter` only does that when `find_replace_all` has been toggled off via Shift+Tab first; by default (`find_replace_all => 1`) `Enter` performs a full Replace-All. Neither script ever sent Shift+Tab, so both were actually testing Replace-All all along.
2. **That mismatch was masked by the P0 bug itself.** Pre-fix, Tab-prepopulating the replace field with the find term left it unselected, so typing `"ZZZ"` after the find term `"aaa"` produced the replace value `"aaaZZZ"` — every `"aaa"` got replaced with the literal `"aaaZZZ"`, and both scripts' `grep -o "aaa"`/`grep -o "ZZZ"` substring counts came back non-zero (since `"aaa"` is a substring of `"aaaZZZ"`), coincidentally satisfying each script's `-ge 1 && -ge 1` assertion — a false-positive pass that had nothing to do with either script's actual intent. Once the P0 fix made replace-all behave correctly (all `"aaa"` → clean `"ZZZ"`, zero `"aaa"` substrings left), the assertion's `aaa_count -ge 1` half legitimately went to 0 and failed — but each script's `echo "$content" | grep -o "aaa" | wc -l` pipeline, run under `qa-helpers.sh`'s `set -e -o pipefail`, itself exits 1 when `grep -o` finds zero matches, aborting the whole script *before* it ever reached the `qa_fail` call — hence "error, no output" rather than a clean fail.

**Fix:** rewrote both scripts to (a) actually reach single-replace mode via a raw `\x1b[Z` (CSI "back-tab", the standard VT220 encoding of Shift+Tab) sent through `qa_raw_stdin` — the same raw-injection technique `reg_202_csiu_special_keys.sh` already established for keys hangon's named `keys` list doesn't cover (confirmed via `InputParser.pm:305`, `$final eq 'Z'` maps to a Shift+Tab key event; verified interactively that one Shift+Tab from the default state toggles to single-replace mode without touching regex/case) — and (b) guard each `grep -o` with `|| true` so a legitimate zero-match count doesn't crash the script under `set -e -o pipefail`. Tightened both assertions from `-ge 1` to the exact expected counts (`ZZZ=1, aaa=2`) now that they're testing genuine single-replace behavior. Verified non-tautological: both now correctly fail (`ZZZ=1, aaa=3`, the same concatenation signature) against the pre-fix binary, and pass against the fix.

### ~~P2: No on-screen indicator for Replace-One vs. Replace-All mode, and no palette command to switch between them~~ FIXED (2026-08-31)
Found investigating the QA-script fix above. `Renderer.pm::_render_find_bar` reads `$find->{replace_all}` into a local `$replace_all` variable (line ~5001) but never uses it anywhere else in the function — there is no visible pill, label, or other indicator anywhere in the find bar showing which mode is currently active, and `CommandRegistry.pm` has no command for toggling it either. The *only* way to switch modes is Shift+Tab (which also, confusingly, cycles through regex/case toggles when pressed again — see `Editor.pm`'s Shift+Tab handler), with zero on-screen feedback about the current state or that the toggle exists at all. This is a real UI-discoverability gap (CLAUDE.md Rule 2: "every feature must be discoverable through the UI").

**Reproduced first (Rule 5):** confirmed interactively via `hangon` — ⌃F, type a term, Tab to replace field showed a plain `Replace:` label; sending raw Shift+Tab (`\x1b[Z`, since it's not in `hangon`'s named `keys` list) toggled `find_replace_all` internally but produced a byte-for-byte identical screen capture, confirming zero visual feedback.

**Fix, attempt 1 (reverted):** a separate rounded pill matching the regex/case toggle pills' full styling (`" All "`/`" One "` inside pill edges, ~8 chars wide including the gap before the next pill) was implemented first. It broke `tests/renderer.t`'s pre-existing P0 overflow-guard tests at cols=76 (every match count) and cols=80 (match_count ≥ 250). Root cause: measuring the *pristine, unmodified* renderer directly showed `find_bar_input_width` already lands with **zero spare margin** at common widths (76-90 cols) — the input fields are already shrunk to their computed floor there (as low as 1-4 chars wide) with `padding_needed` flooring at 0, so there is no slack left to absorb any additional fixed-width element. This find bar has now had overflow regressions caught three times (the original P0 fix, the P3 follow-up for ≤70 cols, and this one) — the lesson: **any new fixed-width element added to this bar must be measured against the real renderer at cols=76/80 with a large match count before assuming there's room, not estimated by eye.**

**Fix, attempt 2 (shipped):** rather than add width, repurposed the existing `"Replace:"` label itself — it now reads `"Rep All:"` or `"Rep One:"` depending on `find_replace_all`, colored like the regex/case toggle pills' active (colored) vs. inactive (dim) states. Both strings are exactly 8 characters, identical to the original `"Replace:"`, so it's a zero-width-budget change: none of the four places that duplicate the find-bar layout formula (`_render_find_bar`, `render()`'s cursor-positioning code, `Editor.pm::handle_find_bar_click`, `Editor.pm::_handle_find_bar_drag`) needed to change. The label is also now clickable (`handle_find_bar_click`'s new `$label_start`/`$label_end` region, previously dead space) via a new `Editor.pm::_toggle_replace_all_mode()` — a clean, single-purpose toggle with no side effects on regex/case, unlike Shift+Tab's second press. Also added a `CommandRegistry.pm` "Replace All Mode" palette command (`cmd_toggle_replace_all_mode`, opens Find and Replace if not already active) with a `get_toggle_state` special case so the palette shows `[on]`/`[off]` matching the current mode.

**Verified (Rule 5 "test after"):** `tests/renderer.t` (4 new subtests: label text per mode, absence when replace is inactive, width-neutrality between modes, and the full P0 overflow-guard sweep re-run with the new label at cols 76-120 × match_count 0-9999 × both modes — all pass) and `tests/find.t` (6 new subtests: default mode, clean toggle with no regex/case side effects, click-region math, palette command behavior including that it doesn't destructively reset an already-open replace field, and command registration/toggle-state). Interactively verified via `hangon`: label shows/toggles correctly at 80 cols, colors match the regex/case pill convention (confirmed via screenshot), the palette command works end-to-end including live `[on]`/`[off]` state. Mouse-click-to-toggle was verified via the unit test's exact click-region-math instead of interactively — raw SGR mouse click injection was confirmed to not reach the find bar's click handlers at all in this `hangon`/tmux harness (checked against the pre-existing, long-working Esc-pill click too, ruling out a regression), consistent with no other QA script in this repo testing find-bar mouse clicks interactively. QA regression script `qa/scripts/tier1/reg_217_find_replace_mode_indicator.sh` (QA-REG-217, cross-referenced from `qa/09_find_replace.txt` QA-FIND-029) covers the label text, Shift+Tab, the palette command, and no-overflow at both 80 and 76 cols. Verified non-tautological: 8 of 12 assertions fail against the pre-fix binary; all 12 pass against the fix. Two pre-existing QA scripts (`find_005_tab_replace.sh`, `find_024_palette_replace.sh`) asserted the literal old `"Replace"` string to confirm the replace field was visible — updated both to match `"Rep (All|One):"` instead, verified they still correctly detect the replace field opening.

Also found and logged separately (not fixed, out of scope) while writing the QA script: opening the command palette while find mode is active and then pressing Escape (without running a command) drops back to plain editing instead of restoring the find bar — see the new P3 entry immediately below.

### P3: Opening the command palette while find mode is active and closing it via Escape drops out of find mode instead of restoring it
Found while writing `reg_217_find_replace_mode_indicator.sh` (see the P2 fix above) — the script's original draft opened the command palette from an active find/replace bar, checked something, then pressed Escape to close the palette (without running a command), expecting to land back in the find bar. Instead the screen showed plain document editing, with the find bar gone entirely. Confirmed interactively via `hangon`, independent of the QA script: ⌃F → type a term → Tab (replace active) → ⌃Space (palette opens) → Escape (once clears the palette's filter text, a second Escape closes the palette) → find bar is gone, cursor back in normal editing mode. Not investigated further (out of scope for the P2 fix this was found during) — plausibly `$self->{state}` gets set to a palette-specific value on open and unconditionally reset to `STATE_EDITING` on close rather than restored to whatever it was before, but that's a guess, not a confirmed root cause. Low-priority: this only affects the specific workflow of opening the palette *while* find mode is already active and then explicitly backing out without running anything — most users open the palette from normal editing, or run a command from it (which keeps working fine, as `cmd_toggle_replace_all_mode` above demonstrates). Not fixed; the QA script and interactive verification for the P2 fix above were both restructured to avoid tripping over it (every palette interaction in `reg_217_find_replace_mode_indicator.sh` ends with Enter, never Escape).

### P3: `qa/09_find_replace.txt`'s `QA-FIND-007` catalog entry doesn't match the pre-existing `find_007_replace_preview.sh` script's filename/purpose
Discovered while investigating the P0 bug above's claim that `qa/09_find_replace.txt` had "zero test cases exercising live preview rendering." A QA *script* (`qa/scripts/tier1/find_007_replace_preview.sh`) already existed and does test preview rendering — but the catalog file's `QA-FIND-007` entry is a completely different, unrelated test case ("Replace One replaces current match only"), and no catalog entry anywhere references `find_007_replace_preview.sh` by name. So the claim was accurate in spirit (no *catalog-indexed* preview coverage existed) but the root cause is this pre-existing numbering/cross-reference mismatch between script filenames and catalog IDs, not a total absence of a script. Added `QA-FIND-028` (cross-referencing the new `reg_211_find_replace_preview_no_mutation.sh`) as part of the P0 fix above, but did not go back and retroactively fix `find_007_replace_preview.sh`'s catalog entry or strengthen its own (tautology-prone — `qa_assert_expect "ZZZ"` would still pass against the `"fooZZZ"` concatenation bug, since `"ZZZ"` is a substring of `"fooZZZ"`) assertion, since that script continues to pass today and isn't the primary regression guard for this bug (QA-REG-211 is); flagging for a future pass to either fix its catalog ID or retire/rename it to avoid future confusion, and to consider strengthening its assertion to a non-substring-matchable pattern.

## Session-end summary (2026-08-31, overnight autonomous session)

The user authorized a fully autonomous overnight session ("fire up a bunch of agents and get going... work through all the issues, improve scorecard, restructure code"). This section summarizes what landed, what's still open, and where to pick up next.

### Landed and pushed to `main` tonight

**Scorecard round 3** (fresh 6-agent audit run after round 2's fixes were already verified clean): 21 findings logged, of which the following are FIXED, merged, tested, and pushed:

1. **P0 — Find & Replace preview screen corruption + wrong preview text** (`3a2696f`). The originally-reported "document mutation" symptom did NOT reproduce on investigation (traced every call path, confirmed no mutating calls in the preview path) — most likely a misreading of the screen-corruption artifact. Two real bugs were found and fixed instead: an input-field-width overflow causing stacked duplicate rows, and a missing text-selection-on-Tab causing the replace field to concatenate instead of replace (which also silently corrupted real, non-preview Replace-All results).
2. **P1 — Multi-cursor/column-select cursor-desync data corruption** (`b109bae`). The single most important fix of the night: backspacing across a line-join, or deleting a multi-line selection, while a second cursor was active could leave that cursor pointing at the wrong document position (or a line number that no longer existed) — the next keystroke then silently corrupted unrelated text. Fixed via a shared position-fixup helper, replacing 5 independently-buggy copies of the same logic (the P3/DRY duplication finding, fixed together as recommended). Independently re-verified via the agent's own precisely-engineered QA scripts plus the full pre-existing `mc_*`/`col_*` regression suites.
3. **P1 — FileSearchEngine.pm ReDoS match-time gap** (`d53c4e1`). "Find in Files" could hang indefinitely on a catastrophic-backtracking regex; `FindEngine.pm` had already solved this exact problem for in-buffer find, the fix was just never applied to the sibling. Mirrored the existing pattern.
4. **P2 — AI completion security: API key leaked via `ps`, no HTTPS enforcement** (`75ff8e8`). The AI API key was passed as a `curl` argv argument, visible to other local users via `ps` for the request's lifetime; fixed via a short-lived 0600 temp file + `curl -K`. Also added HTTPS-only enforcement on the configurable AI API URL.
5. **Editor god-object restructuring, step 1: Palette extraction** (`12e051f`). `lib/Zepto/Editor/Palette.pm` (a `package Zepto::Editor;` file split, not a real module) is now `lib/Zepto/Editor/PaletteController.pm`, a genuine `package Zepto::Editor::PaletteController;` object — the second real precedent (after `TabManager.pm`) for decomposing the 7,800-line/220-method Editor god-object. Caught and fixed a real crash along the way (toggle-command rendering inside the live palette) that `make test`'s 1186 unit tests missed but `make qa` caught — see the "Update" note under "Editor god-object extraction — scoping conclusion" above for the full lesson.
6. **P2/P3 — Performance: Renderer tab-expansion cache, StateStore poll debounce, WrapMap/Renderer layering fix** (`ae2abbd`). Real benchmarks: `_expand_tabs()` ~22.7x faster (mirrors round 2's Highlighter token-cache fix), `StateStore::check_for_changes()` stat() calls reduced from ~10,000 to 2 in a typing-burst simulation.
7. **P2 — Tautological completion.t tests + test-coverage gaps** (`8d80741`). Removed 2 more tautological-fallback tests (same anti-pattern round 2 fixed elsewhere), added 12 new subtests for `cmd_close_tab` (including the data-loss-adjacent save-failure case), `cmd_quit`, and tab-navigation commands — previously zero-covered.
8. **P3 — DRY cleanup: bg-priority-chain duplication, ellipsis-truncation duplication, undo-group reentrancy bug** (`03b9c5c`). The undo-group nesting bug was upgraded from "latent, not currently triggered" to a confirmed real bug via a written repro before fixing (Rule 5). Also found and logged (not fixed, out of scope) that FileTree's flat-filter search feature has zero UI trigger — see below.

**Also fixed earlier tonight (scorecard round 2, carried over from before this /loop session began):** availability hangs (`cmd_transform` IPC::Open3 deadlock, clipboard paste timeout, Tab Width rendering bug), 3 security findings (ImageConverter.pm predictable temp file, StateStore.pm secrets world-readable window, VCS/Git.pm arg-injection edge case), 7 tautological QA/unit tests, the Kitty/fixterms CSI-u dropped-keys input bug, the Highlighter.pm token-cache perf fix (~12.8x faster), and dead-code/consistency cleanup (5 dead subs, `do_find_next`/`do_find_prev` consolidation, `⌃` glyph duplication, Tab Width bounds duplication).

### Feature-idea review (separate thread, published as an Artifact)

Also researched and organized the ~25 feature ideas/bugs from the user's phone note (mostly Reddit-linked neovim plugins) into an opinionated, categorized writeup — published as an Artifact (https://claude.ai/code/artifact/dfa287c0-1d1c-4afb-a8b0-ca0cdff795fa), not committed to this repo since it's a discussion doc, not project code. A live conversation followed: the user confirmed interest in lightweight in-document todo/due-date features (checkbox styling+toggle, due-date proximity coloring, next-open-item nav, in-buffer TODO outline — explicitly scoped to single-buffer, no cross-file indexing) and asked to review/refine Zepto's philosophy docs to make that single-buffer-only scope explicit. **A specific DESIGN.md addition was proposed but the user had not yet replied when this autonomous session wrapped up — this thread is still open, pick it up when they're back. Do not implement the todo/due-date features or the philosophy-doc change without their explicit go-ahead.**

### ~~P2: Toggling Light/Dark theme shifts the status bar because "light" has one more character than "dark"~~ FIXED (2026-08-31)
Found via direct user feedback while actively using the editor: "the shared ^ and opt button labels are hard to spot. I just saw 'T' but not '^T'" and "toggling between light and dark mode... the word 'light' has one more char than 'dark' [so] it makes the buttons shift."

**Root cause:** `Renderer.pm`'s status-bar pill builder (`_render_context_status_bar`, the Ctrl/Alt modifier-grouped pill section) concatenates the RAW toggle-display value onto the Theme pill's label (`$label .= ":$state_display"`), and `CommandRegistry::get_toggle_display` returns the theme preference's literal string value — `'dark'` (4 chars), `'light'` (5 chars), or `'auto'` (4 chars) — with no width normalization, unlike every other toggle command (which only ever displays the fixed-width `'on'`/`'off'`). Reproduced live via `hangon` at a 140-column terminal: switching Dark → Light didn't just shift the Theme pill by one column, it pushed the neighboring "Word Wrap" pill's plain-language label below its priority-based visibility threshold entirely — dark showed `Word Wrap Z`, light silently dropped to a bare `Z`. Confirmed via a unit-level width sweep (cols 60–160) that this threshold-crossing inconsistency recurs at multiple specific widths, not just 140 — it's a structural issue, not a one-off.

**Fix:** pad the theme toggle's display value to the width of the longest possible value (`'light'`, 5 chars) via `sprintf('%-5s', $state_display)`, scoped specifically to `$cmd->{pref} eq 'theme'` so no other toggle command's behavior changes. This makes the Theme pill's width — and therefore everything rendered after it — completely independent of which theme is active.

**Tests:** `tests/renderer.t` — new subtest "Theme pill has constant width across dark/light/auto (no status bar shift)": confirms identical total rendered width for dark vs. light at the exact width (145 cols) where "Word Wrap" survives in both, confirms it lands at the identical column in both, confirms `'auto'`'s width matches `'light'`'s (not just `'dark'`'s, since all three are now the same padded width), and sweeps cols 60–160 asserting dark/light produce identical total width at every one. Confirmed failing against the pre-fix code first (11 of 105 assertions failed, including the exact `got: 140 / expected: 139` width mismatch and the Word Wrap presence/position checks) before implementing the fix, then passing after (Rule 5).

**Interactive verification:** re-verified live via `hangon` at both 140 cols (where the fix makes both themes consistently show the compact `Z` glyph instead of dark showing the full label while light doesn't) and 145 cols (where both themes now consistently show the full `Word Wrap Z` label at the identical column) — confirmed byte-for-byte identical status bar layout apart from the theme word itself.

**Also noted (not addressed, separate design question):** the user's other feedback — that the shared `⌃`/`⌥` column-header modifier glyph is easy to miss when scanning an individual pill, since a bare letter like "T" doesn't visually carry "this is Ctrl+T" without backtracking to the column header — is a legitimate discoverability critique of an intentional space-saving design (`docs/UI_GUIDELINES.md`'s "modifier shown once" pattern), not a straightforward bug with one correct fix. Flagged for discussion with the user rather than a unilateral redesign. **Resolved below.**

---

### P2: Status bar modifier column header hard to spot on individual pills (UX redesign, resolved)

**Reported by user (live, interactive):** *"The shared ^ and opt button labels are hard to spot. I just saw 'T' but not '^T'"* — direct feedback while using the editor, following on from the theme-shift bug above.

**Root cause:** intentional design (`docs/UI_GUIDELINES.md`'s "modifier shown once" pattern) rendered the `⌃`/`⌥` modifier glyph exactly once per column, as a small dim separator label, with every pill in that column showing only its bare key (`Save S`, not `Save ⌃S`). This saved horizontal space but meant a pill viewed in isolation (e.g. scanning quickly, or the header having scrolled out of attention) gave no visual cue that a modifier was needed at all.

**Design process:** implemented three candidate treatments directly in the working tree (bold-glyph header, no change to stripping; repeat modifier per-pill; colored badge per-pill), screenshotted each via `hangon screenshot` at real terminal width, sent all three (plus baseline) to the user as PNGs for a side-by-side comparison rather than describing the tradeoff in prose.

**User's decision:** *"Def prefer the ^T option. Also no need for the ^ on its own so that can save some space... likely nets out"* — repeat the modifier on every pill (e.g. `⌃S`, `⌥Z`), AND remove the now-redundant standalone column-header glyph entirely (not just switch treatments while keeping the header, which the ^T mockup itself still had).

**Fix:** `lib/Zepto/Renderer.pm::_render_context_status_bar` — the modifier-stripping line (`$stripped =~ s/\Q$sym\E//g`) was removed so every pill's shortcut keeps its glyph; the `_render_group_label` sub and its two call sites (rendering the standalone `" ⌃ "` / `" ⌥ "` header) were deleted entirely; `$ctrl_label_w`/`$alt_label_w` (previously 3 columns reserved per column for the header) are now `0`. Net effect observed live: removing the 2×3-character headers freed enough width that "Word Wrap ⌥Z" now survives in full form at the default 80-column session in `--no-nerd-font` mode where it previously required narrowing further to exercise the compact path (see QA-REG-173 below) — the "roughly nets out" prediction held, and narrow terminals come out slightly ahead.

**Tests:** `tests/renderer.t` — rewrote "Status bar groups Ctrl pills left, Alt pills right, modifier shown once" as "...each pill shows its own modifier" — asserts `Save ⌃S` / `Word Wrap ⌥Z` ARE present (inverted from the old assertions) and that no standalone `⌃`/`⌥` glyph appears surrounded by whitespace on its own. Verified non-tautological by reverting `lib/Zepto/Renderer.pm` via `git stash` and confirming the rewritten assertions fail against the pre-redesign code (Rule 5).

**QA:** `qa/scripts/tier1/sbar_016_modifier_groups.sh` (QA-SBAR-016) rewritten to match — resizes to 145 cols so both groups render full-text, asserts modifier-repeated-per-pill and no-standalone-header, confirmed failing against pre-fix code via the same `git stash` technique. `qa/scripts/tier1/sbar_017_open_file_grouped.sh` (QA-SBAR-017) updated: Open File pill now legitimately shows `⌃O/⌃P` (previously asserted the opposite, back when a bare-key form was the "no longer hardcoded" signal). `qa/scripts/tier1/sbar_018_priority_narrow.sh` (QA-SBAR-018) updated: no longer locates the Ctrl segment via the now-deleted `" ⌃ "` header string. `qa/scripts/tier1/reg_173_compact_pill_icon.sh` (QA-REG-173) updated: the freed-up width means the default 80-col session no longer reaches compact form in `--no-nerd-font` mode, so the script now resizes to 74 cols to force it, and the assertion pattern now expects `W ⌥Z` (icon + modifier + key) instead of the old bare-key `W Z`. `qa/26_status_bar.txt` QA-SBAR-016 and QA-SBAR-017 catalog entries rewritten to match. `docs/UI_GUIDELINES.md`'s "Modifier-Grouped Pill Columns" section rewritten with the new behavior and the user-feedback rationale.

**Interactive verification:** confirmed live via `hangon` at 145 cols — `Save ⌃S`, `Open File ⌃O/⌃P`, `Find ⌃F`, `File Tree ⌃B`, `Theme:dark ⌃T` render left-to-right with no standalone header before them, `Word Wrap ⌥Z` renders right of the fill gap, `Commands ⌃␣` stays rightmost; toggling theme (dark → light → dark) confirmed the layout holds steady (no shift, consistent with the fix above).

### Still open (not attempted, or attempted and stalled)

- ~~**P1 — Ghost-text completion renders at the end of line content, not at the cursor.**~~ FIXED 2026-08-31 on a fresh attempt (the agent noted above stalled with no commit; this is unrelated follow-up work, not a resumption) — see the full FIXED entry earlier in this file for root cause, fix, and verification.
- ~~**P1 — FileTree's flat-filter search (`start_filter`/`filter_active`) has zero UI trigger, completely unreachable from the running editor.**~~ **FIXED** in a fresh follow-up session (2026-08-31) — see "File-tree fuzzy-filter trigger fix" above for the full writeup. `/` now triggers filter mode while the tree is focused; also found and fixed that `Renderer.pm` never actually drew the search bar's content (only had cursor-placement math for it), and found (not fixed, logged as its own P2) that `⌃B` hides rather than refocuses the tree when it's visible-but-unfocused.
- ~~**P2 — No on-screen indicator for Replace-One vs. Replace-All mode**, and no palette command to switch between them.~~ **FIXED** 2026-08-31 — see the full FIXED entry earlier in this file for root cause, fix, and verification. Also found (not fixed, logged as its own P3) that opening the command palette while find mode is active and dismissing it via Escape drops out of find mode instead of restoring it.
- ~~**P3 — `FileTree::_dir_vcs_status_from_hash()` is O(unloaded-dirs × changed-files)**, mitigated by an existing 5s debounce; explicitly deprioritized as a "bonus, only if time permits" item and not reached.~~ **FIXED** — see the full FIXED entry earlier in this file for root cause, fix, real before/after timing, and verification.
- ~~**P3 — Test coverage gaps**: `AIComplete.pm`'s command-layer wiring (`cmd_ai_setup`/`cmd_toggle_ai`)~~ **FIXED** 2026-09-01 (branch `add-aicomplete-test-coverage`) — see the full FIXED entries above ("`AIComplete.pm` — the one network-calling module — has zero test coverage" and "AI-completion command-layer wiring is untested") for what's covered (18 of 23 `AIComplete.pm` subs, plus `cmd_ai_setup`/`cmd_toggle_ai`) and what's still open (the fork/pipe-bound `check_trigger`/`_fire_request`/`poll()` orchestration, out of scope without a transport-injection refactor). `HelpDocs.pm` (54 lines, 3 subs) still has zero test coverage — not attempted, out of scope for this pass.
- **P3 — Find bar can still overflow on an extremely narrow terminal (≤70 cols) combined with a 15+ match count.** Edge case beyond the original P0 repro's scope.
- **P2 — `Renderer.pm` (5,845+ lines) has quietly become a second, undocumented god object**, larger than `Editor.pm` itself, with no submodule-extraction precedent. Tracked but not scheduled for extraction — the Editor god-object work (Palette done, multi-cursor/selection-state next) was this session's architectural priority.
- **Editor god-object extraction, step 2: multi-cursor/selection-state.** Not attempted — per the scoping investigation, this is materially harder than Palette was (~28 inline dispatch branch points across 8-10 core editing methods vs. Palette's 2 integration seams) and needs its own careful re-scoping pass before implementation, following the same "map every touch point first" discipline that made the Palette extraction succeed cleanly.
- ~~**P2 — `⌃B` hides the tree instead of refocusing it when the tree is visible-but-unfocused, contradicting `docs/UI_GUIDELINES.md`.**~~ **FIXED** 2026-08-31 — see the full FIXED entry earlier in this file for root cause, fix, and verification (`QA-REG-220`). Also found (not fixed, logged as its own finding in that entry) that `reg_183_tree_back_hint.sh`'s "Tree panel remains open after ⌃B" assertion is tautological and that QA-TREE-002/QA-TREE-020 carried stale text about that unrelated, unchanged (and confirmed-correct) hide-on-focused behavior — resolved the documentation ambiguity, left the test code itself for a future pass.
- ~~**P2 — Shift+Tab in the find/replace bar drops the last character of BOTH the Find and Replace field values.**~~ **FIXED** (2026-08-31, fresh follow-up session, branch `fix-shifttab-field-truncation`) — see the full FIXED entry below for root cause, fix, and verification. Not an `InputParser.pm`/CSI-`Z` bug and not specific to Shift+Tab after all: the actual defect was a stale-scroll-offset bug in the shared `InputWidget::viewport()` used by every status-bar text field.
- ~~**P2 — Tab-bar buttons (close/tabs/quit hints) use a visually different style than the bottom status bar's pills**~~ **FIXED** 2026-09-01 (branch `unify-tabbar-pill-styling`, ASKS.md item 3) — see the full FIXED entry near the end of this file for investigation, fix, width-floor trade-off, and verification.
- ~~**P2/P3 — Scrolling to the end of a file lets the final line scroll off the top of the viewport, past the point where most editors stop.**~~ **FIXED** 2026-09-01 — see the full FIXED entry below for root cause, fix, and verification (`QA-REG-221`).
- ~~**UX design question (not a straightforward bug) — the top-of-screen column indicator jumps around while moving the cursor down across lines of different lengths**, because it reports the cursor's real (bounded-by-line-length) column rather than a "sticky" intended column.~~ **RESOLVED 2026-09-01 — already correctly implemented, not a bug.** See "Sticky/goal column (ASKS.md item 2) — investigated, found already correct, hardened with tests" below for the full investigation, mutation-tested regression coverage, and interactive verification. No `View.pm` changes were needed; `_preferred_col` already implements this exactly.

### Sticky/goal column (ASKS.md item 2) — investigated, found already correct, hardened with tests (2026-09-01)

Picked up as ASKS.md item 2, on branch `add-sticky-goal-column`, following the user's live report: *"As I move cursor down across lines (either via mouse drag or arrows), the column indicator on top ruler jumps around due to lines ending before cursor position."* The user separately confirmed a concrete design: track a separate "goal" column that survives moving through shorter lines; pin the cursor at true end-of-line (never drawn past the text) when goal exceeds a line's length; End sets goal to the line's real end; typing while pinned past a short line's end snaps to the true end (explicitly rejecting whitespace padding).

**Rule 5 discipline, "reproduce first":** before writing any fix, tried to reproduce the described jumping behavior — first by reading `View.pm`'s cursor-movement code, then via direct unit-level probes against `Zepto::View`, then via the actual compiled binary through `hangon` (both keyboard arrows and `hangon mouse-drag`). **Could not reproduce it.** `View.pm` already has a `_preferred_col` field (`new()` doc comment: "Preferred column for vertical movement, to handle short lines") that is:
- Updated to the real cursor column on every `set_cursor()` call (i.e. every horizontal move, Home/End, mouse click/drag, typing) — this is exactly the "horizontal movement resets the goal" rule.
- **Not** updated by `move_up`/`move_down`/`move_page_up`/`move_page_down` (both the plain and the word-wrap-visual-row code paths) — each of those reads `_preferred_col` as the *target* column, clamps the resulting `cursor_col` to the landing line's real length, but leaves `_preferred_col` itself untouched. That is precisely the sticky-goal-column pattern the ask describes.
- `do_insert_char` (`Editor.pm` ~3419-3480) always inserts at the *current* (already-clamped) `cursor_col`, then calls `move_right()` — since `cursor_col` is never virtually past a real line's end outside column-select mode, "typing past end" can't actually produce padding; it always lands at the true end and the subsequent `move_right()` naturally updates the goal to match.
- Mouse-drag (`Editor.pm::handle_mouse_event`, the `'drag'` branch) recomputes the document column fresh from the screen's `x` position on every move event via `visual_to_char_col()` — for a drag that stays at a fixed terminal column while moving down (the normal case), this has the same net effect as a tracked goal column, with no separate field needed.

Verified all of this two ways: (1) direct `Zepto::View`/`Zepto::Editor` unit probes covering arrow up/down through 1-4 shorter lines and back, Page Up/Down (both word-wrap-off and word-wrap-on, including crossing full document-line boundaries, not just wrap-segment boundaries within one line), Home/End, horizontal-reset, typing-past-end (byte-level check of the resulting line content — no stray whitespace), and with a narrow viewport forcing horizontal scroll; (2) the actual compiled `./zepto` via `hangon` — arrowed down through a long→short→short→long 4-line file, screenshotted the intermediate pinned-at-true-end state and the restored-original-column state, typed a character while pinned on a short line and confirmed via `od -c` on the saved file that no padding spaces were inserted before the typed character, and confirmed the same restoration via `hangon mouse-drag` with `--steps` through several short lines.

**Conclusion: no `View.pm`/`Editor.pm` code changes were made** — inventing a "fix" for correctly-working code would have violated Rule 5 (nothing to reproduce) and Rule 7 (no new patterns without a reason; `_preferred_col` was already the established pattern). Given this was zero-risk to verify (it touches no other subsystem — the field is private to `View.pm`), also ran a mutation test to prove the new regression coverage actually bites: temporarily changed `move_up`/`move_down`/`move_page_up`/`move_page_down` (both wrap and non-wrap branches) to update `_preferred_col` to the clamped landing column on every vertical move (i.e. simulate the "naive/broken" implementation the bug report describes) — this made the new tests fail with the expected symptom (goal not restored on a longer line), including one *pre-existing* test ("Cursor clamping" in `tests/view.t`) that turned out to already be an unrelabeled regression guard for this exact behavior. Reverted the mutation and confirmed all tests pass again before touching anything else.

**What was added:** regression coverage that didn't previously exist for most of these behaviors (only one pre-existing subtest, "Cursor clamping" in `tests/view.t`, covered a single up/down step) —
- `tests/view.t`: 6 new subtests — sticky column across multiple shorter lines and round-trip restore; End sets goal to the true line end (not a large sentinel); horizontal movement (Left/Right) resets the goal; Home resets the goal to where it lands; typing past a pinned short-line end snaps to true end with no padding (goal updates to match); Page Up/Down respect the goal the same as arrow keys.
- `tests/view_wordwrap.t`: 2 new subtests — goal column surviving crossing full *document* lines (not just wrap segments within one logical line) in word-wrap mode, and End resetting the goal in wrap mode.
- `tests/editor.t`: 3 new subtests, driven through real `handle_event()` key/char dispatch (not direct `View.pm` calls) — typing past a pinned end snaps with no padding via the actual `do_insert_char` call site, a sanity control proving the no-type case really does restore the old goal (isolating that the type, not something else, caused the reset), and Page Up/Down through real key events.

**Not covered / explicitly out of scope:**
- Column (rectangular block) selection mode's vertical extend (`do_column_select_up`/`down`, `Editor.pm` ~3942-3963) does **not** use `_preferred_col` at all — it uses the *actual current* `cursor_col` directly as the rectangle's right edge on every line, with no clamp (column mode already allows virtual whitespace past line end). This is correct, different, and *more* sticky than needed for that feature (a genuinely fixed rectangle edge), but it's a distinct feature from single-cursor goal-column tracking and was not touched or given new tests here.
- Multi-cursor mode was not specifically exercised for this behavior because plain arrow-key/Page-Up/Down/Home/End navigation already unconditionally clears multi-cursors before moving (`Editor.pm` ~1463-1466, pre-existing, unrelated to this investigation) — there is no multi-cursor vertical-movement path to test.
- Mouse-drag was verified interactively (`hangon mouse-drag`) but not unit-tested — it lives in `Editor.pm`'s mouse handler and isn't practically unit-testable the way `View.pm`'s keyboard paths are; the interactive verification is the evidence for that path.
- Did not investigate whether Find/jump-to-match, Go To Line, or other non-vertical-movement cursor relocations interact with the goal column — they all route through `set_cursor()`, which resets the goal by the same rule as any other explicit repositioning, consistent with the horizontal-reset behavior already covered.

**QA:** `QA-NAV-019` in `qa/07_navigation.txt`, script `qa/scripts/tier1/nav_019_sticky_goal_column.sh` (12 assertions: goal restored after 2 shorter lines, pinned-at-true-end at each step, round-trip up, horizontal reset, type-past-end snap with a saved-file content check). Discoverability note (per Rule 2): this is pure cursor-movement behavior with no associated command — there's nothing to add to the palette because there's nothing to turn on; it should simply feel like the unsurprising way arrow keys/Page Up/Down already behave, matching every other editor's sticky-column convention.

**Interactive verification:** `hangon` session `sticky-demo` (`--state-dir /tmp/zepto-sticky-column-state`), file with a 42-char line, "short" (5 chars), "tiny" (4 chars), a 46-char line. Moved to col 46 on line 1 (screenshot 1), arrowed down through both short lines landing pinned at each true end (screenshot 2 shows the cursor sitting immediately after "tiny", not floating past it), arrowed down once more restoring col 46 exactly on line 4 (screenshot 3, ruler badge and status bar both show "46"). Separately arrowed to a short line's pinned end and typed a character (screenshot 4: `shortZ` with cursor right after it); saved and confirmed via `od -c` the on-disk bytes are exactly `s h o r t Z \n` with no inserted spaces.

**Foreman re-verification (2026-09-01), independent of the above:** rebuilt this branch's binary fresh and drove the same class of scenario myself via a separate `hangon` session (`verify-sticky`) with its own 4-line fixture (a 46-char line, `short`, `tiny`, another long line) — arrowed to column 31 on the long line, down through both short lines (ruler/status bar correctly clamped to 6 and 5, the true end of each), down once more onto the second long line, and confirmed the column restored to exactly 31. Typed a character while pinned at a short line's end and confirmed the result was `shortX` with no padding. This independently corroborates the worker's core claim: arrow-key sticky-column already works correctly and needed no fix.

**Mouse-drag nuance found during foreman re-verification, not fully surfaced in the original report above:** traced `Editor.pm`'s `'drag'` mouse-event branch (`handle_mouse_event`, ~2065-2175) directly. Every drag-move event — not just drag-start — computes `$doc_col` fresh from the live screen `$x` via `visual_to_char_col()` and calls `$view->set_cursor($doc_line, $doc_col, 1)` unconditionally. Since `set_cursor()` is exactly what resets `_preferred_col` to match on every call (the same "horizontal movement resets the goal" rule that makes arrow-key movement correct), a mouse drag has **no persistent goal column at all** — the column at every intermediate row is determined solely by whatever the pointer's live `x` happens to be at that instant. The original report's own phrasing ("this has the same net effect as a tracked goal column... for a drag that stays at a fixed terminal column") is correct but understates how narrow that condition is: a real mouse/trackpad drag is essentially never perfectly vertical pixel-for-pixel, so ordinary hand movement during a drag will visibly shift the column from row to row — this is very likely what the user actually experienced and described as "jumps around... via mouse drag."

This is **not a bug to fix**, and implementing goal-column snapping during a live drag would itself be a regression: a drag-select's whole purpose is to follow the pointer's actual position for selecting text, and silently overriding that with a remembered column would make the selection stop tracking the mouse, which is broken drag behavior in any editor. Flagging this as informational context to relay back to the user rather than a `DECISION NEEDED` requiring a foreman-blocking choice: arrow-key/Page-Up/Down sticky-column is confirmed correct and needs no work; the "jumping" during mouse drag is expected pointer-follow behavior, not a defect, and matches how mouse-drag selection works in effectively every other editor.

### ~~P2: Shift+Tab in the find/replace bar drops the last character of BOTH the Find and Replace field values~~ FIXED (2026-08-31)

Picked up fresh in a follow-up session on branch `fix-shifttab-field-truncation` (the bullet above records the original finding: `⌃F` → type `aaa` → Tab to replace field → type `bbb` → raw Shift+Tab, CSI `Z` → both `Find:aaa` and the replace field's `bbb` render one character short, 100% reproducible, confirmed pre-existing rather than a regression from any of that session's other fixes).

**Reproduced first (Rule 5):** confirmed interactively via `hangon`, exact repro from the finding above — `Find:aa` and `Rep One:bb` after the raw Shift+Tab injection, matching the original report byte for byte.

**Root cause — traced, not guessed:** added temporary debug instrumentation (removed before the final commit) logging every raw input byte, every parsed event, and widget `view_offset`/`value` state at each step. This ruled out both suspects named in the original finding:
- `InputParser.pm`'s CSI-`Z` handling (`_decode_csi`'s `$final eq 'Z'` branch) consumes the raw `\x1b[Z` sequence in a single parse pass and emits exactly one `key=tab,modifiers=[shift]` event — no stray byte leaks through as a separate Backspace/Delete.
- `Editor.pm::handle_find_event`'s Shift+Tab branch never touches either widget's `{value}` — logged `find=aaa replace=bbb` immediately before and after that branch runs, both times fully intact.

The real bug is a pure rendering/display defect in `Zepto::InputWidget::viewport()` (`lib/Zepto/InputWidget.pm`), the shared scroll-window logic behind *every* status-bar text field (find/replace bars, Go To Line, Save As, command palette filter). `viewport()` caches its horizontal scroll offset (`view_offset`) on the widget object across render calls. Shift+Tab calls `Editor.pm::_update_find_matches(1)`, which re-runs the find engine's `search()` and leaves its `is_searching` flag transiently true for exactly one render frame. While true, `Renderer.pm::_render_find_bar` appends `"..."` to the match-count text (9 chars → 12 chars for a single match), which shrinks `right_side_width` and therefore `find_bar_input_width()`'s shared budget for both fields (4 → 3 columns in the exact repro: 80-col terminal, `"aaa"`/`"bbb"`, 1 match). With both fields exactly as wide as that transiently narrowed width and the cursor at the end, `viewport()`'s scroll-into-view check (`$cursor >= $vo + $width`) fires on both widgets and bumps `view_offset` from 0 to 1. On the very next render frame (a few ms later), `is_searching` goes false and the width widens back to 4 — but the stale `view_offset=1` was never reset, because the cursor still fit inside the now-wider `[view_offset, view_offset+width)` window, so nothing re-triggered a correction. Both fields then permanently rendered `substr($value, 1, 4)` — their first character scrolled out of view — even though `$self->{value}` itself was never touched. Not Shift+Tab-specific and not find-bar-specific: any caller that hands `viewport()` a transiently narrower width for one frame, while a same-width-or-shorter value's cursor sits at the end, can trigger the same stale-offset drift on any `InputWidget`-backed field.

**Fix:** `viewport()` now resets `view_offset` to 0 whenever the caller-supplied width is wide enough to show the entire value (`$len <= $width`), instead of trusting a cached offset that may have been computed for a narrower call:

```perl
# If the whole value now fits within $width, there is never a reason
# to hide any of it -- reset to no scroll unconditionally rather than
# trusting a cached view_offset from a previous call.
$vo = 0 if $len <= $width;
```

This only applies when the whole value already fits — the deliberate "one empty trailing cell at cursor" scroll behavior for values genuinely longer than the field (`tests/input_widget.t`'s pre-existing `'viewport scrolls to keep cursor visible when at end'`) is completely unaffected, both by inspection (that test's `len > width`, so the new reset never fires) and by a new explicit regression-guard test.

**Verified (Rule 5 "test after"):** `tests/input_widget.t` gained 3 new subtests (`'viewport self-corrects stale view_offset once value fits again'`, `'viewport resets stale offset to 0 whenever full value fits width'`, and the regression guard `'viewport does not disturb legitimate end-of-value scroll for long values'`); `tests/renderer.t` gained `'Find bar fields recover full value after a transient is_searching width narrowing'`, which reproduces the exact mechanism at the Renderer/InputWidget boundary (two `_render_find_bar` calls against the same widget objects, `is_searching => 1` then `=> 0`) — and also proves the underlying widget values were never corrupted even pre-fix (those two assertions passed against the unfixed code; only the *display* assertions failed). All new tests confirmed non-tautological: fail against the pre-fix `InputWidget.pm`, pass against the fix. Full suite: `make check && make build && make test` clean, 1261 tests, no noise.

Interactively re-verified via `hangon`: the exact repro (`⌃F` → `aaa` → Tab → `bbb` → raw Shift+Tab) now shows `Find:aaa` and `Rep One:bbb` fully intact; cycled 5 more Shift+Tab presses through the full mode rotation (back to Replace All) with both values staying intact throughout; repeated with a second, differently-sized term (`hello`/`world12345`) with legitimate overflow-scroll behavior (values longer than the field genuinely truncate to their tail, unaffected by the fix — correct, pre-existing behavior) confirmed unchanged; Home-key navigation within the field re-verified working normally. Also spot-checked the command palette filter field (a second `InputWidget` consumer) after the fix — unaffected, filters normally.

QA: `qa/scripts/tier1/reg_219_find_replace_shifttab_truncation.sh` (`QA-REG-219`, cross-referenced from `qa/09_find_replace.txt` `QA-FIND-030`) reproduces the exact bugs.md repro against a real running zepto, confirms both fields keep their full value through a complete Shift+Tab mode cycle, and repeats with a second term. Verified non-tautological: 6 of 13 assertions fail against the pre-fix binary (the primary-repro assertions); all 13 pass against the fix. `make qa` (tier 1, all ~641 scripts) run clean after the fix.

### State at end of session

Original wrap-up was at `main` `ae2abbd` (see above). Since then, three more fixes landed in a follow-up round: `fix-ghost-text-render-position` (`7193c6e`), `fix-filetree-filter-trigger` (`e4b0c80`), `fix-replace-mode-indicator` (`c29d4e3` — recovered from a stalled agent's complete, verified-but-uncommitted work). `make check`/`make build`/`make test` all clean after each. Two new bugs surfaced and logged during this round (the `⌃B` tree-focus bug and the Shift+Tab field-truncation bug above), neither fixed yet.

### ~~P3: [Documentation] Hardcoded developer path in QA catalog files~~ FIXED
`qa/01_installation_and_cli.txt` and `qa/36_preferences.txt` embedded the literal absolute path `/Users/joe/src/zepto` (8 occurrences total) in "Reference:" lines and example CLI commands — the exact class of mistake `CLAUDE.md`'s "No sloppy assumptions" section already documents as a past incident (`cd /Users/joe/src/zepto` hardcoded in 5 test scripts, broke on Ubuntu). Anyone other than the original author copy-pasting these example commands would run them against a path that doesn't exist on their machine.

**Fix:** "Reference:" lines (pointers to source files, `qa/01_installation_and_cli.txt` lines 8-9 and `qa/36_preferences.txt` line 8) now use repo-relative paths (`zepto`, `install.sh`, `Formula/`, `lib/Zepto/Preferences.pm`) instead of an absolute path baked to one machine. The four directory-argument examples (`qa/01_installation_and_cli.txt` lines 79/82/170/198/211 — QA-CLI-004, QA-CLI-009, QA-CLI-011, QA-CLI-012, all "open zepto against an existing directory to check tree behavior") now use `.` with an explicit "from the repo root" note, since the surrounding steps already assume `./zepto` is run from the repo root — this keeps the test using a real, reproducible directory with real files rather than a machine-specific one.

Confirmed via `grep -rn '/Users/joe' qa/` that no other files in the `qa/` tree (including `qa/scripts/tier1/*.sh`) were affected — this was two stale documentation examples that had already drifted from the real executable scripts. `qa/scripts/tier1/cli_004_open_dir.sh` (and the other QA-CLI-00x scripts) were checked and already use `$QA_TMPDIR` and never referenced the hardcoded path, so no executable script was broken and no `QA-REG-###` regression test was warranted. Verified interactively via `hangon`: `./zepto .` from the repo root opens with the file tree visible showing the repo's actual contents and no file loaded in the editor area, matching QA-CLI-004's VERIFY criteria exactly.

### P3: [Code Quality] Status-bar pill rendering hand-rolled at 4 call sites instead of reusing `_render_pill_list` — PARTIALLY FIXED (2026-09-01, branch `dedupe-renderer-pill-helper`)

A `/scorecard` DRY-category audit flagged 4 call sites in `Renderer.pm` that visually render rounded status-bar pills without going through the existing `_render_pill_list` helper (already correctly used for the Ctrl/Alt command-pill groups). Investigated each of the 4 individually rather than converting on the audit's say-so, per the "DRY is a means, not an end" principle:

1. **FILE_TREE tree-context hint pills** (`⌃B back`, `/ filter`, `↵ open`, `↑↓`, `←→ fold`) — **confirmed genuinely duplicative, converted.** These pills are pure keyboard-shortcut hints, not bound to any command — the hand-rolled loop was byte-for-byte equivalent render logic to `_render_pill_list` minus button/hover handling (which these pills never had, since `$ui->{hover_pill_index}` isn't even read in this branch of `_render_context_status_bar`). Extended `_render_pill_list` to accept `undef` for `$buttons_ref`/`$hover_pill_index`/`$btn_offset_ref` — when omitted, it renders a purely informational pill list with no hover highlighting and no click-button registration, instead of forcing every caller into the interactive/clickable shape. This is the same "non-interactive but pill-shaped" niche `_render_group_label` already carves out for non-pill labels; now there's a matching option for hint pills that keep the rounded-cap pill look.

2. **Open File pill** (FILE_TREE context) — **confirmed real but NOT converted.** Its click region (`x_start`/`x_end`) deliberately spans the *entire* rendered pill including both rounded caps (`$open_width` already folds in the `+2` cap columns and is used directly as the button span), whereas `_render_pill_list`'s convention starts the button *after* the left cap and ends *before* the trailing gap — a real ~2-column difference in clickable area when nerd-font icons are on. It's also unconditionally rendered in a single static color; `_render_context_status_bar`'s tree-context branch never reads `$ui->{hover_pill_index}` at all, so converting it would silently *add* hover highlighting where none currently exists. Both are genuine behavioral differences a "pure" DRY conversion would have silently introduced.

3. **Palette trigger pill (FILE_TREE context)** — **confirmed real but NOT converted.** Same two reasons as #2 (cap-inclusive click region, no hover support in this branch). Additionally, this pill and the Open File pill share a single fixed-width "gap" convention (one manual space between them, no trailing space after the last one) specifically to avoid re-overflowing `$cols` — the exact class of bug fixed in QA-REG-186. `_render_pill_list` always appends a trailing gap space after *every* pill in its list, including the last; feeding it `[Open File, Palette]` as one list would silently reintroduce a 1-column overflow at the exact widths QA-REG-186 guards.

4. **Palette trigger pill (DOCUMENT context, rightmost)** — **confirmed real but NOT converted.** Same click-region-includes-caps and no-hover-support reasoning as #2/#3 (this branch defines `$hover_pill_index` for the Ctrl/Alt groups but never checks it for this pill).

**Verdict:** items 2–4 are a deliberate design pattern — "anchor" trigger pills (always-visible, most-important actions) get a larger, cap-inclusive click target and static styling, while dynamic command-pill groups (Ctrl/Alt groups, and now the FILE_TREE hint pills) get the tighter click region and hover feedback `_render_pill_list` provides. Unifying them would be a legitimate follow-up, but it's a deliberate behavior change (bigger/smaller click targets, new hover states), not a "no-op" DRY refactor — out of scope for a pure-refactor task and not done here. If a future pass wants to unify all pill rendering through one helper, `_render_pill_list` would need a second extension: an opt-in "cap-inclusive click region" flag and an opt-out for the trailing per-pill gap space on list-final items.

**Verification:** `make check`/`make build`/`make test` clean (1267 tests, incl. the existing `tests/renderer.t` FILE_TREE hint-row subtests and the QA-REG-186 $cols-overflow sweep across 40–120 cols × nerd-font on/off — all passed unchanged, no test edits needed). Interactive `hangon` verification: captured the FILE_TREE hint row and DOCUMENT-context bottom bar via `hangon screen`/`hangon screenshot` before the change, then again after, at 80 cols in both nerd-font-on and nerd-font-off modes (toggled via the "Nerd Font" palette command) — all four captures were byte-for-byte/pixel-for-pixel identical to their pre-change baselines. Foreman re-verification (2026-09-01): rebuilt both the pre-fix (`c226382`) and post-fix binaries independently and diffed `hangon screen` output for the FILE_TREE hint row side by side — confirmed byte-identical, corroborating the worker's own A/B.

### ~~P1: Replace All undo granularity inconsistency (N undo entries for <=100 matches vs. 1 for >100) + Document::replace() undo-group bypass~~ FIXED (2026-09-01, branch `fix-document-replace-undo-group`)

Two related findings from a fleet audit, fixed together because the second depends on the first.

**Finding A — `Zepto::Document::replace()` bypassed `_undo_group` (latent, P2):** `insert()` and `delete()` both record their undo action via `_push_undo()`, which checks `$self->{_undo_group}` and, when a group is open (`begin_undo_group()`), appends to the group array instead of pushing a standalone entry onto `undo_stack`. `replace()` never went through `_push_undo()` — it built its own `{type => 'replace', pos, old_text, new_text}` action and pushed it straight onto `undo_stack` unconditionally, ignoring `_undo_group` entirely. Confirmed real by reading the code (not stale audit noise): `replace()` is not implemented via delete+insert composition through the normal insert/delete path — it manipulates the buffer directly and does its own bookkeeping. No caller combined `replace()` with an undo group before this fix, so it was purely latent.

**Finding B — Replace All undo granularity split (P1):** `Editor.pm`'s Replace All has two code paths keyed off match count. `_replace_all()` (>100 matches) builds the whole new document text via one string operation and applies it with a single `$doc->replace(0, $doc->length(), $text)` call — always exactly 1 undo entry. `_replace_all_sync()` (<=100 matches — the common case, needed for per-match capture-group expansion) looped `$doc->replace()` once per match with **no undo group around the loop** — N undo entries, so pressing Undo once after a small Replace All only reverted the *last* match, not all of them. No principled reason for the split (confirmed by reading both code paths): the >100 path was a later, separate performance optimization that never had its undo semantics reconciled with the pre-existing <=100 path. Judgment call: the >100 path's single-entry behavior is the correct target ("undo my replace-all" as one action matches user intent and how most editors behave) — the <=100 path was the outlier, not the reverse.

**Fix:**
1. `Document::replace()` now records its action via `_push_undo()` instead of pushing directly, so it joins an open `_undo_group` exactly like `insert()`/`delete()`.
2. `Editor::_replace_all_sync()`'s per-match loop is now wrapped in `$doc->begin_undo_group()` / `$doc->end_undo_group()`, unifying it with the >100 path's single-entry behavior. The >100 path itself is unchanged.

**A third bug surfaced by fixing the above (P1, also fixed here):** routing `replace()` through `_push_undo()` exposed two more pre-existing defects in `_push_undo()` that had never been reachable by `replace()` before:
- **Uninitialized-value warning:** `_push_undo()`'s consecutive-edit merge heuristic (for grouping adjacent single-char inserts/deletes typed within `UNDO_GROUP_TIMEOUT`) unconditionally read `$action->{text}` once `$action->{type} eq $last->{type}` — but `replace` actions use `old_text`/`new_text`, not `text`. Two back-to-back ungrouped `replace()` calls (e.g. `Zepto::Editor::Commands`'s multi-line comment-toggle, `_toggle_comment_lines`, which calls `$doc->replace()` once per line with no undo group — a separate, pre-existing call site, untouched by this fix) now hit that heuristic and warned `Use of uninitialized value in numeric eq (==)` on every affected edit, which showed up as unexpected stderr noise in `make test`. Fixed by restricting the merge heuristic to `insert`/`delete` action types only (`($action->{type} eq 'insert' || $action->{type} eq 'delete') &&` added to the condition) — `replace` actions never merge with anything, which matches the pre-existing behavior of the direct-push code path being replaced.
- **`_content_version` never bumped for grouped edits (real rendering bug, not just a warning):** `_push_undo()`'s grouped branch set `dirty`/`redo_stack`/`_vcs_dirty`/`_last_edit_*` but never incremented `_content_version` (the ungrouped branch does, at the bottom of `_push_undo()`) — and `end_undo_group()`'s flush doesn't bump it either. `WrapMap.pm`'s `_ensure_built()`, `Renderer.pm`'s render cache, and `Minimap.pm` all auto-detect document changes purely by comparing `$doc->content_version()` to their own cached last-seen value — with no bump, they never saw a version change for edits made inside *any* undo group and kept serving stale cached data computed from the pre-edit content. This bug pre-dates this session entirely and already affected the two other existing `begin_undo_group`/`end_undo_group` call sites in the codebase (`Editor.pm`'s `do_move_line_up`/`do_move_line_down` delete+insert swap, and `Editor::Commands`'s `_column_paste`) — it was simply never caught because no existing QA/unit test happened to assert on rendered content immediately after a grouped edit. First caught interactively, not by reading code: `qa/scripts/tier1/reg_226_replace_all_single_undo.sh` (written for Finding B) intermittently showed Replace All's new text truncated to the OLD line's length — e.g. `"foo bar"` (7 chars) replaced with `"REPL bar"` (8 chars) rendered as truncated `"REPL ba"` (7 chars) — while `tests/find.t`'s equivalent unit-level checks (which don't exercise the renderer) passed cleanly, pointing straight at a render-layer staleness bug rather than the undo/document logic itself. Reproduced deterministically outside the flaky QA-script timing by running `qa/scripts/tier1/reg_211_find_replace_preview_no_mutation.sh` (a pre-existing, unrelated find/replace QA script whose "real Replace-All still works" section happens to assert on-screen content immediately after Replace All) 3x in a row: failed 3/3 with the fix for Findings A/B applied but this one not yet, passed 3/3 on unmodified `main` (proving it was a genuine regression introduced by making `_replace_all_sync()`'s loop the first caller to combine multiple content-mutating `replace()` calls inside a group), and passed 3/3 again once this fix was added. Fixed by adding `$self->{_content_version}++;` to `_push_undo()`'s grouped branch, matching the ungrouped branch exactly.

**Tests:** `tests/document.t` — `'replace() inside begin/end_undo_group joins the group like insert/delete'` (Finding A: fails pre-fix with 3 undo-stack entries instead of 2, and a single `undo()` only reverting the trailing insert, leaving `'HELLO world'` instead of `'hello world'`; passes after) and `'Two consecutive replace() calls do not warn'` (the uninitialized-value regression: fails pre-fix with the exact warning text captured via `$SIG{__WARN__}`, passes after). `tests/find.t` — `'Replace All (<=100 matches, sync path) produces exactly ONE undo entry'` and `'...a single undo() fully reverts ALL replacements at once'` (Finding B: fail pre-fix — got 3 undo-stack entries for 3 replacements, a single `undo()` only reverted the last match — pass after) and `'Replace All (>100 matches, fast path) still produces exactly ONE undo entry (regression guard)'` (passes both before and after — confirms the >100 path was already correct and stays correct). `tests/wrapmap.t` — `'Edits made inside a Document undo group are still picked up (content_version bump)'` (the render-staleness bug: fails pre-fix — `content_version` unchanged after a grouped `replace()`, and WrapMap's rebuilt segments reflect empty/stale content instead of the new text — passes after). All four failure modes reproduced and pasted before the fix, all four pass after (Rule 5). Full suite: `make check && make build && make test` clean, 1273 tests, zero unexpected stdout/stderr (re-verified after the `_content_version` fix specifically, since that fix's own absence was what caused the stderr-noise investigation in the first place).

**Interactive verification (`hangon`):** Replace All on a 4-match file (`foo bar foo baz foo` / `qux foo end`, term "foo"→"XXX") — a single `⌃Z` reverted all 4 replacements at once (both lines back to original), a single `⌃Y` (redo) restored all 4 at once. Spot-checked the >100-match fast path with a 150-line file (term "needle"→"TARGET") — same single-`⌃Z`/single-`⌃Y` round trip, confirmed unchanged. Also re-verified the two other real `begin_undo_group` callers after the `_content_version` fix: Move Line Down (`⌥↓`) on a 3-line file swapped lines correctly with no rendering corruption, and a single `⌃Z` reverted the swap in one step; `qa/scripts/tier1/clip_007_column_paste.sh` (column-paste, the other grouped-edit call site) passed cleanly.

**QA:** `qa/scripts/tier1/reg_226_replace_all_single_undo.sh` (`QA-REG-226`, cross-referenced from `qa/09_find_replace.txt` `QA-FIND-032`) — reproduces the small-match-count bug (single `⌃Z` must revert all matches) and regression-guards the large-match-count fast path. `QA-REG-227` (Document-level, no independent UI manifestation — covered by `tests/document.t`, exercised interactively via `QA-REG-226`'s script through its one real caller). Both catalogued in `qa/40_regression_bugs.txt`. Verified non-tautological: the primary script's assertions fail against the pre-fix binary exactly as expected (single `⌃Z` reverted only the first of 4 matches, leaving `XXX` on the others) and pass against the fix.

**Coordination note — QA-REG numbering collision, resolved at merge time:** this fix originally claimed `QA-REG-222`/`223`/`224`. Two concurrently-running sibling agents claimed overlapping numbers on separate not-yet-merged branches: `agent-clipboard-alarm` (branch `fix-clipboard-copy-alarm-guard`) independently claimed `QA-REG-222` for an unrelated clipboard-copy-timeout bug, and `agent-sigwarn` (branch `add-sigwarn-handler`) claimed `QA-REG-225`. Flagged for the merge-gating process rather than resolved unilaterally, since renumbering risked colliding with in-flight work on those other branches. The foreman merged `fix-clipboard-copy-alarm-guard` (keeping `QA-REG-222`) and `add-sigwarn-handler` (keeping `QA-REG-225`) first, then renumbered this fix's three IDs to `QA-REG-226`/`227`/`228` (next free after 225) before merging, updating every reference across `bugs.md`, `qa/40_regression_bugs.txt`, `qa/09_find_replace.txt`, `tests/find.t`, `tests/wrapmap.t`, and renaming the QA script to `reg_226_replace_all_single_undo.sh`.

**Process incident (unrelated to the fix itself, logged for the record):** mid-session, `git stash` / `git stash pop` in this worktree collided with a concurrent sibling agent's (`agent-sigwarn`, branch `add-sigwarn-handler`) own `git stash` in *their* worktree — `refs/stash` is shared across all worktrees of a repository (they share the common `.git` dir), so a `git stash pop` here applied and dropped *their* stashed changes (an unrelated `__WARN__`-handler feature touching `Editor.pm`/`Terminal.pm`) into this worktree instead of this session's own. Caught immediately (the popped diff didn't match what this session had written), recovered without further `git stash` use by locating both sessions' actual stash commits as dangling objects via `git fsck --unreachable --no-reflog` (identifiable by their `WIP on <branch-name>: ...` messages) and restoring this session's correct state via direct `git checkout <stash-commit-sha> -- <paths>` (which only touches the working tree/index, never the shared `refs/stash`). Confirmed no lasting harm to the other agent: their own worktree still had their full, further-progressed working tree intact (it included files beyond what leaked here, proving they'd already independently stashed-and-recovered before this collision). Lesson for future sessions in this fleet: never use `git stash` inside a shared-`.git` worktree setup — use a throwaway branch, `git diff > file`, or plain file copies for any need to set aside and restore work-in-progress.

---

## Repo hygiene: 24 empty worktrees + 44 stale merged branches (2026-09-01)

Found while investigating a stale `/loop` wakeup that fired hours late with outdated content. `git worktree list` showed 24 leftover worktrees under `.claude/worktrees/agent-*`, most on named branches (`fix-filetree-discoverability`, `redesign-tab-bar`, `expand-llm-judge-coverage`, `fix-input-timing-races`, `fix-statestore-test-isolation`, `fix-light-theme-bg-fill`, `fix-discoverability-gaps`, `fix-stale-line-tail-render`, `fix-narrow-width-layout`, `fix-doc-accuracy`, plus 14 unnamed `worktree-agent-*`). Inventoried each with `git rev-list --count main..branch` and `git status --porcelain` before touching anything: **every single one was 0 commits ahead of main and 0 uncommitted files** — pure abandoned scaffolding (agents dispatched but never actually did any work, or branches created but never used), not lost work. Removed all 24 worktrees and their empty branches (`git worktree remove --force` + `git branch -D`).

Separately, `git branch` showed 44 more stray local branches with no worktree attached. Checked `git branch --merged main` vs `--no-merged main`: all 44 were already merged into main (mostly the session's own landed fixes, e.g. `fix-ctrlb-tree-focus`, `fix-shifttab-field-truncation`, plus more from earlier in the session like `extract-palette-controller`, `fix-multicursor-cursor-desync`). Deleted all 44 with `git branch -d` (not `-D` — lets git refuse anything not actually safe; nothing was refused). Left `backup-pre-history-cleanup` alone — a genuine unmerged branch from May 2026 with a diverged root and ~90 "init" commits, clearly a deliberate safety snapshot from a prior git-history rewrite, not agent debris.

`git worktree list` and `git branch` are now clean (just `main` + the one intentional backup branch).

### ~~P2 — Mouse-wheel scroll-down doesn't clamp at end of file; last line rises to the top of the viewport instead of staying pinned at the bottom~~ FIXED (2026-09-01)

**Reported by user (live, interactive):** *"when scrolling to end of file, it's possible to scroll most of doc (except final line) off screen. most editors keep final line at bottom but dont allow to scroll further"*

**Reproduced first (Rule 5):** opened a 200-line file via `hangon`, sent a large `mouse-scroll --delta 500` past the end. Confirmed exactly as reported: line 200 landed as the TOPMOST visible row, with 19+ blank rows rendered underneath it in the viewport.

**Root cause:** `View.pm::scroll_down` (the mouse-wheel-down handler, `Editor.pm:2041` — independent of cursor position, unlike arrow-key scrolling) computed `my $max_scroll = $self->{document}->line_count() - 1;` and clamped `scroll_line` to that. This is the maximum *document line index*, not the maximum *scroll offset* — it lets the very last line become the top row of the viewport. The correct clamp is `line_count() - viewport_rows` (floored at 0 for documents shorter than the viewport), so the last line lands at the *bottom* row instead.

Cursor-driven scrolling (arrow keys, `ensure_cursor_visible()`) was never affected — that's a separate code path with its own, already-correct clamping logic (`View.pm:915-917`: `$self->{scroll_line} = $self->{cursor_line} - $self->{viewport_rows} + 1` when the cursor moves past the bottom of the viewport). Verified this directly: pressing Down 210 times on the same 200-line file correctly stopped with line 200 pinned at the bottom row, no bug. The bug was specific to `scroll_down`, which only mouse-wheel-down calls.

**Fix:** `lib/Zepto/View.pm::scroll_down`:
```perl
my $total_lines = $self->{document}->line_count();
my $max_scroll = $total_lines > $self->{viewport_rows}
    ? $total_lines - $self->{viewport_rows}
    : 0;
```
As a side effect this also fixes the same bug on documents *shorter* than the viewport — previously such a document could still be "scrolled" by `line_count() - 1` lines, which would push its own last line to the top with blank space below it (visually the same bug, just also reachable on tiny files, not only ones taller than the viewport). Now `max_scroll = 0` for those, so they never scroll at all, which is correct.

**Tests:** `tests/view.t` — new subtest `'scroll_down clamps so the last line stays pinned at the bottom, not the top'`: a 10-line doc in a 4-row viewport clamps to `scroll_line == 6` after `scroll_down(1000)` (so line index 9, the last line, is the bottom row — confirmed via `visible_line_range()` returning `(6, 10)`), and a 3-line doc in a 10-row viewport never scrolls (`scroll_line` stays `0`). Verified non-tautological via `git stash` on `lib/Zepto/View.pm`: fails against the pre-fix code (old clamp gives `scroll_line == 9`, not `6`), passes after the fix.

**QA:** `qa/scripts/tier1/ms_023_scroll_wheel_eof_clamp.sh` (`QA-MS-023`, cataloged in `qa/31_mouse_interactions.txt`; regression entry `QA-REG-221` in `qa/40_regression_bugs.txt`) — opens a 200-line file, sends a large mouse-wheel scroll-down delta via `hangon mouse-scroll`, asserts line 200 is visible AND lands in the bottom few rows of the pane rather than the top. Verified non-tautological the same way: fails against the pre-fix binary (line 200 appears at the top with blank rows below), passes after the fix.

**Interactive verification:** re-confirmed live via `hangon` post-fix — scrolling a 200-line file drastically down with the mouse wheel now stops with line 200 correctly pinned at the bottom row of the viewport, matching standard editor behavior. Also re-confirmed arrow-key scrolling was unaffected throughout (same correct pinned-at-bottom behavior before and after this fix, since that path was never broken).

### ~~P2: Tab-bar buttons (close/tabs/quit hints) use a visually different style than the bottom status bar's pills~~ FIXED (2026-09-01, branch `unify-tabbar-pill-styling`, ASKS.md item 3)

**Reported by user (live, interactive):** *"buttons at bottom have pill shape, but at top (e.g. close, quit) use a different style. Also they're lowercase. Build a common component (reusable code)."*

**Investigated first (per ASKS.md's own instruction), reproduced before fixing (Rule 5):** located the tab-bar corner hint at `Renderer.pm::_render_tab_bar` (~line 1355, "Fill remaining space" section) and its FILE_TREE-context twin at `_render_context_status_bar` (~line 4455) — both fed by a single shared function, formerly `_core_nav_hint_text()`. Confirmed via direct `hangon` screenshots (before/after captured in a throwaway worktree, unmodified baseline first) that this hint rendered as **plain lowercase text** (`^W close   ⌥←/→ tabs   ⌃Q quit`) on the tab bar's own background color, with no rounded caps, no chip background, and no click target — visually nothing like the bottom status bar's `_render_pill_list`-rendered pills (rounded caps, distinct pill background, Title Case labels like "Save", "Open File").

**Decision: straightforward conversion, not a DECISION NEEDED.** Reusing `_render_pill_list` (the same helper the FILE_TREE tree-context hint pills were converted to use in the prior partial pill-dedup pass, `1d5c2ac`) fit almost exactly, with one genuine, narrow gap: `_render_pill_list` hardcoded the theme color `'status_bg'` for the pill-to-pill gap and nerd-font cap fill, which is correct for the bottom status bar but wrong for the tab bar (`tab_bar_bg` — a genuinely different color per `Theme.pm`, e.g. dark `bg_rgb(30,32,44)` vs `bg_rgb(36,40,59)`; confirmed both values differ, not incidentally equal). Fixed by adding a `$bg_color_name` parameter to `_render_pill_list` (all 3 existing call sites updated to pass `'status_bg'` explicitly; the two tab-bar/FILE_TREE-hint call sites pass `'tab_bar_bg'`/`'status_bg'` respectively) rather than duplicating the whole function — this is the "extend it further only if a genuine, narrow gap requires it" case ASKS.md anticipated, not architectural rework. No click target was added — this hint has never had one (informational only), and the task explicitly scoped out new interactivity; both call sites pass `undef` for the interactive-only args, matching the FILE_TREE tree-context hint pills' established convention.

**A second, real gap found mid-implementation:** `_fit_pill_group` (the greedy per-pill helper used elsewhere for pill columns) does per-pill accumulation — if the highest-priority pill fits in *full* form, it stops there and never tries compact form for the group, even if all three would fit compact together. Using it directly for this hint silently dropped "Quit" at exactly the width where a prior P1 fix (`QA-REG-171`) specifically added it to close a "quit has no on-screen hint anywhere" gap — reintroducing that exact regression. Fixed by adding `_fit_core_nav_hint_pills()`, an atomic all-full/all-compact/none fit across all three pills as one group (mirrors the original `_core_nav_hint_text()`'s two-tier degradation exactly), used instead of `_fit_pill_group` for this specific hint. Caught by writing the width-floor test *before* accepting the implementation as done (Rule 5) — the first draft (using `_fit_pill_group`) passed `make build` cleanly but silently broke this guarantee, only visible via direct output inspection.

**Fix (Rule 5 "fix"):**
- `Renderer.pm::_render_pill_list` — added `$bg_color_name` parameter (was hardcoded `'status_bg'` at 3 internal points); all 3 pre-existing call sites updated to pass `'status_bg'` explicitly.
- `Renderer.pm::_core_nav_hint_text()` replaced with `_core_nav_hint_pill_candidates()` (returns pill candidate structs: full/compact text + `pill_action_fg/bg/edge` colors, Title Case on the full-form labels only — "Close"/"Tabs"/"Quit" vs. the old "close"/"tabs"/"quit"; compact-tier glyph content is byte-for-byte unchanged from before, including a pre-existing, **not** fixed here, label/compact wording mismatch: the full form says "⌥←/→ Tabs" but the compact form spells out the actual `⌥,`/`⌥.` shortcut glyphs — flagging per Rule 6, out of scope for a pure visual-styling change) and `_fit_core_nav_hint_pills()` (atomic fit, see above) — both shared between `_render_tab_bar` and `_render_context_status_bar` so wording/casing can't drift between the two contexts, same guarantee the old shared function provided.
- Both call sites now render via `_render_pill_list` with `undef` hover/buttons/offset (non-interactive).

**Measured, disclosed trade-off (not a silent regression):** real pill chrome costs more horizontal space per pill (padding + inter-pill gap) than the old maximally-dense plain-text form. Directly measured via a synthetic sweep (`cols` 20-70, both nerd-font and ASCII-fallback modes, several tab-name lengths) rather than assumed: the compact tier's "never disappears" floor moved from a flat 40 cols to ~44 cols (nerd-font, short tab name) / ~38 cols (ASCII-fallback) up to ~51 cols (nerd-font, a realistic 12-char tab name) depending on how much of `tab_cols` the tabs themselves consume first. Below its floor the hint degrades to blank fill (confirmed via both the unit sweep and a live `hangon` screenshot at 40×15 — no corruption, no truncated glyphs, just absent), and quit/close/tab-switching remain fully reachable via `⌃␣` Commands regardless (the code's own longstanding comment already frames this hint as "lowest priority... first thing to drop under width pressure"). Surfaced explicitly here and in the screenshot sign-off request rather than silently accepted, per this project's "any UX/design decision gets surfaced, not picked unilaterally" convention — the alternative (a lighter/denser pill treatment to preserve the old 40-col floor) was not implemented since the user's ask was specifically to match the status bar's actual pill visual language, and a deliberately-different lighter pill would reopen the "different style" complaint from a different angle.

**A separate, pre-existing, unrelated bug found incidentally while building this fix's width-overflow test (Rule 6):** with only ONE tab open, an overly-long filename is never truncated or scrolled to fit the terminal width — `_render_tab_bar`'s truncation/scroll logic (`_truncate_tab_names` / `_calc_visible_tab_range`) is gated on `@tab_info > 1` (`Renderer.pm` ~line 1179), so a lone tab's pill renders at full, untruncated width regardless of how narrow the terminal is. Confirmed via direct A/B measurement against unpatched `main` (`git show main:lib/Zepto/Renderer.pm`, loaded standalone): a single 46-char filename at 25/30/35/40/45/50 cols renders at a constant 53-char width in all cases — a genuine `$cols` overflow, same failure class as `QA-REG-179`/`QA-REG-186` (soft-wrap → whole-screen scroll → tab bar pushed off-screen), reproducible on a completely clean `main` checkout, unrelated to and untouched by this fix. **Not fixed here** — out of scope for a corner-hint visual-styling task, and a real fix belongs in the tab-name-truncation code path, not the pill-rendering code this task touched. Logged for a future pass; the new `QA-REG-231` sweep test added below deliberately excludes the single-huge-tab-name case from its coverage (with a comment explaining why) so it doesn't spuriously fail on this separate, known issue while still fully covering the corner-hint pill conversion.

**Tests (Rule 5 "test after"):** `tests/renderer.t` — updated 5 existing subtests' assertions from lowercase (`close`/`tabs`/`quit`) to Title Case (`Close`/`Tabs`/`Quit`), including a new explicit "no stale lowercase leaks through" check and fixing one assertion (`unlike($s, qr/quit/)` in the "nothing fits" subtest) that would otherwise have silently become vacuous after the casing change (case-sensitive lowercase-only pattern would never match the new Title Case text regardless of whether it leaked through — switched to `/i`). Updated the narrow-width "never disappears" subtest to assert at its newly-measured real floor (51 cols, was 40) rather than weakening the guarantee — also added a same-width-minus-one check confirming the atomic fit drops the *whole* group, not a silent partial subset that would lose quit. Added a new property-sweep subtest, `'Tab bar row never exceeds $cols at any width... (QA-REG-231)'` (same technique as `QA-REG-179`/`186`) covering both nerd-font modes × 11 widths (25-120) × 5 tab-name/count combinations — confirmed it actually catches overflow (it initially failed for real, against the separate pre-existing single-tab bug described above, before that case was excluded with an explanatory comment; after excluding it, 0/440 combinations fail). Full suite: `make check && make build && make test` clean, 1278 tests, zero unexpected stdout/stderr.

**Interactive verification (`hangon`, Rule 2 — mandatory for this UI change):** session name `tabbar-pills-agent`, `--state-dir /tmp/zepto-tabbar-pills-state`. Since `hangon`'s resize mechanism is currently broken (logged separately, see ASKS.md item 4 / this file's "hangon resize" note) and `hangon start process` has no size flag, used `sh -c 'stty cols N rows M; exec ./zepto ...'` to set the real pty geometry before exec (confirmed via `tput cols`/`tput lines` inside the session that this genuinely sets the pty's window size, equivalent to a real terminal starting at that size) — screenshots confirmed correct at 40×15, 60×20, 80×20, and 90×20. At wider widths (90-110 cols) `hangon screen`'s raw text capture intermittently showed content *shrinking* as `cols` increased (e.g. "Close" truncating mid-word at 110 cols after showing complete at 95) — the opposite of what a real terminal could ever do, and inconsistent with deterministic direct-function-call measurements at the same widths, so treated as a known `hangon`-capture-side artifact (consistent with this file's prior documented case of `hangon screenshot` rendering wrong background colors) rather than a real bug; 80×20 and 60×20 screenshots showed the full 3-pill labeled form rendering completely and correctly, corroborating this. Functional verification (styling-only change, keybindings must be unaffected): confirmed `⌃W` (close tab, 2→1 tabs), `⌥,` (switch to previous tab, active-tab highlight + document content both changed correctly), and `⌃Q` (quit, process exited) all still work via direct `hangon keys` + screenshot before/after comparison.

**QA:** updated `qa/21_tabs.txt` `QA-TAB-013` (the existing "tab bar nav hints visible, labeled, and include Quit" test case — already covered this exact hint, so updated in place per Rule 8's ID-stability convention rather than adding a duplicate) to describe the new pill-shaped, Title Case rendering and the new atomic all-or-nothing degradation. Added `qa/40_regression_bugs.txt` `QA-REG-231` cross-referencing `QA-TAB-013` and `tests/renderer.t`'s new sweep subtest. This is a genuine visual-consistency bug fix (not just an aesthetic preference — the user explicitly reported the mismatch as a bug and asked for a shared component), so a regression entry is warranted, not just a feature note. Incidentally noticed while reading `qa/21_tabs.txt` that `QA-TAB-001` (a separate, unrelated test case) describes the tab *cap* glyph as a full-block `█` — stale documentation left over from the "make tabs more tabby" redesign that was reverted back to `◢`/`◣` triangles the same day (see this file's "Tab bar visual redesign" entry) — not touched here (out of scope for a corner-hint task, and `QA-TAB-001` isn't about the hint this fix changed), logged here per Rule 6 for a future doc-accuracy pass.

**What was NOT done:** did not add a click target to the corner hint (none existed before; not asked for). Did not fix the pre-existing, unrelated single-tab-name-never-truncates overflow bug found incidentally (logged above for a future pass). Did not fix the pre-existing label/compact wording mismatch in the "Tabs" pill (`⌥←/→` vs. the compact tier's actual `⌥,`/`⌥.` glyphs) — preserved byte-for-byte from the original text to keep this a pure visual-styling change. Did not attempt to work around `hangon`'s broken resize mechanism or investigate the wide-width capture artifact further — both are tooling issues already tracked separately (ASKS.md item 4), not zepto bugs.

**Follow-up, found by the human reviewing the sign-off screenshot (2026-09-01), fixed before merge — see `QA-REG-232` in `qa/40_regression_bugs.txt` for the full writeup:** *"I see some text underlined in the tabs and pills. And the rounded caps of the pills seem to be a different color to rest of pill."* Both symptoms were one root cause: `_render_tab_bar` keeps its whole baseline row underlined (with its own SGR-58 underline color, independent of foreground) from near the top of the function until a single `$UL_OFF` at the very end — the new corner-hint pill block sat inside that underlined span, so the pill text and its rounded caps both inherited the underline and its distinct color, which at the cap glyph's color boundary read as a mismatched edge color. Fixed with one `push @_out, $UL_OFF;` immediately before the pill block. `tests/renderer.t` gained a subtest inspecting the raw ANSI byte sequence directly (the right instrument for an attribute-only bug — `hangon screen`'s text capture doesn't preserve underline state); verified non-tautological via `git stash` (fails 1/124 pre-fix, passes after). Re-verified interactively in both themes and the FILE_TREE narrow-width compact form via `hangon screenshot`.

Merged to `main` and pushed — branch `unify-tabbar-pill-styling` cleared human sign-off after this fix.

---

## P0: Cursor left outside valid line numbers after paste → undo (2026-09-01)

**Reported live by the user** (`ASKS.md` item 0, the session's highest-priority item): *"I pasted a block of text, then hit undo, then some sequence of moving / redo, and my cursor ended up outside of the valid line numbers. I'm not sure exactly how I did it."* P0 per this file's own scale — an out-of-range cursor makes the next keystroke insert somewhere other than where the cursor is drawn.

**Reproduced first (Rule 5).** The user could not pin down the trigger, so the hunt started with a fuzz-style permutation sweep rather than a hand-picked sequence: `tests/undo_redo_cursor_bounds.t` builds 6 document shapes × 4 paste payloads × 5 paste positions × ~200 undo/redo/movement sequences and asserts the cursor, selection anchor and every multi-cursor are in range after **every** step. Against the pre-fix code it reported **9082 of 27480 permutations failing**, the first being far simpler than the user's description:

```
doc[single line, no trailing NL] paste[multi-line block] at[start of document]
  seq[undo] -- broke after 'undo': cursor line 5 out of range [0, 1)
```

**Minimal repro: paste a multi-line block, press undo once.** No movement or redo needed — those were incidental to how the user happened to notice it.

Confirmed live in the real binary via `hangon` on a 3-line file (`alpha/beta/gamma`) with a 5-line block pasted at the top:

- after `⌃V`: document 8 lines, cursor line 6 — fine
- after `⌃Z`: document back to 3 lines, **status bar reported `6:1`** — a line number that does not exist
- typing `X` there: the character was silently inserted at the **start of line 3**, not at the phantom line 6, because `line_col_to_offset()` saturates at the last real line. Saved file: `alpha\nbeta\nXgamma\n` — text landed somewhere the user was not looking
- the redraw was also corrupted: line 3 rendered as `Xgamm` (truncated) from the stale render cache, and the status bar still read `6:1` after the keystroke

**Root cause (traced, not guessed).** `Zepto::Document` stores no cursor information in its undo entries at all — `undo()`/`redo()` only replay buffer mutations. `Editor::Commands::cmd_undo`/`cmd_redo` called `$doc->undo()`/`$doc->redo()` and then left the view's cursor exactly as it was. `View::set_cursor()` does clamp, but undo/redo never routed through it, so undoing a paste that had shrunk the document left the cursor addressing a line that no longer existed. `cmd_undo`/`cmd_redo` are the **only** two callers of `Document::undo`/`redo` in the codebase, so this affected every undo and redo.

**NOT caused by this session's `Document.pm` undo-group / `_content_version` work (QA-REG-226/227/228).** The timing was suspicious, so it was checked directly rather than assumed: the same sweep fails **identically — 9082 of 27480** — at `a424abb`, the commit immediately *before* `e59af09` which landed those fixes; and `e59af09` does not touch `lib/Zepto/Editor/Commands.pm` at all (`git show --stat`). `git log -L` on `cmd_undo` shows its last functional change was `2d3055f`, long predating this session. The defect is original to the Editor module (`bc0c1f8`), not a regression.

**Fix.** New `View::clamp_to_document()` (`lib/Zepto/View.pm`) re-clamps every document position the view holds — cursor, selection anchor, all multi-cursors *and* their anchors, and `scroll_line` — into the document's current bounds, using the same rules as `set_cursor()` (including the column-select virtual-whitespace exemption, so column mode is unaffected). It only recomputes the preferred column and calls `ensure_cursor_visible()` when the cursor actually moved, so an already-in-bounds view is left byte-for-byte untouched. `cmd_undo` and `cmd_redo` (`lib/Zepto/Editor/Commands.pm`) call it immediately after a successful `$doc->undo()`/`$doc->redo()`. Because those are the only two callers of undo/redo, the invariant "cursor is always within `[0, line_count)` and `[0, line_length(cursor_line)]`" now holds after *any* undo/redo, not just the reported sequence.

**Tests.** `tests/undo_redo_cursor_bounds.t` — the sweep described above (trimmed to 23,880 permutations to keep it near 1s; Rule 3). It carries its own self-check subtest that pokes known-bad values into the view and asserts the bounds checker flags them, so a broken checker cannot yield a vacuous pass. `tests/editor.t` — new subtest `'Cursor stays in bounds across undo/redo'` driving the real `cmd_paste`/`cmd_undo`/`cmd_redo` command path: **11 of its 24 assertions fail against the pre-fix code**, all `"cursor line N out of range [0, 3)"`. It also asserts that a character typed after the undo lands at the cursor's *own reported* position, with the expected document text computed from the live cursor rather than hardcoded.

**QA.** `qa/scripts/tier1/reg_230_undo_cursor_bounds.sh` (`QA-REG-230` in `qa/40_regression_bugs.txt`, feature test `QA-UNDO-013` in `qa/04_undo_redo.txt`). Copies a 3-line block inside the editor, pastes it at **end** of document, undoes, and asserts the status bar's reported line is inside the now-3-line document, that a typed character lands on the line the cursor claims, and that the cursor stays in range through a following undo/move/redo. Verified non-tautological: **3 assertions fail against the unfixed binary** (`"Document has 3 lines, status bar reports line 5"`), all 10 pass after the fix, stable across 3 consecutive runs of each.

**Trap worth recording:** the first draft of that QA script pasted at the *top* of the document. That left the cursor on line 3 of a 3-line document after undo — in range by coincidence — so the script **passed against the unfixed binary and proved nothing**. The paste must leave the cursor *below* the document's original last line for this bug to be reachable at all. The script now carries a comment saying so.

**Interactive verification.** Before/after captured via `hangon` (`--state-dir` scratch dir, unique session names). Before: status bar `6:1` on a 3-line document, typed character landing on line 3, `Xgamm` render corruption. After: status bar `3:1`, cursor visibly on line 3, typing advances it to `3:2` and renders `Xgamma` correctly; paste → undo → ↓ → redo leaves the cursor at `3:1` in an 8-line document.

**Deliberately NOT changed (needs a UX call).** The clamp puts a stale cursor on the nearest valid position — which for the common "paste at end, undo" case is the document's last line, not the position the cursor occupied *before* the paste. Most editors restore the cursor to the edit site on undo, which would require `Document` to record cursor positions in its undo entries (its actions already carry `pos`). That is a visible behavior change to every undo/redo, so per `CLAUDE.md`'s do-not-touch rule it is left for the user to decide rather than picked unilaterally. The P0 — an out-of-range cursor and the silent mis-insertion it caused — is fully fixed either way.

## P2: `cmd_paste` in unit tests reads the developer's real system clipboard (2026-09-01)

Found incidentally while writing the QA-REG-230 regression tests. `tests/editor.t`'s mock terminal (`mock_terminal()`, backed by two temp files) still has `_clipboard_paste_cmd` populated — platform detection doesn't depend on being a tty — so `Editor::cmd_paste` shells out to `pbpaste`/`xclip` and **overwrites `$editor->{clipboard}` with whatever the developer happens to have copied**. The existing paste tests (`tests/editor.t` 'Copy and paste', ~line 1120) only pass because the clipboard is usually empty or irrelevant.

Demonstrated non-destructively (clipboard saved and restored around the probe): with `CLIPBOARD_POLLUTION` on the system clipboard, a test that sets `$editor->{clipboard} = 'Hello'` and pastes into `"Hello World"` produced `"CLIPBOARD_POLLUTIONHello World"` instead of the expected `"HelloHello World"`.

Not fixed here — out of scope for the P0 above, and it needs a decision about whether to neutralise the clipboard command centrally in `mock_terminal()` (which would change several existing tests' effective coverage) or per-test. The QA-REG-230 tests work around it explicitly via a documented `editor_with_paste_isolated()` helper that clears `_clipboard_paste_cmd`. Anyone touching the paste tests should do the same, or fix `mock_terminal()` centrally.

## P2: `make build` did not rebuild after a help-doc edit — shipped stale built-in docs (2026-09-01)

Found incidentally while updating `docs/help/changelog.md` for the P0 above. `build.pl` embeds `docs/help/*.md` into the single-file binary (it globs that directory directly), but the `Makefile`'s `zepto:` target only depended on `$(MODULES)` (`lib/**/*.pm`) and `build.pl`. Editing a help doc alone therefore left `make build` reporting `Nothing to be done for 'build'`, and the binary kept serving the previous revision of the built-in documentation — including the changelog that `CLAUDE.md` requires be updated on every commit.

**Fix:** added `HELPDOCS := $(wildcard docs/help/*.md)` to the `zepto:` target's prerequisites, with a comment explaining the coupling.

**Verified non-tautological:** with the target already up to date, `make build` correctly reports `Nothing to be done`; `touch docs/help/changelog.md && make build` then rebuilds (`Building single-file zepto... Built: zepto`). Against the pre-fix Makefile the same `touch` produced `Nothing to be done`, i.e. the stale binary the bug describes.

No QA script — this is a build-system dependency, not user-visible editor behavior, and the guard is the Makefile prerequisite itself.

---

## Architecture-audit follow-up: WrapMap↔Renderer coupling doc claim (2026-09-01)

### ~~P3: [Documentation] `DESIGN.md:88`'s WrapMap row described a coupling that had already been fixed one commit earlier, but the doc wasn't updated~~ FIXED

`DESIGN.md:88`'s WrapMap purity column read: *"calls into Renderer's private `_`-prefixed tab/column helpers directly (accepted coupling, not a public API)"*. That sentence was accurate when it was written (see the `~~P3: DESIGN.md labels Renderer and WrapMap "Pure function" — both claims are false~~ FIXED` entry above it in this file), but it describes a state of the code that no longer exists: commit `9b88233` ("Cache Renderer tab expansion, debounce StateStore polling, fix WrapMap layering") added real no-underscore public wrapper subs to `Renderer.pm` — `expand_tabs()` (wraps `_expand_tabs()`) and `char_to_visual_col()` (wraps `_char_to_visual_col()`) — and repointed `WrapMap.pm`'s call sites at them (see the `~~P3: WrapMap.pm reaches into Renderer.pm's private functions — layering violation~~ FIXED` entry above). That commit touched `lib/Zepto/Renderer.pm`, `lib/Zepto/WrapMap.pm`, `bugs.md`, `qa/40_regression_bugs.txt`, `tests/renderer.t`, and new QA scripts — but not `DESIGN.md`, so the architecture doc kept describing the pre-fix "reaches into private internals" state as current/"accepted" even after it had been fixed for real.

**Verified directly (not just trusting the prior bugs.md writeup):** re-read `lib/Zepto/WrapMap.pm` in full. All 4 cross-module calls into Renderer are non-underscore names: `Zepto::Renderer::expand_tabs()` (`:268`), `Zepto::Renderer::char_to_visual_col()` (`:288`, `:445`), `Zepto::Renderer::visual_to_char_col()` (`:483`). Confirmed in `lib/Zepto/Renderer.pm`: `expand_tabs()` (`:481`) and `char_to_visual_col()` (`:485`) are the thin public wrappers added by `9b88233` (`return _expand_tabs(@_)` / `return _char_to_visual_col(@_)`, with their own doc comment explicitly framing them as "the supported entry point instead" of the underscore-prefixed private functions they wrap); `visual_to_char_col()` (`:434`) was already public with no private counterpart (unchanged by that commit — see the original fix's own note that only the other two needed wrappers). None of the four functions WrapMap actually calls today are underscore-prefixed. `DESIGN.md:88`'s claim was therefore stale, not just imprecise.

Also checked whether this is isolated to WrapMap by grepping every `Zepto::Renderer::` cross-module call site in `lib/` (`grep -rn "Zepto::Renderer::" lib/ | grep -v lib/Zepto/Renderer.pm`): `Editor.pm` and `Editor/PaletteController.pm` also call several non-underscore Renderer functions/constants (`get_ruler_buttons`, `get_prompt_buttons`, `get_status_buttons`, `get_palette_geometry`, `get_palette_buttons`, `MIN_TEXT_WIDTH`, `MINIMAP_WIDTH`, plus `visual_to_char_col()` at `Editor.pm:1963,2154` — the same public helper WrapMap uses) — all consistent with the public/private naming convention, and confirms `visual_to_char_col()` has more than one caller (WrapMap is not its only consumer). One exception found and logged separately below: `Editor.pm:5189` calls the underscore-prefixed `Zepto::Renderer::_get_image_dimensions()` directly, which *does* violate the private-function convention — but that's a distinct, previously-untracked finding, not part of what `DESIGN.md:88` was describing (that line is specifically about the tab/column helpers WrapMap uses).

**Fix (doc-only):** Corrected `DESIGN.md:88` to describe the current, already-fixed reality — WrapMap calls Renderer's public `expand_tabs()`/`char_to_visual_col()`/`visual_to_char_col()` wrappers, not private `_`-prefixed internals — and added a cross-reference to this file's two prior entries so a future reader can see both halves of the history (the original leaky-coupling finding, and the code fix that resolved it). No code was changed by this entry: the architectural fix already happened in `9b88233`; there was nothing left to refactor. Considered whether the WrapMap→Renderer coupling itself (calling into Renderer at all from a layout module) is still worth flagging architecturally, independent of the naming issue — judged **not** a new architectural problem: the shared tab/column math is genuinely used by multiple modules (`WrapMap.pm` and `Editor.pm` both call `visual_to_char_col()`), the coupling now goes through a real, documented public API rather than a package-qualified reach into internals, and moving the tab-math functions out of `Renderer.pm` into a separate module would be a larger, unrelated restructuring with no bug driving it — not attempted here.

**Not done / explicitly out of scope:** did not touch `lib/Zepto/Renderer.pm` or `lib/Zepto/WrapMap.pm` (no code changes — the relevant refactor already shipped in `9b88233`); did not attempt to relocate the tab/column-math functions out of `Renderer.pm`; did not address the newly-found `Editor.pm:5189` → `_get_image_dimensions()` private-function call (logged as its own finding directly below instead, since it's a different call site with different callers and wasn't part of the original audit finding this entry is closing out).

**QA/changelog:** no QA script or `QA-REG-###` entry added — this is a pure documentation-accuracy correction with zero behavioral change (nothing to regress; `DESIGN.md` prose isn't exercised by any test or the running binary). No `docs/help/changelog.md` entry added for the same reason — no user-visible change, following the same precedent set by this session's `_render_pill_list` dedup work, which also skipped the changelog for an internal-only change.

### ~~P3: [Code Quality] `Editor.pm:5189` calls Renderer's underscore-prefixed (private-by-convention) `_get_image_dimensions()` directly across the package boundary~~ FIXED

### ~~P3: [Repo Hygiene] QA script ID collisions — 5 scripts squatting on 3 already-claimed catalog IDs~~ FIXED (branch `fix-qa-script-id-collisions`)

An audit flagged that several `qa/scripts/tier1/*.sh` (and, once swept, `tier2/*.sh`) executable scripts declared the SAME `QA-<TAG>-###` ID as a sibling script testing DIFFERENT behavior, while the corresponding `qa/NN_*.txt` catalog entry only documents ONE of the two — meaning the other was a real, passing script invisible to anyone using `grep -r 'QA-' qa/*.txt` as the index (violating Rule 8: every QA script needs a catalog entry). Investigated each of the 3 named pairs plus a full-tree sweep for others.

**Confirmed and fixed (4 real collisions, all pre-existing, none newly introduced):**

1. **QA-UNDO-010** — `undo_010_ghost_retrigger.sh` ("Ghost text re-triggers after undo") matches the existing catalog entry and kept its ID. `undo_010_redo_stack.sh` ("New edit clears redo stack") was the orphan — renamed to `undo_014_redo_stack_after_second_edit.sh`, ID changed to `QA-UNDO-014`, new catalog entry added to `qa/04_undo_redo.txt`. Noted in that entry: this script is functionally a near-duplicate of the already-cataloged `QA-UNDO-006` ("Redo stack cleared by new edit") with a different fixture — kept as a working script rather than deleted, flagged for a possible future consolidation, not merged here (out of scope for an ID-hygiene pass).

2. **QA-UNDO-011** — `undo_011_reload_clears.sh` (external file modification → Zepto's own change-detection → reload) matches the catalog entry's SETUP ("Modify file externally... Zepto detects and silently reloads") and kept its ID. `undo_011_after_reload.sh` (forces reload via the command palette's "reload" command, a materially different trigger path) was the orphan — renamed to `undo_015_force_reload_command.sh`, ID changed to `QA-UNDO-015`, new catalog entry added.

3. **QA-SBAR-005** — the audit's `sbar_005_*.sh` pair turned out to live in `qa/scripts/tier2/` (vision-judge), not `tier1/` as named in the original finding — filenames in the finding weren't exact, matching the finding's own caveat. `sbar_005_toggle_pills.sh`'s own header/`qa_header` text ("Status bar toggle pills (visual)") is close to verbatim the catalog NAME ("Toggle pills show ON/OFF visually") and kept its ID. `sbar_005_wrap_active.sh` (a narrower single-state "is the Wrap pill highlighted" check) was the orphan — renamed to `sbar_023_wrap_active.sh`, ID changed to `QA-SBAR-023` (next unused SBAR id), new catalog entry added to `qa/26_status_bar.txt`.

4. **QA-MD-009** (found in the full-tree sweep, not one of the 3 originally named pairs) — `md_012_dim_delimiters.sh`'s content matches the catalog's `QA-MD-009` ("Dim emphasis delimiters") essentially word-for-word and kept its ID (its filename says "012" but that's now a pre-existing, out-of-scope naming quirk — `QA-MD-012` already legitimately belongs to `reg_175_image_spacer_bg.sh` in the catalog, unrelated to either script in this pair; renaming the *file* of the correctly-ID'd script was left alone per the "only fix the orphan" rule). `md_009_code_inline.sh` (checks inline-code/heading color distinctness — unrelated to emphasis-delimiter dimming) was the orphan — renamed to `md_013_code_inline.sh`, ID changed to `QA-MD-013` (next unused MD id), new catalog entry added to `qa/33_markdown_rendering.txt`.

**Investigated and confirmed NOT a real collision (false positive, left untouched):** the full-tree sweep's `grep -m1 -oh 'QA-[A-Z]*-[0-9]*'` matched `QA-PREF-015` in `qa/scripts/tier1/sess_009_toggle_pref.sh` too — but that script's header comment reads `# QA-SESS-009 / QA-PREF-015: ...` as an explicit RELATED cross-reference (its `qa_header` call, the thing that actually names the script's own identity, says only `QA-SESS-009`), not a second self-claim. `QA-SESS-009` doesn't collide with anything else and matches its own catalog entry in `qa/02_startup_and_quit.txt`. No action needed — this is exactly the "legitimate RELATED cross-ref, not a true collision" case the audit's own caveat called out.

**Verification (all via `hangon`, actual script runs, not read-throughs):** all 6 touched scripts (3 kept + 3 renumbered) run end-to-end and PASS under their final, distinct IDs — `undo_010_ghost_retrigger.sh` (QA-UNDO-010), `undo_014_redo_stack_after_second_edit.sh` (QA-UNDO-014), `undo_011_reload_clears.sh` (QA-UNDO-011), `undo_015_force_reload_command.sh` (QA-UNDO-015), `md_012_dim_delimiters.sh` (QA-MD-009), `md_013_code_inline.sh` (QA-MD-013). The two `sbar_005`/`sbar_023` tier2 scripts both currently FAIL — see the separate finding immediately below; this is a pre-existing vision-judge issue confirmed unrelated to the ID rename (diffed the pre/post-rename script content: only the ID string and tmpfile basename changed, assertion logic and screenshot steps are byte-identical). `make check`/`make build`/`make test` clean (1298 tests). No duplicate `^ID:` lines remain across any `qa/*.txt` catalog file, and no script-level ID collision remains across `qa/scripts/tier1/*.sh` + `qa/scripts/tier2/*.sh` (re-swept after the fix).

**Not fixed / out of scope:** the `md_012_dim_delimiters.sh` filename vs. its actual `QA-MD-009` ID (a confusing but harmless naming leftover, not an ID collision); the `QA-UNDO-014` vs. `QA-UNDO-006` behavioral near-duplication (flagged above, not merged/retired).

### P3: [QA Infra] `sbar_005_toggle_pills.sh` / `sbar_023_wrap_active.sh` (tier2 vision-judge) FAIL at default 80-col width — confirmed false positive, not a real rendering bug

While verifying the ID-collision fix above (see the entry immediately above this one), both `qa/scripts/tier2/sbar_005_toggle_pills.sh` (QA-SBAR-005) and the newly-renumbered `sbar_023_wrap_active.sh` (QA-SBAR-023) FAILed their vision-judge assertion ("no Wrap pill is visible") when run via `hangon` at the default terminal width. Manually launched a session at the same default width and inspected both a `hangon screen` text dump and a `hangon screenshot` PNG: the Wrap pill IS present and correctly rendered — it's in the documented "compact form" (icon + `⌥Z` key only, no "Wrap" text label), which is expected, deliberate behavior at 80 cols per the already-cataloged `QA-SBAR-016`/`QA-SBAR-020`/`QA-SBAR-021` (compact pills drop their label text but keep icon+key and the color-based on/off state). The vision-judge prompts in both scripts assume a labeled "Wrap" pill and don't account for the compact form, so they FAIL on a correctly-behaving screen. This is exactly the "trust but verify" pattern `qa/README.md` already documents for tier2 — traced to a prompt-wording issue in the test scripts, not a product bug; no `bugs.md` P0-P2 entry warranted, no application code touched. Not fixed in this pass (out of scope for an ID-hygiene task — fixing the prompt wording is a content change to two tier2 scripts, left for a dedicated follow-up); logged per Rule 6 so it doesn't get mistaken for a rendering regression by a future run of `make qa-visual`.

Found while auditing all cross-module `Zepto::Renderer::` call sites for the WrapMap doc-accuracy fix above. `Editor.pm:5189` (inside the image-tab sizing logic that fits a Kitty-graphics-protocol image preview to the available viewport) calls `Zepto::Renderer::_get_image_dimensions($image_path)` — the leading underscore marks it private-by-convention per `docs/CODE_QUALITY.md`'s "Naming" section, same convention that made the now-fixed `WrapMap.pm` → `_expand_tabs()`/`_char_to_visual_col()` calls a flagged layering violation (see the `~~P3: WrapMap.pm reaches into Renderer.pm's private functions~~ FIXED` entry above). This is the same class of problem, just in `Editor.pm` instead of `WrapMap.pm`, and it was not touched by that fix (which only repointed WrapMap's 3 call sites). `_get_image_dimensions()` is defined at `Renderer.pm:1679` (line number shifted from `1659` since this entry was logged) with no public wrapper.

**FIXED** in the exact pattern predicted above: added a thin no-underscore wrapper `get_image_dimensions()` to `Renderer.pm` (immediately after `char_to_visual_col()`, `Renderer.pm:490-503`) that just forwards args — `return _get_image_dimensions(@_);` — mirroring `expand_tabs()`/`char_to_visual_col()`'s doc-comment style exactly. Repointed `Editor.pm:5189` at the new public wrapper. Confirmed via `grep -rn "_get_image_dimensions" lib/` that the only other caller of the private function is `Renderer.pm:1821` itself (same-module call, not a layering violation, left untouched).

Verified pure behavioral no-op several ways, mirroring the WrapMap fix's own verification approach: (1) a direct equivalence check — `perl -Ilib -MZepto::Renderer` calling both `_get_image_dimensions($path)` and `get_image_dimensions($path)` on the same generated 200×100 PNG returned identical `(200, 100)` from both; (2) added `tests/renderer.t`'s "Public get_image_dimensions() wrapper matches the private function exactly" subtest (mirroring the WrapMap fix's own "Public expand_tabs()/char_to_visual_col() wrappers match the private functions exactly" subtest) — compares public vs. private output for a real 1×1 PNG fixture (width, height) and for a missing-file failure case (empty-list return); per Rule 5, mutation-tested by temporarily replacing the wrapper's body with a hardcoded wrong return (`(999, 888)`), confirming all 3 new assertions failed, then restoring the real fix and confirming all 3 passed again; (3) `tests/renderer.t`'s pre-existing `_get_image_dimensions` subtests (which call the private function directly and were untouched) all still pass unchanged; (4) `make test` is green (1299/1299 — one `find_engine_perf.t` "Background search - tick respects time budget" timing flake seen on two separate runs, confirmed unrelated: it passes 15/15 in isolation, the full suite passed clean on immediate rerun both times, and this fix touches no code find_engine_perf.t exercises). Interactive `hangon` check: opened both a markdown file referencing an image and the PNG file directly as an image tab — editor renders and responds normally, no crash, clean `ctrl-q` exit; the Kitty-graphics overlay itself isn't visible in a tmux/hangon text capture (needs a real Kitty-protocol terminal, `Terminal.pm:854`'s `supports_kitty_graphics()` gate), a known limitation of this test environment unrelated to this change. No QA-REG entry or changelog line added — pure internal refactor, zero behavior change, no user-visible surface, matching the WrapMap fix's own precedent exactly (that fix's changelog entries were only for its two *behavior-affecting* sibling fixes in the same commit — tab-expansion caching and StateStore debounce — not for the layering-violation fix itself, which got no changelog line; and the layering fix got no QA-REG entry either, since there was no bug to regression-guard, only a layering violation to close, confirmed by inspecting commit `9b88233`'s actual diff).