Tui Bug Hunt

VibeSys TUI bug hunt

Goal: exercise the VibeSys TUI end to end, catch all types of frontend and backend bugs (display/layout, interaction/keybinding, streaming, theme/contrast on the frontend; protocol, lifecycle, state, and evaluator/benchmark on the backend), and produce reports that map cleanly onto the repo's issue forms. Enhancements and net-new features are in scope to identify and report: when a surface is missing something it should have, file it as an engineering change (§7). The TUI is a full-screen OpenTUI app, so it is driven through a real PTY provided by tmux; no human at a terminal is needed.

Priority order (do not reorder): (1) find the issue, (2) help the user open a GitHub issue ticket for it, (3) only then, and only with the user's explicit approval, discuss and implement a fix or feature. Never write code / open a PR for a finding before the ticket exists and the user has approved implementation. This skill's job ends at a filed ticket unless the user says to go further. The fixing guidance in §8 applies only once that approval exists.

Always run a real Claude-Code-provider run, and keep it to 1-2 rounds (§2): short enough to be cheap, long enough to reach a resolved hypothesis and see the log table, Measured deltas, and /perf update live.

Read reference.md (same folder) for the exhaustive command/keybinding/ breakpoint/error/issue-form tables. This file is the workflow.

0. Prerequisites (verify once)

• Toolchains on PATH: node (≥20), bun, pnpm, tmux, and uv; plus go + cargo when running real rounds on the queue example. claude CLI installed and authenticated (claude -p "ok" returns ok) for real-provider runs.
• TUI built: clients/tui/dist/launcher.js and dist/index.js exist. If not: pnpm install --frozen-lockfile && pnpm --dir clients/backend-client generate:protocol && pnpm build:clients.
• Python env: <repo>/.venv with vibesys installed (uv sync). Export VIBESYS_PYTHON=<repo>/.venv/bin/python.
• A standalone candidate repo (its own git root). The bundled queue-rs example is nested in this repo, so copy it out first, e.g. /tmp/vibesys-runs/queue-{spsc,mpsc,mpmc}.
• On a shared host, the framework benchmark path collision (hardcoded /tmp/vibesys-framework-benchmark-*.json) can block benchmark recording; the per-uid fix in loop.py resolves it. If /perf is empty, check backend.log for framework-benchmark FAIL: ... permission denied.

1. The driving harness

Use tuidrv.sh in this folder. It wraps a detached tmux session.

tuidrv.sh start <COLSxROWS> <PROJECT> <TASK> [vibesys args...]
tuidrv.sh cap        # rendered frame, plain text (layout/wrapping/alignment)
tuidrv.sh capE       # frame WITH ansi escapes (color / theme / contrast checks)
tuidrv.sh keys <k…>  # named keys: Enter Escape C-w C-l F4 F2 F3 Up Down Tab BTab '[' ']' PgUp PgDn
tuidrv.sh type <txt> # literal text
tuidrv.sh cmd <txt>  # type then Enter (e.g. cmd /help)
tuidrv.sh size <WxH> # resize to test responsive layout
tuidrv.sh log [N]    # tail the live backend.log
tuidrv.sh wait [S]   # let renders / agent turns settle
tuidrv.sh stop

Driving discipline:

• After every start, wait 15-20 (backend readiness up to 30s), then cap.
• After every keystroke/command, wait 1-2 before cap; agent turns need longer (wait 10-30) in real mode.
• Judge alignment from cap without stripping trailing spaces (borders live at the right edge). Judge color/contrast from capE.
• Always cap the frame into your notes verbatim as evidence before acting.
• One session at a time (default name vsbug); stop when done or before a new start. Set VS_TUI_SESSION to run several.

2. Run mode: always real (Claude Code provider)

Always hunt against a real run. Do NOT use --stub-agent for bug hunting: the stub is a mock and misses real backend/stream/agent behavior, and this project requires findings to come from reality.

start 200x50 /tmp/vibesys-runs/queue-mpmc mpmc --profiler none --cli-provider claude --max-rounds 2

This uses the Claude Code provider and exercises the live event stream, real agent turns, chat wired to a coding agent, real measured metrics (/perf), and /pause /steer /resume. It is slower and spends tokens, so default to --max-rounds 2 (1 is fine for a quick pass, never more than 2 unless the user asks for a long run), and reuse the one running session for the entire sweep rather than relaunching. Two rounds is enough to see a hypothesis resolve, the log table refetch, Measured deltas populate, and /perf plot a second point.

