diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 634ad45..acc4122 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -17,10 +17,12 @@ Both ends of that wiring sit in named functions outside `runTUI` — `newRootMod
 and `restartIfRequested(final, restart)` — because `runTUI` needs a terminal and cannot be
 tested, and those two lines are the whole path from the model logic to the user.
 
-Three areas carry more rationale than fits here — updating a tool, self-update, and panel
-`[3]`'s README pipeline. Their full text lives under `docs/design/`:
-[`updating.md`](docs/design/updating.md), [`self-update.md`](docs/design/self-update.md)
-and [`readme-pipeline.md`](docs/design/readme-pipeline.md).
+Four areas carry more rationale than fits here — updating a tool, self-update, panel
+`[3]`'s README pipeline, and running a tool in the embedded terminal. Their full text
+lives under `docs/design/`: [`updating.md`](docs/design/updating.md),
+[`self-update.md`](docs/design/self-update.md),
+[`readme-pipeline.md`](docs/design/readme-pipeline.md) and
+[`tool-overlay.md`](docs/design/tool-overlay.md).
 
 ## Package map
 
@@ -34,7 +36,7 @@ graph TD
     model[internal/model] --> loader[internal/loader]
     model --> version[internal/version]
     model --> updater[internal/updater]
-    model --> launcher[internal/launcher]
+    model --> term[internal/term]
     model --> ui[internal/ui]
     model --> proc[internal/proc]
     model --> logx
@@ -44,6 +46,7 @@ graph TD
     version --> configdir
     updater --> loader
     updater --> proc
+    term --> proc
     ui --> loader
     loader --> logx
     loader --> configdir
@@ -53,16 +56,16 @@ graph TD
 | Package | Responsibility |
 |---|---|
 | `internal/configdir` | Resolve the base user-config dir: `~/.config/keepkit` on macOS/Linux (`$XDG_CONFIG_HOME` else `~/.config`), `%AppData%\keepkit` on Windows. Pure `baseFor(goos, …)` core + `Base()` wrapper; stdlib-only bottom leaf shared by `loader`/`version`/`logx`/`main` |
-| `internal/launcher` | Decide how to run a tracked tool in a new terminal tab: pure `planFor(env, command, toolName)` → `Plan{Argv, Fallback, Terminal}`, detection chain tmux → iTerm2 → Terminal.app → kitty → WezTerm → fallback; env-only, no subprocesses |
 | `internal/loader` | Tracker persistence (`meta.yaml`), status lifecycle (`active → trying → inactive`, legacy values migrated on read), the one-tag-per-tool invariant (a legacy multi-tag list is truncated to its first entry on read), GitHub ref parsing (`NormalizeRepo`, `ParseToolRef`) |
 | `internal/logx` | Session error journal: errors only, one lazily created file per session, imports only the stdlib-only `configdir` leaf. Package-level state — any package can log without threading a logger through |
 | `internal/model` | The entire Bubble Tea model: TUI state, key handling, rendering |
 | `internal/proc` | `DetachTTY` — run probes without a controlling terminal; `KillGroup` — process-group SIGKILL (plain `Kill` on Windows) |
+| `internal/term` | Run a command on a pseudo-terminal and stream what it prints: `Start(shell, args, w, h, env)` over `x/xpty` (unix ptys, Windows ConPTY), one reader goroutine, `Events() <-chan Event` ending in a single `Exit{Err, Elapsed, Killed}`. A pty read error is never the verdict — `EIO`/EOF/`os.ErrClosed` are all normal termination and `xpty.WaitProcess` decides. Sets `Setsid`+`Setctty` itself (xpty does not), which is why `proc.DetachTTY` must never touch a pty command. No TUI knowledge, no config, no logging |
 | `internal/ui` | `Theme` — the app's ten semantic color roles — and `Styles`, the whole style set built from one theme by `NewStyles`; the two non-role palettes (`LanguageColor`, and `HeadingColors`/`ChromaColors` for panel `[3]`); `PlaceOverlay`, `StripANSI` |
 | `internal/updater` | Detect the package manager that owns an installed binary and produce an update `Plan{Manager, Argv, Display}` |
 | `internal/version` | Detect the installed version locally — `InstalledVersion(t) (ver, present)`; GitHub API with a 24-hour cache; semver comparison (`IsNewer`) and the card's version spelling (`DisplayVersion`); keepkit's own release check (`SelfRepo`, `SelfLatest`) |
 
-`configdir`, `launcher`, `logx`, `proc`, `ui`, `updater` and `version` sit at the bottom of the import graph:
+`configdir`, `logx`, `proc`, `term`, `ui`, `updater` and `version` sit at the bottom of the import graph:
 they know nothing about the TUI (`ui`, `updater` and `version` reach only into
 `loader`/`proc`/`logx`). `configdir` is the lowest leaf (stdlib only), shared by
 `loader`/`version`/`logx`/`main` for one config-dir resolution. GitHub ref parsing
@@ -74,6 +77,7 @@ The `model` package is split across files within a single package:
 |---|---|
 | `model.go` | The `Model` struct, message types, `New`/`Init`/`Update`, selection and filtering helpers (`selectMeta`, `setFocus`, `searchMatches`, `filteredMeta`, `indexOfMeta`, `setHelpContent`) |
 | `mode.go` | The `inputMode` enum and a handler per input mode |
+| `overlay_term.go` | The embedded tool terminal: the pty session interface, its messages and commands, the input relay, key translation, geometry and the frame renderer |
 | `commands.go` | All `tea.Cmd` constructors (fetch commands, update streaming) and re-fetch predicates |
 | `render.go` | `View`, panel/card/status-bar/gauge/overlay renderers, mouse handling. The two list/card builders return their line index alongside the text: `buildCard` → clickable lines, `buildToolRows` → the tool-index ↔ screen-line maps. Carries the single-entry `changelogRenderCache` — the card is rebuilt on every spinner frame, so the release-notes conversion must not repeat |
 | `readme.go` | `renderReadme` — panel `[3]`'s pipeline: sanitize → preprocess → glamour, with a single-entry render cache; `chromaFormatterFor` maps the color profile onto chroma's formatter so a code fence's plate is not quantized away from the card's |
@@ -191,9 +195,10 @@ no focus and fetches nothing (see the layout invariant below). Focus moves with
 `1`/`2`/`3`, or a mouse click; everything goes through `setFocus(f)`, which repaints
 the tools list — the only viewport whose content depends on focus.
 
-All modal state is a single field `m.mode inputMode` (12 values: `modeNormal`, `modeSearch`,
+All modal state is a single field `m.mode inputMode` (13 values: `modeNormal`, `modeSearch`,
 `modeEditNote`, `modeEditTags`, `modeTrack`, `modeConfirmUntrack`, `modeRename`,
-`modeRunInput`, `modeConfirmUpdate`, `modeAPIStatus`, `modeTokenInput`, `modeHotkeys`). Exactly one mode is active at
+`modeRunInput`, `modeConfirmUpdate`, `modeAPIStatus`, `modeTokenInput`, `modeHotkeys`,
+`modeToolOverlay`). Exactly one mode is active at
 a time; `Update()` dispatches via `switch m.mode`, so keys that open other modes
 structurally cannot fire inside another mode's input.
 
@@ -345,7 +350,7 @@ path). Detection spawns subprocesses, so it runs as a `tea.Cmd`, never inside
 
 Five steps are path-convention based (cargo, pipx, uv, pnpm, bun) and take their
 roots from `managerDirsFrom(getenv, home, goos)` (pure core, `resolveManagerDirs()`
-wrapper — the `launcher.planFor` idiom): `$UV_TOOL_DIR`, `$PNPM_HOME` and
+wrapper — the `configdir.baseFor` idiom): `$UV_TOOL_DIR`, `$PNPM_HOME` and
 `$BUN_INSTALL` with per-platform defaults, plus home-derived `~/.cargo/bin` and
 `~/.local/pipx/venvs` (no `$CARGO_HOME`/`$PIPX_HOME` — unchanged behaviour, and a
 separate question from path resolution). Carrying all five is what lets
@@ -469,26 +474,32 @@ succeed).
 ## Running a tool (`enter`)
 
 `enter` in `[1] Tools` opens a one-line prompt (prefilled with the last command
-dispatched for the tool this session, else the tool name) and launches the
-command. `launcher.Detect` picks the path from the environment alone — no
-subprocesses, so unlike every probe it is safe inside `Update()`. A tab plan
-runs its argv as a `tea.Cmd` through `proc.DetachTTY` with a 10-second ceiling
-(`proc.KillGroup` on the process group when it fires — mostly for osascript
-blocked on the macOS Automation dialog); a `Fallback` plan — terminals with no
-scripting API, and native Windows — runs the command in the current window via
-`tea.ExecProcess` (`sh -c` / `cmd /c`): keepkit suspends and resumes when the
-tool exits.
-
-An adapter failure **auto-falls back** to `tea.ExecProcess`, so the tool still
-launches — but only from `modeNormal`: the result can arrive seconds after
-enter, and seizing the terminal under an open editor or overlay would send the
-user's keystrokes to the spawned shell. Under any other mode the fallback is
-deferred, not dropped: it fires — with a visible status message — on the
-keystroke that closes the mode, going straight to the exec fallback (the
-failing adapter plan is never re-run). One adapter launch runs at a time (`m.launchingFor`, the
-launch twin of `updatingFor`). Working directories differ by path: a tab opens
-in the new shell's default cwd, the fallback inherits keepkit's. A non-zero
-exit of the tool itself is a status message only — never logged.
+dispatched for the tool this session, else the tool name) and runs the command
+on a **pseudo-terminal inside keepkit** — a bordered block over the dimmed
+layout, with the whole keyboard handed to the tool. One path for everything: a
+TUI draws and lives in it, a plain CLI prints and exits and its final screen
+stays until `esc`.
+
+`internal/term` owns the pty and one reader goroutine; the VT emulator lives on
+the model, so only `Update` ever touches its screen state. While the tool runs
+every key is forwarded — `esc` and `ctrl+c` included, because `esc` is what
+makes vim usable and `ctrl+c` is the tool's interrupt. `ctrl+\` is the one
+reserved chord: it kills the process group and stays in the mode, since the
+outcome line arrives with the exit. Afterwards `esc` closes and nothing else
+does anything.
+
+The block is 70% of the screen with its exit row reserved from the start and
+every row padded to the body width, so it never moves when the tool finishes. A
+screen too small refuses the keypress and remembers nothing; a terminal shrunk
+mid-session clamps to the floor and keeps the tool running. The working
+directory is keepkit's. A non-zero exit of the tool itself is shown in the exit
+row — never logged.
+
+This replaced a tab launcher that scripted other terminals (tmux, iTerm2,
+Terminal.app, kitty, WezTerm) into opening a tab, plus the `tea.ExecProcess`
+fallback and the deferred-fallback machinery that existed to survive an adapter
+failing. Full rationale, including the upstream races it works around, in
+[`docs/design/tool-overlay.md`](docs/design/tool-overlay.md).
 
 ## GitHub API
 
@@ -578,8 +589,8 @@ leaves no file, so the presence of a file is itself the signal. The filename car
 colon-free zero-padded timestamp: lexicographic order equals chronological order,
 which is what `Cleanup()` relies on (the 20 most recent are kept). `logx.Recover` is
 hooked deeper than Bubble Tea's own recover (inside `Update`, `View` and every
-command via `safeCmd`; `execToolCmd` is the one unwrapped cmd — `tea.ExecProcess`
-only constructs the exec message, nothing there can panic): it records the panic
+command via `safeCmd`; the one unwrapped cmd is `handleTermChunk`'s exit
+re-emit, a closure returning a prebuilt value that cannot panic): it records the panic
 with a stack trace and **re-panics** so
 Bubble Tea restores the terminal correctly. The logger's own failures are swallowed
 silently.
diff --git a/CLAUDE.md b/CLAUDE.md
index 42b5fbb..3df0d48 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,32 +19,33 @@ CI (`.github/workflows/ci.yml`) runs build / vet / `test -race` / golangci-lint
 
 **`keepkit`** is a terminal TUI tracker for CLI tools built with Bubble Tea. It is a pure TUI app — running `keepkit` launches the interface directly; the only CLI surface is `--version`/`--help`.
 
-**Deep design docs.** Three features carry more rationale than belongs in a file loaded on every session, so their full text lives under `docs/design/` and this file keeps the invariants plus a link. **Read the linked file before changing anything in its area** — each one records what already broke once and why the current shape is the way it is:
+**Deep design docs.** Four features carry more rationale than belongs in a file loaded on every session, so their full text lives under `docs/design/` and this file keeps the invariants plus a link. **Read the linked file before changing anything in its area** — each one records what already broke once and why the current shape is the way it is:
 
 | File | Covers |
 |---|---|
 | [`docs/design/updating.md`](docs/design/updating.md) | `enter` in `[2]`: `updater.Detect`'s manager chain, the confirm dialog, the streaming update log |
 | [`docs/design/self-update.md`](docs/design/self-update.md) | `U`/`X`: the version gate, `selfState`, the restart and its path resolution |
 | [`docs/design/readme-pipeline.md`](docs/design/readme-pipeline.md) | panel `[3]`: the three sources, `cleanReadmeMarkdown`, the glamour theme |
+| [`docs/design/tool-overlay.md`](docs/design/tool-overlay.md) | `enter` in `[1]`: the embedded pty, the Update-only emulator rule, key translation, `ctrl+\`, the geometry |
 
-Everything else stays here. **Never re-inline these three sections.** When a change makes one of them wrong, fix it in its own file, and touch this one only when the invariant summary itself went wrong — the split is the layout, not drift.
+Everything else stays here. **Never re-inline these four sections.** When a change makes one of them wrong, fix it in its own file, and touch this one only when the invariant summary itself went wrong — the split is the layout, not drift.
 
 ### Entry point
 
 `main.go` is a thin launcher: it loads tracker metadata via `loader.LoadMeta()` and starts the Bubble Tea TUI with `model.New(meta).WithAppVersion(ver)` — the running binary's own version, which is what the self-check compares against keepkit's latest release and the gate that switches that whole feature off on a dev build (see **Self-update** below). Before that, `handleCLI` answers `--version`/`-V`/`-v`/`version` (prints `keepkit <version>` — dotted-numeric on release/`go install` builds, so `version.InstalledVersion`'s regex parses it and a keepkit tracked inside keepkit shows as installed) and `--help`/`-h`/`help` (static usage text); **any other argument exits 2 with usage on stderr** — falling through to the TUI is what used to make a probed keepkit boot Bubble Tea on a detached TTY, fail with `could not open a new TTY`, and litter `logs/` with junk session files. There are no other subcommands or flags.
 
-`runTUI` keeps the model `p.Run()` returns (it used to discard it) for one reason: `RestartRequested()` is how `[U] restart` after a self-update reaches `restartSelf()`. `runTUI` itself opens a Bubble Tea program on a TTY and cannot be tested, so — the same pure-core-plus-thin-wrapper split as `shellCommand`/`planFor`/`resolveSelfPath` — the two lines that carry the whole self-update feature from the model to the user live outside it: **`newRootModel(meta, ver)`** (the `model.New(meta).WithAppVersion(ver)` wiring, without which every shipped binary would silently have no self-check, no banner and no restart offer) and **`restartIfRequested(final, restart)`** (the post-`p.Run()` decision, with the restart function injected exactly like `restartSelfWith`'s `execve`). Both had zero coverage until a review mutation showed the full suite staying green with each of them removed; `TestNewRootModelInjectsAppVersion` (counts `Init`'s batch — a release version queues one command more than a dev one) and `TestRestartIfRequested` are what kill those mutations now, and deleting the `restartIfRequested` call from `runTUI` is a compile error because `final` would go unused. `restartIfRequested` asserts on a local **`restarter` interface**, not on `model.Model`: the flag is only reachable through unexported state, so a stand-in is the only way to exercise the true branch — the package-level `var _ restarter = model.Model{}` is what keeps the real model bound to it. Still uncovered in `main.go` and known to be so: `buildVersion()` (its pure `resolveVersion` core is tested, the `debug.ReadBuildInfo` wrapper is not), the `logx.SetHeader` format strings, `migrateConfigDir` and `main`'s own `handleCLI` dispatch. The root package carries three more files for the restart, and each one's build tag matches where its code is actually reachable: `restart.go` — **only** the shared `restartHint` const, the one thing both platforms use; `restart_unix.go` (`//go:build !windows`) — `restartSelf`/`restartSelfWith` (`syscall.Exec` over `os.Args`/`os.Environ()`) plus the pure `resolveSelfPath` core and its `selfPath()`/`fileExists` wrappers, all of which the Windows build never calls; `restart_windows.go` — the honest degradation (print the hint, exit). Keeping the path core out of the untagged file is why `unused` no longer depends on a test to see it referenced.
+`runTUI` keeps the model `p.Run()` returns (it used to discard it) for one reason: `RestartRequested()` is how `[U] restart` after a self-update reaches `restartSelf()`. `runTUI` itself opens a Bubble Tea program on a TTY and cannot be tested, so — the same pure-core-plus-thin-wrapper split as `shellCommand`/`baseFor`/`resolveSelfPath` — the two lines that carry the whole self-update feature from the model to the user live outside it: **`newRootModel(meta, ver)`** (the `model.New(meta).WithAppVersion(ver)` wiring, without which every shipped binary would silently have no self-check, no banner and no restart offer) and **`restartIfRequested(final, restart)`** (the post-`p.Run()` decision, with the restart function injected exactly like `restartSelfWith`'s `execve`). Both had zero coverage until a review mutation showed the full suite staying green with each of them removed; `TestNewRootModelInjectsAppVersion` (counts `Init`'s batch — a release version queues one command more than a dev one) and `TestRestartIfRequested` are what kill those mutations now, and deleting the `restartIfRequested` call from `runTUI` is a compile error because `final` would go unused. `restartIfRequested` asserts on a local **`restarter` interface**, not on `model.Model`: the flag is only reachable through unexported state, so a stand-in is the only way to exercise the true branch — the package-level `var _ restarter = model.Model{}` is what keeps the real model bound to it. Still uncovered in `main.go` and known to be so: `buildVersion()` (its pure `resolveVersion` core is tested, the `debug.ReadBuildInfo` wrapper is not), the `logx.SetHeader` format strings, `migrateConfigDir` and `main`'s own `handleCLI` dispatch. The root package carries three more files for the restart, and each one's build tag matches where its code is actually reachable: `restart.go` — **only** the shared `restartHint` const, the one thing both platforms use; `restart_unix.go` (`//go:build !windows`) — `restartSelf`/`restartSelfWith` (`syscall.Exec` over `os.Args`/`os.Environ()`) plus the pure `resolveSelfPath` core and its `selfPath()`/`fileExists` wrappers, all of which the Windows build never calls; `restart_windows.go` — the honest degradation (print the hint, exit). Keeping the path core out of the untagged file is why `unused` no longer depends on a test to see it referenced.
 
 ### Package overview
 
 | Package | Purpose |
 |---|---|
-| `internal/configdir` | Resolve keepkit's base user-config dir (parent of the `keepkit/` subdir holding `meta.yaml`, `cache.json`, `token`, `logs/`). Pure `baseFor(goos, getenv, userConfigDir, userHomeDir)` core + thin `Base()` wrapper (the `shellCommand`/`planFor` idiom). **Windows** → `os.UserConfigDir()` (`%AppData%`); **macOS and Linux** → `$XDG_CONFIG_HOME` else `~/.config` — deliberately *not* `os.UserConfigDir()`, which is `~/Library/Application Support` on macOS. The **bottom leaf of the import graph** (stdlib only), so `loader`/`version`/`logx`/`main` all share one resolution without a cycle |
-| `internal/launcher` | Decide how to run a tracked tool in a new terminal tab: pure `planFor(env, command, toolName)` over an injected env lookup → `Plan{Argv, Fallback, Terminal}`, thin `Detect` wrapper over `os.Getenv`. Detection chain (first hit wins): `$TMUX` → iTerm2 → Terminal.app → kitty → WezTerm → `Fallback: true` (no scripting API — run in the current window). `$TMUX` is deliberately first: inside tmux `TERM_PROGRAM` names the *outer* terminal and a tmux window is the correct "tab" there. Terminal.app opens a **window**, not a tab (tabs aren't scriptable without System Events — honest degradation). tmux/kitty/wezterm plans carry command and tool name as argv elements (no escaping; the tmux plan puts `--` before the command so a `-`-leading edit isn't eaten as a flag); the two osascript plans interpolate into script source through `appleScriptQuote` (backslashes, then double quotes, then `\n`/`\r`/`\t` — the control characters an AppleScript literal cannot carry raw), the single escaping point. The kitty plan needs a remote-control socket (`listen_on` → `KITTY_LISTEN_ON`): the adapter runs detached, so tty-transport remote control cannot work — without the socket it degrades to the auto-fallback. Env-only — no subprocesses — so `Detect` is safe inside `Update()`. Bottom of the import graph like `updater`: no TUI knowledge |
+| `internal/configdir` | Resolve keepkit's base user-config dir (parent of the `keepkit/` subdir holding `meta.yaml`, `cache.json`, `token`, `logs/`). Pure `baseFor(goos, getenv, userConfigDir, userHomeDir)` core + thin `Base()` wrapper (the `shellCommand` idiom). **Windows** → `os.UserConfigDir()` (`%AppData%`); **macOS and Linux** → `$XDG_CONFIG_HOME` else `~/.config` — deliberately *not* `os.UserConfigDir()`, which is `~/Library/Application Support` on macOS. The **bottom leaf of the import graph** (stdlib only), so `loader`/`version`/`logx`/`main` all share one resolution without a cycle |
 | `internal/loader` | Persist tracker metadata (`meta.yaml`: name, status, tag, note, github ref, optional `update_cmd` override); own the tool-status lifecycle (`active → trying → inactive` via `NextStatus`; legacy `forgotten`/`archived` values are migrated to `inactive` in `LoadMeta` — in-memory, the file keeps the old value until the next `SaveMeta`); hold the **one tag per tool** invariant (`Tags` stays a `[]string` so the yaml schema is unchanged, but `LoadMeta` truncates a legacy multi-tag list to `Tags[:1]` in the same migration loop — first tag wins, matching what the editor's `parseTag` does to comma-separated input. Unlike the status migration, which swaps a retired value for its successor, this one **discards user-authored data** and the next `SaveMeta` — any note edit or status cycle — makes it permanent, so a load that actually dropped tags stashes the pre-migration file as `meta.yaml.bak` first: best-effort, logged and swallowed on failure, and not rewritten by later already-migrated loads); parse GitHub refs (`NormalizeRepo`, `ParseToolRef` in `github.go`) |
 | `internal/logx` | Errors-only session logger (imports only the stdlib-only `configdir` leaf); one lazily-created plain-text file per session under `<configdir.Base>/keepkit/logs`. Package-level state (`mu`/`file`/`path`/`header`), so any package can log without threading a logger through constructors |
 | `internal/model` | Entire Bubble Tea model — all TUI state, key handling, and rendering |
 | `internal/proc` | `DetachTTY` — runs tool probe subprocesses without a controlling terminal (`Setsid` on unix, `DETACHED_PROCESS` on Windows); `KillGroup` — process-group SIGKILL (negative pid; plain `Process.Kill` on Windows) for the update streamer's timeout path |
+| `internal/term` | Run a command on a pseudo-terminal and stream what it prints — the architectural slot `internal/launcher` vacated: bottom of the import graph, no TUI knowledge. `Start(shell, args, w, h, env)` creates the pty (`x/xpty`: unix ptys via creack/pty, Windows **ConPTY**) and one reader goroutine; everything it observes leaves through `Events() <-chan Event` — zero or more `Data`, then exactly one `Exit{Err, Elapsed, Killed}`, then close — so the model consumes it with the update streamer's `waitForChunkCmd` pattern. The channel is buffered (64) so the reader stays ahead of a once-per-message consumer; past it the child is throttled, which is the correct back-pressure. **A pty read error is never the verdict** (`EIO` on Linux, EOF on macOS, `os.ErrClosed` after a Kill — all normal termination): it comes from `xpty.WaitProcess`, which also synthesises the `*exec.ExitError` `os.Process.Wait` fails to produce on ConPTY. `Elapsed`/`Killed` are stamped in the goroutine, never by the consumer. **xpty sets neither `Setsid` nor `Setctty`** — its `Start` only wires stdio — so this package sets them itself on the unix build, which is also why **`proc.DetachTTY` must never touch the pty command**: it assigns `SysProcAttr` wholesale and would drop them. `Setsid` is what makes `proc.KillGroup`'s negative-pid signal reach an `sh -c` line's grandchildren. The caller builds argv (the model's `shellCommand`), keeping this package goos-agnostic. No config paths, no `logx` — failures ride `Exit.Err` — hence no `TestMain` seam |
 | `internal/ui` | `Theme` (theme.go) — the app's ten semantic color roles plus the gauge's dim track — and `Styles` (styles.go), every lipgloss style keepkit renders with, built from one theme by the single `NewStyles(Theme)`. `DefaultStyles()` is the fallback for a `Model{}` literal and nothing else. **Two** palettes here are **not** theme roles and must not follow a theme switch, and they are exceptions for different reasons: `LanguageColor` (lang.go) is linguist's per-language brand marks, keyed case-folded, `(color, false)` for a language it does not know — somebody else's colors, so keepkit may not restyle them; `HeadingColors`/`ChromaColors` (readme_palette.go) are keepkit-*invented* shades for panel `[3]`'s heading ladder and code-fence accents, a contained exception to "color is a role, not a shade" taken because a heading *level* is not a meaning `Theme` has a word for and six levels cannot be six meanings. The consequence is stated in all three of theme.go, readme_palette.go and `keepkitStyle`: a theme switch repaints `[3]`'s body, links, quotes and inline code and **not** H1–H5 or the fence accents. `HeadingColors` **descends** — bright H1 to dark H5 — and `TestHeadingColorsDescend` pins that direction, because reordering it is a one-line edit that breaks nothing else. Plus `PlaceOverlay` (which takes the dim style rather than reading a package var) and `StripANSI` |
 | `internal/updater` | Detect the package manager that owns an installed binary and produce an update `Plan{Manager, Argv, Display}` (brew → go → cargo → pipx → uv → pnpm → bun → npm chain; `update_cmd` override always wins; on a `LookPath` miss **or an exhausted chain**, a brew-by-name fallback before giving up — see [`docs/design/updating.md`](docs/design/updating.md)). Bottom of the import graph like `version`: no TUI knowledge, depends only on `loader` for `Tool`. Pure `detectFromPath`/`brewNamePlanAt`/`managerDirsFrom`/`pnpmShimTarget` cores + OS-facing `Detect`/`brewNamePlan`/`resolveManagerDirs`/`readPnpmShim` wrappers, plus the wrapper-less goos-parameterized `customPlan(goos, cmd)` (`update_cmd` → `sh -c`, `cmd /c` on Windows so a winget/PowerShell command needs no Git Bash) — **a deliberate duplicate of `model.shellCommand`** for `testBrewPrefix`'s reason (`updater` sits below `model` and may not import it); the cross-reference comments on both copies are the only drift guard, and both carry the same accepted caveat — Go's argv quoting is not cmd.exe-aware, so an `update_cmd` embedding double quotes can misparse under `cmd /c`. Seams: `testHomeDir`, `testBrewPrefix` (a deliberate duplicate of `version`'s — two bottom leaves that may not import each other) and `testGOOS`, which exists because **CI runs `go test` on linux only** (the Windows job cross-compiles), so an expectation derived from `runtime.GOOS` asserts nothing about the Windows branch — `TestDetectUpdateCmdOverride` drives the seam per row and is what catches `Detect` passing a literal goos, the regression this package shipped once |
 | `internal/version` | Detect installed version locally — `InstalledVersion(t) (ver string, present bool)`, the two results independent so the card can tell "installed but won't say its version" from "not installed". Sources in order: `--version`/`-V`, then `brewDirVersion` in `brew.go` (reads the version from the `Caskroom/<name>`/`Cellar/<name>` directory names — no brew subprocess — so casks with no version CLI still resolve), then `cargoListVersion`/`cargoVersionFromList` (same idea one ecosystem over: `cargo install --list` names every cargo-installed crate's version without running its binary; gated on the binary existing, and `LookPath("cargo")` short-circuits before any subprocess). A fallback hit suppresses the anomaly log; `testBrewPrefix` seam. Also: fetch latest release, repo card, changelog and README from the GitHub API with a 24h cache; semver comparison (`IsNewer`) and the card's version spelling (`DisplayVersion`); keepkit's own self-check (`selfcheck.go`: `SelfRepo`, `SelfLatest`) |
@@ -54,8 +55,9 @@ The `model` package is split by responsibility (one package, several files):
 | File | Contents |
 |---|---|
 | `model.go` | `Model` struct, msg types, `New`, `Init`, `Update` dispatch, selection/filter helpers |
-| `mode.go` | `inputMode` enum + per-mode key handlers (`updateNoteEdit`, `updateTagsEdit`, `updateTrackInput`, `updateUntrackConfirm`, `updateRenameInput`, `updateRunInput`, `updateAPIStatus`, `updateConfirmUpdate`, `updateHotkeys`) and the pure `trackTool`/`renameTool` |
-| `commands.go` | Every `tea.Cmd` constructor (`fetchInstalledCmd`, `remoteCmd`, `fetchRateCmd`, `selfCheckCmd`, `changelogCmd`, `fetchHelpCmd`, `readmeCmd`/`fetchReadmeCmd`/`refreshReadmeCmd`, `validateTokenCmd`, `detectUpdateCmd(t, self)` (one command for `enter` and `[U]` — the flag only tags the message), `startUpdateCmd`, `waitForChunkCmd`, `startLaunchCmd`, `execToolCmd` + the pure per-GOOS `shellCommand`) + fetch predicates (`needsInstalled`, `needsRemote`, `needsReadme`, `refreshSelectedCmd`, `autoFetchCmdsForSelected`) |
+| `mode.go` | `inputMode` enum + per-mode key handlers (`updateNoteEdit`, `updateTagsEdit`, `updateTrackInput`, `updateUntrackConfirm`, `updateRenameInput`, `updateRunInput`, `updateAPIStatus`, `updateConfirmUpdate`, `updateHotkeys`) and the pure `trackTool`/`renameTool`. `updateToolOverlay` and its key translation live in `overlay_term.go` |
+| `overlay_term.go` | The embedded tool terminal (`modeToolOverlay`): the `termSession` narrow interface, the `termStarted`/`termChunk`/`termExit` messages, `startTermCmd`/`waitForTermChunkCmd`, the `termInput` relay and its lifecycle, `updateToolOverlay` + key translation, `termGeometry` and the frame renderer |
+| `commands.go` | Every `tea.Cmd` constructor (`fetchInstalledCmd`, `remoteCmd`, `fetchRateCmd`, `selfCheckCmd`, `changelogCmd`, `fetchHelpCmd`, `readmeCmd`/`fetchReadmeCmd`/`refreshReadmeCmd`, `validateTokenCmd`, `detectUpdateCmd(t, self)` (one command for `enter` and `[U]` — the flag only tags the message), `startUpdateCmd`, `waitForChunkCmd` + the pure per-GOOS `shellCommand`, which now builds argv for the tool overlay's pty) + fetch predicates (`needsInstalled`, `needsRemote`, `needsReadme`, `refreshSelectedCmd`, `autoFetchCmdsForSelected`) |
 | `render.go` | `View`, panel/card/status-bar/gauge/overlay renderers, scrollbar, mouse handling |
 | `readme.go` | `renderReadme` — panel `[3]`'s pipeline (sanitize → preprocess → glamour) + the single-entry `readmeRenderCache`; `testReadmeStyle` seam |
 | `readme_clean.go` | `cleanReadmeMarkdown(text, about)` — the pure README preprocessor: fenced-block/inline-span segmentation first, then the image/link/HTML/emoji/shortcode removal rules on what is left, then `rcDropTitleBlock` |
@@ -96,7 +98,7 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
 
 **Tag grouping (`space` in `focusTools`)**: the second list view, off by default (`m.groupByTag`). `m.grouped()` — `groupByTag && searchQuery() == "" && hasTaggedTool()` — is the single "tag view is on" predicate, shared by the ordering and the header rows so they can never disagree; an active `/` search suppresses it, so search behaves exactly as before, and so does a tracker with **no** tagged tool (grouping it would draw one `untagged` divider over the unchanged list — a keypress that reads as broken). `toggleGroupByTag` refuses to turn the view *on* in that state with a `no tags to group by — press [#] on a tool` statusMsg (it named `[t]` until the tag editor moved off that key), but never refuses to turn it **off** — otherwise removing the last tag would strand the user in the tag view; a successful toggle reports `grouped by tag` / `flat list`, the only feedback a view switch has. All three exits route through `setStatus`, so `toggleGroupByTag` returns a `tea.Cmd` (the expiry tick) that the `space` case returns — the message auto-clears after `statusMsgTTL` (see the status-message lifecycle below); a view toggle still fetches nothing. Ordering lives in the same single projection point: `searchMatches()` returns early through `groupMatchesByTag(out)`, which puts tools sharing a tag together (groups in first-appearance order, `meta.yaml` order inside a group, untagged last). The grouping identity is **`tagKey(mt)` — the case-folded tag**, because `matchingTag` already compares case-insensitively and two spellings the search treats as one tag must not split into two sections; the header shows the group's first spelling. Grouping and the update partition are **exclusive** — the partition would break the sections' contiguity — so in the tag view an updatable tool stays in its group and only keeps its ` ↑` marker. **`metaSelected` stays a tool index into `filteredMeta()`**, never a screen row: that is what keeps navigation (`j/k/g/G/PgUp/PgDn/ctrl+d/u`), `selectedMeta()`, `indexOfMeta` and every index-writing site untouched by the feature. The header rows exist only in the two translation points, via maps built by `buildToolRows()` alongside the content — `toolLine[i]` (tool index → screen line) and `lineTool[l]` (screen line → tool index, `-1` on a header), both the identity when grouping is off: `syncToolsViewport` scrolls to `selectedLine()` (**both** branches in screen-line units — mixing units breaks scrolling the moment a header sits above the selection; the upward clamp additionally pulls in a header sitting directly above the selection, or the first group would render as if it had none, with no keyboard way to bring it back), `handleMouse` maps a click row through `toolAtLine()` (a header click selects nothing but still focuses the panel), and the **page/half-page keys step screen lines, not tools** — their step is a viewport-row count, so `PgUp/PgDn/ctrl+f/ctrl+b/ctrl+d/ctrl+u` go through `toolNearLine(selectedLine() ± step, dir)`, which lands on the tool at that line or the next one in the direction of travel. Counting rows as tools would jump past the rows the headers occupied. Both helpers fall back to the identity when the maps are empty, so a hand-built model that never painted the list behaves as it did before. **Every repaint of the list content must go through `setToolsContent()`** — it writes the maps for the content it just rendered, so a bare `SetContent(renderLeftContent())` elsewhere would leave them describing the previous list (the `WindowSizeMsg` handler was exactly that and now routes through it; `TestWindowSizeRebuildsLineMaps` guards it). The toggle itself (`toggleGroupByTag`) reorders `filteredMeta()`, so it uses the same capture-name-then-`indexOfMeta` remap as the async handlers — deliberately not via `selectMeta`, since a pure view toggle must fire no auto-fetch.
 
-**Input modes**: all input/modal state lives in one `m.mode inputMode` field (`mode.go`) — `modeNormal` (base), `modeSearch`, `modeEditNote`, `modeEditTags`, `modeTrack`, `modeConfirmUntrack`, `modeRename`, `modeRunInput`, `modeConfirmUpdate`, `modeAPIStatus`, `modeTokenInput`, `modeHotkeys`. Exactly one mode is active at a time; the `tea.KeyMsg` branch in `Update()` dispatches on `switch m.mode`, so a non-normal mode's handler owns the input and other modes' opening keys cannot fire (the old per-flag guard bugs are structurally impossible). `modeTokenInput` is a sub-state of the API-status overlay: entered from `modeAPIStatus` via `[e]`, esc returns to `modeAPIStatus`, and `apiOverlayVisible()` reports "overlay on screen" for both. `overlayVisible()` is the broader predicate — `apiOverlayVisible() || modeHotkeys` — used by `View()` and the mouse gate to mean "any modal on screen". `refreshingFor`, `helpMode`, `focus` and `selfState` (the self-update banner is non-modal by design — the whole app keeps working under it) are deliberately *not* input modes and stay separate fields.
+**Input modes**: all input/modal state lives in one `m.mode inputMode` field (`mode.go`) — `modeNormal` (base), `modeSearch`, `modeEditNote`, `modeEditTags`, `modeTrack`, `modeConfirmUntrack`, `modeRename`, `modeRunInput`, `modeConfirmUpdate`, `modeAPIStatus`, `modeTokenInput`, `modeHotkeys`, `modeToolOverlay`. Exactly one mode is active at a time; the `tea.KeyMsg` branch in `Update()` dispatches on `switch m.mode`, so a non-normal mode's handler owns the input and other modes' opening keys cannot fire (the old per-flag guard bugs are structurally impossible). `modeTokenInput` is a sub-state of the API-status overlay: entered from `modeAPIStatus` via `[e]`, esc returns to `modeAPIStatus`, and `apiOverlayVisible()` reports "overlay on screen" for both. `overlayVisible()` is the broader predicate — `apiOverlayVisible() || modeHotkeys || modeToolOverlay` — used by `View()` and the mouse gate to mean "any modal on screen". `refreshingFor`, `helpMode`, `focus` and `selfState` (the self-update banner is non-modal by design — the whole app keeps working under it) are deliberately *not* input modes and stay separate fields.
 
 - **Tool-list search (`/` in `focusTools`)** is a commit/rollback transaction over `modeSearch`. `case "/"` captures `m.searchPrevName` (the selected tool's name; empty when the list is empty) before entering the mode, and `filteredMeta()` narrows the list live as the query changes. The predicate is `searchMatches()` (`model.go`): a tool matches when its **name OR its tag** contains the lowercased query (`matchingTag` still iterates the slice — it predates the one-tag invariant and stays correct under it), returning `[]searchMatch{meta, byTagOnly, tag}` so the renderer knows which rows matched only by tag; `filteredMeta()` is a thin projection over it, so all other callers (count, selection, cursor remap) keep seeing plain metas. While searching, the matched name substring renders peach-bold via `highlightNameMatch` (render.go), tag-only rows show the earning tag as a dim `#<tag>` suffix when it fits the row budget without wrapping, and the search status bar shows an `N/M` counter (matches / total tracked) between the query and the hints (a keystroke that changes the query text resets `metaSelected` to 0 — first match highlighted, marker visible during search; pure cursor movement like `left`/`right` keeps a user-moved highlight; that reset repaints `[3]` through **`setHelpContent()`**, not a bare `SetContent(renderHelpContent())`: the readme branch serves `m.helpBase`, which nothing else re-renders, so the cheaper call would leave the *previous* tool's README on screen under the new tool's name — no fetch is fired there, one per keystroke would spend the quota on rows merely typed past). Inside the mode: `↑`/`↓` move the highlight through the filtered list via `selectMeta` (modular wrap, full `j`/`k` parity; **never** forwarded to the textinput, so the query text is untouched — with zero matches they are consumed as no-ops); `enter` commits — exits to `modeNormal`, clears the query, remaps the cursor onto the unfiltered (but still update-grouped) list by name via `indexOfMeta(mt.Name)` — the search filter is gone once the mode is normal, but the update grouping is not, so `indexOfMeta` resolves the **displayed** index — and moves focus to `focusBrief` (no matches → no-op, search stays open); `esc` rolls back — unfiltered list with the cursor restored via `indexOfMeta(m.searchPrevName)` (fallback 0 when that tool was untracked mid-search). Both exits clear `searchPrevName` and go through `selectMeta`, so the help panel is re-synced too (an arrow move may have loaded another tool's help mid-search). `indexOfMeta(name)` lives next to `filteredMeta()` in `model.go`; the status bar echoes the live query plus the `N/M` counter and `[enter] open  [↑/↓] move  [esc] cancel` hints.
 - **Central panel actions (`focusBrief`)** operate on the data the card already shows: **`enter` installs the release the card is offering** (the panel's primary action, and the mirror of `enter`-runs-a-tool in `[1]` — same key, because in both panels it is the thing the user came to that panel to do; see **Update** below), `o` opens the repo in the browser, `c` opens the changelog/releases page, `r` force-refreshes the tool's data, `s` cycles the status (`loader.NextStatus`: `active → trying → inactive`, unknown values fall back to active), `e` edits the note, `#` edits the tool's single tag. **`#` rather than `t`**: `t` is now the global track verb, and a tag editor reachable only from the card is where the tag is shown. `o`/`c` go through `openURLCmd` (resolved per-`GOOS` by `browserCommand`); a tool with no `GitHub` sets `m.statusMsg` instead of launching. `s`/`e`/`#` mutate `m.meta` via `loader.UpsertMeta`, persist with `loader.SaveMeta`, then refresh the card with `m.briefViewport.SetContent(m.renderCard())`. The tags editor commits through `parseTag` (mode.go): the input is **one** tag — everything past the first comma is dropped, so typing `cli, foo` and loading a legacy `[cli, foo]` list both land on `cli` and the editor can never disagree with `LoadMeta`'s `Tags[:1]` migration about a tag's shape. Spaces inside a tag are kept (`dev tools`); empty input clears it to `nil`, which `omitempty` drops from `meta.yaml`. Everything downstream reads the one tag through `tagOf(mt)` rather than joining the slice.
@@ -106,7 +108,7 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
 - **Card metrics strip**: `metricsStrip` is what the card's `[info]` section became — installed / latest / maintenance / stars laid out as **captioned columns on the `Theme.Surface` background** instead of six `label: value` lines whose labels ran down the left edge and pushed every value into a column of its own. Captions are uppercase (`INSTALLED`, `LATEST`, `MAINTENANCE`, `STARS`) because a terminal has no smaller type size to demote a label with, and the values are what the eye should land on. **`installed:` still has four states** and the two version-less ones stay distinct: a resolved version in `Text`, `✓ present` in `Ok` (a tool that is installed but won't name its version — a ratatui app that ignores `--version` — is a working install and reads affirmative), `✕ missing` in `Danger` (the one thing on the card that is actually wrong), and `detecting…` in `Dim` while the local probe is in flight. Both version-less values are **one word**, because the caption above them already says INSTALLED and the sentences they used to be were the only values in the strip too wide for a baseline-width column. `latest:` renders in `SignalBold` with a trailing ` ↑` when `hasUpdate`, otherwise `Text`, and the release date is a **second line under it** rather than a suffix on it. **The values sit at `Text`, one step below the tool's name and one above their own captions**: a terminal has a single font size — the grid belongs to the terminal, not to the app — so the three sizes the design draws in the card's head are three steps of weight and brightness here, and there is room for exactly one peak. Spending the brightest role on four measurements left the name nothing to be the peak of. The two exceptions carry meaning rather than rank: a pending release is one of the screen's three "act on this" points, and a broken install is its one alarm. The header block is separated from the strip by **one** plain blank row — the strip's own padding row is filled with the plate colour and already reads as air, so a second plain row on top of it reads as a hole. Both versions go through **`version.DisplayVersion`**, which puts a `v` in front of a bare version number: a tool's `--version` prints `1.10.2` where its release is tagged `v1.10.2`, and the two used to sit one letter apart for the same binary. It edits nothing else — `canonSemver` decides only *whether* the string is a version number (`nightly`, `cli-2.0` pass through untouched), and its own output is deliberately not what is displayed, since it drops zero-padding, a 4th segment and build metadata. The `\uf412` glyph the two version lines used to carry is gone with the labels that needed disambiguating: a caption says what the number is. A metric with nothing to report is **left out entirely**, so a tool with no GitHub ref shows a one-cell strip rather than three empty captions, and an empty strip is no strip at all. The grid **re-flows rather than truncates**, and it is sized by the widest *value* as well as the widest caption (`need`): sizing on captions alone cut `✕ not installed` to `✕ not insta` at the 80×24 baseline — the default terminal, and the exact state a tracker is opened in. The count is solved against the row the strip actually draws — a blank cell at each end plus a rule between every pair — by counting up while `2 + cols*need + (cols-1)*3` still fits, **not** by dividing `inner` by `need`: that division ignores the overhead, so a 40-cell panel was told it had three columns and then handed each of them 10 cells, cutting `MAINTENANCE` to `MAINTENANC` — the caption the floor exists to protect. At the 80-column baseline the card panel is 27 cells and even two columns need 29, so the grid stands on one; a value longer than any caption costs a column rather than its own legibility. Below `metricStripMinWidth` (`metricMinCol` plus the row's two blank edge cells — measuring against `metricMinCol` alone was two cells short, and a 12-cell panel drew a single 10-cell column) the strip stands down completely, which only a hand-built model reaches since the panel has a 30-cell minimum. **Every row is exactly `inner` cells** — a short row would break the fill into a ragged edge — and every segment carries the background itself for the reason the selected list row does. **Each cell is centered in its column** (odd slack to the right, so a caption and its value can differ by at most one cell in where they start): a caption and the value under it are one measurement, and flush-left hangs them off a rule that is nowhere near either. `TestMetricsStripLayout` pins the width, the caption-over-value reading (via `metricValue`, which identifies a column by the `│` rules around it rather than by the caption's start offset — centered caption and value deliberately do not begin at the same cell), the centering and the re-flow; `TestMetricsStripOmitsUnknowns` pins the omission.
 - **Panel titles**: all three panels inset a title into their top border (`┌─ ▸ [1] tools 27 3↑ ─…─┐`) via the shared `insetPanelTitle` — an ANSI-safe splice over the already-rendered frame (`ui`'s `truncateVisible` is unexported; the helper repaints the border runs from their `stripANSI` text and drops the title in **already styled**). That is what lets one title carry several colors, which the `[1]` counts are the point of: the tracked count in `Dim`, the update count in `Signal` — the tracker's whole reason to exist, so it is the one thing in a panel title that gets the signal color, and it is absent when nothing is behind. A `panelTitle` carries **both** a plain and a styled form: the plain one is what the border arithmetic measures, because escape sequences are not cells, and a title that does not fit is dropped whole (a chopped title reads worse than none). **Focus is marked twice** — by the accent color and by a `▸` prefix — so it survives a monochrome terminal and a reader who cannot separate the two panel colors; `TestPanelTitleFollowsFocus` pins both signals. The titles are lowercase (`[1] tools`, `[2] brief`, `[3] readme` / `[3] help` / `[3] man`, overridden by `[3] update` while a live log shows and by `[3] update finished` / `[3] update failed` once it ended) and double as the documentation for the digit focus hotkeys, so the status bar carries no digit hints. `[3]` additionally names **the two sources it is not showing** (`· h help · m man`) in the border color: those keys switch what the panel *is*, which is a property of the panel rather than an action on its content — and they are dropped while the update log owns it, since none of the three modes is what is on screen. All title characters are single-width and non-East-Asian-Ambiguous except `▸` (U+25B8, Ambiguous like the list markers, and measured with the plain form either way), keeping the border width math stable.
 - **Panel footers**: each panel reserves the last `panelFooterRows` (2) of its content height for a **blank** spacer plus a footer line. `[1]` carried a border-colored rule there for a while and it only made the footer read as a fourth section of the list rather than as the frame's own caption. Cells are joined by a **dim** ` · ` — the same painted middot the card's language list uses, since an unpainted one renders at the terminal's default brightness, louder than the hint labels it is separating (`TestPanelFooterSeparatorIsDim`). `[1]` carries `/ filter · enter run · space group` — `enter` is a `[1]` action, not a global one (see **Status bar**), and the three are ordered most-important-first because cells drop from the right and on a narrow list "run" outranks "group"; a right cell that is absent now reserves **nothing**, gap included, which is what had been dropping `[1]`'s last cell one step earlier than the width required. `[2]` carries its own actions led by the contextual `enter update to <v>` when a release is pending (and deliberately **not** `e note` / `# tags`: both are already offered in the meta line beside the values they edit, and a footer repeating them spends the row on saying it twice), `[3]` the source name, the `page/pages` position, the entry-cursor hints while there is an index to walk, the zoom toggle `z zoom` **last** (least actionable of the four — where you are in the text and how to walk it both outrank a width preference — and dropped entirely while an update log owns the panel, exactly as the title drops the source hints), and `ctrl+d/u page` pinned right. Measured shed geometry for that last cell: it survives from ~114 columns with no entry index to walk and from ~150 once there is one, since the index adds a `j/k navigate` cell. **The split is the index, not the source**: `--help` measures at ~150 because it has one, and a `man` page without one sheds at ~105 like the readme — so a per-mode number is the wrong shape to remember, and a test that fixes a width per mode is asserting about its fixture's cache rather than about the mode. Between ~82 (where `z` starts doing something) and whichever of those two widths applies, the key works unadvertised here, which is what the `[?]` overlay, the one surface that never sheds, is for. Cells are dropped from the right until they fit, exactly like the status bar and for the same reason: a footer that wrapped would push the panel one row past its height, and lipgloss answers that by scrolling the top border off the alt screen. **`calcListHeight()` is the single definition** of the viewport height inside a panel (`calcVpHeight() - footerRows()`), used both by `applyLayout` (which sizes the viewports) and by the renderers that stack viewport + footer back to the full height — two copies of that arithmetic would drift and cost a row. On a terminal too short to spare them (`calcVpHeight() < 6`) `footerRows()` is 0 and the panels are content only: two of six rows is a third of the panel, and a footer is a reminder while the content is the point.
-- **Panel widths and the zoom toggle (`z`)**: the three panel widths come from **`panelWidthsFor(zoom bool)`** in render.go — 20% tools / 46% brief / remainder to `[3]` normally, 20/30/remainder zoomed, then the 15/30/30 minimum-clamp cascade unchanged. `calcPanelWidths()` is the one-line wrapper reading `m.helpZoom`, the session-only view flag `z` owns (a view flag like `groupByTag`, not an `inputMode` — nothing here owns input — and deliberately not persisted: it is a way to read one README, not a preference). The parameterized core exists so **`toggleZoom()` can compare the two states without copying a `Model`** (the `baseFor`/`planFor`/`shellCommand` idiom), which is exactly what it does: below ~82 columns the clamps produce the **same triple for both variants**, so the keypress reports `too narrow to zoom` and flips nothing rather than setting a flag nothing follows — the honest no-op of `toggleGroupByTag`'s refusal, **one-directional in the same way and for the same reason**: `!m.helpZoom` gates the check, so zoom can always be turned *off*. A symmetric refusal strands the flag on — a session zoomed at 160 columns and resized to 80 could not clear it, and the layout came back zoomed the moment the terminal grew again, which is `toggleGroupByTag`'s stuck-in-the-tag-view failure one feature over (`TestZoomNarrowStillUnzooms`). The refusal is also the reason the status is short (18 cells: `renderStatusBar`'s statusMsg branch does not truncate, so an over-long message is exactly the wrap `TestStatusBarNeverWraps` exists to catch, and this is the one message whose trigger *is* a narrow terminal). `!m.ready` is checked **first and explicitly**, not left to the clamps agreeing by coincidence: before the first `WindowSizeMsg` every width is zero and there is no layout to toggle. **A successful toggle says nothing at all** and therefore returns a nil command — two panels change width over the full height of the screen, so the user is looking straight at the answer and a bar reading `readme zoomed` only restates it one line below where it happened. That is the one place this toggle parts company with `toggleGroupByTag`, which does report: reordering one panel's rows and inserting headers is a subtler change, and its message names which of two orderings you landed in. The refusal is the only exit that speaks, and it is exactly the case where the screen does *not* answer — nothing moved and the reason has nowhere else to live. The nil is a stricter invariant than the expiry tick it replaced: any command returned from the success path is a fetch, and `TestZoomFetchesNothing` says so directly. Two consequences are **stated, tested, and accepted**: the wrap width changes (`helpW` stays ≥ 30, off `helpWrapWidth()`'s floor), so `applyLayout` runs `setHelpContent()` and an active `j/k` spotlight in `[3]` is lost; and the README re-renders through glamour synchronously, since the width is part of `readmeRenderCache`'s key. Both are exactly what a width resize already costs. Zoom is orthogonal to the `[3]` update-log takeover — `showsUpdateLog()` owns *content*, zoom owns *width*.
+- **Panel widths and the zoom toggle (`z`)**: the three panel widths come from **`panelWidthsFor(zoom bool)`** in render.go — 20% tools / 46% brief / remainder to `[3]` normally, 20/30/remainder zoomed, then the 15/30/30 minimum-clamp cascade unchanged. `calcPanelWidths()` is the one-line wrapper reading `m.helpZoom`, the session-only view flag `z` owns (a view flag like `groupByTag`, not an `inputMode` — nothing here owns input — and deliberately not persisted: it is a way to read one README, not a preference). The parameterized core exists so **`toggleZoom()` can compare the two states without copying a `Model`** (the `baseFor`/`shellCommand` idiom), which is exactly what it does: below ~82 columns the clamps produce the **same triple for both variants**, so the keypress reports `too narrow to zoom` and flips nothing rather than setting a flag nothing follows — the honest no-op of `toggleGroupByTag`'s refusal, **one-directional in the same way and for the same reason**: `!m.helpZoom` gates the check, so zoom can always be turned *off*. A symmetric refusal strands the flag on — a session zoomed at 160 columns and resized to 80 could not clear it, and the layout came back zoomed the moment the terminal grew again, which is `toggleGroupByTag`'s stuck-in-the-tag-view failure one feature over (`TestZoomNarrowStillUnzooms`). The refusal is also the reason the status is short (18 cells: `renderStatusBar`'s statusMsg branch does not truncate, so an over-long message is exactly the wrap `TestStatusBarNeverWraps` exists to catch, and this is the one message whose trigger *is* a narrow terminal). `!m.ready` is checked **first and explicitly**, not left to the clamps agreeing by coincidence: before the first `WindowSizeMsg` every width is zero and there is no layout to toggle. **A successful toggle says nothing at all** and therefore returns a nil command — two panels change width over the full height of the screen, so the user is looking straight at the answer and a bar reading `readme zoomed` only restates it one line below where it happened. That is the one place this toggle parts company with `toggleGroupByTag`, which does report: reordering one panel's rows and inserting headers is a subtler change, and its message names which of two orderings you landed in. The refusal is the only exit that speaks, and it is exactly the case where the screen does *not* answer — nothing moved and the reason has nowhere else to live. The nil is a stricter invariant than the expiry tick it replaced: any command returned from the success path is a fetch, and `TestZoomFetchesNothing` says so directly. Two consequences are **stated, tested, and accepted**: the wrap width changes (`helpW` stays ≥ 30, off `helpWrapWidth()`'s floor), so `applyLayout` runs `setHelpContent()` and an active `j/k` spotlight in `[3]` is lost; and the README re-renders through glamour synchronously, since the width is part of `readmeRenderCache`'s key. Both are exactly what a width resize already costs. Zoom is orthogonal to the `[3]` update-log takeover — `showsUpdateLog()` owns *content*, zoom owns *width*.
 - **`applyLayout()` is the single relayout definition** (model.go, beside `helpWrapWidth`): everything the `tea.WindowSizeMsg` handler used to do after storing `m.width`/`m.height` — the width recompute, `calcListHeight`, the first-time `initViewports(vpH)` arm, the wrap-width-changed `setHelpContent` guard, and the `setToolsContent()` + card repaint tail. The handler is now those two assignments plus the call, so the resize path and `z` cannot drift. **The `prevWrapW` capture must stay above the `calcPanelWidths` assignment**: `helpWrapWidth()` reads the **stored** `m.helpW`, so a capture placed below compares the new width against itself, the re-wrap guard is dead, and `[3]` silently keeps its pre-resize wrapping. **Neither of `applyLayout`'s two tests is the sole guard on its mutation, and the comments on them say so** — the capture is also held by `TestHelpNavIdxResetTriggers/resize`, `TestResizeHeightOnlyKeepsCursor` and `TestReadmeResizeRerenders`, and the `setToolsContent` tail by six mouse and line-map tests including `TestWindowSizeRebuildsLineMaps`. What `TestApplyLayoutRewrapsHelpOnWidthChange` and `TestApplyLayoutIdempotent` add is a failure that **names the thing that moved**: the others report a lost spotlight or a click landing on the wrong row, which is three inference steps from the line that actually broke. Claiming sole coverage where there is none is the worse error of the two, because the next reader deletes the redundant-looking test believing the invariant travels with it.
 - **`panelGutter`**: the blank column a panel keeps between its frame and everything it draws — the `[1]` group headers, every footer, and in `[2]` and `[3]` **all** content, at **both** ends. Content that touches the border it lives in reads as having overflowed it, and on the right the gutter is also what keeps text off the scrollbar thumb. The two wide panels reach it from opposite directions and each through a **single definition**: `[2]` sizes itself to **`cardWidth()`** (`briefW - 1 - 2*panelGutter` — the viewport is one column narrower than the panel, `withScrollbar` keeps that one) and `buildCard` steps the finished card in with **`indentLines`** at the very end; `[3]` wraps to **`helpWrapWidth()`** (the same arithmetic) and `renderHelpContent` is a one-line wrapper applying `indentLines` over `helpContent()`, so the spotlight, the search highlight, the placeholders and the update log all land on the same point and no branch can render flush against the frame. The indent is applied **last, to whole finished lines**: it is plain spaces outside the styling, so it can never split an escape sequence, it lands in front of the metrics plate's own background segments rather than inside them, and it cannot shift a line index — which is why `buildCard`'s clickable-link map, built while writing, stays correct for free. `TestPanelsKeepTheirGutter` pins both panels on rendered output. `[1]` and `[2]` additionally open with a blank **row** for the same reason — their content started against the title spliced into the top border. In `[1]` that row is a real screen line, so it goes into the line maps as a non-selectable one and every tool below it shifts by one (which is what the maps exist for, and `syncToolsViewport` walks *up* over every non-selectable row above the selection so a header and the blank above it are revealed together). Tool rows keep the wider `toolRowIndent` (gutter + marker + blank), which puts the `⏺` in the same column as a section header's label and the names one step in from it.
 - **Refresh (`r` in `focusBrief`)**: `refreshSelectedCmd(t)` force-refreshes the selected tool bypassing the 24h cache TTL — the repo pass (`refreshRemoteCmd` → `version.RefreshRepoData`) + changelog (`refreshChangelogCmd` → `version.RefreshChangelog`) + README (`refreshReadmeCmd` → `version.RefreshReadme`, preceded by a `delete(m.readmeData, name)` so a session-cached 404/rate-limit negative can recover, then a `markReadmeLoading(name)` — the deletion makes `needsReadme` true again for the whole in-flight window, so without the marker leaving and re-entering the tool would spend a second request; `refreshingFor` does *not* cover it, since `remoteMsg` clears that flag as soon as the repo pass lands, which can be well before the README does) + a local installed re-detect (`fetchInstalledCmd`). It emits the same `remoteMsg`/`changelogMsg` as the startup path, so the merge/re-render logic is reused. While the repo pass is in flight `m.refreshingFor` (the tool name) turns the card title into a status line — `refreshing <name> data <spinner>` (`bubbles/spinner`, `MiniDot`; the about is hidden) — with no status-bar takeover; the `remoteMsg` handler clears `refreshingFor` on completion, which reverts the title to name+about and halts the `spinner.TickMsg` loop. **`[r]` answers every press**: on completion the handler returns `setStatus(refreshFailedStatus(msg.err))` whenever **`msg.err != nil`** — every path that actually failed to fetch now carries a named error (see `version.pickFetchErr`), while a pass that fetched something stays silent because the repainted card *is* the answer. The predicate is deliberately **not `!msg.conclusive`**, which is a broader thing: it is also false when the version layer refused the ref outright (an unsupported or spoofed host — a bare `RepoData` with a nil `Err`, no request made), which would report a network failure that never happened, and on a partial pass that fetched a new tag and lost only the repo card, where the bar would contradict a card the user just watched update. Before that, success, a rate limit, a 401, a timeout and a dropped connection were one indistinguishable gesture: the spinner turns, the card does not change. The reason is two-tier — `ErrRateLimited` → `refresh failed: rate limited — press [a]` (the one class with an answer the user can act on), everything else → `refresh failed: network error`. There is deliberately **no token wording**: by the time a fetch fails, `doGH` has already retried a rejected token anonymously, so the refresh did not fail *because of* the token, and the gauge and `[a]` overlay report that state anyway. The write sits inside the `msg.toolName == m.refreshingFor` branch, so the background passes `Init` fires — inconclusive all the time on an offline start — never put a "refresh failed" on the bar for a gesture nobody made. `refreshingFor` doubles as the double-press guard; a tool with no `GitHub` only re-detects the installed version (`m.statusMsg = "no repo to refresh"`, no spinner). Note `case "r"` no longer branches at all: it is refresh in `focusBrief` and unbound everywhere else. Rename went global as `m` and the README source moved to `R`, so the key that once meant three things by focus now means one.
@@ -115,12 +117,12 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
 - **Panel `[3]` modes (`helpMode`)** — full rationale in **[`docs/design/readme-pipeline.md`](docs/design/readme-pipeline.md)**. Three sources: `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool; `[R]`/`[H]`/`[M]` switch it from `focusBrief || focusHelp` through the shared **`switchHelpMode(mode)`** (sets the mode, dismisses a *completed* update log, `setHelpContent()` + `GotoTop()`, returns the fetch command for the mode's missing source). The trio is **capitals as a set** so none collides with a lowercase verb (`r` is `[2]`'s refresh, `m` the global rename). **`z` shares their gate and nothing else**: it is the fourth key that changes what `[3]` is, so it fires from the same `focusBrief || focusHelp` pair, but it changes the panel's *width* rather than its source — so it does **not** move focus (a width change is not a change of what you are reading), goes through `toggleZoom()` rather than `switchHelpMode`, and fetches nothing. See **Panel widths and the zoom toggle** below. The invariants most often broken (the full list is in the design file): **`m.helpCache` is a `map[string][2]string` indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return *before* the array read; a **live** update log keeps `[3]` in every path (its branch sits ahead of both the readme branch and the `No tool selected` guard). Rendering is `cleanTerminalOutput` → **`cleanReadmeMarkdown`** (readme_clean.go) → glamour with `keepkitStyle`, and a glamour failure falls back to the **preprocessed** text, never to the raw one. In the preprocessor: **code is never rewritten** (fenced blocks segmented, inline spans NUL-masked), CRLF is normalized on entry (a `\r`-suffixed closing fence protects the rest of the file), images run before links, autolinks and bare URLs are left alone, both reference forms are gated on labels collected **document-wide after** the HTML rules, HTML tag names come from the fixed `rcHTMLNames` allowlist whose trailing `\b` is what makes the ~80-branch alternation order-independent, and **`rcLineContent` slices rather than `ReplaceAllString`** — the replace form froze the whole TUI for 8.4 s on a 512 KiB adversarial README. `keepkitStyle` **clones** the glamour globals and assigns a **fresh pointer** per override, because `styles.DefaultStyles` aliases the same structs and writing through a cloned one restyles glamour process-wide. Dark/light is resolved **once at construction** into `m.darkBG` — `glamour.WithAutoStyle()` probes the terminal with an OSC query that races Bubble Tea's input reader. In the theme itself: the heading ladder and the fence accents come from `ui.HeadingColors`/`ui.ChromaColors` and **do not follow a theme switch** (the contract change, stated in three places); **`H1.Prefix = ""`/`H2.Prefix = ""` are load-bearing assignments** — glamour's cascade overrides a child prefix only when it is non-empty, so losing them brings the stock `# `/`## ` markers back rather than falling through to `Heading`; **`H6.Bold` must be set explicitly** (the stock dark H6 is an explicit `Bold: false` that beats inheritance); in the chroma repaint **`Text.BackgroundColor` is what carries the whole plate** — chroma resolves an unset token background up to `Text`, its root, not to `Background`, so the five accents set `Color` only; and `HorizontalRule.Format` is guarded on `width > 0`, since a caller with no layout yet must get the stock rule rather than an empty string. **`chromaFormatterFor`** (readme.go) is what keeps a fence's plate the same color as the card's: glamour's default formatter is `terminal256` for *every* profile, ignoring the `WithColorProfile` beside it, which quantized `Surface` `#343945` to index 237 and put one plate on screen in two colors. Two accepted limits stay: chroma's plate covers only the highlighted **tokens** — glamour paints a code block's left indent with the *enclosing* block's style and never paints the pad out to the wrap width, so a wrapped fence line reads as a short smudge — and `TestFencePlateMatchesTheCard` allows one unit per channel, because **termenv** rounds `#343945` to `52;56;69` while chroma writes the hex verbatim. **Any override new to this file must be confirmed against glamour's renderer once before its struct test is written** — a struct assertion only proves the field changed, and `Item.Color` passes one while doing nothing.
 - **Help navigation (`j`/`k` in `focusHelp`)**: `[3]` is navigable per *entry* — a flag or subcommand line plus its indented description block. `parseHelpEntries(raw, width)` (textutil.go) detects entries heuristically on the **pre-wrap source lines** (flag start = the `helpTokenRe` flag core at the trimmed line start; subcommand start = `helpEntrySubcmdRe`, an indented non-dash word + 2+ spaces + text — the word class excludes `.` so justified man prose like `tree.  See also…` doesn't match; continuation = `continuesEntry`: any deeper-indented non-header line — including deeper lines that *begin* with a flag token (`…overridden with\n --no-ignore.`) — plus blank lines whose next non-blank line still continues, so multi-paragraph descriptions stay one entry; the entry ends at a section header or the next line at the entry's own indent or shallower) and maps the ranges to wrapped display-line indices via `wrapLine` — the same code `wrapText` uses, which is the point: `wrapText` rebuilds wrapped lines from `strings.Fields` (indentation is lost), so parsing wrapped output would break the indent heuristic, and sharing the wrap algorithm plus the single `helpWrapWidth()` (`max(helpW-1-2*panelGutter, 20)` — the viewport is a column narrower than the panel and a gutter is held at each end) keeps entry indices in lockstep with what the viewport shows. `isHelpSectionHeader` is the one definition of a header, used by both `colorizeHelp` and the parser. State is `m.helpEntries []entryRange` + `m.helpNavIdx` (−1 = off) + `m.helpBase` — the wrapped+colorized full-color content, cached because cursor moves repaint per keystroke and must not re-run the colorize regex over a whole man page (`helpContent`'s normal path serves `applySpotlight(helpBase)`, and `renderHelpContent` is the one-line wrapper that steps the result in by `panelGutter`; the base is built directly in `setHelpContent`, not via the renderer, which serves that very base back through `applySpotlight`). **`setHelpContent()` is the single recompute point** — every site where the *visible* text changes (selection via `autoFetchCmdsForSelected`, `[R]`/`[H]`/`[M]`, `helpOutputMsg` — gated on `msg.mode == m.helpMode`, a late fetch for the hidden mode must not reset the cursor, `readmeMsg` for the selected tool while in readme mode, resize — only when `helpWrapWidth()` actually changed, so a height-only resize keeps the cursor and a width change re-renders the README, update-log start) goes through it: recompute entries (empty for the update log, readme mode, `helpLoadingFor` and placeholders — `j`/`k` stay plain scroll there), reset the cursor, repaint, never scroll. Style-only repaints (per-chunk log appends, cursor moves) call `SetContent(renderHelpContent())` directly and must not reset the cursor. Interaction: **only the letter keys navigate — `↑`/`↓` keep their 3-line scroll** so prose between/after entries stays keyboard-reachable; the first `j`/`k` lands via `helpNavStart(delta)` on the first entry intersecting the window, or (none visible) the nearest entry in the movement direction; later presses step clamped without wrap; `applySpotlight` (render.go) dims every line outside the current entry (`Styles.Dim.Render(stripANSI(line))` — the `[a]` overlay's strip-then-repaint trick per whole line) while the entry keeps full `colorizeHelp` color; `scrollToNavEntry` keeps it in view with mutually exclusive branches and a `min(end-Height, start)` clamp so a taller-than-window entry pins its start to the top. `esc` is two-stage: cursor off first (scroll kept), focus walk second. `PgUp`/`PgDn`/`g`/`G`/wheel stay pure scroll and never touch the cursor. Every path that deactivates navigation (esc, any `setFocus` move) goes through `clearHelpNav()`, which pairs the reset with the repaint — clearing the index without repainting leaves stale dimming. The `focusHelp` bar shows `[j/k] navigate` alongside `[↑↓] scroll` when entries exist and prepends `[esc] exit nav` while the cursor is on.
 - **Tracking verbs are global**: `t` track (add by GitHub URL or plain name → `modeTrack`), `u` untrack (with confirmation → `modeConfirmUntrack`), `m` rename (fix the binary name when the repo name differs → `modeRename`). All three fire in **every focus** and are three of the six keys `globalHints` puts on the status bar. They used to be `[1]`-only because each collided with a `[2]` action (`t` tags, `u` update, `r` refresh); the redesign moved those onto keys of their own (`#` tags, `enter` update) and freed all three to mean one thing everywhere, which is what lets the bar carry a single focus-independent list instead of three per-focus ones. Rename is **`m`, not `R`**: `R` is panel `[3]`'s readme source now, and the tracker's verbs are the lowercase set. That leaves lowercase `r` meaning **refresh in `[2]` and nothing else** — it used to double as `[3]`'s readme switch, so one key meant "spend three requests" or "swap the panel's source" depending on a focus the `[3]` title did not mention. Each mode has a handler in `mode.go` and a matching branch in `renderStatusBar()`, mirroring the `modeEditNote`/`modeEditTags` input pattern. Mutations go through `loader.UpsertMeta`/`RemoveMeta`, persist via `loader.SaveMeta`, then rebuild `m.tools = loader.ToolsFromMeta(m.meta)` and refresh the viewport.
-- **Run (`enter` in `focusTools`)**: launches the selected tool without leaving keepkit. `enter` fires only in `modeNormal`+`focusTools` (empty list → no-op; in `modeSearch` enter stays the commit key) and opens `modeRunInput` — a one-line prompt (`m.runInput`, its own textinput like `m.search`, not shared with note/tags) prefilled with `m.lastRun[name]` else the tool name, cursor at end; the status bar echoes `run <name>: <input>  [enter] run  [esc] cancel`. `m.lastRun map[string]string` is session-only per-tool memory of the last dispatched command — rename's stale-state cleanup deletes the old-name entry alongside `helpCache` et al.; untrack deliberately leaves it (harmless, session-scoped). Enter with empty/whitespace input cancels like `esc`. On dispatch `launcher.Detect(command, name)` picks the path — env-only, so unlike every probe it is safe inside `Update()`: a tab plan runs its `Argv` via `startLaunchCmd` (`exec.Command` + `proc.DetachTTY`, `launchTimeout` — a 10s **var**, shrunk by the timeout/KillGroup test — with `proc.KillGroup` on expiry, `safeCmd`-wrapped) → `launchDoneMsg{toolName, command, err}`, with `m.launchingFor` (the launch twin of `updatingFor`) as the one-adapter-launch-at-a-time guard and a `launching <name> in <terminal>…` statusMsg as in-flight feedback (this is also `Plan.Terminal`'s consumer); a `Fallback` plan runs `execToolCmd` → `tea.ExecProcess` over `shellCommand(runtime.GOOS, cmd)` (`sh -c` / `cmd /c`; goos-parameterized and spawn-free like `browserCommand`, so both branches are table-testable) — keepkit suspends, Bubble Tea restores the terminal when the tool exits → `execDoneMsg{toolName, err}`. **Auto-fallback**: an adapter failure (kitty remote control off, Automation permission denied) must not strand the launch — the `launchDoneMsg` error handler sets `statusMsg` (`tab open failed — running <name> here`) and returns `execToolCmd(msg.toolName, msg.command)`; `command` rides the msg so the handler never re-reads input state. The auto-fallback is **gated on `modeNormal`**: the result can arrive up to `launchTimeout` after enter (osascript blocked on the macOS Automation dialog), and `tea.ExecProcess` seizing the terminal under an open editor/overlay would route keystrokes to the spawned shell — under any other mode the fallback is **deferred**, not dropped: the gate stores `m.pendingLaunchName`/`Command` and `flushPendingLaunch` (mode.go) dispatches `execToolCmd` with the same statusMsg (single definition: `launchFallbackStatus`, shared with the ungated auto-fallback) on the keystroke that returns the mode to `modeNormal` (every modal return in `Update` funnels through it — the mode-dispatch switch plus the inline `modeSearch` exit; `modeTokenInput`'s esc lands on `modeAPIStatus`, so the flush waits for the overlay to actually close). A statusMsg set at gate time would be dead UI — every open mode's `renderStatusBar` branch outranks the statusMsg branch, and the blanket `statusMsg = ""` reset on `tea.KeyMsg` fires on the very keystroke that closes the mode; setting it in the flush (after both) is what makes the failure visible. The flush goes straight to `execToolCmd` — never back through `launcher.Detect` — so a known-failing adapter plan is never re-run; a new dispatch from `modeRunInput`'s enter drops a pending fallback first (flushing both on one keystroke would run two commands), and confirming untrack of the pending tool itself drops it too — the dialog-closing enter must not exec the now-untracked tool's command (a pending fallback for a *different* tool deliberately survives the untrack and flushes on that keystroke). The handler clears `launchingFor` first in all outcomes. Working directory differs by path: a tab opens in the new shell's default cwd, the ExecProcess fallback inherits keepkit's. The timeout carries one accepted race: an adapter killed after its tab command already executed (osascript stuck post-`write text`) still triggers the fallback, so the command can run twice — narrow, undetectable, and better than stranding genuine failures. This path also serves native Windows: `planFor` is env-only, so WezTerm there yields a doomed `sh -c` plan whose failure lands in the fallback (one noisy attempt accepted; a `GOOS` guard in `planFor` is deliberate YAGNI). Success wording is mode-neutral — `launched <name>` — because Terminal.app and tmux open a *window*, not a tab. **No `logx` anywhere in the flow**: a non-zero tool exit (`statusMsg "<name> exited: <err>"`) is the tool's business, not a keepkit anomaly, and an adapter error is a degraded path, not a malfunction (the auto-fallback still launches the tool). Launch during a running update is deliberately not blocked — independent concerns; ExecProcess pauses rendering of the live update log and the buffer catches up on resume. A not-installed tool launches anyway (no PATH pre-check): in a tab `sh` reports `command not found` inside that tab, while on the ExecProcess path the shell's not-found exit (`notFoundExit`: 127 sh / 9009 cmd.exe) maps to `statusMsg "<name> not found — is it installed?"` instead of the cryptic raw exit status. The `[?]` overlay's tools group carries `enter — run in tab` (desc kept short — the overlay sits at the 76-col edge of its budget).
+- **Run (`enter` in `focusTools`)** — full rationale in **[`docs/design/tool-overlay.md`](docs/design/tool-overlay.md)**. Runs the selected tool on a pseudo-terminal **inside keepkit**: `enter` opens `modeRunInput` (a one-line prompt, `m.runInput`, prefilled with `m.lastRun[name]` else the tool name; blank input or `esc` cancels), and the dispatched command runs in a centred overlay over the dimmed layout. There is **one path for a TUI and a CLI** — vim draws in it, `rg --version` prints and stops and the final screen stays until `esc`. The invariants most often broken (the full list is in the design file): **only `Update` touches the emulator's screen state** — `vt.Emulator` lives on `Model`, the pty is read by one goroutine posting `tea.Msg`s; **input needs a relay goroutine** because x/vt exports no key encoder and its `SendKey` encodes against DECCKM, which no accessor exposes — a hand-rolled encoder would send the wrong arrows to exactly the full-screen tools this exists for; **teardown closes `InputPipe()`'s writer, never `Emulator.Close()`** (upstream race charmbracelet/x#879, reproduced under `-race`), and `closeToolOverlay` is the single teardown, session-first so a parked relay write fails fast; **while the tool runs every key is forwarded, `esc` and `ctrl+c` included** — `ctrl+\` is the one reserved chord and it kills *without* leaving the mode, since the outcome line arrives with `termExitMsg`; after the exit only `esc` acts; **the exit row is reserved from the start and every row is padded to the body width**, the two things that keep `PlaceOverlay` from re-centring the block at the moment the user starts reading the outcome; **`termGeometry` returns the size and `ok` separately** — the keypress refuses on `!ok` (`terminal too small to run a tool`, **no `lastRun` write**), a mid-session shrink clamps to the floor and keeps the tool running, and `!m.ready` is checked first (the `toggleZoom` idiom); **the drain carries the exit rather than swallowing it** (`termChunkMsg.exit`), so a short-lived tool's final screen is painted before the verdict. A not-installed tool needs no special case: `sh` says so and exits 127, which the `✕ exit 127` line shows. `m.lastRun` is session-only per-tool memory; rename deletes the old-name entry alongside `helpCache` et al., untrack deliberately leaves it. Launch during a running update is deliberately not blocked — independent concerns; the log keeps streaming into `[3]` under the dim. **No `logx` anywhere in the flow**: a non-zero tool exit is the tool's business, not a keepkit anomaly. The `[?]` overlay's tools group carries `enter — run in overlay`.
 - **Status bar** (`renderStatusBar()`) is **global** — the same line in every focus, instead of the three per-focus lists it used to rewrite itself between as the user moved panels. A key belongs on it exactly when it does the same thing in **every** focus, and six do: `t track · u untrack · m rename · a api · ? keys · q quit` (`globalHints`). `enter` and `/` used to lead that list and are precisely the two that failed the definition — `enter` runs a tool in `[1]`, installs a release in `[2]` and is unbound in `[3]`; `/` filters the list in `[1]` and is unbound in `[2]`/`[3]` — so the bar either advertised a key that does nothing in two of the three panels, or (in `enter`'s case) one meaning while being wrong about the others. Both moved to `[1]`'s footer beside `space group`, next to the panel where their meaning is fixed, which is the same rule everything else panel-local follows (see **Panel footers**). Key hints lost their brackets — `m.key(k)` renders the bare key in the accent, and `m.hint(k, label)` pairs it with its word **in `Dim`**, a deliberate two-step contrast (the key is the only part of a hint the eye needs to find, so the word beside it steps back rather than competing at reading brightness), so the key/label contrast is defined once; the accent already says "this is a key", and at the bar's density a pair of brackets per hint cost more columns than the whole `[?]` overlay's third column. Literal brackets survive only where they name a *panel* (`[3] readme`), which is now the only bracketed thing on screen. In the three normal focus states `renderHintsBar` lays the line out as **three zones**: **`appVersionCell()`** pinned to the **left** edge, the hint cells **centered on the bar**, and the **API-usage gauge** pinned to the **right** edge. The two edges are the two facts that hold regardless of what the user is doing — which build this is, and how much quota is left — so they sit where the eye returns rather than inside a key list; centering the keys between them is only honest because those keys no longer change with focus. Centering is measured against the **whole bar**, not against the leftover band between the edges (the block must read as centered on screen, and the two edges are rarely the same width), then clamped into that band, so on a narrow terminal it is pushed up against the version cell rather than overlapping it. The collapsed **self-update cell** rides with the version on the left: it carries its action alone (`U update`) and `appVersionCell` is the subject naming what is being updated — split across the two edges, the verb would lose its noun. `appVersionCell` is keepkit's own identity line — `keepkit v0.1.0` in `Dim`, the one fact about the app that is true on every frame and the answer to "which build is this?" without opening `[?]`; when a newer release is known and still uninstalled (`selfUpdateAvailable()`, the sixth `selfState` site) the version takes `SignalBold` and the same ` ↑` an outdated tool row carries, so the app announces its own update in the vocabulary it announces everyone else's. The version shown stays the **running** one — the offer is that this build is behind, not a preview of what it would become — and once the update is installed the arrow goes (the pending action is a restart, which the self cell says). It **replaced the pending-updates count** that used to sit here: that count was the third surface for the same number (the `[1]` title carries it beside the tracked count, and every outdated row carries its own `↑`), while the running version had none outside an overlay; `updateCount()` still feeds the `[1]` title. Under width pressure the bar sheds in order of how *actionable* the thing dropped is: trailing hint cells first (they are ordered most-important-first, so `? keys` and `q quit` go before `t track`), then the gauge (read-only), then the version cell, then the self cell — and the leading hint cell is never dropped, only truncated. That order is spelled out step by step rather than computed, because "what goes next" is a judgement about meaning, not about width. `TestAppVersionCell` pins the cell across all five self states plus a tagless offer. **The gauge is on screen for the whole session** once the rate is known (`gaugeVisible`): it is also the only visible sign that keepkit has an API surface at all, so hiding it at rest hid the `[a]` overlay along with it — the numbers are the affordance, and `a api` sits in the global key list beside them. Its fill turns `Danger` under `min(gaugeDangerRemaining, limit/4)` remaining, read against the limit as well as absolutely, because an absolute-only bound would paint a token-less user's bar permanently red — the opposite of a signal. It renders as `api ▮▮▮▮░░░░░░░░ 45/60` in the corner, a fixed 12-cell bar of foreground-colored `▮` fill / `░` track glyphs (not painted backgrounds, so it survives a degraded color profile; both glyphs are deliberately non-East-Asian-Ambiguous, where a `█` would measure two cells and break the alignment math), degrading to `api 45/60`, then to `api✕` when there is a rejection to report, and then to nothing. **A rejected token adds a `Danger` `✕` to the label** (`api✕ ▮▮▮…`) in every form — this is the primary place a degraded session is announced, and the compact form is the one a narrow bar keeps, which is exactly where bare numbers explain themselves least. It is a suffix rather than a relabel to `anon` because a user with no token is also anonymous and that is not degradation; the `✕` says a credential was **refused**, and the limit beside it says what is left. `rejectedTokenGlyph` is U+2715, one cell under **both** runewidth conditions (U+00D7 would be two under `RUNEWIDTH_EASTASIAN=1`), which the right-edge arithmetic requires. That one column is also why **`renderRateMarker()`** exists as a third, narrowest form: at the 80×24 baseline the marked gauge no longer fits beside the six hints, so without it arming the degraded state removed the announcement entirely — the session that most needs announcing was the one showing nothing. What survives follows the bar's own shed rule (drop the least actionable thing first): the numbers are a measurement the `[a]` overlay repeats, the `✕` is the only sign anywhere on screen that requests stopped carrying the user's token. It returns `""` when there is no rejection, so a healthy bar gains no form it did not have before. `gaugeFilled` clamps the rounded ratio so any usage shows at least one `▮` and a full bar means exhaustion only. The bar spends **no columns advertising `[a]`** — the `[?]` overlay documents it. Input/modal states show no right group at all. **The bar must stay one line**: `Styles.StatusBar` is width-constrained, so a hint list wider than `m.width-2` wraps to a second row and `View()` returns `m.height+1` lines — one row past the terminal, which scrolls the top border off the alt screen. `renderHintsBar` therefore takes the hints as `[]string` cells ordered most-important-first and drops them from the right until they fit, reserving the two non-gauge right-group members first. The **leading** cell is never dropped, so one cell wider than the whole bar is possible — the fused self banner is 37 cells and overflows below ~39 columns — and that case is **truncated** (ANSI stripped first, since a cut inside an escape sequence would be re-emitted to the terminal verbatim) rather than allowed to wrap. `TestStatusBarNeverWraps` pins the invariant at the 80×24 baseline and, for the banner, down to 24 columns. Below 80 columns only the *bar* is checked: the three panels have their own minimums (15+30+30 plus borders), so the layout overflows there on its own — a separate, pre-existing limit.
-- **Status-message lifecycle**: `m.statusMsg` (rendered by `renderStatusBar`, which outranks both the self-update banner and the hints bar whenever non-empty — the banner is not modal, and a transient status covering it for `statusMsgTTL` is intended) has two clears. (1) **Immediate**: the blanket `m.statusMsg = ""` on every `tea.KeyMsg` — any keypress wipes the current status at once. (2) **TTL auto-expiry**: every *transient* status is set via **`setStatus(s) tea.Cmd`** (model.go), which bumps a generation counter `m.statusSeq`, sets the message, and returns `tea.Tick(statusMsgTTL, …)` producing a `statusExpiredMsg{seq}` stamped with the current seq; the `Update` handler clears the message only when `msg.seq == m.statusSeq`, so a stale timer from a message already superseded by a newer one is a harmless no-op. `statusMsgTTL` is a **var** (`1 * time.Second`), shrunk by tests the same way as `launchTimeout` (the tick captures the value at construction, so the shrink must precede the `Update`). The returned `tea.Cmd` must be **batched** into whatever the caller already returns (`tea.Batch`); callers that only set a status return it directly. **In-flight** statuses (`launching <name> in <terminal>…`, `still launching <name>`) are the deliberate exception and go through **`setStickyStatus(s)`** — no timer, but it **still bumps `statusSeq`**: they report work still in progress and are extinguished by `launchDoneMsg`, not the clock, so letting a timer expire one mid-flight would hide the only sign the adapter is busy for up to `launchTimeout`. The bump is the whole point of the helper rather than a plain assignment — a transient status set within the last `statusMsgTTL` (the group toggle, say) has a tick in flight whose seq would otherwise still match the sticky message and wipe it (`TestInFlightStatusSurvivesStaleExpiry`). `TestStatusExpired*`/`TestSetStatus*` pin the mechanism; `assertOnlyExpiryTick` is the test helper that asserts a site returns *only* the expiry tick (no fetch/exec rode along).
+- **Status-message lifecycle**: `m.statusMsg` (rendered by `renderStatusBar`, which outranks both the self-update banner and the hints bar whenever non-empty — the banner is not modal, and a transient status covering it for `statusMsgTTL` is intended) has two clears. (1) **Immediate**: the blanket `m.statusMsg = ""` on every `tea.KeyMsg` — any keypress wipes the current status at once. (2) **TTL auto-expiry**: every *transient* status is set via **`setStatus(s) tea.Cmd`** (model.go), which bumps a generation counter `m.statusSeq`, sets the message, and returns `tea.Tick(statusMsgTTL, …)` producing a `statusExpiredMsg{seq}` stamped with the current seq; the `Update` handler clears the message only when `msg.seq == m.statusSeq`, so a stale timer from a message already superseded by a newer one is a harmless no-op. `statusMsgTTL` is a **var** (`1 * time.Second`), shrunk by tests through `shrinkStatusTTL` — the last shrinkable timeout seam now that `launchTimeout` died with the tab launcher (the tick captures the value at construction, so the shrink must precede the `Update`). The returned `tea.Cmd` must be **batched** into whatever the caller already returns (`tea.Batch`); callers that only set a status return it directly. Every transient status goes through `setStatus`; **work still in progress reports itself on the surface that owns it** — the update log's outcome block, the tool overlay's exit row — rather than on a bar message that would have to outlive its own timer. The `setStickyStatus` helper that existed for the tab launcher's `launching …` feedback died with it. `TestStatusExpired*`/`TestSetStatus*` pin the mechanism; `assertOnlyExpiryTick` is the test helper that asserts a site returns *only* the expiry tick (no fetch/exec rode along).
 - **API-status overlay (`a`)**: opens a read-only view of the GitHub rate limit and token (source, masked value, used/limit with threshold icon, reset time) with token entry/removal/refresh. When no token is configured it leads with an `add a github token…` nudge; a **rejected** one gets `replace the token to restore the 5000/h limit` instead — "add" reads as advice to someone who has already done it, and the thing to do is swap the credential, not create one. A rejected **env** token gets a third wording, `GITHUB_TOKEN was refused — replace it in your shell`, and offers **no key at all**: `[e]` runs `SetToken`, which writes the config file, and `effectiveToken` reads that only when `GITHUB_TOKEN` is empty — so the key cannot fix this one, and the variable belongs to the shell that launched keepkit. The env arm must stay **first** in the switch or the config wording swallows it; `[d]` two blocks down has gated on the source all along for the same reason. All three are hidden while entering a token, when the open input is already the answer. A rejection also rewrites the token line itself to `token  <source> (<masked>) — rejected (HTTP 401)` in `Danger`, with `requests run unauthenticated` under it: this is the surface that **always** has the answer, since the gauge's `✕` is droppable under width pressure and invisible before the first rate snapshot. **The mask is load-bearing** — it is how the user recognises which credential to replace — and it survives only because `version.Token()` reads the raw `effectiveToken()` core rather than the suppressed `resolveToken()`. It is `modeAPIStatus` (token entry: `modeTokenInput`) with a matching `renderStatusBar()` branch; `a` fires only in `modeNormal`; `esc` **or `q`** closes it. See the GitHub API section for the data flow.
-- **Overlay compositing**: two overlays composite over the layout via `ui.PlaceOverlay` (a centered fg-over-bg compositor), gated by the shared `overlayVisible()` predicate in `View()` — the `[a]` API-status overlay (`renderAPIStatus`) and the `[?]` hotkeys overlay (`renderHotkeys`), picked by `m.mode`. `PlaceOverlay` dims the whole visible background — original styling is stripped and repainted with `OverlayDimStyle` (`ColorDim`) — so the modal is the only full-color element. Covered rows get the dim inside `overlayLine` *after* `truncateVisible`/`dropVisible`, because those helpers `StripANSI` the bg and would erase a pre-applied dim from the modal's side margins.
-- **Mouse policy** (`handleMouse` in `render.go`, dispatched from `Update()` before the mode switch, gated inside the function): wheel scrolling works in every mode; while any overlay is visible (`overlayVisible()` — `[a]` API status or `[?]` hotkeys) all mouse input is a no-op, and before the first `WindowSizeMsg` (`!m.ready`) too. Clicks that change selection or focus fire only in `modeNormal` — otherwise a click would move `selectedMeta()` under an open note/tags/rename editor and retarget the commit. A click that changes the selected tool goes through the same `selectMeta` helper as the keyboard `j`/`k` path, including the auto-fetch; a click anywhere in the tools panel (row or empty area) focuses it via `setFocus`, matching brief/help — the same helper the keyboard uses, so a click cannot leave the list painted with stale focus styling. Both panels translate the click row the same way — **through `panelRow(msg.Y, vp.Height)`**, then `+ vp.YOffset`. X alone does not mean "inside a panel": the outer `Margin(1,0)` row, the two borders and the status/hints bars all share the panels' columns, and with a scrolled viewport an unbounded `msg.Y - 2` maps that chrome onto real content — a click on the blank top row would open a card link. `panelRow` returns `-1` outside the viewport's rows; inside, `[1]` goes through `toolAtLine()` (a group header maps to `-1` and selects nothing) and `[2]` through `buildCard()`'s link index — a click on the `repo:` line or the changelog release URL returns `openURLCmd(url)`, every other line only moves focus.
+- **Overlay compositing**: three overlays composite over the layout via `ui.PlaceOverlay` (a centered fg-over-bg compositor), gated by the shared `overlayVisible()` predicate in `View()` — the `[a]` API-status overlay (`renderAPIStatus`), the `[?]` hotkeys overlay (`renderHotkeys`) and the embedded tool terminal (`renderToolOverlay`), picked by a **`switch m.mode`**. A switch rather than the two-way `if` it grew out of: that form let the API-status default answer for every mode that was not `modeHotkeys`, which with a third overlay would paint the token panel over a running tool. `PlaceOverlay` dims the whole visible background — original styling is stripped and repainted with `OverlayDimStyle` (`ColorDim`) — so the modal is the only full-color element. Covered rows get the dim inside `overlayLine` *after* `truncateVisible`/`dropVisible`, because those helpers `StripANSI` the bg and would erase a pre-applied dim from the modal's side margins.
+- **Mouse policy** (`handleMouse` in `render.go`, dispatched from `Update()` before the mode switch, gated inside the function): wheel scrolling works in every mode; while any overlay is visible (`overlayVisible()` — `[a]` API status, `[?]` hotkeys or the tool terminal) all mouse input is a no-op, and before the first `WindowSizeMsg` (`!m.ready`) too. Clicks that change selection or focus fire only in `modeNormal` — otherwise a click would move `selectedMeta()` under an open note/tags/rename editor and retarget the commit. A click that changes the selected tool goes through the same `selectMeta` helper as the keyboard `j`/`k` path, including the auto-fetch; a click anywhere in the tools panel (row or empty area) focuses it via `setFocus`, matching brief/help — the same helper the keyboard uses, so a click cannot leave the list painted with stale focus styling. Both panels translate the click row the same way — **through `panelRow(msg.Y, vp.Height)`**, then `+ vp.YOffset`. X alone does not mean "inside a panel": the outer `Margin(1,0)` row, the two borders and the status/hints bars all share the panels' columns, and with a scrolled viewport an unbounded `msg.Y - 2` maps that chrome onto real content — a click on the blank top row would open a card link. `panelRow` returns `-1` outside the viewport's rows; inside, `[1]` goes through `toolAtLine()` (a group header maps to `-1` and selects nothing) and `[2]` through `buildCard()`'s link index — a click on the `repo:` line or the changelog release URL returns `openURLCmd(url)`, every other line only moves focus.
 
 ### File storage
 
@@ -154,7 +156,7 @@ Config files are not the only process-global state a test can leak. `version.rej
 
 An errors-only journal so bugs can be researched after the fact instead of reconstructed from memory. One plain-text file per session, created **lazily on the first write** — a session with no errors leaves no file at all, so the presence of a file is itself the signal. The timestamp is colon-free (Windows filenames) and zero-padded, so lexicographic order equals chronological order, which is what `Cleanup()` (keep newest 20) relies on. The header (`keepkit <version> <goos>/<goarch> tools=<n> token=<source>`) is assembled in `main.go` via `logx.SetHeader` and written as the file's first line — it stays in `main` because pulling version/tool-count/token-source into `logx` would invert the import graph (`logx`'s only project import is the stdlib-only `configdir` leaf, keeping it near the bottom of the graph).
 
-**Why our `recover` sits deeper than Bubble Tea's:** `recover()` consumes a panic wherever it fires first, and Bubble Tea's own recover in each `tea.Cmd` goroutine prints the trace *after* `p.cancel()` (async) but *before* the terminal is restored — so the trace lands in the alt-screen buffer and vanishes on exit. `logx.Recover(context)` is therefore deferred *inside* `Update`, `View` and every command (via the `safeCmd` wrapper; `execToolCmd` is the one unwrapped cmd — `tea.ExecProcess` only constructs the exec message, nothing there can panic), records the value plus `debug.Stack()` (which still contains the real panic site from inside the defer), then **re-panics** so Bubble Tea still catches it, restores the terminal and returns `ErrProgramPanic`. `tea.WithoutCatchPanics` is deliberately **not** used — terminal restoration is Bubble Tea's job and it does it correctly. Errors-only by design: there is no debug level, no `KEYS_DEBUG`, no env reading, no JSON, no size-based rotation — without a debug level the file appears only when something went wrong. The logger never breaks the app: its own failures (file won't open, disk full) are swallowed silently.
+**Why our `recover` sits deeper than Bubble Tea's:** `recover()` consumes a panic wherever it fires first, and Bubble Tea's own recover in each `tea.Cmd` goroutine prints the trace *after* `p.cancel()` (async) but *before* the terminal is restored — so the trace lands in the alt-screen buffer and vanishes on exit. `logx.Recover(context)` is therefore deferred *inside* `Update`, `View` and every command (via the `safeCmd` wrapper; the one unwrapped cmd is `handleTermChunk`'s exit re-emit — a closure returning a prebuilt value, nothing there can panic, the same safe-by-construction category `execToolCmd` occupied until it died with the tab launcher), records the value plus `debug.Stack()` (which still contains the real panic site from inside the defer), then **re-panics** so Bubble Tea still catches it, restores the terminal and returns `ErrProgramPanic`. `tea.WithoutCatchPanics` is deliberately **not** used — terminal restoration is Bubble Tea's job and it does it correctly. Errors-only by design: there is no debug level, no `KEYS_DEBUG`, no env reading, no JSON, no size-based rotation — without a debug level the file appears only when something went wrong. The logger never breaks the app: its own failures (file won't open, disk full) are swallowed silently.
 
 Logging sites are `Errorf`-only: cache read/write failures (`version.LoadCache`/`SaveCache`), GitHub API failures (`doGH`/`classifyStatus` — HTTP code + `X-RateLimit-Remaining`, never the token), installed-version detection give-up (`InstalledVersion`, logged once — but only when a binary that *is* on PATH fails to answer `--version`/`-V`; a plain not-on-PATH miss is the normal "not installed" state and is never logged, so a tracked-but-uninstalled tool does not create a log every startup. A brew/cargo fallback hit and an `isTUITakeover` capture both suppress it too — the first is that path's normal state, the second is a classified kind of tool rather than a malfunction), `meta.yaml` save failures (`loader.SaveMeta`), help-capture failures (`fetchHelpCmd`), update failures (`recordUpdateOutcome`, shared by the tool and self paths — the *on-screen* reason is the outcome block, owner-gated on `updateOutcome.tool == updateLogFor`, while the log line is unconditional; nothing is written into the buffer, so the logged tail is the manager's own output), a failed unix restart (`restartSelf` — a path-resolution miss or an exec refusal; the Windows branch logs nothing, its hint is planned degradation), and a panic-ended session from `main`. `View`/render steady state and keystrokes are deliberately never logged.
 
diff --git a/README.md b/README.md
index e515486..b8cfd10 100644
--- a/README.md
+++ b/README.md
@@ -61,8 +61,9 @@ Pure TUI, no subcommands; the only flags are `--version` and `--help`.
   draws them as a proportional band in GitHub's own per-language colors
 - **Tags and grouping** — one tag per tool; `space` regroups the flat list under
   section headers, led by everything with a pending update, and back
-- **Run tools** — launch any tracked tool in a new terminal tab (tmux / iTerm2 /
-  kitty / WezTerm / Terminal.app) or in the current window, without leaving keepkit
+- **Run tools** — `enter` runs any tracked tool on an embedded terminal inside
+  keepkit: a TUI like vim or yazi draws and lives in it with the full keyboard,
+  a plain command prints and its final screen stays until you close it
 - **Search** — `/` filters by name and tag with match highlighting and an `N/M` counter
 - **GitHub API token** — a quota gauge in the status bar, plus token management in
   the `a` overlay, lifts the anonymous 60 requests/hour to 5000
@@ -128,7 +129,7 @@ Run `keepkit` — a three-panel interface opens:
 
 - **`[1] Tools`** — the tracker list, each row carrying its installed version:
   search, tag grouping, track / untrack / rename, and `enter` to run the selected
-  tool.
+  tool in an embedded terminal.
 - **`[2] Brief`** — the tool card: the tool's name and repo, its tagline, then a
   metrics strip (installed / latest / maintenance / stars) and a line carrying
   languages, status, tag and note. From here `enter` installs a pending release, the
@@ -392,6 +393,9 @@ subprocess sandbox — is described in [ARCHITECTURE.md](ARCHITECTURE.md).
 - [Glamour](https://github.com/charmbracelet/glamour) — markdown rendering for the README panel
 - [goldmark-emoji](https://github.com/yuin/goldmark-emoji) — GitHub's `:shortcode:` dictionary, used to strip them from a README
 - [x/ansi](https://github.com/charmbracelet/x) — stripping escape sequences from captured tool output
+- [x/xpty](https://github.com/charmbracelet/x) — the pseudo-terminal a tool runs on (unix ptys, Windows ConPTY)
+- [x/vt](https://github.com/charmbracelet/x) — the terminal emulator that turns a tool's output back into a screen
+- [ultraviolet](https://github.com/charmbracelet/ultraviolet) — x/vt's key and cell types, used to translate keystrokes for the running tool
 - [termenv](https://github.com/muesli/termenv) — terminal color-profile detection
 - [go-runewidth](https://github.com/mattn/go-runewidth) — glyph width measurement
 - [golang.org/x/mod/semver](https://pkg.go.dev/golang.org/x/mod/semver) — version comparison
diff --git a/docs/design/tool-overlay.md b/docs/design/tool-overlay.md
new file mode 100644
index 0000000..175b7b7
--- /dev/null
+++ b/docs/design/tool-overlay.md
@@ -0,0 +1,302 @@
+# The tool overlay: running a tracked tool inside keepkit
+
+`enter` in `[1] tools` opens a one-line prompt, and the command you type runs on
+a **pseudo-terminal inside keepkit** — a bordered block over the dimmed layout,
+with the whole keyboard handed to the tool. `vim` draws in it and edits; `fzf`
+filters in it; `rg --version` prints two lines and stops, and the block stays
+put until `esc`. There is one path for all of them.
+
+This replaced a tab launcher that scripted *someone else's* terminal into
+opening a tab (`internal/launcher`: tmux, iTerm2, Terminal.app, kitty, WezTerm,
+plus a `tea.ExecProcess` fallback and an auto-fallback for when an adapter
+failed). That whole package and its recovery machinery are gone; what follows is
+why the current shape is the way it is.
+
+Read this before changing anything in `internal/term`, `internal/model/overlay_term.go`,
+or the `enter` dispatch in `updateRunInput`.
+
+## The one rule everything else follows
+
+**Only `Update` touches the emulator's screen state.**
+
+`vt.Emulator` lives on `Model`, not inside `internal/term`. The pty is read by a
+single goroutine that posts bytes as `tea.Msg`s — the same `waitForChunkCmd`
+pattern the update streamer uses — and the `termChunkMsg` handler is the only
+place that calls `Write`. `Render`, `Resize` and `CursorPosition` are likewise
+reached from `Update`/`View` and nowhere else.
+
+The rule exists because x/vt's screen buffer is not synchronised and the library
+carries an open race issue (charmbracelet/x#879). Keeping every screen-touching
+call on Bubble Tea's own goroutine sidesteps the whole class instead of guarding
+against it call by call.
+
+The **input** path is the one exception, and it is a deliberate, bounded one —
+see below.
+
+## Why input needs a goroutine after all
+
+The plan preferred translating a `tea.KeyMsg` into bytes and calling
+`Session.Write` directly: no second goroutine, and the rule above becomes
+literally true. That turned out to be impossible to do *correctly*.
+
+`vt.SendKey` encodes against emulator state:
+
+```go
+ack := e.isModeSet(ansi.ModeCursorKeys)    // DECCKM: arrows are \x1bOA, not \x1b[A
+akk := e.isModeSet(ansi.ModeNumericKeypad) // DECNKM
+```
+
+`isModeSet` is unexported and nothing surfaces it, and no key encoder is
+exported anywhere in the pinned stack (`ultraviolet` has only output-side
+`Encode*` helpers). A hand-rolled encoder could not know whether the child had
+switched to application cursor keys — the mode `vim` and `less` set on entry.
+Arrows in vim are not a corner case for this feature.
+
+So keys go through the emulator, and `termInput` is the goroutine that reads
+them back out of its input pipe and writes them to the pty. It touches no screen
+state.
+
+Translation splits three ways, by what actually depends on emulator state:
+
+| Keys | How | Why |
+|---|---|---|
+| runes, space | `SendText` | printable text, no encoding decision |
+| arrows, Home/End, PgUp/PgDn, Insert/Delete, shift+tab, F1–F12 | `SendKey` | DECCKM/DECNKM apply |
+| the control range (`KeyEnter`, `KeyEsc`, `KeyCtrlA` …) | the byte itself | Bubble Tea's control key *types are* the control bytes, and none of them is mode-dependent — writing the byte is exactly what vt's encoder produces |
+| ctrl/shift-modified cursor keys | hand-encoded `CSI 1;<mod><final>` | **x/vt encodes none of them** — its `SendKey` default emits nothing when `Mod != 0`, which would silently swallow `ctrl+left` in every editor. Safe to write out because, unlike the bare arrows, the modified forms do not depend on DECCKM |
+| a paste (`KeyRunes` with `Paste: true`) | `Emulator.Paste` | one block of text, not typed keys: `Paste` brackets it with the `?2004` markers exactly when the tool set that mode — without them vim auto-indents every pasted line — and passes it bare to a tool that never asked |
+
+`Alt` is a Bubble Tea flag rather than a key: it becomes an ESC prefix (a paste takes no prefix — it has no modifier).
+
+### Teardown: never call `Emulator.Close()`
+
+This is the sharp edge, and it is load-bearing:
+
+```go
+func (e *Emulator) Read(p []byte) (int, error) {
+	if e.closed { return 0, io.EOF }   // unsynchronised read
+	return e.pr.Read(p)
+}
+
+func (e *Emulator) Close() error {
+	e.closed = true                    // unsynchronised write
+	return e.pw.CloseWithError(io.EOF)
+}
+```
+
+A relay parked in `Read` plus a `Close()` from `Update` is charmbracelet/x#879,
+and `go test -race` reports it immediately — reproduced here, which is why the
+workaround is not speculative.
+
+**`InputPipe()` returns the emulator's `*io.PipeWriter`; closing *that* unblocks
+the parked `Read` through `io.Pipe`'s own synchronisation and never touches the
+bool.** `termInput.stop` does exactly that, falling back to `Close()` only if a
+future x/vt stops handing out an `io.Closer`.
+`TestSessionInputPipeCloseIsRaceFree` is what keeps the next reader from
+reaching for the obvious teardown.
+
+`closeToolOverlay` is the single teardown and its order matters: **session first**
+(so a relay parked in `Session.Write` fails fast), then stop the relay and
+*wait* for it, then drop the emulator. Reversing the first two can park the
+relay in a write nobody will drain.
+
+## esc belongs to the tool
+
+While the tool runs, **every** key is forwarded — `esc`, `ctrl+c`, `q`,
+everything. `esc` is what makes vim usable; `ctrl+c` is the tool's interrupt and
+must not be keepkit's quit. That is the whole meaning of "the tool has the
+keyboard", and it is why `updateToolOverlay` consumes keys it has no use for
+instead of letting them fall through to the normal-mode map.
+
+**`ctrl+\` is the one reserved chord.** It kills the process group and *stays in
+the mode*: the verdict arrives as `termExitMsg`, and that is what turns the
+overlay into its outcome line. Leaving on the keypress would throw away the log
+the user killed something in order to read.
+
+Once the tool has exited the overlay is a still image: `esc` closes it, every
+other key does nothing, and nothing is forwarded because there is nothing left
+to forward to.
+
+Quitting keepkit while the overlay is open is unreachable by design. The way out
+is quitting the tool (or `ctrl+\`), then `esc`. If keepkit itself is killed, the
+closing pty master HUPs the child — accepted.
+
+## Geometry, and the two things that must not move
+
+The block is 70% of the screen in both directions, centred by `ui.PlaceOverlay`.
+`Styles.OverlayBorder` is a rounded border plus `Padding(0, 1)`, so the emulator
+body is `outerW - 4` by `outerH - 2 - 2` — the two rows being the title and the
+exit row. At the 80×24 baseline that is **52×11**, and the baseline succeeding
+is the number that mattered.
+
+Two invariants keep the block still, and they fail differently:
+
+- **The exit row is reserved from the start** — blank while the tool runs. Without
+  it the block would grow by a row at the moment the tool finishes and
+  `PlaceOverlay` would re-centre it vertically.
+- **Every row is padded to the body width.** lipgloss sizes a border to its
+  widest line, so before this the block measured 54 cells running and 53 exited
+  (the title loses its `ctrl+\ kill` hint) and jumped sideways at the exact
+  moment the user starts reading the outcome. `termRow` clamps both directions,
+  ANSI-safely; the case it really exists for is a tool name longer than the body,
+  which would otherwise push the frame past the screen edge where `PlaceOverlay`
+  clips silently.
+
+`termGeometry` returns the size **and** a separate `ok`, because the two callers
+want different things: the keypress refuses on `!ok` (`terminal too small to run
+a tool`, no `lastRun` write — a launch that never started is not remembered),
+while a terminal shrunk *mid-session* clamps to the floor and keeps the tool
+running. Resizing somebody's editor into nothing is bad; killing it outright is
+worse. `!m.ready` is checked first and explicitly, the `toggleZoom` idiom: before
+the first `WindowSizeMsg` every dimension is zero and the percentages would agree
+on a floor-sized overlay by coincidence rather than by measurement.
+
+Resize propagation hangs off **`applyLayout`**, the single relayout point, so it
+cannot drift from it; the emulator is re-laid-out first and the pty told second,
+so the child's redraw lands on a screen that is already the right shape.
+
+## The cursor
+
+The child's cursor is a reverse-video cell while the tool runs, hidden once it
+has exited — a cursor on a dead screen invites typing. The pinned x/vt exposes
+`CursorPosition()` but no visibility accessor, so alive/exited is the whole rule.
+
+The splice goes through `ansi.Truncate`/`ansi.TruncateLeft`, which cut by
+**visible column** and keep the SGR runs on both sides intact. A rune-index cut
+would land inside an escape sequence, which the terminal then executes. Padding
+happens *before* the splice for a related reason: on a short line, a cursor past
+its end would otherwise be spliced in right after the last glyph instead of
+where the tool actually put it.
+
+`ui.Styles.TermCursor` is the only style in the set naming no theme colour, and
+that is the point — reverse video swaps whatever the *tool* painted into that
+cell, which is the only way one style can mark a cursor on a screen keepkit does
+not control. A terminal with no SGR support shows no cursor; a terminal with no
+SGR support cannot show a cursor block anyway.
+
+## The pty session
+
+`internal/term` is the architectural slot `internal/launcher` vacated: bottom of
+the import graph, no TUI knowledge, no config paths, no `logx` — a failure rides
+`Exit.Err` to the caller, which is the surface that can actually show it. That is
+why it needs no `TestMain` seam.
+
+`Session` owns one pty and one reader goroutine. Events leave through
+`Events() <-chan Event`: zero or more `Data`, then exactly one `Exit`, then the
+channel closes. The channel is buffered (64) so the reader stays ahead of a
+consumer that drains once per Bubble Tea message; past it the reader blocks and
+the child is throttled, which is the correct back-pressure.
+
+Three rules inside it:
+
+- **A pty read error is never the verdict.** A master whose child has exited
+  answers `EIO` on Linux and EOF on macOS, and one closed by `Kill`/`Close`
+  answers `os.ErrClosed`. All three are normal termination; what happened comes
+  from `xpty.WaitProcess`, which also synthesises the `*exec.ExitError` that
+  `os.Process.Wait` fails to produce on ConPTY.
+- **`Elapsed` and `Killed` are stamped in the goroutine.** `time.Now()` inside
+  `Update` would make completion non-deterministic in tests, and only the
+  session knows whether an exit followed a kill — making the model correlate its
+  own keypress against `signal: killed` would be guesswork.
+- **Never call `proc.DetachTTY` on the pty command.** xpty sets neither `Setsid`
+  nor `Setctty` (its `Start` only wires stdio), so `internal/term` sets them
+  itself; `DetachTTY` assigns `SysProcAttr` wholesale and would drop them,
+  leaving the child with no controlling terminal — the exact opposite of the
+  point. `Setsid` is also what makes the unix child a process-group leader, so
+  `proc.KillGroup`'s negative-pid signal reaches the tools an `sh -c` line
+  started.
+
+The model builds argv with its existing `shellCommand`, which is what keeps
+`internal/term` goos-agnostic.
+
+## Message flow, and the ordering that is easy to break
+
+```
+enter (prompt) → startTermCmd ──► termStartedMsg{session}
+                                       │  Update creates the emulator here
+                                       ▼
+                            waitForTermChunkCmd ──► termChunkMsg{data, exit?}
+                                       ▲                    │
+                                       └────────────────────┘
+                                                            │ exit != nil
+                                                            ▼
+                                                      termExitMsg
+```
+
+`waitForTermChunkCmd` folds everything already queued into one message — a
+full-screen redraw arrives as several reads and repainting once per read would
+spend a frame on each.
+
+**The drain carries the exit rather than swallowing it.** A Go channel cannot be
+un-read, so when the drain runs into the final event it has nowhere to put it
+back; it rides on `termChunkMsg.exit`, the handler writes the data first and
+re-emits the exit as the *next* message. Delivering the exit before the data it
+followed would lose a short-lived tool's final screen, which is precisely what
+esc-after-exit exists to show.
+
+Two guards that are structural, not cosmetic:
+
+- **A chunk whose session is not the current one is dropped without
+  re-subscribing.** A dead session's channel must not keep a command chain alive.
+- **A `termStartedMsg` arriving outside the mode is killed and closed, not
+  adopted.** A start that lost its race with `esc` would otherwise strand a live
+  pty nothing can reach.
+- **Keys before `termStartedMsg` are dropped.** The window is milliseconds, but a
+  nil deref there would re-panic through `logx.Recover` and take keepkit down.
+
+## The outcome line
+
+The reserved row fills in with one of four verdicts, built from the update
+block's own helpers (`formatElapsed`, `fitCells`, `footerSep`):
+
+```
+✓ exited · 12s · esc close
+✕ exit 3 · 4s · esc close
+✕ killed · 1m30s · esc close
+✕ failed to start · no such file · esc close
+```
+
+A start failure spends the middle cell on its reason rather than on an elapsed
+it does not have. There is **no status message** on exit: the screen the tool
+left behind is the answer and this row is the caption on it. The status bar gets
+a branch of its own for the same reason the siblings have one — without it the
+bar would go on advertising six global keys the running tool has taken over,
+including a `q quit` that cannot fire.
+
+A tool that is not installed needs no special handling: `sh` reports it and exits
+127, which the `✕ exit 127` line shows. That replaced the old `notFoundExit`
+mapping the tab launcher needed.
+
+## What was deleted, and what that bought
+
+`internal/launcher` (the five-adapter detection chain, `Plan`, `appleScriptQuote`)
+and, in the model: `startLaunchCmd`, `execToolCmd`, `launchDoneMsg`/`execDoneMsg`,
+`m.launchingFor`, `pendingLaunchName`/`Command`, `flushPendingLaunch` and every
+modal-return call site it wrapped, `launchTimeout`, `launchFallbackStatus`,
+`notFoundExit`, and `setStickyStatus` (whose only callers were the two launch
+statuses).
+
+Most of that existed to survive an adapter failing — a fallback, a deferred
+fallback for when the fallback could not seize the terminal safely, a guard so
+two of them could not run at once, and a sticky status because the in-flight
+message had to outlive its own timer. None of it has anything to answer now: the
+overlay is keepkit's own screen, there is no adapter to fail and no terminal to
+seize. One mode replaced the lot.
+
+`shellCommand` survives and now builds argv for the pty. Its deliberate duplicate
+in `updater.customPlan` still must not drift.
+
+## Known limits
+
+- **Windows works via ConPTY but is untested at runtime** — CI only
+  cross-compiles, the same level of assurance as `restart_windows`. `ConPty.Start`
+  populates `cmd.Process`, so `proc.KillGroup`'s Windows branch needs no change.
+- **Mouse is not proxied.** `SendMouse` exists; nothing wanted it yet.
+- **Child OSC title and bell events are ignored.**
+- **Wide graphemes split across two reads can render wrong** (charmbracelet/x#935).
+  The reader delivers large chunks and the failure is cosmetic and transient.
+- **Working directory is inherited** from keepkit, not from anything the tool
+  chose.
+
+`docs/research/pty-stack.md` records why this stack was chosen, what was
+rejected, and every pinned version's reason.
diff --git a/docs/design/updating.md b/docs/design/updating.md
index 6775847..67e893c 100644
--- a/docs/design/updating.md
+++ b/docs/design/updating.md
@@ -8,7 +8,7 @@ Read this before touching `internal/updater`,
 update rides this same pipeline; its banner, version gate and restart are described in
 [`self-update.md`](self-update.md).
 
-- **Update (`enter` in `focusBrief`)**: installs a newer release from inside the TUI. `enter` fires the card's primary action in `focusBrief` (in `focusTools` the same key runs the selected tool); it requires `hasUpdate(name)` (else `statusMsg`) and reports the shared `updateBusyStatus` (`another update is running`) while `updatingFor != ""` instead of starting a second one (one update at a time, no queue; the same wording `[U]` uses, since the running update's only other sign is a card spinner invisible unless that tool is selected). The whole guard sequence lives in `startToolUpdate()` — a **pointer receiver**, because it sets a status message, and its caller assigns the command before returning `m`, since Go copies the model into the return before evaluating the second operand. It fires `detectUpdateCmd(t, false)` — detection spawns subprocesses (`go version -m`, `cargo install --list`) so it must never run inside `Update()`, same as every other probe. `updater.Detect` runs the brew → go → cargo → pipx → uv → pnpm → bun → npm chain. **Order is load-bearing twice**: brew before go, so a brew-installed Go binary with buildinfo isn't misrouted, and pnpm/bun before npm, because both layouts carry `node_modules` segments the npm step claims on sight — a bun global (`$BUN_INSTALL/bin/<bin>` → `install/global/node_modules/<pkg>/…`) really did resolve to `npm install -g <pkg>`, the wrong manager, installing a duplicate under npm's prefix that the bun copy keeps shadowing on `PATH`. Five steps are **path-convention** based (cargo, pipx, uv, pnpm, bun), and an empty root switches its own step off — enforced **inside `underDir`/`segmentUnder`**, which answer "no match" for an empty dir, deliberately *not* by a `!= ""` guard repeated at each step. The hazard is real: `filepath.Rel("", "bin/exa")` succeeds and yields `bin/exa`, so a **relative** path reads as living under every disabled root, and one forgotten copy of the guard silently claims it. It lived as six hand-copied copies of that one convention until the review that turned it into one definition — the same lesson as `version.applyReleaseOutcome` (`TestPathHelpersRejectEmptyDir`, plus a per-step `empty <root> leaves a relative path undetected` row): `uv` = `segmentUnder(realPath, uvTools)` → `uv tool upgrade <pkg>`; `pnpm` = `underDir(realPath, pnpmHome)` plus a name from the shim target or the resolved path → `pnpm add -g <pkg>`; `bun` = `underDir(realPath, bunInstall)` + `npmPackage(realPath)` → `bun add -g <pkg>`. **`add -g`, not `update -g`**: `update` honours the semver range saved at install time and can silently refuse a major bump, while keepkit promises the version the card shows as `latest:`. A manager's own binary carries no `node_modules` segment and no shim target, so it falls through — `bun upgrade`/`pnpm self-update` are deliberately out of scope. **All five roots** come from **`managerDirsFrom(getenv, home, goos)`** (pure core, `resolveManagerDirs()` wrapper — the `launcher.planFor` idiom), and carrying cargo/pipx there too is what lets `detectFromPath` stop calling `homeDir()`, making its "no I/O, no environment" contract literally true instead of nearly true. cargo and pipx stay home-derived with **no env var of their own** — `$CARGO_HOME`/`$PIPX_HOME` are not consulted, exactly as before the struct existed, since honouring them changes behaviour for anyone who sets them and belongs in its own commit. `<home>/.cargo/bin` and `<home>/.local/pipx/venvs`; `$UV_TOOL_DIR` else `$XDG_DATA_HOME/uv/tools` else `~/.local/share/uv/tools` (macOS included — uv is XDG there too; **Windows env-only**, its layout is unverified and a wrong guess beats no guess only in the wrong direction), `$PNPM_HOME` else `~/Library/pnpm` (darwin) / `$XDG_DATA_HOME/pnpm` else `~/.local/share/pnpm` (linux) / `%LOCALAPPDATA%\pnpm` (windows), `$BUN_INSTALL` else `~/.bun`. An empty field is a *disabled* check, which is what keeps the zero-value `managerDirs{}` backwards compatible. The wrapper then **expands symlinks in every one of the five roots** (`resolveDir` → `filepath.EvalSymlinks`, falling back to the raw path when it does not resolve — a root that does not exist yet is the normal state for an uninstalled manager and must stay a harmless *non-match* rather than becoming an empty, i.e. disabled, field). That expansion is load-bearing, not hygiene: `Detect` compares these roots against an `EvalSymlinks`-**resolved** binary path, so a root carrying any symlink component — a relocated `~/.bun` → `/mnt/big/bun`, a home on a secondary volume, `/home` under autofs, and on macOS `/var` → `/private/var`, which is what made every fixture test here need `EvalSymlinks(t.TempDir())` — silently fails to match. For uv and pnpm's shim/store layouts that only costs the update offer, but a bun global and a legacy pnpm one still carry a plain `node_modules/<pkg>` segment, so the npm step claims them and offers `npm install -g <pkg>` — the exact duplicate-install misdetection this chain exists to prevent, measured on all five layouts and pinned by `TestDetectSymlinkedManagerRoot`. The expansion is a **loop over pointers to all five fields**, so a sixth field added to `managerDirs` but forgotten there would resolve to a root nothing can ever match; `TestResolveManagerDirsExpandsSymlinks` asserts all five at once as the guard. **pnpm needs a second signal** because its globals are not symlinks at all: `$PNPM_HOME/bin/<name>` is a cmd-shim `/bin/sh` script `EvalSymlinks` resolves to itself, whose last line — `# cmd-shim-target=<abs path>` — is the only machine-readable link to the owning package. `Detect` reads it (best-effort, capped at `pnpmShimMaxBytes` = 8 KiB against real shims of ~1.5 KiB, and **only** when the found path sits under a non-empty `pnpmHome` — reading every binary on `PATH` to look for a comment would be an open per detection) through `readPnpmShim` → the pure `pnpmShimTarget` (last marker wins: cmd-shim writes it as the final line). A file **over** the cap is rejected whole (`LimitReader(cap+1)` + a length check, `getReadme`'s idiom) rather than parsed truncated, and that is a correctness guard, not tidiness: a cut landing inside the marker line hands the parser a *shortened* path, and `…/node_modules/typescript/…` shortened to `…/node_modules/types` yields `types` — a real package on npm, so the chain would offer a confidently wrong `pnpm add -g types` where everything else here degrades honestly (`TestReadPnpmShim`'s oversized row, whose fixture asserts the truncated parse *would* have said `types`), and passes it into the core as `shimTarget` exactly the way `goBuildinfo` rides in; an unreadable file yields `""`, i.e. the check simply has no signal. Two npm-side consequences of the pnpm layout: `npmPackage` **refuses a bare scope** (`…/node_modules/@angular` with nothing after it is a directory holding packages, not one — returning it offered `pnpm add -g @angular`, and the pnpm step feeds this function a *shim target*, i.e. file content nothing validated) and **skips a post-`node_modules` segment starting with `.`** (`.pnpm` is the virtual store, `.bin` the shim dir — never package names) and keeps scanning, and the **npm step refuses any path through `/node_modules/.pnpm/`** — such a path reaching npm means a pnpm layout the pnpm step failed to attribute, and `npm install -g <pkg>` there is the duplicate-install failure again, so the chain falls through to `ErrUnknownManager` + the `update_cmd` hint (honest degradation). Detection is convention-based end to end: a future layout change makes its check miss *silently* and degrade to the hint, never to a wrong command. A `update_cmd` in `meta.yaml` always wins and runs via the platform shell — `sh -c`, or `cmd /c` on Windows, so a `winget`/PowerShell `update_cmd` needs no Git Bash (`customPlan(goos, cmd)`, the pure goos-parameterized core, deliberate sibling of `model`'s `shellCommand`) — and skips detection entirely. The chain starts from `exec.LookPath(t.Name)`, and a **miss there is not the end**: the tracked name can still be a brew formula whose binaries are named differently — `rust` ships `rustc`/`cargo`, so `LookPath("rust")` misses while `brew upgrade rust` is exactly right — so `brewNamePlan` checks for a `Cellar/<name>`/`Caskroom/<name>` directory before `ErrUnknownManager` is returned. **An exhausted chain takes the same fallback**: a binary can be found and still belong to no known manager — a Homebrew cask app keeps its launcher on `PATH` while the executable lives inside the `.app` bundle (`agterm`), matching neither the Cellar regex nor any later step — so `Detect` retries `brewNamePlan` on `ErrUnknownManager` from `detectFromPath` too (`TestDetectBrewByNameChainExhausted`). Both sites are self-validating (they fire only when such a keg actually exists) and share `version.brewDirVersion`'s traversal guard: a name carrying `/` or `\` can't be a formula name and must not turn the `Join` into a traversal. The `updateDetectedMsg` handler drops a stale result through the shared predicate **`acceptsUpdateDetect(msg)`**: both paths refuse while `updatingFor != ""` and while `m.mode != modeNormal` (detection spawns subprocesses and can answer seconds later — a confirm dialog opening under an editor, a search or an overlay steals the keystroke aimed at it, the mirror of `launchDoneMsg`'s mode gate), and beyond that a *tool* result must still match the selection while keepkit's own has no selection to match. It maps `ErrUnknownManager` to a `statusMsg` hint (`no known updater for <name> — set update_cmd or [o] releases` — no dead-end dialog; the wording branches on **`isSelfUpdate(msg.tool)`**, not on `msg.self`, so the identical failure of the identical binary reads the same from `enter` on a tracked `keepkit` row as from `[U]` — `msg.self` keeps the one meaning only it has, "no selection to match", inside `acceptsUpdateDetect`), and on success stores `m.updatePlan` plus **`m.updateTarget = msg.tool`** and enters `modeConfirmUpdate`. The target is resolved *there*, not when enter is pressed: a selection that moved while detection ran can no longer retarget the dialog, and keepkit's own update — which has no row, and no selection at all with an empty tracker — needs no second identity. The confirm status bar shows `update <updateTarget>: <plan.Display>  enter run  esc cancel`; `enter` sets `m.updatingFor`/`m.updateLogFor` to that target, resets the log, and fires `startUpdateCmd` (any other key cancels, not just `esc`, and clears `updateTarget` with the plan it named). The `enter update to <v>` cell leads the `[2]` panel footer only when `hasUpdate(selected)`.
+- **Update (`enter` in `focusBrief`)**: installs a newer release from inside the TUI. `enter` fires the card's primary action in `focusBrief` (in `focusTools` the same key runs the selected tool); it requires `hasUpdate(name)` (else `statusMsg`) and reports the shared `updateBusyStatus` (`another update is running`) while `updatingFor != ""` instead of starting a second one (one update at a time, no queue; the same wording `[U]` uses, since the running update's only other sign is a card spinner invisible unless that tool is selected). The whole guard sequence lives in `startToolUpdate()` — a **pointer receiver**, because it sets a status message, and its caller assigns the command before returning `m`, since Go copies the model into the return before evaluating the second operand. It fires `detectUpdateCmd(t, false)` — detection spawns subprocesses (`go version -m`, `cargo install --list`) so it must never run inside `Update()`, same as every other probe. `updater.Detect` runs the brew → go → cargo → pipx → uv → pnpm → bun → npm chain. **Order is load-bearing twice**: brew before go, so a brew-installed Go binary with buildinfo isn't misrouted, and pnpm/bun before npm, because both layouts carry `node_modules` segments the npm step claims on sight — a bun global (`$BUN_INSTALL/bin/<bin>` → `install/global/node_modules/<pkg>/…`) really did resolve to `npm install -g <pkg>`, the wrong manager, installing a duplicate under npm's prefix that the bun copy keeps shadowing on `PATH`. Five steps are **path-convention** based (cargo, pipx, uv, pnpm, bun), and an empty root switches its own step off — enforced **inside `underDir`/`segmentUnder`**, which answer "no match" for an empty dir, deliberately *not* by a `!= ""` guard repeated at each step. The hazard is real: `filepath.Rel("", "bin/exa")` succeeds and yields `bin/exa`, so a **relative** path reads as living under every disabled root, and one forgotten copy of the guard silently claims it. It lived as six hand-copied copies of that one convention until the review that turned it into one definition — the same lesson as `version.applyReleaseOutcome` (`TestPathHelpersRejectEmptyDir`, plus a per-step `empty <root> leaves a relative path undetected` row): `uv` = `segmentUnder(realPath, uvTools)` → `uv tool upgrade <pkg>`; `pnpm` = `underDir(realPath, pnpmHome)` plus a name from the shim target or the resolved path → `pnpm add -g <pkg>`; `bun` = `underDir(realPath, bunInstall)` + `npmPackage(realPath)` → `bun add -g <pkg>`. **`add -g`, not `update -g`**: `update` honours the semver range saved at install time and can silently refuse a major bump, while keepkit promises the version the card shows as `latest:`. A manager's own binary carries no `node_modules` segment and no shim target, so it falls through — `bun upgrade`/`pnpm self-update` are deliberately out of scope. **All five roots** come from **`managerDirsFrom(getenv, home, goos)`** (pure core, `resolveManagerDirs()` wrapper — the `configdir.baseFor` idiom), and carrying cargo/pipx there too is what lets `detectFromPath` stop calling `homeDir()`, making its "no I/O, no environment" contract literally true instead of nearly true. cargo and pipx stay home-derived with **no env var of their own** — `$CARGO_HOME`/`$PIPX_HOME` are not consulted, exactly as before the struct existed, since honouring them changes behaviour for anyone who sets them and belongs in its own commit. `<home>/.cargo/bin` and `<home>/.local/pipx/venvs`; `$UV_TOOL_DIR` else `$XDG_DATA_HOME/uv/tools` else `~/.local/share/uv/tools` (macOS included — uv is XDG there too; **Windows env-only**, its layout is unverified and a wrong guess beats no guess only in the wrong direction), `$PNPM_HOME` else `~/Library/pnpm` (darwin) / `$XDG_DATA_HOME/pnpm` else `~/.local/share/pnpm` (linux) / `%LOCALAPPDATA%\pnpm` (windows), `$BUN_INSTALL` else `~/.bun`. An empty field is a *disabled* check, which is what keeps the zero-value `managerDirs{}` backwards compatible. The wrapper then **expands symlinks in every one of the five roots** (`resolveDir` → `filepath.EvalSymlinks`, falling back to the raw path when it does not resolve — a root that does not exist yet is the normal state for an uninstalled manager and must stay a harmless *non-match* rather than becoming an empty, i.e. disabled, field). That expansion is load-bearing, not hygiene: `Detect` compares these roots against an `EvalSymlinks`-**resolved** binary path, so a root carrying any symlink component — a relocated `~/.bun` → `/mnt/big/bun`, a home on a secondary volume, `/home` under autofs, and on macOS `/var` → `/private/var`, which is what made every fixture test here need `EvalSymlinks(t.TempDir())` — silently fails to match. For uv and pnpm's shim/store layouts that only costs the update offer, but a bun global and a legacy pnpm one still carry a plain `node_modules/<pkg>` segment, so the npm step claims them and offers `npm install -g <pkg>` — the exact duplicate-install misdetection this chain exists to prevent, measured on all five layouts and pinned by `TestDetectSymlinkedManagerRoot`. The expansion is a **loop over pointers to all five fields**, so a sixth field added to `managerDirs` but forgotten there would resolve to a root nothing can ever match; `TestResolveManagerDirsExpandsSymlinks` asserts all five at once as the guard. **pnpm needs a second signal** because its globals are not symlinks at all: `$PNPM_HOME/bin/<name>` is a cmd-shim `/bin/sh` script `EvalSymlinks` resolves to itself, whose last line — `# cmd-shim-target=<abs path>` — is the only machine-readable link to the owning package. `Detect` reads it (best-effort, capped at `pnpmShimMaxBytes` = 8 KiB against real shims of ~1.5 KiB, and **only** when the found path sits under a non-empty `pnpmHome` — reading every binary on `PATH` to look for a comment would be an open per detection) through `readPnpmShim` → the pure `pnpmShimTarget` (last marker wins: cmd-shim writes it as the final line). A file **over** the cap is rejected whole (`LimitReader(cap+1)` + a length check, `getReadme`'s idiom) rather than parsed truncated, and that is a correctness guard, not tidiness: a cut landing inside the marker line hands the parser a *shortened* path, and `…/node_modules/typescript/…` shortened to `…/node_modules/types` yields `types` — a real package on npm, so the chain would offer a confidently wrong `pnpm add -g types` where everything else here degrades honestly (`TestReadPnpmShim`'s oversized row, whose fixture asserts the truncated parse *would* have said `types`), and passes it into the core as `shimTarget` exactly the way `goBuildinfo` rides in; an unreadable file yields `""`, i.e. the check simply has no signal. Two npm-side consequences of the pnpm layout: `npmPackage` **refuses a bare scope** (`…/node_modules/@angular` with nothing after it is a directory holding packages, not one — returning it offered `pnpm add -g @angular`, and the pnpm step feeds this function a *shim target*, i.e. file content nothing validated) and **skips a post-`node_modules` segment starting with `.`** (`.pnpm` is the virtual store, `.bin` the shim dir — never package names) and keeps scanning, and the **npm step refuses any path through `/node_modules/.pnpm/`** — such a path reaching npm means a pnpm layout the pnpm step failed to attribute, and `npm install -g <pkg>` there is the duplicate-install failure again, so the chain falls through to `ErrUnknownManager` + the `update_cmd` hint (honest degradation). Detection is convention-based end to end: a future layout change makes its check miss *silently* and degrade to the hint, never to a wrong command. A `update_cmd` in `meta.yaml` always wins and runs via the platform shell — `sh -c`, or `cmd /c` on Windows, so a `winget`/PowerShell `update_cmd` needs no Git Bash (`customPlan(goos, cmd)`, the pure goos-parameterized core, deliberate sibling of `model`'s `shellCommand`) — and skips detection entirely. The chain starts from `exec.LookPath(t.Name)`, and a **miss there is not the end**: the tracked name can still be a brew formula whose binaries are named differently — `rust` ships `rustc`/`cargo`, so `LookPath("rust")` misses while `brew upgrade rust` is exactly right — so `brewNamePlan` checks for a `Cellar/<name>`/`Caskroom/<name>` directory before `ErrUnknownManager` is returned. **An exhausted chain takes the same fallback**: a binary can be found and still belong to no known manager — a Homebrew cask app keeps its launcher on `PATH` while the executable lives inside the `.app` bundle (`agterm`), matching neither the Cellar regex nor any later step — so `Detect` retries `brewNamePlan` on `ErrUnknownManager` from `detectFromPath` too (`TestDetectBrewByNameChainExhausted`). Both sites are self-validating (they fire only when such a keg actually exists) and share `version.brewDirVersion`'s traversal guard: a name carrying `/` or `\` can't be a formula name and must not turn the `Join` into a traversal. The `updateDetectedMsg` handler drops a stale result through the shared predicate **`acceptsUpdateDetect(msg)`**: both paths refuse while `updatingFor != ""` and while `m.mode != modeNormal` (detection spawns subprocesses and can answer seconds later — a confirm dialog opening under an editor, a search or an overlay steals the keystroke aimed at it, and under the tool overlay it steals one the running tool is waiting for), and beyond that a *tool* result must still match the selection while keepkit's own has no selection to match. It maps `ErrUnknownManager` to a `statusMsg` hint (`no known updater for <name> — set update_cmd or [o] releases` — no dead-end dialog; the wording branches on **`isSelfUpdate(msg.tool)`**, not on `msg.self`, so the identical failure of the identical binary reads the same from `enter` on a tracked `keepkit` row as from `[U]` — `msg.self` keeps the one meaning only it has, "no selection to match", inside `acceptsUpdateDetect`), and on success stores `m.updatePlan` plus **`m.updateTarget = msg.tool`** and enters `modeConfirmUpdate`. The target is resolved *there*, not when enter is pressed: a selection that moved while detection ran can no longer retarget the dialog, and keepkit's own update — which has no row, and no selection at all with an empty tracker — needs no second identity. The confirm status bar shows `update <updateTarget>: <plan.Display>  enter run  esc cancel`; `enter` sets `m.updatingFor`/`m.updateLogFor` to that target, resets the log, and fires `startUpdateCmd` (any other key cancels, not just `esc`, and clears `updateTarget` with the plan it named). The `enter update to <v>` cell leads the `[2]` panel footer only when `hasUpdate(selected)`.
   - **Streaming** (channel + re-subscribe idiom, no `*tea.Program`): `startUpdateCmd` runs the plan via `exec.Command` + `proc.DetachTTY` (10-min deadline; a sudo prompt fails fast instead of hanging — deliberate), with stdout+stderr merged into one pipe. **Reader ordering is load-bearing** (os/exec forbids `Wait` before pipe reads finish): the goroutine scans the pipe to EOF via `streamLines` → then `cmd.Wait()` → sends the exit error as a final `updateLine{done:true, err}` → then `close(ch)`. `waitForChunkCmd` does one receive → `updateChunkMsg`; a done item or closed channel → `updateDoneMsg`. The channel carries a typed `updateLine{text, replace, done, err, elapsed}` (not `chan string`) so the `replace` flag, the completion error and the duration all ride the same channel — no second error channel threaded through every re-subscribe. **`elapsed` is stamped here, after `Start` returns**, and not in the `updateDoneMsg` handler: `time.Now()` inside `Update()` would make completion non-deterministic in every test that drives it, while this is where the process actually lives. The two early returns (empty argv, a `StdoutPipe`/`Start` error) never reach the stamp and report zero, which the outcome block reads as "it never ran" and prints no duration cell for. Each segment is sanitized through `cleanTerminalOutput` (which already strips ANSI) at the boundary; `streamLines` splits on `\n` **and** `\r`, and a `\r` segment sets `replace` so brew/npm progress bars collapse to one updating line. `m.updateLog` is capped at ~500 lines (tail matters). On deadline, `proc.KillGroup` SIGKILLs the process group (negative pid — `DetachTTY`'s `Setsid` makes the child a session leader, so a plain kill would orphan `sh -c` grandchildren). **That is the unix path only.** On Windows there is no process group to signal: `proc.KillGroup` degrades to `Process.Kill` on the direct child, so a deadline kill ends the `cmd /c` wrapper while the real updater (`winget`, `powershell`) survives — still holding the pipe write handle it inherited. No EOF means `streamLines` never returns, so `cmd.Wait()` is never reached, the `done` item is never sent and `updatingFor` stays set for the rest of the session (every later update answers `another update is running`). `cmd.WaitDelay` does **not** fix it — `StdoutPipe` creates no copier goroutine, so `c.goroutineErr` is nil and os/exec's force-close of `parentIOPipes` only ever runs from inside `Wait()`, which is exactly what the drain is blocking. The fix is a real Windows process-tree kill (a Job Object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, or `taskkill /T /F`) in `internal/proc`; it is deferred alongside the `cmd /c` quoting caveat until a real Windows report justifies untestable per-GOOS code (no Windows runner executes this suite — CI cross-compiles only).
   - **Live log in `[3]`**: `m.updateLog []string` is a single active-session buffer (not a map); `m.updateLogFor` names its tool. Every site that asks "does the log own panel `[3]`?" asks the **single predicate `showsUpdateLog()`** (defined in [`self-update.md`](self-update.md)), never `updateLogFor` directly: `renderHelpContent()` returns the log **ahead of** the `helpLoadingFor`/cache branches, and `autoFetchCmdsForSelected` skips the help fetch (and `helpLoadingFor` set) — otherwise re-selecting the tool paints `Loading...` or a late `helpOutputMsg` clobbers the live log. The panel title comes from **`updateLogTitle()`** (same `insetPanelTitle` path as `[3] help`/`[3] man`, and the source hints are dropped with it): `[3] update` while one runs, then `[3] update finished` / `[3] update failed` once the session has ended. One string feeds both the title and the footer's source cell, so the two can never disagree about whether an update is still running, and a reader who has scrolled away from the end of a long log still learns it ended. **Words, not the block's own `✓`/`✕`**: `insetPanelTitle` measures the title in **runes**, not cells, so an East-Asian-Ambiguous glyph there renders two cells wide under `RUNEWIDTH_EASTASIAN=1` and pushes the top border out by one — inside the viewport the same glyphs are harmless, which is why the block keeps them. The panel autoscrolls to bottom on each chunk, and the buffer persists after completion until the next update. For a *tool* update the claim is per tool: navigating away shows the other tool's normal help; back shows the live log.
   - **Spinner + completion**: `m.updatingFor` twins `refreshingFor` — card title `updating <name> <spinner>`; the `spinner.TickMsg` gate is `refreshingFor != "" || updatingFor != ""` (or the spinner freezes after one frame). The `updateDoneMsg` handler clears `updatingFor`; success → `statusMsg "updated <name>"` + `fetchInstalledCmd(t)` (the version merge extinguishes `↑` and the existing by-name cursor remap moves the tool out of the update group); failure → `statusMsg "update failed — see [3]"`. A tool untracked mid-update just clears `updatingFor` (no re-fetch, no crash).
diff --git a/docs/plans/completed/20260814-tool-overlay-terminal.md b/docs/plans/completed/20260814-tool-overlay-terminal.md
new file mode 100644
index 0000000..046700c
--- /dev/null
+++ b/docs/plans/completed/20260814-tool-overlay-terminal.md
@@ -0,0 +1,267 @@
+# Tool overlay terminal: run tracked tools in an embedded PTY overlay
+
+## Overview
+
+- `enter` on the selected tool in `[1] tools` keeps opening the `modeRunInput` prompt (prefill: tool name / `lastRun`, editable), but the dispatched command now runs in an **embedded terminal overlay inside keepkit** (~70% of the screen, centered, `PlaceOverlay`-dimmed background) instead of a new terminal tab.
+- One path for everything — **no TUI-vs-CLI distinction**: a TUI (vim/yazi/fzf) draws and lives in the overlay with the full keyboard proxied to it; a plain CLI prints and exits, and the overlay stays with the final screen + exit status until dismissed with `esc`.
+- While the process is alive **every key (esc included) goes to the tool**; `ctrl+\` is the one reserved chord (kill). After exit, `esc` closes. This is the biggest feature of the project and **replaces the tab launcher entirely** — `internal/launcher`, the auto-fallback and `tea.ExecProcess` are deleted.
+
+## Context (from discovery)
+
+- Stack (researched 2026-08, decided): `github.com/charmbracelet/x/xpty` **v0.1.4** (tagged; unix pty via creack/pty + Windows **ConPTY**) + `github.com/charmbracelet/x/vt` (**untagged — pin the pseudo-version**; VT220+truecolor emulator: `NewEmulator(w, h)`, `Write` pty bytes in, `Render()` ANSI string out, `Resize`, `SendKey`/`SendText`, `InputPipe()`). Rejected: creack/pty direct (no Windows — ConPTY never merged), `taigrr/bubbleterm` (needs Bubble Tea v2; crib its emulator↔Model wiring only).
+- x/vt has an open race issue (charmbracelet/x#879, Read/Close) and grapheme-split issue (#935) → **architecture rule: only `Update` touches the emulator's screen state**; the pty is read by one goroutine posting chunks as `tea.Msg`s — the `waitForChunkCmd` pattern from the update streamer. Note the rule sidesteps the *screen-buffer* races; the input path gets its own treatment (Task 1 decides between a key→bytes encoder — preferred, zero extra goroutines — and an `InputPipe` copy goroutine with an explicit lifecycle).
+- x/vt master pulls `charmbracelet/ultraviolet` (Bubble Tea v2 rendering core) into the module graph and will likely bump `x/ansi` (pinned v0.11.6 — `ui.StripANSI` delegates to it), `x/cellbuf`, `colorprofile` — all transitive deps of lipgloss/glamour, i.e. **the dependency bump alone can move every render test**. Task 1's gate is therefore the full suite, not the new package.
+- Existing anchors (verified by review): `shellCommand` (`internal/model/commands.go:117`) stays — the model builds argv with it and hands it to `term.Start`. `updateRunInput` (`internal/model/mode.go:330`) is the dispatch point to rewire; its refusal path deliberately skips the `lastRun` write (`mode.go:346`). `setStickyStatus`'s only callers are the two launch statuses (`mode.go:353`, `mode.go:371`) — it dies with them, plus `TestInFlightStatusSurvivesStaleExpiry` in `status_test.go`. `mode_test.go`'s `TestRunInputEnterStoresLastRun` asserts the post-enter mode and **will break at the switch** — it is in Task 5's file list.
+- keepkit is on bubbletea v1.3.10; x/vt works in a v1 app — `Render()` returns a plain ANSI string.
+- Patterns to follow: update streamer (`startUpdateCmd`/`waitForChunkCmd`, elapsed stamped in the cmd, never in `Update`), `modeAPIStatus` modality, `updateOutcomeBlock`'s helpers (`formatElapsed`, `fitCells`, `footerSep` — `render.go:2370`) for the exit line, the `restarter` narrow-interface idiom from main.go for the session seam, `toggleZoom`'s `!m.ready`-first refusal idiom.
+
+## Development Approach
+
+- **testing approach**: Regular (code first, then tests in the same task)
+- complete each task fully before moving to the next
+- make small, focused changes; the old launch path stays intact and green until the single switch-over task (Task 5)
+- **CRITICAL: every task MUST include new/updated tests** for code changes in that task
+  - tests are not optional - they are a required part of the checklist
+  - unit tests for new and modified functions, covering success and error scenarios
+- **CRITICAL: all tests must pass before starting next task** (`go test -race ./...`) - no exceptions
+- **CRITICAL: update this plan file when scope changes during implementation** (➕/⚠️ prefixes)
+- no meta.yaml schema changes; no config files written by this feature
+
+## Testing Strategy
+
+- **unit tests**: required for every task; the per-task gate is `go build ./...` + `go vet ./...` + `go test -race ./...` + `golangci-lint run` (full tree, not just the touched package — see the dependency-bump note above), plus `GOOS=windows go build ./...` wherever a build tag or dependency changes. Note: every symbol added in Tasks 2–4 is unreferenced from non-test code until Task 5 — **its own task's tests are what keep `unused` quiet**.
+- **e2e tests**: none in this project (TUI verified by model-level tests, per existing convention); x/vt being pure Go means even alt-screen/truecolor rendering is assertable in model tests
+- **real pty**: only in `internal/term`'s own tests (unix `sh -c echo …`, no network), under `-race`. `internal/term` writes no config and does no `logx` logging (failures ride `Exit.Err`), so it needs no `TestMain` seam — stated in the package doc, not left as an omission.
+- **model tests never execute the cmd returned by the run-prompt enter** — it would spawn a real pty; assert on the returned cmd/state only (the `assertOnlyExpiryTick` hazard).
+
+## Progress Tracking
+
+- mark completed items with `[x]` immediately when done
+- add newly discovered tasks with ➕ prefix
+- document issues/blockers with ⚠️ prefix
+- keep plan in sync with actual work done
+
+## Solution Overview
+
+- New package **`internal/term`** — bottom of the import graph, no TUI knowledge (the architectural slot `internal/launcher` vacates): `Session` owns the pty lifecycle. The **model builds argv with its existing `shellCommand`** and passes it to `term.Start` — `internal/term` stays goos-agnostic and needs no duplicate. `Start` creates the `xpty.Pty`, starts **one reader goroutine** pty → chunk channel; the exit (err + elapsed, stamped in the goroutine) lands as the final event on the same channel, then the channel closes.
+- **`vt.Emulator` lives on `Model`, not in `internal/term`**: only `Update` writes to its screen state (`termChunkMsg` → `m.termEmu.Write`). Input: ⚠️ *decided in Task 1* — the preferred encoder **does not exist** in the pinned stack and could not be written correctly (DECCKM is unexported), so this is the **copy goroutine**: `Update` calls `emu.SendKey`/`SendText`, a per-session goroutine relays `emu.Read` → `Session.Write`, and teardown closes **`InputPipe()`'s writer** (never `Emulator.Close()`, which is upstream race #879).
+- New **`inputMode: modeToolOverlay`** — modal like `modeAPIStatus`: while the process is alive its handler forwards every key to the tool (esc included) and reserves only `ctrl+\` (kill via `Session.Kill`); after `termExitMsg` only `esc` acts (cleanup: close session, `termEmu = nil`, back to `modeNormal`). `overlayVisible()` gains this third member — **mouse gating rides along; `View()`'s fg picker does not** (it is a two-way `if` that must become a `switch m.mode`, done in Task 2 with a placeholder body). One overlay at a time is structural (the mode) — no `launchingFor`-style guard.
+- Geometry (owned by `termGeometry`, which must agree with the frame arithmetic, so it lives in Task 4): the **outer block** is 70% of width/height, centered; `Styles.OverlayBorder` is a rounded border **plus `Padding(0, 1)`**, so the emulator body is `emuW = outerW - 4`, `emuH = outerH - 2 - 1 (title row) - 1 (exit row)`. The **exit row is reserved from the start** (blank while running) so the block height never changes and `PlaceOverlay` never re-centers mid-session. Min clamps ≈40×10 on the emulator body; below that — and before the first `WindowSizeMsg` (`!m.ready`, checked first per the `toggleZoom` precedent) — the keypress refuses honestly with a statusMsg. `View()` wraps the composite in `Margin(1, 0)` (the background PlaceOverlay measures is the layout, not the terminal) and PlaceOverlay clips silently past the bottom — the clamps must account for both.
+
+## Technical Details
+
+- `internal/term` API sketch (verified against the real packages as Task 1's **first** item, with a stop condition):
+  - `Start(shell string, args []string, w, h int, env []string) (*Session, error)` — env gets `TERM=xterm-256color`, `COLORTERM=truecolor` appended; cwd inherited
+  - `Events() <-chan Event` where `Event` is either `Data []byte` or the final `Exit{Err error, Elapsed time.Duration}`
+  - `Resize(w, h int) error`, `Write(p []byte) (int, error)`, `Kill()`
+  - reader posts bounded chunks (≈32 KiB buffer). **pty EOF semantics**: reading the master after child exit returns `EIO` on Linux, EOF on macOS — both are normal termination, never `Exit.Err`; the verdict comes from `cmd.Wait()`/xpty's wait alone
+  - `waitForTermChunkCmd` on the model side drains pending chunks non-blockingly into one msg; **a drain that reaches `Exit` stops there and delivers the accumulated data first** — the exit goes out as the next message (otherwise a short-lived CLI's final screen is lost, defeating the esc-after-exit design)
+- Messages: `termStartedMsg{session}` (a start error surfaces as an immediate `termExitMsg`), `termChunkMsg{data []byte}`, `termExitMsg{err, elapsed}`. Elapsed is stamped in the session goroutine, never in `Update`.
+- Model state: `m.termSession` (narrow interface, fake-able), `m.termEmu`, `m.termExit *termExitMsg` (nil while running), `m.termW/termH`, `m.termToolName`. **Pre-`termStartedMsg` window**: session and emulator are nil between dispatch and the started msg — keys are dropped, `ctrl+\` is a no-op, the overlay renders a `starting <tool>…` body (the `starting update…` idiom); a panic here would re-panic through `logx.Recover` and crash keepkit, so the guard is structural, not cosmetic.
+- Rendering (`render.go`): frame `Styles.OverlayBorder`, title = tool name with a dim `ctrl+\ kill` hint on the right while running; body = `m.termEmu.Render()` (exactly w×h); the reserved bottom row carries the outcome line after exit, built from `updateOutcomeBlock`'s helpers: `✓ exited · <elapsed> · esc close` / `✕ exit <code> · <elapsed> · esc close` / `✕ killed · <elapsed> · esc close` / `✕ failed to start · <reason> · esc close`. No statusMsg on exit — the screen is the answer. **The child's cursor is rendered**: reverse-video the cell at the emulator's cursor position while the process is alive (hidden after exit; honour the emulator's cursor-visibility state if exposed).
+- Status bar: `renderStatusBar` gets a `modeToolOverlay` branch (its siblings all have one; without it the bar advertises six dead global keys incl. a `q quit` that cannot fire): while running `<tool> running  ctrl+\ kill`, after exit `<tool> exited  esc close` — within the no-truncate budget (`TestStatusBarNeverWraps`).
+- Key translation: rune keys → text input, named keys (arrows, enter, backspace, tab, home/end, pgup/pgdn, F-keys, ctrl+letter) → key events; exact mechanism (encoder vs `SendKey`+pipe) fixed in Task 1. Mouse is **not** proxied in v1 (`SendMouse` exists — YAGNI). Child OSC title/bell events ignored in v1.
+- Not-installed tool: `sh` prints `command not found` into the overlay and exits 127 — visible with the ✕ line, no special handling (replaces the old `notFoundExit` mapping).
+- Kill path: **never call `proc.DetachTTY` on the pty command** — ⚠️ *corrected in Task 1*: xpty sets neither `Setsid` nor `Setctty`, so `internal/term` sets them itself and `DetachTTY` would assign `SysProcAttr` wholesale and drop them. Unix kill goes to the process group (negative pid) off that session, via the existing `proc.KillGroup`; on the ConPTY path `cmd.Process` **is** populated (`os.FindProcess` in `ConPty.Start`), so `KillGroup`'s Windows branch needs no change.
+- Quit-while-open is unreachable by design (all keys go to the tool): the way out is quitting the tool (or `ctrl+\`), then `esc`. If keepkit itself dies (SIGTERM/kill), the closing pty master HUPs the child — accepted.
+- Windows: works via ConPTY (`xpty`); runtime untested by CI — accepted, the same level as `restart_windows`; the existing `GOOS=windows go build` cross-compile step covers the build.
+- Launch during a running update stays allowed (independent concerns; the update log keeps streaming into `[3]` under the dim).
+- go.mod: `x/xpty v0.1.4` (tagged) + `x/vt` pinned pseudo-version; upstream issues #879/#935 are tracked limitations.
+
+## What Goes Where
+
+- **Implementation Steps** (`[ ]` checkboxes): code, tests, docs — all inside this repo.
+- **Post-Completion** (no checkboxes): manual verification in real terminals (real vim/yazi/fzf sessions, Windows smoke test), demo GIF decision — external to unit-testable code.
+
+## Implementation Steps
+
+### Task 1: dependencies + `internal/term` package — pty session with reader goroutine
+
+**Files:**
+- Create: `internal/term/session.go`
+- Create: `internal/term/session_test.go`
+- Create: `docs/research/pty-stack.md`
+- Modify: `go.mod`, `go.sum`
+
+- [x] **first, before writing `Session`**: `go get github.com/charmbracelet/x/xpty@v0.1.4` + `github.com/charmbracelet/x/vt@latest`, pin the vt pseudo-version, and verify the researched API against the real packages (`NewEmulator`/`Render`/`SendKey`/`InputPipe`, cursor accessors, `xpty.NewPty`/`Start`/`Resize`); **check whether x/vt exposes a key→bytes encoder** (`vt.EncodeKey`-style) that would let `Update` translate keys and call `Session.Write` directly — no second goroutine, the Update-only rule becomes literally true. **Stop condition: if `Render() string`, the input mechanism or the cursor API differ materially from the sketch, stop and re-plan Tasks 2–4 before writing code**; record drift with ➕
+  - vt pinned at `v0.0.0-20260813141921-f091cedeaf78`. `Render() string`, `NewEmulator`, `Resize`, `CursorPosition()`, `IsAltScreen()`, `xpty.NewPty`/`Start`/`Resize` all match the sketch — **stop condition not tripped**, Tasks 2–4 stand.
+  - ➕ **drift 1 — there is no key encoder.** `ultraviolet` exports output-side `Encode*` only; `x/ansi` has none. Worse, `vt.SendKey` encodes against `isModeSet(ansi.ModeCursorKeys)` (DECCKM — the mode vim/less set, where arrows are `\x1bOA` not `\x1b[A`) and **no accessor exposes it**, so a hand-rolled encoder would be wrong for exactly the full-screen tools this feature exists for. → **Task 3 takes the plan's fallback: `SendKey` + a copy goroutine.**
+  - ➕ **drift 2 — the `Emulator.Close()` teardown is the upstream race.** #879 reproduced here under `-race` (`e.closed` written by `Close`, read by every `Read`). **Workaround: never call `Emulator.Close()`** — `InputPipe()` returns the `*io.PipeWriter`; closing *that* unblocks the parked `Read` through `io.Pipe`'s own synchronisation and never touches the bool. Verified race-clean; pinned by `TestSessionInputPipeCloseIsRaceFree`, with a fallback to `Close()` if the assertion ever fails.
+  - ➕ **drift 3 — `xpty` does *not* make the child a session leader.** The plan assumed "the pty's own `Setsid`+`Setctty`"; `UnixPty.Start` only wires stdio and calls `cmd.Start()`. `internal/term` sets `SysProcAttr{Setsid: true, Setctty: true}` itself (unix build). The **no-`DetachTTY` invariant survives with a sharper reason**: it assigns `SysProcAttr` wholesale and would drop our `Setctty`.
+  - ➕ **Windows kill needs no detour**: `ConPty.Start` populates `cmd.Process` via `os.FindProcess`, so `proc.KillGroup`'s existing Windows branch works as-is.
+- [x] record the transitive bumps the vt/xpty pull causes (`x/ansi`, `x/cellbuf`, `colorprofile`, new `ultraviolet`) with ➕; if any existing render test in `internal/model`/`internal/ui` moves under the bumped deps, fix or pin **before** Task 2 so breakage is attributed to the bump, not to later feature code
+  - ➕ bumps: `x/ansi` 0.11.6→0.11.7, **`go-runewidth` 0.0.19→0.0.23**, **`displaywidth` 0.9.0→0.11.0**, `uax29/v2` 2.5.0→2.7.0, `go-colorful` 1.3.0→1.4.0, `colorprofile` 0.4.1→0.4.2, `x/sys` 0.38→0.47, `x/sync` 0.17→0.19, new `ultraviolet`. `x/cellbuf` unchanged. **Full suite run on the bump alone before any feature code: all green** — no render test moved.
+- [x] drop the 2026-08 stack research (candidates, rejection reasons, pinned versions, upstream issues #879/#935) into `docs/research/pty-stack.md` so the pin has a rationale that outlives this plan
+- [x] implement `Session`: `Start(shell, args, w, h, env)` → xpty + command (env: `TERM=xterm-256color`, `COLORTERM=truecolor`; cwd inherited), one reader goroutine → events channel; final `Exit{Err, Elapsed}` (elapsed stamped in the goroutine) then close. **Treat `EIO`/`os.ErrClosed` on the master read as normal EOF** (Linux vs macOS differ) — the verdict comes from the wait, never from the read error
+  - ➕ `Exit` carries a third field, **`Killed bool`**: the session is the only place that knows both the kill and the status, so it answers rather than making the model correlate its own keypress against `signal: killed`. This is what feeds the `✕ killed` outcome line in Task 4.
+  - ➕ the events channel is **buffered (64)**, so the reader stays ahead of a consumer that drains once per Bubble Tea message; past it the reader blocks and throttles the child, which is the correct back-pressure.
+- [x] implement `Resize`, `Write`, `Kill` — **no `proc.DetachTTY` on the pty command** (it would clobber the pty's `Setctty`); unix kill signals the pty-led process group; verify `cmd.Process` is populated on the ConPTY path, else kill via xpty's own API (record the Windows shape with ➕)
+  - `Kill` reuses the existing **`proc.KillGroup`** (negative pid on unix, `Process.Kill` on Windows) rather than a duplicate — `proc` is a stdlib-only bottom leaf, so `term` may import it.
+- [x] state in the package doc: no config paths, no `logx` — failures ride `Exit.Err`; hence no `TestMain` seam
+- [x] write tests (unix): `sh -c 'printf hi'` → data chunk then `Exit{Err: nil}` with elapsed > 0 (this is also the Linux `EIO`-is-not-an-error test); non-zero exit surfaces in `Exit.Err`; `Kill` terminates a `sleep` and the channel closes (no goroutine leak); `Resize` returns no error; all under `-race`
+  - ➕ four tests beyond the list, each pinning something the plan relies on elsewhere: `TestSessionKillReachesGrandchildren` (the `Setsid` premise — an `sh -c` background job must die too, or the pty never EOFs), `TestSessionEnvOverridesTerm` (os/exec's last-duplicate-wins is why appending TERM is enough), `TestSessionNotInstalledToolExits127` (replaces the deleted `notFoundExit` mapping), `TestSessionOutputRendersInEmulator` (the term↔model contract, so Task 2's fake session is honest).
+- [x] write error-case tests: `Start` with a bogus shell → error, no goroutine leak (channel closes)
+- [x] run the full gate: `go build ./...` + `go vet ./...` + `go test -race ./...` + `golangci-lint run` + `GOOS=windows go build ./...` - must pass before task 2
+  - ⚠️ **local-only**: `go build` fails in a git *worktree* with `error obtaining VCS status: exit status 128` (every git command it shells out to works standalone). CI clones normally and is unaffected; locally the gate runs `go build -buildvcs=false ./...`.
+
+### Task 2: model plumbing — mode, msgs, cmds, emulator state (no dispatch change yet)
+
+**Files:**
+- Create: `internal/model/overlay_term.go`
+- Modify: `internal/model/model.go`, `internal/model/commands.go`, `internal/model/render.go`
+- Modify: `internal/model/mouse_test.go`, `internal/model/zoom_test.go`
+- Create: `internal/model/overlay_term_test.go`
+
+- [x] add `modeToolOverlay` to the `inputMode` enum; extend `overlayVisible()` with it — mouse gating rides along, **`View()`'s fg picker does not**: turn the `if m.mode == modeHotkeys` two-way pick into a `switch m.mode` with a placeholder `modeToolOverlay` body here, so Task 4 only fills the renderer in
+- [x] add model state: `termSession` behind a narrow local interface (the `restarter` idiom — `var _ termSession = (*term.Session)(nil)`), `termEmu`, `termExit`, `termW/termH`, `termToolName`
+  - ➕ plus `termInput *termInput`, the relay's handle (Task 1's drift 1 made the goroutine unavoidable). `termExit != nil` is the single "has it finished" discriminator — no separate flag, no "running" enum member, mirroring `selfState`'s derived `selfUpdating()`.
+- [x] add msgs `termStartedMsg`/`termChunkMsg`/`termExitMsg` and cmds `startTermCmd(shell, args, w, h)` (safeCmd-wrapped) + `waitForTermChunkCmd(session)` with the non-blocking drain that **stops at `Exit` and delivers accumulated data first**; handlers in `Update`: started → create emulator (Update-only rule) + wire the input path per Task 1's decision, chain the wait cmd; chunk → `termEmu.Write` + chain; exit → store `termExit`, stop chaining
+  - ➕ **the drain's exit rides `termChunkMsg.exit *termExitMsg`**: a Go channel cannot be un-read, so the exit the drain already consumed had nowhere else to go. The handler writes the data, then re-emits the exit as the *next* message — the plan's stated ordering, literally.
+  - ➕ `termExitMsg` carries **`startFailed`** so the outcome line can say `✕ failed to start` without reconstructing it from a nil session.
+  - ➕ **stale-session gating**: a chunk whose session is not `m.termSession` is dropped **without re-subscribing** (a dead session's channel must not keep a command chain alive), and a `termStartedMsg` arriving outside the mode is **killed and closed** rather than adopted — otherwise a start that lost its race with `esc` strands a live pty.
+- [x] if Task 1 landed on the `InputPipe` copy goroutine: implement its explicit lifecycle — started exactly once per session when both ends exist; close order on cleanup is `Kill`/wait → close pty → close the emulator's input pipe → goroutine returns; it must never outlive `esc`
+  - implemented as `termInput.stop(emu)`, called by the single teardown `closeToolOverlay()` in exactly that order, and it **waits** on the goroutine's done channel.
+- [x] add `modeToolOverlay` to the modal tables in `mouse_test.go` (mouse no-op set, ~line 201) and `zoom_test.go` (modal `z` guard, ~line 287) — these tables are what "rides along" means
+  - ⚠️ **plan ordering flaw**: the `zoom_test.go` row cannot be green until the mode-dispatch case exists, which the plan put in Task 3. Pulled the `case modeToolOverlay:` dispatch (and a `updateToolOverlay` that consumes every key) forward into Task 2 — a mode that owns all input is the truthful placeholder, and it is what the table asserts. Task 3 fills in translation, the kill chord and esc.
+- [x] write tests: handlers drive a fake session (chunk channel + recorded `Write`/`Kill`/`Resize`); chunk msg reaches a real `vt` emulator and `Render()` shows the bytes (pure Go — no pty); a fake whose channel holds data+data+Exit yields both data chunks before `termExitMsg` and `Render()` shows all of it; exit msg stores status and stops the chain; if the pipe goroutine exists — a `-race` leak test for its close order
+- [x] run the full gate (build + vet + `go test -race ./...` + lint) - must pass before task 3
+  - ⚠️ **golangci-lint's cache lies across a package's file set**: adding `overlay_term.go` made it report 6 `SA5011` false positives in three *untouched* test files. `golangci-lint cache clean` → 0 issues, before and after. Not a code problem; worth knowing before anyone "fixes" a `t.Fatalf` helper that was never broken.
+
+### Task 3: input routing — `updateToolOverlay` handler and key translation
+
+**Files:**
+- Modify: `internal/model/mode.go`, `internal/model/overlay_term.go`
+- Modify: `internal/model/overlay_term_test.go`
+
+- [x] implement key translation `tea.KeyMsg` → tool input (runes → text; named keys/ctrl-chords → key events; mechanism per Task 1's decision), confirmed against the pinned vt version; esc translates and is **sent**, not consumed, while the process runs
+  - three paths, split by what actually depends on emulator state: **runes/space** → `SendText`; **the mode-dependent named keys** (arrows, Home/End, PgUp/PgDn, Insert/Delete, shift+tab, F1–F12) → `SendKey`, so DECCKM/DECNKM are honoured; **the control range** → the byte itself, because Bubble Tea's control key *types are* the control bytes (`KeyEnter` is 0x0d, `KeyEsc` 0x1b, `KeyBackspace` 0x7f) and none of them is mode-dependent — writing the byte is exactly what vt's encoder produces.
+  - ➕ **`termModifiedKeys`**: the pinned x/vt encodes no modified special key at all — its `SendKey` default emits nothing when `Mod != 0` — so `ctrl+left` and friends would be silently swallowed in every editor. They are written out as xterm's `CSI 1;<mod><final>`, which is safe to hand-encode precisely because, unlike the bare arrows, the modified forms do not depend on DECCKM.
+  - `Alt` is a Bubble Tea *flag*, not a key: it becomes an ESC prefix (or `ModAlt` on the `SendKey` path).
+- [x] add `case modeToolOverlay: return m.updateToolOverlay(msg)` to the mode dispatch **unwrapped** — deliberately *not* through `flushPendingLaunch` like its siblings: a deferred exec fallback must not fire `tea.ExecProcess` on the very keystroke that closes the overlay (the wrapper disappears entirely in Task 5)
+  - landed in Task 2 (see the ⚠️ ordering note there); `TestToolOverlayDoesNotFlushPendingLaunch` is what pins the unwrapping.
+- [x] `updateToolOverlay`: process alive → translate & send everything except `ctrl+\` (→ `Session.Kill`, stays in mode until `termExitMsg`); process exited → `esc` cleans up (session close, `termEmu = nil`, `modeNormal`), everything else no-op
+- [x] **pre-`termStartedMsg` nil guard**: keys arriving before the session exists are dropped, `ctrl+\` is a no-op there (a nil deref would re-panic through `logx.Recover` and crash keepkit)
+- [x] write tests: keys (incl. esc, ctrl+c) reach the fake's input while alive; `ctrl+\` triggers `Kill` and mode holds; esc before exit does NOT close; esc after `termExitMsg` cleans and returns to `modeNormal`; non-esc after exit is a no-op; a key in the pre-started state neither panics nor reaches anything
+  - ➕ the forwarding test is a **19-row table asserting the exact bytes** the tool receives, not just that something arrived: the encoding is the feature, and "a key reached the fake" would pass with every sequence wrong.
+- [x] run the full gate (build + vet + `go test -race ./...` + lint) - must pass before task 4
+
+### Task 4: rendering — geometry, overlay frame, cursor, exit line, status bar, resize
+
+**Files:**
+- Modify: `internal/model/render.go`, `internal/model/overlay_term.go`, `internal/model/model.go` (`applyLayout`/`WindowSizeMsg`)
+- Modify: `internal/model/overlay_term_test.go` (and/or `render_test.go`)
+
+- [x] implement `termGeometry(width, height)` beside the frame arithmetic it must agree with: outer block = 70%×70% centered; body `emuW = outerW - 4` (border + `Padding(0,1)`), `emuH = outerH - 2 - 1 (title) - 1 (reserved exit row)`; account for `View()`'s `Margin(1, 0)` and PlaceOverlay's silent bottom clip; min clamps ≈40×10 body; ok=false below them **and when `!m.ready` (checked first, the `toggleZoom` idiom)**
+  - ➕ the size and the verdict are **separate answers**: the size is always clamped to the floor and `ok` is returned beside it, because the two callers want different things — the keypress refuses on `!ok`, while a terminal shrunk *mid-session* keeps rendering at the minimum. Killing somebody's editor because they narrowed a window is worse than a cramped overlay.
+  - at the 80×24 baseline the body is **52×11** — the default terminal succeeds, which is the number that mattered.
+- [x] render the overlay in the `View()` switch: `OverlayBorder` frame, title = tool name + dim `ctrl+\ kill` right-hint while running; body = `termEmu.Render()` (pre-start: `starting <tool>…`); the **exit row is reserved from the start** (blank while running) so the block height is constant and the overlay never re-centers at exit
+  - ⚠️ **the visual pass caught what the plan's arithmetic missed**: the reserved row holds the *height*, but nothing held the *width*, and lipgloss sizes a border to its widest line. At 80×24 the block measured 54 cells running and 53 exited — it jumped sideways at the exact moment the user starts reading the outcome. Fixed by padding every row to the body width (`termRow`, ANSI-safe in both directions).
+- [x] render the child's cursor: reverse-video the cell at the emulator's cursor position while the process is alive, hidden after exit; honour the emulator's cursor-visibility state if the API exposes it
+  - the pinned x/vt exposes `CursorPosition()` but **no visibility accessor**, so the alive/exited rule is the whole of it. The splice goes through `ansi.Truncate`/`TruncateLeft` (cut by *visible column*, keeping SGR on both sides) — a rune-index cut would land inside an escape sequence.
+  - ➕ `ui.Styles.TermCursor` is a new style and the only one naming no theme colour: reverse video swaps whatever the *tool* painted, which is the only way one style can mark a cursor on a screen keepkit does not control.
+- [x] fill the reserved row after exit via `updateOutcomeBlock`'s helpers (`formatElapsed`/`fitCells`/`footerSep`): `✓ exited · <elapsed> · esc close` / `✕ exit <code> · <elapsed> · esc close` / `✕ killed · <elapsed> · esc close` / `✕ failed to start · <reason> · esc close` (`✓`/`✕` in `Ok`/`Danger`)
+  - a start failure spends the middle cell on its **reason** rather than on an elapsed it does not have.
+- [x] add the `renderStatusBar` branch for `modeToolOverlay` (its siblings all have one — without it the bar advertises six dead global keys): running → `<tool> running  ctrl+\ kill`, exited → `<tool> exited  esc close`, within the no-truncate budget
+- [x] handle `WindowSizeMsg` while open: recompute `termGeometry`, `termEmu.Resize` + `Session.Resize`; shrinking below the minimum keeps the overlay at the clamped floor (no mid-session kill)
+  - hung off **`applyLayout`**, the single relayout point, so the resize path cannot drift from it; a no-op in every other mode.
+- [x] write tests: rendered View contains frame, title, hint, `starting…` body pre-start, cursor cell reverse-video while alive, all four outcome lines after their exits; **block height identical before and after `termExitMsg`**; dimmed background; a body line carrying SGR renders at the right visible width inside the frame and no escape leaks past the frame's right edge (assert on `stripANSI(View())` width and the dim margins); status-bar branch in both states; resize propagates to fake session and emulator; refusal on a tiny terminal and on `!m.ready`
+  - **every new assertion was mutation-checked** (11 mutations, all killed). Two survived on the first pass and both were real test defects, not code ones: the block-size helper was scanning the *composited* view, where the three panels' own rounded corners are what it found, so it reported a constant size no matter what the overlay did; and the width claim was already satisfied by the body rows, so it was rewritten to assert the case the clamp actually exists for — **a tool name longer than the body must not widen the block**.
+  - the cursor test needs `forceColor(t)`: reverse video is styling, and the default test profile strips it, so the assertion would have passed against a cursor that was never drawn.
+- [x] run the full gate (build + vet + `go test -race ./...` + lint) - must pass before task 5
+
+### Task 5: the switch — dispatch to overlay, delete the tab launcher wholesale
+
+**Files:**
+- Modify: `internal/model/mode.go` (`updateRunInput`), `internal/model/model.go`, `internal/model/commands.go`
+- Delete: `internal/launcher/` (whole package)
+- Modify: `internal/model/mode_test.go`, `internal/model/status_test.go`
+- Modify/Delete: `internal/model/launch_test.go`
+
+- [x] rewire `updateRunInput`'s enter: **refusal first** (`termGeometry` incl. `!m.ready`) → statusMsg (`terminal too small to run a tool`-class wording) with **no `lastRun` write** — a launch that never started is not remembered (today's refusal comment, `mode.go:346`, keeps its meaning); on success: `lastRun` write, `startTermCmd`, `modeToolOverlay`; empty-input-cancels unchanged
+- [x] delete `internal/launcher`; in model: `startLaunchCmd`, `execToolCmd`, `launchDoneMsg`/`execDoneMsg`, `m.launchingFor`, `pendingLaunchName`/`Command` + `flushPendingLaunch` and all its modal-return call sites, `launchTimeout`, `launchFallbackStatus`, `notFoundExit`, the `launching…`/`tab open failed…` wordings
+  - the untrack handler's "drop a pending fallback for this tool" branch goes with them, and the `tea.KeyMsg` dispatch comment now states what the switch actually does rather than what the wrapper used to.
+- [x] delete `setStickyStatus` (its only callers were the two launch statuses) and `TestInFlightStatusSurvivesStaleExpiry`; keep `setStatus`/TTL machinery untouched
+- [x] keep `shellCommand` (now feeds the overlay dispatch; refresh its comment and the cross-reference on `updater.customPlan`)
+- [x] update `mode_test.go`: `TestRunInputEnterStoresLastRun` (post-enter mode → `modeToolOverlay`, `lastRun` still written); audit the other `modeRunInput` tests (`TestRunInputOpensPrefilled`, `TestRunInputEscCancels`, `TestRunInputBlankInputCancels`, `TestRunDuringUpdate`, `TestRunInputKeyGuard`) — prompt-opening ones stay, only dispatch-shape assertions change
+  - ⚠️ `TestRunInputEnterStoresLastRun` broke for a second reason the plan did not predict: `newTestModel` sets `width`/`height` **without a `WindowSizeMsg`**, so `m.ready` is false and the new refusal fired. It now goes through a real resize — which is the honest fixture, since the dispatch measures the screen.
+- [x] rewrite `launch_test.go` into overlay-dispatch tests: enter→prompt→overlay opens with prefill variants; empty list no-op; rename still clears `lastRun`; refusal writes no `lastRun`; **no test executes the returned cmd** (it would spawn a real pty)
+  - `TestRenameClearsLastRun` already existed in `mode_test.go` and was left there rather than duplicated.
+- [x] run the full gate + `GOOS=windows go build ./...` - must pass before task 6
+  - ➕ four comments in Go source pointed at now-deleted symbols and were re-anchored here rather than left for Task 8: `updater.go`'s `launcher.planFor` idiom → `configdir.baseFor`, two `launchTimeout` var-seam references → `updateTimeout`, and `acceptsUpdateDetect`'s `launchDoneMsg` mode-gate mirror → the overlay's own reason.
+
+### Task 6: surfaces — hotkeys overlay sweep
+
+**Files:**
+- Modify: `internal/model/render.go`
+- Modify: `internal/model/render_test.go`
+
+- [x] `[?]` overlay tools group: the row is `{"enter", "run in a tab"}` (`render.go:797`) → `run in overlay`; that is +2 visible cells against the hard ≤76-col framed budget — measure after the change, and if `TestRenderHotkeysSizeBudget` breaks, shorten to `run overlay` rather than dropping a row
+  - measured after the change: **64×20 in all five self states** against the 76×20 budget. The width worry was unfounded — the overlay is 12 columns inside its ceiling; it is the *height* that sits exactly at 20, which is what the plan's "a new binding needs a row freed" note is about. `run in overlay` stands, no shortening needed.
+- [x] verify no status-bar or footer branch references the deleted launch statuses; `[1]` footer `enter run` and the `modeRunInput` bar branch stay as-is
+- [x] sweep rendered-surface tests: hotkeys budget across all five self states, footer cells, status bar at the 80×24 baseline stay green with the new wording
+- [x] write/adjust tests for the changed `[?]` row
+- [x] run the full gate (build + vet + `go test -race ./...` + lint) - must pass before task 7
+
+### Task 7: Verify acceptance criteria
+
+- [x] verify all requirements from Overview: prompt kept, overlay launch, full keyboard proxy while alive, `ctrl+\` kill, esc-after-exit close, reserved exit line, cursor rendered, CLI-and-TUI single path, tab path fully gone
+
+| Requirement | Pinned by |
+|---|---|
+| prompt kept, prefilled | `TestRunInputPrefill`, `TestRunInputEnterOpensOverlay` |
+| launches into the overlay | `TestRunInputEnterOpensOverlay`, `TestRunInputEnterStoresLastRun` |
+| every key reaches the tool | `TestToolOverlayForwardsEveryKeyWhileRunning` (19 rows, exact bytes), `TestToolOverlayEscDoesNotCloseWhileRunning`, `TestToolOverlayCtrlCDoesNotQuit` |
+| `ctrl+\` kills | `TestToolOverlayKillChord` |
+| esc closes after exit | `TestToolOverlayAfterExit`, `TestToolOverlayCloseDispatchesNothing` |
+| exit row reserved | `TestToolOverlayExitRowBlankWhileRunning`, `TestToolOverlayBlockDoesNotMoveAtExit` |
+| cursor rendered | `TestToolOverlayCursor` |
+| one path for CLI and TUI | `TestToolOverlayEndToEndWithRealPty` (CLI), `TestSessionOutputRendersInEmulator` |
+| tab path gone | `internal/launcher` deleted; no reference survives outside prose |
+
+- [x] verify edge cases: empty list, empty input cancel, launch during a running update, resize during session, tiny-terminal and `!m.ready` refusals, not-installed tool shows 127 in overlay, keys before `termStartedMsg` are safe
+  - `TestRunInputEmptyList`, `TestRunInputCancels`, `TestRunDuringUpdate`, `TestToolOverlayResize` + `TestToolOverlayResizeBelowMinimumClamps`, `TestRunInputRefusesOnTinyTerminal` + `TestTermGeometryNotReady`, `TestSessionNotInstalledToolExits127`, `TestToolOverlayKeysBeforeStart`.
+- [x] run full test suite: `go test -race ./...`
+  - ➕ **one coverage gap was real and is now closed**: every overlay test drove a *fake* session, so nothing would have noticed if `waitForTermChunkCmd` and `term.Session` disagreed about their own channel. `TestToolOverlayEndToEndWithRealPty` runs start → adopt → drain → render → exit against a real pty (a `printf`, unix-only), pumping the command chain the way the tea runtime does. It deliberately does **not** execute the run-prompt's returned cmd, which stays untested by design.
+- [x] run `go vet ./...`, `golangci-lint run`, `GOOS=windows go build ./...`, `GOOS=darwin go build ./...`
+  - all green, plus `GOOS=windows go vet ./...`. 473 tests pass in `internal/model` + `internal/term`.
+
+### Task 8: [Final] Update documentation
+
+**Files:**
+- Create: `docs/design/tool-overlay.md`
+- Modify: `CLAUDE.md`, `ARCHITECTURE.md`, `README.md`, `docs/design/updating.md`, `internal/updater/updater.go`, `internal/model/model.go`
+
+- [x] create `docs/design/tool-overlay.md` (fourth deep-design doc: the Update-only emulator rule and why, the input-path decision, esc semantics, the kill chord and the no-`DetachTTY` invariant, geometry incl. the reserved exit row, the pty EOF rule, what was deleted and why) and link it from CLAUDE.md's design-docs table
+- [x] CLAUDE.md: replace the `internal/launcher` package row with `internal/term`; rewrite the **Run (`enter` in `focusTools`)** bullet to the overlay invariant summary; input-modes list (`modeToolOverlay`); `overlayVisible()` description; commands.go/mode.go file-table rows; drop `setStickyStatus` from the status-message lifecycle section; **"Three features" → four** in the design-docs preamble (line ~22) and the "never re-inline these three sections" sentence; fix the misquoted hotkeys row (`run in a tab`, not `run in tab`) while touching it
+- [x] re-anchor the **`planFor` idiom** onto a surviving example (`baseFor`/`shellCommand`): CLAUDE.md lines ~36/42/109, ARCHITECTURE.md ~348, `docs/design/updating.md` (two sites), `internal/updater/updater.go:93`; rewrite the "`execToolCmd` is the one unwrapped cmd" sentence in CLAUDE.md's logx section and ARCHITECTURE.md ~581 (every cmd is safeCmd-wrapped again); drop `launcher` from ARCHITECTURE.md ~65's bottom-leaf list; replace the "`launchDoneMsg`'s mode gate" mirror in `docs/design/updating.md` and the comment at `internal/model/model.go:839` with the surviving reason
+- [x] ARCHITECTURE.md: mermaid edge `model --> term` (drop `--> launcher`), package table row, mode count, rewrite the "Running a tool (`enter`)" section, "Three areas" → four (~20-22)
+- [x] README.md: rewrite the Features bullet at ~64-65 (the adapter list is the whole sentence and it all goes), Usage `enter` line at ~129-131, and the `[1]` hint enumeration at ~153
+- [x] move this plan to `docs/plans/completed/`
+
+## Post-Completion
+
+**Manual verification** (real terminals, real tools — unit tests must not touch them):
+- vim in the overlay: esc reaches vim (mode switch works), cursor visible and tracking, `:q` exits, ✓ line shows, esc closes, keepkit screen intact
+- yazi/fzf session end-to-end; a plain `rg --version` run: output + ✓ line stays until esc (verify the final screen survived the drain)
+- `ctrl+\` on a hung `sleep 1000` (✕ killed line); terminal resize mid-vim; launch while an update streams in `[3]`
+- Windows smoke test via ConPTY when a Windows machine is available (CI only cross-compiles)
+- truecolor/alt-screen fidelity spot-check (btop or similar) — known upstream limits (#935 graphemes) noted, not fixed here
+
+**External follow-ups**:
+- demo GIFs (`demo/hero.gif`, `demo/update.gif`) show the old launch flow — decide on regeneration via the demo-gifs skill after merge
+- track upstream x/vt issues #879/#935; a future tagged x/vt release replaces the pinned pseudo-version
+
+## Task 8 notes
+
+- ➕ **the docs-sync sweep found two real drifts beyond the plan's list**: the mermaid
+  graph was missing the `term --> proc` edge (`internal/term/session.go` imports it for
+  `KillGroup`), and README's *Stack* omitted `ultraviolet`, which the key translation
+  made a **direct** dependency. Both fixed.
+- ➕ the `modeRunInput` enum comment in `mode.go` still said *"run the tool in a new
+  terminal tab"* — corrected while verifying the enum against the docs.
+- ⚠️ **CLAUDE.md is 144 641 characters**, over the docs-sync skill's ~140 000 warning
+  threshold and under the 150 000 harness limit. This change *reduced* it by 1 896
+  (146 537 → 144 641): the Run bullet became an invariant summary plus a link, which
+  more than paid for the new package row and the fourth design-doc row. The threshold
+  was already crossed before this work, so splitting another section out is left as a
+  separate decision rather than folded in here.
diff --git a/docs/research/pty-stack.md b/docs/research/pty-stack.md
new file mode 100644
index 0000000..02cc6a7
--- /dev/null
+++ b/docs/research/pty-stack.md
@@ -0,0 +1,166 @@
+# The pty stack behind the tool overlay (researched 2026-08)
+
+Why keepkit runs a tracked tool on an embedded pseudo-terminal the way it does,
+which libraries were considered, and what each pinned version is buying. This
+outlives the implementation plan on purpose: the pins below are load-bearing and
+a future reader upgrading them needs the reasons, not just the numbers.
+
+## What the feature needs
+
+Running `vim`, `yazi` or `fzf` *inside* keepkit's own screen means three things
+at once, and no single library gives all three:
+
+1. a **pty** — the tool must believe it owns a terminal, or it will not draw at
+   all (`isatty` fails, ncurses/crossterm refuse to start);
+2. a **terminal emulator** — something has to interpret the escape sequences the
+   tool writes and hand keepkit a rectangle of styled cells it can paint into a
+   Bubble Tea `View()`;
+3. **Windows support**, because keepkit ships a Windows binary and its release
+   workflow cross-compiles for it.
+
+## Chosen: `charmbracelet/x/xpty` + `charmbracelet/x/vt`
+
+| Module | Version | Why |
+|---|---|---|
+| `github.com/charmbracelet/x/xpty` | **v0.1.4** (tagged) | one `Pty` interface over unix ptys (via `creack/pty`) and Windows **ConPTY**; `WaitProcess` papers over the Go runtime's inability to `cmd.Wait()` a ConPTY child |
+| `github.com/charmbracelet/x/vt` | **pseudo-version `v0.0.0-20260813141921-f091cedeaf78`** — untagged upstream | VT220 + truecolor emulator in pure Go: `NewEmulator(w, h)`, `Write` pty bytes in, `Render() string` out |
+
+`vt` has **no tagged release**, so the pseudo-version is deliberate rather than
+sloppy. Re-pin it only together with a run of the full suite — see *Dependency
+blast radius* below.
+
+### Rejected alternatives
+
+- **`creack/pty` directly** — no Windows. ConPTY support has been proposed
+  upstream for years and never merged, so choosing it would mean shipping a
+  feature that silently does not exist on one of keepkit's three platforms.
+- **`taigrr/bubbleterm`** — the closest thing to a drop-in, but it requires
+  Bubble Tea **v2** and keepkit is on v1.3.10. Upgrading the whole TUI to v2 to
+  get one feature is the tail wagging the dog. Its emulator↔`Model` wiring was
+  read for ideas; nothing was vendored.
+
+`vt` works fine under Bubble Tea v1 because `Render()` returns a plain ANSI
+string — it needs no v2 rendering core to hand keepkit its screen.
+
+## What the API actually looks like (verified, not assumed)
+
+The implementation plan sketched this API from research; every item below was
+re-checked against the pinned modules before a line of `internal/term` was
+written, because the plan carried a stop condition for material drift.
+
+Matches the sketch:
+
+- `vt.NewEmulator(w, h) *Emulator`, `Write([]byte)`, `Render() string`,
+  `Resize(w, h)` (no error), `CursorPosition() uv.Position`, `IsAltScreen()`.
+- `xpty.NewPty(w, h)`, `Pty.Start(*exec.Cmd)`, `Resize`, `Read`/`Write`/`Close`.
+- `xpty.WaitProcess(ctx, cmd)` — falls back to `cmd.Wait()` off Windows and
+  synthesises the `*exec.ExitError` that `os.Process.Wait` fails to produce on
+  ConPTY, so the exit code has the same shape on every platform.
+- `ConPty.Start` populates `cmd.Process` (via `os.FindProcess`), so the kill
+  path needs no Windows-specific detour.
+
+### Drift #1 — there is no key encoder, and the modes it would need are unexported
+
+The plan preferred translating a `tea.KeyMsg` into bytes and calling
+`Session.Write` directly, because that needs no second goroutine and makes
+"only `Update` touches the emulator" literally true. **That function does not
+exist** in the pinned stack: `ultraviolet` exports only output-side encoders
+(`EncodeCursorStyle`, `EncodeMouseMode`, …), and `x/ansi` has none either.
+
+Writing our own was rejected on correctness, not effort. `vt`'s `SendKey`
+encodes **against emulator state**:
+
+```go
+ack := e.isModeSet(ansi.ModeCursorKeys)    // DECCKM - arrows are \x1bOA, not \x1b[A
+akk := e.isModeSet(ansi.ModeNumericKeypad) // DECNKM
+```
+
+`isModeSet` is unexported and no accessor surfaces it, so a hand-rolled encoder
+could not know whether the child had switched to application cursor keys — the
+mode `vim` and `less` set on entry. Arrows in vim are not a corner case for the
+project's flagship feature. So keepkit uses `vt`'s own `SendKey`, which means
+accepting the copy goroutine the plan listed as the fallback.
+
+### Drift #2 — `xpty` does **not** make the child a session leader
+
+The plan assumed "the pty's own `Setsid`+`Setctty`". It has neither:
+`UnixPty.Start` wires `Stdin`/`Stdout`/`Stderr` to the slave and calls
+`cmd.Start()`, and that is all. Without `Setsid`+`Setctty` the child inherits
+keepkit's controlling terminal, job control never engages, and a
+`SIGKILL`-to-the-process-group teardown would signal the wrong group.
+
+`internal/term` therefore sets `SysProcAttr{Setsid: true, Setctty: true}`
+itself, on the unix build only. `Ctty` defaults to 0, which is the child's
+stdin — the slave that `xpty` just attached, so the default is the correct fd.
+
+The invariant the plan derived from its wrong premise survives intact, and now
+has a sharper reason: **never call `proc.DetachTTY` on the pty command.** It
+would overwrite `SysProcAttr` wholesale, dropping `Setctty` and handing the
+child a pty with no controlling terminal — the exact opposite of the point.
+
+## Upstream issues we are living with
+
+### charmbracelet/x#879 — `Emulator.Read`/`Close` data race
+
+Real, reproduced here under `-race`, and it dictates the teardown:
+
+```go
+func (e *Emulator) Read(p []byte) (int, error) {
+	if e.closed { return 0, io.EOF }   // unsynchronised read
+	return e.pr.Read(p)
+}
+
+func (e *Emulator) Close() error {
+	e.closed = true                    // unsynchronised write
+	return e.pw.CloseWithError(io.EOF)
+}
+```
+
+A copy goroutine parked in `Read` plus a `Close()` from `Update` is a textbook
+race, and `go test -race` reports it immediately. keepkit's suite runs `-race`,
+so this is not a theoretical concern.
+
+**The workaround: never call `Emulator.Close()`.** `InputPipe()` returns the
+emulator's `*io.PipeWriter`; closing *that* unblocks the parked `Read` with
+`io.EOF` through `io.Pipe`'s own synchronisation and never touches the
+`e.closed` bool. Verified race-clean, and `TestSessionInputPipeCloseIsRaceFree`
+in `internal/term` is what keeps the knowledge from being lost the next time
+somebody reaches for the obvious `Close()`.
+
+If a future `vt` fixes #879, the type assertion can go and `Close()` can come
+back — the assertion falls back to `Close()` already if `InputPipe()` ever stops
+returning an `io.Closer`.
+
+### charmbracelet/x#935 — grapheme splitting
+
+Wide graphemes split across two `Write` calls can render wrong. Not worked
+around; the pty reader delivers large chunks and the failure is cosmetic and
+transient. Tracked, not fixed here.
+
+## Dependency blast radius
+
+Pulling `vt` drags in `charmbracelet/ultraviolet` (the Bubble Tea v2 rendering
+core) and bumps several modules that lipgloss and glamour already sat on — i.e.
+**the dependency bump alone can move keepkit's render tests**, which is why the
+gate for the dependency step was the full suite rather than the new package.
+
+Measured on the bump (`go test ./...` before any feature code): **everything
+stayed green.**
+
+| Module | Before | After |
+|---|---|---|
+| `x/ansi` | v0.11.6 | v0.11.7 |
+| `mattn/go-runewidth` | v0.0.19 | v0.0.23 |
+| `clipperhouse/displaywidth` | v0.9.0 | v0.11.0 |
+| `clipperhouse/uax29/v2` | v2.5.0 | v2.7.0 |
+| `lucasb-eyer/go-colorful` | v1.3.0 | v1.4.0 |
+| `charmbracelet/colorprofile` | v0.4.1 | v0.4.2 |
+| `golang.org/x/sys` | v0.38.0 | v0.47.0 |
+| `golang.org/x/sync` | v0.17.0 | v0.19.0 |
+| `charmbracelet/ultraviolet` | — | v0.0.0-20260303162955-0b88c25f3fff (new) |
+
+`go-runewidth` and `displaywidth` are the two to watch on any future re-pin:
+keepkit measures glyph widths in half a dozen places (the gauge, the language
+band, the list markers, `insetPanelTitle`'s border arithmetic) and pins several
+of them with dedicated tests precisely because a width change is invisible until
+a border tears.
diff --git a/go.mod b/go.mod
index 3afa3ee..f564b83 100644
--- a/go.mod
+++ b/go.mod
@@ -7,8 +7,11 @@ require (
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
-	github.com/charmbracelet/x/ansi v0.11.6
-	github.com/mattn/go-runewidth v0.0.19
+	github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff
+	github.com/charmbracelet/x/ansi v0.11.7
+	github.com/charmbracelet/x/vt v0.0.0-20260813141921-f091cedeaf78
+	github.com/charmbracelet/x/xpty v0.1.4
+	github.com/mattn/go-runewidth v0.0.23
 	github.com/muesli/termenv v0.16.0
 	github.com/yuin/goldmark-emoji v1.0.6
 	golang.org/x/mod v0.37.0
@@ -20,17 +23,21 @@ require (
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
-	github.com/charmbracelet/colorprofile v0.4.1 // indirect
+	github.com/charmbracelet/colorprofile v0.4.2 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/conpty v0.2.0 // indirect
+	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
 	github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
-	github.com/clipperhouse/displaywidth v0.9.0 // indirect
-	github.com/clipperhouse/stringish v0.1.1 // indirect
-	github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
+	github.com/charmbracelet/x/termios v0.1.1 // indirect
+	github.com/charmbracelet/x/windows v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/creack/pty v1.1.24 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/gorilla/css v1.0.1 // indirect
-	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
@@ -41,7 +48,8 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/goldmark v1.7.17 // indirect
 	golang.org/x/net v0.38.0 // indirect
-	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/term v0.36.0 // indirect
 	golang.org/x/text v0.30.0 // indirect
 )
diff --git a/go.sum b/go.sum
index d148b56..91b804c 100644
--- a/go.sum
+++ b/go.sum
@@ -16,28 +16,42 @@ github.com/charmbracelet/bubbles v1.0.0 h1:12J8/ak/uCZEMQ6KU7pcfwceyjLlWsDLAxB5f
 github.com/charmbracelet/bubbles v1.0.0/go.mod h1:9d/Zd5GdnauMI5ivUIVisuEm3ave1XwXtD1ckyV6r3E=
 github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
 github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
-github.com/charmbracelet/colorprofile v0.4.1 h1:a1lO03qTrSIRaK8c3JRxJDZOvhvIeSco3ej+ngLk1kk=
-github.com/charmbracelet/colorprofile v0.4.1/go.mod h1:U1d9Dljmdf9DLegaJ0nGZNJvoXAhayhmidOdcBwAvKk=
+github.com/charmbracelet/colorprofile v0.4.2 h1:BdSNuMjRbotnxHSfxy+PCSa4xAmz7szw70ktAtWRYrY=
+github.com/charmbracelet/colorprofile v0.4.2/go.mod h1:0rTi81QpwDElInthtrQ6Ni7cG0sDtwAd4C4le060fT8=
 github.com/charmbracelet/glamour v1.0.0 h1:AWMLOVFHTsysl4WV8T8QgkQ0s/ZNZo7CiE4WKhk8l08=
 github.com/charmbracelet/glamour v1.0.0/go.mod h1:DSdohgOBkMr2ZQNhw4LZxSGpx3SvpeujNoXrQyH2hxo=
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 h1:ZR7e0ro+SZZiIZD7msJyA+NjkCNNavuiPBLgerbOziE=
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834/go.mod h1:aKC/t2arECF6rNOnaKaVU6y4t4ZeHQzqfxedE/VkVhA=
-github.com/charmbracelet/x/ansi v0.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
-github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
+github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff h1:uY7A6hTokHPJBHfq7rj9Y/wm+IAjOghZTxKfVW6QLvw=
+github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff/go.mod h1:E6/0abq9uG2SnM8IbLB9Y5SW09uIgfaFETk8aRzgXUQ=
+github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
+github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
 github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
 github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
+github.com/charmbracelet/x/conpty v0.2.0 h1:eKtA2hm34qNfgJCDp/M6Dc0gLy7e07YEK4qAdNGOvVY=
+github.com/charmbracelet/x/conpty v0.2.0/go.mod h1:fexgUnVrZgw8scD49f6VSi0Ggj9GWYIrpedRthAwW/8=
 github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91 h1:payRxjMjKgx2PaCWLZ4p3ro9y97+TVLZNaRZgJwSVDQ=
 github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
+github.com/charmbracelet/x/exp/ordered v0.1.0 h1:55/qLwjIh0gL0Vni+QAWk7T/qRVP6sBf+2agPBgnOFE=
+github.com/charmbracelet/x/exp/ordered v0.1.0/go.mod h1:5UHwmG+is5THxMyCJHNPCn2/ecI07aKNrW+LcResjJ8=
 github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf h1:rLG0Yb6MQSDKdB52aGX55JT1oi0P0Kuaj7wi1bLUpnI=
 github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf/go.mod h1:B3UgsnsBZS/eX42BlaNiJkD1pPOUa+oF1IYC6Yd2CEU=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
 github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
-github.com/clipperhouse/displaywidth v0.9.0 h1:Qb4KOhYwRiN3viMv1v/3cTBlz3AcAZX3+y9OLhMtAtA=
-github.com/clipperhouse/displaywidth v0.9.0/go.mod h1:aCAAqTlh4GIVkhQnJpbL0T/WfcrJXHcj8C0yjYcjOZA=
-github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
-github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
-github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
-github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
+github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
+github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
+github.com/charmbracelet/x/vt v0.0.0-20260813141921-f091cedeaf78 h1:CIlgdpAf3PLGkv6Z+tISRNe6cnFoHVnjXtBWzo/NLAU=
+github.com/charmbracelet/x/vt v0.0.0-20260813141921-f091cedeaf78/go.mod h1:u1LOIABor9JqY54oZdktK3TCRrgzP6tzHrDYx1nd3wY=
+github.com/charmbracelet/x/windows v0.2.2 h1:IofanmuvaxnKHuV04sC0eBy/smG6kIKrWG2/jYn2GuM=
+github.com/charmbracelet/x/windows v0.2.2/go.mod h1:/8XtdKZzedat74NQFn0NGlGL4soHB0YQZrETF96h75k=
+github.com/charmbracelet/x/xpty v0.1.4 h1:4jaW7u+8AHQMxesiVc+zUMsspu7GyDwtJO+gy/tFtW4=
+github.com/charmbracelet/x/xpty v0.1.4/go.mod h1:7t8P7BpPiolHJ1pLzz7/4ujDbD+sUxI9yA3CBOLOIcU=
+github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
+github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
 github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
@@ -46,15 +60,15 @@ github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
 github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
 github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
-github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
-github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
+github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
 github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
 github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
-github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
-github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
+github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
 github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
 github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
@@ -81,10 +95,12 @@ golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
 golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
 golang.org/x/net v0.38.0 h1:vRMAPTMaeGqVhG5QyLJHqNDwecKTomGeqbnfZyKlBI8=
 golang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
-golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.36.0 h1:zMPR+aF8gfksFprF/Nc/rd1wRS1EI6nDBGyWAvDzx2Q=
 golang.org/x/term v0.36.0/go.mod h1:Qu394IJq6V6dCBRgwqshf3mPF85AqzYEzofzRdZkWss=
 golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
diff --git a/internal/launcher/launcher.go b/internal/launcher/launcher.go
deleted file mode 100644
index 08d6130..0000000
--- a/internal/launcher/launcher.go
+++ /dev/null
@@ -1,103 +0,0 @@
-// Package launcher decides how to run a tracked tool in a new terminal tab.
-// It sits at the bottom of the import graph like internal/updater: no TUI
-// knowledge, a pure core (planFor over an injected env lookup) plus a thin
-// os.Getenv-facing wrapper (Detect).
-package launcher
-
-import (
-	"fmt"
-	"os"
-	"strings"
-)
-
-// Plan describes how to open the user's command in a new terminal tab.
-// When no supported terminal is detected, Fallback is true and Argv is empty —
-// the caller runs the command in the current window via tea.ExecProcess.
-type Plan struct {
-	Argv     []string // adapter command, executed directly (not through a shell)
-	Fallback bool     // no scripting API available; run in the current window
-	Terminal string   // human-readable adapter name ("tmux", "iTerm2", …)
-}
-
-// planFor is the pure detection core. The priority chain is deliberate:
-// $TMUX first, because inside tmux TERM_PROGRAM names the *outer* terminal and
-// a tmux window is the correct "tab" there; then TERM_PROGRAM/KITTY_WINDOW_ID
-// checks; anything else falls back.
-//
-// The user command always executes as `sh -c <cmd>` (tmux runs the string via
-// the user's shell itself). For tmux/kitty/wezterm the command and tool name
-// travel as argv elements — no escaping. For the two AppleScript paths the
-// command is interpolated into the script source, with appleScriptQuote as the
-// single escaping point.
-func planFor(env func(string) string, command, toolName string) Plan {
-	switch {
-	case env("TMUX") != "":
-		// "--" terminates option parsing: a user command edited to start with
-		// "-" must reach tmux as the shell command, not be eaten as a flag.
-		return Plan{
-			Terminal: "tmux",
-			Argv:     []string{"tmux", "new-window", "-n", toolName, "--", command},
-		}
-	case env("TERM_PROGRAM") == "iTerm.app":
-		script := fmt.Sprintf(`tell application "iTerm2"
-	tell current window
-		set newTab to (create tab with default profile)
-		tell current session of newTab
-			set name to "%s"
-			write text "%s"
-		end tell
-	end tell
-end tell`, appleScriptQuote(toolName), appleScriptQuote(command))
-		return Plan{
-			Terminal: "iTerm2",
-			Argv:     []string{"osascript", "-e", script},
-		}
-	case env("TERM_PROGRAM") == "Apple_Terminal":
-		// Terminal.app opens a *window*, not a tab: tabs are not scriptable
-		// without System Events. Honest degradation, documented in the plan.
-		script := fmt.Sprintf(`tell application "Terminal" to do script "%s"`, appleScriptQuote(command))
-		return Plan{
-			Terminal: "Terminal.app",
-			Argv:     []string{"osascript", "-e", script},
-		}
-	case env("KITTY_WINDOW_ID") != "":
-		// kitten @ needs a remote-control socket (`listen_on` in kitty.conf →
-		// exported KITTY_LISTEN_ON, which the subprocess inherits): the adapter
-		// runs detached with no controlling terminal, so the tty transport of
-		// plain `allow_remote_control yes` cannot work. Without the socket the
-		// run fails and the caller's auto-fallback launches in the current
-		// window instead.
-		return Plan{
-			Terminal: "kitty",
-			Argv:     []string{"kitten", "@", "launch", "--type=tab", "--tab-title", toolName, "sh", "-c", command},
-		}
-	case env("TERM_PROGRAM") == "WezTerm":
-		// Tab title left to wezterm defaults; naming needs a second pane-id
-		// round-trip — deliberately skipped.
-		return Plan{
-			Terminal: "WezTerm",
-			Argv:     []string{"wezterm", "cli", "spawn", "--", "sh", "-c", command},
-		}
-	default:
-		return Plan{Fallback: true}
-	}
-}
-
-// appleScriptQuote escapes a string for interpolation inside a double-quoted
-// AppleScript string literal: backslashes first, then double quotes, then the
-// control characters AppleScript literals cannot carry raw (a pasted newline
-// would otherwise split the literal and make osascript fail on user data —
-// AppleScript understands \n/\r/\t escapes).
-func appleScriptQuote(s string) string {
-	s = strings.ReplaceAll(s, `\`, `\\`)
-	s = strings.ReplaceAll(s, `"`, `\"`)
-	s = strings.ReplaceAll(s, "\n", `\n`)
-	s = strings.ReplaceAll(s, "\r", `\r`)
-	return strings.ReplaceAll(s, "\t", `\t`)
-}
-
-// Detect resolves the launch Plan for the current environment. Env-only — no
-// subprocesses — so it is safe to call inside Bubble Tea's Update.
-func Detect(command, toolName string) Plan {
-	return planFor(os.Getenv, command, toolName)
-}
diff --git a/internal/launcher/launcher_test.go b/internal/launcher/launcher_test.go
deleted file mode 100644
index 58182a8..0000000
--- a/internal/launcher/launcher_test.go
+++ /dev/null
@@ -1,191 +0,0 @@
-package launcher
-
-import (
-	"reflect"
-	"strings"
-	"testing"
-)
-
-// envFrom builds an env lookup over a fixed map; missing keys return "".
-func envFrom(m map[string]string) func(string) string {
-	return func(k string) string { return m[k] }
-}
-
-func TestPlanFor(t *testing.T) {
-	tests := []struct {
-		name         string
-		env          map[string]string
-		command      string
-		toolName     string
-		wantTerminal string
-		wantFallback bool
-		wantArgv     []string
-	}{
-		{
-			name:         "tmux",
-			env:          map[string]string{"TMUX": "/tmp/tmux-501/default,1234,0"},
-			command:      "yazi",
-			toolName:     "yazi",
-			wantTerminal: "tmux",
-			wantArgv:     []string{"tmux", "new-window", "-n", "yazi", "--", "yazi"},
-		},
-		{
-			name: "tmux wins over TERM_PROGRAM",
-			env: map[string]string{
-				"TMUX":         "/tmp/tmux-501/default,1234,0",
-				"TERM_PROGRAM": "iTerm.app",
-			},
-			command:      "fzf",
-			toolName:     "fzf",
-			wantTerminal: "tmux",
-			wantArgv:     []string{"tmux", "new-window", "-n", "fzf", "--", "fzf"},
-		},
-		{
-			name:         "kitty",
-			env:          map[string]string{"KITTY_WINDOW_ID": "3"},
-			command:      "dive nginx:latest",
-			toolName:     "dive",
-			wantTerminal: "kitty",
-			wantArgv:     []string{"kitten", "@", "launch", "--type=tab", "--tab-title", "dive", "sh", "-c", "dive nginx:latest"},
-		},
-		{
-			name:         "wezterm",
-			env:          map[string]string{"TERM_PROGRAM": "WezTerm"},
-			command:      "btop",
-			toolName:     "btop",
-			wantTerminal: "WezTerm",
-			wantArgv:     []string{"wezterm", "cli", "spawn", "--", "sh", "-c", "btop"},
-		},
-		{
-			name:         "empty env falls back",
-			env:          map[string]string{},
-			command:      "yazi",
-			toolName:     "yazi",
-			wantFallback: true,
-		},
-		{
-			name:         "unknown TERM_PROGRAM falls back",
-			env:          map[string]string{"TERM_PROGRAM": "ghostty"},
-			command:      "yazi",
-			toolName:     "yazi",
-			wantFallback: true,
-		},
-		{
-			name:         "tool name with spaces stays one argv element (tmux)",
-			env:          map[string]string{"TMUX": "x"},
-			command:      "docker run -it alpine",
-			toolName:     "my tool",
-			wantTerminal: "tmux",
-			wantArgv:     []string{"tmux", "new-window", "-n", "my tool", "--", "docker run -it alpine"},
-		},
-		{
-			name:         "dash-leading command survives tmux option parsing",
-			env:          map[string]string{"TMUX": "x"},
-			command:      "-la",
-			toolName:     "ls",
-			wantTerminal: "tmux",
-			wantArgv:     []string{"tmux", "new-window", "-n", "ls", "--", "-la"},
-		},
-		{
-			name:         "unicode tool name stays intact (kitty)",
-			env:          map[string]string{"KITTY_WINDOW_ID": "1"},
-			command:      "ls",
-			toolName:     "инструмент",
-			wantTerminal: "kitty",
-			wantArgv:     []string{"kitten", "@", "launch", "--type=tab", "--tab-title", "инструмент", "sh", "-c", "ls"},
-		},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			got := planFor(envFrom(tc.env), tc.command, tc.toolName)
-			if got.Fallback != tc.wantFallback {
-				t.Fatalf("Fallback = %v, want %v", got.Fallback, tc.wantFallback)
-			}
-			if got.Terminal != tc.wantTerminal {
-				t.Errorf("Terminal = %q, want %q", got.Terminal, tc.wantTerminal)
-			}
-			if tc.wantFallback {
-				if len(got.Argv) != 0 {
-					t.Errorf("fallback plan carries Argv %v, want empty", got.Argv)
-				}
-				return
-			}
-			if !reflect.DeepEqual(got.Argv, tc.wantArgv) {
-				t.Errorf("Argv = %#v, want %#v", got.Argv, tc.wantArgv)
-			}
-		})
-	}
-}
-
-func TestPlanForITerm(t *testing.T) {
-	got := planFor(envFrom(map[string]string{"TERM_PROGRAM": "iTerm.app"}), `echo "hi"`, "echo tool")
-	if got.Terminal != "iTerm2" || got.Fallback {
-		t.Fatalf("plan = %+v, want iTerm2 non-fallback", got)
-	}
-	if len(got.Argv) != 3 || got.Argv[0] != "osascript" || got.Argv[1] != "-e" {
-		t.Fatalf("Argv = %#v, want [osascript -e <script>]", got.Argv)
-	}
-	script := got.Argv[2]
-	if !strings.Contains(script, `tell application "iTerm2"`) {
-		t.Errorf("script missing iTerm2 tell block:\n%s", script)
-	}
-	if !strings.Contains(script, `write text "echo \"hi\""`) {
-		t.Errorf("script does not embed the escaped command:\n%s", script)
-	}
-	if !strings.Contains(script, `set name to "echo tool"`) {
-		t.Errorf("script does not set the session name:\n%s", script)
-	}
-}
-
-func TestPlanForAppleTerminal(t *testing.T) {
-	got := planFor(envFrom(map[string]string{"TERM_PROGRAM": "Apple_Terminal"}), `say "hi" \now`, "say")
-	if got.Terminal != "Terminal.app" || got.Fallback {
-		t.Fatalf("plan = %+v, want Terminal.app non-fallback", got)
-	}
-	want := `tell application "Terminal" to do script "say \"hi\" \\now"`
-	if len(got.Argv) != 3 || got.Argv[0] != "osascript" || got.Argv[1] != "-e" || got.Argv[2] != want {
-		t.Fatalf("Argv = %#v, want [osascript -e %q]", got.Argv, want)
-	}
-}
-
-func TestAppleScriptQuote(t *testing.T) {
-	tests := []struct {
-		in, want string
-	}{
-		{``, ``},
-		{`plain`, `plain`},
-		{`say "hi"`, `say \"hi\"`},
-		{`back\slash`, `back\\slash`},
-		{`\"`, `\\\"`},
-		{`a\\b"c`, `a\\\\b\"c`},
-		// Control characters an AppleScript literal cannot carry raw: a pasted
-		// newline must become the \n escape, not split the script source.
-		{"a\nb", `a\nb`},
-		{"a\rb", `a\rb`},
-		{"a\tb", `a\tb`},
-	}
-	for _, tc := range tests {
-		if got := appleScriptQuote(tc.in); got != tc.want {
-			t.Errorf("appleScriptQuote(%q) = %q, want %q", tc.in, got, tc.want)
-		}
-	}
-}
-
-func TestDetect(t *testing.T) {
-	// Clear every detection variable, then set TMUX: Detect must route through
-	// the real os.Getenv and yield the tmux plan.
-	t.Setenv("TMUX", "")
-	t.Setenv("TERM_PROGRAM", "")
-	t.Setenv("KITTY_WINDOW_ID", "")
-
-	if got := Detect("ls", "ls"); !got.Fallback {
-		t.Fatalf("Detect with empty env = %+v, want fallback", got)
-	}
-
-	t.Setenv("TMUX", "/tmp/tmux-1/default,1,0")
-	got := Detect("ls", "ls")
-	if got.Fallback || got.Terminal != "tmux" {
-		t.Fatalf("Detect with TMUX set = %+v, want tmux plan", got)
-	}
-}
diff --git a/internal/model/commands.go b/internal/model/commands.go
index f6d25cf..d7041ff 100644
--- a/internal/model/commands.go
+++ b/internal/model/commands.go
@@ -7,12 +7,10 @@ import (
 	"io"
 	"os"
 	"os/exec"
-	"runtime"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 
-	"github.com/stanlyzoolo/keepkit/internal/launcher"
 	"github.com/stanlyzoolo/keepkit/internal/loader"
 	"github.com/stanlyzoolo/keepkit/internal/logx"
 	"github.com/stanlyzoolo/keepkit/internal/proc"
@@ -49,68 +47,15 @@ func validateTokenCmd(token string) tea.Cmd {
 	})
 }
 
-// launchTimeout bounds a tab-open adapter subprocess. Adapters normally return
-// near-instantly; the ceiling exists for the paths that can block on a human —
-// most notably osascript waiting on the macOS Automation permission dialog.
-// When it fires, the launchDoneMsg error handler auto-falls back to running the
-// tool in the current window, so the launch still happens. A var, not a const:
-// the timeout/KillGroup wiring is load-bearing and tests shrink it instead of
-// waiting 10 real seconds (the same seam idiom as updater's testHomeDir).
-var launchTimeout = 10 * time.Second
-
-// launchDoneMsg carries the result of a tab-open adapter run (startLaunchCmd).
-// command is the user's shell command, carried so the error handler can build
-// the ExecProcess fallback without re-reading input state.
-type launchDoneMsg struct {
-	toolName string
-	command  string
-	err      error
-}
-
-// execDoneMsg is the tea.ExecProcess callback result for the fallback path:
-// the tool ran in the current window and keepkit resumed. err is the tool's
-// own exit status — a tool exiting non-zero is not a keepkit anomaly, so the
-// handler surfaces it as a statusMsg and never logs it.
-type execDoneMsg struct {
-	toolName string
-	err      error
-}
-
-// startLaunchCmd runs a tab-open adapter plan (tmux new-window, osascript,
-// kitten @ launch, …) and emits launchDoneMsg. The adapter is detached from
-// the controlling terminal like every other probe (proc.DetachTTY), and on the
-// timeout the whole process group is killed — DetachTTY's Setsid makes the
-// child a session leader, so a plain kill would orphan grandchildren. The
-// error is not logged here: the launchDoneMsg handler auto-falls back, so an
-// adapter failure is a degraded path, not a dead end.
-//
-// Accepted race: if the timeout kills an adapter that had already executed its
-// tab command (osascript stuck after `write text`, a stalled tmux server), the
-// error still triggers the fallback and the command runs twice. The window is
-// narrow and undetectable from here; the alternative — not falling back — would
-// strand every genuine failure.
-func startLaunchCmd(plan launcher.Plan, toolName, command string) tea.Cmd {
-	return safeCmd("startLaunchCmd", func() tea.Msg {
-		if len(plan.Argv) == 0 {
-			return launchDoneMsg{toolName: toolName, command: command, err: errors.New("empty launch command")}
-		}
-		ctx, cancel := context.WithTimeout(context.Background(), launchTimeout)
-		defer cancel()
-		cmd := exec.CommandContext(ctx, plan.Argv[0], plan.Argv[1:]...)
-		proc.DetachTTY(cmd)
-		cmd.Cancel = func() error { return proc.KillGroup(cmd) }
-		err := cmd.Run()
-		return launchDoneMsg{toolName: toolName, command: command, err: err}
-	})
-}
-
-// shellCommand resolves the shell invocation that runs the user's command in
-// the current window. Pure and goos-parameterized so both branches are
+// shellCommand resolves the shell invocation that runs the user's command on
+// the embedded terminal's pty. Pure and goos-parameterized so both branches are
 // table-testable without spawning anything — the exact mirror of
-// browserCommand's seam. The cmd /c branch rides Go's generic argv quoting,
-// which is not cmd.exe-aware — a command embedding double quotes can misparse
-// there; accepted on the degraded Windows path (the fix, SysProcAttr.CmdLine,
-// needs a per-GOOS file and a real Windows report to justify it).
+// browserCommand's seam, and the reason internal/term needs no goos knowledge
+// of its own: the model builds argv and hands it over.
+// The cmd /c branch rides Go's generic argv quoting, which is not cmd.exe-aware
+// — a command embedding double quotes can misparse there; accepted on the
+// degraded Windows path (the fix, SysProcAttr.CmdLine, needs a per-GOOS file
+// and a real Windows report to justify it).
 // updater.customPlan is the deliberate duplicate of this decision on the update
 // path (updater sits below model in the import graph and may not import it);
 // the two must not drift.
@@ -121,39 +66,6 @@ func shellCommand(goos, cmd string) (string, []string) {
 	return "sh", []string{"-c", cmd}
 }
 
-// execToolCmd runs command in the current window via tea.ExecProcess: Bubble
-// Tea releases the terminal, the tool takes it over, and keepkit resumes when
-// it exits. This is the fallback for terminals with no tab-scripting API and
-// the safety net when an adapter fails. Deliberately not wrapped in safeCmd:
-// tea.ExecProcess only builds the exec message — nothing here can panic.
-func execToolCmd(toolName, command string) tea.Cmd {
-	name, args := shellCommand(runtime.GOOS, command)
-	return tea.ExecProcess(exec.Command(name, args...), execDoneCallback(toolName))
-}
-
-// execDoneCallback maps the tea.ExecProcess completion error into execDoneMsg
-// for toolName. Extracted from execToolCmd so the mapping is testable — the
-// exec message Bubble Tea builds keeps its callback field unexported.
-func execDoneCallback(toolName string) func(error) tea.Msg {
-	return func(err error) tea.Msg {
-		return execDoneMsg{toolName: toolName, err: err}
-	}
-}
-
-// notFoundExit reports whether err is the shell's "command not found" exit
-// status: 127 from sh (POSIX), 9009 from cmd.exe. Exit 127 means the tool
-// never ran at all, so the execDoneMsg handler can say "not installed"
-// instead of a cryptic exit status. Only the ExecProcess fallback can see
-// this — a tab adapter's shell reports the miss inside its own tab.
-func notFoundExit(err error) bool {
-	var ee *exec.ExitError
-	if !errors.As(err, &ee) {
-		return false
-	}
-	code := ee.ExitCode()
-	return code == 127 || code == 9009
-}
-
 // fetchInstalledCmd returns a Cmd that detects the installed version of t
 // locally (subprocess) and emits an installedMsg. It never touches the network,
 // so the installed version can render before any GitHub fetch completes.
diff --git a/internal/model/launch_test.go b/internal/model/launch_test.go
index 2529ea4..0446b5a 100644
--- a/internal/model/launch_test.go
+++ b/internal/model/launch_test.go
@@ -1,45 +1,18 @@
 package model
 
 import (
-	"errors"
-	"fmt"
-	"os/exec"
-	"runtime"
-	"strings"
 	"testing"
-	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 
-	"github.com/stanlyzoolo/keepkit/internal/launcher"
-	"github.com/stanlyzoolo/keepkit/internal/logx"
+	"github.com/stanlyzoolo/keepkit/internal/loader"
 )
 
-// assertExecMsg pins the ExecProcess path: the cmd's message must be Bubble
-// Tea's internal exec message. The matching rule (type-name substring, not
-// the exact "tea.execMsg" — the type is unexported and a bubbletea rename
-// would otherwise break these tests confusingly; launchDoneMsg excluded)
-// lives in execMsgIn, the single definition for both helpers.
-func assertExecMsg(t *testing.T, msg tea.Msg) {
-	t.Helper()
-	if !execMsgIn(msg) {
-		t.Errorf("msg = %+v (%T), want Bubble Tea's exec message", msg, msg)
-	}
-}
-
-// clearTerminalEnv blanks every variable launcher.Detect inspects, so the
-// detection chain lands on the fallback plan regardless of the terminal the
-// tests actually run in. planFor is unexported and cross-package — env is the
-// seam.
-func clearTerminalEnv(t *testing.T) {
-	t.Helper()
-	t.Setenv("TMUX", "")
-	t.Setenv("TERM_PROGRAM", "")
-	t.Setenv("KITTY_WINDOW_ID", "")
-}
-
 // enterRun drives updateRunInput's enter with value as the typed command and
 // returns the resulting model and dispatched cmd.
+//
+// The cmd is never *executed* by these tests: it starts a real pty, which
+// belongs in internal/term's own tests and nowhere near a model test.
 func enterRun(m Model, value string) (Model, tea.Cmd) {
 	m.mode = modeRunInput
 	m.runInput.SetValue(value)
@@ -47,8 +20,18 @@ func enterRun(m Model, value string) (Model, tea.Cmd) {
 	return updated.(Model), cmd
 }
 
+// runModel is a laid-out model with two tools, sized so the overlay fits.
+func runModel(t *testing.T, w, h int) Model {
+	t.Helper()
+
+	m := New([]loader.ToolMeta{{Name: "git"}, {Name: "fd"}})
+	return mustModel(m.Update(tea.WindowSizeMsg{Width: w, Height: h}))
+}
+
 // TestShellCommand pins both branches of the goos-parameterized shell seam:
-// unix runs the command through sh -c, Windows through cmd /c.
+// unix runs the command through sh -c, Windows through cmd /c. It survives the
+// tab launcher because the overlay builds its argv with it — which is what
+// keeps internal/term goos-agnostic.
 func TestShellCommand(t *testing.T) {
 	tests := []struct {
 		goos     string
@@ -77,465 +60,132 @@ func TestShellCommand(t *testing.T) {
 	}
 }
 
-// TestStartLaunchCmd runs the adapter command constructor against harmless
-// argvs: a succeeding binary yields a nil-err launchDoneMsg carrying the tool
-// and command, a missing binary a non-nil err, and an empty argv (which a
-// fallback plan would have — dispatch must never route one here) errors
-// instead of panicking on Argv[0].
-func TestStartLaunchCmd(t *testing.T) {
-	t.Run("success", func(t *testing.T) {
-		if runtime.GOOS == "windows" {
-			t.Skip("needs the unix true binary")
-		}
-		msg, ok := startLaunchCmd(launcher.Plan{Argv: []string{"true"}}, "git", "git status")().(launchDoneMsg)
-		if !ok {
-			t.Fatalf("unexpected msg type %T", msg)
-		}
-		if msg.err != nil {
-			t.Errorf("err = %v, want nil", msg.err)
-		}
-		if msg.toolName != "git" || msg.command != "git status" {
-			t.Errorf("msg = %+v, want toolName git and command carried", msg)
-		}
-	})
-	t.Run("missing adapter binary", func(t *testing.T) {
-		msg, ok := startLaunchCmd(launcher.Plan{Argv: []string{"keepkit-no-such-adapter-xyz"}}, "git", "git status")().(launchDoneMsg)
-		if !ok {
-			t.Fatalf("unexpected msg type %T", msg)
-		}
-		if msg.err == nil {
-			t.Error("err = nil, want the exec failure")
-		}
-	})
-	t.Run("empty argv", func(t *testing.T) {
-		msg, ok := startLaunchCmd(launcher.Plan{}, "git", "git status")().(launchDoneMsg)
-		if !ok {
-			t.Fatalf("unexpected msg type %T", msg)
-		}
-		if msg.err == nil {
-			t.Error("err = nil, want an empty-command error")
-		}
-	})
-}
-
-// TestStartLaunchCmdTimeout pins the load-bearing timeout wiring: when the
-// launchTimeout deadline fires, cmd.Cancel (proc.KillGroup on the process
-// group) kills the adapter and the launchDoneMsg carries the failure — this is
-// what routes a stuck osascript into the auto-fallback. launchTimeout is a var
-// precisely so this test does not wait 10 real seconds.
-func TestStartLaunchCmdTimeout(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("needs the unix sleep binary")
-	}
-	orig := launchTimeout
-	launchTimeout = 50 * time.Millisecond
-	defer func() { launchTimeout = orig }()
-
-	start := time.Now()
-	msg, ok := startLaunchCmd(launcher.Plan{Argv: []string{"sleep", "30"}}, "git", "git status")().(launchDoneMsg)
-	if !ok {
-		t.Fatalf("unexpected msg type %T", msg)
-	}
-	if msg.err == nil {
-		t.Fatal("err = nil, want the deadline kill")
-	}
-	if msg.toolName != "git" || msg.command != "git status" {
-		t.Errorf("msg = %+v, want toolName and command carried for the fallback", msg)
-	}
-	if elapsed := time.Since(start); elapsed > 5*time.Second {
-		t.Errorf("adapter outlived the deadline by %v — Cancel/KillGroup wiring is broken", elapsed)
-	}
-}
+// Enter on the prompt opens the overlay on the selected tool with the geometry
+// the frame will render at, and remembers the command for the next prompt.
+func TestRunInputEnterOpensOverlay(t *testing.T) {
+	m := runModel(t, 120, 34)
 
-// TestRunInputDispatchFallback: with no detectable terminal (env cleared) the
-// enter dispatch takes the ExecProcess path — the returned cmd yields Bubble
-// Tea's internal exec message, not a launchDoneMsg — and records lastRun.
-func TestRunInputDispatchFallback(t *testing.T) {
-	clearTerminalEnv(t)
-	m := newTestModel(focusTools)
-	nm, cmd := enterRun(m, "git status")
-	if nm.mode != modeNormal {
-		t.Errorf("mode = %d, want modeNormal", nm.mode)
-	}
-	if got := nm.lastRun["git"]; got != "git status" {
-		t.Errorf("lastRun[git] = %q, want %q", got, "git status")
-	}
-	if nm.launchingFor != "" {
-		t.Errorf("launchingFor = %q, want empty — the ExecProcess path needs no guard", nm.launchingFor)
-	}
-	if cmd == nil {
-		t.Fatal("cmd = nil, want the ExecProcess dispatch")
-	}
-	// Invoking the cmd only builds the message — the process runs later, when
-	// the runtime handles it — so nothing is spawned here.
-	assertExecMsg(t, cmd())
-}
+	nm, cmd := enterRun(m, "git log --oneline")
 
-// TestRunInputDispatchAdapter: with $TMUX set (pointing at a bogus socket, so
-// invoking the cmd cannot touch a real tmux server) the enter dispatch takes
-// the adapter path — the returned cmd emits launchDoneMsg carrying the tool
-// name and command for the auto-fallback.
-func TestRunInputDispatchAdapter(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("invoking the adapter cmd needs a unix tmux/exec environment")
+	if nm.mode != modeToolOverlay {
+		t.Fatalf("mode = %v after enter, want modeToolOverlay", nm.mode)
 	}
-	clearTerminalEnv(t)
-	t.Setenv("TMUX", "/nonexistent/keepkit-test-socket,99999,0")
-	m := newTestModel(focusTools)
-	nm, cmd := enterRun(m, "git status")
-	if got := nm.lastRun["git"]; got != "git status" {
-		t.Errorf("lastRun[git] = %q, want %q", got, "git status")
+	if nm.termToolName != "git" {
+		t.Errorf("termToolName = %q, want %q", nm.termToolName, "git")
 	}
-	// Dispatch feedback + one-launch-at-a-time guard: the adapter can block
-	// for seconds, so the user must see progress and a second enter must not
-	// dispatch concurrently.
-	if nm.launchingFor != "git" {
-		t.Errorf("launchingFor = %q, want %q", nm.launchingFor, "git")
+	wantW, wantH, _ := nm.termGeometry()
+	if nm.termW != wantW || nm.termH != wantH {
+		t.Errorf("geometry = %dx%d, want %dx%d", nm.termW, nm.termH, wantW, wantH)
 	}
-	if !strings.Contains(nm.statusMsg, "launching git") || !strings.Contains(nm.statusMsg, "tmux") {
-		t.Errorf("statusMsg = %q, want launching feedback naming tool and terminal", nm.statusMsg)
+	if got := nm.lastRun["git"]; got != "git log --oneline" {
+		t.Errorf("lastRun[git] = %q, want the dispatched command", got)
 	}
 	if cmd == nil {
-		t.Fatal("cmd = nil, want the adapter dispatch")
+		t.Error("enter dispatched no command")
 	}
-	msg, ok := cmd().(launchDoneMsg)
-	if !ok {
-		t.Fatalf("unexpected msg type %T, want launchDoneMsg", msg)
+	// nothing has started yet: the session arrives with termStartedMsg
+	if nm.termSession != nil || nm.termEmu != nil {
+		t.Error("the session or emulator existed before termStartedMsg")
 	}
-	if msg.toolName != "git" || msg.command != "git status" {
-		t.Errorf("msg = %+v, want toolName and command carried for the fallback", msg)
-	}
-	// err is not asserted: tmux may be missing entirely or fail to connect to
-	// the bogus socket — either way the adapter path emitted its message.
 }
 
-// TestLaunchDoneMsgFallback: an adapter failure sets an explanatory statusMsg
-// and auto-falls back to the ExecProcess path, so the tool still launches.
-// Nothing is logged — the fallback makes this degraded, not broken.
-func TestLaunchDoneMsgFallback(t *testing.T) {
-	logDir := t.TempDir()
-	restore := logx.SetDirForTesting(logDir)
-	defer restore()
+// The prompt prefills with the last command for that tool, falling back to the
+// tool's own name.
+func TestRunInputPrefill(t *testing.T) {
+	m := runModel(t, 120, 34)
 
-	m := newTestModel(focusTools)
-	m.launchingFor = "git"
-	updated, cmd := m.Update(launchDoneMsg{toolName: "git", command: "git status", err: errors.New("osascript: not authorized")})
-	nm := updated.(Model)
-	if nm.launchingFor != "" {
-		t.Errorf("launchingFor = %q, want the guard cleared", nm.launchingFor)
+	opened := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyEnter}))
+	if opened.mode != modeRunInput {
+		t.Fatalf("mode = %v, want modeRunInput", opened.mode)
 	}
-	if nm.statusMsg == "" || !strings.Contains(nm.statusMsg, "git") {
-		t.Errorf("statusMsg = %q, want a tab-failure explanation naming the tool", nm.statusMsg)
+	if got := opened.runInput.Value(); got != "git" {
+		t.Errorf("prefill = %q, want the tool name", got)
 	}
-	if cmd == nil {
-		t.Fatal("cmd = nil, want the ExecProcess auto-fallback")
-	}
-	assertExecMsg(t, cmd())
-	if out := logx.ReadAllForTesting(logDir); out != "" {
-		t.Errorf("adapter failure must not log (auto-fallback handles it), got:\n%s", out)
-	}
-}
 
-// execMsgIn walks a cmd's produced message, flattening tea batches, and
-// reports whether some leaf is Bubble Tea's exec message (matched like
-// assertExecMsg — type-name substring, launchDoneMsg excluded).
-func execMsgIn(msg tea.Msg) bool {
-	if batch, ok := msg.(tea.BatchMsg); ok {
-		for _, c := range batch {
-			if c != nil && execMsgIn(c()) {
-				return true
-			}
-		}
-		return false
+	ran, _ := enterRun(opened, "git status -sb")
+	ran.mode = modeNormal
+	reopened := mustModel(ran.Update(tea.KeyMsg{Type: tea.KeyEnter}))
+	if got := reopened.runInput.Value(); got != "git status -sb" {
+		t.Errorf("prefill = %q, want the remembered command", got)
 	}
-	if _, isLaunch := msg.(launchDoneMsg); isLaunch {
-		return false
-	}
-	return strings.Contains(fmt.Sprintf("%T", msg), "exec")
 }
 
-// TestLaunchDoneMsgModeGateDefersFallback: a delayed adapter failure
-// (osascript can block on the Automation dialog until launchTimeout) must NOT
-// auto-fall back while another mode owns the screen — tea.ExecProcess would
-// seize the terminal under an open editor/overlay and route keystrokes to the
-// spawned shell. The failure must not be silent either: the fallback is
-// deferred, and the keystroke that closes the mode flushes it — dispatching
-// the exec fallback directly (no adapter re-run) with a status message the
-// normal-mode status bar actually renders. The visibility assertion is the
-// point: a statusMsg set at gate time is shadowed by the mode's own
-// status-bar branch and wiped by the blanket KeyMsg reset.
-func TestLaunchDoneMsgModeGateDefersFallback(t *testing.T) {
-	for _, mode := range []inputMode{modeEditNote, modeSearch, modeAPIStatus, modeTrack, modeRunInput, modeHotkeys} {
-		m := newTestModel(focusTools)
-		m.mode = mode
-		m.launchingFor = "git"
-		updated, cmd := m.Update(launchDoneMsg{toolName: "git", command: "git status", err: errors.New("osascript: not authorized")})
-		nm := updated.(Model)
-		if cmd != nil {
-			t.Errorf("mode %d: cmd != nil — the auto-fallback fired under an open mode", mode)
-		}
-		if nm.mode != mode {
-			t.Errorf("mode %d: mode changed to %d, want untouched", mode, nm.mode)
-		}
-		if nm.launchingFor != "" {
-			t.Errorf("mode %d: launchingFor = %q, want the guard cleared", mode, nm.launchingFor)
-		}
-		if nm.pendingLaunchName != "git" || nm.pendingLaunchCommand != "git status" {
-			t.Errorf("mode %d: pending = %q/%q, want the deferred fallback stored", mode, nm.pendingLaunchName, nm.pendingLaunchCommand)
-		}
-
-		// The mode-closing keystroke (esc exits every one of these modes)
-		// flushes the deferred fallback.
-		closed, flushCmd := nm.Update(tea.KeyMsg{Type: tea.KeyEsc})
-		fm := closed.(Model)
-		if fm.mode != modeNormal {
-			t.Fatalf("mode %d: esc left mode %d, want modeNormal", mode, fm.mode)
-		}
-		if fm.pendingLaunchName != "" || fm.pendingLaunchCommand != "" {
-			t.Errorf("mode %d: pending = %q/%q after flush, want cleared", mode, fm.pendingLaunchName, fm.pendingLaunchCommand)
-		}
-		if flushCmd == nil {
-			t.Fatalf("mode %d: flush cmd = nil, want the exec fallback dispatched", mode)
-		}
-		if !execMsgIn(flushCmd()) {
-			t.Errorf("mode %d: flush cmd produced no exec message — the fallback did not fire", mode)
-		}
-		// VISIBILITY: the message must survive the mode-closing keystroke and
-		// render on the normal-mode status bar.
-		if bar := stripANSI(fm.renderStatusBar()); !strings.Contains(bar, "tab open failed — running git here") {
-			t.Errorf("mode %d: status bar = %q, want the fallback message rendered", mode, bar)
-		}
-	}
-}
-
-// TestLaunchDoneMsgModeGateTokenInputTwoStage: modeTokenInput's esc falls back
-// to modeAPIStatus, not modeNormal — the deferred fallback must stay pending
-// through that intermediate stop and flush only on the esc that actually
-// closes the overlay.
-func TestLaunchDoneMsgModeGateTokenInputTwoStage(t *testing.T) {
-	m := newTestModel(focusTools)
-	m.mode = modeTokenInput
-	updated, _ := m.Update(launchDoneMsg{toolName: "git", command: "git status", err: errors.New("osascript: not authorized")})
-	nm := updated.(Model)
+// A screen with no room for an overlay refuses, and — the part that matters —
+// writes no lastRun: a launch that never started is not something to remember.
+func TestRunInputRefusesOnTinyTerminal(t *testing.T) {
+	shrinkStatusTTL(t)
+	m := runModel(t, 60, 20)
 
-	stage1, cmd1 := nm.Update(tea.KeyMsg{Type: tea.KeyEsc})
-	sm := stage1.(Model)
-	if sm.mode != modeAPIStatus {
-		t.Fatalf("mode = %d after first esc, want modeAPIStatus", sm.mode)
-	}
-	if cmd1 != nil && execMsgIn(cmd1()) {
-		t.Error("exec fallback fired while the API overlay is still open")
-	}
-	if sm.pendingLaunchName != "git" {
-		t.Errorf("pendingLaunchName = %q, want kept through the modeAPIStatus stop", sm.pendingLaunchName)
-	}
+	nm, _ := enterRun(m, "git log")
 
-	stage2, cmd2 := sm.Update(tea.KeyMsg{Type: tea.KeyEsc})
-	fm := stage2.(Model)
-	if fm.mode != modeNormal {
-		t.Fatalf("mode = %d after second esc, want modeNormal", fm.mode)
+	if nm.mode == modeToolOverlay {
+		t.Error("the overlay opened on a terminal too small for it")
 	}
-	if fm.pendingLaunchName != "" {
-		t.Errorf("pendingLaunchName = %q, want cleared by the flush", fm.pendingLaunchName)
+	if nm.statusMsg != "terminal too small to run a tool" {
+		t.Errorf("statusMsg = %q, want the refusal", nm.statusMsg)
 	}
-	if cmd2 == nil || !execMsgIn(cmd2()) {
-		t.Error("second esc produced no exec message — the deferred fallback never ran")
-	}
-	if bar := stripANSI(fm.renderStatusBar()); !strings.Contains(bar, "tab open failed — running git here") {
-		t.Errorf("status bar = %q, want the fallback message rendered", bar)
+	if _, ok := nm.lastRun["git"]; ok {
+		t.Error("a refused launch was recorded in lastRun")
 	}
 }
 
-// TestRunInputRedispatchSupersedesPendingLaunch: a gated adapter failure can
-// land while the run prompt is open. An explicit new dispatch from that
-// prompt supersedes the deferred fallback — flushing both on the same enter
-// would run two commands.
-func TestRunInputRedispatchSupersedesPendingLaunch(t *testing.T) {
-	clearTerminalEnv(t)
-	m := newTestModel(focusTools)
-	m.pendingLaunchName = "git"
-	m.pendingLaunchCommand = "git status"
-	nm, cmd := enterRun(m, "git log")
-	if nm.pendingLaunchName != "" || nm.pendingLaunchCommand != "" {
-		t.Errorf("pending = %q/%q, want dropped by the new dispatch", nm.pendingLaunchName, nm.pendingLaunchCommand)
-	}
-	if cmd == nil {
-		t.Fatal("cmd = nil, want the new command dispatched")
-	}
-	msg := cmd()
-	if _, isBatch := msg.(tea.BatchMsg); isBatch {
-		t.Fatalf("msg = %T, want a single exec dispatch — a batch means the stale fallback ran too", msg)
-	}
-	assertExecMsg(t, msg)
-	if strings.Contains(nm.statusMsg, "tab open failed") {
-		t.Errorf("statusMsg = %q, want no stale-fallback message on a fresh dispatch", nm.statusMsg)
-	}
-}
+// esc and empty input both cancel without opening anything.
+func TestRunInputCancels(t *testing.T) {
+	t.Run("esc", func(t *testing.T) {
+		m := runModel(t, 120, 34)
+		m.mode = modeRunInput
+		m.runInput.SetValue("git log")
 
-// TestUntrackConfirmDropsPendingLaunchForSameTool: a deferred fallback for
-// the tool being untracked dies with the untrack — the dialog-closing enter
-// funnels through flushPendingLaunch and would otherwise exec the
-// now-untracked tool's command.
-func TestUntrackConfirmDropsPendingLaunchForSameTool(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
-	m := newTestModel(focusTools)
-	m.mode = modeConfirmUntrack
-	m.untrackTarget = "git"
-	m.pendingLaunchName = "git"
-	m.pendingLaunchCommand = "git status"
-	updated, cmd := m.Update(tea.KeyMsg{Type: tea.KeyEnter})
-	nm := updated.(Model)
-	if nm.pendingLaunchName != "" || nm.pendingLaunchCommand != "" {
-		t.Errorf("pending = %q/%q, want dropped by the untrack", nm.pendingLaunchName, nm.pendingLaunchCommand)
-	}
-	if strings.Contains(nm.statusMsg, "tab open failed") {
-		t.Errorf("statusMsg = %q, want no fallback message for the untracked tool", nm.statusMsg)
-	}
-	if cmd != nil && execMsgIn(cmd()) {
-		t.Error("exec fallback fired for the tool that was just untracked")
-	}
-}
-
-// TestRunInputInFlightGuard: while an adapter run is pending (launchingFor
-// set), a second enter dispatches nothing and does not record lastRun — one
-// launch at a time, mirroring updatingFor.
-func TestRunInputInFlightGuard(t *testing.T) {
-	clearTerminalEnv(t)
-	m := newTestModel(focusTools)
-	m.launchingFor = "yazi"
-	nm, cmd := enterRun(m, "git status")
-	if cmd != nil {
-		t.Error("cmd != nil, want the dispatch blocked while a launch is in flight")
-	}
-	if len(nm.lastRun) != 0 {
-		t.Errorf("lastRun = %v, want empty — the blocked command never ran", nm.lastRun)
-	}
-	if !strings.Contains(nm.statusMsg, "yazi") {
-		t.Errorf("statusMsg = %q, want it naming the in-flight launch", nm.statusMsg)
-	}
-}
-
-// TestLaunchDoneMsgSuccess: a clean adapter run reports "launched <name>"
-// (mode-neutral — Terminal.app and tmux open a window, not a tab) and
-// dispatches nothing further.
-func TestLaunchDoneMsgSuccess(t *testing.T) {
-	shrinkStatusTTL(t)
-	m := newTestModel(focusTools)
-	m.launchingFor = "git"
-	updated, cmd := m.Update(launchDoneMsg{toolName: "git", command: "git status"})
-	nm := updated.(Model)
-	if nm.statusMsg != "launched git" {
-		t.Errorf("statusMsg = %q, want %q", nm.statusMsg, "launched git")
-	}
-	if nm.launchingFor != "" {
-		t.Errorf("launchingFor = %q, want the guard cleared", nm.launchingFor)
-	}
-	// Success dispatches nothing further — only the transient-status expiry tick.
-	assertOnlyExpiryTick(t, cmd)
-}
-
-// TestExecDoneMsg: the ExecProcess callback result. A non-zero exit surfaces
-// as a statusMsg and is never logged (the tool's exit status is not a keepkit
-// anomaly); a clean exit is silent.
-func TestExecDoneMsg(t *testing.T) {
-	shrinkStatusTTL(t)
-	t.Run("non-zero exit", func(t *testing.T) {
-		logDir := t.TempDir()
-		restore := logx.SetDirForTesting(logDir)
-		defer restore()
-
-		m := newTestModel(focusTools)
-		updated, cmd := m.Update(execDoneMsg{toolName: "git", err: errors.New("exit status 1")})
-		nm := updated.(Model)
-		if want := "git exited: exit status 1"; nm.statusMsg != want {
-			t.Errorf("statusMsg = %q, want %q", nm.statusMsg, want)
-		}
-		// The status shows, but nothing else is dispatched — only its expiry tick.
-		assertOnlyExpiryTick(t, cmd)
-		if out := logx.ReadAllForTesting(logDir); out != "" {
-			t.Errorf("a tool's non-zero exit must not log, got:\n%s", out)
-		}
-	})
-	t.Run("clean exit", func(t *testing.T) {
-		m := newTestModel(focusTools)
-		updated, cmd := m.Update(execDoneMsg{toolName: "git"})
-		nm := updated.(Model)
-		if nm.statusMsg != "" {
-			t.Errorf("statusMsg = %q, want silence on a clean exit", nm.statusMsg)
+		nm := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyEsc}))
+		if nm.mode != modeNormal {
+			t.Errorf("mode = %v after esc, want modeNormal", nm.mode)
 		}
-		if cmd != nil {
-			t.Error("cmd != nil, want none")
+		if _, ok := nm.lastRun["git"]; ok {
+			t.Error("a cancelled prompt was recorded in lastRun")
 		}
 	})
-	t.Run("command not found exit", func(t *testing.T) {
-		if runtime.GOOS == "windows" {
-			t.Skip("needs the unix sh binary")
-		}
-		logDir := t.TempDir()
-		restore := logx.SetDirForTesting(logDir)
-		defer restore()
 
-		// A real 127 from the same shell the fallback uses — the tool never
-		// ran, so the message must say "not installed", not the exit status.
-		err := exec.Command("sh", "-c", "exit 127").Run()
-		m := newTestModel(focusTools)
-		updated, cmd := m.Update(execDoneMsg{toolName: "git", err: err})
-		nm := updated.(Model)
-		if want := "git not found — is it installed?"; nm.statusMsg != want {
-			t.Errorf("statusMsg = %q, want %q", nm.statusMsg, want)
-		}
-		// The status shows, but nothing else is dispatched — only its expiry tick.
-		assertOnlyExpiryTick(t, cmd)
-		if out := logx.ReadAllForTesting(logDir); out != "" {
-			t.Errorf("a not-found exit must not log, got:\n%s", out)
-		}
-	})
+	for _, blank := range []string{"", "   "} {
+		t.Run("blank "+blank, func(t *testing.T) {
+			m := runModel(t, 120, 34)
+			nm, cmd := enterRun(m, blank)
+			if nm.mode != modeNormal {
+				t.Errorf("mode = %v, want modeNormal", nm.mode)
+			}
+			if cmd != nil {
+				t.Error("a blank command dispatched something")
+			}
+		})
+	}
 }
 
-// TestNotFoundExit pins the "command not found" classifier: only the shell's
-// own not-found exit codes (127 sh, 9009 cmd.exe) qualify — an ordinary
-// non-zero exit, a non-ExitError and nil all stay on the generic path.
-func TestNotFoundExit(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("needs the unix sh binary")
-	}
-	exit127 := exec.Command("sh", "-c", "exit 127").Run()
-	exit1 := exec.Command("sh", "-c", "exit 1").Run()
+// Enter on an empty tracker opens nothing: there is no tool to run.
+func TestRunInputEmptyList(t *testing.T) {
+	m := New(nil)
+	mm := mustModel(m.Update(tea.WindowSizeMsg{Width: 120, Height: 34}))
 
-	tests := []struct {
-		name string
-		err  error
-		want bool
-	}{
-		{"shell not-found 127", exit127, true},
-		{"ordinary failure 1", exit1, false},
-		{"non-ExitError", errors.New("exit status 127"), false},
-		{"nil", nil, false},
+	nm, cmd := mm.Update(tea.KeyMsg{Type: tea.KeyEnter})
+
+	if nm.(Model).mode != modeNormal {
+		t.Errorf("mode = %v on an empty list, want modeNormal", nm.(Model).mode)
 	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := notFoundExit(tt.err); got != tt.want {
-				t.Errorf("notFoundExit(%v) = %v, want %v", tt.err, got, tt.want)
-			}
-		})
+	if cmd != nil {
+		t.Error("enter on an empty list dispatched a command")
 	}
 }
 
-// TestExecDoneCallback pins the ExecProcess completion mapping that
-// execToolCmd hands to Bubble Tea: the callback must carry the tool name and
-// the error into execDoneMsg (the exec message's callback field is unexported,
-// so this is the only way to exercise it).
-func TestExecDoneCallback(t *testing.T) {
-	fail := errors.New("exit status 2")
-	msg, ok := execDoneCallback("git")(fail).(execDoneMsg)
-	if !ok {
-		t.Fatalf("unexpected msg type %T", msg)
-	}
-	if msg.toolName != "git" || !errors.Is(msg.err, fail) {
-		t.Errorf("msg = %+v, want toolName git and the error carried", msg)
+// An update running in [3] does not block a launch: they are independent, and
+// the log keeps streaming under the overlay's dim.
+func TestRunDuringUpdate(t *testing.T) {
+	m := runModel(t, 120, 34)
+	m.updatingFor = "fd"
+
+	nm, cmd := enterRun(m, "git status")
+
+	if nm.mode != modeToolOverlay {
+		t.Errorf("mode = %v during a running update, want the overlay to open anyway", nm.mode)
 	}
-	clean, ok := execDoneCallback("git")(nil).(execDoneMsg)
-	if !ok || clean.err != nil {
-		t.Errorf("clean exit mapping = %+v, want nil err", clean)
+	if cmd == nil {
+		t.Error("no command dispatched during a running update")
 	}
 }
diff --git a/internal/model/mode.go b/internal/model/mode.go
index 945ee68..d149ee6 100644
--- a/internal/model/mode.go
+++ b/internal/model/mode.go
@@ -2,12 +2,12 @@ package model
 
 import (
 	"fmt"
+	"runtime"
 	"strings"
 
 	"github.com/charmbracelet/bubbles/textinput"
 	tea "github.com/charmbracelet/bubbletea"
 
-	"github.com/stanlyzoolo/keepkit/internal/launcher"
 	"github.com/stanlyzoolo/keepkit/internal/loader"
 	"github.com/stanlyzoolo/keepkit/internal/updater"
 	"github.com/stanlyzoolo/keepkit/internal/version"
@@ -28,11 +28,12 @@ const (
 	modeTrack                    // "t", global
 	modeConfirmUntrack           // "u", global
 	modeRename                   // "m", global
-	modeRunInput                 // enter in focusTools: run the tool in a new terminal tab
+	modeRunInput                 // enter in focusTools: the run prompt
 	modeConfirmUpdate            // enter in focusBrief (or "U"): confirm the detected update command
 	modeAPIStatus                // "a": rate-limit / token overlay
 	modeTokenInput               // "e" inside the overlay: masked token entry
 	modeHotkeys                  // "?": static hotkeys-help overlay
+	modeToolOverlay              // enter in focusTools: the tool runs in an embedded terminal
 )
 
 // apiOverlayVisible reports whether the API-status overlay is on screen —
@@ -42,11 +43,12 @@ func (m Model) apiOverlayVisible() bool {
 }
 
 // overlayVisible reports whether any modal overlay is composited over the
-// layout — the [a] API-status overlay (incl. token entry) or the [?] hotkeys
-// overlay. It is the single "modal on screen" predicate for View() and the
-// mouse gate, so a new overlay only has to extend this one helper.
+// layout — the [a] API-status overlay (incl. token entry), the [?] hotkeys
+// overlay, or the embedded tool terminal. It is the single "modal on screen"
+// predicate for View() and the mouse gate, so a new overlay only has to extend
+// this one helper.
 func (m Model) overlayVisible() bool {
-	return m.apiOverlayVisible() || m.mode == modeHotkeys
+	return m.apiOverlayVisible() || m.mode == modeHotkeys || m.mode == modeToolOverlay
 }
 
 // updateHotkeys handles keys while the [?] hotkeys overlay is open: esc, q, or
@@ -213,16 +215,6 @@ func (m Model) updateUntrackConfirm(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	switch msg.String() {
 	case "enter":
 		m.mode = modeNormal
-		// A deferred launch fallback for this same tool dies with the
-		// untrack: this dialog-closing enter funnels through
-		// flushPendingLaunch, which would otherwise exec the now-untracked
-		// tool's command. A pending fallback for a *different* tool
-		// deliberately survives and flushes on this keystroke — that launch
-		// was requested before the dialog opened and its tool is still
-		// tracked.
-		if m.pendingLaunchName == m.untrackTarget {
-			m.pendingLaunchName, m.pendingLaunchCommand = "", ""
-		}
 		m.meta = loader.RemoveMeta(m.meta, m.untrackTarget)
 		loader.SaveMeta(m.meta) //nolint:errcheck
 		m.tools = loader.ToolsFromMeta(m.meta)
@@ -319,14 +311,12 @@ func (m Model) updateRenameInput(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 
 // updateRunInput handles the one-line run prompt opened by enter in focusTools
 // (modeRunInput): esc cancels back to modeNormal; enter with empty/whitespace
-// input cancels too; enter with text records the command in m.lastRun and
-// dispatches the launch. launcher.Detect is env-only (no subprocesses), so it
-// is safe to call here on the Update thread: a fallback plan runs the tool in
-// the current window via tea.ExecProcess, any other plan opens a terminal tab
-// via startLaunchCmd (whose error handler auto-falls back to ExecProcess).
-// Adapter dispatch sets m.launchingFor (one launch at a time) and a
-// "launching <name> in <terminal>…" statusMsg — the in-flight feedback for the
-// seconds an adapter can block.
+// input cancels too; enter with text records the command in m.lastRun and opens
+// the embedded terminal overlay on it.
+//
+// The refusal comes first, and it is the reason lastRun is written where it is:
+// a screen with no room for an overlay means the tool never starts, and a
+// launch that never happened is not something to remember for the next prompt.
 func (m Model) updateRunInput(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	switch msg.String() {
 	case "enter":
@@ -340,36 +330,21 @@ func (m Model) updateRunInput(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		if !ok {
 			return m, nil
 		}
-		// One launch at a time: an adapter run can stay pending up to
-		// launchTimeout (osascript on the Automation dialog), and nothing else
-		// stops a second enter+enter from dispatching concurrently. The
-		// command is deliberately not recorded in lastRun — it never ran.
-		if m.launchingFor != "" {
-			// Sticky, not setStatus: this reports a launch that is *still in
-			// progress* (overwritten by launchDoneMsg). Letting a timer expire it
-			// mid-flight would hide the only sign the adapter is busy for up to
-			// launchTimeout — including a timer armed by a transient status set
-			// moments earlier, which is why the helper bumps statusSeq.
-			m.setStickyStatus("still launching " + m.launchingFor)
-			return m, nil
+
+		w, h, fits := m.termGeometry()
+		if !fits {
+			return m, m.setStatus("terminal too small to run a tool")
 		}
+
 		m.lastRun[mt.Name] = command
-		// An explicit new dispatch supersedes a fallback deferred while this
-		// prompt was open (a gated adapter failure landing mid-typing) —
-		// flushing both would run two commands on this same keystroke.
-		m.pendingLaunchName, m.pendingLaunchCommand = "", ""
-		plan := launcher.Detect(command, mt.Name)
-		if plan.Fallback {
-			return m, execToolCmd(mt.Name, command)
-		}
-		// In-flight feedback: the adapter can block for seconds, and without a
-		// statusMsg the prompt just closes and nothing visibly happens. Sticky,
-		// not setStatus: this must not expire mid-flight — it is extinguished by
-		// launchDoneMsg, not the clock, and a still-armed transient timer must
-		// not retire it either (setStickyStatus bumps the seq for that).
-		m.launchingFor = mt.Name
-		m.setStickyStatus("launching " + mt.Name + " in " + plan.Terminal + "…")
-		return m, startLaunchCmd(plan, mt.Name, command)
+		m.termToolName = mt.Name
+		m.termW, m.termH = w, h
+		m.mode = modeToolOverlay
+
+		// The model builds argv with the same shellCommand the old exec path
+		// used; internal/term stays goos-agnostic because of it.
+		shell, args := shellCommand(runtime.GOOS, command)
+		return m, startTermCmd(shell, args, w, h)
 	case "esc":
 		m.mode = modeNormal
 		m.runInput.Blur()
@@ -381,40 +356,6 @@ func (m Model) updateRunInput(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	}
 }
 
-// launchFallbackStatus is the single definition of the tab-failure fallback
-// message — shown by both the ungated launchDoneMsg auto-fallback (model.go)
-// and the deferred flush below, which must stay byte-identical (tests pin the
-// exact text).
-func launchFallbackStatus(name string) string {
-	return "tab open failed — running " + name + " here"
-}
-
-// flushPendingLaunch dispatches the exec fallback deferred by the
-// launchDoneMsg mode gate (see the pendingLaunchName field doc). Every modal
-// keystroke return in Update funnels through it: when the handler has just
-// brought the model back to modeNormal and a gated tab-open failure is
-// pending, the terminal is safe to seize again — the fallback fires now, with
-// the same statusMsg the ungated auto-fallback shows. Set here, AFTER the
-// blanket statusMsg reset and the mode handler, the message survives the
-// mode-closing keystroke, and modeNormal's renderStatusBar actually paints it
-// (every open mode's status-bar branch outranks statusMsg — a hint set at gate
-// time was dead UI). Going straight to execToolCmd — never back through
-// launcher.Detect — means the retry cannot re-run the known-failing adapter
-// plan. While the mode stays open (or modeTokenInput fell back to
-// modeAPIStatus) this is a no-op passthrough.
-func flushPendingLaunch(mdl tea.Model, cmd tea.Cmd) (tea.Model, tea.Cmd) {
-	// Plain assertion: every per-mode handler returns a Model value, and a
-	// future handler returning a different concrete type should fail loudly
-	// here, not silently skip the flush.
-	m := mdl.(Model)
-	if m.mode != modeNormal || m.pendingLaunchName == "" {
-		return mdl, cmd
-	}
-	name, command := m.pendingLaunchName, m.pendingLaunchCommand
-	m.pendingLaunchName, m.pendingLaunchCommand = "", ""
-	return m, tea.Batch(cmd, m.setStatus(launchFallbackStatus(name)), execToolCmd(name, command))
-}
-
 // updateConfirmUpdate handles the modeConfirmUpdate dialog (modeled on
 // modeConfirmUntrack): enter launches the update — set updatingFor, reset the
 // live log to the target, and fire the streaming command plus the spinner tick;
diff --git a/internal/model/mode_test.go b/internal/model/mode_test.go
index 9c5b257..5205dd8 100644
--- a/internal/model/mode_test.go
+++ b/internal/model/mode_test.go
@@ -1773,9 +1773,8 @@ func TestRunInputEmptyEnterCancels(t *testing.T) {
 
 // TestRunInputOpensDuringUpdate pins a deliberate decision: a running update
 // stream (updatingFor set) does NOT block the launch prompt — independent
-// concerns; ExecProcess pauses rendering of the live update log and the buffer
-// catches up on resume. A future "safety" guard here would silently change
-// documented behavior.
+// concerns; the log keeps streaming into [3] under the overlay's dim. A future
+// "safety" guard here would silently change documented behavior.
 func TestRunInputOpensDuringUpdate(t *testing.T) {
 	m := newTestModel(focusTools)
 	m.updatingFor = "git"
@@ -1786,14 +1785,19 @@ func TestRunInputOpensDuringUpdate(t *testing.T) {
 }
 
 // TestRunInputEnterStoresLastRun: a dispatching enter records the trimmed
-// command under the tool's name, so the next prompt prefills it.
+// command under the tool's name, so the next prompt prefills it, and leaves the
+// model in the overlay rather than back at modeNormal.
+//
+// The model has to go through a real WindowSizeMsg: the dispatch now measures
+// the screen first and refuses without one, which is also what the geometry
+// refusal test asserts from the other side.
 func TestRunInputEnterStoresLastRun(t *testing.T) {
-	m := newTestModel(focusTools)
+	m := mustModel(newTestModel(focusTools).Update(tea.WindowSizeMsg{Width: 120, Height: 34}))
 	m.mode = modeRunInput
 	m.runInput.SetValue("  git status  ")
 	nm := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyEnter}))
-	if nm.mode != modeNormal {
-		t.Errorf("mode = %d, want modeNormal", nm.mode)
+	if nm.mode != modeToolOverlay {
+		t.Errorf("mode = %d, want modeToolOverlay", nm.mode)
 	}
 	if got := nm.lastRun["git"]; got != "git status" {
 		t.Errorf("lastRun[git] = %q, want the trimmed %q", got, "git status")
diff --git a/internal/model/model.go b/internal/model/model.go
index 6017e1f..4d675b3 100644
--- a/internal/model/model.go
+++ b/internal/model/model.go
@@ -13,6 +13,7 @@ import (
 	"github.com/charmbracelet/bubbles/viewport"
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/lipgloss"
+	"github.com/charmbracelet/x/vt"
 
 	"github.com/stanlyzoolo/keepkit/internal/loader"
 	"github.com/stanlyzoolo/keepkit/internal/logx"
@@ -113,8 +114,9 @@ type readmeMsg struct {
 type statusExpiredMsg struct{ seq int }
 
 // statusMsgTTL is how long a transient status message holds the bar before it
-// yields back to the hints. A var, not a const, mirroring launchTimeout: tea.Tick
-// blocks for the full duration, so tests shrink it to inspect the produced
+// yields back to the hints. A var, not a const — the last shrinkable timeout
+// seam now that launchTimeout died with the tab launcher: tea.Tick blocks for
+// the full duration, so tests shrink it to inspect the produced
 // statusExpiredMsg without a real sleep.
 var statusMsgTTL = 1 * time.Second
 
@@ -284,8 +286,10 @@ type Model struct {
 	// bumps it on every transient message and stamps the value into the
 	// statusExpiredMsg tick it returns, so a stale timer (from a message already
 	// superseded by a newer one) is dropped instead of clearing the current
-	// message early. In-flight statuses ("launching …") bypass setStatus and so
-	// carry no timer — they are extinguished by launchDoneMsg, not the clock.
+	// message early. Every transient status goes through setStatus; work still
+	// in progress reports itself on the surface that owns it (the update log's
+	// outcome block, the overlay's exit row) rather than on a bar message that
+	// would have to outlive its own timer.
 	statusSeq int
 	width     int
 	height    int
@@ -313,27 +317,28 @@ type Model struct {
 	runInput textinput.Model
 	lastRun  map[string]string
 
-	// launchingFor is the one-adapter-launch-at-a-time guard (the launch twin
-	// of updatingFor): the name of the tool whose tab-open adapter run is in
-	// flight, empty when idle. Set on startLaunchCmd dispatch, cleared by
-	// launchDoneMsg. Without it a second enter+enter while osascript sits on
-	// the macOS Automation dialog (up to launchTimeout) would dispatch a
-	// concurrent adapter run. The ExecProcess fallback needs no guard — it
-	// suspends the TUI synchronously.
-	launchingFor string
-
-	// pendingLaunchName/Command hold the exec fallback deferred by the
-	// launchDoneMsg mode gate: the adapter failed while another mode owned the
-	// screen (tea.ExecProcess would seize the terminal under an open
-	// editor/overlay and route keystrokes to the spawned shell), so the
-	// fallback waits here until the keystroke that returns the model to
-	// modeNormal — flushPendingLaunch (mode.go) then dispatches it with a
-	// visible status message. A statusMsg set at gate time would be dead UI:
-	// every non-normal mode's renderStatusBar branch outranks the statusMsg
-	// branch, and the blanket statusMsg reset on tea.KeyMsg wipes it on the
-	// very keystroke that closes the mode.
-	pendingLaunchName    string
-	pendingLaunchCommand string
+	// The embedded tool terminal (modeToolOverlay). termSession is the running
+	// tool behind a narrow interface so tests can drive the handlers with a
+	// fake; termEmu is the VT emulator turning its bytes back into a screen and
+	// lives here, on the model, precisely so that only Update ever touches its
+	// screen state. termInput is the goroutine relaying encoded keys back to
+	// the tool (see its type doc for why one is needed at all).
+	//
+	// termExit is nil while the tool runs and holds the verdict afterwards — it
+	// is the single "has it finished" discriminator, which is why there is no
+	// separate flag and no "running" member on any enum. termW/termH are the
+	// emulator's body size, resolved from termGeometry at dispatch, and
+	// termToolName is what the frame and the status bar call it.
+	//
+	// The whole group is nil/zero outside the overlay: closeToolOverlay is the
+	// single teardown and clears every field, so a stale session can never
+	// outlive the mode.
+	termSession  termSession
+	termEmu      *vt.Emulator
+	termInput    *termInput
+	termExit     *termExitMsg
+	termW, termH int
+	termToolName string
 
 	// spinner animates while a force refresh ([r]) is in flight; refreshingFor
 	// holds the name of the tool being refreshed (empty = idle). refreshingFor
@@ -836,7 +841,8 @@ func (m *Model) selfUpdateKey() tea.Cmd {
 // queue) and while any input mode owns the keyboard: detection spawns
 // subprocesses and the answer can arrive seconds later, so a confirm dialog
 // opening under an editor, a search or an overlay would steal the keystroke
-// aimed at it (the same reasoning as launchDoneMsg's mode gate). Beyond that a
+// aimed at it — and under the tool overlay it would steal one the running tool
+// is waiting for. Beyond that a
 // tool result must still match the selection — the user may have moved on —
 // while keepkit's own has no selection to match: it is typically untracked and
 // the tracker may be empty.
@@ -1214,52 +1220,6 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		return m, nil
 
-	case launchDoneMsg:
-		// Tab-open adapter finished. Clear the one-launch-at-a-time guard
-		// first, so the fallback (or the user's retry) can dispatch again.
-		if m.launchingFor == msg.toolName {
-			m.launchingFor = ""
-		}
-		// On failure, auto-fall back to running the tool in the current
-		// window — the tool always launches, the status bar explains the
-		// degradation. Not logged: the fallback makes this a degraded path,
-		// not a keepkit malfunction.
-		if msg.err != nil {
-			// The result can arrive up to launchTimeout after enter (osascript
-			// blocked on the macOS Automation dialog). tea.ExecProcess seizes
-			// the terminal, so the auto-fallback fires only from the base
-			// state: under an open editor/overlay/search it would hijack the
-			// screen and send the user's keystrokes to the spawned shell —
-			// there the fallback is deferred instead: flushPendingLaunch
-			// dispatches it (same statusMsg, no adapter re-run) on the
-			// keystroke that returns the mode to modeNormal.
-			if m.mode != modeNormal {
-				m.pendingLaunchName = msg.toolName
-				m.pendingLaunchCommand = msg.command
-				return m, nil
-			}
-			return m, tea.Batch(
-				m.setStatus(launchFallbackStatus(msg.toolName)),
-				execToolCmd(msg.toolName, msg.command),
-			)
-		}
-		// Mode-neutral wording: Terminal.app and tmux open a window, not a tab.
-		return m, m.setStatus("launched " + msg.toolName)
-
-	case execDoneMsg:
-		// The tool ran in the current window and keepkit resumed. A non-zero
-		// exit belongs to the tool, not keepkit — statusMsg only, no logx.
-		// Exception in wording only: the shell's own "command not found"
-		// exit (notFoundExit) means the tool never ran, so the message says
-		// "not installed" instead of surfacing a cryptic exit status.
-		if msg.err != nil {
-			if notFoundExit(msg.err) {
-				return m, m.setStatus(msg.toolName + " not found — is it installed?")
-			}
-			return m, m.setStatus(msg.toolName + " exited: " + msg.err.Error())
-		}
-		return m, nil
-
 	case helpOutputMsg:
 		// Only the named tool's result retires the loading marker: a stale
 		// fetch for a previously highlighted tool must not clear the flag
@@ -1411,6 +1371,16 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		m.briefViewport.SetContent(m.renderCard())
 		return m, tea.Batch(statusCmd, fetchInstalledCmd(t))
 
+	case termStartedMsg:
+		return m, m.handleTermStarted(msg)
+
+	case termChunkMsg:
+		return m, m.handleTermChunk(msg)
+
+	case termExitMsg:
+		m.handleTermExit(msg)
+		return m, nil
+
 	case statusExpiredMsg:
 		// Retire a transient status only if it is still the current one: a stale
 		// timer from a superseded message must not clear the newer message. The
@@ -1429,30 +1399,30 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case tea.KeyMsg:
 		m.statusMsg = ""
 
-		// Every modal return funnels through flushPendingLaunch: the keystroke
-		// that brings the mode back to modeNormal is the single point where a
-		// deferred exec fallback (launchDoneMsg mode gate) can safely fire —
-		// see the pendingLaunchName field doc. While the mode stays open the
-		// wrapper is a no-op.
+		// A non-normal mode owns the keyboard: its handler runs and returns, so
+		// the per-focus map below and the global keys after it never see the
+		// key. That is what makes the old per-flag guard bugs impossible.
 		switch m.mode {
 		case modeEditNote:
-			return flushPendingLaunch(m.updateNoteEdit(msg))
+			return m.updateNoteEdit(msg)
 		case modeEditTags:
-			return flushPendingLaunch(m.updateTagsEdit(msg))
+			return m.updateTagsEdit(msg)
 		case modeTrack:
-			return flushPendingLaunch(m.updateTrackInput(msg))
+			return m.updateTrackInput(msg)
 		case modeConfirmUntrack:
-			return flushPendingLaunch(m.updateUntrackConfirm(msg))
+			return m.updateUntrackConfirm(msg)
 		case modeRename:
-			return flushPendingLaunch(m.updateRenameInput(msg))
+			return m.updateRenameInput(msg)
 		case modeRunInput:
-			return flushPendingLaunch(m.updateRunInput(msg))
+			return m.updateRunInput(msg)
 		case modeConfirmUpdate:
-			return flushPendingLaunch(m.updateConfirmUpdate(msg))
+			return m.updateConfirmUpdate(msg)
 		case modeAPIStatus, modeTokenInput:
-			return flushPendingLaunch(m.updateAPIStatus(msg))
+			return m.updateAPIStatus(msg)
 		case modeHotkeys:
-			return flushPendingLaunch(m.updateHotkeys(msg))
+			return m.updateHotkeys(msg)
+		case modeToolOverlay:
+			return m.updateToolOverlay(msg)
 		}
 
 		if m.mode == modeSearch {
@@ -1470,7 +1440,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				// selectMeta before the flush: it mutates m, and Go copies m
 				// into the call before evaluating a second argument.
 				cmd = m.selectMeta(m.indexOfMeta(prev))
-				return flushPendingLaunch(m, cmd)
+				return m, cmd
 			case "enter":
 				// Commit: accept the highlighted match. With no matches the key
 				// is a no-op and search stays open.
@@ -1488,7 +1458,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				// flush: it mutates m, and Go copies m into the call before
 				// evaluating a second argument.
 				cmd = m.selectMeta(m.indexOfMeta(mt.Name))
-				return flushPendingLaunch(m, cmd)
+				return m, cmd
 			case "up", "down":
 				// Move the highlight through the filtered list (wrap-around,
 				// j/k parity). Never forwarded to the textinput, so the query
@@ -2054,18 +2024,6 @@ func (m *Model) setStatus(s string) tea.Cmd {
 	})
 }
 
-// setStickyStatus shows an in-flight status with no expiry timer — it reports
-// work still in progress and is extinguished by the completion message, not by
-// the clock. The seq bump is the whole point of the helper: a transient status
-// set within the last statusMsgTTL still has a tick in flight, and its seq would
-// otherwise match this message too, wiping the only sign the adapter is busy for
-// up to launchTimeout. It returns nothing, so a caller cannot batch a timer onto
-// it by mistake.
-func (m *Model) setStickyStatus(s string) {
-	m.statusSeq++
-	m.statusMsg = s
-}
-
 // toggleGroupByTag flips the [1] list between the flat update-grouped view and
 // the tag-grouped one. The toggle reorders filteredMeta(), and metaSelected is
 // an index into that projection — so it would silently point at a different
@@ -2344,6 +2302,10 @@ func (m *Model) applyLayout() {
 	// the pre-resize content (wrong scroll, out-of-range click mapping).
 	m.setToolsContent()
 	m.briefViewport.SetContent(m.renderCard())
+	// The embedded terminal is sized off the screen rather than off the panel
+	// widths, so it follows a resize from here — the single relayout point —
+	// and is a no-op in every other mode.
+	m.resizeToolOverlay()
 }
 
 // initViewports creates the three viewports on the first relayout — the
diff --git a/internal/model/mouse_test.go b/internal/model/mouse_test.go
index 9ea4f02..ce4891b 100644
--- a/internal/model/mouse_test.go
+++ b/internal/model/mouse_test.go
@@ -198,7 +198,7 @@ func TestMouseNoOpUnderOverlay(t *testing.T) {
 	for i := range names {
 		names[i] = fmt.Sprintf("tool%02d", i)
 	}
-	for _, mode := range []inputMode{modeAPIStatus, modeTokenInput, modeHotkeys} {
+	for _, mode := range []inputMode{modeAPIStatus, modeTokenInput, modeHotkeys, modeToolOverlay} {
 		t.Run(fmt.Sprintf("mode_%d", mode), func(t *testing.T) {
 			m := newMouseTestModel(t, 80, 10, names...)
 			m.mode = mode
diff --git a/internal/model/overlay_term.go b/internal/model/overlay_term.go
new file mode 100644
index 0000000..ead922d
--- /dev/null
+++ b/internal/model/overlay_term.go
@@ -0,0 +1,685 @@
+package model
+
+import (
+	"errors"
+	"io"
+	"os/exec"
+	"strconv"
+	"strings"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	uv "github.com/charmbracelet/ultraviolet"
+	"github.com/charmbracelet/x/ansi"
+	"github.com/charmbracelet/x/vt"
+
+	"github.com/stanlyzoolo/keepkit/internal/term"
+)
+
+// termSession is the model's view of a running tool: everything the overlay
+// needs and nothing else, so a test can drive the handlers with a fake instead
+// of spawning a real pty. The narrow-interface idiom main.go uses for
+// restarter, and the package-level assertion below is what keeps the real
+// session bound to it.
+type termSession interface {
+	Events() <-chan term.Event
+	Write(p []byte) (int, error)
+	Resize(w, h int) error
+	Kill()
+	Close() error
+}
+
+var _ termSession = (*term.Session)(nil)
+
+// termStartedMsg carries the live session back to Update, which is where the
+// emulator is created — the emulator's screen state is touched by Update and
+// nothing else, so it cannot be built in the command goroutine.
+type termStartedMsg struct {
+	session termSession
+}
+
+// termChunkMsg is one drained batch of the tool's output.
+//
+// exit is set when the drain ran into the session's final event. It rides along
+// rather than being dropped because the drain has already taken it off the
+// channel and there is nowhere to put it back: the handler writes data to the
+// emulator first and re-emits exit as the *next* message, which is what keeps a
+// short-lived CLI's final screen on display. Losing it the other way round —
+// exit first, data discarded — would defeat the whole esc-after-exit design.
+type termChunkMsg struct {
+	session termSession
+	data    []byte
+	exit    *termExitMsg
+}
+
+// termExitMsg is the tool's verdict. elapsed and killed are stamped by the
+// session goroutine, never here: time.Now() inside Update would make completion
+// non-deterministic in tests, and only the session knows whether the exit
+// followed a kill.
+//
+// startFailed marks the case where there is no session at all — term.Start
+// itself failed, so the overlay opens straight into its outcome line. It is an
+// explicit field rather than an inference from a nil m.termSession because the
+// renderer reads it long after the distinction would have to be reconstructed.
+type termExitMsg struct {
+	err         error
+	elapsed     time.Duration
+	killed      bool
+	startFailed bool
+}
+
+// exitMsgFrom converts the session's final event into the model's message.
+func exitMsgFrom(e term.Exit) termExitMsg {
+	return termExitMsg{err: e.Err, elapsed: e.Elapsed, killed: e.Killed}
+}
+
+// termInput relays the emulator's encoded input to the tool.
+//
+// This goroutine exists because the pinned x/vt has no exported key encoder and
+// its SendKey encodes against emulator modes (DECCKM — whether arrows are
+// \x1bOA or \x1b[A) that no accessor exposes, so keys must go through the
+// emulator and come back out of its input pipe. Update calls SendKey/SendText;
+// this goroutine is the reader that unblocks the internal io.Pipe those write
+// into, and it touches no screen state — the Update-only rule holds.
+type termInput struct {
+	done chan struct{}
+}
+
+// startTermInput wires emu's input side to sess. One goroutine per session,
+// started exactly once, when both ends exist.
+func startTermInput(emu *vt.Emulator, sess termSession) *termInput {
+	ti := &termInput{done: make(chan struct{})}
+	go func() {
+		defer close(ti.done)
+		buf := make([]byte, 256)
+		for {
+			n, err := emu.Read(buf)
+			if n > 0 {
+				if _, werr := sess.Write(buf[:n]); werr != nil {
+					return
+				}
+			}
+			if err != nil {
+				return
+			}
+		}
+	}()
+	return ti
+}
+
+// stop ends the relay and waits for the goroutine, so it can never outlive the
+// overlay. Callers close the session first: that way a relay parked in
+// Session.Write fails fast instead of holding the teardown.
+//
+// It closes the emulator's *input pipe* rather than the emulator. Emulator.Close
+// writes an unsynchronised bool that Emulator.Read checks on every call
+// (charmbracelet/x#879) — reproduced under -race in internal/term — while
+// closing the pipe writer unblocks the parked Read through io.Pipe's own
+// synchronisation and touches nothing shared. The Close fallback is for a future
+// x/vt that stops handing out an io.Closer; see docs/research/pty-stack.md.
+func (ti *termInput) stop(emu *vt.Emulator) {
+	if ti == nil {
+		return
+	}
+	if emu != nil {
+		if closer, ok := emu.InputPipe().(io.Closer); ok {
+			_ = closer.Close()
+		} else {
+			_ = emu.Close()
+		}
+	}
+	<-ti.done
+}
+
+// startTermCmd runs shell+args on a fresh w×h pty off the Update thread.
+//
+// A start failure never reaches the caller as an error: it becomes an immediate
+// termExitMsg, so the overlay that just opened shows why instead of closing
+// again under the user.
+func startTermCmd(shell string, args []string, w, h int) tea.Cmd {
+	return safeCmd("startTermCmd", func() tea.Msg {
+		s, err := term.Start(shell, args, w, h, nil)
+		if err != nil {
+			return termExitMsg{err: err, startFailed: true}
+		}
+		return termStartedMsg{session: s}
+	})
+}
+
+// waitForTermChunkCmd blocks for the session's next event and folds everything
+// already queued behind it into one message — a full-screen redraw arrives as
+// several reads and repainting once per read would spend a Bubble Tea frame on
+// each. It is the re-subscribe half of the channel idiom waitForChunkCmd uses
+// for the update streamer.
+//
+// The drain stops at the final event and hands it back through termChunkMsg.exit
+// rather than swallowing it; see that field's doc for why the order matters.
+func waitForTermChunkCmd(s termSession) tea.Cmd {
+	return safeCmd("waitForTermChunkCmd", func() tea.Msg {
+		ev, ok := <-s.Events()
+		if !ok {
+			// A closed channel with no Exit behind it is not something the
+			// session can produce, but a fake can: end the overlay rather
+			// than re-subscribing to a channel that will never answer.
+			return termExitMsg{}
+		}
+
+		switch e := ev.(type) {
+		case term.Exit:
+			return exitMsgFrom(e)
+		case term.Data:
+			data := e.Bytes
+			for {
+				select {
+				case next, open := <-s.Events():
+					if !open {
+						return termChunkMsg{session: s, data: data, exit: &termExitMsg{}}
+					}
+					switch n := next.(type) {
+					case term.Data:
+						data = append(data, n.Bytes...)
+					case term.Exit:
+						exit := exitMsgFrom(n)
+						return termChunkMsg{session: s, data: data, exit: &exit}
+					}
+				default:
+					return termChunkMsg{session: s, data: data}
+				}
+			}
+		}
+		return nil
+	})
+}
+
+// handleTermStarted adopts the live session: the emulator is created here, on
+// the Update goroutine, and the input relay is started now that both ends
+// exist.
+//
+// A session arriving when the overlay is no longer waiting for one is killed
+// rather than adopted. As wired that cannot happen — the start-failure exit
+// and a started session are alternative results of the same command, and no
+// message handler writes m.mode without a gate that refuses modeToolOverlay —
+// but a fake can produce it and a future mode writer could, and a guard kept
+// for that future must actually be safe when it fires: the drain below is
+// what lets the reader goroutine end (and the killed child be reaped) when a
+// chatty tool has already filled the event buffer, where a bare Kill+Close
+// would park the reader on a channel send forever.
+func (m *Model) handleTermStarted(msg termStartedMsg) tea.Cmd {
+	if m.mode != modeToolOverlay || m.termSession != nil {
+		msg.session.Kill()
+		_ = msg.session.Close()
+		// Bounded: the closed master fails the reader's next read, the wait
+		// reaps the killed child, Exit lands and the channel closes.
+		return safeCmd("drainStaleTermSession", func() tea.Msg {
+			for range msg.session.Events() {
+			}
+			return nil
+		})
+	}
+
+	m.termSession = msg.session
+	m.termEmu = vt.NewEmulator(m.termW, m.termH)
+	m.termInput = startTermInput(m.termEmu, msg.session)
+	// The pty was created at the geometry the run-prompt enter captured. A
+	// WindowSizeMsg processed in the start window has already moved termW/termH
+	// with no session to follow it, and resizeToolOverlay's nothing-changed
+	// early return then sees the new size stored — so the pty would keep the
+	// stale winsize until the next real resize. Unconditional on purpose: in
+	// the common no-resize case this is a same-size TIOCSWINSZ, which the
+	// kernel drops without a SIGWINCH, so the child never notices.
+	_ = msg.session.Resize(m.termW, m.termH)
+	return waitForTermChunkCmd(msg.session)
+}
+
+// handleTermChunk folds one batch of output into the emulator.
+//
+// A chunk whose session is not the current one is stale — its overlay is
+// already closed — and is dropped without re-subscribing, so a dead session's
+// channel cannot keep a command chain alive.
+func (m *Model) handleTermChunk(msg termChunkMsg) tea.Cmd {
+	if msg.session == nil || msg.session != m.termSession {
+		return nil
+	}
+
+	if m.termEmu != nil && len(msg.data) > 0 {
+		_, _ = m.termEmu.Write(msg.data)
+	}
+
+	if msg.exit != nil {
+		// Deliver the exit as the next message, after this batch has been
+		// painted: the final screen is the point of staying open.
+		exit := *msg.exit
+		return func() tea.Msg { return exit }
+	}
+	return waitForTermChunkCmd(msg.session)
+}
+
+// handleTermExit records the verdict and stops the chain. It writes nothing
+// else: the overlay stays exactly as the tool left it until esc, and the
+// screen is the answer — no status message.
+func (m *Model) handleTermExit(msg termExitMsg) {
+	if m.mode != modeToolOverlay {
+		return
+	}
+	exit := msg
+	m.termExit = &exit
+}
+
+// closeToolOverlay tears the overlay down and returns to modeNormal.
+//
+// The order is load-bearing: the session goes first so the relay's pending
+// Session.Write fails fast, then the relay is stopped and waited for, and only
+// then are the emulator and the rest of the state dropped. Reversing the first
+// two can park the relay in a write nobody will drain.
+func (m *Model) closeToolOverlay() {
+	if m.termSession != nil {
+		m.termSession.Kill()
+		_ = m.termSession.Close()
+	}
+	m.termInput.stop(m.termEmu)
+
+	m.termSession = nil
+	m.termInput = nil
+	m.termEmu = nil
+	m.termExit = nil
+	m.termToolName = ""
+	m.termW, m.termH = 0, 0
+	m.mode = modeNormal
+}
+
+// termKillKey is the one chord the overlay keeps for itself. Everything else —
+// esc, ctrl+c, q — belongs to the tool, so the way out of a hung program cannot
+// be a key the program might want. ctrl+\ is the choice because it is already
+// SIGQUIT by convention and no editor binds it.
+const termKillKey = tea.KeyCtrlBackslash
+
+// updateToolOverlay owns every keystroke while the overlay is open — that is
+// what "the tool has the keyboard" means, and it is why the mode consumes keys
+// it has no use for rather than letting them fall through to the normal-mode
+// map underneath.
+//
+// While the tool runs, every key is translated and sent, ctrl+\ kills. Once it
+// has exited the overlay is a still image: esc closes it and nothing else does
+// anything — in particular the keys are no longer forwarded, because there is
+// nothing left to forward them to.
+func (m Model) updateToolOverlay(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
+	if m.termExit != nil {
+		if msg.Type == tea.KeyEsc {
+			m.closeToolOverlay()
+		}
+		return m, nil
+	}
+
+	if msg.Type == termKillKey {
+		// Kill, but stay in the mode: the verdict arrives as termExitMsg and
+		// that is what turns the overlay into its outcome line. Leaving here
+		// would drop the log the user just killed something to read.
+		if m.termSession != nil {
+			m.termSession.Kill()
+		}
+		return m, nil
+	}
+
+	// Between the keypress that opened the overlay and termStartedMsg there is
+	// no emulator and no session. Keys are dropped rather than queued: the
+	// window is milliseconds, and a nil deref here would re-panic through
+	// logx.Recover and take keepkit down with it.
+	if m.termEmu != nil {
+		sendToolKey(m.termEmu, msg)
+	}
+	return m, nil
+}
+
+// termNamedKeys maps the Bubble Tea key types that need the emulator's own
+// encoder — the ones whose bytes depend on emulator state (DECCKM turns the
+// arrows and Home/End into their \x1bO… forms, DECNKM the keypad). Everything
+// here goes through SendKey for that reason; see the file header on why the
+// model cannot encode them itself.
+var termNamedKeys = map[tea.KeyType]uv.KeyPressEvent{
+	tea.KeyUp:       {Code: uv.KeyUp},
+	tea.KeyDown:     {Code: uv.KeyDown},
+	tea.KeyRight:    {Code: uv.KeyRight},
+	tea.KeyLeft:     {Code: uv.KeyLeft},
+	tea.KeyHome:     {Code: uv.KeyHome},
+	tea.KeyEnd:      {Code: uv.KeyEnd},
+	tea.KeyPgUp:     {Code: uv.KeyPgUp},
+	tea.KeyPgDown:   {Code: uv.KeyPgDown},
+	tea.KeyInsert:   {Code: uv.KeyInsert},
+	tea.KeyDelete:   {Code: uv.KeyDelete},
+	tea.KeyShiftTab: {Code: uv.KeyTab, Mod: uv.ModShift},
+	tea.KeyF1:       {Code: uv.KeyF1},
+	tea.KeyF2:       {Code: uv.KeyF2},
+	tea.KeyF3:       {Code: uv.KeyF3},
+	tea.KeyF4:       {Code: uv.KeyF4},
+	tea.KeyF5:       {Code: uv.KeyF5},
+	tea.KeyF6:       {Code: uv.KeyF6},
+	tea.KeyF7:       {Code: uv.KeyF7},
+	tea.KeyF8:       {Code: uv.KeyF8},
+	tea.KeyF9:       {Code: uv.KeyF9},
+	tea.KeyF10:      {Code: uv.KeyF10},
+	tea.KeyF11:      {Code: uv.KeyF11},
+	tea.KeyF12:      {Code: uv.KeyF12},
+}
+
+// termModifiedKeys covers the modified cursor keys, which the pinned x/vt does
+// not encode at all — its SendKey falls through to a default that emits nothing
+// for a modified special key, so routing these through the emulator would
+// silently swallow ctrl+left in every editor.
+//
+// They are safe to write out here because, unlike the bare arrows, the modified
+// forms do not depend on DECCKM: xterm's CSI 1;<mod><final> shape is what every
+// terminal sends whatever the cursor-keys mode. The modifier digit is
+// 1+shift(1)+alt(2)+ctrl(4), and the finals are A/B/C/D for the arrows and H/F
+// for home/end.
+var termModifiedKeys = map[tea.KeyType]string{
+	tea.KeyShiftUp:        "\x1b[1;2A",
+	tea.KeyShiftDown:      "\x1b[1;2B",
+	tea.KeyShiftRight:     "\x1b[1;2C",
+	tea.KeyShiftLeft:      "\x1b[1;2D",
+	tea.KeyShiftHome:      "\x1b[1;2H",
+	tea.KeyShiftEnd:       "\x1b[1;2F",
+	tea.KeyCtrlUp:         "\x1b[1;5A",
+	tea.KeyCtrlDown:       "\x1b[1;5B",
+	tea.KeyCtrlRight:      "\x1b[1;5C",
+	tea.KeyCtrlLeft:       "\x1b[1;5D",
+	tea.KeyCtrlHome:       "\x1b[1;5H",
+	tea.KeyCtrlEnd:        "\x1b[1;5F",
+	tea.KeyCtrlShiftUp:    "\x1b[1;6A",
+	tea.KeyCtrlShiftDown:  "\x1b[1;6B",
+	tea.KeyCtrlShiftRight: "\x1b[1;6C",
+	tea.KeyCtrlShiftLeft:  "\x1b[1;6D",
+	tea.KeyCtrlShiftHome:  "\x1b[1;6H",
+	tea.KeyCtrlShiftEnd:   "\x1b[1;6F",
+	tea.KeyCtrlPgUp:       "\x1b[5;5~",
+	tea.KeyCtrlPgDown:     "\x1b[6;5~",
+}
+
+// sendToolKey translates one Bubble Tea key into what the tool should read.
+//
+// Bubble Tea's control-key types are the control bytes themselves — KeyEnter is
+// 0x0d, KeyEsc 0x1b, KeyCtrlA 0x01, KeyBackspace 0x7f — and none of those is
+// mode-dependent, so writing the byte is exactly what the emulator's encoder
+// would have produced for them. Alt arrives as a flag rather than a key, and an
+// alt-modified key is its unmodified form behind an ESC.
+func sendToolKey(emu *vt.Emulator, msg tea.KeyMsg) {
+	alt := ""
+	if msg.Alt {
+		alt = "\x1b"
+	}
+
+	switch msg.Type {
+	case tea.KeyRunes:
+		if msg.Paste {
+			// A paste is one block of text, not typed keys: Emulator.Paste
+			// brackets it with the ?2004 markers exactly when the tool asked
+			// for them, which is what keeps vim from auto-indenting every
+			// pasted line. No alt prefix — a paste has no modifier.
+			emu.Paste(string(msg.Runes))
+			return
+		}
+		emu.SendText(alt + string(msg.Runes))
+	case tea.KeySpace:
+		emu.SendText(alt + " ")
+	default:
+		if seq, ok := termModifiedKeys[msg.Type]; ok {
+			emu.SendText(alt + seq)
+			return
+		}
+		if key, ok := termNamedKeys[msg.Type]; ok {
+			if msg.Alt {
+				key.Mod |= uv.ModAlt
+			}
+			emu.SendKey(key)
+			return
+		}
+		// What is left is the control range, where the key type *is* the byte.
+		// A type outside it is one Bubble Tea knows and this build does not
+		// (a newer F-key, say); dropping it beats sending a stray rune.
+		if msg.Type >= 0 && msg.Type <= 0x7f {
+			emu.SendText(alt + string(rune(msg.Type)))
+		}
+	}
+}
+
+// Overlay geometry. The block covers termOverlayPercent of the screen in both
+// directions; the minimums are what a tool actually needs to be usable rather
+// than merely drawn — below them the keypress refuses instead of opening a
+// window nothing fits in.
+const (
+	termOverlayPercent = 70
+	termMinBodyW       = 40
+	termMinBodyH       = 10
+
+	// termChromeRows is what the frame spends on itself inside the border: the
+	// title row and the exit row. The exit row is reserved from the very start
+	// and left blank while the tool runs, so the block's height never changes
+	// and PlaceOverlay cannot re-centre it the moment the tool exits.
+	termChromeRows = 2
+	// termChromeCols is the border (2) plus OverlayBorder's Padding(0, 1) (2).
+	termChromeCols = 4
+)
+
+// termGeometry is the emulator's body size for the current terminal, plus
+// whether the screen is big enough for one at all.
+//
+// The size is always clamped to the floor and ok is a separate answer, because
+// the two callers want different things: the keypress refuses on !ok, while a
+// terminal shrunk *mid-session* keeps rendering at the minimum — resizing the
+// user's editor into nothing is bad, killing it outright is worse.
+//
+// !m.ready is checked first and explicitly, the toggleZoom idiom: before the
+// first WindowSizeMsg every dimension is zero and the percentages below would
+// agree on a floor-sized overlay by coincidence rather than by measurement.
+func (m Model) termGeometry() (w, h int, ok bool) {
+	if !m.ready {
+		return termMinBodyW, termMinBodyH, false
+	}
+	return termGeometryFor(m.width, m.height)
+}
+
+// termGeometryFor is the pure core (the planFor/baseFor idiom), so the clamps
+// are testable without a laid-out model.
+func termGeometryFor(width, height int) (w, h int, ok bool) {
+	// The overlay composites over the layout, not over the terminal: View wraps
+	// the composite in Margin(1, 0), so two rows are already spoken for and an
+	// overlay sized against the raw height would be clipped at the bottom by
+	// PlaceOverlay — silently, which is how a missing exit line would look.
+	bgH := height - 2
+
+	outerW := min(width*termOverlayPercent/100, width)
+	outerH := min(bgH*termOverlayPercent/100, bgH)
+
+	w, h = outerW-termChromeCols, outerH-2-termChromeRows
+	ok = w >= termMinBodyW && h >= termMinBodyH
+	return max(w, termMinBodyW), max(h, termMinBodyH), ok
+}
+
+// resizeToolOverlay follows a terminal resize through to the tool: the emulator
+// is re-laid-out first and the pty is told second, so the child's redraw lands
+// on a screen that is already the right shape.
+func (m *Model) resizeToolOverlay() {
+	if m.mode != modeToolOverlay {
+		return
+	}
+	w, h, _ := m.termGeometry()
+	if w == m.termW && h == m.termH {
+		return
+	}
+	m.termW, m.termH = w, h
+	if m.termEmu != nil {
+		m.termEmu.Resize(w, h)
+	}
+	if m.termSession != nil {
+		_ = m.termSession.Resize(w, h)
+	}
+}
+
+// renderToolOverlay draws the embedded terminal: a title row naming the tool,
+// the tool's own screen, and a bottom row that is blank while it runs and
+// carries the verdict once it has exited.
+func (m Model) renderToolOverlay() string {
+	s := m.sty()
+	w, h, _ := m.termGeometry()
+
+	// Title. The kill chord is advertised here rather than only in the status
+	// bar because this frame is what the user is looking at, and it is the one
+	// key that still belongs to keepkit while the tool has the keyboard. It
+	// goes once the tool has exited — by then the only key that does anything
+	// is esc, and the exit row says so.
+	title := s.EmphasisBold.Render(m.termToolName)
+	titleRow := title
+	if m.termExit == nil {
+		hint := m.hint(`ctrl+\`, "kill")
+		if pad := w - lipgloss.Width(title) - lipgloss.Width(hint); pad > 0 {
+			titleRow = title + strings.Repeat(" ", pad) + hint
+		}
+	}
+
+	rows := make([]string, 0, h+termChromeRows)
+	rows = append(rows, titleRow)
+	rows = append(rows, m.termBodyRows(w, h)...)
+	rows = append(rows, m.termExitRow(w))
+
+	// Every row is padded to exactly w before the frame goes round it. lipgloss
+	// sizes a border to its widest line, so without this the block would be as
+	// wide as whatever the tool happened to print — and, worse, it would *change
+	// width at exit*, when the title loses its kill hint and the exit row
+	// replaces a blank. PlaceOverlay centres what it is given, so a one-cell
+	// change is the whole block jumping sideways at the moment the user is
+	// reading the outcome. The reserved row keeps the height constant; this
+	// keeps the width constant.
+	for i, row := range rows {
+		rows[i] = termRow(row, w)
+	}
+	return s.OverlayBorder.Render(strings.Join(rows, "\n"))
+}
+
+// termRow fits one row to exactly w visible cells.
+//
+// Both directions go through x/ansi: padding is plain spaces appended after the
+// styling (never inside it), and a row too wide is cut by visible column rather
+// than by byte or rune index, which would land inside an escape sequence that
+// the terminal then executes.
+func termRow(row string, w int) string {
+	switch width := lipgloss.Width(row); {
+	case width < w:
+		return row + strings.Repeat(" ", w-width)
+	case width > w:
+		return ansi.Truncate(row, w, "")
+	default:
+		return row
+	}
+}
+
+// termBodyRows is the tool's screen, exactly h rows tall.
+//
+// Before termStartedMsg there is no emulator: the overlay is already on screen
+// (the keypress opened it) and has to say something, which is the same
+// "starting …" idiom the update log uses for its own pre-output window.
+func (m Model) termBodyRows(w, h int) []string {
+	rows := make([]string, h)
+	if m.termEmu == nil {
+		rows[0] = m.sty().Dim.Render("starting " + m.termToolName + "…")
+		return rows
+	}
+
+	lines := strings.Split(m.termEmu.Render(), "\n")
+	for i := range rows {
+		if i < len(lines) {
+			// Padded here rather than by the final pass, because the cursor
+			// splice below addresses a *column*: on a short line, a cursor
+			// past its end would otherwise be spliced in right after the last
+			// glyph instead of where the tool actually put it.
+			rows[i] = termRow(lines[i], w)
+		} else {
+			rows[i] = strings.Repeat(" ", w)
+		}
+	}
+	return m.withTermCursor(rows, w, h)
+}
+
+// withTermCursor reverse-videos the cell the tool has its cursor on, so a shell
+// prompt or an editor's caret is visible instead of the screen looking frozen.
+// Hidden once the tool has exited: a cursor on a dead screen invites typing.
+//
+// The splice goes through x/ansi rather than a byte offset: an emulator line
+// carries SGR runs, and cutting one at a rune index lands inside an escape
+// sequence, which the terminal then executes. ansi.Truncate/TruncateLeft cut by
+// *visible* column and keep the styling on both sides intact.
+func (m Model) withTermCursor(rows []string, w, h int) []string {
+	if m.termExit != nil || m.termEmu == nil {
+		return rows
+	}
+
+	pos := m.termEmu.CursorPosition()
+	if pos.X < 0 || pos.X >= w || pos.Y < 0 || pos.Y >= h || pos.Y >= len(rows) {
+		return rows
+	}
+
+	content := " "
+	if cell := m.termEmu.CellAt(pos.X, pos.Y); cell != nil && cell.Content != "" {
+		content = cell.Content
+	}
+
+	line := rows[pos.Y]
+	rows[pos.Y] = ansi.Truncate(line, pos.X, "") +
+		m.sty().TermCursor.Render(content) +
+		ansi.TruncateLeft(line, pos.X+1, "")
+	return rows
+}
+
+// termExitRow is the reserved bottom row: blank while the tool runs, the
+// verdict plus the way out once it has finished.
+//
+// No status message accompanies it — the screen the tool left behind is the
+// answer, and this row is the caption on it.
+func (m Model) termExitRow(w int) string {
+	if m.termExit == nil {
+		return ""
+	}
+	s := m.sty()
+	sep := s.Dim.Render(footerSep)
+
+	verdict := s.Ok.Render("✓ exited")
+	switch {
+	case m.termExit.startFailed:
+		verdict = s.Danger.Render("✕ failed to start")
+	case m.termExit.killed:
+		verdict = s.Danger.Render("✕ killed")
+	case m.termExit.err != nil:
+		verdict = s.Danger.Render("✕ exit " + termExitCode(m.termExit.err))
+	}
+
+	cells := []string{verdict}
+	// A start failure has no elapsed worth printing and a reason that is the
+	// whole point, so it takes the middle cell the others spend on duration.
+	if m.termExit.startFailed {
+		if reason := m.termExit.err; reason != nil {
+			cells = append(cells, s.Dim.Render(reason.Error()))
+		}
+	} else if el := formatElapsed(m.termExit.elapsed); el != "" {
+		cells = append(cells, s.Dim.Render(el))
+	}
+	cells = append(cells, m.hint("esc", "close"))
+
+	return fitCells(cells, sep, w, 0)
+}
+
+// termExitCode names the code an exited tool reported, falling back to "?" for
+// an error that is not an exit status at all (a wait that failed on its own).
+func termExitCode(err error) string {
+	var ee *exec.ExitError
+	if errors.As(err, &ee) {
+		return strconv.Itoa(ee.ExitCode())
+	}
+	return "?"
+}
+
+// termRunning reports that the overlay has a tool that has not exited yet —
+// the state where every key belongs to the tool and only ctrl+\ is reserved.
+// A session still starting counts as running: its keys are dropped, not
+// treated as an exited overlay's.
+func (m Model) termRunning() bool {
+	return m.mode == modeToolOverlay && m.termExit == nil
+}
diff --git a/internal/model/overlay_term_test.go b/internal/model/overlay_term_test.go
new file mode 100644
index 0000000..19ac3af
--- /dev/null
+++ b/internal/model/overlay_term_test.go
@@ -0,0 +1,1111 @@
+package model
+
+import (
+	"errors"
+	"fmt"
+	"os/exec"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+
+	"github.com/stanlyzoolo/keepkit/internal/loader"
+	"github.com/stanlyzoolo/keepkit/internal/term"
+	"github.com/stanlyzoolo/keepkit/internal/ui"
+)
+
+// fakeTermSession drives the overlay handlers without a pty: the test feeds
+// events in and reads back what the model wrote, killed or resized. Every
+// method is safe to call from the input relay goroutine, so the fake is usable
+// under -race.
+type fakeTermSession struct {
+	events chan term.Event
+
+	mu      sync.Mutex
+	written []byte
+	killed  int
+	closed  int
+	resized [][2]int
+	writeIn error
+}
+
+func newFakeSession(buffer int) *fakeTermSession {
+	return &fakeTermSession{events: make(chan term.Event, buffer)}
+}
+
+func (f *fakeTermSession) Events() <-chan term.Event { return f.events }
+
+func (f *fakeTermSession) Write(p []byte) (int, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.writeIn != nil {
+		return 0, f.writeIn
+	}
+	f.written = append(f.written, p...)
+	return len(p), nil
+}
+
+func (f *fakeTermSession) Resize(w, h int) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.resized = append(f.resized, [2]int{w, h})
+	return nil
+}
+
+func (f *fakeTermSession) Kill() {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.killed++
+}
+
+func (f *fakeTermSession) Close() error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.closed++
+	return nil
+}
+
+// input returns everything the model has relayed to the tool so far. It polls,
+// because the relay is a goroutine and a bare read would race the handoff.
+func (f *fakeTermSession) input(t *testing.T, want string) string {
+	t.Helper()
+
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		f.mu.Lock()
+		got := string(f.written)
+		f.mu.Unlock()
+		if want == "" || strings.Contains(got, want) || time.Now().After(deadline) {
+			return got
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+func (f *fakeTermSession) resizes() [][2]int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([][2]int(nil), f.resized...)
+}
+
+func (f *fakeTermSession) counts() (killed, closed int) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.killed, f.closed
+}
+
+// overlayModel is a model sitting in modeToolOverlay with the session already
+// adopted, i.e. the state everything after termStartedMsg runs in.
+func overlayModel(t *testing.T, f *fakeTermSession) Model {
+	t.Helper()
+
+	m := newTestModel(focusTools)
+	m.mode = modeToolOverlay
+	m.termToolName = "git"
+	m.termW, m.termH = 40, 10
+
+	nm := mustModel(m.Update(termStartedMsg{session: f}))
+	if nm.termSession == nil {
+		t.Fatal("termStartedMsg did not adopt the session")
+	}
+	if nm.termEmu == nil {
+		t.Fatal("termStartedMsg did not create the emulator")
+	}
+	t.Cleanup(func() { nm.closeToolOverlay() })
+	return nm
+}
+
+// The started message is what creates the emulator - on the Update goroutine,
+// which is the whole reason the emulator lives on the model and not inside
+// internal/term.
+func TestTermStartedCreatesEmulatorAtGeometrySize(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	if got := m.termEmu.Width(); got != 40 {
+		t.Errorf("emulator width = %d, want 40 (termW)", got)
+	}
+	if got := m.termEmu.Height(); got != 10 {
+		t.Errorf("emulator height = %d, want 10 (termH)", got)
+	}
+	if m.termExit != nil {
+		t.Error("termExit is set on a session that just started")
+	}
+	if !m.termRunning() {
+		t.Error("termRunning() is false right after the session started")
+	}
+}
+
+// A session that arrives after the overlay is gone must not be adopted and must
+// not be left running: nothing could reach it afterwards. The branch must also
+// drain the session's events — a chatty child that filled the buffer before
+// the kill would otherwise park the reader goroutine on a channel send
+// forever, with the killed child never reaped behind it.
+func TestTermStartedAfterCloseKillsTheSession(t *testing.T) {
+	f := newFakeSession(4)
+	// What a chatty child leaves behind: queued output plus the exit, channel
+	// closed — the shape the reader produces once Kill+Close land.
+	f.events <- term.Data{Bytes: []byte("queued output")}
+	f.events <- term.Exit{}
+	close(f.events)
+
+	m := newTestModel(focusTools) // still modeNormal - the overlay never opened
+
+	tm, cmd := m.Update(termStartedMsg{session: f})
+	nm := tm.(Model)
+
+	if nm.termSession != nil {
+		t.Error("a session was adopted outside modeToolOverlay")
+	}
+	killed, closed := f.counts()
+	if killed == 0 || closed == 0 {
+		t.Errorf("stale session left running: killed=%d closed=%d, want both > 0", killed, closed)
+	}
+	if cmd == nil {
+		t.Fatal("the stale branch returned no drain cmd")
+	}
+	if msg := cmd(); msg != nil {
+		t.Errorf("the drain produced %v, want nil — it must never re-enter the overlay's message flow", msg)
+	}
+	if _, ok := <-f.events; ok {
+		t.Error("the stale session's events were not drained")
+	}
+}
+
+// A chunk reaches a real vt emulator and shows up in Render() - pure Go, no
+// pty involved, which is what makes the whole overlay assertable in model
+// tests.
+func TestTermChunkReachesTheEmulator(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	nm := mustModel(m.Update(termChunkMsg{session: f, data: []byte("hello overlay")}))
+
+	if got := nm.termEmu.Render(); !strings.Contains(got, "hello overlay") {
+		t.Errorf("emulator rendered %q, want it to contain %q", got, "hello overlay")
+	}
+}
+
+// A chunk belonging to a session the model no longer holds is dropped, and -
+// the part that matters - it does not re-subscribe: a dead session's channel
+// must not keep a command chain alive for the rest of the process.
+func TestTermChunkFromStaleSessionIsDropped(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	stale := newFakeSession(4)
+	nm, cmd := m.Update(termChunkMsg{session: stale, data: []byte("ghost")})
+
+	if cmd != nil {
+		t.Error("a stale chunk re-subscribed to its session")
+	}
+	if got := nm.(Model).termEmu.Render(); strings.Contains(got, "ghost") {
+		t.Error("a stale chunk was written to the live emulator")
+	}
+}
+
+// The drain folds queued output into one message and, when it runs into the
+// exit, delivers the data first and the exit as the next message. Losing that
+// order loses a short-lived CLI's final screen, which is the whole point of
+// staying open until esc.
+func TestWaitForTermChunkDeliversDataBeforeExit(t *testing.T) {
+	f := newFakeSession(8)
+	f.events <- term.Data{Bytes: []byte("first ")}
+	f.events <- term.Data{Bytes: []byte("second")}
+	f.events <- term.Exit{Err: nil, Elapsed: 3 * time.Second}
+	close(f.events)
+
+	msg := waitForTermChunkCmd(f)()
+
+	chunk, ok := msg.(termChunkMsg)
+	if !ok {
+		t.Fatalf("first message is %T, want termChunkMsg", msg)
+	}
+	if got := string(chunk.data); got != "first second" {
+		t.Errorf("drained data = %q, want %q - the drain did not fold both chunks", got, "first second")
+	}
+	if chunk.exit == nil {
+		t.Fatal("the drain reached the exit and dropped it")
+	}
+	if chunk.exit.elapsed != 3*time.Second {
+		t.Errorf("elapsed = %v, want 3s (stamped by the session, not by Update)", chunk.exit.elapsed)
+	}
+
+	// and the model plays them out in that order: emulator first, exit next
+	m := overlayModel(t, f)
+	nm, cmd := m.Update(chunk)
+	if got := nm.(Model).termEmu.Render(); !strings.Contains(got, "first second") {
+		t.Errorf("emulator rendered %q, want the drained data", got)
+	}
+	if nm.(Model).termExit != nil {
+		t.Error("the exit was recorded in the same update as the data it must follow")
+	}
+	if cmd == nil {
+		t.Fatal("no follow-up command carried the exit")
+	}
+	if _, ok := cmd().(termExitMsg); !ok {
+		t.Errorf("follow-up message is %T, want termExitMsg", cmd())
+	}
+}
+
+// A drain that starts on the exit reports it directly.
+func TestWaitForTermChunkExitOnly(t *testing.T) {
+	f := newFakeSession(2)
+	f.events <- term.Exit{Err: errors.New("boom"), Elapsed: time.Second, Killed: true}
+
+	msg := waitForTermChunkCmd(f)()
+
+	exit, ok := msg.(termExitMsg)
+	if !ok {
+		t.Fatalf("message is %T, want termExitMsg", msg)
+	}
+	if exit.err == nil || !exit.killed {
+		t.Errorf("exit = %+v, want the error and killed flag carried through", exit)
+	}
+}
+
+// The exit message stores the verdict and stops the chain. It writes no status
+// message: the screen is the answer.
+func TestTermExitStoresVerdictAndStopsTheChain(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	nm, cmd := m.Update(termExitMsg{err: errors.New("exit status 1"), elapsed: 2 * time.Second})
+	got := nm.(Model)
+
+	if got.termExit == nil {
+		t.Fatal("termExit is nil after termExitMsg")
+	}
+	if got.termExit.elapsed != 2*time.Second {
+		t.Errorf("elapsed = %v, want 2s", got.termExit.elapsed)
+	}
+	if cmd != nil {
+		t.Error("termExitMsg returned a command - the chain must stop at the exit")
+	}
+	if got.termRunning() {
+		t.Error("termRunning() is still true after the exit")
+	}
+	if got.statusMsg != "" {
+		t.Errorf("statusMsg = %q, want empty - the overlay itself reports the outcome", got.statusMsg)
+	}
+	if got.mode != modeToolOverlay {
+		t.Errorf("mode = %v, want modeToolOverlay - the overlay stays until esc", got.mode)
+	}
+}
+
+// An exit arriving after the overlay closed changes nothing.
+func TestTermExitOutsideOverlayIsIgnored(t *testing.T) {
+	m := newTestModel(focusTools)
+
+	nm := mustModel(m.Update(termExitMsg{err: errors.New("late")}))
+
+	if nm.termExit != nil {
+		t.Error("a late exit was recorded outside the overlay")
+	}
+}
+
+// A start failure never reaches the user as a closed overlay: it arrives as an
+// exit that the outcome line can explain.
+func TestStartTermCmdFailureBecomesExit(t *testing.T) {
+	msg := startTermCmd("keepkit-no-such-shell-xyz", nil, 40, 10)()
+
+	exit, ok := msg.(termExitMsg)
+	if !ok {
+		t.Fatalf("message is %T, want termExitMsg", msg)
+	}
+	if exit.err == nil {
+		t.Error("a failed start carried no error")
+	}
+	if !exit.startFailed {
+		t.Error("startFailed is false on a start that failed")
+	}
+}
+
+// The input relay carries what Update sends to the tool, and the emulator is
+// what encodes it - which is why the relay exists at all (x/vt has no exported
+// key encoder). This is the -race lifecycle test: the relay must relay while
+// the screen is being written from Update, and must be gone after teardown.
+func TestTermInputRelayAndTeardown(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	m.termEmu.SendText("ls -la\r")
+	// drive the screen from this goroutine at the same time: the relay must
+	// not touch screen state
+	if _, err := m.termEmu.Write([]byte("banner")); err != nil {
+		t.Fatalf("emulator write: %v", err)
+	}
+
+	if got := f.input(t, "ls -la"); !strings.Contains(got, "ls -la\r") {
+		t.Errorf("tool received %q, want it to contain %q", got, "ls -la\r")
+	}
+
+	done := m.termInput.done
+	m.closeToolOverlay()
+
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("the input relay outlived the overlay")
+	}
+	if m.termSession != nil || m.termEmu != nil || m.termInput != nil || m.termExit != nil {
+		t.Error("closeToolOverlay left overlay state behind")
+	}
+	if m.mode != modeNormal {
+		t.Errorf("mode = %v after teardown, want modeNormal", m.mode)
+	}
+	killed, closed := f.counts()
+	if killed == 0 || closed == 0 {
+		t.Errorf("teardown left the session alive: killed=%d closed=%d", killed, closed)
+	}
+}
+
+// Teardown is safe on an overlay that never got a session - the window between
+// the keypress and termStartedMsg.
+func TestCloseToolOverlayBeforeStart(t *testing.T) {
+	m := newTestModel(focusTools)
+	m.mode = modeToolOverlay
+	m.termToolName = "git"
+
+	m.closeToolOverlay() // must not panic on the nil session/emulator/relay
+
+	if m.mode != modeNormal {
+		t.Errorf("mode = %v, want modeNormal", m.mode)
+	}
+}
+
+// The third overlay rides the shared modal predicate, which is what gates the
+// mouse and View().
+func TestToolOverlayIsAnOverlay(t *testing.T) {
+	m := newTestModel(focusTools)
+	m.mode = modeToolOverlay
+
+	if !m.overlayVisible() {
+		t.Error("overlayVisible() = false in modeToolOverlay")
+	}
+	if m.apiOverlayVisible() {
+		t.Error("apiOverlayVisible() = true in modeToolOverlay - it is a different overlay")
+	}
+}
+
+// View picks the tool overlay rather than falling through to the API-status
+// panel, which is what the old two-way if would have done.
+func TestViewPicksTheToolOverlay(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+	m.ready = true
+	m.applyLayout()
+
+	nm := mustModel(m.Update(termChunkMsg{session: f, data: []byte("in-overlay-marker")}))
+
+	view := nm.View()
+	if !strings.Contains(view, "in-overlay-marker") {
+		t.Error("View() does not show the tool overlay's content")
+	}
+	if strings.Contains(view, "github token") {
+		t.Error("View() fell through to the API-status overlay")
+	}
+}
+
+// Every key reaches the tool while it runs — including the ones keepkit would
+// otherwise act on. esc must not close the overlay (vim needs it) and ctrl+c
+// must not quit keepkit (it is the tool's interrupt), which is the whole claim
+// "the tool has the keyboard" makes.
+func TestToolOverlayForwardsEveryKeyWhileRunning(t *testing.T) {
+	tests := []struct {
+		name string
+		key  tea.KeyMsg
+		want string
+	}{
+		{"letters", keyRunes("ls"), "ls"},
+		{"space", tea.KeyMsg{Type: tea.KeySpace}, " "},
+		{"enter", tea.KeyMsg{Type: tea.KeyEnter}, "\r"},
+		{"tab", tea.KeyMsg{Type: tea.KeyTab}, "\t"},
+		{"backspace", tea.KeyMsg{Type: tea.KeyBackspace}, "\x7f"},
+		{"esc goes to the tool", tea.KeyMsg{Type: tea.KeyEsc}, "\x1b"},
+		{"ctrl+c goes to the tool", tea.KeyMsg{Type: tea.KeyCtrlC}, "\x03"},
+		{"ctrl+d", tea.KeyMsg{Type: tea.KeyCtrlD}, "\x04"},
+		{"up arrow", tea.KeyMsg{Type: tea.KeyUp}, "\x1b[A"},
+		{"down arrow", tea.KeyMsg{Type: tea.KeyDown}, "\x1b[B"},
+		{"home", tea.KeyMsg{Type: tea.KeyHome}, "\x1b[H"},
+		{"page up", tea.KeyMsg{Type: tea.KeyPgUp}, "\x1b[5~"},
+		{"delete", tea.KeyMsg{Type: tea.KeyDelete}, "\x1b[3~"},
+		{"shift+tab", tea.KeyMsg{Type: tea.KeyShiftTab}, "\x1b[Z"},
+		{"f1", tea.KeyMsg{Type: tea.KeyF1}, "\x1bOP"},
+		{"f5", tea.KeyMsg{Type: tea.KeyF5}, "\x1b[15~"},
+		{"ctrl+left", tea.KeyMsg{Type: tea.KeyCtrlLeft}, "\x1b[1;5D"},
+		{"shift+right", tea.KeyMsg{Type: tea.KeyShiftRight}, "\x1b[1;2C"},
+		{"alt+rune", tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("b"), Alt: true}, "\x1bb"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f := newFakeSession(4)
+			m := overlayModel(t, f)
+
+			nm := mustModel(m.Update(tt.key))
+
+			if got := f.input(t, tt.want); !strings.Contains(got, tt.want) {
+				t.Errorf("tool received %q, want it to contain %q", got, tt.want)
+			}
+			if nm.mode != modeToolOverlay {
+				t.Errorf("mode = %v, want the overlay to keep the keyboard", nm.mode)
+			}
+		})
+	}
+}
+
+// A paste is one block of text, not typed keys: it goes through
+// Emulator.Paste, which brackets it with the ?2004 markers exactly when the
+// tool asked for them — vim without the markers auto-indents every pasted
+// line.
+func TestToolOverlayPasteBracketsWhenTheToolAskedForIt(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	// The tool enables bracketed paste; the request arrives like any other
+	// output, through a chunk.
+	nm := mustModel(m.Update(termChunkMsg{session: f, data: []byte("\x1b[?2004h")}))
+
+	mustModel(nm.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("a\n\tb"), Paste: true}))
+
+	want := "\x1b[200~a\n\tb\x1b[201~"
+	if got := f.input(t, want); !strings.Contains(got, want) {
+		t.Errorf("tool received %q, want it to contain %q", got, want)
+	}
+}
+
+// A tool that never asked for bracketed paste gets the pasted text bare — the
+// markers would be input it does not understand.
+func TestToolOverlayPasteIsBareWithoutBracketedPaste(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	mustModel(m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("plain paste"), Paste: true}))
+
+	got := f.input(t, "plain paste")
+	if !strings.Contains(got, "plain paste") {
+		t.Errorf("tool received %q, want it to contain %q", got, "plain paste")
+	}
+	if strings.Contains(got, "\x1b[200~") || strings.Contains(got, "\x1b[201~") {
+		t.Errorf("tool received %q with paste markers it never asked for", got)
+	}
+}
+
+// esc while the tool runs is the tool's, not the overlay's: closing here would
+// make vim unusable, which is the case the whole design is built around.
+func TestToolOverlayEscDoesNotCloseWhileRunning(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	nm := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyEsc}))
+
+	if nm.mode != modeToolOverlay {
+		t.Errorf("mode = %v after esc, want the overlay still open", nm.mode)
+	}
+	if nm.termSession == nil {
+		t.Error("esc tore down a running session")
+	}
+}
+
+// ctrl+c must not reach keepkit's global quit. That case sits after the mode
+// dispatch, so this is structural - asserted because the failure is keepkit
+// exiting out from under a running tool.
+func TestToolOverlayCtrlCDoesNotQuit(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	nm, cmd := m.Update(tea.KeyMsg{Type: tea.KeyCtrlC})
+
+	if cmd != nil {
+		t.Error("ctrl+c in the overlay returned a command (tea.Quit reached)")
+	}
+	if nm.(Model).mode != modeToolOverlay {
+		t.Error("ctrl+c left the overlay")
+	}
+}
+
+// ctrl+\ is the reserved chord: it kills but stays in the mode, because the
+// outcome line the user killed something to read arrives with termExitMsg.
+func TestToolOverlayKillChord(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+
+	nm := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyCtrlBackslash}))
+
+	killed, _ := f.counts()
+	if killed != 1 {
+		t.Errorf("Kill called %d times, want 1", killed)
+	}
+	if nm.mode != modeToolOverlay {
+		t.Errorf("mode = %v after ctrl+\\, want to stay until the exit arrives", nm.mode)
+	}
+	if nm.termExit != nil {
+		t.Error("ctrl+\\ synthesised an exit instead of waiting for the session's")
+	}
+	if got := f.input(t, ""); strings.Contains(got, "\x1c") {
+		t.Error("the kill chord was also forwarded to the tool")
+	}
+}
+
+// After the exit the overlay is a still image: esc closes, everything else does
+// nothing, and nothing is forwarded because there is nothing to forward to.
+func TestToolOverlayAfterExit(t *testing.T) {
+	f := newFakeSession(4)
+	base := overlayModel(t, f)
+	base = mustModel(base.Update(termExitMsg{elapsed: time.Second}))
+
+	t.Run("esc closes", func(t *testing.T) {
+		m := base
+		nm := mustModel(m.Update(tea.KeyMsg{Type: tea.KeyEsc}))
+		if nm.mode != modeNormal {
+			t.Errorf("mode = %v after esc, want modeNormal", nm.mode)
+		}
+		if nm.termSession != nil || nm.termEmu != nil || nm.termExit != nil {
+			t.Error("esc left overlay state behind")
+		}
+	})
+
+	t.Run("other keys are no-ops", func(t *testing.T) {
+		for _, key := range []tea.KeyMsg{
+			keyRunes("q"), tea.KeyMsg{Type: tea.KeyEnter}, tea.KeyMsg{Type: tea.KeyCtrlC},
+			tea.KeyMsg{Type: tea.KeyCtrlBackslash},
+		} {
+			m := base
+			nm, cmd := m.Update(key)
+			if nm.(Model).mode != modeToolOverlay {
+				t.Errorf("key %v left the exited overlay", key)
+			}
+			if cmd != nil {
+				t.Errorf("key %v returned a command from an exited overlay", key)
+			}
+		}
+		// nothing was written to a tool that is no longer there
+		if got := f.input(t, ""); got != "" {
+			t.Errorf("an exited overlay forwarded %q to the dead session", got)
+		}
+	})
+}
+
+// The window between the keypress and termStartedMsg has no session and no
+// emulator. A key there must be dropped, not dereferenced: a panic would
+// re-panic through logx.Recover and take keepkit down.
+func TestToolOverlayKeysBeforeStart(t *testing.T) {
+	m := newTestModel(focusTools)
+	m.mode = modeToolOverlay
+	m.termToolName = "git"
+
+	for _, key := range []tea.KeyMsg{
+		keyRunes("x"), tea.KeyMsg{Type: tea.KeyEsc}, tea.KeyMsg{Type: tea.KeyCtrlBackslash},
+		tea.KeyMsg{Type: tea.KeyUp},
+	} {
+		nm, cmd := m.Update(key) // must not panic
+		if nm.(Model).mode != modeToolOverlay {
+			t.Errorf("key %v left the pre-start overlay", key)
+		}
+		if cmd != nil {
+			t.Errorf("key %v returned a command before the session existed", key)
+		}
+	}
+}
+
+// Closing the overlay dispatches nothing at all. The esc that closes it is the
+// one keystroke the deleted tab launcher could have hijacked with a deferred
+// tea.ExecProcess, so this pins that the exit is silent: no fetch, no exec, no
+// status tick rides along.
+func TestToolOverlayCloseDispatchesNothing(t *testing.T) {
+	f := newFakeSession(4)
+	m := overlayModel(t, f)
+	m = mustModel(m.Update(termExitMsg{elapsed: time.Second}))
+
+	nm, cmd := m.Update(tea.KeyMsg{Type: tea.KeyEsc})
+
+	if cmd != nil {
+		t.Errorf("closing the overlay returned a command (%T)", cmd())
+	}
+	if nm.(Model).mode != modeNormal {
+		t.Error("esc did not close the overlay")
+	}
+}
+
+// laidOutOverlay is a ready model of the given size sitting in the overlay with
+// the session adopted and the emulator sized by termGeometry — the state every
+// rendering assertion runs against.
+func laidOutOverlay(t *testing.T, w, h int, f *fakeTermSession) Model {
+	t.Helper()
+
+	m := New([]loader.ToolMeta{{Name: "yazi"}}).WithAppVersion("v0.1.0")
+	mm := mustModel(m.Update(tea.WindowSizeMsg{Width: w, Height: h}))
+	mm.mode = modeToolOverlay
+	mm.termToolName = "yazi"
+	mm.termW, mm.termH, _ = mm.termGeometry()
+
+	nm := mustModel(mm.Update(termStartedMsg{session: f}))
+	t.Cleanup(func() { nm.closeToolOverlay() })
+	return nm
+}
+
+// blockSize reports the overlay frame's size in visible cells.
+//
+// Measured on the frame itself rather than on the composited View: the layout
+// behind it is full of rounded corners of its own (three panels and the status
+// bar), so scanning the finished screen for a frame finds the panels' borders
+// and reports a size that never changes no matter what the overlay does.
+func blockSize(t *testing.T, frame string) (rows, cols int) {
+	t.Helper()
+
+	lines := strings.Split(stripANSI(frame), "\n")
+	for _, line := range lines {
+		if w := len([]rune(line)); w > cols {
+			cols = w
+		}
+	}
+	if cols == 0 {
+		t.Fatal("the overlay frame rendered nothing")
+	}
+	return len(lines), cols
+}
+
+// The block must not move when the tool exits. Height is held by the reserved
+// exit row and width by padding every row to the body width; without either,
+// PlaceOverlay re-centres the whole frame at the exact moment the user is
+// reading the outcome.
+func TestToolOverlayBlockDoesNotMoveAtExit(t *testing.T) {
+	for _, dim := range [][2]int{{80, 24}, {120, 34}} {
+		t.Run(fmt.Sprintf("%dx%d", dim[0], dim[1]), func(t *testing.T) {
+			f := newFakeSession(4)
+			m := laidOutOverlay(t, dim[0], dim[1], f)
+			m = mustModel(m.Update(termChunkMsg{session: f, data: []byte("a wide enough line of tool output\r\n")}))
+
+			runRows, runCols := blockSize(t, m.renderToolOverlay())
+
+			exited := mustModel(m.Update(termExitMsg{elapsed: 12 * time.Second}))
+			exitRows, exitCols := blockSize(t, exited.renderToolOverlay())
+
+			if runRows != exitRows {
+				t.Errorf("block height %d running, %d exited — the reserved row is not doing its job", runRows, exitRows)
+			}
+			if runCols != exitCols {
+				t.Errorf("block width %d running, %d exited — a row is not padded to the body width", runCols, exitCols)
+			}
+		})
+	}
+}
+
+// Every row inside the frame is exactly the body width, whatever the tool
+// printed: a short row leaves a ragged edge and a long one widens the block.
+func TestToolOverlayRowsAreExactlyBodyWidth(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+	// a line carrying SGR, and one longer than the body can hold
+	m = mustModel(m.Update(termChunkMsg{session: f,
+		data: []byte("\x1b[1;31mred\x1b[0m short\r\n" + strings.Repeat("x", 200))}))
+
+	rows := m.termBodyRows(m.termW, m.termH)
+	for i, row := range rows {
+		if got := lipgloss.Width(row); got != m.termW {
+			t.Errorf("body row %d is %d cells, want %d", i, got, m.termW)
+		}
+	}
+
+	frame := m.renderToolOverlay()
+	widths := map[int]bool{}
+	for _, line := range strings.Split(stripANSI(frame), "\n") {
+		widths[len([]rune(line))] = true
+	}
+	if len(widths) != 1 {
+		t.Errorf("frame lines have %d distinct widths %v, want all equal", len(widths), widths)
+	}
+}
+
+// A tool whose name is wider than the body must not widen the block. lipgloss
+// sizes a border to its widest line, so an unclamped title row is the one thing
+// that can push the frame past the geometry everything else agreed on — and it
+// would push it past the screen edge, where PlaceOverlay clips silently.
+func TestToolOverlayLongToolNameDoesNotWidenTheBlock(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+	want := frameWidth(t, m.renderToolOverlay())
+
+	m.termToolName = strings.Repeat("very-long-tool-name-", 8)
+	if got := frameWidth(t, m.renderToolOverlay()); got != want {
+		t.Errorf("frame is %d cells wide with a long tool name, want %d", got, want)
+	}
+
+	// and the same once it has exited, where the title row loses its right cell
+	m.termExit = &termExitMsg{elapsed: time.Second}
+	if got := frameWidth(t, m.renderToolOverlay()); got != want {
+		t.Errorf("exited frame is %d cells wide with a long tool name, want %d", got, want)
+	}
+}
+
+// frameWidth is the visible width of a rendered frame's widest line.
+func frameWidth(t *testing.T, frame string) int {
+	t.Helper()
+
+	widest := 0
+	for _, line := range strings.Split(stripANSI(frame), "\n") {
+		if w := len([]rune(line)); w > widest {
+			widest = w
+		}
+	}
+	return widest
+}
+
+// The title names the tool and, while it runs, carries the one key that is
+// still keepkit's. Both go once the tool has exited: by then esc is the only
+// key that does anything, and the exit row is what says so.
+func TestToolOverlayTitleAndKillHint(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+
+	running := stripANSI(m.renderToolOverlay())
+	if !strings.Contains(running, "yazi") {
+		t.Error("the frame does not name the tool")
+	}
+	if !strings.Contains(running, `ctrl+\ kill`) {
+		t.Error("the frame does not advertise the kill chord while the tool runs")
+	}
+
+	exited := stripANSI(mustModel(m.Update(termExitMsg{elapsed: time.Second})).renderToolOverlay())
+	if strings.Contains(exited, `ctrl+\ kill`) {
+		t.Error("the kill chord is still advertised after the tool exited")
+	}
+}
+
+// Before termStartedMsg the overlay is already on screen and has to say
+// something rather than showing a blank rectangle.
+func TestToolOverlayStartingBody(t *testing.T) {
+	m := New([]loader.ToolMeta{{Name: "yazi"}})
+	mm := mustModel(m.Update(tea.WindowSizeMsg{Width: 100, Height: 30}))
+	mm.mode = modeToolOverlay
+	mm.termToolName = "yazi"
+
+	if got := stripANSI(mm.renderToolOverlay()); !strings.Contains(got, "starting yazi…") {
+		t.Errorf("pre-start frame does not say what it is waiting for:\n%s", got)
+	}
+}
+
+// The child's cursor is a reverse-video cell while it runs, so a shell prompt
+// does not look frozen; it goes once the tool has exited, because a cursor on a
+// dead screen invites typing.
+func TestToolOverlayCursor(t *testing.T) {
+	// Reverse video is styling, and the default test profile strips it — the
+	// assertion would pass against a cursor that was never drawn.
+	forceColor(t)
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+	m = mustModel(m.Update(termChunkMsg{session: f, data: []byte("$ ")}))
+
+	pos := m.termEmu.CursorPosition()
+	if pos.X != 2 || pos.Y != 0 {
+		t.Fatalf("emulator cursor at (%d,%d), want (2,0) after %q", pos.X, pos.Y, "$ ")
+	}
+
+	rows := m.termBodyRows(m.termW, m.termH)
+	if !strings.Contains(rows[0], "\x1b[7m") {
+		t.Errorf("cursor row carries no reverse-video sequence: %q", rows[0])
+	}
+	if got := lipgloss.Width(rows[0]); got != m.termW {
+		t.Errorf("the cursor splice changed the row width to %d, want %d", got, m.termW)
+	}
+
+	exited := mustModel(m.Update(termExitMsg{elapsed: time.Second}))
+	if strings.Contains(exited.termBodyRows(exited.termW, exited.termH)[0], "\x1b[7m") {
+		t.Error("the cursor is still drawn after the tool exited")
+	}
+}
+
+// The four outcomes each get their own line, and each names what happened plus
+// the way out. No status message accompanies them — the screen is the answer.
+func TestToolOverlayExitRow(t *testing.T) {
+	tests := []struct {
+		name string
+		exit termExitMsg
+		want []string
+	}{
+		{"clean", termExitMsg{elapsed: 12 * time.Second}, []string{"✓ exited", "12s", "esc close"}},
+		{"non-zero", termExitMsg{err: exitErrorWithCode(t, 3), elapsed: 4 * time.Second},
+			[]string{"✕ exit 3", "4s", "esc close"}},
+		{"killed", termExitMsg{err: errors.New("signal: killed"), elapsed: 90 * time.Second, killed: true},
+			[]string{"✕ killed", "1m30s", "esc close"}},
+		{"failed to start", termExitMsg{err: errors.New("no such file"), startFailed: true},
+			[]string{"✕ failed to start", "no such file", "esc close"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f := newFakeSession(4)
+			m := laidOutOverlay(t, 120, 34, f)
+			m = mustModel(m.Update(tt.exit))
+
+			row := stripANSI(m.termExitRow(m.termW))
+			for _, want := range tt.want {
+				if !strings.Contains(row, want) {
+					t.Errorf("exit row %q does not contain %q", row, want)
+				}
+			}
+			if m.statusMsg != "" {
+				t.Errorf("statusMsg = %q, want the exit row to be the only report", m.statusMsg)
+			}
+		})
+	}
+}
+
+// While the tool runs the row is reserved and blank: it exists so the block's
+// height never changes, not to say anything yet.
+func TestToolOverlayExitRowBlankWhileRunning(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+
+	if got := m.termExitRow(m.termW); got != "" {
+		t.Errorf("exit row = %q while the tool runs, want it reserved and blank", got)
+	}
+}
+
+// The status bar has a branch of its own, because the global one advertises six
+// keys the running tool has taken over — including a q quit that cannot fire.
+func TestToolOverlayStatusBar(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 100, 30, f)
+
+	running := stripANSI(m.renderStatusBar())
+	if !strings.Contains(running, "yazi running") || !strings.Contains(running, `ctrl+\ kill`) {
+		t.Errorf("running status bar = %q", running)
+	}
+	for _, dead := range []string{"q quit", "t track", "a api"} {
+		if strings.Contains(running, dead) {
+			t.Errorf("status bar still advertises %q, which the tool has taken over", dead)
+		}
+	}
+
+	exited := stripANSI(mustModel(m.Update(termExitMsg{elapsed: time.Second})).renderStatusBar())
+	if !strings.Contains(exited, "yazi exited") || !strings.Contains(exited, "esc close") {
+		t.Errorf("exited status bar = %q", exited)
+	}
+	if strings.Count(exited, "\n") != 2 {
+		t.Errorf("status bar wrapped: %q", exited)
+	}
+}
+
+// Geometry: 70% of the screen, minus the frame's own chrome, refusing below the
+// minimums. The 80x24 baseline must succeed — it is the default terminal.
+func TestTermGeometry(t *testing.T) {
+	tests := []struct {
+		w, h         int
+		wantW, wantH int
+		wantOK       bool
+	}{
+		// 80x24: background is 22 rows, 70% -> 56x15, body 52x11
+		{80, 24, 52, 11, true},
+		{120, 34, 80, 18, true},
+		{60, 20, termMinBodyW, termMinBodyH, false}, // too short: body would be 8 rows
+		{40, 40, termMinBodyW, 22, false},           // too narrow: body would be 24 cols, height is fine
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("%dx%d", tt.w, tt.h), func(t *testing.T) {
+			w, h, ok := termGeometryFor(tt.w, tt.h)
+			if ok != tt.wantOK {
+				t.Errorf("ok = %v, want %v", ok, tt.wantOK)
+			}
+			if w != tt.wantW || h != tt.wantH {
+				t.Errorf("body = %dx%d, want %dx%d", w, h, tt.wantW, tt.wantH)
+			}
+			if w < termMinBodyW || h < termMinBodyH {
+				t.Errorf("body %dx%d is under the floor — a shrunk terminal must clamp, not vanish", w, h)
+			}
+		})
+	}
+}
+
+// Before the first WindowSizeMsg there is no layout: refused explicitly rather
+// than by the percentages agreeing on the floor by coincidence.
+func TestTermGeometryNotReady(t *testing.T) {
+	m := New([]loader.ToolMeta{{Name: "yazi"}})
+	m.width, m.height = 200, 60 // set, but no WindowSizeMsg has been applied
+
+	if _, _, ok := m.termGeometry(); ok {
+		t.Error("termGeometry() reported ok before the first relayout")
+	}
+}
+
+// A resize follows through to both halves: the emulator is re-laid-out and the
+// tool is told, so its redraw lands on a screen of the right shape.
+func TestToolOverlayResize(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 120, 34, f)
+	beforeW, beforeH := m.termW, m.termH
+
+	nm := mustModel(m.Update(tea.WindowSizeMsg{Width: 160, Height: 44}))
+
+	if nm.termW == beforeW && nm.termH == beforeH {
+		t.Fatalf("geometry unchanged after a resize: %dx%d", nm.termW, nm.termH)
+	}
+	if nm.termEmu.Width() != nm.termW || nm.termEmu.Height() != nm.termH {
+		t.Errorf("emulator is %dx%d, want %dx%d", nm.termEmu.Width(), nm.termEmu.Height(), nm.termW, nm.termH)
+	}
+	got := f.resizes()
+	if len(got) == 0 {
+		t.Fatal("the tool was never told about the resize")
+	}
+	if last := got[len(got)-1]; last[0] != nm.termW || last[1] != nm.termH {
+		t.Errorf("tool told %dx%d, want %dx%d", last[0], last[1], nm.termW, nm.termH)
+	}
+}
+
+// Shrinking past the minimum clamps to the floor and keeps the tool running:
+// resizing somebody's editor into nothing is bad, killing it outright is worse.
+func TestToolOverlayResizeBelowMinimumClamps(t *testing.T) {
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 120, 34, f)
+
+	nm := mustModel(m.Update(tea.WindowSizeMsg{Width: 50, Height: 16}))
+
+	if nm.termW != termMinBodyW || nm.termH != termMinBodyH {
+		t.Errorf("geometry = %dx%d, want the %dx%d floor", nm.termW, nm.termH, termMinBodyW, termMinBodyH)
+	}
+	if nm.mode != modeToolOverlay || nm.termSession == nil {
+		t.Error("a shrink tore the session down")
+	}
+}
+
+// A resize landing in the window between the run-prompt enter and
+// termStartedMsg must still reach the tool. The pty was created at the
+// geometry captured at keypress time; the WindowSizeMsg handler moves
+// termW/termH but has no session to tell, and resizeToolOverlay's
+// nothing-changed early return then sees the new size already stored — so
+// adoption is the one place left that can bring the pty up to date.
+func TestToolOverlayResizeBeforeStartReachesTheSession(t *testing.T) {
+	f := newFakeSession(4)
+	m := New([]loader.ToolMeta{{Name: "yazi"}}).WithAppVersion("v0.1.0")
+	mm := mustModel(m.Update(tea.WindowSizeMsg{Width: 120, Height: 34}))
+	mm.mode = modeToolOverlay
+	mm.termToolName = "yazi"
+	// What the run-prompt enter captured: startTermCmd is in flight at this
+	// size and the pty it creates will be exactly this large.
+	mm.termW, mm.termH, _ = mm.termGeometry()
+	startW, startH := mm.termW, mm.termH
+
+	// The resize lands while term.Start is still in flight.
+	mm = mustModel(mm.Update(tea.WindowSizeMsg{Width: 160, Height: 44}))
+	if mm.termW == startW && mm.termH == startH {
+		t.Fatal("the resize did not change the overlay geometry — the fixture no longer exercises the race")
+	}
+
+	nm := mustModel(mm.Update(termStartedMsg{session: f}))
+	t.Cleanup(func() { nm.closeToolOverlay() })
+
+	if nm.termEmu.Width() != nm.termW || nm.termEmu.Height() != nm.termH {
+		t.Errorf("emulator is %dx%d, want %dx%d", nm.termEmu.Width(), nm.termEmu.Height(), nm.termW, nm.termH)
+	}
+	got := f.resizes()
+	if len(got) == 0 {
+		t.Fatal("the pty keeps the keypress-time size: the session was never resized to the new geometry")
+	}
+	if last := got[len(got)-1]; last[0] != nm.termW || last[1] != nm.termH {
+		t.Errorf("session resized to %dx%d, want %dx%d", last[0], last[1], nm.termW, nm.termH)
+	}
+}
+
+// The background is dimmed like every other overlay, so the tool's screen is
+// the only full-colour thing on it.
+func TestToolOverlayDimsTheBackground(t *testing.T) {
+	forceColor(t)
+	f := newFakeSession(4)
+	m := laidOutOverlay(t, 120, 34, f)
+
+	view := m.View()
+	dim := lipgloss.NewStyle().Foreground(ui.Default.Dim).Render("")
+	if seq, _, _ := strings.Cut(dim, "m"); !strings.Contains(view, seq) {
+		t.Error("the layout behind the overlay is not dimmed")
+	}
+}
+
+// exitErrorWithCode produces a real *exec.ExitError carrying code, so the exit
+// row is exercised against the shape a session actually reports rather than a
+// zero value whose ExitCode() is -1.
+func exitErrorWithCode(t *testing.T, code int) error {
+	t.Helper()
+
+	err := exec.Command("sh", "-c", fmt.Sprintf("exit %d", code)).Run()
+	var ee *exec.ExitError
+	if !errors.As(err, &ee) {
+		t.Fatalf("sh -c 'exit %d' returned %v, want an *exec.ExitError", code, err)
+	}
+	return ee
+}
+
+// The whole loop against a *real* pty, once: start → adopt → drain → render →
+// exit. Every other overlay test drives a fake session, which is what makes
+// them fast and deterministic but also means none of them would notice if
+// waitForTermChunkCmd and term.Session disagreed about their own channel.
+//
+// Deliberately not the run-prompt's returned cmd — that stays untested by
+// design — and deliberately a printf rather than anything interactive: this
+// asserts the wiring, not the tools.
+func TestToolOverlayEndToEndWithRealPty(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("ConPTY is not exercised by CI; see the plan's manual verification")
+	}
+
+	m := newTestModel(focusTools)
+	m = mustModel(m.Update(tea.WindowSizeMsg{Width: 120, Height: 34}))
+	m.mode = modeToolOverlay
+	m.termToolName = "printer"
+	m.termW, m.termH, _ = m.termGeometry()
+
+	shell, args := shellCommand(runtime.GOOS, "printf 'real pty output'")
+	msg := startTermCmd(shell, args, m.termW, m.termH)()
+
+	started, ok := msg.(termStartedMsg)
+	if !ok {
+		t.Fatalf("startTermCmd returned %T (%+v), want termStartedMsg", msg, msg)
+	}
+	m = mustModel(m.Update(started))
+	t.Cleanup(func() { m.closeToolOverlay() })
+
+	// Pump the chain to its end, exactly as the tea runtime would.
+	cmd := waitForTermChunkCmd(m.termSession)
+	var exit *termExitMsg
+	for range 50 {
+		next := cmd()
+		if next == nil {
+			t.Fatal("the command chain produced a nil message")
+		}
+		updated, follow := m.Update(next)
+		m = updated.(Model)
+		if m.termExit != nil {
+			exit = m.termExit
+			break
+		}
+		if follow == nil {
+			t.Fatal("the chain stopped before the exit arrived")
+		}
+		cmd = follow
+	}
+
+	if exit == nil {
+		t.Fatal("no exit after 50 messages")
+	}
+	if exit.err != nil {
+		t.Errorf("exit.err = %v, want nil for a clean printf", exit.err)
+	}
+	if exit.elapsed <= 0 {
+		t.Errorf("exit.elapsed = %v, want > 0", exit.elapsed)
+	}
+	if got := m.termEmu.Render(); !strings.Contains(got, "real pty output") {
+		t.Errorf("the tool's output never reached the emulator: %q", got)
+	}
+	// and the frame the user actually sees carries it plus the way out
+	view := stripANSI(m.renderToolOverlay())
+	if !strings.Contains(view, "real pty output") || !strings.Contains(view, "esc close") {
+		t.Errorf("the rendered overlay is missing the output or the exit row:\n%s", view)
+	}
+}
+
+var _ tea.Model = Model{}
diff --git a/internal/model/race_disabled_test.go b/internal/model/race_disabled_test.go
new file mode 100644
index 0000000..0b73f9a
--- /dev/null
+++ b/internal/model/race_disabled_test.go
@@ -0,0 +1,6 @@
+//go:build !race
+
+package model
+
+// raceEnabled: see race_enabled_test.go — this is the plain-build half.
+const raceEnabled = false
diff --git a/internal/model/race_enabled_test.go b/internal/model/race_enabled_test.go
new file mode 100644
index 0000000..c97a95e
--- /dev/null
+++ b/internal/model/race_enabled_test.go
@@ -0,0 +1,9 @@
+//go:build race
+
+package model
+
+// raceEnabled reports that this test binary runs under the race detector.
+// Its instrumentation slows string-heavy code several times over, and the
+// pathological-input budget test scales its budget by it rather than either
+// flaking on CI's shared runners or dropping the guard.
+const raceEnabled = true
diff --git a/internal/model/readme_clean_test.go b/internal/model/readme_clean_test.go
index e8638d6..228fa59 100644
--- a/internal/model/readme_clean_test.go
+++ b/internal/model/readme_clean_test.go
@@ -529,7 +529,16 @@ func TestCleanReadmeMarkdownNormalizesCRLF(t *testing.T) {
 // The shape that did: one line of leading block markers, which made
 // rcLineContent copy the remaining line once per marker — 8.4 s at the cap.
 func TestCleanReadmeMarkdownPathologicalInputIsFast(t *testing.T) {
-	const budget = 2 * time.Second
+	budget := 2 * time.Second
+	if raceEnabled {
+		// The race detector slows this string-heavy pass several times over
+		// — ~1s under race on an M-series against ~30ms without — and CI's
+		// shared two-core runners land exactly on the 2s line (2.003s and
+		// 2.031s observed on a fair pass). The guard is against the 8.4s
+		// freeze class, so tripling under race still catches the regression
+		// while no longer failing a pass a slower runner merely stretched.
+		budget *= 3
+	}
 	inputs := map[string]string{
 		"leading bullets":  "\U0001F680 " + strings.Repeat("- ", 262144),
 		"leading quotes":   "\U0001F680 " + strings.Repeat("> ", 262144),
diff --git a/internal/model/render.go b/internal/model/render.go
index 1569a1e..b3a71ea 100644
--- a/internal/model/render.go
+++ b/internal/model/render.go
@@ -30,9 +30,18 @@ func (m Model) View() string {
 	body := lipgloss.JoinHorizontal(lipgloss.Top, left, middle, right)
 	layout := lipgloss.JoinVertical(lipgloss.Left, body, m.renderStatusBar())
 	if m.overlayVisible() {
-		fg := m.renderAPIStatus()
-		if m.mode == modeHotkeys {
+		// One picker per overlay mode. It is a switch rather than the two-way
+		// if it grew out of because the API-status default silently answered
+		// for every mode that was not modeHotkeys — with a third overlay that
+		// would have painted the token panel over a running tool.
+		var fg string
+		switch m.mode {
+		case modeHotkeys:
 			fg = m.renderHotkeys()
+		case modeToolOverlay:
+			fg = m.renderToolOverlay()
+		default:
+			fg = m.renderAPIStatus()
 		}
 		layout = ui.PlaceOverlay(layout, fg, m.sty().OverlayDim)
 	}
@@ -120,6 +129,16 @@ func (m Model) renderStatusBar() string {
 	if m.mode == modeHotkeys {
 		return style.Render(m.hint("esc", "close"))
 	}
+	// The overlay's siblings all have a branch here, and without one the bar
+	// would go on advertising six global keys the running tool has taken over —
+	// including a q quit that cannot fire. Two states, because the keyboard
+	// belongs to different owners in each.
+	if m.mode == modeToolOverlay {
+		if m.termExit == nil {
+			return style.Render(s.Dim.Render(m.termToolName+" running") + "  " + m.hint(`ctrl+\`, "kill"))
+		}
+		return style.Render(s.Dim.Render(m.termToolName+" exited") + "  " + m.hint("esc", "close"))
+	}
 	if m.statusMsg != "" {
 		return style.Render(s.AccentBold.Render(m.statusMsg))
 	}
@@ -794,7 +813,7 @@ func (m Model) renderHotkeys() string {
 			// group is the on-screen statement of the same-in-every-focus rule.
 			{"/", "filter the list"},
 			{"space", "group by tag"},
-			{"enter", "run in a tab"},
+			{"enter", "run in overlay"},
 		}},
 	})
 
diff --git a/internal/model/render_test.go b/internal/model/render_test.go
index 88c8421..e00cbfa 100644
--- a/internal/model/render_test.go
+++ b/internal/model/render_test.go
@@ -4457,7 +4457,7 @@ func TestRenderHotkeysOverlayContent(t *testing.T) {
 		"self-update",       // self
 		"navigate / scroll", // [3] readme
 		"half page",         // [3] readme
-		"run in a tab",      // [1] tools enter row
+		"run in overlay",    // [1] tools enter row
 		"close",             // title close hint
 	} {
 		if !strings.Contains(view, want) {
@@ -4522,7 +4522,7 @@ func TestRenderHotkeysSizeBudget(t *testing.T) {
 	}
 	// Bottom-most row of the left column — its trailing word survives only if
 	// nothing was clipped off the bottom or the right edge.
-	if !strings.Contains(view, "run in a tab") {
+	if !strings.Contains(view, "run in overlay") {
 		t.Errorf("size budget: last [1] tools row clipped (bottom/right overflow)")
 	}
 	// Bottom-most row of the right column, in the widest state.
diff --git a/internal/model/status_test.go b/internal/model/status_test.go
index 328689c..452a847 100644
--- a/internal/model/status_test.go
+++ b/internal/model/status_test.go
@@ -1,7 +1,6 @@
 package model
 
 import (
-	"runtime"
 	"strings"
 	"testing"
 	"time"
@@ -14,9 +13,8 @@ import (
 
 // shrinkStatusTTL shortens statusMsgTTL so a test can invoke the tick Cmd that
 // setStatus returns without waiting the real TTL (tea.Tick blocks for the full
-// duration). Same var-seam idiom as launchTimeout in launch_test.go. Must be
-// called before the Update that produces the tick — tea.Tick captures the TTL
-// value at construction time.
+// duration). Must be called before the Update that produces the tick —
+// tea.Tick captures the TTL value at construction time.
 func shrinkStatusTTL(t *testing.T) {
 	t.Helper()
 	orig := statusMsgTTL
@@ -163,45 +161,6 @@ func TestToggleGroupByTagSetsExpiringStatus(t *testing.T) {
 	assertExpiryTickSeq(t, cmd, m.statusSeq)
 }
 
-// TestInFlightStatusSurvivesStaleExpiry drives the real sequence a user can
-// produce in under statusMsgTTL: a transient status (the group toggle), then a
-// launch dispatch whose "launching …" message reports work still in progress.
-// The transient's timer is still in flight when the launch message lands, and it
-// must not take it down — the in-flight status is extinguished by launchDoneMsg,
-// not by the clock, and losing it hides the only sign the adapter is busy for up
-// to launchTimeout. A direct m.statusMsg assignment leaves statusSeq unbumped,
-// so the stale timer's seq still matches and the expiry handler wipes it; the
-// bump is what setStickyStatus exists for.
-func TestInFlightStatusSurvivesStaleExpiry(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("the adapter path needs a unix tmux environment")
-	}
-	shrinkStatusTTL(t)
-	clearTerminalEnv(t)
-	t.Setenv("TMUX", "/nonexistent/keepkit-test-socket,99999,0")
-
-	m := groupTestModel(t)
-	m.focus = focusTools
-	toggleCmd := m.toggleGroupByTag()
-	staleSeq := m.statusSeq
-	if toggleCmd == nil {
-		t.Fatal("toggle returned no expiry tick")
-	}
-
-	// The launch dispatch: an adapter plan, so the status is the in-flight one.
-	nm, _ := enterRun(m, "git status")
-	if !strings.Contains(nm.statusMsg, "launching") {
-		t.Fatalf("statusMsg = %q, want the in-flight launch feedback", nm.statusMsg)
-	}
-	inFlight := nm.statusMsg
-
-	// The toggle's timer fires now — it belongs to a message already replaced.
-	after := mustModel(nm.Update(statusExpiredMsg{seq: staleSeq}))
-	if after.statusMsg != inFlight {
-		t.Errorf("statusMsg = %q after the stale expiry, want the in-flight %q", after.statusMsg, inFlight)
-	}
-}
-
 // TestStatusBarReturnsHintsAfterExpiry: while a transient status is live the bar
 // shows it (outranking the hints); once the matching timer fires the hints bar
 // returns on its own, with no keypress.
diff --git a/internal/model/zoom_test.go b/internal/model/zoom_test.go
index dd4c49b..27038d0 100644
--- a/internal/model/zoom_test.go
+++ b/internal/model/zoom_test.go
@@ -284,7 +284,7 @@ func TestZoomInSearchStaysQueryText(t *testing.T) {
 // screen underneath an open modal is the one failure this would produce, and
 // modeSearch next door proves the dispatch is not uniform.
 func TestZoomUnderOverlay(t *testing.T) {
-	for _, mode := range []inputMode{modeHotkeys, modeAPIStatus} {
+	for _, mode := range []inputMode{modeHotkeys, modeAPIStatus, modeToolOverlay} {
 		m := zoomModel(t, 160, 40)
 		m.mode = mode
 		nm := mustModel(m.Update(keyRunes("z")))
diff --git a/internal/term/attr_unix.go b/internal/term/attr_unix.go
new file mode 100644
index 0000000..4efb767
--- /dev/null
+++ b/internal/term/attr_unix.go
@@ -0,0 +1,43 @@
+//go:build !windows
+
+package term
+
+import (
+	"syscall"
+
+	"github.com/charmbracelet/x/xpty"
+)
+
+// ptyProcAttr puts the child in its own session with the pty slave as its
+// controlling terminal.
+//
+// xpty does neither — UnixPty.Start only wires stdin/stdout/stderr to the slave
+// — so without this the child inherits keepkit's controlling terminal, job
+// control never engages, and Kill's process-group signal would land on
+// keepkit's own group.
+//
+// Ctty is left at its zero value on purpose: it names a descriptor in the
+// *child's* table, and fd 0 there is the slave xpty just attached as stdin.
+func ptyProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true, Setctty: true}
+}
+
+// closeSlave drops the parent's copy of the pty slave right after the child
+// starts. xpty keeps both halves of the pair open in the parent and its Start
+// never closes the slave (creack/pty's own StartWithAttrs does, with a defer
+// right after Open — xpty rewired the same fds without that line), and on
+// Linux a read on the master returns EIO only once *every* slave fd is closed
+// — the parent's copy included. Keeping it meant the child's exit never ended
+// stream's read, so the Exit event never fired and every consumer of Events()
+// hung; macOS revokes the terminal when the session leader exits and answers
+// EOF regardless, which is why the leak was invisible locally.
+//
+// Closing here is safe for Setctty: cmd.Start's fork/exec handshake completes
+// before it returns, so the child has already made its own fd 0 — its dup of
+// the slave — the controlling terminal. The child's copies are untouched;
+// only the parent's leaks.
+func closeSlave(p xpty.Pty) {
+	if u, ok := p.(*xpty.UnixPty); ok {
+		_ = u.Slave().Close()
+	}
+}
diff --git a/internal/term/attr_windows.go b/internal/term/attr_windows.go
new file mode 100644
index 0000000..afbc0b3
--- /dev/null
+++ b/internal/term/attr_windows.go
@@ -0,0 +1,19 @@
+//go:build windows
+
+package term
+
+import (
+	"syscall"
+
+	"github.com/charmbracelet/x/xpty"
+)
+
+// ptyProcAttr has nothing to add on Windows: ConPTY gives the child its own
+// console, and the session-leader/controlling-terminal model the unix build
+// needs Setsid/Setctty for does not exist here. ConPty.Start passes this
+// straight through to the spawn as ProcAttr.Sys, where nil is fine.
+func ptyProcAttr() *syscall.SysProcAttr { return nil }
+
+// closeSlave has nothing to close on Windows: a ConPTY is one pseudo-console
+// handle rather than a master/slave fd pair, and ConPty.Close owns all of it.
+func closeSlave(xpty.Pty) {}
diff --git a/internal/term/session.go b/internal/term/session.go
new file mode 100644
index 0000000..501d160
--- /dev/null
+++ b/internal/term/session.go
@@ -0,0 +1,185 @@
+// Package term runs a command on a pseudo-terminal and streams what it prints.
+//
+// It is the architectural slot the old tab launcher vacated: bottom of the
+// import graph, no TUI knowledge. A Session owns the pty and one reader
+// goroutine; everything it observes leaves through Events() as a value, so the
+// model can consume it with the same waitForChunkCmd pattern the update
+// streamer uses. The terminal *emulator* deliberately lives on the model, not
+// here — only Bubble Tea's Update goroutine may touch its screen state.
+//
+// The caller builds argv (keepkit's model has shellCommand for that) and hands
+// it to Start, which keeps this package goos-agnostic.
+//
+// This package writes no config and does no logx logging: a failure rides
+// Exit.Err to the caller, which is the surface that can actually show it. That
+// is why it needs no TestMain seam, unlike loader/version/logx.
+package term
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/charmbracelet/x/xpty"
+	"github.com/stanlyzoolo/keepkit/internal/proc"
+)
+
+// readChunk bounds one read off the pty master. A full-screen redraw of a
+// large terminal is tens of kilobytes, so this sizes one repaint into one
+// event rather than a dozen.
+const readChunk = 32 * 1024
+
+// Event is what a Session reports: Data for output, Exit exactly once, last.
+type Event interface{ termEvent() }
+
+// Data is a chunk of bytes the child wrote. Bytes is owned by the receiver —
+// the reader copies out of its buffer before sending.
+type Data struct{ Bytes []byte }
+
+func (Data) termEvent() {}
+
+// Exit is the final event on the channel; the channel closes right after it.
+// Err is nil for a clean exit and an *exec.ExitError for a non-zero one, so a
+// caller can read the code off it. Elapsed is stamped in the reader goroutine,
+// never by the consumer — a consumer that stamped it would make completion
+// depend on when it got round to reading, which is not a testable quantity.
+type Exit struct {
+	Err     error
+	Elapsed time.Duration
+	// Killed reports that the exit followed a Kill() call rather than the
+	// child deciding to stop. The session is the only place that knows both
+	// halves of that, so it answers rather than making the caller correlate
+	// its own keypress against an exit status that says "signal: killed".
+	Killed bool
+}
+
+func (Exit) termEvent() {}
+
+// Session is one command running on one pty.
+type Session struct {
+	pty    xpty.Pty
+	cmd    *exec.Cmd
+	events chan Event
+
+	killed    atomic.Bool
+	closeOnce sync.Once
+}
+
+// Start runs shell with args on a fresh w×h pty and begins streaming.
+//
+// env is the child's environment; nil inherits keepkit's. TERM and COLORTERM
+// are appended either way — os/exec keeps the last value for a duplicate key,
+// so appending overrides an inherited TERM without having to scan for it. The
+// working directory is inherited.
+//
+// On unix the child is put in its own session with the pty slave as its
+// controlling terminal. xpty does not do this itself (it only wires stdio), and
+// without it job control never engages and the kill path would signal the wrong
+// process group. It is also why proc.DetachTTY must never be applied here: it
+// assigns SysProcAttr wholesale and would drop Setctty.
+func Start(shell string, args []string, w, h int, env []string) (*Session, error) {
+	pty, err := xpty.NewPty(w, h)
+	if err != nil {
+		return nil, err
+	}
+
+	if env == nil {
+		env = os.Environ()
+	}
+	cmd := exec.Command(shell, args...)
+	cmd.Env = append(append([]string{}, env...), "TERM=xterm-256color", "COLORTERM=truecolor")
+	cmd.SysProcAttr = ptyProcAttr()
+
+	if err := pty.Start(cmd); err != nil {
+		_ = pty.Close()
+		return nil, err
+	}
+	// The child owns its dup of the slave now; the parent's copy must go, or
+	// on Linux the master never answers EIO after the child exits and the
+	// Exit event never fires. See closeSlave.
+	closeSlave(pty)
+
+	s := &Session{
+		pty:    pty,
+		cmd:    cmd,
+		events: make(chan Event, eventBuffer),
+	}
+	go s.stream()
+	return s, nil
+}
+
+// eventBuffer lets the reader stay ahead of a consumer that only drains once
+// per Bubble Tea message, without letting output queue without bound: past it
+// the reader blocks, the pty buffer fills, and the child is throttled — which
+// is the correct back-pressure for a tool printing faster than we can paint.
+const eventBuffer = 64
+
+// Events returns the stream. It yields zero or more Data events, then exactly
+// one Exit, then closes.
+func (s *Session) Events() <-chan Event { return s.events }
+
+// stream is the one goroutine per session: pty master → Data events, then the
+// process verdict → Exit, then close.
+func (s *Session) stream() {
+	started := time.Now()
+	buf := make([]byte, readChunk)
+
+	for {
+		n, err := s.pty.Read(buf)
+		if n > 0 {
+			chunk := make([]byte, n)
+			copy(chunk, buf[:n])
+			s.events <- Data{Bytes: chunk}
+		}
+		if err != nil {
+			// Any read error ends the stream and none of them is the
+			// verdict. A master whose child has exited answers EIO on
+			// Linux and EOF on macOS, and a master closed by Kill/Close
+			// answers os.ErrClosed — all three are normal termination.
+			// What actually happened comes from the wait below.
+			break
+		}
+	}
+
+	err := xpty.WaitProcess(context.Background(), s.cmd)
+	s.events <- Exit{Err: err, Elapsed: time.Since(started), Killed: s.killed.Load()}
+	close(s.events)
+}
+
+// Write sends input to the child.
+func (s *Session) Write(p []byte) (int, error) { return s.pty.Write(p) }
+
+// Resize tells the child its terminal changed size.
+func (s *Session) Resize(w, h int) error { return s.pty.Resize(w, h) }
+
+// Kill terminates the child and everything it spawned. The unix child is a
+// session leader (see Start), so its pid doubles as its process-group id and
+// proc.KillGroup's negative-pid signal reaches the tools an `sh -c` line
+// started. Best-effort: an already-exited process is a no-op, and the verdict
+// still arrives as the Exit event once the reader drains.
+func (s *Session) Kill() {
+	s.killed.Store(true)
+	_ = proc.KillGroup(s.cmd)
+}
+
+// Close releases the pty. Calling it while the child lives sends it SIGHUP;
+// the normal path is to Close after the Exit event has already arrived. Safe
+// to call more than once.
+//
+// os.ErrClosed is filtered out: xpty's Close closes master then slave, and the
+// unix slave was already dropped at Start (see closeSlave) — its second close
+// is the expected shape of a clean teardown, not a failure to report.
+func (s *Session) Close() error {
+	var err error
+	s.closeOnce.Do(func() {
+		err = s.pty.Close()
+		if errors.Is(err, os.ErrClosed) {
+			err = nil
+		}
+	})
+	return err
+}
diff --git a/internal/term/session_test.go b/internal/term/session_test.go
new file mode 100644
index 0000000..01c9f4e
--- /dev/null
+++ b/internal/term/session_test.go
@@ -0,0 +1,316 @@
+//go:build !windows
+
+package term
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"os/exec"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	uv "github.com/charmbracelet/ultraviolet"
+	"github.com/charmbracelet/x/vt"
+)
+
+// collect drains a session to its Exit event, returning everything the child
+// printed plus the verdict. It fails rather than hangs if the session never
+// finishes, so a regression shows up as one named test instead of a timeout on
+// the whole package.
+func collect(t *testing.T, s *Session, within time.Duration) ([]byte, Exit) {
+	t.Helper()
+
+	var out []byte
+	deadline := time.After(within)
+	for {
+		select {
+		case ev, ok := <-s.Events():
+			if !ok {
+				t.Fatal("channel closed before an Exit event")
+			}
+			switch e := ev.(type) {
+			case Data:
+				out = append(out, e.Bytes...)
+			case Exit:
+				// the channel must close right after the Exit
+				select {
+				case _, open := <-s.Events():
+					if open {
+						t.Fatal("an event followed Exit")
+					}
+				case <-time.After(time.Second):
+					t.Fatal("channel did not close after Exit")
+				}
+				return out, e
+			}
+		case <-deadline:
+			t.Fatalf("session did not finish within %s", within)
+		}
+	}
+}
+
+func startTest(t *testing.T, script string) *Session {
+	t.Helper()
+
+	s, err := Start("sh", []string{"-c", script}, 80, 24, nil)
+	if err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	return s
+}
+
+// A clean run streams its output and reports a nil error. This doubles as the
+// EOF test: reading a pty master whose child has exited answers EIO on Linux
+// and EOF on macOS, and neither may become the verdict.
+func TestSessionRunsAndExitsClean(t *testing.T) {
+	s := startTest(t, "printf hi")
+
+	out, exit := collect(t, s, 10*time.Second)
+
+	if !bytes.Contains(out, []byte("hi")) {
+		t.Errorf("output %q does not contain %q", out, "hi")
+	}
+	if exit.Err != nil {
+		t.Errorf("Exit.Err = %v, want nil (a pty read error is not the verdict)", exit.Err)
+	}
+	if exit.Killed {
+		t.Error("Exit.Killed is true for a session nobody killed")
+	}
+	if exit.Elapsed <= 0 {
+		t.Errorf("Exit.Elapsed = %v, want > 0 (stamped in the reader, not by the consumer)", exit.Elapsed)
+	}
+}
+
+// A non-zero exit rides Exit.Err as an *exec.ExitError, so the caller can read
+// the code off it for the overlay's outcome line.
+func TestSessionNonZeroExit(t *testing.T) {
+	s := startTest(t, "exit 3")
+
+	_, exit := collect(t, s, 10*time.Second)
+
+	var ee *exec.ExitError
+	if !errors.As(exit.Err, &ee) {
+		t.Fatalf("Exit.Err = %v (%T), want an *exec.ExitError", exit.Err, exit.Err)
+	}
+	if got := ee.ExitCode(); got != 3 {
+		t.Errorf("exit code %d, want 3", got)
+	}
+}
+
+// A tool that is not installed is not a special case: sh reports it and exits
+// 127, which is what the overlay shows. This replaces the old notFoundExit
+// mapping the tab launcher needed.
+func TestSessionNotInstalledToolExits127(t *testing.T) {
+	s := startTest(t, "keepkit-no-such-tool-xyz")
+
+	out, exit := collect(t, s, 10*time.Second)
+
+	var ee *exec.ExitError
+	if !errors.As(exit.Err, &ee) {
+		t.Fatalf("Exit.Err = %v, want an *exec.ExitError", exit.Err)
+	}
+	if got := ee.ExitCode(); got != 127 {
+		t.Errorf("exit code %d, want 127", got)
+	}
+	if !strings.Contains(strings.ToLower(string(out)), "not found") {
+		t.Errorf("output %q does not carry the shell's not-found message", out)
+	}
+}
+
+// Kill terminates a child that would otherwise outlive the test, the channel
+// closes, and the Exit says it was killed rather than leaving the caller to
+// infer it from "signal: killed".
+func TestSessionKill(t *testing.T) {
+	before := runtime.NumGoroutine()
+	s := startTest(t, "sleep 60")
+
+	// let the child actually reach sleep before killing it
+	time.Sleep(150 * time.Millisecond)
+	s.Kill()
+
+	_, exit := collect(t, s, 10*time.Second)
+
+	if exit.Err == nil {
+		t.Error("Exit.Err is nil for a killed child")
+	}
+	if !exit.Killed {
+		t.Error("Exit.Killed is false after Kill()")
+	}
+
+	// the reader goroutine must be gone once the channel closed
+	waitGoroutines(t, before)
+}
+
+// Kill reaches the tools an `sh -c` line spawned, not just the shell: the child
+// is a session leader, so the negative-pid signal covers the whole group. A
+// grandchild that survived would keep the pty's write end open and the reader
+// would never see EOF - which is exactly what this asserts by finishing.
+func TestSessionKillReachesGrandchildren(t *testing.T) {
+	s := startTest(t, "sleep 60 & sleep 60")
+
+	time.Sleep(150 * time.Millisecond)
+	s.Kill()
+
+	_, exit := collect(t, s, 10*time.Second)
+	if !exit.Killed {
+		t.Error("Exit.Killed is false after Kill()")
+	}
+}
+
+func TestSessionResize(t *testing.T) {
+	s := startTest(t, "sleep 1")
+
+	if err := s.Resize(100, 30); err != nil {
+		t.Fatalf("Resize: %v", err)
+	}
+
+	s.Kill()
+	collect(t, s, 10*time.Second)
+}
+
+// Write reaches the child's stdin.
+func TestSessionWrite(t *testing.T) {
+	s := startTest(t, "read line; printf 'got:%s' \"$line\"")
+
+	time.Sleep(150 * time.Millisecond)
+	if _, err := s.Write([]byte("ping\r")); err != nil {
+		t.Fatalf("Write: %v", err)
+	}
+
+	out, exit := collect(t, s, 10*time.Second)
+	if exit.Err != nil {
+		t.Errorf("Exit.Err = %v, want nil", exit.Err)
+	}
+	if !bytes.Contains(out, []byte("got:ping")) {
+		t.Errorf("output %q does not echo the written line", out)
+	}
+}
+
+// A bogus command fails at Start and leaks nothing: no session is returned, so
+// there is no channel to close and no goroutine to leak.
+func TestStartBogusShell(t *testing.T) {
+	before := runtime.NumGoroutine()
+
+	s, err := Start("keepkit-no-such-shell-xyz", nil, 80, 24, nil)
+	if err == nil {
+		_ = s.Close()
+		t.Fatal("Start with a bogus shell returned no error")
+	}
+	if s != nil {
+		t.Errorf("Start returned a session (%v) alongside an error", s)
+	}
+
+	waitGoroutines(t, before)
+}
+
+// Start's env is what the child sees, and TERM/COLORTERM are appended so the
+// tool renders in colour. Appending is enough because os/exec keeps the last
+// value for a duplicate key - this pins that, since an inherited TERM would
+// otherwise win and a tmux/screen TERM would cost the overlay its colours.
+func TestSessionEnvOverridesTerm(t *testing.T) {
+	s, err := Start("sh", []string{"-c", "printf '%s|%s' \"$TERM\" \"$COLORTERM\""},
+		80, 24, []string{"TERM=dumb"})
+	if err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+
+	out, _ := collect(t, s, 10*time.Second)
+
+	if !bytes.Contains(out, []byte("xterm-256color|truecolor")) {
+		t.Errorf("child saw %q, want TERM=xterm-256color and COLORTERM=truecolor", out)
+	}
+}
+
+// The bytes a session streams are what a vt emulator turns back into a screen -
+// this is the whole contract between internal/term and the model, checked once
+// here so the model's own tests can use a fake session with a clear conscience.
+func TestSessionOutputRendersInEmulator(t *testing.T) {
+	s := startTest(t, "printf 'hello pty'")
+
+	out, _ := collect(t, s, 10*time.Second)
+
+	emu := vt.NewEmulator(40, 5)
+	if _, err := emu.Write(out); err != nil {
+		t.Fatalf("emulator write: %v", err)
+	}
+	if !strings.Contains(emu.Render(), "hello pty") {
+		t.Errorf("emulator rendered %q, want it to contain %q", emu.Render(), "hello pty")
+	}
+}
+
+// Closing the emulator's input pipe is how a copy goroutine parked in Read is
+// stopped, and it must stay race-free: Emulator.Close() writes an
+// unsynchronised bool that Read checks on every call (charmbracelet/x#879), so
+// the obvious teardown is the one that trips -race. Closing InputPipe()'s
+// writer goes through io.Pipe's own synchronisation instead and never touches
+// that bool. The model's overlay teardown depends on this; see
+// docs/research/pty-stack.md.
+func TestSessionInputPipeCloseIsRaceFree(t *testing.T) {
+	emu := vt.NewEmulator(20, 5)
+
+	var relayed []byte
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		buf := make([]byte, 64)
+		for {
+			n, err := emu.Read(buf)
+			if n > 0 {
+				relayed = append(relayed, buf[:n]...)
+			}
+			if err != nil {
+				return
+			}
+		}
+	}()
+
+	// drive the screen state from this goroutine while the copy goroutine
+	// reads the input side: the two halves must not race either.
+	for range 50 {
+		if _, err := emu.Write([]byte("x")); err != nil {
+			t.Fatalf("emulator write: %v", err)
+		}
+		emu.SendKey(uv.KeyPressEvent{Code: 'a'})
+	}
+
+	closer, ok := emu.InputPipe().(io.Closer)
+	if !ok {
+		t.Fatalf("InputPipe() is %T, not an io.Closer - the overlay teardown assumes it is", emu.InputPipe())
+	}
+	if err := closer.Close(); err != nil {
+		t.Fatalf("close input pipe: %v", err)
+	}
+
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("the copy goroutine did not exit after the input pipe was closed")
+	}
+	if len(relayed) != 50 {
+		t.Errorf("relayed %d bytes, want 50", len(relayed))
+	}
+}
+
+// waitGoroutines gives the runtime a moment to retire finished goroutines
+// before comparing counts - an immediate read races the scheduler.
+func waitGoroutines(t *testing.T, before int) {
+	t.Helper()
+
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		got := runtime.NumGoroutine()
+		if got <= before {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Errorf("goroutines: %d before, %d after - the reader leaked", before, got)
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+}
diff --git a/internal/ui/styles.go b/internal/ui/styles.go
index b5d3de5..1d824e9 100644
--- a/internal/ui/styles.go
+++ b/internal/ui/styles.go
@@ -75,6 +75,14 @@ type Styles struct {
 	OverlayBorder lipgloss.Style
 	OverlayDim    lipgloss.Style
 
+	// TermCursor marks where the tool running in the [enter] overlay has its
+	// cursor. It is the one style here that names no theme color, and that is
+	// the point: reverse video swaps whatever the tool already painted into
+	// that cell, so the block stays visible against the tool's own palette
+	// instead of keepkit's — which is the only way one style can mark a cursor
+	// on a screen keepkit does not control.
+	TermCursor lipgloss.Style
+
 	// The API-usage gauge. GaugeTrack is Theme.SignalDim's only consumer: fill
 	// and track have to read as one bar, which no other pair of roles can do.
 	GaugeFill  lipgloss.Style
@@ -130,6 +138,7 @@ func NewStyles(t Theme) *Styles {
 			BorderForeground(t.Accent).
 			Padding(0, 1),
 		OverlayDim: fg(t.Dim),
+		TermCursor: lipgloss.NewStyle().Reverse(true),
 
 		GaugeFill:  fg(t.Signal),
 		GaugeTrack: fg(t.SignalDim),
diff --git a/internal/updater/updater.go b/internal/updater/updater.go
index 8f55ac1..20425ec 100644
--- a/internal/updater/updater.go
+++ b/internal/updater/updater.go
@@ -90,7 +90,7 @@ type managerDirs struct {
 }
 
 // resolveManagerDirs is the thin OS-facing wrapper over managerDirsFrom
-// (the launcher.planFor idiom: pure core over an injected env lookup), plus the
+// (the configdir.baseFor idiom: pure core over an injected env lookup), plus the
 // one thing the pure core cannot do — expanding symlinks in the resolved roots.
 //
 // That expansion is load-bearing, not hygiene. Detect compares these roots