Release v1.1.0

Bug-fix release. Full notes in CHANGELOG.md.

Contributors: @thomasleveil, @jakduch (x2), @Fruhji (x2), @HaydenHaines.
Triage and verification: Claude Code & Codex collab.

Author: phuryn

.gitignore

@@ -1,2 +1,4 @@
 __pycache__/
 server.log
+
+.pr-candidates.md

AGENTS.md

@@ -89,3 +89,14 @@ The entire UI lives in `HTML_TEMPLATE` as a raw string. Chart.js is loaded from
 - `tests/test_scanner.py` and `tests/test_dashboard.py` use `tempfile.NamedTemporaryFile` for an isolated DB; never touch the user's real `~/.claude/usage.db`.
 - The `/api/rescan` test patches `dashboard.DB_PATH` and `scanner.DEFAULT_PROJECTS_DIRS` — keep that contract intact (see commit 8ae2664).
 - On Windows, `~/.claude/` may not exist on a fresh checkout. `get_db` creates the parent dir (`mkdir(parents=True, exist_ok=True)`) — don't remove that or `sqlite3.connect` will fail in CI / fresh installs (commit b5d1e15).
+
+## Respecting contributors
+
+When merging community PRs, **preserve the original author's commit so they get GitHub contributor credit**. In practice:
+
+- `git fetch origin pull/<N>/head:pr-<N>` → `git merge --no-ff pr-<N>` keeps the author commit verbatim inside the merge bubble (don't squash, don't rebase-flatten).
+- For a partial merge — when only one hunk of a PR is wanted — use `git cherry-pick <commit-sha>` against the specific upstream commit so authorship is preserved. If the diff isn't a clean single commit, fall back to applying the hunk manually + adding a `Co-Authored-By: Name <email>` trailer.
+- Improvements that the bot/maintainer makes _on top_ of a contributor's work go in **separate follow-up commits**, not amendments to the contributor's commit.
+- When closing duplicate PRs (multiple authors fixed the same bug independently), thank each one and explain that landing the earliest version isn't a quality judgment.
+
+This applies to all agents working on this repo, not just Claude Code.

CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## 2026-04-09
+## v1.1.0 — 2026-05-28
+
+### Dashboard
+
+- Fix `ReferenceError: cutoff is not defined` in the hourly filter that blanked the entire dashboard (#73, thanks @thomasleveil)
+- Fix hourly chart ignoring the range upper bound for `week` / `month` / `prev-month` ranges
+- Fix 404 on dashboard URLs containing query strings (`?range=...&models=...`) so reloads and bookmarks work, with regression tests (#81, thanks @jakduch)
+- Fix blank dashboard for users whose data only contains non-billable / unknown models, or rows with empty model names: `COALESCE(NULLIF(model, ''), 'unknown')` normalises empty-string models (in both SELECT and GROUP BY so mixed NULL + '' rows collapse to a single "unknown" group), and the default selection falls back to all models when no billable models exist (#109, thanks @HaydenHaines)
+- Use `ThreadingHTTPServer` so a slow `/api/data` no longer blocks other dashboard requests (#79, thanks @jakduch)
+- Add a `Today` range button (#112, thanks @Fruhji)
+
+### Scanner
+
+- Fix incremental scan not updating `first_timestamp` when a newly discovered session's records arrive out of order (#111, thanks @Fruhji)
+
+### Project / docs
+
+- Adopt `AGENTS.md` as the canonical agent guide (shared with Codex); `CLAUDE.md` is now a thin `@AGENTS.md` import
+- Codify the rule that future PR merges must preserve original-author commits (`merge --no-ff` for full merges, `cherry-pick` for partial, `Co-Authored-By` trailers when applying hunks manually)
+- Drop unused `.claude/launch.json`
+
+## v1.0.0 — 2026-04-09
 
 - Fix token counts inflated ~2x by deduplicating streaming events that share the same message ID
 - Fix session cost totals that were inflated when sessions spanned multiple JSONL files

dashboard.py

@@ -5,7 +5,8 @@
 import json
 import os
 import sqlite3
-from http.server import HTTPServer, BaseHTTPRequestHandler
+from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
+from urllib.parse import urlparse
 from pathlib import Path
 from datetime import datetime
 
@@ -20,10 +21,12 @@ def get_dashboard_data(db_path=DB_PATH):
     conn.row_factory = sqlite3.Row
 
     # ── All models (for filter UI) ────────────────────────────────────────────
+    # GROUP BY uses the normalised expression too so NULL and '' don't end up
+    # as two separate "unknown" rows.
     model_rows = conn.execute("""
-        SELECT COALESCE(model, 'unknown') as model
+        SELECT COALESCE(NULLIF(model, ''), 'unknown') as model
         FROM turns
-        GROUP BY model
+        GROUP BY COALESCE(NULLIF(model, ''), 'unknown')
         ORDER BY SUM(input_tokens + output_tokens) DESC
     """).fetchall()
     all_models = [r["model"] for r in model_rows]
@@ -32,14 +35,14 @@ def get_dashboard_data(db_path=DB_PATH):
     daily_rows = conn.execute("""
         SELECT
             substr(timestamp, 1, 10)   as day,
-            COALESCE(model, 'unknown') as model,
+            COALESCE(NULLIF(model, ''), 'unknown') as model,
             SUM(input_tokens)          as input,
             SUM(output_tokens)         as output,
             SUM(cache_read_tokens)     as cache_read,
             SUM(cache_creation_tokens) as cache_creation,
             COUNT(*)                   as turns
         FROM turns
-        GROUP BY day, model
+        GROUP BY day, COALESCE(NULLIF(model, ''), 'unknown')
         ORDER BY day, model
     """).fetchall()
 
@@ -59,12 +62,12 @@ def get_dashboard_data(db_path=DB_PATH):
         SELECT
             substr(timestamp, 1, 10)                  as day,
             CAST(substr(timestamp, 12, 2) AS INTEGER) as hour,
-            COALESCE(model, 'unknown')                as model,
+            COALESCE(NULLIF(model, ''), 'unknown')    as model,
             SUM(output_tokens)                        as output,
             COUNT(*)                                  as turns
         FROM turns
         WHERE timestamp IS NOT NULL AND length(timestamp) >= 13
-        GROUP BY day, hour, model
+        GROUP BY day, hour, COALESCE(NULLIF(model, ''), 'unknown')
         ORDER BY day, hour, model
     """).fetchall()
 
@@ -235,6 +238,7 @@ def get_dashboard_data(db_path=DB_PATH):
   <div class="filter-sep"></div>
   <div class="filter-label">Range</div>
   <div class="range-group">
+    <button class="range-btn" data-range="today" onclick="setRange('today')">Today</button>
     <button class="range-btn" data-range="week" onclick="setRange('week')">This Week</button>
     <button class="range-btn" data-range="month" onclick="setRange('month')">This Month</button>
     <button class="range-btn" data-range="prev-month" onclick="setRange('prev-month')">Prev Month</button>
@@ -481,8 +485,8 @@ def get_dashboard_data(db_path=DB_PATH):
 const MODEL_COLORS = ['#d97757','#4f8ef7','#4ade80','#a78bfa','#fbbf24','#f472b6','#34d399','#60a5fa'];
 
 // ── Time range ─────────────────────────────────────────────────────────────
-const RANGE_LABELS = { 'week': 'This Week', 'month': 'This Month', 'prev-month': 'Previous Month', '7d': 'Last 7 Days', '30d': 'Last 30 Days', '90d': 'Last 90 Days', 'all': 'All Time' };
-const RANGE_TICKS  = { 'week': 7, 'month': 15, 'prev-month': 15, '7d': 7, '30d': 15, '90d': 13, 'all': 12 };
+const RANGE_LABELS = { 'today': 'Today', 'week': 'This Week', 'month': 'This Month', 'prev-month': 'Previous Month', '7d': 'Last 7 Days', '30d': 'Last 30 Days', '90d': 'Last 90 Days', 'all': 'All Time' };
+const RANGE_TICKS  = { 'today': 1, 'week': 7, 'month': 15, 'prev-month': 15, '7d': 7, '30d': 15, '90d': 13, 'all': 12 };
 const VALID_RANGES = Object.keys(RANGE_LABELS);
 
 function rangeIncludesToday(range) {
@@ -498,6 +502,10 @@ def get_dashboard_data(db_path=DB_PATH):
   if (range === 'all') return { start: null, end: null };
   const today = new Date();
   const iso = d => d.toISOString().slice(0, 10);
+  if (range === 'today') {
+    const t = iso(today);
+    return { start: t, end: t };
+  }
   if (range === 'week') {
     const day = today.getDay();
     const diffToMon = day === 0 ? 6 : day - 1;
@@ -555,15 +563,21 @@ def get_dashboard_data(db_path=DB_PATH):
 
 function readURLModels(allModels) {
   const param = new URLSearchParams(window.location.search).get('models');
-  if (!param) return new Set(allModels.filter(m => isBillable(m)));
+  if (!param) {
+    const billable = allModels.filter(m => isBillable(m));
+    // Fallback: if the user only has non-billable / unknown models (e.g. all
+    // local-LLM runs), default to all models so the dashboard isn't blank.
+    return new Set(billable.length ? billable : allModels);
+  }
   const fromURL = new Set(param.split(',').map(s => s.trim()).filter(Boolean));
   return new Set(allModels.filter(m => fromURL.has(m)));
 }
 
 function isDefaultModelSelection(allModels) {
   const billable = allModels.filter(m => isBillable(m));
-  if (selectedModels.size !== billable.length) return false;
-  return billable.every(m => selectedModels.has(m));
+  const expected = billable.length ? billable : allModels;
+  if (selectedModels.size !== expected.length) return false;
+  return expected.every(m => selectedModels.has(m));
 }
 
 function buildFilterUI(allModels) {
@@ -742,7 +756,7 @@ def get_dashboard_data(db_path=DB_PATH):
 
   // Hourly aggregation (filtered by model + range, then bucketed by UTC hour)
   const hourlySrc = (rawData.hourly_by_model || []).filter(r =>
-    selectedModels.has(r.model) && (!cutoff || r.day >= cutoff)
+    selectedModels.has(r.model) && (!start || r.day >= start) && (!end || r.day <= end)
   );
   const hourlyAgg = aggregateHourly(hourlySrc, hourlyTZ);
 
@@ -1242,13 +1256,17 @@ def log_message(self, format, *args):
         pass
 
     def do_GET(self):
-        if self.path in ("/", "/index.html"):
+        # self.path includes the query string, but every URL the UI emits has
+        # one (e.g. "/?range=all"); compare the bare path so bookmarkable
+        # URLs don't fall through to 404.
+        path = urlparse(self.path).path
+        if path in ("/", "/index.html"):
             self.send_response(200)
             self.send_header("Content-Type", "text/html; charset=utf-8")
             self.end_headers()
             self.wfile.write(HTML_TEMPLATE.encode("utf-8"))
 
-        elif self.path == "/api/data":
+        elif path == "/api/data":
             data = get_dashboard_data()
             body = json.dumps(data).encode("utf-8")
             self.send_response(200)
@@ -1262,7 +1280,8 @@ def do_GET(self):
             self.end_headers()
 
     def do_POST(self):
-        if self.path == "/api/rescan":
+        path = urlparse(self.path).path
+        if path == "/api/rescan":
             # Full rebuild: delete DB and rescan from scratch.
             # Pass DB_PATH / DEFAULT_PROJECTS_DIRS explicitly so tests that
             # patch the module globals are honored (scan's defaults are
@@ -1290,7 +1309,7 @@ def do_POST(self):
 def serve(host=None, port=None):
     host = host or os.environ.get("HOST", "localhost")
     port = port or int(os.environ.get("PORT", "8080"))
-    server = HTTPServer((host, port), DashboardHandler)
+    server = ThreadingHTTPServer((host, port), DashboardHandler)
     print(f"Dashboard running at http://{host}:{port}")
     print("Press Ctrl+C to stop.")
     try:

scanner.py

@@ -419,6 +419,8 @@ def scan(projects_dir=None, projects_dirs=None, db_path=DB_PATH, verbose=True):
                             meta = new_session_metas[session_id]
                             if timestamp and (not meta["last_timestamp"] or timestamp > meta["last_timestamp"]):
                                 meta["last_timestamp"] = timestamp
+                            if timestamp and (not meta["first_timestamp"] or timestamp < meta["first_timestamp"]):
+                                meta["first_timestamp"] = timestamp
 
                         if rtype == "assistant":
                             msg = record.get("message", {})

tests/test_dashboard.py

@@ -124,6 +124,131 @@ def test_hourly_by_model_carries_day_and_model(self):
         self.assertTrue(all(r["day"] == "2026-04-08" for r in rows))
 
 
+class TestEmptyStringModelNormalization(unittest.TestCase):
+    """Regression: turns with model='' (empty string) must group as 'unknown'.
+    COALESCE(model, 'unknown') alone returns '' because empty string isn't NULL;
+    NULLIF(model, '') is needed first."""
+
+    def setUp(self):
+        self.tmpfile = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        self.tmpfile.close()
+        self.db_path = Path(self.tmpfile.name)
+        conn = get_db(self.db_path)
+        init_db(conn)
+        upsert_sessions(conn, [{
+            "session_id": "sess-empty", "project_name": "u/p",
+            "first_timestamp": "2026-04-08T09:00:00Z",
+            "last_timestamp": "2026-04-08T09:05:00Z",
+            "git_branch": "", "model": "",
+            "total_input_tokens": 100, "total_output_tokens": 50,
+            "total_cache_read": 0, "total_cache_creation": 0,
+            "turn_count": 1,
+        }])
+        insert_turns(conn, [{
+            "session_id": "sess-empty", "timestamp": "2026-04-08T09:05:00Z",
+            "model": "", "input_tokens": 100, "output_tokens": 50,
+            "cache_read_tokens": 0, "cache_creation_tokens": 0,
+            "tool_name": None, "cwd": "/tmp",
+        }])
+        conn.commit()
+        conn.close()
+
+    def tearDown(self):
+        os.unlink(self.db_path)
+
+    def test_all_models_contains_unknown_not_empty(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        self.assertIn("unknown", data["all_models"])
+        self.assertNotIn("", data["all_models"])
+
+    def test_daily_by_model_contains_unknown_not_empty(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        models = {r["model"] for r in data["daily_by_model"]}
+        self.assertIn("unknown", models)
+        self.assertNotIn("", models)
+
+    def test_hourly_by_model_contains_unknown_not_empty(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        models = {r["model"] for r in data["hourly_by_model"]}
+        self.assertIn("unknown", models)
+        self.assertNotIn("", models)
+
+
+class TestMixedNullAndEmptyModel(unittest.TestCase):
+    """Regression: a mix of model=NULL and model='' rows must collapse into a
+    SINGLE 'unknown' group across all aggregations. Without `GROUP BY
+    COALESCE(NULLIF(model, ''), 'unknown')` (matching the SELECT expression),
+    SQLite groups by raw value and emits two distinct 'unknown' rows."""
+
+    def setUp(self):
+        self.tmpfile = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        self.tmpfile.close()
+        self.db_path = Path(self.tmpfile.name)
+        conn = get_db(self.db_path)
+        init_db(conn)
+        upsert_sessions(conn, [{
+            "session_id": "sess-mix", "project_name": "u/p",
+            "first_timestamp": "2026-04-08T09:00:00Z",
+            "last_timestamp": "2026-04-08T10:00:00Z",
+            "git_branch": "", "model": "",
+            "total_input_tokens": 200, "total_output_tokens": 100,
+            "total_cache_read": 0, "total_cache_creation": 0,
+            "turn_count": 2,
+        }])
+        # Insert one turn with model='' and one with model=NULL on the same day.
+        # Use raw INSERT for the NULL row because insert_turns() requires the
+        # model key to exist (would error on missing key, not on None).
+        insert_turns(conn, [{
+            "session_id": "sess-mix", "timestamp": "2026-04-08T09:00:00Z",
+            "model": "", "input_tokens": 100, "output_tokens": 50,
+            "cache_read_tokens": 0, "cache_creation_tokens": 0,
+            "tool_name": None, "cwd": "/tmp",
+        }])
+        conn.execute("""
+            INSERT INTO turns (session_id, timestamp, model, input_tokens,
+                output_tokens, cache_read_tokens, cache_creation_tokens,
+                tool_name, cwd)
+            VALUES ('sess-mix', '2026-04-08T09:30:00Z', NULL, 100, 50, 0, 0, NULL, '/tmp')
+        """)
+        conn.commit()
+        conn.close()
+
+    def tearDown(self):
+        os.unlink(self.db_path)
+
+    def test_all_models_collapses_to_single_unknown(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        unknowns = [m for m in data["all_models"] if m == "unknown"]
+        self.assertEqual(len(unknowns), 1, f"got duplicate 'unknown' rows: {data['all_models']}")
+
+    def test_daily_collapses_to_single_unknown(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        unknown_rows = [r for r in data["daily_by_model"] if r["model"] == "unknown"]
+        # One day, one model bucket
+        self.assertEqual(len(unknown_rows), 1, f"got {unknown_rows}")
+        self.assertEqual(unknown_rows[0]["turns"], 2)
+        self.assertEqual(unknown_rows[0]["input"], 200)
+
+    def test_hourly_collapses_to_single_unknown(self):
+        data = get_dashboard_data(db_path=self.db_path)
+        # Both turns are in UTC hour 9 — must be one row, not two
+        hour9 = [r for r in data["hourly_by_model"]
+                 if r["hour"] == 9 and r["model"] == "unknown"]
+        self.assertEqual(len(hour9), 1, f"got {hour9}")
+        self.assertEqual(hour9[0]["turns"], 2)
+
+
+class TestNonBillableModelFallback(unittest.TestCase):
+    """Regression: when the user has only non-billable models (e.g. gemma, glm,
+    local LLMs) — or all turns lack a model field — the default model selection
+    must fall back to ALL models so the dashboard isn't blank."""
+
+    def test_readurlmodels_fallback_in_html_template(self):
+        # The fallback logic is JS; we assert the source contains the guard so
+        # a future refactor doesn't silently remove it.
+        self.assertIn("billable.length ? billable : allModels", HTML_TEMPLATE)
+
+
 class TestDashboardHTTP(unittest.TestCase):
     """Integration test: start server and make HTTP requests."""
 
@@ -166,6 +291,23 @@ def test_index_returns_html(self):
             self.assertEqual(resp.status, 200)
             self.assertIn("text/html", resp.headers["Content-Type"])
 
+    def test_index_with_query_string_returns_html(self):
+        # Regression: ?range=... and ?models=... must not 404. The dashboard
+        # itself rewrites the URL with these params via history.replaceState,
+        # so anything that reloads or bookmarks the page hits this path.
+        for qs in ("?range=all", "?range=30d&models=claude-opus-4-7"):
+            with urllib.request.urlopen(f"http://127.0.0.1:{self.port}/{qs}") as resp:
+                self.assertEqual(resp.status, 200)
+                self.assertIn(b"Claude Code Usage Dashboard", resp.read())
+
+    def test_api_data_with_query_string(self):
+        # /api/data is fetched without query parameters today, but the route
+        # should be tolerant if any are tacked on (e.g. cache-busting).
+        with urllib.request.urlopen(
+            f"http://127.0.0.1:{self.port}/api/data?_=cachebust"
+        ) as resp:
+            self.assertEqual(resp.status, 200)
+
     def test_api_data_returns_json(self):
         url = f"http://127.0.0.1:{self.port}/api/data"
         with urllib.request.urlopen(url) as resp:
@@ -228,6 +370,15 @@ def test_hourly_peak_hour_constants(self):
         self.assertIn('PEAK_HOURS_UTC', HTML_TEMPLATE)
         self.assertIn('[12, 13, 14, 15, 16, 17]', HTML_TEMPLATE)
 
+    def test_today_range_button_present(self):
+        """The 'Today' range button is wired into RANGE_LABELS, RANGE_TICKS,
+        getRangeBounds, and the filter-bar HTML."""
+        self.assertIn("data-range=\"today\"", HTML_TEMPLATE)
+        self.assertIn("'today': 'Today'", HTML_TEMPLATE)
+        self.assertIn("'today': 1", HTML_TEMPLATE)
+        # Bounds case: today returns start === end === today's ISO date
+        self.assertIn("range === 'today'", HTML_TEMPLATE)
+
 
 class TestPricingParity(unittest.TestCase):
     """Verify CLI and dashboard pricing tables stay in sync."""