relay-flow 0.2.9-alpha → 0.2.11-alpha

package/README.md

@@ -24,13 +24,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.2.9-alpha
+opencode plugin relay-flow-plugin@0.2.11-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.9-alpha
+pi install npm:relay-flow-plugin@0.2.11-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -91,6 +91,9 @@ running `relay-flow serve --background`.
 ```sh
 relay-flow workflow submit --file examples/minimal-jira-task-workflow.yaml
 relay-flow workflow list
+relay-flow workflow list --json   # stable automation output
+relay-flow run get --ticket PAY-101 # Argo-shaped human inspection view
+relay-flow run get --ticket PAY-101 --json # stable automation output
 ```
 
 Replace the example workflow with
@@ -157,7 +160,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.2.9-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.11-alpha"]
 }
 ```
 
@@ -166,7 +169,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.2.9-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.11-alpha"]
 }
 ```
 
@@ -182,7 +185,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.9-alpha
+pi install npm:relay-flow-plugin@0.2.11-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -678,6 +681,17 @@ One Repo Poller per registered repo (not per workflow) fetches active parent tic
 
 ---
 
+## CLI inspection and automation
+
+Human-readable workflow and run views are intended for interactive operator
+use. Scripts should always pass `--json`; the JSON output is the stable
+machine-readable interface. `run get --ticket <key>` shows metadata,
+conditions, timing, progress, resource-duration placeholders, and the actual
+node-visit tree, including retries and revisits. Scoped `--help` is available
+at the root, group, and leaf command levels. Build information is available
+without a server through `relay-flow version`, `relay-flow --version`, and
+`relay-flow -v`.
+
 ## Development
 
 ```sh

package/cmd/relay-flow/main.go

@@ -17,6 +17,7 @@ import (
 	"os/exec"
 	"os/signal"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"syscall"
 	"time"
@@ -52,6 +53,14 @@ const (
 	exitUsage = 2
 )
 
+// Build metadata has safe local-build defaults and can be replaced by release
+// builds with -ldflags -X main.version=... and friends.
+var (
+	version   = "dev"
+	commit    = "unknown"
+	buildDate = "unknown"
+)
+
 func main() { os.Exit(run(os.Args[1:], os.Stdin)) }
 
 // home returns the relay-flow root, honoring RELAY_FLOW_HOME (tests and
@@ -81,6 +90,13 @@ func run(args []string, stdin io.Reader) int {
 		usage(os.Stderr)
 		return exitUsage
 	}
+	if isVersionArgs(args) {
+		printVersion(os.Stdout, len(args) == 1 && args[0] == "version")
+		return exitOK
+	}
+	if hasHelpArg(args) {
+		return printScopedHelp(args, os.Stdout)
+	}
 	p, err := home()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
@@ -133,6 +149,9 @@ func usage(w io.Writer) {
 	fmt.Fprintln(w, `relay-flow — durable ticket runner
 
 Usage:
+  relay-flow [command] [flags]
+
+Setup and server:
   relay-flow init [--force] [--task-plugin <name> --runner-plugin <name> --harness-plugin <name>]
                    [--executor-plugin <goworkflows|temporal>]
                    [--temporal-address <host:port>] [--temporal-namespace <name>]
@@ -141,21 +160,174 @@ Usage:
   relay-flow serve [--recover] [--debug] [--background]
   relay-flow stop
   relay-flow report
+  relay-flow version | --version | -v
 
+Workflow:
   relay-flow workflow submit --file <path>
   relay-flow workflow remove --name <name>
-  relay-flow workflow list
-  relay-flow workflow get --name <name>
+  relay-flow workflow list [--json]
+  relay-flow workflow get --name <name> [--json]
 
+Repository:
   relay-flow repo register [--name <name> --path <path> --set key=value ...]
   relay-flow repo remove --name <name>
   relay-flow repo list
   relay-flow repo get --name <name>
 
-  relay-flow run list
-  relay-flow run get --ticket <key>
+Run:
+  relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json]
+  relay-flow run get --ticket <key> [--json]
   relay-flow run restart --ticket <key>
