cctally 1.47.0 → 1.49.0

package/bin/_lib_conversation_query.py

@@ -16,7 +16,7 @@ import json as _json
 import os
 import re
 import sqlite3
-from datetime import datetime as _datetime
+from datetime import datetime as _datetime, timezone as _timezone
 
 # Public surface (Plan 2): shipped in the npm tarball + brew formula + public
 # mirror — imported by the dashboard's conversation endpoints at runtime.
@@ -272,6 +272,55 @@ def _subagent_key(source_path):
     return stem or None
 
 
+# §4 1a — nested (grandchild) subagent result parse. The new Claude Code format
+# emits a grandchild's spawn result as STRING content (no structured
+# `agent_id`/`subagent_meta`), with a trailing `agentId: <hash> (use SendMessage
+# …)` line and an OPTIONAL `<usage>` totals wrapper. Anchored on the literal
+# `<usage>` wrapper; tolerant of whitespace/newline variants (re.DOTALL).
+_NESTED_AGENT_ID_RE = re.compile(r"agentId:\s*([0-9a-f]+)")
+_NESTED_USAGE_RE = re.compile(
+    r"<usage>\s*subagent_tokens:\s*(\d+)\s*tool_uses:\s*(\d+)\s*duration_ms:\s*(\d+)\s*</usage>",
+    re.DOTALL,
+)
+
+
+def _parse_nested_agent_result(text):
+    """Nested (grandchild) subagent result: string-content, no structured
+    `agentId` (spec §4 1a). Parse `agentId` (+ OPTIONAL `<usage>` totals) out of
+    the result text. Returns (agent_id, meta) — meta is {} when `<usage>` is
+    absent/clipped past the 16 KB cap, populated with completed totals when
+    present. Returns None when no `agentId` is present (an ordinary result, or a
+    >16 KB clip past the `agentId:` line itself — degrades to a flat card, no
+    mis-link). Linking on `agentId` ALONE is sufficient (Codex P1-B)."""
+    if not text:
+        return None
+    m = _NESTED_AGENT_ID_RE.search(text)
+    if not m:
+        return None
+    meta = {}
+    u = _NESTED_USAGE_RE.search(text)
+    if u:
+        meta["total_tokens"] = int(u.group(1))
+        meta["total_tool_use_count"] = int(u.group(2))
+        meta["total_duration_ms"] = int(u.group(3))
+        meta["status"] = "completed"
+    return m.group(1), meta
+
+
+def _iso_ms(ts):
+    """Epoch milliseconds for an ISO-8601 timestamp string (tolerant of a
+    trailing 'Z'); None on parse failure. Used by §4 1c derived-duration."""
+    if not ts:
+        return None
+    try:
+        dt = _datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=_timezone.utc)
+        return int(dt.timestamp() * 1000)
+    except (ValueError, TypeError):
+        return None
+
+
 def _entry_cost(model, inp, out, cc, cr, cost_usd_raw) -> float:
     """Cost for one session_entries row via the shared pricing helper. Tokens →
     the helper's usage dict. cost_usd_raw is passed as the optional override the
@@ -396,6 +445,30 @@ def _stamp_cache_failures(items):
         running_max[key] = max(rm, cr)
 
 
+def session_cache_rebuild_count(conn, session_id) -> int:
+    """Per-session count of cache-rebuild (cache-failure) turns.
+
+    Single source of truth: assembles the session via the SAME pipeline the
+    reader/outline use and runs the SAME _stamp_cache_failures kernel, then
+    counts flagged items. /outline omits stats.cache_failures when the count is
+    0, so "no flagged items" -> 0 (byte-identical to outline). Stored on the
+    conversation_sessions rollup by _recompute_conversation_sessions; filtered
+    by list_conversations(rebuild_min=...).
+
+    _assemble_session already runs _stamp_cache_failures internally before
+    returning, so the items carry the flag on entry; re-running the kernel here
+    is an idempotent recompute (it only ADDS the key on a flagged turn, never
+    clears one, and the predicate is deterministic over the same items) that
+    keeps the helper correct even if assembly ever stops stamping.
+    """
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return 0
+    items = asm["items"]
+    _stamp_cache_failures(items)
+    return sum(1 for it in items if "cache_failure" in it)
+
+
 def _session_cost_map(conn, session_ids):
     """{session_id: total_cost_usd} for the given sessions. Joins
     conversation_messages turn keys to the single deduped session_entries row
