Skip to main content
Version: Next

0034: The watch draws a full-screen view on the alternate screen, and keeps every line in a log file

  • Status: Accepted (backfilled 2026-10-06: records a decision already built)
  • Date: 2026-10-06

Context​

orion watch runs for hours. A scrolling log reprinted the board every few minutes, and a person had to find the latest copy among the lines. An earlier attempt pinned a region at the bottom of the terminal; it produced six display defects in two days, all the same shape: the code erased a counted number of rows, the terminal had scrolled or wrapped a different number, and the difference was left on screen.

Decision​

On a terminal, the watch takes the alternate screen and redraws it like top: the board on top, the newest log lines under it (internal/ui/screen.go). Nothing is counted, so nothing can be miscounted:

  • every frame starts from the top-left corner;
  • auto-wrap is off, so no line takes two rows;
  • a frame is cut to the terminal's height, so nothing scrolls;
  • a wrong frame is repaired by the next one, instead of accumulating.

The alternate screen has no scrollback, so every line also goes to a log file under ~/.orion/logs/, colour stripped, named in the header.

Every exit (normal, drained or forced) restores the terminal and prints the last lines and the log path. The scrolling log is kept wherever a full-screen view would be wrong: --plain, --once, --dry-run, output to a pipe, or TERM=dumb.

Consequences​

  • The board is always current and in one place.
  • Scrolling back means opening the log file.
  • Scripts and CI get the plain log they always had.

Alternatives rejected​

  • A pinned region in the normal screen. Tried; it depends on counting rows, and the count is wrong whenever the terminal scrolls or wraps.
  • Reprinting the board into the log. The original problem.
  • A terminal UI library. Orion has no third-party modules; the view is a few escape sequences.