feat: terminal cell "brick-laying"

ask:
one small change I want to get in with this feature set, prob doesn't need a ticket... but when the "terminal view" of htop to terminal was implemented, it's printing each node out line-by-line... which is to be expected. But can we make this behavior from a '-l --list' flag and instead we "wrap" these outputs into "cells" across the terminal and then wrap/stack those like "bricks" It gets difficult because we don't want their positions changing randomly... and also the terminal is drawn line by line, so we'd have to get clever with curses or something to accomplish this maybe? If this is _not_ a small change, maybe we do need to plan this out in a ticket?

codex-5.5-medium:
Worked for 1m 46s
Implemented it as a small change, no new ticket needed.

Terminal mirror behavior now:

Default: renders nodes as stable, sorted “brick” cells across the terminal width.
-l / --list: keeps the previous vertical list rendering.
Details:

Uses deterministic name sorting, so nodes do not jump around randomly.
Packs cells based on COLUMNS, falling back to width 100.
Composes the full frame as text before redraw, so no curses dependency is needed.
Verification:

GOCACHE=/tmp/psstd-go-build go test ./... passes.

Author: centerorbit

README.md

@@ -49,6 +49,7 @@ export PSSTD_SEEDS="10.0.1.20:7946,10.0.1.21:7946" # explicit peer sync addresse
 export PSSTD_DB="./data"                          # local state directory
 export PSSTD_WEB="true"                           # set false for sync-only nodes
 export PSSTD_NODE_NAME="rack-a-01"                # optional stable node identity override