@@ -521,40 +594,135 @@ def _rollup_authoritative(conn) -> bool:
     return not pending
 
 
-def _list_session_rows_rollup(conn, order, limit, offset):
+# --- Browse-list filter predicates (spec §2) ------------------------------
+# The rail filters on four axes (date / project / cost / cache-rebuilds). All
+# four are STORED columns on the conversation_sessions rollup, so the rollup
+# fast path expresses every axis as a parameterized WHERE pushed BEFORE
+# LIMIT/OFFSET (pagination stays correct over the filtered set). The live
+# GROUP BY fallback has no cost/project/rebuild columns, so it expresses ONLY
+# the date axis (via HAVING over MAX(timestamp_utc)) — the rollup-only axes
+# degrade in that brief, self-correcting non-authoritative window (spec §1
+# dual-branch parity). The date predicate compares against the stored
+# last_activity_utc string, so the caller MUST pass UTC-ISO bounds in the same
+# format (...Z) — see bin/_lib_dashboard_dates.parse_filter_date_range.
+_FILTER_KEYS = ("date_from", "date_to", "projects",
+                "cost_min", "cost_max", "rebuild_min")
+# The rollup-only axes — the ones the live fallback cannot express. Used to set
+# the page's filter_degraded flag when one is requested under the live branch.
+_ROLLUP_ONLY_FILTER_KEYS = ("projects", "cost_min", "cost_max", "rebuild_min")
+
+
+def _empty_filters() -> dict:
+    """A no-op filter dict (every axis None) — the unfiltered default and the
+    shape the row-source helpers expect."""
+    return {k: None for k in _FILTER_KEYS}
+
+
+def _rollup_where(filters):
+    """(sql_fragment, params) for the ROLLUP branch — all four axes are stored
+    columns. Returns (" WHERE ...", [params]) or ("", []) when no axis is set.
+    Project IN-list naturally excludes empty/NULL project_label (neither the ''
+    no-cwd sentinel nor a NULL not-yet-filled row matches a real label).
+
+    The date axis is HALF-OPEN: ``date_from`` is an inclusive start-of-day lower
+    bound (``>=``) and ``date_to`` is the EXCLUSIVE start-of-next-day upper bound
+    (``<``) emitted by ``_lib_dashboard_dates.parse_filter_date_range``. The
+    strict ``<`` is load-bearing: it makes the lex compare against the stored
+    mixed-precision ``last_activity_utc`` (whole-second AND millisecond ``...Z``)
+    chronologically correct at the day edge (review Finding 1)."""
+    clauses, params = [], []
+    if filters["date_from"] is not None:
+        clauses.append("last_activity_utc >= ?"); params.append(filters["date_from"])
+    if filters["date_to"] is not None:
+        clauses.append("last_activity_utc < ?"); params.append(filters["date_to"])
+    if filters["projects"]:
+        ph = ",".join("?" for _ in filters["projects"])
+        clauses.append("project_label IN (%s)" % ph); params.extend(filters["projects"])
+    if filters["cost_min"] is not None:
+        clauses.append("cost_usd >= ?"); params.append(filters["cost_min"])
+    if filters["cost_max"] is not None:
+        clauses.append("cost_usd <= ?"); params.append(filters["cost_max"])
+    if filters["rebuild_min"] is not None:
+        clauses.append("cache_rebuild_count >= ?"); params.append(filters["rebuild_min"])
+    return (" WHERE " + " AND ".join(clauses)) if clauses else "", params
+
+
+def _live_having(filters):
+    """(sql_fragment, params) for the LIVE fallback — only the DATE axis is
+    expressible (no cost/project/rebuild columns exist on the raw messages).
+    The rollup's last_activity_utc IS MAX(timestamp_utc), so the date predicate
+    is the same HALF-OPEN bound applied via HAVING over the aggregate: inclusive
+    ``>=`` lower, EXCLUSIVE strict-``<`` upper — kept byte-for-byte in lockstep
+    with ``_rollup_where``'s date axis so both branches agree at the day edge
+    over mixed-precision timestamps (review Finding 1)."""
+    having, params = [], []
+    if filters["date_from"] is not None:
+        having.append("MAX(timestamp_utc) >= ?"); params.append(filters["date_from"])
+    if filters["date_to"] is not None:
+        having.append("MAX(timestamp_utc) < ?"); params.append(filters["date_to"])
+    return (" HAVING " + " AND ".join(having)) if having else "", params
+
+
+def _list_session_rows_rollup(conn, order, limit, offset, filters=None):
     """FAST path: read the pre-aggregated rail rows straight from the
     conversation_sessions rollup (spec §3). No GROUP BY, no temp B-tree for the
     ``recent`` sort. Returns (session_id, msg_count, started, last_activity)
     tuples — the same shape the live aggregate yields, so the downstream
-    assembly is identical. No WHERE is needed: the rollup is non-null by
-    construction (PK NOT NULL; the recompute's GROUP BY already drops NULLs)."""
+    assembly is identical. The optional ``filters`` dict pushes the four-axis
+    browse predicate (date/project/cost/rebuild — all stored columns) into the
+    WHERE BEFORE LIMIT/OFFSET, so ``has_more``/``next_offset`` stay correct over
+    the filtered set."""
+    where, params = _rollup_where(filters or _empty_filters())
     return conn.execute(
         "SELECT session_id, msg_count, "
         "       started_utc AS started, last_activity_utc AS last_activity "
-        "FROM conversation_sessions "
-        "ORDER BY " + order + " LIMIT ? OFFSET ?",
-        (limit + 1, offset),
+        "FROM conversation_sessions"
+        + where +
+        " ORDER BY " + order + " LIMIT ? OFFSET ?",
+        (*params, limit + 1, offset),
     ).fetchall()
 
 
-def _list_session_rows_live(conn, order, limit, offset):
+def _list_session_rows_live(conn, order, limit, offset, filters=None):
     """RETAINED fallback (Codex gate BLOCKER 2): the original live GROUP BY over
     conversation_messages, used while the rollup is not authoritative (the flag
     is set — e.g. an existing install before its first sync, or permanently
     under ``--no-sync``). Byte-identical output to the rollup branch by
