[smarzban]

Why

Some host terminals drop the board's alternate screen while the pane is hidden. T3 Code's terminal panel does this when you switch away and back. ratatui then repaints only the cells that changed since its last frame, so the board comes back as scattered ages and counts on a blank pane. tsk now asks for focus reports and repaints every cell when focus returns, or on ctrl+l.

What changed

• The board and quick capture turn on focus reporting (?1004h) and turn it off on exit (src/ui/mouse.rs).
• FocusGained or ctrl+l resets ratatui's frame before any surface sees the event, so the next paint writes every cell (forget_frame_on_repaint_request in src/app.rs). It uses Terminal::resize to the current size, not Terminal::clear, because clear asks for the cursor position. A terminal that doesn't answer that question made the board exit with an error during the live smoke.
• Docs: a ctrl+l row and a note in keys.md, a Help row, and a CHANGELOG Fixed line.

Scope

• Covers: focus-in repaint and the ctrl+l redraw key on every surface, text entry included.
• Leaves out: T3 Code's own terminal behaviour.
• Changed since the start: added item 4 after the first live smoke crashed on Terminal::clear.

Done when

#	Result	Proved by	Proof	Step
1	Focus reporting is turned on, and off again on exit	agent	focus_reporting_is_enabled_and_restored; smoke 1	5
2	Focus in repaints the whole board after the host dropped the screen	agent	repaint_request_restores_a_screen_the_host_terminal_dropped; smoke 1	5
3	ctrl+l does the same	agent	same test; smoke 1	5
4	The repaint never asks for the cursor position	agent	repaint_request_never_queries_the_cursor_position (fails with terminal.clear()); smoke 1	5
5	Docs, Help and CHANGELOG list ctrl+l	agent	diff	4
6	The board looks right when you switch back to it in T3 Code	owner	Your steps in the report

Verification

Commit: 6d58b30 (smoke 1 ran on the binary from 5edae4a. 6d58b30 changes only tests.)

1. PTY smoke, with isolated TSK_STATE_DIR, TSK_CONFIG_DIR and HOME under /tmp. It runs the board in a 100×30 pty fed to a pyte screen, wipes the emulator's screen, sends focus in (ESC [ I), then wipes it again and sends ctrl+l:

   before (origin/main 5b30b8d6): focus reporting requested: False
     after host drop + focus in: PARTIAL (0 words vs 116)
     after host drop + ctrl+l:   PARTIAL (0 words vs 116)
   after: focus reporting requested: True
     after host drop + focus in: FULL (116 words vs 116)
     after host drop + ctrl+l:   FULL (116 words vs 116)
   

   With Terminal::clear in place of the fix, the same smoke ended the board with tsk: The cursor position could not be read within a normal duration, because pyte doesn't answer the query.
2. cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test: 2428 passed, 0 failed. Also cargo clippy --all-targets --target x86_64-pc-windows-gnu -- -D warnings and cd site && npm test, both clean.
3. Each new test was watched failing with its fix reverted by hand.

Could break

Every focus-in now clears and repaints the screen once, so a slow terminal might flicker briefly. On Windows, crossterm treats the focus-reporting commands as no-ops, and focus events arrive anyway.

Review

Pi review panel (gpt-6.1-sol and opus-5-5; holistic, tests, specification-conformance) on 5edae4a: 6 of 6 seats voted. Holistic and spec seats found nothing. Kept F-3/F-2 (no test failed on a cursor query), fixed in 6d58b30, and the opus seat's verify passed.
Set aside: F-1/F-4. Nothing tests the one line that hooks the repaint into the event loop. Covering it would mean pulling a step out of run_board_loop, and the PTY smoke covers that line end to end.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
herdr-tsk	Building	Preview	Nov 13, 2026 5:51pm UTC