Before each session, clean prior state (stale tmux sessions, leftover /tmp/vibesys-session-*, and prior run state) and re-stage a pristine project copy, so a run never fails on a resumed/duplicated hypothesis or a /tmp collision. The framework benchmark path is now per-uid, so cross-user /tmp collisions no longer block benchmark recording; if /perf is still empty, check backend.log for framework-benchmark FAIL.

Freeze for inspection: live updates race your captures. Use /pause (or wait for a round boundary) before the responsive-size, theme, and keybinding passes, so a layout change is attributable to your resize/keys and not to new events landing. /resume to continue.

3. Systematic sweep protocol

Work the surfaces in order. At each step: send the keys/command, wait, cap (and capE when color matters), and check against the intended behavior in reference.md / the TUI README. Log every deviation as a candidate finding.

1. Startup & experiment log. Launch real (claude provider); wait for the backend (≤30s) and the first agent turn. Verify the landing view is the hypothesis-keyed log: columns present for the width, ▸ on the active hypothesis, spelled-out Accepted/Rejected (not color-only), rounds ranges, Measured deltas. Check the footer hint and the Ctrl+W to type here chat instruction.
2. Log navigation. Up/Down move selection; PgUp/PgDn scroll; Enter opens the selected hypothesis. Confirm selection survives a table refetch (it is keyed by hypothesis id).
3. Hypothesis summary → round. In a hypothesis, select a round, Enter to open the transcript + rounds strip + agent map. [/] change rounds; Tab/Shift+Tab change agents; arrows move the transcript cursor; Enter toggles a tool card; F2/Ctrl+T todos; F3/Ctrl+P latest prompt. Escape should unwind entry cursor → agent filter → hypothesis.
4. Agent strip/graph. Confirm the graph renders at wide widths and falls back to the stacked list when narrow; clicking a node filters the transcript; clicking the selected node clears the filter (mouse via tmux is optional).
5. Commands. Run each: /help, /theme, /theme <name>, /perf, /todos, /prompt, /pause, /resume, /steer x (and empty /steer), /open-round, /open-round --2. Verify each surface (modal vs pane vs inline) and the exact error strings for bad input. Confirm /help lists the right commands and the Planned section.
6. Chat. Ctrl+W moves focus to the chat and back (focus border + ▸ move). Ask a question; in stub it returns a fixed string. Test /clear, /model, and a slash command typed in chat (forwarded). Dock vs modal is width-driven (see step 8).
7. Split panes & zoom. /perf opens a right pane (≥100 cols) or a modal (<100). Ctrl+W cycles focus across visible panes; F4 zooms the focused pane and restores selection/scroll on toggle; Escape on the right pane closes it.
8. Responsive matrix. Repeat key views at several sizes and check reflow and the exact breakpoints in reference.md: size 200x50 (wide), 120x40, 104x40, 100x40, 92x40, 88x40, 72x30, 60x24. Watch: chat docks ≥92 else modal; /perf splits ≥100 else modal; log columns drop Kept(104) → Claim(90) → Measured(62); agents graph → stacked; footer hint collapses <60. Resize both directions; a width-only change must still redraw (cached-width bug risk).
9. Themes. For each theme (dark, light, solarized-dark/light, catppuccin-mocha/latte, high-contrast-dark/light): /theme <name> then capE. Check contrast of muted/subtle text and that status meaning does not depend on color (glyph + word present). Also test --theme flag and agent.toml [tui].theme precedence, and the picker (/theme, then Up/ Down, Enter, Esc).
10. Error surfaces. Trigger the banner and confirm it is dismissable (Escape, Ctrl+PgUp/PgDn scroll) and does not permanently eat 10 rows. Trigger a backend argparse diagnostic by adding a bogus flag (e.g. --nope) to start; confirm it surfaces as a banner with stage/exit/hint, not a crash. Open /help while a banner is up and check for border overlap.
11. Clipboard / Ctrl+C. With no selection, Ctrl+C exits (expected). Note OSC52 selection behavior and the status-line difference when unsupported.
12. Backend & lifecycle. Throughout, tuidrv.sh log for tracebacks, protocol errors, timeouts, or permission denied. In real mode, let a run reach a resolved hypothesis and confirm the log table and Measured//perf update live (table refetches on phase/round completion). Test /pause then /resume. Kill the backend mid-run (stop) and, on a fresh start --resume, confirm resumed hypotheses are not shown empty.

4. Configuration & feature matrix to exercise

The sweep above walks one config. Most real bugs hide in combinations of state you have to deliberately construct: a specific size crossed with a specific theme, a resumed run, a mid-stream resize, an error banner plus an overlay. Vary one axis at a time from a known-good baseline so a regression is attributable. Cross the high-value axes below; capture the frame at each cell.