-    construction; ``order`` here is the _SORTS_LIVE aggregate expression."""
+    construction; ``order`` here is the _SORTS_LIVE aggregate expression. The
+    optional ``filters`` dict applies ONLY the date axis (via HAVING over
+    MAX(timestamp_utc)); the rollup-only axes (project/cost/rebuild) cannot be
+    expressed here and are dropped — the caller flags filter_degraded."""
+    having, hparams = _live_having(filters or _empty_filters())
     return conn.execute(
         "SELECT session_id, COUNT(*) AS msg_count, "
         "       MIN(timestamp_utc) AS started, MAX(timestamp_utc) AS last_activity "
         "FROM conversation_messages "
         "WHERE session_id IS NOT NULL "
-        "GROUP BY session_id "
-        "ORDER BY " + order + " LIMIT ? OFFSET ?",
-        (limit + 1, offset),
+        "GROUP BY session_id"
+        + having +
+        " ORDER BY " + order + " LIMIT ? OFFSET ?",
+        (*hparams, limit + 1, offset),
     ).fetchall()
 
 
-def list_conversations(conn, *, sort="recent", limit=50, offset=0) -> dict:
+def list_conversation_facets(conn) -> dict:
+    """Distinct projects (+ conversation counts) for the browse filter
+    multi-select (spec §2). Reads the rollup; cheap GROUP BY. Empty/NULL
+    project labels are dropped (a no-cwd session stores '' and a not-yet-filled
+    row stores NULL — neither is a real selectable project). Sorted ascending
+    by label so the popover renders a stable list. Returns
+    ``{"projects": [{"project_label": str, "count": int}, ...]}``."""
+    rows = conn.execute(
+        "SELECT project_label, COUNT(*) FROM conversation_sessions "
+        "WHERE project_label IS NOT NULL AND project_label != '' "
+        "GROUP BY project_label ORDER BY project_label"
+    ).fetchall()
+    return {"projects": [{"project_label": p, "count": n} for p, n in rows]}
+
+
+def list_conversations(conn, *, sort="recent", limit=50, offset=0,
+                       date_from=None, date_to=None, projects=None,
+                       cost_min=None, cost_max=None, rebuild_min=None) -> dict:
     """All-history per-session browse rows (spec §3.1). NOT 365-day bounded.
 
     Reads the conversation_sessions rollup (Task A) when it is authoritative —
@@ -573,12 +741,27 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0) -> dict:
     revalidates every visible tick anyway."""
     limit = max(1, min(int(limit), 200))
     offset = max(0, int(offset))
