feat(client): wrap the stage at the terminal's width, never truncate

## Summary

### Why?

The stage column was cut at a hard-coded 120 columns, and the cut fell at the end of the trail — which is exactly where the request currently is. Once the pipeline began reporting its finer stages, an ordinary trail outgrew the line and the run read like this, with the interesting part missing:

```
demo-queue/1  #147  22s  accepted → started → validating → validated → batched → speculating → speculated → la…
```

The 120 was never a measurement. The renderer redraws in place by moving the cursor back over the lines it emitted, and a line that wraps physically occupies two rows, which desyncs every redraw after it — so the width had to be bounded somehow, and a constant was cheaper than asking. That trade was invisible while trails were short.

### What?

The renderer now asks the terminal how wide it is, and wraps rather than cuts when a trail still will not fit.

Asking first is what matters: on a wide window the whole trail simply fits on one line, and nobody is held to the narrowest window anyone might have. The fallback is the old constant, used whenever there is no size to discover — a pipe, a file, a CI log — where a stable width is what a log wants anyway.

It asks before every draw, not once at startup. The width is not a property of the process: a watch runs for minutes, and a window dragged narrower inside them leaves every later frame wrapped to a width the window no longer has. The terminal then wraps those lines itself — mid-word, ignoring the column alignment — and because the redraw counts the lines it emitted rather than the lines that appeared, it drifts further with every frame. Sampling once traded that away for an `ioctl` per second.

Knowing the width is also what decides whether to redraw in place at all. Detecting a terminal and measuring it were two separate probes, so a terminal that answered the first and not the second got wrapped to the fallback constant — 120 columns of table in whatever window the reader actually had. They are now one question: no size, no wrapping, render as a log.

When a trail is longer than the line even so, it wraps onto continuation lines indented under the stage column, the way a wrapped error already does. This keeps the redraw honest rather than working around it: every line is one the renderer produced and counted, so the cursor arithmetic still holds, and nothing is ever cut. Piped output is left on a single unwrapped line, since a log is easier to read and grep that way and has no width to respect.

## Test Plan

✅ `bazel test //submitqueue/client:go_default_test` — 75 cases pass, including the pre-existing redraw-accounting ones that pin the property this all rests on: no emitted line exceeds the width.

✅ Seven new cases: a long trail wraps instead of truncating and every status survives it, the end of the trail is on the last line, continuations align under the stage column, no line exceeds the width at 80/100/120/200 columns, a 240-column terminal needs no wrapping at all, piped output stays on one line, and a window too narrow for the columns still wraps to a readable floor rather than one word per line.

✅ The zero-value renderer that tests construct directly falls back to the default width rather than collapsing, which is what keeps the moved tests working unchanged.

✅ A resize is followed: a table drawn at 200 columns and redrawn after the window narrows to 94 keeps every line inside 94. This is the case that reaches a reader as a trail cut mid-word at the window's edge, since the terminal breaks anything the renderer lets past it.

✅ A probe that fails once leaves the last known width alone rather than snapping to the fallback, which on a narrow window is wider than the window.

✅ A terminal whose size cannot be read does not redraw in place, so wrapping never runs against a guessed width.

Author: behinddwalls

MODULE.bazel

