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.

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` — 39 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.

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,20 @@ 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, or defaultLineWidth when it will not say.
+	// Read once: a window resized mid-run is rare next to the cost of asking on
+	// every redraw, and the redraw is already bounded by what it last emitted.
+	width int
+
 	wRequest int
 	wChanges int
 	wElapsed int
@@ -215,13 +231,38 @@ func newRenderer() *renderer {
 	tty := err == nil && info.Mode()&os.ModeCharDevice != 0
 	return &renderer{
 		inPlace:  tty,
+		width:    terminalWidth(),
 		wRequest: len("REQUEST"),
 		wChanges: len("CHANGES"),
 		wElapsed: len("ELAPSED"),
 		wStage:   len("STAGE"),
 	}
 }
 
+// terminalWidth is how wide the output is, in columns.
+//
+// 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 terminalWidth() int {
+	w, _, err := term.GetSize(int(os.Stdout.Fd()))
+	if err != nil || w <= 0 {
+		return defaultLineWidth
+	}
+	return w
+}
+
+// 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
+}
+
 func (r *renderer) draw(rows []*Row, status string) {
 	body := r.body(rows)
 
@@ -245,7 +286,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 +305,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 +323,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 +332,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 +350,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}
 	}
-	return 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 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 +389,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))

submitqueue/client/view_test.go

@@ -294,7 +294,7 @@ func TestDrawStaysWithinLineWidth(t *testing.T) {
 	out := captureStdout(t, func() { r.draw(rows, strings.Repeat("status ", 40)) })
 	for _, line := range strings.Split(out, "\n") {
 		line = strings.ReplaceAll(line, "\033[K", "")
-		assert.LessOrEqual(t, len([]rune(line)), maxLineWidth, "line too wide: %q", line)
+		assert.LessOrEqual(t, len([]rune(line)), r.lineWidth(), "line too wide: %q", line)
 	}
 }
 
@@ -554,7 +554,7 @@ func TestNoteLinesRenderErrorInFull(t *testing.T) {
 
 	var text strings.Builder
 	for i, line := range lines {
-		assert.LessOrEqual(t, len([]rune(line)), maxLineWidth, "a wrapped note still has to fit the line")
+		assert.LessOrEqual(t, len([]rune(line)), r.lineWidth(), "a wrapped note still has to fit the line")
 		trimmed := strings.TrimLeft(line, " ")
 		if i == 0 {
 			assert.True(t, strings.HasPrefix(trimmed, "↳ "), "the first line is marked")
@@ -567,8 +567,8 @@ func TestNoteLinesRenderErrorInFull(t *testing.T) {
 		"the tail of the error is what says what went wrong; it must survive")
 
 	// The row itself keeps only the trail, so the columns stay aligned.
-	assert.NotContains(t, r.rowLine(failed), "speculator failed")
-	assert.NotContains(t, r.rowLine(failed), "…")
+	assert.NotContains(t, strings.Join(r.rowLines(failed), "\n"), "speculator failed")
+	assert.NotContains(t, strings.Join(r.rowLines(failed), "\n"), "…")
 }
 
 // TestNoteLinesIndentToStageColumn keeps a wrapped error visually attached to
@@ -600,7 +600,7 @@ func TestRowLineAlignment(t *testing.T) {
 	r.fit(rows)
 
 	for _, rw := range rows {
-		shown := []rune(visible(r.rowLine(rw)))
+		shown := []rune(visible(r.rowLines(rw)[0]))
 		require.GreaterOrEqual(t, len(shown), r.prefixWidth())
 		assert.Equal(t, rw.stage(), string(shown[r.prefixWidth():]),
 			"the stage should start at column %d and be rendered whole", r.prefixWidth())
@@ -656,3 +656,106 @@ func head(s string, n int) string {
 	}
 	return s[:n]
 }
+
+// longTrail is the shape that prompted wrapping: every status the pipeline now
+// publishes, which no longer fits a default-width line.
+var longTrail = []string{
+	"accepted", "started", "validating", "validated", "batched",
+	"speculating", "speculated", "building", "built", "landing", "landed",
+}
+
+func TestRowLinesWrapsRatherThanTruncates(t *testing.T) {
+	r := newRenderer()
+	r.inPlace = true
+	rw := &Row{SQID: "demo-queue/1", Submitted: time.Now(), Trail: longTrail}
+	r.fit([]*Row{rw})
+
+	lines := r.rowLines(rw)
+	require.Greater(t, len(lines), 1, "a trail this long has to wrap")
+
+	joined := strings.Join(lines, " ")
+	assert.NotContains(t, joined, "…", "nothing is cut, so there is no ellipsis")
+	for _, status := range longTrail {
+		assert.Contains(t, joined, status, "every status survives the wrap")
+	}
+	assert.Contains(t, lines[len(lines)-1], "landed",
+		"the end of the trail is where the request is; it must be the part that shows")
+}
+
+func TestRowLinesContinuationsAlignUnderTheStage(t *testing.T) {
+	r := newRenderer()
+	r.inPlace = true
+	rw := &Row{SQID: "demo-queue/1", Submitted: time.Now(), Trail: longTrail}
+	r.fit([]*Row{rw})
+
+	lines := r.rowLines(rw)
+	require.Greater(t, len(lines), 1)
+
+	for _, line := range lines[1:] {
+		leading := len(line) - len(strings.TrimLeft(line, " "))
+		assert.GreaterOrEqual(t, leading, r.prefixWidth(),
+			"a continuation sits under the stage column, not under the request id")
+	}
+}
+
+func TestRowLinesFitTheWidth(t *testing.T) {
+	// The redraw moves the cursor back by the number of lines it emitted, so a
+	// line wide enough to wrap physically would desync every redraw after it.
+	widths := []int{80, 100, 120, 200}
+	for _, width := range widths {
+		t.Run(fmt.Sprintf("width %d", width), func(t *testing.T) {
+			r := newRenderer()
+			r.inPlace = true
+			r.width = width
+			rw := &Row{SQID: "demo-queue/1", Submitted: time.Now(), Trail: longTrail}
+			r.fit([]*Row{rw})
+
+			for _, line := range r.rowLines(rw) {
+				assert.LessOrEqual(t, len([]rune(visible(line))), width, "line too wide: %q", line)
+			}
+		})
+	}
+}
+
+func TestRowLinesUseTheWholeWidthBeforeWrapping(t *testing.T) {
+	// The point of asking the terminal how wide it is: a window with room for
+	// the whole trail should show it on one line.
+	r := newRenderer()
+	r.inPlace = true
+	r.width = 240
+	rw := &Row{SQID: "demo-queue/1", Submitted: time.Now(), Trail: longTrail}
+	r.fit([]*Row{rw})
+
+	lines := r.rowLines(rw)
+	assert.Len(t, lines, 1, "a wide terminal needs no wrapping")
+	assert.Contains(t, lines[0], "landed")
+}
+
+func TestRowLinesPipedStayOnOneLine(t *testing.T) {
+	// A log has no width to respect and is easier to read and grep unwrapped.
+	r := newRenderer()
+	r.inPlace = false
+	rw := &Row{SQID: "demo-queue/1", Submitted: time.Now(), Trail: longTrail}
+	r.fit([]*Row{rw})
+
+	lines := r.rowLines(rw)
+	require.Len(t, lines, 1)
+	assert.Contains(t, lines[0], "landed")
+	assert.NotContains(t, lines[0], "…")
+}
+
+func TestStageWidthHasAFloor(t *testing.T) {
+	r := newRenderer()
+	r.inPlace = true
+	r.width = 20
+	r.wRequest, r.wChanges, r.wElapsed = 40, 40, 40
+
+	assert.Equal(t, minStageWidth, r.stageWidth(),
+		"a window too narrow to hold the columns still wraps to something readable")
+}
+
+func TestLineWidthFallsBackWhenUnset(t *testing.T) {
+	// Tests build renderers directly; a zero width must not collapse the table.
+	r := &renderer{inPlace: true}
+	assert.Equal(t, defaultLineWidth, r.lineWidth())
+}