+    # Browse-list filters (spec §2). The rollup branch expresses all four axes
+    # as column predicates; the live fallback only the date axis, so when a
+    # rollup-only axis is requested under the live branch we flag the page
+    # filter_degraded (a brief, self-correcting non-authoritative window).
+    filters = {
+        "date_from": date_from,
+        "date_to": date_to,
+        "projects": list(projects) if projects else None,
+        "cost_min": cost_min,
+        "cost_max": cost_max,
+        "rebuild_min": rebuild_min,
+    }
+    degraded = False
     if _rollup_authoritative(conn):
         order = _SORTS.get(sort, _SORTS["recent"])
-        rows = _list_session_rows_rollup(conn, order, limit, offset)
+        rows = _list_session_rows_rollup(conn, order, limit, offset, filters)
     else:
         order = _SORTS_LIVE.get(sort, _SORTS_LIVE["recent"])
-        rows = _list_session_rows_live(conn, order, limit, offset)
+        degraded = any(
+            filters[k] is not None for k in _ROLLUP_ONLY_FILTER_KEYS)
+        rows = _list_session_rows_live(conn, order, limit, offset, filters)
     has_more = len(rows) > limit
     rows = rows[:limit]
     session_ids = [r[0] for r in rows]
@@ -601,12 +784,17 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0) -> dict:
         }
         for (sid, msg_count, started, last_activity) in rows
     ]
+    page = {
+        "next_offset": offset + len(conversations) if has_more else None,
+        "has_more": has_more,
+    }
+    if degraded:
+        # The rail surfaces this: project/cost/rebuild filters apply once the
+        # rollup finishes indexing; only the date axis held this page.
+        page["filter_degraded"] = True
     return {
         "conversations": conversations,
-        "page": {
-            "next_offset": offset + len(conversations) if has_more else None,
-            "has_more": has_more,
-        },
+        "page": page,
     }
 
 
@@ -758,6 +946,9 @@ def _assemble_session(conn, session_id):
     spawn_kind = {}     # tool_use id -> subagent_type
     spawn_desc = {}     # tool_use id -> spawning Task description (#193)
     agent_link = {}     # tool_use id -> (agent_id, raw_meta)
+    nested_candidates = []  # §4 1a: (tool_use_id, block) — string-content spawn
+                            # results with no structured agent_id, resolved after
+                            # spawn_kind is complete (text still present pre-fold)
     ask_link = {}       # tool_use id -> (answers, annotations)  (#177 S2)
     bash_link = {}      # tool_use id -> (stderr, interrupted)   (#177 S3)
     web_search_link = {}  # tool_use id -> web_search payload    (#177 S4)
@@ -782,6 +973,11 @@ def _assemble_session(conn, session_id):
                 meta = b.pop("subagent_meta", None)
                 if aid and b.get("tool_use_id") is not None:
                     agent_link[b["tool_use_id"]] = (aid, meta or {})
+                elif b.get("tool_use_id") is not None:
+                    # §4 1a candidate — a tool_result with no structured agentId.
+                    # Resolved AFTER spawn_kind is complete (text still present,
+                    # pre-Phase-2-fold). The block's `text` holds the result body.
+                    nested_candidates.append((b["tool_use_id"], b))
                 ans = b.pop("ask_answers", None)            # #177 S2
                 anno = b.pop("ask_annotations", None)
                 if ans is not None and b.get("tool_use_id") is not None:
@@ -800,6 +996,14 @@ def _assemble_session(conn, session_id):
                 tlist_ = b.pop("task_list", None)
                 if b.get("tool_use_id") is not None and (tid_ is not None or tlist_ is not None):
                     task_link[b["tool_use_id"]] = {"task_id": tid_, "task_list": tlist_}