+export PSSTD_NODE_TTL="15s"                       # how long this node's heartbeat stays online
 ./psstd
 ```
 
@@ -57,6 +58,10 @@ By default, psstd uses the OS hostname as the node identity. Set
 would otherwise publish the same hostname. The override must be non-empty and
 must not contain whitespace.
 
+Each node publishes its own heartbeat TTL with `PSSTD_NODE_TTL`. Shorter values
+make stale/offline indication react faster; longer values are better for slow or
+lossy networks. The default is `15s`, and values must be at least `2s`.
+
 ## Discovery
 
 | Environment | How nodes find each other |

main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"flag"
 	"fmt"
 	"log"
 	"net"
@@ -15,6 +16,10 @@ import (
 	"github.com/hashicorp/memberlist"
 )
 
+type cliOptions struct {
+	List bool
+}
+
 const (
 	envDB       = "PSSTD_DB"
 	envHTTP     = "PSSTD_HTTP"
@@ -23,16 +28,22 @@ const (
 	envHTTPAd   = "PSSTD_ADVERTISE_HTTP"
 	envWeb      = "PSSTD_WEB" // "true" to enable HTTP, default true
 	envNodeName = "PSSTD_NODE_NAME"
+	envNodeTTL  = "PSSTD_NODE_TTL"
 	gossipPort  = 7946
 	httpPort    = 8080
 )
 
 func main() {
+	opts := parseCLI(os.Args[1:])
 	hostname, _ := os.Hostname()
 	nodeName, err := nodeNameFromEnv(hostname)
 	if err != nil {
 		log.Fatalf("node name: %v", err)
 	}
+	nodeTTL, err := nodeTTLFromEnv()
+	if err != nil {
+		log.Fatalf("node ttl: %v", err)
+	}
 
 	dbPath := envOr(envDB, "./data")
 	httpAddr := envOr(envHTTP, fmt.Sprintf(":%d", httpPort))
@@ -52,7 +63,7 @@ func main() {
 	if err != nil {
 		if pebbleLockHeld(err) {
 			log.Printf("psstd already appears to own %s; starting terminal mirror instead", dbPath)
-			runTerminalMirror(nodeName, gossipAddr, seeds)
+			runTerminalMirror(nodeName, gossipAddr, seeds, opts.List)
 			return
 		}
 		log.Fatalf("pebble open: %v", err)
@@ -84,7 +95,7 @@ func main() {
 			}
 			db = nil
 			log.Printf("psstd already appears to be listening on %s; starting terminal mirror instead", gossipAddr)
-			runTerminalMirror(nodeName, gossipAddr, seeds)
+			runTerminalMirror(nodeName, gossipAddr, seeds, opts.List)
 			return
 		}
 		log.Fatalf("memberlist create: %v", err)
@@ -99,29 +110,28 @@ func main() {
 	// 2. Scan for existing peers (mDNS + any explicit seeds)
 	discovered := discoverPeers()
 	allSeeds := append(seeds, discovered...)
-	logStartupConfig(startupConfig{
-		NodeName:   nodeName,
-		DBPath:     dbPath,
-		HTTPAddr:   httpAddr,
-		WebURL:     webURL,
-		GossipAddr: gossipAddr,
-		WebEnabled: webEnabled,
-		Version:    appVersion,
-		SeedCount:  len(seeds),
-		MDNSCount:  len(discovered),
-	})
+	joinedPeers := 0
+	joinErr := error(nil)
 	if len(allSeeds) > 0 {
-		if n, err := list.Join(allSeeds); err != nil {
-			log.Printf("join warning (joined %d): %v", n, err)
-		} else {
-			log.Printf("joined cluster, %d peer(s)", n)
-		}
-	} else {
-		log.Println("no peers found — running solo, will be discovered by others")
+		joinedPeers, joinErr = list.Join(allSeeds)
 	}
+	logStartupConfig(startupConfig{
+		NodeName:    nodeName,
+		DBPath:      dbPath,
+		HTTPAddr:    httpAddr,
+		WebURL:      webURL,
+		GossipAddr:  gossipAddr,
+		WebEnabled:  webEnabled,
+		Version:     appVersion,
+		NodeTTL:     nodeTTL,
+		SeedCount:   len(seeds),
+		MDNSCount:   len(discovered),
+		JoinedPeers: joinedPeers,
+		JoinErr:     joinErr,
+	})
 
 	// ── Stats heartbeat ─────────────────────────────────────────────────────
-	go statsLoop(nodeName, webURL, appVersion, db, delegate)
+	go statsLoop(nodeName, webURL, appVersion, nodeTTL, db, delegate)
 
 	// ── HTTP ─────────────────────────────────────────────────────────────────
 	if webEnabled {
@@ -135,21 +145,44 @@ func main() {
 	}
 }
 
+func parseCLI(args []string) cliOptions {
+	fs := flag.NewFlagSet("psstd", flag.ExitOnError)
+	fs.SetOutput(os.Stderr)
+	var opts cliOptions
+	fs.BoolVar(&opts.List, "l", false, "render terminal mirror as a vertical node list")
+	fs.BoolVar(&opts.List, "list", false, "render terminal mirror as a vertical node list")
+	_ = fs.Parse(args)
+	return opts
+}
+
 type startupConfig struct {
-	NodeName   string
-	DBPath     string
-	HTTPAddr   string
-	WebURL     string
-	GossipAddr string
-	WebEnabled bool
-	Version    string
-	SeedCount  int
-	MDNSCount  int
+	NodeName    string
+	DBPath      string
+	HTTPAddr    string
+	WebURL      string
+	GossipAddr  string
+	WebEnabled  bool
+	Version     string
+	NodeTTL     time.Duration
+	SeedCount   int
+	MDNSCount   int
+	JoinedPeers int
+	JoinErr     error
 }
 
 func logStartupConfig(cfg startupConfig) {
-	log.Printf("psstd startup: version=%s node=%s db=%s web=%t http=%s advertise=%s gossip=%s seeds=%d mdns=%d",
-		cfg.Version, cfg.NodeName, cfg.DBPath, cfg.WebEnabled, cfg.HTTPAddr, cfg.WebURL, cfg.GossipAddr, cfg.SeedCount, cfg.MDNSCount)
+	log.Print(startupSummary(cfg))
+}
+
+func startupSummary(cfg startupConfig) string {
+	join := "solo"
+	if cfg.JoinErr != nil {
+		join = fmt.Sprintf("warning joined=%d error=%q", cfg.JoinedPeers, cfg.JoinErr)
+	} else if cfg.JoinedPeers > 0 {
+		join = fmt.Sprintf("joined=%d", cfg.JoinedPeers)
+	}
+	return fmt.Sprintf("psstd startup: version=%s node=%s db=%s web=%t http=%s advertise=%s gossip=%s ttl=%s seeds=%d mdns=%d join=%s",
+		cfg.Version, cfg.NodeName, cfg.DBPath, cfg.WebEnabled, cfg.HTTPAddr, cfg.WebURL, cfg.GossipAddr, cfg.NodeTTL, cfg.SeedCount, cfg.MDNSCount, join)
 }
 
 func pebbleLockHeld(err error) bool {
@@ -168,7 +201,7 @@ func addressInUse(err error) bool {
 		strings.Contains(msg, "bind: only one usage of each socket address")
 }
 
-func runTerminalMirror(hostname, gossipAddr string, seeds []string) {
+func runTerminalMirror(hostname, gossipAddr string, seeds []string, listMode bool) {
 	tmpDir, err := os.MkdirTemp("", "psstd-view-*")
 	if err != nil {
 		log.Fatalf("terminal mirror temp db: %v", err)
@@ -203,7 +236,7 @@ func runTerminalMirror(hostname, gossipAddr string, seeds []string) {
 		log.Printf("terminal mirror joined cluster, %d peer(s)", n)
 	}
 
-	terminalRenderLoop(db)
+	terminalRenderLoop(db, listMode)
 }
 
 func terminalMirrorSeeds(gossipAddr string, seeds []string) []string {
@@ -219,11 +252,11 @@ func terminalMirrorSeeds(gossipAddr string, seeds []string) []string {
 
 // ── Stats loop ───────────────────────────────────────────────────────────────
 
-func statsLoop(hostname, webURL, version string, db *pebble.DB, d *kvDelegate) {
+func statsLoop(hostname, webURL, version string, ttl time.Duration, db *pebble.DB, d *kvDelegate) {
 	ticker := time.NewTicker(2 * time.Second)
 	defer ticker.Stop()
 	for range ticker.C {
-		stats, err := collectStats(hostname, webURL, version)
+		stats, err := collectStats(hostname, webURL, version, ttl)
 		if err != nil {
 			log.Printf("stats error: %v", err)
 			continue
@@ -303,6 +336,21 @@ func nodeNameFromEnv(hostname string) (string, error) {
 	return override, nil
 }
 
+func nodeTTLFromEnv() (time.Duration, error) {
+	value, ok := os.LookupEnv(envNodeTTL)
+	if !ok || value == "" {
+		return defaultNodeTTL, nil
+	}
+	ttl, err := time.ParseDuration(value)
+	if err != nil {
+		return 0, fmt.Errorf("%s must be a duration such as 15s or 1m: %w", envNodeTTL, err)
+	}
+	if ttl < 2*time.Second {
+		return 0, fmt.Errorf("%s must be at least 2s", envNodeTTL)
+	}
+	return ttl, nil
+}
+
 func splitCSV(s string) []string {
 	var out []string
 	for _, p := range strings.Split(s, ",") {

main_test.go

@@ -1,8 +1,11 @@
 package main
 
 import (
+	"errors"
 	"os"
+	"strings"
 	"testing"
+	"time"
 )
 
 func withoutNodeNameEnv(t *testing.T) {
@@ -54,3 +57,77 @@ func TestNodeNameFromEnvRejectsWhitespaceOverride(t *testing.T) {
 		})
 	}
 }
+
+func TestNodeTTLFromEnvDefaultAndOverride(t *testing.T) {
+	t.Setenv(envNodeTTL, "")
+	got, err := nodeTTLFromEnv()
+	if err != nil {
+		t.Fatalf("default ttl: %v", err)
+	}
+	if got != defaultNodeTTL {
+		t.Fatalf("default ttl = %s, want %s", got, defaultNodeTTL)
+	}
+
+	t.Setenv(envNodeTTL, "45s")
+	got, err = nodeTTLFromEnv()
+	if err != nil {
+		t.Fatalf("override ttl: %v", err)
+	}
+	if got != 45*time.Second {
+		t.Fatalf("override ttl = %s, want 45s", got)
+	}
+}
+
+func TestNodeTTLFromEnvRejectsInvalidValues(t *testing.T) {
+	for _, value := range []string{"soon", "1s"} {
+		t.Run(value, func(t *testing.T) {
+			t.Setenv(envNodeTTL, value)
+			if got, err := nodeTTLFromEnv(); err == nil {
+				t.Fatalf("ttl = %s, want error", got)
+			}
+		})
+	}
+}
+
+func TestStartupSummaryIncludesJoinOutcome(t *testing.T) {
+	base := startupConfig{
+		Version:    "v1",
+		NodeName:   "node-a",
+		DBPath:     "./data",
+		HTTPAddr:   ":8080",
+		WebURL:     "http://node-a:8080",
+		GossipAddr: ":7946",
+		WebEnabled: true,
+		NodeTTL:    15 * time.Second,
+		SeedCount:  2,
+		MDNSCount:  1,
+	}
+
+	joined := base
+	joined.JoinedPeers = 3
+	if got := startupSummary(joined); !strings.Contains(got, "join=joined=3") {
+		t.Fatalf("joined summary missing outcome: %s", got)
+	}
+
+	solo := base
+	if got := startupSummary(solo); !strings.Contains(got, "join=solo") {
+		t.Fatalf("solo summary missing outcome: %s", got)
+	}
+
+	warn := base
+	warn.JoinedPeers = 1
+	warn.JoinErr = errors.New("partial join")
+	if got := startupSummary(warn); !strings.Contains(got, `join=warning joined=1 error="partial join"`) {
+		t.Fatalf("warning summary missing outcome: %s", got)
+	}
+}
+
+func TestParseCLIListFlag(t *testing.T) {
+	for _, args := range [][]string{{"-l"}, {"--list"}} {
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			if opts := parseCLI(args); !opts.List {
+				t.Fatalf("List = false, want true")
+			}
+		})
+	}
+}