feat(top): TUI papercuts — seven interactive-mode frictions removed

Sorting now scrolls the column window to the sort column; an active filter is
announced permanently in the cmdline instead of only by a header marker that
can itself scroll off-screen; `\` clears every filter of the current screen;
the refresh interval is shown in the header; the verbose panels no longer waste
a screen row and highlight their values like the base rows always did; and
dialog prompts stay aligned with their input field in both display modes.

Closes a live pre-existing crash on the way: the 93-character state-mask prompt
put the dialog's input field past the right edge on an 80-column terminal,
gocui rejected the coordinates and the whole UI was torn down and rebuilt.
Also removes a pre-existing race where the cmdline clear timer touched a view
buffer from a bare goroutine.

Pause on Space was planned for this batch and split into its own feature:
sorting runs in the collector goroutine, so a paused screen cannot re-sort, and
returning from the pager rebuilds the UI with no frame left to repaint.

Verified on a live terminal: all seven behaviours captured on a remote stand
across three geometries, with a second binary built from master to separate
regressions from long-standing behaviour. Acceptance: 27/27 user-spec and 11/11
tech-spec criteria.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Alexey Lesovsky

.claude/skills/project-knowledge/architecture.md

@@ -102,7 +102,8 @@ dedicated `view.View.Verbose bool` (rides `viewCh` to the collector) mirrored in
   into the four `SetView` calls. Compact (and the height-guard fallback) reproduces the historical
   literals (`4/4/3/5/4`) byte-identically; verbose grows the panels asymmetrically (`sysstat` +3,
   `pgstat` +5) and shifts `cmdline`/`dbstat` down. The height-guard refuses to expand when the band +
-  cmdline + table header + ≥1 data row would not fit (threshold `maxY ≥ 13`), falling back to compact +
+  cmdline + table header + ≥1 data row would not fit (threshold `maxY ≥ 12` since 015-feat-tui-papercuts,
+  which tied the verbose table top to the cmdline the way the compact branch always did), falling back to compact +
   a one-shot cmdline hint. Pure-function, gocui-free, table-tested — the [009] `visibleColumns` precedent.
 - **All-three system collection branch (`internal/stat/stat.go:262`, `:401`).** When `view.Verbose` is
   set, `Collector.Update` runs a verbose-gated branch placed **after** the existing mutually-exclusive

.claude/skills/project-knowledge/patterns.md

@@ -184,11 +184,21 @@ by driving pgcenter inside tmux on a dedicated stand over ssh. The regimen below
 from the sibling book project (`../postgresql-destruction-recovery-guide-book`, "Операционные
 правила стенда"), where it is already proven for capturing pgcenter screens.
 
-**Stand.** A dedicated VM reachable over ssh, with PostgreSQL and tmux installed. The address and
-credentials are **not stored in this repository, and not worth recording anywhere else either** —
-stands are ephemeral, with a TTL measured in hours, so a saved address is stale by the next
-session. Ask the author at the start of every run, and never assume the previous run's state
-survived.
+**Stand.** A dedicated VM reachable over ssh. The address and credentials are **not stored in this
+repository, and not worth recording anywhere else either** — stands are ephemeral, with a TTL
+measured in hours, so a saved address is stale by the next session. Ask the author at the start of
+every run, and never assume the previous run's state survived.
+
+**Take an inventory before planning the run — the stand is not a fixed image.** Observed so far:
+Ubuntu 24.04 with tmux preinstalled, and Debian 12 with no tmux, no Go, and a Postgres Pro build
+whose `shared_preload_libraries` lacks `pg_stat_statements` (so the statements screens are simply
+unavailable). Check for `tmux`, the PostgreSQL flavour and the loaded libraries first; installing
+tmux is fine with the passwordless sudo these stands carry, but a missing extension may mean a
+screen cannot be exercised at all — decide that before writing the plan, not mid-run.
+
+**Bring a second binary built from `master`.** Running the same scenario on both is what separates a
+regression introduced by the feature from behaviour that was always broken. In 015 this reclassified
+three of five findings as pre-existing; without it they would have been filed against the feature.
 
 **The binary under test must be shipped explicitly.** The stand carries a pgcenter built from
 `master`; a feature branch's behaviour is not there until you copy the freshly built
@@ -217,18 +227,42 @@ Stripping ANSI from an `-e` capture for diffing: `sed 's/\x1b\[[0-9;]*m//g'`.
 **Leave the stand as you found it.** Server GUCs changed for an experiment are reset afterwards
 and the reset is verified with `SHOW`; the tmux session is killed at the end of the run.
 
-## printCmdline() — Mutual Exclusion
-
-`printCmdline(g, msg)` calls `g.Update` followed by `v.Clear`. If it is called twice in the
-same view-switch handler the second call immediately overwrites the first render. When a
-handler needs to show either a warning or a normal message, these two cases must be mutually
-exclusive — use an `if/else` branch, not two sequential calls. Calling `printCmdline(warning)`
-and then `printCmdline(v.Msg)` in the same code path will always discard the warning before
-the user can read it.
-
-When multiple independent availability probes can fail (e.g., IO + delay accounting in
-`switchViewToProcPidStat`), use a 4-branch `switch` covering all combinations, with a combined
-message for the case where both are unavailable — still exactly one `printCmdline` call per path.
+## The cmdline: one composer, transient messages, persistent state (015-feat-tui-papercuts)
+
+Everything written to the cmdline goes through **one composition point**. `printCmdline` keeps its
+historical signature and its 2-second clear timer; `printCmdlinePersist` is the same writer without
+the timer, for text that must survive until dismissed (the dialog prompt). Both delegate to a shared
+core that builds the line as *reserved state prefix* + *transient message* and clamps it to the
+terminal width in **runes**.
+
+- **Persistent state is a token, not a message.** `cmdlineToken` carries renderings ordered
+  longest-to-shortest; the composer degrades the rightmost token through its variants only when the
+  line does not fit, then drops tokens from the right. A token with exactly one variant never
+  shrinks — that is how a "must always be visible" indicator is expressed in data rather than in a
+  special case. Adding a second token requires no change to the composer.
+- **Read state only on the gocui goroutine.** The composer reads its state from a package-level
+  ambient `*config`, written once by a named setter from `RunMain` — deliberately not from `newApp`,
+  which unit tests call repeatedly and would leave a stale pointer behind. Dereference only inside
+  `g.Update` closures or key handlers. This is the package's only package-level mutable var; it
+  exists so the 44 existing call sites keep their signature.
+- **The clear timer renders, it does not erase.** It re-renders the prefix-only line inside its own
+  `g.Update` (removing an older race where a bare goroutine touched the view buffer) and is gated on
+  an atomic UI-generation counter **captured into a local before the goroutine is spawned** — read
+  inside, it would compare a value to itself and do nothing. `mainLoop` rebuilds the `Gui` without
+  closing it on every pager/editor return, so an ungated timer pins the abandoned one.
+- **Sanitise anything that came from the server.** Column names reach the indicator, and
+  `gocui.View.Clear()` resets the line buffer but *not* the escape-interpreter state — an
+  unterminated sequence on this low-frequency surface survives the whole session, unlike the stats
+  table, which repaints every tick amid correct sequences and self-heals.
+
+**Still true, and now the sharper hazard:** two writes in one code path still leave only the last
+one visible, because `g.Update` enqueues each from its own goroutine and the order is not
+guaranteed. Keep exactly one call per path — an `if/else`, or the 4-branch `switch` that
+`switchViewToProcPidStat` uses for its two independent probes. Two known paths violate this and
+predate the composer: `dialogFinish` writes an empty line before its result, so **no message shown
+after a dialog closes is ever visible** (the action still happens), and the verbose height-guard
+hint loses to `collecting...` on the same keypress. Both are registered tech debt — do not treat a
+"missing" cmdline message as a new bug before checking whether it is one of these.
 
 ## Adding a Hybrid View (SQL + procfs enrichment)
 

.gitignore

@@ -1,2 +1,3 @@
 # Build artifacts
 /bin/
+.test_coverage.txt

docs/decisions-log.md

@@ -952,3 +952,82 @@ without touching five files.
 **Alternatives considered:** branching at 14 (rejected — matches fixtures, not reality); adding a PG 13
 cluster (rejected — disproportionate, PG 13 is past EOL); renaming the constants (rejected — rested on
 a convention that does not exist).
+
+---
+
+## [015-feat-tui-papercuts] One cmdline composer fed by an ambient config
+
+**Date:** 2026-08-02
+**Feature:** 015-feat-tui-papercuts
+**Status:** Accepted
+
+**Context:** A persistent filter indicator has to appear on every cmdline write, but the writers are
+reached from 19 functions across 11 files, four of which (`showPgConfig`, `editPgConfig`,
+`showPgLog`, `resetStat`) have no `config` in scope at all. There are 44 existing call sites.
+
+**Decision:** A package-level `cmdlineCfg *config` in `top/`, written exactly once by
+`setCmdlineConfig` called from `RunMain`, dereferenced only inside `g.Update` closures or key
+handlers. All existing call sites keep their signature.
+
+**Rationale:** Threading the config explicitly costs 44 call-site edits plus four helper signatures
+and their keybinding registrations — a large mechanical diff across files that three waves were
+editing concurrently, for a dependency that is genuinely process-global in a single-instance TUI.
+Setting it from `RunMain` rather than `newApp` matters: `newApp` runs in unit tests, and an ambient
+set there would leave one test's config visible to every test that follows. That is safe today only
+because nothing in `top/` calls `t.Parallel()` — an undocumented invariant not worth depending on.
+
+**Alternatives considered:** Explicit threading (rejected on diff size and cross-wave merge risk,
+not on principle). `sync.Once` (guards a second write that cannot happen). Note this is the first
+package-level mutable var in `top/`; `internal/version` and `internal/stat/procpidstat.go` have
+package vars, but they hold immutable data.
+
+---
+
+## [015-feat-tui-papercuts] Reserve the input field's room before composing the dialog prompt
+
+**Date:** 2026-08-02
+**Feature:** 015-feat-tui-papercuts
+**Status:** Accepted
+
+**Context:** The dialog input field was positioned from the raw prompt length, assuming an empty
+cmdline. With a persistent indicator that assumption breaks. It was already broken without one: the
+93-character state-mask prompt puts the field's left edge right of its right edge on an 80-column
+terminal, `gocui.SetView` rejects the coordinates, and the error propagates to `MainLoop`, which
+tears down and rebuilds the entire UI. Reproducible at startup on `master`.
+
+**Decision:** Compose the prompt against a width budget that already excludes the field's reserved
+minimum, so an overlong prompt is **truncated** (with an ellipsis spent from the same budget) rather
+than overlaid by the field. The x0 clamp remains as a backstop that provably never bites.
+
+**Rationale:** Clamping alone keeps the dialog on screen but slides the field over the prompt's
+tail, contradicting the alignment requirement. Truncating satisfies both at once. The prefix is
+rendered at the same width the writer uses, so the measured line and the drawn line are the same
+string by construction rather than by coincidence — the one place where two independently correct
+pieces could silently disagree.
+
+**Alternatives considered:** Clamp and accept the overlay (contradicts an approved criterion);
+shorten the prompt strings themselves (changes user-visible text unrelated to the feature).
+
+---
+
+## [015-feat-tui-papercuts] Probe the existing window function instead of recomputing the offset
+
+**Date:** 2026-08-02
+**Feature:** 015-feat-tui-papercuts
+**Status:** Accepted
+
+**Context:** Auto-scrolling to the sort column needs the smallest offset at which that column is
+visible. The admission rule lives in `visibleColumns`, whose marker-reservation arithmetic ADR
+[009] records as error-prone — it shipped a bug invisible to unit tests.
+
+**Decision:** Walk candidate offsets and ask `visibleColumns` whether the column is inside the
+returned window; take the first that admits it. Where no offset admits it at all — a terminal
+narrower than the frozen column — leave the offset untouched.
+
+**Rationale:** Any independent computation would be a second implementation of the same subtle rule.
+The function is pure and the column count is bounded by the widest screen. The research sketch
+returned the last index in the no-fit case, which would jerk the window to an arbitrary edge; the
+acceptance criterion overrode it.
+
+**Alternatives considered:** Direct backward-walk arithmetic (a second source of truth for the
+marker rule).

docs/features-catalog.md

@@ -185,8 +185,10 @@ hidden to the left/right. Closes issue #14, the most-requested item, open since
 - Switch to another screen (including the per-process screen via `Shift+S`): the new screen
   opens unscrolled (offset reset to 0). The offset persists across auto-refresh ticks within one screen.
 - On a wide terminal where everything fits, `[`/`]` are no-ops and no markers are shown.
-- Sorting (`←`/`→`) and scrolling (`[`/`]`) are independent — the sort column may sit outside the
-  visible window, which is expected (no auto-scroll to the sort column).
+- Sorting (`←`/`→`) and scrolling (`[`/`]`) are independent in the sense that a manual scroll is
+  never undone by a refresh. **Superseded in part by [015-feat-tui-papercuts]:** changing the sort
+  column now scrolls the window to bring that column into view, so "the sort column may sit outside
+  the visible window" is no longer expected behaviour.
 
 **Limitations:**
 - **Main stats table only.** The side extra-panels (iostat / netdev / fsstats / logtail) do not
@@ -336,3 +338,47 @@ is blank for some rows now places those rows last in both directions instead of
 zero. Most visible on [005-feat-replication-slots], whose default sort key is sparse.
 [009-feat-horizontal-scroll] is what makes the wider screen usable. The `report` replay path gained
 correct handling of a recorded version change, which matters for archives spanning a major upgrade.
+
+---
+
+### [015-feat-tui-papercuts] Interactive-mode Papercuts
+
+**What it does:** Removes seven frictions that made `pgcenter top` slower to drive than it should
+be. Sorting now scrolls the column window to whatever column you sorted by; an active filter is
+announced permanently in the command line instead of only by a `*` on a header that may itself be
+off-screen; `\` clears every filter of the current screen at once; the refresh interval is shown in
+the header; the verbose panels stop wasting a screen row and highlight their values the way the
+normal rows always did; and dialog prompts line up with their input field in both display modes.
+
+**Key scenarios:**
+- On a narrow terminal, press `→` past the right edge: the window follows the sort column and brings
+  it into view, highlight included. Scroll away with `[`/`]` afterwards and it stays where you put
+  it — the window is only moved when the sort column changes.
+- Set a filter, then scroll its column off-screen or switch to another screen and back: the command
+  line keeps showing `[F:datname]`, so a filtered view can no longer be mistaken for the whole
+  picture. With several filters it lists them all: `[F:datname,usename]`.
+- Press `\` to drop every filter on the screen at once, instead of hunting down each column that set
+  one. The message says how many were removed, or says plainly that there were none.
+- Press `v`: the verbose panels expand with no blank gap above the table, values are highlighted,
+  and degraded `n/a` fields stay plain so a missing signal still looks different from a real number.
+- Open any dialog with a filter active: the prompt and the input field stay aligned, in both compact
+  and verbose mode. An overlong prompt is cut with an ellipsis rather than covered by the field.
+
+**Limitations:**
+- Pause on `Space` was planned for this batch and **split into its own feature** ([016] on the
+  0.12.0 roadmap): sorting runs in the collector goroutine, so a paused screen cannot re-sort, and
+  returning from the pager rebuilds the UI with no frame to repaint. Both need product decisions of
+  their own.
+- The auto-scroll fires only when the sort column changes. Entering a screen whose default sort
+  column sits off-screen leaves it there until the first arrow press — reachable only on terminals
+  narrower than about 80 columns.
+- Filters still combine as OR, not AND. The indicator makes that visible for the first time but does
+  not change it.
+- Messages printed after a dialog closes remain invisible (pre-existing, registered as tech debt),
+  so one of the three filter messages can only be seen in tests, not on screen.
+- The verbose threshold moved from 13 terminal rows to 12 — verbose now engages one row earlier.
+
+**Touches:** [009-feat-horizontal-scroll] — supersedes its "no auto-scroll to the sort column"
+limitation and reuses its column-window function. [010-feat-overview-dashboard] — fixes two defects
+in the verbose panels it introduced. The command-line composer added here is the foundation the
+deferred pause feature builds on.