+    # §4 1a — nested grandchild results: gate the text-parse on the owning
+    # tool_use being a spawn (in spawn_kind), so an ordinary tool result that
+    # merely mentions "agentId" never matches.
+    for _tuid, _block in nested_candidates:
+        if _tuid in spawn_kind and _tuid not in agent_link:
+            parsed = _parse_nested_agent_result(_block.get("text"))
+            if parsed is not None:
+                agent_link[_tuid] = parsed
     subagent_meta = {}
     for _tuid, _kind in spawn_kind.items():
         _link = agent_link.get(_tuid)
@@ -814,6 +1018,24 @@ def _assemble_session(conn, session_id):
                 _entry[_f] = _raw[_f]
         subagent_meta[_aid] = _entry       # agent_id == subagent_key
 
+    # §4 1b — parent linkage: the item HOLDING each linked spawn is the child's
+    # parent thread + placement anchor. tooluse_index[spawn_id] = (item, block);
+    # the item's subagent_key/anchor.uuid were set at build time (available now,
+    # pre-Phase-3). Works for a main parent (subagent_key=None) AND a grandchild
+    # whose parent is a child subagent. spawn_tool_use_id is required because one
+    # assistant item can hold MORE than one spawn (Codex P1-C).
+    for _tuid, (_aid, _raw) in agent_link.items():
+        _entry = subagent_meta.get(_aid)
+        if _entry is None:
+            continue
+        _hit = tooluse_index.get(_tuid)
+        if _hit is None:
+            continue
+        _owner = _hit[0]
+        _entry["parent_subagent_key"] = _owner["subagent_key"]
+        _entry["spawn_uuid"] = _owner["anchor"]["uuid"]
+        _entry["spawn_tool_use_id"] = _tuid
+
     # ---- Phase 2: fold each tool_result item into its owning assistant item ----
     drop = set()                                 # id() of folded placeholder items
     for tr in tool_result_items:
@@ -987,6 +1209,66 @@ def _assemble_session(conn, session_id):
             it.pop("_has_prose", None)
     header_cost = round(header_cost, 6)
 
+    # §4 1c — async completion. A background subagent's launch result carries
+    # status:"async_launched" and NO totals; completion arrives as a separate
+    # <task-notification> meta row (text populated by Phase 4). Join it back, and
+    # derive any totals Claude Code never provided from the child's own thread.
+    _notif_status = {}                       # spawn tool_use_id -> status
+    for it in items:
+        if it["kind"] == "meta" and it.get("meta_kind") == "notification":
+            body = it.get("text") or ""
+            tu = re.search(r"<tool-use-id>([^<]+)</tool-use-id>", body)
+            stx = re.search(r"<status>([^<]+)</status>", body)
+            if tu and stx:
+                _notif_status[tu.group(1).strip()] = stx.group(1).strip()
+    for _tuid, _status in _notif_status.items():
+        _link = agent_link.get(_tuid)
+        if _link is not None and _link[0] in subagent_meta:
+            subagent_meta[_link[0]]["status"] = _status   # upgrades async_launched -> completed
+
+    # Derived totals: any child still missing a count gets it from its own
+    # subagent_key bucket. tool-count = tool_call/tool_use blocks; duration =
+    # (max_ts - min_ts) ms; tokens = sum of per-turn token totals (now stamped).
+    # Authoritative values always win; only missing keys are filled.
+    # Bucket items by subagent_key in ONE document-ordered pass so the loop
+    # below indexes in O(1) instead of re-walking all items per child.
+    _items_by_subagent_key: dict[str, list] = {}
+    for it in items:
+        _sk = it.get("subagent_key")
+        if _sk is not None:
+            _items_by_subagent_key.setdefault(_sk, []).append(it)
+    for _aid, _entry in subagent_meta.items():
+        if all(_entry.get(_f) is not None
+               for _f in ("total_tokens", "total_duration_ms", "total_tool_use_count")):
+            continue
+        _bucket = _items_by_subagent_key.get(_aid)
+        if not _bucket:
+            continue
+        _derived = False
+        if _entry.get("total_tool_use_count") is None:
+            _entry["total_tool_use_count"] = sum(
+                1 for it in _bucket for b in it["blocks"]
+                if b.get("kind") in ("tool_call", "tool_use"))
+            _derived = True
+        if _entry.get("total_duration_ms") is None:
+            _ms = [m for m in (_iso_ms(it.get("ts")) for it in _bucket) if m is not None]
+            if len(_ms) >= 2:
+                _entry["total_duration_ms"] = max(_ms) - min(_ms)
+                _derived = True
+        if _entry.get("total_tokens") is None:
+            _tok, _any = 0, False
+            for it in _bucket:
+                t = it.get("tokens")
+                if t:
+                    _any = True
+                    _tok += (t.get("input", 0) + t.get("output", 0)
+                             + t.get("cache_creation", 0) + t.get("cache_read", 0))
+            if _any:
+                _entry["total_tokens"] = _tok
+                _derived = True
+        if _derived:
+            _entry["totals_derived"] = True
+
     # Stamp cache-failure markers (spec §1) AFTER tokens are on each item and
     # while `items` is still document-ordered (the running-max walk is
     # order-dependent). Healthy turns get no key (absent, not zero). Shared