• Terminal geometry. Every breakpoint in reference.md §Responsive, plus the boundary itself (99 vs 100, 91 vs 92, 103 vs 104, 61 vs 62) and one column below the smallest (58x20) to see graceful degradation vs corruption. Also very tall/short (120x12, 120x80) to stress vertical reservation (banner 10 rows, perf chart 8, overlay 60%). Resize while a turn is streaming and while a modal/picker is open.
• Themes × geometry. Each theme at wide and at the narrowest usable size; a live /theme switch while a modal, the perf pane, and the error banner are open (style-disposal and preview-vs-applied bugs live here). Precedence: --theme flag vs agent.toml [tui].theme vs VIBESYS_THEME vs default.
• Launch flags. --max-rounds 1|2, --profiler none vs a real profiler, --theme, --resume, a bogus flag (--nope) for the argparse banner, and --headless/-h/validate (must bypass the TUI, not half-render it).
• agent.toml config. [tui].theme, model/provider blocks, and any [tui] keys. Feed an invalid value (bad theme name, unknown key) and confirm it fails with a named error, not a silent fallback or a crash (AGENTS.md: reject unknown keys).
• Providers / models. Default claude provider is the baseline. If asked to go broader, --cli-provider codex with a gpt-* model exercises a different turn/stream shape; /model in chat switches harness+model mid-run.
• Lifecycle transitions. /pause→resize→/resume; kill backend mid-round then --resume (resumed hypotheses must not render empty, per #420); let a hypothesis resolve Accepted, Rejected, and Deferred/unmeasured and check each renders with a word+glyph, not color alone. Steer mid-run (/steer …) and confirm the injected guidance appears in the next turn.
• Data-shape stress. A run with >8 rounds (rounds-strip overflow, #255); a long hypothesis claim / long chat input (composer clipping, #427); parallel tool calls in one turn (card keying); a turn that errors (banner scope/title).
• Focus & overlay stacking. Every pair of {chat docked, chat modal, perf pane, perf modal, /help, /theme picker, error banner, todo strip, F4 zoom} open together. Keys must reach the top surface only; nothing should leak to the view behind a modal/picker (#331), and overlays must not collide (§10 seed).

Not every cell is worth a capture on every run. Prioritize boundaries, transitions, and stacked surfaces; those are where the contract is thinnest.

5. Detection heuristics & adversarial mindset

Hunt like an adversary: for each surface ask "what state would make this formatting, keying, caching, or reservation assumption wrong?", then construct it. The richest bugs come from a surface built for the common case meeting an edge you forced (empty, overflow, mutation-in-place, transport loss, a width the author cached).

A finding is any deviation from reference.md / the README, or any of:

• Layout: broken/misaligned box-drawing borders; content past the right edge; overlapping panes/overlays (e.g. a modal colliding with the error banner); truncation without an ellipsis or a ‹ n / n › more-indicator; a column that should have dropped (or shouldn't have) at a given width; empty region where data is expected.
• Text/stream: one-token-per-line breaks; duplicated or dropped streamed tail; a mutated entry not updating in place; stale content after a filter or round change.
• Color/theme (capE): low-contrast muted/subtle text; status conveyed by color only (no glyph/word); wrong theme after launch or a leak of the previous theme's colors after a switch.
• Interaction: a key that moves the wrong thing (e.g. arrows scroll the view instead of a suggestion/menu); focus indicator missing or wrong; a click that does nothing; keys leaking to the view behind a modal/picker; a suggestion Tab that always completes the first match.
• Backend/protocol (log): Python traceback, protocol_error, transport timeout, permission denied, event loop is already running, or a ValueError/state error that fails the run.
• Lifecycle: selection/scroll lost on refetch or resize; timers/leaks; resumed state shown empty; run that fails where the stub scenario should succeed.
• Contract disagreement: two surfaces that derive the same fact disagree (e.g. a streamed event says skipped while the persisted/projected record says fail). When two views of one datum diverge, one of them is reading a stale or mis-owned field; that is a backend/projection bug even though you saw it in the UI. Note both values and where each is computed.

For each, decide bug vs intended: some behaviors are deliberate contracts (e.g. non-slash text in the command box is intentionally not accepted; the chat composer owns questions; the frontend must not optimistically mutate backend-authoritative state). Cite the README/architecture line the behavior matches or violates before filing. When unsure whether the fault is render vs state vs backend, that judgement belongs in reproduction (§6), not in the ticket title.