@kitlangton/motel 0.1.0 → 0.1.2

package/src/services/TelemetryStore.ts

@@ -94,6 +94,7 @@ interface FacetSearch {
 	readonly type: "traces" | "logs"
 	readonly field: string
 	readonly serviceName?: string | null
+	readonly key?: string | null
 	readonly lookbackMinutes?: number
 	readonly limit?: number
 }
@@ -612,41 +613,73 @@ export const TelemetryStoreLive = Layer.effect(
 			const now = yield* Clock.currentTimeMillis
 
 			yield* Effect.sync(() => {
-				let deletedData = false
-				// Time-based retention
 				const cutoff = now - config.otel.retentionHours * 60 * 60 * 1000
-				const deletedSpans = db.query(`DELETE FROM spans WHERE start_time_ms < ?`).run(cutoff) as { changes?: number }
-				const deletedLogs = db.query(`DELETE FROM logs WHERE timestamp_ms < ?`).run(cutoff) as { changes?: number }
-				deletedData = (deletedSpans.changes ?? 0) > 0 || (deletedLogs.changes ?? 0) > 0
 
-				// Size-based retention: if actual data exceeds max, delete oldest 20% of rows.
-				// Use (page_count - freelist_count) to ignore freed-but-not-vacuumed pages;
-				// otherwise a large freelist triggers a deletion death spiral.
+				// Evict at TRACE granularity so we never leave a trace half-gutted
+				// (previous logic deleted oldest 20% of spans, which happily sliced
+				// across traces and corrupted the summary rebuild). Running traces
+				// are protected — only `active_span_count = 0` summaries are in
+				// scope for eviction.
+				const toEvict = new Set<string>()
+
+				// Time-based: completed traces whose last span ended before cutoff.
+				const timeExpired = db.query(
+					`SELECT trace_id FROM trace_summaries WHERE active_span_count = 0 AND ended_at_ms > 0 AND ended_at_ms < ?`,
+				).all(cutoff) as readonly { trace_id: string }[]
+				for (const row of timeExpired) toEvict.add(row.trace_id)
+
+				// Size-based: if actual data exceeds cap, drop oldest 20% of the
+				// remaining completed traces. `(page_count - freelist_count)`
+				// ignores freed-but-not-vacuumed pages so a large freelist doesn't
+				// trigger a deletion death spiral.
 				const pageCount = (db.query(`PRAGMA page_count`).get() as { page_count: number }).page_count
 				const freePages = (db.query(`PRAGMA freelist_count`).get() as { freelist_count: number }).freelist_count
 				const pageSize = (db.query(`PRAGMA page_size`).get() as { page_size: number }).page_size
 				const dbSize = (pageCount - freePages) * pageSize
 				if (dbSize > maxDbSizeBytes) {
-					const spanCount = (db.query(`SELECT COUNT(*) AS c FROM spans`).get() as { c: number }).c
-					const logCount = (db.query(`SELECT COUNT(*) AS c FROM logs`).get() as { c: number }).c
-					const spanCutCount = Math.max(1, Math.floor(spanCount * 0.2))
-					const logCutCount = Math.max(1, Math.floor(logCount * 0.2))
-					db.query(`DELETE FROM spans WHERE rowid IN (SELECT rowid FROM spans ORDER BY start_time_ms ASC LIMIT ?)`).run(spanCutCount)
-					db.query(`DELETE FROM logs WHERE rowid IN (SELECT rowid FROM logs ORDER BY timestamp_ms ASC LIMIT ?)`).run(logCutCount)
-					deletedData = true
+					const completedCount = (db.query(
+						`SELECT COUNT(*) AS c FROM trace_summaries WHERE active_span_count = 0`,
+					).get() as { c: number }).c
+					const traceCutCount = Math.max(1, Math.floor(completedCount * 0.2))
+					const oldest = db.query(
+						`SELECT trace_id FROM trace_summaries WHERE active_span_count = 0 ORDER BY started_at_ms ASC LIMIT ?`,
+					).all(traceCutCount) as readonly { trace_id: string }[]
+					// Set.add dedupes overlap with the time-expired batch above.
+					for (const row of oldest) toEvict.add(row.trace_id)
 				}
 
-				if (deletedData) {
-					db.query(`DELETE FROM span_attributes WHERE NOT EXISTS (SELECT 1 FROM spans WHERE spans.trace_id = span_attributes.trace_id AND spans.span_id = span_attributes.span_id)`).run()
-					db.query(`DELETE FROM log_attributes WHERE NOT EXISTS (SELECT 1 FROM logs WHERE logs.id = log_attributes.log_id)`).run()
+				// Always prune orphan logs (no trace_id) by timestamp — they're
+				// not covered by trace eviction.
+				db.query(`DELETE FROM logs WHERE trace_id IS NULL AND timestamp_ms < ?`).run(cutoff)
+
+				if (toEvict.size === 0) return
+
+				// Batch the trace-id list so the IN placeholders stay under
+				// SQLite's default limit (~999). Each batch wipes every row
+				// reachable from those trace_ids across the cascade tables.
+				const traceIds = Array.from(toEvict)
+				const BATCH_SIZE = 500
+				for (let offset = 0; offset < traceIds.length; offset += BATCH_SIZE) {
+					const batch = traceIds.slice(offset, offset + BATCH_SIZE)
+					const placeholders = batch.map(() => "?").join(",")
+					db.query(`DELETE FROM span_attributes WHERE trace_id IN (${placeholders})`).run(...batch)
 					try {
-						db.query(`DELETE FROM span_operation_fts WHERE NOT EXISTS (SELECT 1 FROM spans WHERE spans.trace_id = span_operation_fts.trace_id AND spans.span_id = span_operation_fts.span_id)`).run()
-						db.query(`DELETE FROM log_body_fts WHERE NOT EXISTS (SELECT 1 FROM logs WHERE logs.id = CAST(log_body_fts.log_id AS INTEGER))`).run()
+						db.query(`DELETE FROM span_operation_fts WHERE trace_id IN (${placeholders})`).run(...batch)
 					} catch {
-						// FTS tables may not exist.
+						// FTS table may not exist on old DBs.
 					}
-					db.query(`DELETE FROM trace_summaries`).run()
-					rebuildTraceSummaries.run()
+					db.query(`DELETE FROM spans WHERE trace_id IN (${placeholders})`).run(...batch)
+					db.query(`DELETE FROM logs WHERE trace_id IN (${placeholders})`).run(...batch)
+					db.query(`DELETE FROM trace_summaries WHERE trace_id IN (${placeholders})`).run(...batch)
+				}
+
+				// Log-side orphans (log_attributes + FTS) are keyed by log.id,
+				// so prune what no longer has a parent log row.
+				db.query(`DELETE FROM log_attributes WHERE NOT EXISTS (SELECT 1 FROM logs WHERE logs.id = log_attributes.log_id)`).run()
+				try {
+					db.query(`DELETE FROM log_body_fts WHERE NOT EXISTS (SELECT 1 FROM logs WHERE logs.id = CAST(log_body_fts.log_id AS INTEGER))`).run()
+				} catch {
+					// FTS table may not exist on old DBs.
 				}
 			})
 		})