@@ -1026,6 +1308,20 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
     _pl = _project_label(_latest(logical, 10))
     _title = _session_titles_map(conn, [session_id]).get(session_id) or _pl or session_id
 
+    # Jump-to-latest target (spec §3): the {session_id, uuid, id} of the
+    # conversation's FINAL rendered turn, sourced from the tail of the
+    # whole-session assembled item list (so it lands on a real grouped item, not
+    # a folded fragment). Codex P2 #4: assembled anchors carry session_id=None
+    # (only the returned PAGE's anchors are patched), so build it EXPLICITLY with
+    # the request session_id rather than copying items[-1]["anchor"] verbatim.
+    # None only for a genuinely empty conversation (an existing session always
+    # has >=1 item, so this stays non-None for any non-None return). Computed on
+    # the unsliced list so it is the SAME regardless of which page was requested.
+    last_anchor = None
+    if items:
+        _la = items[-1]["anchor"]
+        last_anchor = {"session_id": session_id, "uuid": _la["uuid"], "id": _la["id"]}
+
     # Cursor pagination over the item list (anchored to each item's canonical id).
     # A non-None `after` that matches no item's anchor (stale/deleted cursor)
     # yields an EMPTY page — never silently re-serves the head (M1).
@@ -1046,6 +1342,7 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                 "last_activity_utc": logical[-1][2],
                 "cost_usd": header_cost,
                 "models": sorted({r[6] for r in logical if r[6]}),
+                "last_anchor": last_anchor,
                 "items": [],
                 "subagent_meta": subagent_meta,
                 "page": {"next_after": None, "has_more": False},
@@ -1081,6 +1378,7 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
         "last_activity_utc": last[2],
         "cost_usd": header_cost,
         "models": models,
+        "last_anchor": last_anchor,
         "items": page,
         "subagent_meta": subagent_meta,
         "page": {"next_after": next_after, "has_more": has_more},

package/bin/_lib_dashboard_dates.py

