feat(top): scaffold + activity view (S1)

[NikolayS]

Summary

S1 of the /top initiative — see .samo/spec/top/SPEC.md (v0.2) for the full eight-sprint roadmap. This PR ships the MVP: a live ratatui-powered Postgres monitor with a single Activity view over pg_stat_activity. Inspired by pg_top and pgcenter top; module layout mirrors /ash so reviewers can pattern-match.

• New /top interactive TUI (alt-screen + mouse capture + raw-mode RAII guard).
• New /top --once headless mode — one-shot text snapshot for CI / scripting / evidence.
• Header: db, user, PG version, primary/standby, uptime, "as of T…", connection LED, session counts (active / idle-in-tx / wait / total), stale-tick badge.
• Activity view: pid · user · db · app · client · backend · state · wait · qtime · xtime · query. Wide layout ≥120 cols; narrow layout drops app/client/backend.
• 35 new unit + snapshot tests (state machine, SQL invariants, renderer via ratatui::TestBackend, theme, args parser).
• Adjacent fix: exec_command now dispatches /-extension commands. Previously only \-metas were recognized in -c / stdin mode, so any rpg-extension command (/top, /dba, /ash, …) passed via -c fell through to SQL execution and raised a syntax error. Five-line addition mirroring the existing \ branch and the interactive REPL.

Out of scope (deferred to later sprints)

View switching · sort/filter · drill-down (Q/E/A/L/W) · blocking tree · sparklines · kill actions · pause/rewind · JSON output · AI hand-offs (Shift-X eXplain selected, Shift-I Info on whole view) · rpg top clap subcommand alias · system-stats (cpu/mem/io/net) reader. All tracked in .samo/spec/top/SPEC.md §7.

Red/green TDD

Manual integration testing against PG 17.9 caught one bug that unit tests didn't cover: extract(epoch from …) returns Postgres numeric, which tokio-postgres cannot deserialize directly into f64. The --once snapshot failed with error deserializing column 9. Fix:

1. Red — added elapsed_time_columns_cast_to_float8 to src/top/sql.rs asserting the SQL casts ::float8. Test failed.
2. Green — added ::float8 to the two extract(...) expressions for qtime_secs and xtime_secs. Test passed.

Test plan

• cargo fmt --check — clean
• RUSTFLAGS="-D warnings" cargo clippy --all-targets --all-features -- -D warnings — clean (matches CI)
• cargo test — 2101 passed; 0 failed (35 new tests in src/top/)
• Manual: rpg --command "/top --once" against PG 17.9 with three pg_sleep(60) victims (see evidence below)
• CI green (PG14–PG18 matrix)
• REV review

Manual-test evidence

Local PG 17.9 (Debian) on port 55433. Three short-lived victim sessions running pg_sleep(60) (one wrapped in BEGIN; … COMMIT;):

===Backends===
  pid  | state  | wait_event_type | wait_event |                   left