@@ -66,6 +66,7 @@ use_repo(
     "org_golang_google_protobuf",
     "org_golang_x_oauth2",
     "org_golang_x_sync",
+    "org_golang_x_term",
     "org_uber_go_fx",
     "org_uber_go_mock",
     "org_uber_go_yarpc",

go.mod

@@ -14,6 +14,7 @@ require (
 	go.uber.org/zap v1.27.1
 	golang.org/x/oauth2 v0.34.0
 	golang.org/x/sync v0.19.0
+	golang.org/x/term v0.39.0
 	google.golang.org/grpc v1.68.1
 	google.golang.org/protobuf v1.36.10
 	gopkg.in/yaml.v3 v3.0.1

go.sum

@@ -249,6 +249,8 @@ golang.org/x/sys v0.0.0-20211019181941-9d821ace8654/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
 golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=
+golang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=

submitqueue/client/BUILD.bazel

@@ -19,6 +19,7 @@ go_library(
         "@org_golang_google_grpc//:go_default_library",
         "@org_golang_google_grpc//credentials:go_default_library",
         "@org_golang_google_grpc//credentials/insecure:go_default_library",
+        "@org_golang_x_term//:go_default_library",
     ],
 )
 

submitqueue/client/view.go

@@ -24,23 +24,28 @@ import (
 
 	pb "github.com/uber/submitqueue/api/submitqueue/gateway/protopb"
 	"github.com/uber/submitqueue/submitqueue/entity"
+	"golang.org/x/term"
 )
 
 const (
 	// pollInterval bounds how often the watcher re-reads every request's history.
 	pollInterval = 2 * time.Second
 
-	// maxLineWidth caps a redrawn line. A line that wraps occupies two physical
-	// rows, which permanently desyncs the cursor arithmetic the in-place redraw
-	// depends on; capping is cheaper than asking the terminal how wide it is.
-	maxLineWidth = 120
+	// defaultLineWidth is the width assumed when the terminal will not say how
+	// wide it is — piped output, or a terminal that answers no size at all.
+	defaultLineWidth = 120
 
 	// absent is what a cell shows before there is anything to put in it.
 	absent = "—"
 
 	// minNoteWidth keeps a wrapped error readable even when the columns before
 	// it have eaten most of the line.
 	minNoteWidth = 40
+
+	// minStageWidth is the narrowest the stage column is allowed to wrap to. A
+	// window narrow enough to force this is already unreadable; the floor keeps
+	// the wrap from degenerating into one word per line.
+	minStageWidth = 24
 )
 
 // terminalStatuses are the states a land request settles on. They are keyed off
@@ -192,9 +197,24 @@ func summarize(rows []*Row) error {
 //
 // Column widths only ever grow, so a value that turns out to be wider than the
 // header does not make the table jitter as rows fill in.
+//
+// No line the renderer emits may exceed the terminal's width. A line that wraps
+// occupies two physical rows, and the in-place redraw moves the cursor back by
+// the number of lines it *emitted* — so one wrapped line desyncs every redraw
+// after it. Everything wide is therefore wrapped deliberately, into lines the
+// renderer counts itself.
 type renderer struct {
 	inPlace bool
 
+	// width is the terminal's width, re-read before every draw. A watch runs for
+	// minutes and a window can be resized inside them, so this is not a property
+	// the process can sample once — see resize.
+	width int
+
+	// size reports the terminal's width and whether it could be read. Held as a
+	// field so a test can drive a resize without a terminal.
+	size func() (int, bool)
+
 	wRequest int
 	wChanges int
 	wElapsed int
@@ -211,18 +231,71 @@ type renderer struct {
 }
 
 func newRenderer() *renderer {
-	info, err := os.Stdout.Stat()
-	tty := err == nil && info.Mode()&os.ModeCharDevice != 0
+	width, sized := terminalSize()
 	return &renderer{
-		inPlace:  tty,
+		// Redrawing in place requires knowing the width to wrap to. A terminal
+		// that will not report its size is therefore treated as a log: emitting
+		// a guessed width into a narrower window is what produces a physically
+		// wrapped line, and the redraw counts the lines it emitted rather than
+		// the lines that appeared, so one of those desyncs every frame after it.
+		inPlace:  sized,
+		width:    width,
+		size:     terminalSize,
 		wRequest: len("REQUEST"),
 		wChanges: len("CHANGES"),
 		wElapsed: len("ELAPSED"),
 		wStage:   len("STAGE"),
 	}
 }
 
+// terminalSize is how wide the output is, in columns, and whether that came
+// from the terminal rather than from the fallback.
+//
+// Asking the terminal is what lets a wide window show a long trail in full,
+// rather than everyone being held to the narrowest window anyone might have.
+// Anything that is not a sized terminal — a pipe, a file, a CI log — falls back
+// to a fixed width, since there is no width to discover and a log wants a
+// stable one anyway.
+func terminalSize() (int, bool) {
+	w, _, err := term.GetSize(int(os.Stdout.Fd()))
+	if err != nil || w <= 0 {
+		return defaultLineWidth, false
+	}
+	return w, true
+}
+
+// lineWidth is the width to render to. It tolerates a renderer built without
+// one — a zero-value renderer in a test — rather than collapsing to nothing.
+func (r *renderer) lineWidth() int {
+	if r.width <= 0 {
+		return defaultLineWidth
+	}
+	return r.width
+}
+
+// resize re-reads the terminal's width before a draw.
+//
+// The width is not a property of the process: a watch runs for minutes and the
+// window can be dragged narrower at any point in them. Sampling once at startup
+// means every frame after a resize is wrapped to a width the window no longer
+// has, and the terminal wraps those lines itself — mid-word, ignoring the
+// column alignment, and without telling the redraw, which then moves the cursor
+// back by fewer lines than actually appeared.
+//
+// Only the width is re-read. Whether output is a terminal at all cannot change
+// under a running process, and re-deciding it per frame would let a transient
+// probe failure switch rendering modes mid-run.
+func (r *renderer) resize() {
+	if !r.inPlace || r.size == nil {
+		return
+	}
+	if w, sized := r.size(); sized {
+		r.width = w
+	}
+}
+
 func (r *renderer) draw(rows []*Row, status string) {
+	r.resize()
 	body := r.body(rows)
 
 	if !r.inPlace {
@@ -245,7 +318,7 @@ func (r *renderer) draw(rows []*Row, status string) {
 		fmt.Printf("\033[K%s\n", line)
 	}
 	fmt.Printf("\033[K\n")
-	fmt.Printf("\033[K  ▸ %s\n", truncate(status, maxLineWidth-4))
+	fmt.Printf("\033[K  ▸ %s\n", truncate(status, r.lineWidth()-4))
 	// Every draw emits the body, one blank line, and the status line; moving
 	// back by exactly this many lines is what keeps the redraw from drifting.
 	r.lastLines = len(body) + 2
@@ -264,7 +337,7 @@ func (r *renderer) body(rows []*Row) []string {
 			rule(r.wRequest), rule(r.wChanges), rule(r.wElapsed), rule(r.wStage)))
 
 	for _, rw := range rows {
-		lines = append(lines, r.rowLine(rw))
+		lines = append(lines, r.rowLines(rw)...)
 		lines = append(lines, r.noteLines(rw)...)
 	}
 	return lines
@@ -282,7 +355,7 @@ func (r *renderer) fit(rows []*Row) {
 		r.wStage = max(r.wStage, utf8.RuneCountInString(rw.stage()))
 	}
 	if r.inPlace {
-		r.wStage = min(r.wStage, max(len("STAGE"), maxLineWidth-r.prefixWidth()))
+		r.wStage = min(r.wStage, r.stageWidth())
 	}
 }
 
@@ -291,7 +364,14 @@ func (r *renderer) prefixWidth() int {
 	return 2 + r.wRequest + 2 + r.wChanges + 2 + r.wElapsed + 2
 }
 
-func (r *renderer) rowLine(rw *Row) string {
+// rowLines renders one row: its columns, and the stage wrapped onto indented
+// continuation lines when the trail does not fit the width.
+//
+// Wrapping rather than cutting is what keeps a long trail readable — the end of
+// it is where the request actually is, so a cut there hides the interesting
+// part. Continuations align under the stage column so the wrapped text reads as
+// one field rather than as new rows.
+func (r *renderer) rowLines(rw *Row) []string {
 	sqid := rw.SQID
 	if sqid == "" {
 		sqid = absent
@@ -302,14 +382,31 @@ func (r *renderer) rowLine(rw *Row) string {
 		r.wRequest, sqid, pad(changes, visible, r.wChanges), r.wElapsed, rw.elapsed())
 
 	tail := rw.stage()
-	if r.inPlace {
-		// Only the tail can overflow, and unlike the changes cell it never holds
-		// escape sequences, so it is the one part safe to cut. The budget comes
-		// from the column widths rather than the rendered prefix, which counts a
-		// hyperlink's escape bytes that take up no space on screen.
-		tail = truncate(tail, maxLineWidth-r.prefixWidth())
+	if !r.inPlace {
+		// A log has no width to respect and is easier to read and grep on one
+		// line, so it takes the trail whole.
+		return []string{prefix + tail}
+	}
+
+	indent := r.prefixWidth()
+	segments := wrap(tail, r.stageWidth())
+	if len(segments) == 0 {
+		return []string{prefix + tail}
+	}
+
+	lines := make([]string, 0, len(segments))
+	lines = append(lines, prefix+segments[0])
+	for _, segment := range segments[1:] {
+		lines = append(lines, strings.Repeat(" ", indent)+"  "+segment)
 	}
-	return prefix + tail
+	return lines
+}
+
+// stageWidth is the room a wrapped stage has. The two columns subtracted are
+// the indent a continuation line carries, so every line of a wrapped stage
+// fits the same budget as the first.
+func (r *renderer) stageWidth() int {
+	return max(minStageWidth, r.lineWidth()-r.prefixWidth()-2)
 }
 
 // noteLines renders a request's error under its row, wrapped and indented to
@@ -324,7 +421,7 @@ func (r *renderer) noteLines(rw *Row) []string {
 	indent := r.prefixWidth()
 	// A piped run spends most of the line on URLs, so the wrap width is floored
 	// rather than allowed to collapse to nothing.
-	width := max(minNoteWidth, maxLineWidth-indent-2)
+	width := max(minNoteWidth, r.lineWidth()-indent-2)
 
 	wrapped := wrap(rw.Note, width)
 	lines := make([]string, 0, len(wrapped))