feat(traces): add live search and cursor pagination to traces search

[gsvigruha]

Summary

• Adds --live to pup traces search, which pins the query window's end to "now" so results are the freshest slice of matching spans available. Correction (2026-08-11): this does NOT confirm bypassing ingestion sampling. It calls the same public Spans Search API as any other query — no separate live endpoint or sampling-related parameter exists in the SDK. A returned span in testing had retained_by: "retention_filter", which points to indexed/sampled retention, not an unsampled bypass. Functionally, --live is equivalent to omitting --to (which already defaults to "now"); it mainly acts as a guardrail against an explicitly-passed stale --to. Whether the web UI's separate "Live" toggle hits a genuinely different (unsampled) backend path is still an open question.
• Adds --cursor to page backwards through older spans; the response's next cursor (meta.page.after) is surfaced back via next_action in agent mode.

Changes

• src/commands/traces.rs — search() now takes cursor: Option<String> and live: bool, forces to=now when --live is set, forwards the cursor into SpansListRequestPage, and surfaces the next cursor in agent-mode metadata.
• src/main.rs — new --cursor and --live flags on pup traces search, updated help/examples.

Testing

• cargo test --bin pup — added test_search_live_forces_to_now (asserts --to is overridden to a fresh millis timestamp) and test_search_sends_cursor_and_surfaces_next_cursor (asserts the cursor is sent in the request body and the next cursor round-trips into response metadata); updated existing limit-validation tests for the new signature.
• cargo fmt --check and cargo clippy -- -D warnings pass.
• Manually verified against staging (datad0g.com) with a release build:
  • pup traces search --live --query="*" --limit=5 returned real spans with start_timestamp essentially at request time — confirms freshness, not sampling bypass (see correction above).
  • pup traces search --live --query="*" --limit=3 --agent returned truncated: true and a next_action with a ready-to-use --cursor="..." hint.
  • Re-ran with --cursor="<from next_action>" and confirmed the second page returned distinct, strictly older span IDs than the first page's boundary — correct backward pagination, no duplicates.
  • Confirmed the exhausted-results case: a query matching zero spans returns no next_action/truncated.
  • Hit a transient 429 Too many pending queries on the very first staging call (org-level throttling, unrelated to this change); succeeded on retry.

Follow-up: a fix for the shipped --live CLI help text (still claims an "unsampled" buffer) is coming in a separate PR.

---

🤖 Generated with Claude Code