fix: add pagination support for recap trace list

packages/opencode/src/altimate/observability/tracing.ts

@@ -1000,6 +1000,32 @@ export class Trace {
     }
   }
 
+  /**
+   * List traces with pagination support.
+   * Returns a page of traces plus total count for building pagination UI.
+   */
+  static async listTracesPaginated(
+    dir?: string,
+    options?: { offset?: number; limit?: number },
+  ): Promise<{
+    traces: Array<{ sessionId: string; file: string; trace: TraceFile }>
+    total: number
+    offset: number
+    limit: number
+  }> {
+    const all = await Trace.listTraces(dir)
+    const rawOffset = options?.offset ?? 0
+    const rawLimit = options?.limit ?? 20
+    const offset = Number.isFinite(rawOffset) ? Math.max(0, Math.trunc(rawOffset)) : 0
+    const limit = Number.isFinite(rawLimit) ? Math.max(1, Math.trunc(rawLimit)) : 20
+    return {
+      traces: all.slice(offset, offset + limit),
+      total: all.length,
+      offset,
+      limit,
+    }
+  }
+
   static async loadTrace(sessionId: string, dir?: string): Promise<TraceFile | null> {
     const tracesDir = dir ?? DEFAULT_TRACES_DIR
     try {

packages/opencode/src/cli/cmd/trace.ts

@@ -49,13 +49,23 @@ function truncate(str: string, len: number): string {
 }
 
 // altimate_change start — trace: list session traces (recordings/recaps of agent sessions)
-function listTraces(traces: Array<{ sessionId: string; trace: TraceFile }>, tracesDir?: string) {
-  if (traces.length === 0) {
+function listTraces(
+  traces: Array<{ sessionId: string; trace: TraceFile }>,
+  pagination: { total: number; offset: number; limit: number },
+  tracesDir?: string,
+) {
+  if (traces.length === 0 && pagination.total === 0) {
     UI.println("No traces found. Run a command with tracing enabled:")
     UI.println("  altimate-code run \"your prompt here\"")
     return
   }
 
+  if (traces.length === 0 && pagination.total > 0) {
+    UI.println(`No traces on this page (offset ${pagination.offset} past end of ${pagination.total} traces).`)
+    UI.println(UI.Style.TEXT_DIM + `Try: altimate-code trace list --offset 0 --limit ${pagination.limit}` + UI.Style.TEXT_NORMAL)
+    return
+  }
+
   // Header
   const header = [
     "DATE".padEnd(13),
@@ -97,8 +107,13 @@ function listTraces(traces: Array<{ sessionId: string; trace: TraceFile }>, trac
   }
 
   UI.empty()
-  // altimate_change start — trace: session trace messages
-  UI.println(UI.Style.TEXT_DIM + `${traces.length} trace(s) in ${Trace.getTracesDir(tracesDir)}` + UI.Style.TEXT_NORMAL)
+  // altimate_change start — trace: session trace messages with pagination footer
+  const rangeStart = pagination.offset + 1
+  const rangeEnd = pagination.offset + traces.length
+  UI.println(UI.Style.TEXT_DIM + `Showing ${rangeStart}-${rangeEnd} of ${pagination.total} trace(s) in ${Trace.getTracesDir(tracesDir)}` + UI.Style.TEXT_NORMAL)
+  if (rangeEnd < pagination.total) {
+    UI.println(UI.Style.TEXT_DIM + `Next page: altimate-code trace list --offset ${rangeEnd} --limit ${pagination.limit}` + UI.Style.TEXT_NORMAL)
+  }
   UI.println(UI.Style.TEXT_DIM + "View a trace: altimate-code trace view <session-id>" + UI.Style.TEXT_NORMAL)
   // altimate_change end
 }
@@ -134,6 +149,11 @@ export const TraceCommand = cmd({
         describe: "number of traces to show",
         default: 20,
       })
+      .option("offset", {
+        type: "number",
+        describe: "number of traces to skip (for pagination)",
+        default: 0,
+      })
       .option("live", {
         type: "boolean",
         describe: "auto-refresh the viewer as the trace updates (for in-progress sessions)",
@@ -148,8 +168,16 @@ export const TraceCommand = cmd({
     const tracesDir = (cfg as any).tracing?.dir as string | undefined
 
     if (action === "list") {
-      const traces = await Trace.listTraces(tracesDir)
-      listTraces(traces.slice(0, args.limit || 20), tracesDir)
+      // Use nullish coalescing so an explicit 0 is preserved and reaches
+      // listTracesPaginated() for clamping. `args.offset || 0` would
+      // treat `--offset 0` as unset (no semantic change, harmless), but
+      // `args.limit || 20` would promote `--limit 0` to 20 instead of
+      // letting the API clamp it to 1.
+      const page = await Trace.listTracesPaginated(tracesDir, {
+        offset: args.offset ?? 0,
+        limit: args.limit ?? 20,
+      })
+      listTraces(page.traces, page, tracesDir)
       return
     }
 
@@ -168,7 +196,7 @@ export const TraceCommand = cmd({
       if (!match) {
         UI.error(`Trace not found: ${args.id}`)
         UI.println("Available traces:")
-        listTraces(traces.slice(0, 10), tracesDir)
+        listTraces(traces.slice(0, 10), { total: traces.length, offset: 0, limit: 10 }, tracesDir)
         process.exit(1)
       }
 

packages/opencode/src/cli/cmd/tui/component/dialog-trace-list.tsx

@@ -47,7 +47,16 @@ export function DialogTraceList(props: {
     }
     // altimate_change end
 
-    const items = traces() ?? []
+    // Cap rendered items for TUI perf — DialogSelect creates reactive
+    // nodes per item via <For>, so very large trace directories
+    // (thousands of entries) can cause noticeable lag. Users with more
+    // than MAX_TUI_ITEMS traces should use `altimate-code trace list
+    // --offset N` from the CLI to navigate the full set.
+    const MAX_TUI_ITEMS = 500
+    const allItems = traces() ?? []
+    const items =
+      allItems.length > MAX_TUI_ITEMS ? allItems.slice(0, MAX_TUI_ITEMS) : allItems
+    const truncated = allItems.length > MAX_TUI_ITEMS
     const today = new Date().toDateString()
     const result: Array<{ title: string; value: string; category: string; footer: string }> = []
 
@@ -61,7 +70,7 @@ export function DialogTraceList(props: {
       })
     }
 
-    result.push(...items.slice(0, 50).map((item) => {
+    result.push(...items.map((item) => {
         const rawStartedAt = item.trace.startedAt
         const parsedDate = typeof rawStartedAt === "string" || typeof rawStartedAt === "number"
           ? new Date(rawStartedAt)
@@ -96,6 +105,16 @@ export function DialogTraceList(props: {
         }
       }))
 
+    // Append truncation hint if we capped the list
+    if (truncated) {
+      result.push({
+        title: `... ${allItems.length - MAX_TUI_ITEMS} more not shown`,
+        value: "__truncated__",
+        category: "Older",
+        footer: `Showing ${MAX_TUI_ITEMS} of ${allItems.length} — use CLI --offset to navigate`,
+      })
+    }
+
     return result
   })
 
@@ -113,7 +132,7 @@ export function DialogTraceList(props: {
       options={options()}
       current={props.currentSessionID}
       onSelect={(option) => {
-        if (option.value === "__error__") {
+        if (option.value === "__error__" || option.value === "__truncated__") {
           dialog.clear()
           return
         }

packages/opencode/test/altimate/tracing.test.ts

@@ -737,6 +737,123 @@ describe("Recap — static helpers", () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// listTracesPaginated — pagination boundary math
+// ---------------------------------------------------------------------------
+
+describe("Recap.listTracesPaginated", () => {
+  // Seed a known set of traces in a fresh directory for each test.
+  // A fresh tracer is created per iteration so spans don't accumulate
+  // across startTrace/endTrace cycles — matches the pattern used
+  // elsewhere in this file (see the maxFiles test above).
+  async function seedTraces(count: number, dir: string): Promise<void> {
+    for (let i = 0; i < count; i++) {
+      const tracer = Recap.withExporters([new FileExporter(dir)])
+      tracer.startTrace(`session-${String(i).padStart(4, "0")}`, {
+        prompt: `prompt-${i}`,
+      })
+      await tracer.endTrace()
+    }
+  }
+
+  test("returns empty page when directory has no traces", async () => {
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: 0, limit: 10 })
+    expect(result.traces).toEqual([])
+    expect(result.total).toBe(0)
+    expect(result.offset).toBe(0)
+    expect(result.limit).toBe(10)
+  })
+
+  test("returns a bounded page of the requested size", async () => {
+    await seedTraces(15, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: 0, limit: 5 })
+    expect(result.traces).toHaveLength(5)
+    expect(result.total).toBe(15)
+    expect(result.offset).toBe(0)
+    expect(result.limit).toBe(5)
+  })
+
+  test("applies offset to return later pages", async () => {
+    await seedTraces(10, tmpDir)
+    const page1 = await Recap.listTracesPaginated(tmpDir, { offset: 0, limit: 4 })
+    const page2 = await Recap.listTracesPaginated(tmpDir, { offset: 4, limit: 4 })
+    const page3 = await Recap.listTracesPaginated(tmpDir, { offset: 8, limit: 4 })
+    expect(page1.traces).toHaveLength(4)
+    expect(page2.traces).toHaveLength(4)
+    expect(page3.traces).toHaveLength(2) // only 2 left on the tail
+    // Pages must not overlap
+    const ids = new Set<string>()
+    for (const p of [page1, page2, page3]) {
+      for (const t of p.traces) {
+        expect(ids.has(t.sessionId)).toBe(false)
+        ids.add(t.sessionId)
+      }
+    }
+    expect(ids.size).toBe(10)
+  })
+
+  test("returns empty traces array when offset equals total", async () => {
+    await seedTraces(5, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: 5, limit: 10 })
+    expect(result.traces).toEqual([])
+    expect(result.total).toBe(5)
+    expect(result.offset).toBe(5)
+  })
+
+  test("returns empty traces array when offset exceeds total", async () => {
+    await seedTraces(3, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: 99, limit: 10 })
+    expect(result.traces).toEqual([])
+    expect(result.total).toBe(3)
+    expect(result.offset).toBe(99)
+  })
+
+  test("clamps negative offset to 0", async () => {
+    await seedTraces(5, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: -10, limit: 3 })
+    expect(result.offset).toBe(0)
+    expect(result.traces).toHaveLength(3)
+  })
+
+  test("clamps non-positive limit to 1", async () => {
+    await seedTraces(5, tmpDir)
+    const zero = await Recap.listTracesPaginated(tmpDir, { offset: 0, limit: 0 })
+    expect(zero.limit).toBe(1)
+    expect(zero.traces).toHaveLength(1)
+    const neg = await Recap.listTracesPaginated(tmpDir, { offset: 0, limit: -5 })
+    expect(neg.limit).toBe(1)
+    expect(neg.traces).toHaveLength(1)
+  })
+
+  test("truncates fractional offset and limit to integers", async () => {
+    await seedTraces(10, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, { offset: 2.9, limit: 3.7 })
+    expect(result.offset).toBe(2)
+    expect(result.limit).toBe(3)
+    expect(result.traces).toHaveLength(3)
+  })
+
+  test("clamps NaN offset and limit to defaults", async () => {
+    await seedTraces(5, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir, {
+      offset: NaN,
+      limit: NaN,
+    })
+    expect(result.offset).toBe(0)
+    expect(result.limit).toBe(20) // default
+    expect(result.traces).toHaveLength(5) // all 5 fit in default page
+  })
+
+  test("uses defaults when no options provided", async () => {
+    await seedTraces(3, tmpDir)
+    const result = await Recap.listTracesPaginated(tmpDir)
+    expect(result.offset).toBe(0)
+    expect(result.limit).toBe(20)
+    expect(result.total).toBe(3)
+    expect(result.traces).toHaveLength(3)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // Edge cases — schema integrity
 // ---------------------------------------------------------------------------