-------+--------+-----------------+------------+------------------------------------------
 32166 | active | Timeout         | PgSleep    | select pg_sleep(60)
 32167 | active | Timeout         | PgSleep    | begin; select pg_sleep(60); commit;
 32168 | active | Timeout         | PgSleep    | select pg_sleep(60)
 32120 | idle   | Client          | ClientRead | copy "pgss_queryid_queries" ( "time", "d
(4 rows)

rpg --command "/top --once" output (exit 0):

Click to expand — 130×30 plain-text snapshot

┌ rpg /top ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│db postgres  user postgres  pg 17.9  primary  uptime 7d14h  as of T177                 ● active 3  idle-in-tx 0  wait 3  total 9│
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 Activity
 Activity (9 rows)────────────────────────────────────────────────────────────────────────────────────────────────────────────────
pid     user       db          app         client      backend    state    wait     qtime   xtime   query
32166   postgres   postgres    psql        172.18.0.1/ client     active   Timeout. 2.0s    2.0s    select pg_sleep(60)
32168   postgres   postgres    psql        172.18.0.1/ client     active   Timeout. 2.0s    2.0s    select pg_sleep(60)
32167   postgres   postgres    psql        172.18.0.1/ client     active   Timeout. 2.0s    2.0s    begin; select pg_sleep(60); co
32120   pgwatch    measurement pgwatch     172.18.0.5/ client     idle     Client.C 14.4s   -       copy "pgss_queryid_queries" (
68                                                     checkpoin…          Activity -       -
69                                                     bg writer           Activity -       -
71                                                     walwriter           Activity -       -
72                                                     autovacuu…          Activity -       -
73      postgres                                       logical r…          Activity -       -


──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 q quit  ↑↓ move  Home/End first/last  PgUp/PgDn page

Verified:

• ✅ Header shows db, user, pg 17.9, primary, uptime, as of T…, connection LED, session counts.
• ✅ Activity tab + (9 rows) caption.
• ✅ Active backends sorted first, then by qtime desc (wait and xtime columns populated).
• ✅ Background workers (checkpointer, bg writer, walwriter, autovacuum launcher, logical replication launcher) shown via backend_type with empty client info — correct.
• ✅ Footer keymap hint visible.
• ✅ Exit code 0.

The interactive run was also smoke-tested locally: /top enters the alt-screen, refreshes every 1 s, responds to ↑/↓/PgUp/PgDn/Home/End, and exits cleanly on q / Esc / Ctrl-C (TerminalGuard restores the parent terminal even if the loop panics).

Refs

• Spec: .samo/spec/top/SPEC.md v0.2
• Decisions log: .samo/spec/top/decisions.md

🤖 Generated with Claude Code

[NikolayS]

REV Code Review Report

• PR: feat(top): scaffold + activity view (S1) #837 — feat(top): scaffold + activity view (S1)
• Author: @NikolayS
• AI-Assisted: yes
• CI: ✅ green (Lint, MSRV, Test, PG14–18 integration, regress, connection, coverage, 6 build targets, CodeQL — 26/26 passing)
• REV ignored: SOC2 (per CLAUDE.md project policy)

---

BLOCKING ISSUES (5)

HIGH src/top/sampler.rs — No integration test against a real PostgreSQL connection

The two sampler tests only match enum variants of TickResult; tick(), query_summary(), and query_activity() are never exercised against a DB. This is the only path that would have caught the extract(epoch …)::float8 regression I fixed during manual testing — the unit test only checks string content, not actual deserialization. CI matrix PG14–18 already exists.
Fix: Add tests/top_smoke.rs gated by --features integration that spawns rpg via CARGO_BIN_EXE_rpg and runs --command "/top --once" against the test cluster, asserting exit code 0 and key content patterns. (confidence 9/10)

HIGH src/repl/mod.rs:1853 — New /-dispatch branch in exec_command has no test

A regression here would silently break the batch/CI use case from US-11 (rpg --command "/top --once").
Fix: Add a test that verifies /-prefixed input does not fall through to execute_query. (confidence 8/10)

HIGH src/top/renderer.rs — Connection-LED color flip is never asserted

buffer_to_string() discards Style; the stale-badge test only checks the "stale 2" text, not that the ● is rendered in status_stale color. A bug that swaps status_ok/status_stale would pass all tests.
Fix: Inspect buf[(x, y)].style().fg for the ● cell and assert it matches the expected theme color. (confidence 8/10)

MEDIUM src/top/sql.rs — Dangling intra-doc link to deleted SUPPORTED_PG_VERSION_HINT

The module-level //! comment references [SUPPORTED_PG_VERSION_HINT] but that constant was removed during cleanup. Will produce a broken rustdoc reference (and clippy may flag it).
Fix: Remove the dangling reference from the module doc comment. (confidence 8/10)

MEDIUM .samo/spec/top/SPEC.md:198 — Spec signature mismatch

§3.1 documents run_top as taking Arc<Mutex<Client>> but the actual S1 implementation uses &Client (matching /ash's pattern). Misleads reviewers auditing the connection-sharing model.
Fix: Update the spec to match the S1 signature; mark the Arc<Mutex<…>> design as a future-sprint concern. (confidence 8/10)

---

POTENTIAL ISSUES (5)

MEDIUM src/repl/mod.rs:1853 — New /-branch always returns 0 (confidence 7/10)

let _ = dispatch_ai_command(...).await; return 0; — discards both unmatched commands (/typo) and failed /top --once runs. Both exit with status 0, breaking US-11's CI-scripting story.
Fix: Distinguish matched/unmatched/errored in dispatch_ai_command (or fall back to execute_query's error reporting on None).

MEDIUM src/top/sampler.rs — reset_timeout destroys user's prior statement_timeout (confidence 6/10)

Hard-codes set statement_timeout = 0 regardless of what the user had configured. After /top exits, the user's session-level setting is gone. Mirrors the same pattern in /ash/sampler.rs (so consistency is acceptable), but worth tracking.

MEDIUM Terminal-escape injection via unsanitized pg_stat_activity fields (confidence 7/10)

application_name and query are freely settable by any connected Postgres client (e.g. SET application_name = E'\x1b[2J\x1b[31mPWNED'). They flow into Span::raw cells and, in --once mode, are written byte-for-byte to stdout. squash_query only strips \n/\r/\t; nothing filters \x1b/\x07/etc. A low-privileged Postgres client can inject ANSI escapes that another DBA's terminal will execute.
Fix: Add a control-char scrubber applied to all pg_stat_activity strings flowing into Span::raw/the --once writer. Add a regression test feeding "\x1b[2J" into a fixture row.

MEDIUM .samo/spec/top/SPEC.md + architecture.json — Stale procfs/system-stats references (confidence 7/10)

Both the ASCII diagram and architecture.json still mention procfs/system stats, which §4.10 + decisions.md + the v0.2 changelog explicitly say are out of scope for v1. Future readers following the diagram will look for procfs code that does not (and will not) exist in S1.
Fix: Remove the procfs node/edge from the diagram and JSON; SPEC.md text is already correct.

MEDIUM src/top/sql.rs ACTIVITY_SQL doc comment — misleading PG14 wording (confidence 7/10)

"Newer columns (e.g. query_id from PG14, leader_pid) are excluded to keep S1 minimal." query_id was added in PG14 (the project's minimum), and leader_pid was added in PG13. Reads as if these are version-gated, but they are not.
Fix: Reword to "Columns available in PG14 but excluded to keep S1 minimal."

---

NON-BLOCKING (15)

LOW src/top/renderer.rs — as of T<unix-epoch> is unreadable (confidence 5/10) — format with chrono as HH:MM:SS.
LOW src/top/mod.rs — sampler is awaited inline; a hostile lock can delay q/Esc for up to SAMPLE_TIMEOUT_MS (5 s). (confidence 4/10) — spec §3.2 plans a separate task; track as known S1 limitation.
LOW src/top/theme.rs — Theme fields and default_theme() lack doc comments. (confidence 5–6/10)
LOW src/top/views/activity.rs — pub const SELECTED_HIGHLIGHT is pub + #[allow(dead_code)]; should be pub(crate) until S6 consumes it. (confidence 5/10)
LOW docs/COMMANDS.md — /top entry doesn't show --once. (confidence 5/10)
LOW src/top/state.rs — ServerSummary fields (waiting, idle_in_tx, etc.) lack doc comments explaining semantics. (confidence 4/10)
LOW src/top/views/activity.rs — state_color, wait_color, qtime_warn_color, short_backend_type and format_secs negative-input branch untested. (confidence 5–7/10)
LOW src/top/mod.rs — page_size() untested. (confidence 6/10)
LOW src/top/sql.rs — SUMMARY_SQL missing self-exclusion regression test (parallels existing activity_sql_excludes_self_backend). (confidence 6/10)
LOW src/top/sampler.rs — is_query_canceled untested. (confidence 5/10)
LOW src/top/renderer.rs — Spec promises insta snapshots; impl uses hand-rolled buffer_to_string() + substring matches. (confidence 5/10)
INFO .samo/spec/top/SPEC.md:314 — uses MB/s/MiB/s mismatch; CLAUDE.md mandates MiB/s. (confidence 7/10)
INFO src/top/sql.rs — and mid-line in case when (CLAUDE.md SQL style says AND/OR at line start). (confidence 5/10)
INFO Spec mentions SET LOCAL statement_timeout but impl uses session-scoped SET (consistent with /ash). (confidence 4/10)

---

Summary

Area	Findings	Potential	Filtered
CI/Pipeline	0	0	0
Security	0	1	0
Bugs	0	2	2
Tests	3	0	6
Guidelines	0	0	4
Docs	2	2	5
Metadata	0	0	0

• Findings: high-confidence (8–10/10) — blocking
• Potential: medium-confidence (4–7/10) — review manually
• Filtered: lower-confidence — surfaced as NON-BLOCKING

---

Result: 5 BLOCKING items. Will fix and re-CI/re-REV before merge per project workflow (CLAUDE.md PR workflow + memory: never merge without explicit user approval).

REV-assisted review (parallel AI analysis: security, bugs, tests, guidelines, docs).

[NikolayS]

REV blockers addressed — re-CI green

Commit f0b1327 resolves all 5 BLOCKING and 3 high-value POTENTIAL findings from the previous REV report, via red/green TDD (test committed before fix in every case).

Finding	Resolution
T1 — no integration test against real PG	New tests/top_smoke.rs (gated by --features integration); 3 tests covering idle render, backend-count caption, and unknown-/-command routing. Includes explicit guard against the error deserializing column 9 regression. Ran locally against PG 17.9 in 1.38 s.
T2 — no test for /-dispatch in exec_command	Extracted is_slash_extension_command predicate; 2 unit tests covering recognition (with leading whitespace) and rejection (SQL, \-meta, mid-statement /). Integration test (T1, third case) covers the end-to-end behavior.
T3 — connection-LED color flip never asserted	New connection_led_color_reflects_freshness test inspects the ● cell's style().fg and asserts it flips between status_ok and status_stale based on stale_ticks.
D1 — dangling intra-doc link to SUPPORTED_PG_VERSION_HINT	Removed the stale reference; rewrote the module-level comment to point at the future server-version-aware branching strategy.
D2 — SPEC.md sig mismatch (Arc<Mutex<Client>> vs &Client)	§3.1 + ASCII diagram updated to S1's actual signature; the Arc<Mutex<…>> design is documented as a future-sprint concern.
S1 — terminal-escape injection via pg_stat_activity strings (POTENTIAL/7)	New scrub_terminal_unsafe helper strips every C0/C1 control byte (ESC, BEL, BS, DEL, …) — whitespace controls collapse to a space, others drop. Applied at truncate, squash_query, truncate_err, and every Span::raw over user-controlled summary fields. End-to-end renderer test scans the entire cell buffer for ESC/BEL bytes given a hostile fixture row.
B3 — as of T1700000000 ugly format (POTENTIAL/5)	New format_clock_utc helper formats the snapshot ts as HH:MM:SS UTC via modular arithmetic (no chrono dep). Test includes the anchor case 1_700_000_000 → 22:13:20 and pre-epoch fallback.
D3, D8 — stale procfs in spec; --once missing from docs	Removed procfs node and edge from architecture.json + ASCII diagram; reworded query_id from PG14; docs/COMMANDS.md /top entry now shows [--once]; spec layout uses MiB/s.

Deferred (POTENTIAL, non-blocking)

• B1 — exec_command's /-branch always returns 0. Distinguishing matched-vs-unmatched-vs-errored needs a richer return type from dispatch_ai_command; it's a wider refactor that affects all /-commands and is best done as a follow-up. Documented inline as a known limitation referencing this review.

Test count delta

	Before	After
Unit tests	2101	2110
Integration tests (--features integration)	0 for /top	3

All 2110 unit tests pass; all 3 integration tests pass against local PG 17.9 (and against the CI matrix PG14–18, see below).

CI on f0b1327

✅ 26 / 26 green — Lint, MSRV (1.88), Test, Integration PG14/15/16/17/18, PostgreSQL Regress, Connection Tests, Compatibility, Coverage, all 6 build targets, CodeQL.

Manual evidence (re-captured against PG 17.9 with sanitizer + clock fix)

┌ rpg /top ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│db postgres  user postgres  pg 17.9  primary  uptime 7d14h  @ 06:55:43 UTC                  ● active 3  idle-in-tx 0  wait 3  total 9│
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 Activity
 Activity (9 rows)─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
pid     user       db          app         client      backend    state    wait     qtime   xtime   query
…

Ready for merge approval whenever you'd like — flagging here that I will not merge until you explicitly say so (per memory).

[NikolayS]

Demo gif

Recorded with VHS, following the
existing demos/ pattern (top-workload.sh spawns mixed background
backends; top-demo.tape drives rpg). Files: demos/top-demo.{tape,gif}

• demos/top-workload.sh. Re-render with vhs demos/top-demo.tape.

The recording shows the interactive /top TUI live-updating against
~20 mixed backends (active queries, idle-in-transaction, advisory-lock
waits, short bursts), cursor navigation through rows, and the headless
/top --once snapshot at the end.

View source

[NikolayS]

Updated demo + smart functions clarification

Pacing fix. Pushed 312bda2 — every typed command now has a 1.5 s pause before Enter, so a viewer can read what's about to run.

(GitHub caches the GIF; the ?v=2 param forces a fresh fetch.)

"Where are smart functions demonstrated?"

Honest answer: this PR is S1 of 8 per .samo/spec/top/SPEC.md §7 — intentionally minimal. The smart features visible in the demo as it stands are passive (no interactive trigger):

• Color-coded threshold logic — qtime long-runners turn yellow at >1 s, red at >30 s; idle in transaction rows are yellow; Lock waits are red, IO blue, LWLock light yellow.
• Live header clock — @ HH:MM:SS UTC (the cosmetic fix from REV B3).
• Connection LED — ● is green when the sample is fresh, yellow when stale (would flip on a hung sampler tick — hard to demo without a contrived block).
• Responsive layout — wide ≥120 cols shows app/client/backend; narrow drops them. The recording is wide; resizing is the toggle.
• Cursor stickiness — selection clamps cleanly when row count changes between ticks.
• /top --once — the headless snapshot at the end is the same renderer dumped to stdout (CI/scripting).
• ANSI-escape sanitizer — invisible by design (a hostile application_name = E'\x1b[2J…' would otherwise corrupt the terminal).

The genuinely interactive smart features — fuzzy filter (/), column sort (o/O), drill-down overlay (Q/E/A/L/W + Shift-X AI eXplain selection / Shift-I AI Info on whole view), blocking tree, sparklines, kill actions, pause/rewind — are explicit S2–S7 sprints. They are not in this PR; the spec calls them out as deferred so S1 can land cleanly.

If you'd like me to pull any specific S2–S7 item forward into this PR (or cut a follow-up PR for, say, Shift-I AI overview as a tangible "smart" hook), say which and I'll start a fresh red/green TDD cycle on it.

[NikolayS]

Round 3 — feedback applied

Pushed 15b186a. All requests from the previous round folded in.

Request	Resolution
Wait Type and Event separated by :	format_wait_label now joins them with : (e.g. IO:DataFileRead, Lock:advisory, Timeout:PgSleep). pg_ash convention.
Use pg_ash color scheme	All 12 pg_ash hex codes wired into Theme (24-bit RGB when COLORTERM=truecolor, named-color fallback otherwise). New wait_color_for_row helper routes idle-in-tx → IdleTx, no wait_event_type → CPU* green, then per-wait_event_type.
Idle and idle-in-tx sessions in the demo	top-workload.sh now uses stdin-fed psql to keep three persistent backends alive: one idle (Client:ClientRead), one plain idle in transaction, one idle in transaction holding an advisory xact lock and a temp table (so the locks column shows interesting numbers).
Configurable refresh rate, demo at 0.5 s	New --refresh <n> / -s <n> CLI flag (0.1–60 s range) and interactive s key that opens a footer prompt: delay (secs): _ [Enter to apply, Esc to cancel]. App reads refresh_secs each tick so a change takes effect immediately. Default is 1 s. The demo presses s, types 0.5, watches the faster refresh, and continues.
Locks-acquired column	New locks_held column from a LEFT JOIN pg_locks where granted per pid. Renders - when zero, the count otherwise. Visible in both default and extended layouts.
app/client/backend extended-only	Default columns now: pid · user · db · state · wait · qtime · xtime · locks · query (fits 80 cols). Pressing e toggles extended mode, which adds app · client · backend in front of state (needs ≥120 cols). The title bar gains a [extended] badge. The demo shows the toggle.
Sticky table header	Switched to Table::render_stateful_widget with TableState. The header row stays pinned while the body scrolls under it. The demo presses Down past the visible window, then PageDown, so you can see the body scrolling beneath a sticky header.
Richer header — what else from pgcenter / pg_top?	Header is now two inner lines, Postgres-level only (no OS metrics): total N/max_connections · longest-tx · longest-q · deadlocks · temp-files. All single-query fields — no rate calculation needed yet (TPS / WAL rate / replication lag would need a delta against the previous tick; tracked for the next sprint).
Horizontal scroll on the query column	Not in S1. Query stays truncated; full text + plan + locks live in the drill-down overlay (S4) per the spec. Right/Left arrows are unbound in S1 so they remain available for column-nav in S2.

Test counts

	Before	After
Unit tests in top::	41	64
Total unit tests	2110	2132
Integration tests (--features integration)	3	3

Local: clippy -D warnings clean, fmt clean, all 2132 unit tests pass, 3 integration tests pass against PG 17.9 (1.4 s).

Awaiting CI re-run on the new commit; will follow up if anything breaks.

[NikolayS]

Updated gif (post round-3 changes)

Same file, just re-pinning the link since the CI fix-loop comments pushed it down. The gif at feat/top-s1 HEAD already includes everything from the round-3 changes:

Visible in this recording:

• pg_ash 24-bit RGB palette — Lock red, LWLock pink, IO blue, Timeout orange, Activity purple, Client yellow, IdleTx light yellow, CPU* green
• Type:Event delimiter (e.g. Timeout:PgSleep, Lock:advisory, Client:ClientRead)
• 2-line header — db / user / pg / primary / uptime / @ HH:MM:SS UTC on row 1; ● active / idle-in-tx / wait / total/max / longest-tx / longest-q / deadlocks / temp-files on row 2
• locks column populated (advisory-locking idle-in-tx backend has 5+ locks)
• cursor scroll past the visible window with the table header staying pinned
• e toggles extended mode (app / client / backend columns appear, [extended] badge in the title bar) — visible roughly 22-26s in
• s opens the refresh-delay prompt; user types 0.5 and Enter — visible roughly 28-30s in, with noticeably faster refresh after
• /top --once headless snapshot at the end

PR head: 892f6d6. CI: ✅ 26/26.

[NikolayS]

Round 5 — wide-screen contrast, Space-refresh, help, batch mode, sort indicator, key overlay

Pushed d930532 (and the immediately-prior commit). Addresses the wide-screen screenshot + the four follow-up requests.

Request	Resolution
Wide-screen header looked broken (invisible labels, no borders)	theme.muted and theme.border bumped from DarkGray (invisible on many dark terminals) to a brighter gray pair (truecolor RGB + Color::Gray 256-color fallback). The ┌── rpg /top ──┐ border is now visible everywhere; labels readable.
Wide-screen sprawl — values scattered across blank space	Restored right-aligned cells: row 1 anchors @ HH:MM:SS UTC to the right edge; row 2 anchors ● (and stale N when it appears) to the right edge. Wide screens get visual structure instead of trailing blank cells.
Show which column is sorted, in which direction	Active column header is underlined and carries ▼ (desc) / ▲ (asc). Demo cycles > > > r < < to walk the indicator across columns and reverse direction.
Demo different orderings	Same — tape now drives the sort cycler so the recording shows the indicator moving through several columns.
Visualise key presses	Upper-right corner overlay: ⌨ <label> for 1.2 s after each press, then fades. ↑ ↓ ← → ↩ ⌫ Esc PgUp PgDn Home End get glyphs; chars render as themselves; Ctrl-X as C-x. Suppressed inside the prompt so each typed digit doesn't strobe.
Sticky table header	Switched body to Table::render_stateful_widget + TableState; header pinned, body scrolls under it. Demo presses Down past the visible window + PageDown to make the scrolling obvious.
Batch mode for tmux / file logging, with period + timestamp prefix	New --batch (or -b) loops a text snapshot to stdout until Ctrl-C; --refresh <n> sets the period (0.1–60 s, default 1 s); --ts-format <fmt> accepts a strftime subset (%Y %m %d %H %M %S %T %F %s %z %Z %%). Default = %Y-%m-%dT%H:%M:%SZ. Each block is preceded by ===== <ts> ===== so log scraping is trivial. Calendar arithmetic via Howard Hinnant's civil_from_days — no chrono dep.
Space → immediate refresh, like top	Pressing Space short-circuits the event-poll wait and triggers a sampler tick on the next loop iteration. Footer hint updated: Space refresh.
Document /top in help	/? now lists /top under AI commands (matching the /ash entry); docs/COMMANDS.md already enumerates the flag set.

Footer hints (default)

 q quit  ↑↓ move  Space refresh  </> sort  r reverse  e extended  s set delay

Quick batch-mode example

$ rpg --command "/top --batch --refresh 5 --ts-format '[%F %T UTC]'" > /tmp/top.log
[2026-05-08 19:13:34 UTC]
┌ rpg /top ─────────────────────────────────────────────────────…
…

Test counts

	Before	After
Unit tests in top::	64	83
Total unit tests	2132	2151
Integration tests (--features integration)	3	3

clippy -D warnings clean, fmt clean. CI re-running on d930532 — will follow up.

[NikolayS]

Round 6 — k/K cancel/terminate, ←→ sort, autovacuum/slots, parallel batch

Pushed 669d86a.

Request	Resolution
Left/Right arrows change sort column	Added alongside the existing < / >; r reverses direction (traditional top uses R; we accept lower-case r).
pg_cancel_backend / pg_terminate_backend with confirmation	k → cancel, K → terminate. Footer flips to a red-badged confirm: CANCEL pid 12345 (user@db, active 42s, ‹update accounts set …›)? [y/N]. Captures the selected row at keystroke time so a re-sort between the key and the y doesn't change the target. y/Y fires; n/N/Esc/anything else cancels. After firing, an OK / ERR badge in the footer reports the outcome for ~5 s. Pid ≤ 0 (background workers) is a no-op — the prompt won't even open.
Briefly represent autovacuum / slots / chkpt / bgwriter	Header gained a third line: longest-tx · longest-q · deadlocks · temp-files · av busy/max · slots Aphys/Tphys p · Alog/Tlog l. autovacuum reads pg_stat_activity.backend_type = 'autovacuum worker' against current_setting('autovacuum_max_workers'); slot counts come from pg_replication_slots partitioned by slot_type. Checkpointer / bgwriter rates need delta-against-previous-tick state; tracked for a follow-up since they're only meaningful as rates.
Interactive /top + parallel batch logging to file	Already supported — open two rpg sessions: one runs /top interactively, the other runs rpg ... --command "/top --batch --refresh 5 --ts-format '[%F %T UTC]'" > /tmp/top.log. Both connect to the same PG; tail -f /tmp/top.log in a third tmux pane mirrors what you see live. Documented in docs/COMMANDS.md.

Footer keymap (default)

 q quit  ↑↓ move  Space refresh  ←→ sort  r reverse  k/K cancel/term  e extended  s set delay

Vim-k removed

Vim users would naturally hit k to scroll up. With k now bound to pg_cancel_backend, that reflex would silently start cancelling backends. So I removed the vim-j/k cursor aliases and a regression test catches anyone re-adding them. ↑/↓ (arrows) and PgUp/PgDn are the canonical cursor keys now.

Test counts

	Before	After
Unit tests in top::	83	93
Total unit tests	2151	2161
Integration tests (--features integration)	3	3

clippy -D warnings clean, fmt clean. CI re-running on 669d86a.

[NikolayS]

Live demo gif (rolling — edited in place)

PR head: 3182ebc. Round-12b: smoother gif. The previous 2.9 MiB gifsicle output was dropping frames during the workload-heavy section (you nailed it — vhs's native gif quantizer over-merges identical frames and the busy renderer with churning psql backends triggers exactly that path). New pipeline runs vhs's mp4 output through ffmpeg's palette generator + bayer dither at 15 fps; size is 11 MiB but playback is smooth. Wrapped in demos/render-top.sh so future re-renders are reproducible. mp4 intermediate gitignored.

Round-12 (commit 63211d7) lands the REV blockers: kill confirm targets the sorted-slice row (was reading the unsorted SQL slice → could kill a different pid than highlighted), demos/top-workload.sh rewrapped through a run_psql helper that applies --no-psqlrc / PAGER=cat / long options per CLAUDE.md, and docs/COMMANDS.md now lists --show-keys plus PgUp/PgDn/Home/End. Two security POTENTIAL findings folded in: kill confirm and admin-message footer now run user-controllable strings through scrub_terminal_unsafe.

Figlet font from round-11 unchanged: src/top/keyfont.rs 3×5 grid; render_label walks each char of multi-char labels through the same glyph table so PGDN / ESC render at the same scale as ▲ / K.

Box style: bright Color::Yellow bg, bold black fg, lower-right corner. Opt-in via rpg --show-keys (global) or /top --show-keys (per-command).

Round summary

Round	Key change
6	doc-list lint fix, Activity no longer rendered twice
7	dedup body title, --show-keys opt-in, lower-right billboard
8	global rpg --show-keys flag, modifier prefixes (C-/M-/S-)
9	bright Color::Yellow, plain ASCII, 5-row box
10	hand-built 5×5 block-letter font for single-char labels
10b	tightened box around the 5×5 glyph
11	3×5 figlet font + render_label for multi-char labels
12	REV round-11 blockers: kill targets sorted row, shell-rule, doc gap, scrub kill confirm + admin message
12b	smoother gif via ffmpeg palette pipeline (this push)

(I'm editing this comment in place when the gif updates instead of stacking new comments.)

[NikolayS]

REV-assisted review (round 11) — 50baec6

CI: ✅ all green (27 checks). Reviewing the delta f0b1327..50baec6 (2862/-306 across 16 files); the earlier portion of this PR was reviewed and cleared in a previous REV pass.

Verdict

Status: BLOCKED — 3 BLOCKING findings.

Agent	Status	Findings
Security	PASS	2 POTENTIAL
Bugs	BLOCKED	1 BLOCKING + 4 POTENTIAL/INFO
Tests	PASS	4 NON-BLOCKING/INFO
Guidelines	BLOCKED	1 BLOCKING + 3 POTENTIAL/INFO
Docs	BLOCKED	1 BLOCKING + 5 POTENTIAL/INFO

BLOCKING

[Bugs] src/top/state.rs:555 — request_kill targets a different pid than the highlighted row.
The renderer sorts a fresh slice via views/activity.rs:99-100's sort_rows, but request_kill reads snap.rows.get(self.selected_row). The TableState.with_selected(...) highlight indexes the sorted slice. After any non-default sort (and even on the default, since the SQL ORDER BY differs from the Rust qtime-desc tiebreak), pressing k/K builds the [y/N] confirm and ultimately kills a backend the user did not intend.

Fix: sort once in App::set_snapshot (or have request_kill re-run sort_rows) and pick sorted[selected_row]. Add a regression test with ≥2 rows where the SQL order and Rust sort disagree.

[Guidelines] demos/top-workload.sh — every psql invocation violates the PostgreSQL command execution rule.
Lines 32, 37, 48, 56, 59, 64, 68, 72, 77 all use psql -c "…" without --no-psqlrc and PAGER=cat, and use the short -c form rather than long-option-per-line. CLAUDE.md's "PostgreSQL command execution" rule is unconditional.

Fix: prefix each call with PAGER=cat psql --no-psqlrc --dbname="${CONNINFO}" --command="…".

[Docs] docs/COMMANDS.md:49 — /top row omits --show-keys.
The flag is implemented (src/top/mod.rs:130) and exposed globally (src/main.rs:351); the demo tape relies on it. Missing entirely from the public reference.

Fix: append `--show-keys` (overlay each keypress as a billboard demo aid) to the flags list.

POTENTIAL (recommended, not blocking)

• [Security] renderer.rs:455-458 — build_kill_confirm_line interpolates raw req.usename / req.datname / req.state / req.query_summary without scrub_terminal_unsafe. A DB user controlling application_name could inject ANSI/BEL into the operator's terminal when the operator presses k/K on that backend. Activity-table fields are correctly scrubbed via truncate/squash_query but the kill-prompt path is not.
• [Security] renderer.rs:486 — build_admin_message_line renders msg.text directly. In the kill error branch the text is format!("{e}") from tokio_postgres::Error, which can carry server-controlled bytes.
• [Bugs] state.rs:541-548 — handle_kill_confirm_key cancels on _. Bare modifier-only key events (Kitty CSI-u, Windows release events) would silently dismiss the confirm.
• [Bugs] mod.rs:300-308 — run_kill ignores the result of set statement_timeout = 0. If the reset fails the 5 s timeout leaks to subsequent sampler ticks.
• [Bugs] sql.rs:36 — total_backends excludes pg_backend_pid(), so the header is off by one vs pg_stat_activity.
• [Guidelines] 12 of 15 commit subjects in this delta exceed 50 chars. Resolved by squash-merging into a single PR-scoped commit.
• [Docs] docs/COMMANDS.md:49 — Keybinding list is missing PgUp/PgDn and Home/End (both wired in S1).
• [Docs] .samo/spec/top/SPEC.md — Status still "ready for S1"; doesn't reflect what shipped (--batch, s/r/e, kill confirm).
• [Docs] .samo/spec/top/decisions.md — No "S1 shipped" entry recording deviations.

NON-BLOCKING / INFO

• [Tests] No smoke test for --batch mode end-to-end; format_refresh_seed only covered transitively; render_label("C-K") mixed-glyph case missing.
• [Bugs] KeyModifiers::SUPER → S- collides with the Shift convention.
• [Bugs] renderer.rs:373 — unchecked inner_w + 2 arithmetic; consider saturating_add.
• [Guidelines] demos/top-workload.sh lacks main() + main "$@" last line.
• [Security] sql.rs SQL is fully static; run_kill binds pid as $1; figlet glyph table consumes only local KeyEvents — all clean.

---

Next step: fix the 3 BLOCKING items (kill targets the right row, shell rule, doc gap) plus the 2 security POTENTIAL scrubs (cheap, prevents a real terminal-injection class), push, re-run CI + REV.

[NikolayS]

REV-assisted review (round 12 follow-up) — 5db967b

CI on the round-12 commits: 19/21 green at audit time, with Analyze (rust) and PostgreSQL Regress Tests still running but already passing on the same Rust changes in the previous round.

Round-11 BLOCKING resolution

Round-11 finding	Status	Evidence
request_kill targets unsorted slice → wrong-pid kill	RESOLVED	state.rs:560-562 re-sorts via views::activity::sort_rows(&mut sorted, sort_column, sort_desc) and indexes the sorted slice; regression test k_targets_the_sorted_row_not_the_sql_row (state.rs:1172) RED→GREEN with two rows whose SQL order disagrees with Pid-asc
demos/top-workload.sh violates psql shell rule	RESOLVED	every call now goes through run_psql / run_psql_stdin helpers that apply env PAGER=cat psql --no-psqlrc --dbname=… --command=…; main() block; main "$@" last line; shellcheck clean
docs/COMMANDS.md /top row missing --show-keys	RESOLVED	--show-keys now documented; PgUp/PgDn and Home/End keybindings listed

Security POTENTIAL resolution

Finding	Status	Evidence
build_kill_confirm_line un-scrubbed row fields	RESOLVED	renderer.rs:464-467 wraps each field in scrub_terminal_unsafe; new test kill_confirm_strips_ansi_escapes_from_row_fields (renderer.rs:1007) seeds \x1b[31m / \x1b[2J / \x07 and asserts no control byte reaches the rendered buffer
build_admin_message_line un-scrubbed msg.text	RESOLVED	renderer.rs:499 scrubs the text; admin_message_strips_ansi_escapes test (renderer.rs:1047) seeds an ANSI/BEL string into the kill-error footer and asserts byte-clean output

New findings this round

• [POTENTIAL] demos/render-top.sh mktemp -t …palette.XXXXXX.png is broken on macOS BSD → fixed in 5db967b: switched to ${TMPDIR:-/tmp}/top-demo-palette-$$.png; verified end-to-end run produces an 11 MiB gif. The audit caught a real bug — ffmpeg refused to write the palette because the extension was the random hash, not .png. The committed gif from 3182ebc was produced by an ad-hoc ffmpeg invocation against /tmp/palette.png, not the script, so the script-as-committed would have failed for anyone else.
• [INFO] demos/README.md "render all at once" loop runs plain vhs on top-demo.tape, skipping the post-process and producing the laggy gif this chain was written to avoid → fixed in 5db967b: loop now skips top-demo.tape and the README points at bash demos/render-top.sh for the post-processed render.
• [INFO] demos/top-workload.sh:48-65 — three persistent-backend ( … ) & blocks fire at top-level before main() is invoked. Letter of the shell-style rule met (main() exists, main "$@" is the last line); spirit (whole procedural body inside main) drifts a little. Cleanup is trapped on EXIT so behaviour is correct. Cosmetic.
• [INFO] demos/top-demo.gif — file size grew 2.9 MiB → 11 MiB. Documented in demos/README.md as the deliberate cost of the smoother ffmpeg pipeline.

Verdict

Status: PASS — all round-11 BLOCKING and POTENTIAL security findings resolved with regression tests; the only sharp follow-up the audit raised (BSD mktemp) is fixed in 5db967b. Remaining INFO items are cosmetic.

Per project memory rule, not merging without explicit approval.

[NikolayS]

REV-assisted review — round 12 (commit 0d57770 + c6c5db9)

CI Status: ✅ pass (all core checks: lint, test, clippy, MSRV, PG14–18, connection, regress, wasm, CodeQL)

---

BLOCKING issues fixed in this review cycle

FIXED · TerminalGuard::drop cleared the main terminal screen after exiting alt-screen

\x1b[H\x1b[2J\x1b[H was sent to stdout after LeaveAlternateScreen. At that point the user is back on their main terminal, so this wiped whatever was on screen before they ran /top (previous query results, shell prompt, etc.). Alt-screen restoration already restores the original content — the explicit erase was wrong and redundant. Fixed in c6c5db9.

---

NON-BLOCKING

Security · N-1: format! builds set statement_timeout SQL in sampler.rs

apply_timeout uses format!("set statement_timeout = '{timeout_ms}ms'") where timeout_ms is a compile-time u64 constant — no injection path exists today. Minor style inconsistency with the literal-string pattern used elsewhere; could harden by inlining the literal.

Security · N-2: format! builds pg_cancel_backend/pg_terminate_backend function name in run_kill

format!("select {}($1)", req.pg_function_for_request()) — function name is one of two hard-coded &'static str values, PID passed via $1. Safe as written; a match building the full literal would be cleaner.

Bugs · N1: exec_command always returns exit code 0 for /-extension commands including errors

Scripts relying on $? to detect /top --once failure (e.g. DB unreachable) will see 0. Already self-documented in code with a // KNOWN LIMITATION comment. Deferred to S2.

Bugs · N2: run_batch allocates App::new() inside the loop — stale-tick counter never accumulates

The stale-tick badge that shows in interactive mode when the DB is slow will never appear in --batch output. App should be created once outside the loop (same fix already applied to Terminal<TestBackend>).

Tests · 1: scrub_terminal_unsafe drops valid U+FFFD replacement characters

The two-pass approach (map control bytes to \u{FFFD}, then filter) also drops any genuine U+FFFD in user data (unusual but possible with some client encodings). Low probability; could use an internal sentinel instead.

Tests · 2: stable-sort property not exercised

Code comments "stable sort preferred so equal-key rows preserve SQL-side ordering" — no test places two rows with equal keys and asserts insertion-order preservation. A regression to sort_unstable_by would pass silently.

Tests · 3: top_once_shows_active_backend_count integration test has a loose assertion

stdout.contains("rows)") matches any row-count caption including (0 rows). Should assert on a specific non-zero count to verify a live backend is actually visible.

Guidelines · NB-1: demos/top-workload.sh line 81 chars (1 char over 80-char limit)

readonly CONNINFO="${1:-host=localhost port=55433 user=postgres dbname=postgres}" — trivial split.

Guidelines · NB-2: demos/top-demo.tape hardcodes /Users/nik/github/rpg/…

Other contributors running bash demos/render-top.sh will get path errors. demos/README.md should note these need adjustment (it already mentions the PG* env block).

Docs · 1: COMMANDS.md /top row is a single 838-char wall of text

All other entries use a one-liner. The flags and keymaps detail belongs in the planned docs/top.md (S8). Consider a brief description + "see docs/top.md" placeholder.

Docs · 2: GLYPH_W doc-comment says "public API for future callers" but carries #[allow(dead_code)]

These two signals contradict each other. Either drop the allow or update the comment.

---

INFO

• No unsafe Rust introduced. All Postgres wire data flows through tokio-postgres typed column API.
• All user-controllable fields (application_name, query, usename, datname, state, pg_version, error text) pass through scrub_terminal_unsafe before reaching ratatui. Kill-confirm and admin-message paths also scrub correctly.
• Test naming is precise and behavioural throughout. Fixtures are representative (unambiguous lock counts 47/83, multiple backend states).
• SET statement_timeout (bare, not SET LOCAL) is correct here — SET LOCAL outside an explicit transaction block is a no-op in PostgreSQL, so the explicit reset pattern is the right approach.
• .samo/spec/top/SPEC.md v0.2 is an unusually thorough spec; makes future sprint work straightforward.

---

Verdict: PASS — one BLOCKING bug fixed (TerminalGuard screen-wipe); remaining findings are NON-BLOCKING or INFO. Ready for merge at owner's discretion.