-  relay-flow run cancel --ticket <key>`)
+  relay-flow run cancel --ticket <key>
+
+Examples:
+  relay-flow workflow list --json
+  relay-flow run get --ticket PAY-101
+Example: relay-flow run get --ticket PAY-101`)
+}
+
+func isVersionArgs(args []string) bool {
+	return len(args) == 1 && (args[0] == "version" || args[0] == "--version" || args[0] == "-v")
+}
+
+func hasHelpArg(args []string) bool {
+	for _, arg := range args {
+		if arg == "--help" || arg == "-h" {
+			return true
+		}
+	}
+	return false
+}
+
+func printVersion(w io.Writer, long bool) {
+	if !long {
+		fmt.Fprintf(w, "relay-flow %s\n", version)
+		return
+	}
+	fmt.Fprintf(w, "relay-flow %s\n", version)
+	fmt.Fprintf(w, "Commit: %s\n", commit)
+	fmt.Fprintf(w, "Build date: %s\n", buildDate)
+	fmt.Fprintf(w, "Go: %s\n", runtime.Version())
+	fmt.Fprintf(w, "Platform: %s/%s\n", runtime.GOOS, runtime.GOARCH)
+}
+
+func printScopedHelp(args []string, w io.Writer) int {
+	// Help is handled before home/config/client creation. Keep each block
+	// scoped to the requested command instead of dumping the entire surface.
+	path := make([]string, 0, len(args))
+	for _, arg := range args {
+		if arg == "--help" || arg == "-h" {
+			continue
+		}
+		// Command names are positional; once a flag appears, the remaining
+		// tokens are command arguments and must not change the help scope.
+		if strings.HasPrefix(arg, "-") {
+			break
+		}
+		path = append(path, arg)
+	}
+	if len(path) == 0 {
+		usage(w)
+		return exitOK
+	}
+	name := strings.Join(path, " ")
+	switch name {
+	case "init":
+		fmt.Fprintln(w, "Usage: relay-flow init [flags]")
+		fmt.Fprintln(w, "\nInitialize relay-flow and its durable state.")
+		fmt.Fprintln(w, "Flags: --force, --task-plugin, --runner-plugin, --harness-plugin, --executor-plugin")
+		fmt.Fprintln(w, "Example: relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode")
+	case "serve":
+		fmt.Fprintln(w, "Usage: relay-flow serve [--recover] [--debug] [--background]")
+		fmt.Fprintln(w, "\nStart the relay-flow server.")
+		fmt.Fprintln(w, "Example: relay-flow serve --background")
+	case "stop":
+		fmt.Fprintln(w, "Usage: relay-flow stop")
+		fmt.Fprintln(w, "\nStop the running relay-flow server.")
+		fmt.Fprintln(w, "Example: relay-flow stop")
+	case "report":
+		fmt.Fprintln(w, "Usage: relay-flow report < report.json")
+		fmt.Fprintln(w, "\nSubmit one complete structured node report.")
+		fmt.Fprintln(w, "Example: relay-flow report < report.json")
+	case "task":
+		fmt.Fprintln(w, "Usage: relay-flow task <command>")
+		fmt.Fprintln(w, "\nCommands: auth")
+		fmt.Fprintln(w, "Example: relay-flow task auth")
+	case "task auth":
+		fmt.Fprintln(w, "Usage: relay-flow task auth [task-plugin options]")
+		fmt.Fprintln(w, "\nDelegate authentication to the configured task-system plugin.")
+		fmt.Fprintln(w, "Example: relay-flow task auth")
+	case "runtime-register":
+		fmt.Fprintln(w, "Usage: relay-flow runtime-register < session.json")
+		fmt.Fprintln(w, "\nRegister a harness runtime session with the server.")
+		fmt.Fprintln(w, "Example: relay-flow runtime-register < session.json")
+	case "version":
+		fmt.Fprintln(w, "Usage: relay-flow version")
+		fmt.Fprintln(w, "\nPrint release and build metadata without contacting the server.")
+		fmt.Fprintln(w, "Example: relay-flow version")
+	case "workflow":
+		fmt.Fprintln(w, "Usage: relay-flow workflow <command>")
+		fmt.Fprintln(w, "\nCommands: submit, remove, list, get")
+		fmt.Fprintln(w, "Use relay-flow workflow <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
+	case "workflow submit":
+		fmt.Fprintln(w, "Usage: relay-flow workflow submit --file <path>")
+		fmt.Fprintln(w, "\nCreate or replace a validated workflow definition.")
+		fmt.Fprintln(w, "Example: relay-flow workflow submit --file workflow.yaml")
+	case "workflow remove":
+		fmt.Fprintln(w, "Usage: relay-flow workflow remove --name <name>")
+		fmt.Fprintln(w, "\nRemove a workflow with no active runs.")
+		fmt.Fprintln(w, "Example: relay-flow workflow remove --name basicFlow")
+	case "workflow list":
+		fmt.Fprintln(w, "Usage: relay-flow workflow list [--json] [--no-color]")
+		fmt.Fprintln(w, "\nList configured workflows and their latest execution summaries.")
+		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
+	case "workflow get":
+		fmt.Fprintln(w, "Usage: relay-flow workflow get --name <name> [--json] [--no-color]")
+		fmt.Fprintln(w, "\nShow validated static graph and recent runs. Use --json for automation.")
+		fmt.Fprintln(w, "Example: relay-flow workflow get --name basicFlow")
+	case "repo":
+		fmt.Fprintln(w, "Usage: relay-flow repo <command>")
+		fmt.Fprintln(w, "\nCommands: register, remove, list, get")
+		fmt.Fprintln(w, "Use relay-flow repo <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow repo list")
+	case "repo register":
+		fmt.Fprintln(w, "Usage: relay-flow repo register [--name <name> --path <path> --set key=value]")
+		fmt.Fprintln(w, "\nRegister a runner repository and task-system configuration.")
+		fmt.Fprintln(w, "Example: relay-flow repo register --name payments --path /work/payments")
+	case "repo remove", "repo get":
+		fmt.Fprintf(w, "Usage: relay-flow %s --name <name>\n", name)
+		fmt.Fprintf(w, "Example: relay-flow %s --name payments\n", name)
+	case "repo list":
+		fmt.Fprintln(w, "Usage: relay-flow repo list")
+		fmt.Fprintln(w, "\nList registered repositories.")
+		fmt.Fprintln(w, "Example: relay-flow repo list")
+	case "run":
+		fmt.Fprintln(w, "Usage: relay-flow run <command>")
+		fmt.Fprintln(w, "\nCommands: list, get, restart, cancel")
+		fmt.Fprintln(w, "Use relay-flow run <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
+	case "run list":
+		fmt.Fprintln(w, "Usage: relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json] [--no-color]")
+		fmt.Fprintln(w, "\nList durable runs. Use --json for automation.")
+		fmt.Fprintln(w, "Example: relay-flow run list --active --json")
+	case "run get":
+		fmt.Fprintln(w, "Usage: relay-flow run get --ticket <key> [--json] [--no-color]")
+		fmt.Fprintln(w, "\nShow an Argo-shaped execution detail view and actual step visits.")
+		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
+	case "run restart":
+		fmt.Fprintln(w, "Usage: relay-flow run restart --ticket <key>")
+		fmt.Fprintln(w, "\nStart a fresh attempt for a canceled run.")
+		fmt.Fprintln(w, "Example: relay-flow run restart --ticket PAY-101")
+	case "run cancel":
+		fmt.Fprintln(w, "Usage: relay-flow run cancel --ticket <key> [--reason <text>]")
+		fmt.Fprintln(w, "\nPermanently cancel the current execution attempt.")
+		fmt.Fprintln(w, "Example: relay-flow run cancel --ticket PAY-101 --reason "+`"operator request"`)
+	default:
+		fmt.Fprintf(os.Stderr, "unknown help target: %s\n", name)
+		return exitUsage
+	}
+	return exitOK
 }
 
 // --- init / serve delegate to the section-5 composition root ---
@@ -801,21 +973,28 @@ func cmdWorkflow(c *server.Client, args []string) int {
 		return exitOK
 	case "list":
 		fs := flag.NewFlagSet("workflow list", flag.ContinueOnError)
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
-		wfs, err := c.ListWorkflows(context.Background())
+		finishLoading := beginLoading("Loading workflows", *jsonOutput)
+		summaries, err := c.ListWorkflowSummaries(context.Background())
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		for _, wf := range wfs {
-			fmt.Println(wf.Name)
+		if *jsonOutput {
+			return encodeJSON(summaries)
 		}
+		renderWorkflowSummaries(os.Stdout, summaries, cliRenderOptions())
 		return exitOK
 	case "get":
 		fs := flag.NewFlagSet("workflow get", flag.ContinueOnError)
 		name := fs.String("name", "", "workflow name")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
@@ -823,14 +1002,23 @@ func cmdWorkflow(c *server.Client, args []string) int {
 			fmt.Fprintln(os.Stderr, "workflow get: --name is required")
 			return exitUsage
 		}
-		wf, err := c.GetWorkflow(context.Background(), *name)
+		finishLoading := beginLoading("Loading workflow", *jsonOutput)
+		if *jsonOutput {
+			wf, err := c.GetWorkflow(context.Background(), *name)
+			finishLoading(err)
+			if err != nil {
+				fmt.Fprintln(os.Stderr, err)
+				return exitFail
+			}
+			return encodeJSON(wf)
+		}
+		detail, err := c.GetWorkflowDetail(context.Background(), *name)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		enc := json.NewEncoder(os.Stdout)
-		enc.SetIndent("", "  ")
-		_ = enc.Encode(wf)
+		renderWorkflowDetail(os.Stdout, detail, cliRenderOptions())
 		return exitOK
 	}
 	usage(os.Stderr)
@@ -1034,25 +1222,35 @@ func cmdRun(c *server.Client, args []string) int {
 		repoName := fs.String("repo", "", "filter by repo")
 		workflowName := fs.String("workflow", "", "filter by workflow")
 		ticket := fs.String("ticket", "", "filter by ticket")
+		activeOnly := fs.Bool("active", false, "show only active runs")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
-		runs, err := c.ListRuns(context.Background(), runsvc.Filter{
-			Repo:     *repoName,
-			Workflow: *workflowName,
-			Ticket:   *ticket,
-		})
+		var active *bool
+		if *activeOnly {
+			value := true
+			active = &value
+		}
+		filter := runsvc.Filter{Repo: *repoName, Workflow: *workflowName, Ticket: *ticket, Active: active}
+		finishLoading := beginLoading("Loading runs", *jsonOutput)
+		runs, err := c.ListRuns(context.Background(), filter)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		for _, r := range runs {
-			fmt.Println(formatRunListRow(r))
+		if *jsonOutput {
+			return encodeJSON(runs)
 		}
+		renderRunsFiltered(os.Stdout, runs, cliRenderOptions(), filter)
 		return exitOK
 	case "get":
 		fs := flag.NewFlagSet("run get", flag.ContinueOnError)
 		ticket := fs.String("ticket", "", "ticket key")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
@@ -1060,14 +1258,17 @@ func cmdRun(c *server.Client, args []string) int {
 			fmt.Fprintln(os.Stderr, "run get: --ticket is required")
 			return exitUsage
 		}
-		rn, err := c.GetRunByTicket(context.Background(), *ticket)
+		finishLoading := beginLoading("Loading run", *jsonOutput)
+		detail, err := c.GetRunDetailByTicket(context.Background(), *ticket)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		enc := json.NewEncoder(os.Stdout)
-		enc.SetIndent("", "  ")
-		_ = enc.Encode(rn)
+		if *jsonOutput {
+			return encodeJSON(detail)
+		}
+		renderRunDetail(os.Stdout, detail, cliRenderOptions())
 		return exitOK
 	case "restart":
 		fs := flag.NewFlagSet("run restart", flag.ContinueOnError)

package/cmd/relay-flow/observability_test.go

@@ -0,0 +1,204 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	runsvc "github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+func TestRunDetailRendererKeepsPendingAndNestedVisitOrder(t *testing.T) {
+	now := time.Date(2026, 9, 10, 12, 0, 0, 0, time.UTC)
+	started := now.Add(-2 * time.Minute)
+	finished := now.Add(-time.Minute)
+	detail := runsvc.RunDetail{Run: runsvc.Run{
+		ID: "repo/workflow/T-1", Repo: "repo", Workflow: "workflow", State: runsvc.StateWaiting,
+		Ticket: runsvcTicket("T-1"), StartedAt: started,
+	}, Steps: []runsvc.StepEntry{
+		{Sequence: 0, Node: "start", Status: runsvc.StepSucceeded, Depth: 1, StartedAt: &started, FinishedAt: &finished},
+		{Sequence: 1, Node: "coding", Status: runsvc.StepWaiting, Depth: 1, StartedAt: &started},
+		{Sequence: 2, Node: "coding", Status: runsvc.StepFailed, Depth: 2, StartedAt: &started, FinishedAt: &finished, Message: "setup failed", ParentSequence: 1},
+		{Sequence: 3, Node: "end", Status: runsvc.StepPending, Depth: 1},
+	}}
+	var out bytes.Buffer
+	renderRunDetail(&out, detail, renderOptions{ASCII: true, Now: now})
+	text := out.String()
+	for _, want := range []string{"Status:           Waiting", "Conditions:", "Progress:         3/4", "[ ] end", "setup failed", "    `--"} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("rendered detail missing %q:\n%s", want, text)
+		}
+	}
+	if strings.Index(text, "start") > strings.Index(text, "coding") || strings.Index(text, "coding") > strings.Index(text, "end") {
+		t.Fatalf("step order was not preserved:\n%s", text)
+	}
+}
+
+func TestScopedHelpCoversAllCommandLevels(t *testing.T) {
+	for _, args := range [][]string{
+		{"--help"}, {"workflow", "--help"}, {"workflow", "list", "--help"},
+		{"repo", "--help"}, {"repo", "register", "--help"}, {"run", "--help"},
+		{"run", "get", "--help"}, {"task", "--help"}, {"task", "auth", "--help"},
+		{"serve", "--help"}, {"runtime-register", "--help"}, {"version", "--help"},
+	} {
+		var out bytes.Buffer
+		if code := printScopedHelp(args, &out); code != exitOK {
+			t.Fatalf("help %v exit = %d", args, code)
+		}
+		if out.Len() == 0 {
+			t.Fatalf("help %v was empty", args)
+		}
+		if !strings.Contains(out.String(), "Example:") {
+			t.Fatalf("help %v missing example: %q", args, out.String())
+		}
+	}
+	var example bytes.Buffer
+	if code := printScopedHelp([]string{"run", "get", "--help"}, &example); code != exitOK || !strings.Contains(example.String(), "Example:") {
+		t.Fatalf("run get help missing example: %q", example.String())
+	}
+}
+
+func TestFilteredEmptyRunListShowsEffectiveFilters(t *testing.T) {
+	var out bytes.Buffer
+	active := true
+	renderRunsFiltered(&out, nil, renderOptions{ASCII: true}, runsvc.Filter{Repo: "payments", Workflow: "basicFlow", Active: &active})
+	text := out.String()
+	if !strings.Contains(text, "repo=payments") || !strings.Contains(text, "workflow=basicFlow") || !strings.Contains(text, "active=true") || !strings.Contains(text, "0 runs | 0 active | 0 failed") {
+		t.Fatalf("empty filtered output = %q", text)
+	}
+	var workflows bytes.Buffer
+	renderWorkflowSummaries(&workflows, nil, renderOptions{ASCII: true, Width: 120})
+	if !strings.Contains(workflows.String(), "0 workflows | 0 active") {
+		t.Fatalf("empty workflow output = %q", workflows.String())
+	}
+}
+
+func TestRunDetailRendererShowsRetryErrorWhenRunErrorIsEmpty(t *testing.T) {
+	detail := runsvc.RunDetail{Run: runsvc.Run{ID: "repo/workflow/T-RETRY", State: runsvc.StateWaiting, StartedAt: time.Now().UTC()}}
+	detail.Retry = &runsvc.RetryStatus{Attempt: 2, LastError: "runner temporarily unavailable", NextRetryAt: time.Now().UTC().Add(time.Minute)}
+	var out bytes.Buffer
+	renderRunDetail(&out, detail, renderOptions{ASCII: true, Width: 120, Now: time.Now().UTC()})
+	if !strings.Contains(out.String(), "runner temporarily unavailable") || !strings.Contains(out.String(), "RetryScheduled:   True") {
+		t.Fatalf("retry error output = %q", out.String())
+	}
+}
+
+func TestTerminalStepWithUnknownDurationRendersPlaceholder(t *testing.T) {
+	started := time.Now().UTC().Add(-time.Minute)
+	detail := runsvc.RunDetail{Run: runsvc.Run{ID: "repo/workflow/T-UNKNOWN", State: runsvc.StateCompleted, StartedAt: started}, Steps: []runsvc.StepEntry{{Node: "coding", Status: runsvc.StepSucceeded, Depth: 1, StartedAt: &started}}}
+	var out bytes.Buffer
+	renderRunDetail(&out, detail, renderOptions{ASCII: true, Width: 120, Now: time.Now().UTC()})
+	found := false
+	for _, line := range strings.Split(out.String(), "\n") {
+		if strings.Contains(line, "coding") && strings.Contains(line, " - ") {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("unknown terminal duration output = %q", out.String())
+	}
+}
+
+func TestRunDetailRendererPreservesKnownZeroTimingAndResourceValues(t *testing.T) {
+	created := time.Date(2026, 9, 10, 11, 0, 0, 0, time.UTC)
+	started := created.Add(time.Minute)
+	detail := runsvc.RunDetail{Run: runsvc.Run{ID: "repo/workflow/T-2", State: runsvc.StateCompleted, StartedAt: started, FinishedAt: &started}, CreatedAt: &created, Steps: []runsvc.StepEntry{{Node: "end", Status: runsvc.StepSucceeded, Depth: 1, StartedAt: &started, FinishedAt: &started, Resource: "harness"}}}
+	var out bytes.Buffer
+	renderRunDetail(&out, detail, renderOptions{ASCII: true, Now: started})
+	text := out.String()
+	for _, want := range []string{"Created:          2026-09-10 11:00:00 UTC", "Started:          2026-09-10 11:01:00 UTC", "Duration:         0s", "ResourcesDuration: runner 0s, task-system 0s, harness 0s"} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("timing/resource output missing %q:\n%s", want, text)
+		}
+	}
+}
+
+func TestLoadingIndicatorIsSilentForPipedOutput(t *testing.T) {
+	oldStdout, oldStderr := os.Stdout, os.Stderr
+	stdoutR, stdoutW, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	stderrR, stderrW, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout, os.Stderr = stdoutW, stderrW
+	finish := beginLoading("Loading runs", false)
+	finish(nil)
+	_ = stdoutW.Close()
+	_ = stderrW.Close()
+	os.Stdout, os.Stderr = oldStdout, oldStderr
+	stdout, _ := io.ReadAll(stdoutR)
+	stderr, _ := io.ReadAll(stderrR)
+	_ = stdoutR.Close()
+	_ = stderrR.Close()
+	if len(stdout) != 0 || len(stderr) != 0 {
+		t.Fatalf("piped loading output stdout=%q stderr=%q", stdout, stderr)
+	}
+}
+
+func TestNarrowRunDetailOutputDoesNotExceedTerminalWidth(t *testing.T) {
+	detail := runsvc.RunDetail{Run: runsvc.Run{ID: "repo/workflow/T-1", State: runsvc.StateWaiting, StartedAt: time.Now().UTC()}, Steps: []runsvc.StepEntry{{Node: "a-very-long-node-name", Status: runsvc.StepWaiting, Depth: 1, Message: "a very long message"}}}
+	var out bytes.Buffer
+	renderRunDetail(&out, detail, renderOptions{ASCII: true, Width: 40, Now: time.Now().UTC()})
+	for _, line := range strings.Split(strings.TrimSuffix(out.String(), "\n"), "\n") {
+		if len([]rune(line)) > 40 {
+			t.Fatalf("narrow line length=%d: %q", len([]rune(line)), line)
+		}
+	}
+}
+
+func TestBlockedActiveRunCountsAsActiveAndFailed(t *testing.T) {
+	var out bytes.Buffer
+	active := true
+	renderRunsFiltered(&out, []runsvc.Run{{State: runsvc.StateBlocked, Ticket: runsvcTicket("T-BLOCKED"), Workflow: "workflow"}}, renderOptions{ASCII: true, Width: 120}, runsvc.Filter{Active: &active})
+	if !strings.Contains(out.String(), "1 active") || !strings.Contains(out.String(), "1 failed") {
+		t.Fatalf("blocked aggregate = %q", out.String())
+	}
+}
+
+func TestNarrowWorkflowDetailStaysWithinTerminalWidth(t *testing.T) {
+	wf := &workflow.Workflow{Name: "a-very-long-workflow-name", Repos: []string{"a-very-long-repository-name"}, Nodes: map[string]workflow.Node{workflow.StartNode: {}, workflow.EndNode: {}}}
+	var out bytes.Buffer
+	renderWorkflowDetail(&out, server.WorkflowDetail{Workflow: wf}, renderOptions{ASCII: true, Width: 40})
+	for _, line := range strings.Split(strings.TrimSuffix(out.String(), "\n"), "\n") {
+		if len([]rune(line)) > 40 {
+			t.Fatalf("narrow workflow detail line length=%d: %q", len([]rune(line)), line)
+		}
+	}
+}
+
+func TestNarrowWorkflowAndRunListsStayWithinTerminalWidth(t *testing.T) {
+	options := renderOptions{ASCII: true, Width: 40, Now: time.Now().UTC()}
+	var workflows bytes.Buffer
+	renderWorkflowSummaries(&workflows, []server.WorkflowSummary{{Workflow: &workflow.Workflow{Name: "a-very-long-workflow-name", Repos: []string{"a-very-long-repository-name"}}, NodeCount: 7, ActiveRuns: 1}}, options)
+	var runs bytes.Buffer
+	renderRunsFiltered(&runs, []runsvc.Run{{ID: "repo/workflow/T-3", Repo: "a-very-long-repository-name", Workflow: "a-very-long-workflow-name", Ticket: runsvcTicket("T-3"), CurrentNode: "a-very-long-node-name", State: runsvc.StateBlocked, UpdatedAt: options.Now}}, options, runsvc.Filter{Repo: "repo"})
+	for _, text := range []string{workflows.String(), runs.String()} {
+		for _, line := range strings.Split(strings.TrimSuffix(text, "\n"), "\n") {
+			if len([]rune(line)) > options.Width {
+				t.Fatalf("narrow list line length=%d: %q", len([]rune(line)), line)
+			}
+		}
+	}
+}
+
+func TestVersionOutputIsServerIndependent(t *testing.T) {
+	var short, long bytes.Buffer
+	printVersion(&short, false)
+	printVersion(&long, true)
+	if !strings.HasPrefix(short.String(), "relay-flow ") || !strings.Contains(long.String(), "Go:") || !strings.Contains(long.String(), "Platform:") {
+		t.Fatalf("version output short=%q long=%q", short.String(), long.String())
+	}
+}
+
+func runsvcTicket(key string) task.TicketRef {
+	return task.TicketRef{Key: key}
+}