#201 tui: design + build a live-tail mode for the decision-log browser

[Anonymous]

Originally created by: fu351

What

src/doberman/tui.py is a single-file Textual app that browses the redacted decision log (doberman.storage.log.read_decisions). Today it loads decisions once at startup (on_mount, line 99) and only refreshes on an explicit, manually-triggered key binding (action_reload, line 105, wired via BINDINGS, line 66) — there is no live-tail: a decision the running proxy writes while the TUI is open never appears until the user presses reload. Design and build a live-tail mode: the TUI polls (or is otherwise notified of) new rows in decisions and appends them automatically while open, without breaking the existing redaction/explainability guarantees (module docstring, lines 1–24) or freezing the UI (the existing debounced background-worker pattern for LLM enrichment, lines 14–18, is the template for "never block the event loop").

Difficulty: level-7

Additive, but not a local tweak to the existing manual-reload action — it's a genuinely new capability (a background polling/notification mechanism, new Textual reactive state, a decision on polling interval vs. a push mechanism from the proxy process, and how it interacts with the existing debounced-enrichment worker so two background workers don't fight for the UI thread). Needs a design discussion (this issue) before any code — in particular whether the mechanism is DB-polling only (simplest, no cross-process signaling) or something the long-lived proxy process pushes to the TUI (more complex, cross-process).

Safety constraints (do not weaken these)

• Every guarantee in the current module docstring (lines 1–24) must survive unchanged: the TUI still only ever reads already-redacted rows via read_decisions (never a raw file, raw payload, or any other data source), and all row-derived / LLM-narrated text still renders through rich.text.Text with markup disabled (a crafted value in a stored row must still never restyle or spoof the display).
• A live-tail poll loop must use the same "never block the event loop" discipline as the existing @work enrichment worker (line 155 today) — a slow or failing poll must never freeze scrolling/reload/enrichment, and must degrade to "no new rows yet" rather than crash the app.
• tui.py must keep its stated constraint of never importing doberman.proxy (policy-core decoupling, CLAUDE.md §9 / import-linter) — a DB-polling design satisfies this for free; a cross-process push design must be designed not to violate it.
• This issue is a design discussion first: do not open an implementation PR until the polling-vs-push question (and interval/perf tradeoffs) has maintainer agreement in the issue thread.

Starting files

• src/doberman/tui.py — whole file (single-file Textual app); on_mount (line 99), action_reload (line 105), BINDINGS (line 66), the existing @work(thread=True, exclusive=True, group="explain") enrichment worker (line 155) as the background-work template.
• src/doberman/storage/log.py — read_decisions (the only data source the TUI is allowed to use).

Acceptance criteria

• [ ] The issue thread records a maintainer-agreed design (polling interval and mechanism, or an alternative) before implementation begins.
• [ ] Once implemented: new decisions written by a running proxy appear in the open TUI without a manual reload, within the agreed interval.
• [ ] The existing manual action_reload binding still works unchanged.
• [ ] No raw (non-redacted) data source is introduced; all displayed text (including live-tailed rows) still renders via the existing markup-disabled path.
• [ ] Live-tailing never blocks the UI thread (verified by a test or a documented manual-test procedure if Textual makes this hard to unit-test).
• [ ] tui.py still does not import doberman.proxy (lint-imports / import-linter contract, if one is extended to cover this).
• [ ] Existing behaviour unchanged for every case not touched here (no test weakened, no output format broken)
• [ ] ruff check . && ruff format --check . and lint-imports pass
• [ ] pytest passes

How to validate

doberman tui
# in a second terminal, generate a decision (any mediated tool call) and confirm
# it appears in the open TUI without pressing the reload key.
pytest tests/ -k tui -v

Out of scope

• Do not add a network/remote TUI (multi-machine live-tail) — local single-process (or single-machine, if a push design is chosen) only.
• Do not change how enrichment (doberman.explain) works — the live-tail worker and the enrichment worker are separate concerns; this issue only adds the former.

Notes for contributors

New here? Start with CONTRIBUTING.md. Issues are labelled level-1 (docs only) through level-10 (new subsystem) — pick one at your level and climb. Comment to claim an issue before starting.

[Anonymous]

Originally posted by: fu351

Re-leveled 10 → 7. A live-tail mode is a second Textual worker plus reactive state over the existing decision-log browser, not a new subsystem — substantial, but not top-of-ladder.