@@ -1424,6 +1457,49 @@ export const TelemetryStoreLive = Layer.effect(
 						`).all(...(input.serviceName ? [cutoff, input.serviceName, limit] : [cutoff, limit])) as Array<{ value: string; count: number }>
 						return rows
 					}
+					if (input.field === "attribute_keys") {
+						// Count distinct traces each attribute key appears on, optionally
+						// scoped to a service. Keys with many distinct values (e.g. sessionId,
+						// user id, model) rank higher than keys that are constant across every
+						// trace (service.name, telemetry.sdk.*) — the latter can't discriminate
+						// between traces so they're useless as filters.
+						const params: Array<string | number> = [cutoff]
+						if (input.serviceName) params.push(input.serviceName)
+						params.push(limit)
+						const rows = db.query(`
+							SELECT sa.key AS value,
+							       COUNT(DISTINCT sa.trace_id) AS count,
+							       COUNT(DISTINCT sa.value) AS distinct_values
+							FROM span_attributes sa
+							JOIN spans s ON s.trace_id = sa.trace_id AND s.span_id = sa.span_id
+							WHERE s.start_time_ms >= ?
+							${input.serviceName ? "AND s.service_name = ?" : ""}
+							GROUP BY sa.key
+							ORDER BY (CASE WHEN distinct_values = 1 THEN 1 ELSE 0 END) ASC,
+							         distinct_values DESC,
+							         count DESC,
+							         value ASC
+							LIMIT ?
+						`).all(...params) as Array<{ value: string; count: number; distinct_values: number }>
+						return rows.map((row) => ({ value: row.value, count: row.count }))
+					}
+					if (input.field === "attribute_values") {
+						if (!input.key) return [] as FacetItem[]
+						const params: Array<string | number> = [input.key, cutoff]
+						if (input.serviceName) params.push(input.serviceName)
+						params.push(limit)
+						const rows = db.query(`
+							SELECT sa.value AS value, COUNT(DISTINCT sa.trace_id) AS count
+							FROM span_attributes sa
+							JOIN spans s ON s.trace_id = sa.trace_id AND s.span_id = sa.span_id
+							WHERE sa.key = ? AND s.start_time_ms >= ?
+							${input.serviceName ? "AND s.service_name = ?" : ""}
+							GROUP BY sa.value
+							ORDER BY count DESC, value ASC
+							LIMIT ?
+						`).all(...params) as Array<{ value: string; count: number }>
+						return rows
+					}
 				}
 
 				return [] as FacetItem[]

package/src/services/TraceQueryService.ts

@@ -8,6 +8,8 @@ export class TraceQueryService extends Context.Service<
 		readonly listServices: Effect.Effect<readonly string[], Error>
 		readonly listRecentTraces: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceItem[], Error>
 		readonly listTraceSummaries: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceSummaryItem[], Error>
+		readonly searchTraceSummaries: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly TraceSummaryItem[], Error>
+		readonly listFacets: (input: { readonly type: "traces" | "logs"; readonly field: string; readonly serviceName?: string | null; readonly key?: string | null; readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly { readonly value: string; readonly count: number }[], Error>
 		readonly searchTraces: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly TraceItem[], Error>
 		readonly traceStats: (input: { readonly groupBy: string; readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"; readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly { readonly group: string; readonly value: number; readonly count: number }[], Error>
 		readonly getTrace: (traceId: string) => Effect.Effect<TraceItem | null, Error>
@@ -60,6 +62,8 @@ export const TraceQueryServiceLive = Layer.effect(
 			listServices,
 			listRecentTraces,
 			listTraceSummaries,
+			searchTraceSummaries: store.searchTraceSummaries,
+			listFacets: store.listFacets,
 			searchTraces: store.searchTraces,
 			traceStats: store.traceStats,
 			getTrace,

package/src/ui/AttrFilterModal.tsx

@@ -0,0 +1,120 @@
+import { RGBA, TextAttributes } from "@opentui/core"
+import { BlankRow, TextLine } from "./primitives.tsx"
+import { colors } from "./theme.ts"
+import { fitCell, truncateText } from "./format.ts"
+import type { AttrFacetState, AttrPickerMode } from "./state.ts"
+
+export interface AttrFilterModalProps {
+	readonly width: number
+	readonly height: number
+	readonly mode: Exclude<AttrPickerMode, "off">
+	readonly input: string
+	readonly selectedIndex: number
+	readonly selectedKey: string | null
+	readonly state: AttrFacetState
+	readonly onClose: () => void
+}
+
+// Filter + rank facet rows by the user's current input so typing is
+// responsive even on large key sets. Values list skips this — attribute
+// values are usually opaque ids that users paste in whole.
+export const filterFacets = (
+	rows: readonly { readonly value: string; readonly count: number }[],
+	input: string,
+): readonly { readonly value: string; readonly count: number }[] => {
+	const needle = input.trim().toLowerCase()
+	if (!needle) return rows
+	return rows.filter((row) => row.value.toLowerCase().includes(needle))
+}
+
+export const AttrFilterModal = ({
+	width,
+	height,
+	mode,
+	input,
+	selectedIndex,
+	selectedKey,
+	state,
+	onClose,
+}: AttrFilterModalProps) => {
+	const panelWidth = Math.min(92, Math.max(60, width - 10))
+	const left = Math.max(2, Math.floor((width - panelWidth) / 2))
+	const top = Math.max(1, Math.floor(height / 6))
+	const innerWidth = panelWidth - 4
+	const rows = filterFacets(state.data, input)
+	const clampedIndex = rows.length === 0 ? 0 : Math.max(0, Math.min(selectedIndex, rows.length - 1))
+	const visibleRowCount = Math.max(5, Math.min(18, height - top - 8))
+	const windowStart = Math.max(0, clampedIndex - Math.floor(visibleRowCount / 2))
+	const windowEnd = Math.min(rows.length, windowStart + visibleRowCount)
+	const windowed = rows.slice(windowStart, windowEnd)
+
+	const title = mode === "keys"
+		? "Filter traces by attribute key"
+		: `Filter · ${truncateText(selectedKey ?? "", innerWidth - 14)}`
+
+	const hint = mode === "keys"
+		? "type to narrow · ↑↓ move · enter select · esc cancel"
+		: "type to narrow · ↑↓ move · enter apply · backspace keys · esc cancel"
+
+	const countWidth = 7
+	const valueWidth = Math.max(10, innerWidth - countWidth - 1)
+
+	const renderRow = (row: { readonly value: string; readonly count: number }, isSelected: boolean) => {
+		const label = fitCell(row.value, valueWidth)
+		const count = String(row.count).padStart(countWidth - 1) + " "
+		if (isSelected) {
+			return (
+				<TextLine fg={colors.text} bg={colors.selectedBg}>
+					<span fg={colors.accent} attributes={TextAttributes.BOLD}>{label}</span>
+					<span fg={colors.muted}>{" "}</span>
+					<span fg={colors.muted}>{count}</span>
+				</TextLine>
+			)
+		}
+		return (
+			<TextLine>
+				<span fg={colors.text}>{label}</span>
+				<span fg={colors.muted}>{" "}</span>
+				<span fg={colors.count}>{count}</span>
+			</TextLine>
+		)
+	}
+
+	return (
+		<box position="absolute" zIndex={3000} left={0} top={0} width={width} height={height} backgroundColor={RGBA.fromInts(0, 0, 0, 110)} onMouseUp={onClose}>
+			<box position="absolute" left={left} top={top} width={panelWidth} flexDirection="column" backgroundColor={RGBA.fromInts(20, 20, 28, 255)}>
+				<box paddingLeft={2} paddingRight={2} paddingTop={1} paddingBottom={1} flexDirection="column">
+					<TextLine>
+						<span fg={colors.count} attributes={TextAttributes.BOLD}>{truncateText(title, innerWidth)}</span>
+					</TextLine>
+					<TextLine>
+						<span fg={colors.muted}>{truncateText(hint, innerWidth)}</span>
+					</TextLine>
+					<BlankRow />
+					<TextLine fg={colors.accent}>
+						<span fg={colors.muted}>{"\u203a "}</span>
+						<span fg={colors.text}>{truncateText(input, Math.max(1, innerWidth - 4))}</span>
+						<span fg={colors.accent}>{"\u2588"}</span>
+					</TextLine>
+					<BlankRow />
+					{state.status === "loading" && rows.length === 0 ? (
+						<TextLine><span fg={colors.muted}>loading…</span></TextLine>
+					) : state.error ? (
+						<TextLine><span fg={colors.error}>{truncateText(state.error, innerWidth)}</span></TextLine>
+					) : rows.length === 0 ? (
+						<TextLine><span fg={colors.muted}>no matches</span></TextLine>
+					) : (
+						windowed.map((row, i) => (
+							<box key={row.value} height={1}>
+								{renderRow(row, windowStart + i === clampedIndex)}
+							</box>
+						))
+					)}
+					{rows.length > windowEnd ? (
+						<TextLine><span fg={colors.muted}>{`+${rows.length - windowEnd} more…`}</span></TextLine>
+					) : null}
+				</box>
+			</box>
+		</box>
+	)
+}

package/src/ui/SpanDetailPane.tsx

@@ -30,8 +30,7 @@ export const SpanDetailPane = ({
 	paneWidth: number
 	focused?: boolean
 }) => {
-	const focusIndicator = focused ? "\u25b8 " : ""
-	const headerTitle = `${focusIndicator}SPAN`
+	const headerTitle = "SPAN"
 	const headerRight = span
 		? `${span.status} \u00b7 ${formatDuration(span.durationMs)}${logs.length > 0 ? ` \u00b7 ${logs.length} lg` : ""}`
 		: "no span selected"

package/src/ui/TraceDetailsPane.tsx

@@ -67,8 +67,7 @@ export const TraceDetailsPane = ({
 	const hasTraceSelection = traceSummary !== null
 	const isLoadingTrace = hasTraceSelection && trace === null && traceStatus !== "error"
 
-	const focusIndicator = focused ? "\u25b8 " : ""
-	const headerTitle = `${focusIndicator}TRACE DETAILS`
+	const headerTitle = "TRACE DETAILS"
 	const headerRight = traceMeta
 		? `${traceMeta.errorCount > 0 ? `${traceMeta.errorCount} errors` : traceMeta.isRunning ? "running" : isLoadingTrace ? "loading" : "healthy"} \u00b7 ${formatDuration(traceMeta.durationMs)}${traceLogCount > 0 ? ` \u00b7 ${traceLogCount} logs` : ""}`
 		: traceStatus === "error"
@@ -86,7 +85,6 @@ export const TraceDetailsPane = ({
 	const opLeft = traceMeta?.rootOperationName ?? ""
 	const opGap = Math.max(2, contentWidth - opLeft.length - dateStr.length)
 	const warningCount = traceMeta?.warnings.length ?? 0
-	const firstWarning = traceMeta?.warnings[0] ?? ""
 
 	return (
 		<box flexDirection="column" width={paneWidth} height={bodyLines + TRACE_DETAILS_HEADER_ROWS} overflow="hidden">
@@ -101,23 +99,17 @@ export const TraceDetailsPane = ({
 							<span>{" ".repeat(opGap)}</span>
 							<span fg={colors.muted}>{dateStr}</span>
 						</TextLine>
-						{warningCount > 0 ? (
-							<TextLine>
-								<span fg={colors.defaultService}>{trace.serviceName}</span>
-								<span fg={colors.separator}>{SEPARATOR}</span>
-								<span fg={colors.count}>{trace.spanCount} spans</span>
-								<span fg={colors.separator}>{SEPARATOR}</span>
-								<span fg={colors.error}>{warningCount} warning{warningCount === 1 ? "" : "s"}: {firstWarning}</span>
-							</TextLine>
-						) : (
-							<TextLine>
-								<span fg={colors.defaultService}>{trace.serviceName}</span>
-								<span fg={colors.separator}>{SEPARATOR}</span>
-								<span fg={colors.count}>{trace.spanCount} spans</span>
-								<span fg={colors.separator}>{SEPARATOR}</span>
-								<span fg={colors.muted}>{trace.traceId.slice(0, 16)}</span>
-							</TextLine>
-						)}
+						<TextLine>
+							<span fg={colors.count}>{trace.spanCount} spans</span>
+							{warningCount > 0 ? (
+								<>
+									<span fg={colors.separator}>{SEPARATOR}</span>
+									<span fg={colors.error}>{warningCount} warning{warningCount === 1 ? "" : "s"}</span>
+								</>
+							) : null}
+							<span fg={colors.separator}>{SEPARATOR}</span>
+							<span fg={colors.muted}>{trace.traceId}</span>
+						</TextLine>
 					</box>
 					<Divider width={paneWidth} />
 					<box flexDirection="column" paddingLeft={1} paddingRight={1}>
@@ -143,11 +135,11 @@ export const TraceDetailsPane = ({
 							<span fg={colors.muted}>{dateStr}</span>
 						</TextLine>
 						<TextLine>
-							<span fg={colors.defaultService}>{traceMeta.serviceName}</span>
-							<span fg={colors.separator}>{SEPARATOR}</span>
 							<span fg={colors.count}>{traceMeta.spanCount} spans</span>
 							<span fg={colors.separator}>{SEPARATOR}</span>
 							<span fg={colors.count}>warming adjacent trace...</span>
+							<span fg={colors.separator}>{SEPARATOR}</span>
+							<span fg={colors.muted}>{traceMeta.traceId}</span>
 						</TextLine>
 					</box>
 					<Divider width={paneWidth} />

package/src/ui/TraceList.tsx

@@ -1,9 +1,8 @@
 import { TextAttributes } from "@opentui/core"
-import { memo } from "react"
-import { config } from "../config.ts"
+import { useLayoutEffect, useRef, useState } from "react"
 import type { TraceSummaryItem } from "../domain.ts"
 import { fitCell, formatDuration, lifecycleLabel, relativeTime, traceIndicator, traceIndicatorColor, traceRowId } from "./format.ts"
-import { PlainLine, TextLine } from "./primitives.tsx"
+import { BlankRow, PlainLine, TextLine } from "./primitives.tsx"
 import type { LoadStatus } from "./state.ts"
 import { colors } from "./theme.ts"
 
@@ -12,9 +11,11 @@ const getTraceRowLayout = (contentWidth: number) => {
 	const durationWidth = 8
 	const countWidth = 6
 	const ageWidth = 4
-	// Keep the operation column intentionally capped so the metrics cluster stays
-	// visually closer, but still allow common operation names to fit cleanly.
-	const titleWidth = Math.min(20, Math.max(8, contentWidth - stateWidth - durationWidth - countWidth - ageWidth - 2))
+	// Row layout: state + gap + title + duration + gap + count + gap + age.
+	// Let the title expand to fill whatever width is left so the metrics
+	// cluster lands against the right edge of the pane.
+	const fixed = stateWidth + durationWidth + countWidth + ageWidth + 3
+	const titleWidth = Math.max(8, contentWidth - fixed)
 	return { stateWidth, durationWidth, countWidth, ageWidth, titleWidth }
 }
 
@@ -40,13 +41,17 @@ const TraceRow = ({
 		: trace.rootOperationName
 	const titleColor = selected ? colors.selectedText : trace.isRunning ? colors.warning : colors.text
 
+	// Always surface a duration, including `0ms` for sub-millisecond traces —
+	// a visible duration is easier to scan than a blank column.
+	const durationText = formatDuration(Math.max(0, trace.durationMs))
+
 	return (
 		<box id={traceRowId(trace.traceId)} height={1} onMouseDown={onSelect}>
 			<TextLine fg={selected ? colors.selectedText : colors.text} bg={selected ? colors.selectedBg : undefined}>
 				<span fg={traceIndicatorColor(trace)}>{fitCell(traceIndicator(trace), stateWidth)}</span>
 				<span> </span>
 				<span fg={titleColor}>{fitTraceTitle(title, titleWidth)}</span>
-				<span fg={selected ? colors.accent : colors.count}>{fitCell(trace.durationMs >= 1 ? formatDuration(trace.durationMs) : "", durationWidth, "right")}</span>
+				<span fg={colors.muted}>{fitCell(durationText, durationWidth, "right")}</span>
 				<span> </span>
 				<span fg={colors.muted}>{fitCell(`${trace.spanCount}sp`, countWidth, "right")}</span>
 				<span> </span>
@@ -71,8 +76,53 @@ export interface TraceListProps {
 	readonly onSelectTrace: (traceId: string) => void
 }
 
-export const TraceList = ({
-	showHeader,
+interface TraceListBodyProps extends TraceListProps {
+	readonly viewportRows: number
+}
+
+/**
+ * Header strip that sits above the body (renders the `TRACES 100 · filter: x`
+ * line). Kept as a separate component so the body can live inside a
+ * virtual-windowed box without the header scrolling with it.
+ */
+export const TraceListHeader = ({
+	traces,
+	services,
+	selectedService,
+	filterText,
+	sortMode,
+	totalCount,
+	contentWidth,
+}: TraceListProps) => {
+	const countLabel = totalCount !== undefined && totalCount !== traces.length ? `${traces.length}/${totalCount}` : traces.length > 0 ? String(traces.length) : ""
+	const metaLabel = [
+		filterText ? `filter: ${filterText}` : null,
+		sortMode && sortMode !== "recent" ? `sort: ${sortMode}` : null,
+	].filter((part): part is string => part !== null).join(" · ")
+	const serviceLabel = services.length > 1 && selectedService ? `${services.length} services` : ""
+	const leftLabel = `TRACES${countLabel ? ` ${countLabel}` : ""}${metaLabel ? ` · ${metaLabel}` : ""}`
+	const gap = Math.max(2, contentWidth - leftLabel.length - serviceLabel.length)
+	return (
+		<TextLine>
+			<span fg={colors.accent} attributes={TextAttributes.BOLD}>TRACES</span>
+			{countLabel ? <span fg={colors.muted}>{` ${countLabel}`}</span> : null}
+			{metaLabel ? <span fg={colors.muted}>{` · ${metaLabel}`}</span> : null}
+			<span fg={colors.muted}>{" ".repeat(gap)}</span>
+			<span fg={colors.muted}>{serviceLabel}</span>
+		</TextLine>
+	)
+}
+
+/**
+ * Virtual-windowed body for the trace list. Replaces the previous
+ * opentui <scrollbox> which had a race with opentui's render-time Yoga
+ * layout: useLayoutEffect fires BEFORE the scrollbar's scrollSize has
+ * been updated to reflect new content height, so setting scrollTop after
+ * a refresh got clamped against the stale max. We own the scroll offset
+ * directly as React state and render only the visible rows, eliminating
+ * the race entirely.
+ */
+export const TraceListBody = ({
 	traces,
 	selectedTraceId,
 	status,
@@ -80,41 +130,103 @@ export const TraceList = ({
 	contentWidth,
 	services,
 	selectedService,
-	focused = true,
-	filterText,
-	sortMode,
-	totalCount,
+	viewportRows,
 	onSelectTrace,
-}: { showHeader: boolean } & TraceListProps) => {
-	if (showHeader) {
-		const countLabel = totalCount !== undefined && totalCount !== traces.length ? `${traces.length}/${totalCount}` : traces.length > 0 ? String(traces.length) : ""
-		const metaLabel = [
-			filterText ? `filter: ${filterText}` : null,
-			sortMode && sortMode !== "recent" ? `sort: ${sortMode}` : null,
-		].filter((part): part is string => part !== null).join(" · ")
-		const serviceLabel = services.length > 1 && selectedService
-			? `${services.length} services`
-			: ""
-		const leftLabel = `TRACES${countLabel ? ` ${countLabel}` : ""}${metaLabel ? ` · ${metaLabel}` : ""}`
-		const gap = Math.max(2, contentWidth - leftLabel.length - serviceLabel.length)
-		return (
-			<TextLine>
-				<span fg={colors.accent} attributes={TextAttributes.BOLD}>TRACES</span>
-				{countLabel ? <span fg={colors.muted}>{` ${countLabel}`}</span> : null}
-				{metaLabel ? <span fg={colors.muted}>{` · ${metaLabel}`}</span> : null}
-				<span fg={colors.muted}>{" ".repeat(gap)}</span>
-				<span fg={colors.muted}>{serviceLabel}</span>
-			</TextLine>
-		)
+}: TraceListBodyProps) => {
+	const [scrollOffset, setScrollOffset] = useState(0)
+	// Track (selectedTraceId, its index in `traces`) from the previous render
+	// so we can detect the refresh-shift case (same traceId, new index because
+	// rows were prepended/removed around it) and slide scrollOffset by the
+	// same delta — preserving the selected row's visual position instead of
+	// letting it jump every time auto-refresh pulls in new traces.
+	const lastSelectedIdRef = useRef<string | null>(null)
+	const lastSelectedIndexRef = useRef<number | null>(null)
+	const lastServiceRef = useRef<string | null>(null)
+
+	const viewport = Math.max(1, viewportRows)
+	const maxOffset = Math.max(0, traces.length - viewport)
+
+	useLayoutEffect(() => {
+		// Service change or initial mount: pin to top.
+		if (lastServiceRef.current !== selectedService) {
+			lastServiceRef.current = selectedService
+			lastSelectedIdRef.current = null
+			lastSelectedIndexRef.current = null
+			setScrollOffset(0)
+			return
+		}
+
+		if (!selectedTraceId) {
+			lastSelectedIdRef.current = null
+			lastSelectedIndexRef.current = null
+			return
+		}
+
+		const index = traces.findIndex((t) => t.traceId === selectedTraceId)
+		if (index < 0) {
+			lastSelectedIdRef.current = null
+			lastSelectedIndexRef.current = null
+			return
+		}
+
+		const prevId = lastSelectedIdRef.current
+		const prevIndex = lastSelectedIndexRef.current
+		const isRefreshShift = prevId === selectedTraceId && prevIndex !== null && prevIndex !== index
+
+		setScrollOffset((current) => {
+			let next = current
+			if (isRefreshShift) {
+				// Same row, new position because rows shifted around it — slide
+				// the window by the same delta to keep the row in the same
+				// visible slot.
+				next = current + (index - prevIndex)
+			} else if (index < current) {
+				// Selection moved above the viewport (user pressed k/up or
+				// jumped via gg/home). Snap the top to the selection.
+				next = index
+			} else if (index >= current + viewport) {
+				// Selection moved below the viewport — snap the bottom to it.
+				next = index - viewport + 1
+			}
+			return Math.max(0, Math.min(next, maxOffset))
+		})
+
+		lastSelectedIdRef.current = selectedTraceId
+		lastSelectedIndexRef.current = index
+	}, [traces, selectedTraceId, selectedService, viewport, maxOffset])
+
+	// Mouse wheel moves the scroll window WITHOUT touching selection — lets
+	// the user browse ahead of / behind their selected trace freely.
+	const handleWheel = (event: { scroll?: { direction: string; delta: number }; stopPropagation?: () => void }) => {
+		const info = event.scroll
+		if (!info || traces.length === 0) return
+		const magnitude = Math.max(1, Math.round(info.delta))
+		const signed = info.direction === "up" ? -magnitude : info.direction === "down" ? magnitude : 0
+		if (signed === 0) return
+		setScrollOffset((current) => Math.max(0, Math.min(current + signed, maxOffset)))
+		event.stopPropagation?.()
 	}
 
+	if (status === "loading" && traces.length === 0) {
+		return <PlainLine text="Loading traces..." fg={colors.muted} />
+	}
+	if (status === "error") {
+		return <PlainLine text={error ?? "Could not load traces."} fg={colors.error} />
+	}
+	if (status === "ready" && services.length === 0) {
+		return <PlainLine text="No services reporting yet. Start your app and emit a span." fg={colors.muted} />
+	}
+	if (status === "ready" && selectedService && traces.length === 0) {
+		return <PlainLine text="No traces in the current lookback window." fg={colors.muted} />
+	}
+
+	const windowStart = Math.max(0, Math.min(scrollOffset, maxOffset))
+	const windowTraces = traces.slice(windowStart, windowStart + viewport)
+	const blanks = Math.max(0, viewport - windowTraces.length)
+
 	return (
-		<box flexDirection="column">
-			{status === "loading" && traces.length === 0 ? <PlainLine text="Loading traces..." fg={colors.muted} /> : null}
-			{status === "error" ? <PlainLine text={error ?? "Could not load traces."} fg={colors.error} /> : null}
-			{status === "ready" && services.length === 0 ? <PlainLine text="No services reporting yet. Start your app and emit a span." fg={colors.muted} /> : null}
-			{status === "ready" && selectedService && traces.length === 0 ? <PlainLine text="No traces in the current lookback window." fg={colors.muted} /> : null}
-			{traces.map((trace) => (
+		<box flexDirection="column" onMouseScroll={handleWheel}>
+			{windowTraces.map((trace) => (
 				<TraceRow
 					key={trace.traceId}
 					trace={trace}
@@ -123,6 +235,20 @@ export const TraceList = ({
 					onSelect={() => onSelectTrace(trace.traceId)}
 				/>
 			))}
+			{Array.from({ length: blanks }, (_, i) => (
+				<BlankRow key={`trace-blank-${i}`} />
+			))}
 		</box>
 	)
 }
+
+// Backwards-compatible single-entry wrapper (header + body) for callers
+// that haven't been updated to the split layout yet.
+export const TraceList = ({
+	showHeader,
+	viewportRows,
+	...props
+}: { showHeader: boolean; viewportRows?: number } & TraceListProps) => {
+	if (showHeader) return <TraceListHeader {...props} />
+	return <TraceListBody {...props} viewportRows={viewportRows ?? 20} />
+}