@@ -0,0 +1,166 @@
+"""Pure date-range parsing for dashboard browse filters (spec §2).
+
+The CLI's ``_parse_cli_date_range`` is argparse-coupled and returns a CLI exit
+code (Codex pre-plan P1 #3), so the dashboard cannot reuse it directly. This
+module is the decoupled sibling: it maps a ``(date_from, date_to)`` pair to
+UTC-ISO boundary strings that lexicographically compare against the stored
+``last_activity_utc`` / ``MAX(timestamp_utc)`` value, or raises ``ValueError`` —
+which the handler maps to HTTP 400.
+
+HALF-OPEN, precision-safe bounds (Task 2 review Finding 1)
+----------------------------------------------------------
+Stored timestamps are RAW JSONL passthrough of MIXED precision: both
+whole-second ``YYYY-MM-DDTHH:MM:SSZ`` and millisecond
+``YYYY-MM-DDTHH:MM:SS.mmmZ`` occur in real ``~/.claude/projects`` data. A
+lexicographic SQL string compare on those values is only correct if the bounds
+are chosen so the lex order matches the chronological order at the day edges.
+ASCII ``Z`` (0x5A) sorts AFTER ``.`` (0x2E) and after the digits ``0``-``9``
+(0x30-0x39), so a whole-second ``...00:00:00Z`` lower bound and an inclusive
+``...23:59:59.999999Z`` upper bound BOTH mis-compare at the boundaries:
+
+  * a midnight row ``...T00:00:00.000Z`` is wrongly EXCLUDED by ``>=
+    ...T00:00:00Z`` (``.000Z`` < ``00Z`` because ``.`` < ``Z``);
+  * a last-ms row ``...T23:59:59.999Z`` is wrongly EXCLUDED by ``<=
+    ...T23:59:59.999999Z`` (``.999Z`` > ``.999999Z`` because ``Z`` > ``9``);
+  * a whole-second ``...T23:59:59Z`` row is wrongly EXCLUDED by the same upper
+    bound (``Z`` > ``.``).
+
+The fix is a HALF-OPEN interval ``[start_of_day(date_from),
+start_of_next_day(date_to))``:
+
+  * lower bound = start-of-day of ``date_from`` (in ``display.tz`` → UTC),
+    compared with ``>=``;
+  * upper bound = start-of-day of ``(date_to + 1 day)`` (in ``display.tz`` →
+    UTC), compared with a STRICT ``<`` (NOT the old inclusive end-of-day).
+
+Both bounds are formatted with 6-digit microseconds ``...THH:MM:SS.000000Z``.
+The lex algebra then holds for stored values of EVERY precision: ``.000000`` is
+``<=`` any real fractional part and ``Z`` follows it, so a ``>=`` lower bound of
+``<day>T00:00:00.000000Z`` includes the same-day midnight row at any precision,
+and a strict-``<`` upper bound of ``<nextday>T00:00:00.000000Z`` includes every
+same-day row (any precision) while excluding next-day midnight. The SQL callers
+(``_lib_conversation_query._rollup_where`` and ``_live_having``) therefore use
+``last_activity_utc >= ?`` for the lower bound and ``last_activity_utc < ?`` for
+the upper.
+
+Semantics mirror the CLI's display-tz date posture (``docs/dashboard-gotchas``):
+a naive *date-only* bound is interpreted in ``display.tz`` (start-of-day for the
+lower bound, start-of-NEXT-day for the upper), then converted to UTC for the
+stored-UTC comparison; a *full-ISO* bound carries its own explicit offset and
+bypasses the dual-form parse (tz-independent), used as a precise instant.
+"""
+import datetime as dt
+from zoneinfo import ZoneInfo
+
+# Dual-form date spellings the CLI's ``_try_dual_form_date`` accepts for a
+# naive date-only value (no time component): ISO ``YYYY-MM-DD`` and the compact
+# ``YYYYMMDD``. Anything else is rejected as a malformed date.
+_DUAL_FORMS = ("%Y-%m-%d", "%Y%m%d")
+
+
+def _has_explicit_offset(raw):
+    """True iff ``raw`` carries an explicit UTC offset / ``Z`` — i.e. it is a
+    PRECISE instant, not a wall-clock date(-time) needing localization.
+
+    Finding 3: an offset-less ``T`` form like ``2026-06-15T08:30:00`` parses to a
+    NAIVE datetime; the old predicate routed it to the full-ISO bypass and then
+    the day-bound logic overwrote its time, silently discarding ``08:30:00``. We
+    require a trailing ``Z`` or a ``+``/``-`` sign in the TIME portion (after the
+    ``T``) before treating the value as a precise timestamp; an offset-less ``T``
+    falls through to the date-only day-bound path (its date wins, its naive time
+    is intentionally not used as a sub-day cut)."""
+    if raw.endswith("Z"):
+        return True
+    t = raw.find("T")
+    if t == -1:
+        return False
+    # A '+' or '-' in the time portion is an explicit offset (the date portion's
+    # own '-' separators are before the 'T', so they never match here).
+    tail = raw[t + 1:]
+    return "+" in tail or "-" in tail
+
+
+def _parse_one(raw):
+    """``raw`` -> a naive ``datetime`` (date-only / offset-less spelling, to be
+    localized in display.tz by ``_to_utc_iso``) OR an aware ``datetime``
+    (full-ISO spelling WITH an explicit offset, carries its own instant).
+    ``None``/empty passes through as ``None``. Raises ``ValueError`` on an
+    unrecognized spelling.
+
+    Finding 3: only an input with an explicit offset (``Z`` or a ``+``/``-`` in
+    the time portion, or a parsed non-None ``tzinfo``) is treated as a precise
+    instant; an offset-less ``…THH:MM:SS`` is parsed but returned NAIVE so the
+    day-bound localization applies (its date is what matters)."""
+    if raw is None or raw == "":
+        return None
+    # Precise instant: explicit offset present — bypass the dual-form parse so it
+    # stays tz-independent, matching the CLI's full-ISO posture.
+    if _has_explicit_offset(raw):
+        d = dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        if d.tzinfo is not None:
+            return d
+        # Belt-and-suspenders: a recognized-offset spelling that still parsed
+        # naive (should not happen) degrades to the day-bound path below.
+        return d
+    if "T" in raw:
+        # Offset-less datetime (e.g. 2026-06-15T08:30:00) -> NAIVE; the day-bound
+        # path uses only its date (Finding 3 — do not silently keep the time).
+        return dt.datetime.fromisoformat(raw)
+    for fmt in _DUAL_FORMS:
+        try:
+            return dt.datetime.strptime(raw, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"bad date: {raw!r}")
+
+
+def _utc_micro_iso(u):
+    """Format an aware UTC ``datetime`` as the lex-safe boundary string
+    ``YYYY-MM-DDTHH:MM:SS.000000Z`` (always 6-digit microseconds + ``Z``)."""
+    return u.strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
+
+
+def _to_utc_iso(d, tz, *, upper):
+    """An aware-or-naive ``datetime`` -> a half-open UTC-ISO boundary string.
+
+    Naive (date-only / offset-less) value: localized in ``tz``, snapped to
+    start-of-day; for the UPPER bound it is the start of the NEXT day (so the
+    strict-``<`` comparison covers the whole requested last day). Aware value
+    (explicit-offset full-ISO): used as the precise instant verbatim, converted
+    to UTC. Always emits 6-digit-microsecond ``...Z`` so the lex compare is
+    precision-safe against any stored value (see module docstring)."""
+    if d.tzinfo is None:  # naive date-only / offset-less -> localize in display tz
+        d = d.replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=tz)
+        if upper:
+            # start-of-NEXT-day: half-open exclusive upper. Add a day in the LOCAL
+            # zone (DST-correct: re-localize the resulting wall date so a 23/25h
+            # day still lands on the next midnight) before converting to UTC.
+            nxt = (d + dt.timedelta(days=1)).date()
+            d = dt.datetime(nxt.year, nxt.month, nxt.day, tzinfo=tz)
+    u = d.astimezone(dt.timezone.utc)
+    return _utc_micro_iso(u)
+
+
+def parse_filter_date_range(date_from, date_to, *, tz_name):
+    """``(date_from, date_to)`` -> ``(start_iso|None, end_iso|None)``.
+
+    The returned pair is a HALF-OPEN interval ``[start, end)``: callers compare
+    ``stored >= start`` (inclusive lower) and ``stored < end`` (EXCLUSIVE upper —
+    ``end`` is the start of the day AFTER ``date_to``, NOT an inclusive
+    end-of-day). Both bounds are 6-digit-microsecond ``...Z`` strings chosen so a
+    lexicographic compare against the mixed-precision stored timestamps is
+    chronologically correct at the day edges (see the module docstring).
+
+    Each input is an optional ``YYYY-MM-DD`` / ``YYYYMMDD`` (date-only,
+    localized in ``tz_name``), an offset-less ``...THH:MM:SS`` (date-only day
+    bound — its naive time is NOT used, Finding 3), or a full ISO-8601 string
+    WITH an explicit offset (used as a precise instant; the upper stays
+    exclusive). ``tz_name`` is an IANA key (e.g. ``Etc/UTC``,
+    ``America/New_York``); a falsy ``tz_name`` defaults to UTC. Raises
+    ``ValueError`` on a malformed date — the handler maps that to HTTP 400."""
+    tz = ZoneInfo(tz_name) if tz_name else dt.timezone.utc
+    df = _parse_one(date_from)
+    dtt = _parse_one(date_to)
+    start = _to_utc_iso(df, tz, upper=False) if df is not None else None
+    end = _to_utc_iso(dtt, tz, upper=True) if dtt is not None else None
+    return start, end