nilometer 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.2.0 (2026-10-22)
+
+- **`nilometer view`:** shows the report page in your browser with a **Refresh** button that reads new log lines and rebuilds the page in place, on the tab you're on. It runs until you press Ctrl+C, listening on 127.0.0.1 only, behind a random address made for each run; a refresh must come from that page. `report --save --html` still writes a page you can keep or share, with no button.
+- **Reports in seconds:** on three months of real data, `report` went from 23 s to under 2 s, and `report --save --html` from 53 s to under 7 s, with the same output. Ingest now stores the two building blocks every report query read, instead of each query recomputing them. The first `ingest` after updating takes a few seconds longer, once.
+
+## 0.1.0 (2026-10-22)
 
 First public version.
 

package/README.md

@@ -104,7 +104,7 @@ Usage percentages exist only from the moment the collector is installed, and onl
 
 ## MVP scope
 
-One screen. No daemon, no desktop app, no live updating. Every metric below is retrospective.
+One screen. No daemon, no desktop app, no live updating: `nilometer view` serves the page from your own computer only while you run it, and its Refresh button rebuilds the page when you ask ([D-097](decisions.md)). Every metric below is retrospective.
 
 ### Observed: "Is my plan too small?"
 
@@ -200,9 +200,10 @@ There's no GUI, installer, or auto-updater. Configuration was always the hard pa
 ```sh
 npm install -g nilometer
 nilometer init
+nilometer view
 ```
 
-Installing compiles nothing: the database is the SQLite built into Node.js ([D-093](decisions.md)). To try a command without installing, use `npx nilometer <command>`.
+`init` installs the hook and reads the session logs already on disk. `view` opens the report page in your browser; press **Refresh** on it whenever you want it brought up to date. Installing compiles nothing: the database is the SQLite built into Node.js ([D-093](decisions.md)). To try a command without installing, use `npx nilometer <command>`.
 
 - **macOS:** tested.
 - **Linux:** the test suite and an install from the package pass in CI.
@@ -230,6 +231,7 @@ On Node 24 before 24.15, `npm ci` prints `EBADENGINE` warnings for three lint pl
 | `nilometer init` | Install the hook (wrapping any existing status line), then backfill from session logs |
 | `nilometer ingest` | Read new session log lines and status line readings into the database. `--full` rereads everything; `--json` prints the outcome as JSON |
 | `nilometer report` | Print what was observed, then projections in a separate section. `--json` prints unrounded rows and every label. `--save` also writes a dated copy (`report_YYYY-MM-DD_HHMMSS.txt` and `.json`) to `~/.local/share/nilometer/reports/`; `--save --html` adds a self-contained `.html` page with the same name, which works offline and makes no network requests. The page opens on an overview, has one tab per chart, and keeps the projections in their own labelled tabs. `--save --html --open` also opens the saved page in your browser; if it can't, the command says where the page is and still succeeds |
+| `nilometer view` | Show the report page in your browser from your own computer, with a **Refresh** button that reads new log lines and rebuilds the page in place, on the tab you're on. Runs until you press Ctrl+C. It listens on 127.0.0.1 only, behind a random address made for each run. `--port <n>` picks the port; `--no-open` prints the address without opening a browser |
 | `nilometer explain <metric>` | List the events behind a number in the report, with the file, line, and byte each came from, and add them back up. Metrics: `limit-hits`, `mid-task`, `lockout`, `by-plan`, `not-resumed`, `headroom`, `peak`, `crossings`, `unattributed`, `by-model`, `by-repo`, `burn-rate`, `api-list-price` |
 | `nilometer plan-price set <YYYY-MM> <usd> --name <plan>` | Record your plan's USD list price per month from that month on, shown beside API list price. `plan-price list` shows what's entered |
 | `nilometer alias set <old-path> <new-path>` | Count a renamed or moved project's old path under its new one, so it shows as one repository. The report lists every alias you entered under the repository table. `alias list` shows them; `alias remove <old-path>` undoes one ([D-092](decisions.md)) |
@@ -244,7 +246,7 @@ On Node 24 before 24.15, `npm ci` prints `EBADENGINE` warnings for three lint pl
 
 ### Privacy
 
-- **Everything stays on your computer.** Nilometer reads Claude Code's session logs and status line payload, and copies them into a local SQLite database. It makes no network requests when it runs, and it sends no telemetry.
+- **Everything stays on your computer.** Nilometer reads Claude Code's session logs and status line payload, and copies them into a local SQLite database. It makes no network requests when it runs, and it sends no telemetry. `nilometer view` listens on 127.0.0.1 for your own browser while it runs, and nothing else can reach it.
 - **The database holds copies of your session logs:** prompts, code, and file paths. That's why the data directory is readable only by your account.
 - **Reports contain spend figures and project names.** Think before sharing one. `nilometer explain` output also names session files and IDs.
 

package/core/schema/032_stored_views.sql

@@ -0,0 +1,233 @@
+-- 032_stored_views: requests_dedup and window_readings become tables that ingest fills from their views (D-096, step G6.1).
+--
+-- Every report statement recomputed both from the raw tables: window_readings pairs each of tens of thousands of
+-- rate-limit readings with its API response through correlated lookups, and requests_dedup ranks every request line.
+-- On real data the report and page ran about 20 statements built on them and took 45-50 s. Their inputs (requests,
+-- parsed_lines, raw_lines, source_files, status_readings, rate_limit_windows) are written only by ingest, so ingest
+-- stores their rows once (core/ingest/stored-views.ts) and everything downstream reads the stored rows. The
+-- definitions are unchanged and keep running as views under *_computed, so the rows trace back exactly as before,
+-- and a test fails if a stored table ever differs from its view.
+--
+-- Columns are ANY in a STRICT table: no type affinity, so every value is stored exactly as the view returned it.
+
+DROP VIEW requests_dedup;
+
+-- Observed: one row per distinct API response (winners) plus every unkeyed request line, as 019 computed it; ingest stores its rows in requests_dedup (D-096).
+CREATE VIEW requests_dedup_computed AS
+WITH ranked AS (
+  SELECT
+    r.raw_line_id,
+    r.dedup_key,
+    r.message_id,
+    r.request_id,
+    r.model,
+    r.input_tokens,
+    r.output_tokens,
+    r.cache_read_tokens,
+    r.cache_write_5m_tokens,
+    r.cache_write_1h_tokens,
+    r.cache_write_unsplit_tokens,
+    r.speed,
+    p.session_id,
+    p.timestamp_raw,
+    p.timestamp_utc,
+    p.cwd,
+    p.is_sidechain,
+    f.root,
+    f.relative_path,
+    l.first_run_id,
+    l.line_number,
+    ROW_NUMBER() OVER (
+      PARTITION BY r.dedup_key
+      ORDER BY r.output_tokens DESC, p.is_sidechain ASC,
+               -- Among lines tied on output, the earliest: when those numbers first existed
+               -- (D-065, the same rule D-045 applies to readings). NULLs last, so an unparsed
+               -- timestamp never wins.
+               (p.timestamp_utc IS NULL) ASC, p.timestamp_utc ASC,
+               f.root DESC, f.relative_path DESC, l.first_run_id DESC, l.line_number DESC
+    ) AS candidate_rank
+  FROM requests r
+  JOIN parsed_lines p ON p.raw_line_id = r.raw_line_id
+  JOIN raw_lines l ON l.id = r.raw_line_id
+  JOIN source_files f ON f.id = l.source_file_id
+)
+SELECT
+  raw_line_id, dedup_key, message_id, request_id, model,
+  input_tokens, output_tokens, cache_read_tokens,
+  cache_write_5m_tokens, cache_write_1h_tokens, cache_write_unsplit_tokens, speed,
+  session_id, timestamp_raw, timestamp_utc, cwd, is_sidechain,
+  root, relative_path, first_run_id, line_number
+FROM ranked
+WHERE dedup_key IS NULL OR candidate_rank = 1;
+
+CREATE TABLE requests_dedup (
+  raw_line_id                ANY, -- derived: requests_dedup_computed.raw_line_id
+  dedup_key                  ANY, -- derived: requests_dedup_computed.dedup_key
+  message_id                 ANY, -- derived: requests_dedup_computed.message_id
+  request_id                 ANY, -- derived: requests_dedup_computed.request_id
+  model                      ANY, -- derived: requests_dedup_computed.model
+  input_tokens               ANY, -- derived: requests_dedup_computed.input_tokens
+  output_tokens              ANY, -- derived: requests_dedup_computed.output_tokens
+  cache_read_tokens          ANY, -- derived: requests_dedup_computed.cache_read_tokens
+  cache_write_5m_tokens      ANY, -- derived: requests_dedup_computed.cache_write_5m_tokens
+  cache_write_1h_tokens      ANY, -- derived: requests_dedup_computed.cache_write_1h_tokens
+  cache_write_unsplit_tokens ANY, -- derived: requests_dedup_computed.cache_write_unsplit_tokens
+  speed                      ANY, -- derived: requests_dedup_computed.speed
+  session_id                 ANY, -- derived: requests_dedup_computed.session_id
+  timestamp_raw              ANY, -- derived: requests_dedup_computed.timestamp_raw
+  timestamp_utc              ANY, -- derived: requests_dedup_computed.timestamp_utc
+  cwd                        ANY, -- derived: requests_dedup_computed.cwd
+  is_sidechain               ANY, -- derived: requests_dedup_computed.is_sidechain
+  root                       ANY, -- derived: requests_dedup_computed.root
+  relative_path              ANY, -- derived: requests_dedup_computed.relative_path
+  first_run_id               ANY, -- derived: requests_dedup_computed.first_run_id
+  line_number                ANY  -- derived: requests_dedup_computed.line_number
+) STRICT;
+
+CREATE INDEX requests_dedup_raw_line_id ON requests_dedup (raw_line_id);
+CREATE INDEX requests_dedup_dedup_key ON requests_dedup (dedup_key);
+CREATE INDEX requests_dedup_time ON requests_dedup (timestamp_utc);
+CREATE INDEX requests_dedup_session_time ON requests_dedup (session_id, timestamp_utc);
+CREATE INDEX requests_dedup_cwd ON requests_dedup (cwd);
+
+INSERT INTO requests_dedup (raw_line_id, dedup_key, message_id, request_id, model, input_tokens, output_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens, cache_write_unsplit_tokens, speed, session_id, timestamp_raw, timestamp_utc, cwd, is_sidechain, root, relative_path, first_run_id, line_number)
+SELECT raw_line_id, dedup_key, message_id, request_id, model, input_tokens, output_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens, cache_write_unsplit_tokens, speed, session_id, timestamp_raw, timestamp_utc, cwd, is_sidechain, root, relative_path, first_run_id, line_number FROM requests_dedup_computed;
+
+DROP VIEW window_readings;
+
+-- Observed: one row per observation of a plan window, as 028 computed it; ingest stores its rows in window_readings (D-096). As in 026 (D-044, D-045, D-086), with stale = 1 when a counted reading is more than 1 point below an earlier counted one in its window (D-089).
+CREATE VIEW window_readings_computed AS
+WITH readings AS (
+  SELECT
+    w.raw_line_id, w.window, w.resets_at, w.used_percentage, s.session_id, s.captured_at_s,
+    -- The response behind the latest request line in this session, inside this window, at or before
+    -- the capture (+1 s for whole-second captures). An unkeyed line is its own response.
+    (SELECT COALESCE(rq.dedup_key, 'line:' || rq.raw_line_id)
+       FROM parsed_lines p
+       JOIN requests rq ON rq.raw_line_id = p.raw_line_id
+       WHERE p.session_id = s.session_id AND p.class = 'request'
+         AND p.timestamp_utc > strftime('%Y-%m-%dT%H:%M:%fZ',
+               w.resets_at - CASE w.window WHEN 'five_hour' THEN 5 * 3600 ELSE 7 * 86400 END, 'unixepoch')
+         AND p.timestamp_utc < strftime('%Y-%m-%dT%H:%M:%fZ', s.captured_at_s + 1, 'unixepoch')
+       ORDER BY p.timestamp_utc DESC, p.raw_line_id DESC
+       LIMIT 1) AS response_key
+  FROM rate_limit_windows w
+  JOIN status_readings s ON s.raw_line_id = w.raw_line_id
+  WHERE s.status = 'ok' AND w.validity = 'valid' AND w.window IN ('five_hour', 'seven_day')
+),
+dated AS (
+  SELECT
+    r.*,
+    -- The response's first line: when its numbers first existed.
+    (SELECT MIN(p.timestamp_utc)
+       FROM requests rq
+       JOIN parsed_lines p ON p.raw_line_id = rq.raw_line_id
+       WHERE (r.response_key LIKE 'line:%' AND rq.raw_line_id = CAST(substr(r.response_key, 6) AS INTEGER))
+          OR rq.dedup_key = r.response_key) AS response_first_utc,
+    -- The previous capture of the same response, in capture order.
+    LAG(r.used_percentage) OVER captures AS previous_used_percentage
+  FROM readings r
+  -- A capture-time fallback is its own group: NULL response keys must not merge (D-044).
+  WINDOW captures AS (
+    PARTITION BY r.window, r.resets_at, r.session_id, r.response_key,
+                 CASE WHEN r.response_key IS NULL THEN r.raw_line_id END
+    ORDER BY r.captured_at_s, r.raw_line_id
+  )
+),
+runs AS (
+  SELECT
+    d.*,
+    -- A new run starts at the first capture and at every change of more than 0.01 points: payloads
+    -- carry computed values such as 7.000000000000001, which are the same number (D-044, D-086).
+    SUM(CASE WHEN d.previous_used_percentage IS NULL
+               OR abs(d.used_percentage - d.previous_used_percentage) > 0.01 THEN 1 ELSE 0 END)
+      OVER (
+        PARTITION BY d.window, d.resets_at, d.session_id, d.response_key,
+                     CASE WHEN d.response_key IS NULL THEN d.raw_line_id END
+        ORDER BY d.captured_at_s, d.raw_line_id
+        ROWS UNBOUNDED PRECEDING
+      ) AS run
+  FROM dated d
+),
+observed AS (
+  SELECT
+    u.*,
+    -- A later run's value didn't come from the response, so it's dated when it was first seen.
+    CASE
+      WHEN u.response_first_utc IS NULL THEN strftime('%Y-%m-%dT%H:%M:%fZ', u.captured_at_s, 'unixepoch')
+      WHEN u.run = 1 THEN u.response_first_utc
+      ELSE strftime('%Y-%m-%dT%H:%M:%fZ', MIN(u.captured_at_s) OVER run_captures, 'unixepoch')
+    END AS observed_at_utc,
+    ROW_NUMBER() OVER run_captures_latest AS copy_rank
+  FROM runs u
+  WINDOW
+    run_captures AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+    ),
+    run_captures_latest AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+      ORDER BY u.captured_at_s DESC, u.raw_line_id DESC
+    )
+),
+counted AS (
+  SELECT
+    raw_line_id,
+    window,
+    resets_at,
+    strftime('%Y-%m-%dT%H:%M:%fZ', resets_at, 'unixepoch') AS reset_at_utc,
+    used_percentage,
+    session_id,
+    captured_at_s,
+    strftime('%Y-%m-%dT%H:%M:%fZ', captured_at_s, 'unixepoch') AS captured_at_utc,
+    observed_at_utc,
+    unixepoch(observed_at_utc, 'subsec') AS observed_at_s,
+    CASE
+      WHEN response_key IS NULL THEN 'capture'
+      WHEN run = 1 THEN 'last_request'
+      ELSE 'changed_capture'
+    END AS observed_via,
+    unixepoch(observed_at_utc, 'subsec') > resets_at AS after_reset
+  FROM observed
+  WHERE copy_rank = 1
+)
+SELECT
+  c.*,
+  -- Usage within one window only rises, so a counted reading more than 1 point below an earlier one
+  -- in the same window, from any session, carries a number from before that earlier reading (D-089).
+  CASE
+    WHEN c.after_reset = 0 AND c.used_percentage < MAX(c.used_percentage) OVER (
+      PARTITION BY c.window, c.resets_at ORDER BY c.observed_at_s, c.raw_line_id
+      ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+    ) - 1 THEN 1
+    ELSE 0
+  END AS stale
+FROM counted c;
+
+CREATE TABLE window_readings (
+  raw_line_id     ANY, -- derived: window_readings_computed.raw_line_id
+  window          ANY, -- derived: window_readings_computed.window
+  resets_at       ANY, -- derived: window_readings_computed.resets_at
+  reset_at_utc    ANY, -- derived: window_readings_computed.reset_at_utc
+  used_percentage ANY, -- derived: window_readings_computed.used_percentage
+  session_id      ANY, -- derived: window_readings_computed.session_id
+  captured_at_s   ANY, -- derived: window_readings_computed.captured_at_s
+  captured_at_utc ANY, -- derived: window_readings_computed.captured_at_utc
+  observed_at_utc ANY, -- derived: window_readings_computed.observed_at_utc
+  observed_at_s   ANY, -- derived: window_readings_computed.observed_at_s
+  observed_via    ANY, -- derived: window_readings_computed.observed_via
+  after_reset     ANY, -- derived: window_readings_computed.after_reset
+  stale           ANY  -- derived: window_readings_computed.stale
+) STRICT;
+
+CREATE INDEX window_readings_raw_line ON window_readings (raw_line_id);
+CREATE INDEX window_readings_instance ON window_readings (window, reset_at_utc, observed_at_s);
+CREATE INDEX window_readings_session_time ON window_readings (session_id, observed_at_s);
+CREATE INDEX window_readings_time ON window_readings (observed_at_utc);
+
+INSERT INTO window_readings (raw_line_id, window, resets_at, reset_at_utc, used_percentage, session_id, captured_at_s, captured_at_utc, observed_at_utc, observed_at_s, observed_via, after_reset, stale)
+SELECT raw_line_id, window, resets_at, reset_at_utc, used_percentage, session_id, captured_at_s, captured_at_utc, observed_at_utc, observed_at_s, observed_via, after_reset, stale FROM window_readings_computed;
+
+-- Statistics for the query planner, so the first report after this migration is fast too (D-096).
+ANALYZE;

package/dist/cli/program.js

@@ -7,6 +7,7 @@
  * calls it, and turns outcomes into words. All wording here follows CLAUDE.md "Wording is part of
  * correctness": messages state what happened, never advice or judgment.
  */
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { Command, CommanderError } from "commander";
 import { transaction } from "../core/db/database.js";
@@ -21,6 +22,7 @@ import { runInit, runUninstall, } from "../core/install/install.js";
 import { SettingsError, locateSettings } from "../core/settings/settings-file.js";
 import { CCUSAGE_VERSION, runCcusage, runVerify, } from "../core/verify/verify.js";
 import { openPage } from "../core/util/open-page.js";
+import { listenView } from "../core/view/server.js";
 import { RepositoryAliasError, listAliases, normalizeRepositoryPath, removeAlias, setAlias, validateAlias, } from "../core/plans/repository-aliases.js";
 import { METRIC_NAMES, UnknownMetricError, explain, renderExplanation } from "../viewer/explain.js";
 import { formatNumber } from "../viewer/format.js";
@@ -28,11 +30,25 @@ import { NoDatabaseError, readReport, summarizeStoredData, withReportDatabase, }
 import { loadHtmlData } from "../viewer/html-data.js";
 import { renderHtmlReport } from "../viewer/html.js";
 import { saveReport } from "../viewer/save.js";
-import { displayPath, plural, renderReport, reportJson } from "../viewer/render.js";
+import { displayPath, plural, renderReport, reportJson, } from "../viewer/render.js";
 /** The ccusage release `verify` compares against; pinned so two runs compare the same way. */
 const CCUSAGE_PIN = CCUSAGE_VERSION;
 /** Readings need a terminal session (D-029); said at install so empty usage windows aren't a surprise. */
 export const TERMINAL_ONLY_NOTE = "Readings are recorded only when Claude Code runs in a terminal; the VS Code extension doesn't run the status line.";
+/** Refusal for a `--port` that isn't a port number. */
+export const BAD_PORT = "--port needs a whole number from 1 to 65535, or leave it out for any free port. Nothing was changed.";
+/**
+ * Reads `--port`.
+ * @param value - The flag's text, if given.
+ * @returns The port, 0 for any free one, or undefined when the text isn't a port.
+ */
+export function parsePort(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    const port = /^\d{1,5}$/.test(value) ? Number(value) : NaN;
+    return port >= 1 && port <= 65_535 ? port : undefined;
+}
 /**
  * Refusal for `--open` without both `--save` and `--html`: only a saved page exists to open (D-082).
  * Checked first, so it names everything `--open` needs.
@@ -491,6 +507,55 @@ function openSaved(deps, htmlPath) {
             `Couldn't open the page (${opened.reason}). It's saved at ${displayPath(htmlPath, deps.home)}`,
         ];
 }
+/**
+ * Reads the report, and the page when asked, from one snapshot of the database: one read
+ * transaction, so an ingest finishing between the two reads can't make them disagree (D-070: "the
+ * same views, so the two can't disagree"). Shared by `report` and `view` (D-097).
+ * @param deps - Program dependencies.
+ * @param flags - The command's flags.
+ * @param flags.dataDir - `--data-dir`, if given.
+ * @param reportedAt - The report's time: a window is open only until its reset, as of now (D-083).
+ * @param withPage - Whether to render the page too.
+ * @param serving - How `view` serves the page; omitted for a saved page.
+ * @returns The text report's input, and the page when asked.
+ */
+function readSnapshot(deps, flags, reportedAt, withPage, serving) {
+    const reportOptions = {
+        ...toPlanDatabaseOptions(flags, deps),
+        timeZone: deps.timeZone,
+        reportedAt,
+        // Where init would look, so the warning checks the same file it would fix (D-081).
+        settingsPath: locateSettings({
+            home: deps.home,
+            claudeConfigDir: deps.env["CLAUDE_CONFIG_DIR"],
+        }),
+    };
+    return withReportDatabase(reportOptions, (db, databasePath) => transaction(db, () => {
+        const read = readReport(db, databasePath, reportOptions);
+        return {
+            input: read,
+            html: withPage
+                ? renderHtmlReport(
+                // Reuses what readReport just read from this snapshot, so the costliest views are
+                // computed once (D-070). The home directory shortens repository paths to ~/..., as
+                // in the text report.
+                loadHtmlData(db, {
+                    timeZone: deps.timeZone,
+                    generatedAt: reportedAt,
+                    home: deps.home,
+                    missingHookPath: read.missingHookPath,
+                }, read), serving)
+                : undefined,
+        };
+    }), 
+    /**
+     * Says on stderr that data paths were made owner-only (D-043).
+     * @param tightened - Paths that were tightened.
+     */
+    (tightened) => {
+        noteTightened(deps, tightened);
+    });
+}
 /**
  * Builds the command-line program.
  * @param deps - Program dependencies.
@@ -579,49 +644,11 @@ export function buildProgram(deps, setExitCode) {
             if (flags.html === true && flags.save !== true) {
                 return { exitCode: 1, lines: [], errors: [HTML_NEEDS_SAVE] };
             }
-            /**
-             * Says on stderr that data paths were made owner-only.
-             * @param tightened - Paths that were tightened.
-             */
-            const onTightened = (tightened) => {
-                noteTightened(deps, tightened);
-            };
             // One instant is the report's time (D-083: a window is open only until its reset, as
             // of now), names the saved files, and dates the page, so none of them can disagree.
             const reportedAt = deps.now();
-            const reportOptions = {
-                ...toPlanDatabaseOptions(flags, deps),
-                timeZone: deps.timeZone,
-                reportedAt,
-                // Where init would look, so the warning checks the same file it would fix (D-081).
-                settingsPath: locateSettings({
-                    home: deps.home,
-                    claudeConfigDir: deps.env["CLAUDE_CONFIG_DIR"],
-                }),
-            };
             const at = flags.save === true ? reportedAt : undefined;
-            const { input, html } = withReportDatabase(reportOptions, (db, databasePath) => 
-            // One read transaction for the text and the page: they come from one snapshot of the
-            // database, so an ingest finishing between the two reads can't make them disagree
-            // (D-070: "the same views, so the two can't disagree").
-            transaction(db, () => {
-                const read = readReport(db, databasePath, reportOptions);
-                return {
-                    input: read,
-                    html: at !== undefined && flags.html === true
-                        ? renderHtmlReport(
-                        // Reuses what readReport just read from this snapshot, so the costliest
-                        // views are computed once (D-070).
-                        // The home directory shortens repository paths to ~/..., as in the text report.
-                        loadHtmlData(db, {
-                            timeZone: deps.timeZone,
-                            generatedAt: at,
-                            home: deps.home,
-                            missingHookPath: read.missingHookPath,
-                        }, read))
-                        : undefined,
-                };
-            }), onTightened);
+            const { input, html } = readSnapshot(deps, flags, reportedAt, at !== undefined && flags.html === true);
             const printed = flags.json === true ? JSON.stringify(reportJson(input), null, 2) : renderReport(input);
             if (at === undefined) {
                 return { exitCode: 0, lines: [printed] };
@@ -643,6 +670,59 @@ export function buildProgram(deps, setExitCode) {
             return { exitCode: 0, lines: [printed, "", note], errors: notOpened };
         }));
     });
+    program
+        .command("view")
+        .description("Show the report page in your browser from your own computer (127.0.0.1), with a Refresh button that reads new log lines and rebuilds it. Runs until you press Ctrl+C.")
+        .option("--data-dir <path>", "data directory holding the database and spool")
+        .option("--port <number>", "port on 127.0.0.1 (default: any free port)")
+        .option("--no-open", "print the address without opening a browser")
+        .action((flags) => {
+        setExitCode(report(deps, () => {
+            const port = parsePort(flags.port);
+            if (port === undefined) {
+                return { exitCode: 1, lines: [], errors: [BAD_PORT] };
+            }
+            const token = (deps.viewToken ?? (() => randomBytes(24).toString("base64url")))();
+            const serving = { refreshPath: `/${token}/refresh` };
+            /**
+             * Ingests, then renders the page from what's stored now.
+             * @returns The page, and how many new lines the ingest stored.
+             */
+            const build = () => {
+                const outcome = runIngestCommand(toIngestOptions(flags, deps));
+                const { html } = readSnapshot(deps, flags, deps.now(), true, serving);
+                return { page: html ?? "", stored: outcome.run.linesStored };
+            };
+            let current = build();
+            (deps.serveView ?? listenView)({
+                token,
+                port,
+                page: () => current.page,
+                refresh: () => {
+                    current = build();
+                    return {
+                        ok: true,
+                        message: `${plural(current.stored, "new line", "new lines")} read`,
+                    };
+                },
+                onListening: (url) => {
+                    deps.print(`Showing the report at ${url}`);
+                    deps.print("Refresh on the page reads new log lines and rebuilds it. Press Ctrl+C here to stop.");
+                    if (flags.open !== false) {
+                        const opened = (deps.openPage ?? openPage)(url);
+                        if (!opened.opened) {
+                            deps.printError(`Couldn't open a browser (${opened.reason}). Open the address above.`);
+                        }
+                    }
+                },
+                onError: (message) => {
+                    deps.printError(`nilometer view stopped: ${message}`);
+                    process.exitCode = 1;
+                },
+            });
+            return { exitCode: 0, lines: [] };
+        }));
+    });
     program
         .command("explain <metric>")
         .description(`List the events behind a number in the report, with where each was read from, and re-add them. Metrics: ${METRIC_NAMES.join(", ")}.`)

package/dist/core/ingest/derive.js

@@ -6,6 +6,7 @@
  * in SQL views over these tables.
  */
 import { blobBytes, transaction } from "../db/database.js";
+import { refreshStoredViews } from "./stored-views.js";
 import { classifyLine, extractEvent, extractLinks, extractRequest, identityString, parseLine, parseTimestamp, } from "./classify.js";
 import { resolveResetTime } from "./reset-time.js";
 import { deriveNewSpoolLines } from "./spool.js";
@@ -198,15 +199,21 @@ export function rebuildDerived(db) {
 }
 /**
  * Brings derived tables up to date: a full rebuild if the parser version changed, otherwise only
- * the raw lines not yet derived.
+ * the raw lines not yet derived. Then refills the stored views when their inputs changed (D-096).
  * @param db - Open, migrated database.
  * @returns Number of raw lines derived and whether a rebuild happened.
  */
 export function ensureDerived(db) {
     const row = db.prepare("SELECT value FROM derive_meta WHERE key = 'parser_version'").get();
     if (row?.value !== PARSER_VERSION) {
-        return { derived: rebuildDerived(db), rebuilt: true };
+        const derived = rebuildDerived(db);
+        // Every derived row was replaced, so the stored views are refilled even if the counts match (D-096).
+        refreshStoredViews(db, true);
+        return { derived, rebuilt: true };
     }
-    return { derived: deriveNewLines(db) + deriveNewSpoolLines(db), rebuilt: false };
+    const derived = deriveNewLines(db) + deriveNewSpoolLines(db);
+    // After deriving, so the report's stored rows include this run's lines (D-096).
+    refreshStoredViews(db);
+    return { derived, rebuilt: false };
 }
 //# sourceMappingURL=derive.js.map

package/dist/core/ingest/stored-views.js

@@ -0,0 +1,65 @@
+import { transaction } from "../db/database.js";
+/** Each stored table and the view whose rows it holds. */
+export const STORED_VIEWS = [
+    { table: "requests_dedup", view: "requests_dedup_computed" },
+    { table: "window_readings", view: "window_readings_computed" },
+];
+/** Where the inputs' signature from the last refresh is kept, in `derive_meta`. */
+const SIGNATURE_KEY = "stored_views_input";
+/** Tables the computed views read, each written only by ingest. */
+const INPUT_TABLES = [
+    "raw_lines",
+    "parsed_lines",
+    "requests",
+    "status_readings",
+    "rate_limit_windows",
+];
+/**
+ * Describes the computed views' inputs cheaply enough to check on every ingest: each input table's
+ * row count and highest rowid, and every source file's root and path (requests_dedup carries them).
+ * Rows in those tables are only inserted, or all deleted and derived again, which a rebuild forces
+ * a refresh for anyway; a path changes only when Windows separators are normalized.
+ * @param db - Open, migrated database.
+ * @returns A string that changes whenever an input does.
+ */
+export function inputSignature(db) {
+    const counts = INPUT_TABLES.map((table) => {
+        const row = db
+            .prepare(`SELECT COUNT(*) AS n, COALESCE(MAX(rowid), 0) AS top FROM ${table}`)
+            .get();
+        return `${table}:${row.n}:${row.top}`;
+    });
+    const paths = db
+        .prepare("SELECT COUNT(*) AS n, COALESCE(group_concat(id || '|' || root || '|' || relative_path, '\n'), '') AS list FROM (SELECT id, root, relative_path FROM source_files ORDER BY id)")
+        .get();
+    return [...counts, `source_files:${paths.n}:${paths.list}`].join("\n");
+}
+/**
+ * Refills each stored table from its view when an input changed since the last refresh.
+ * @param db - Open, migrated database.
+ * @param force - Refill even if the inputs look unchanged (after a full rebuild of derived rows).
+ * @returns Whether the tables were refilled.
+ */
+export function refreshStoredViews(db, force = false) {
+    const signature = inputSignature(db);
+    const stored = db.prepare("SELECT value FROM derive_meta WHERE key = ?").get(SIGNATURE_KEY);
+    if (!force && stored?.value === signature) {
+        return false;
+    }
+    transaction(db, () => {
+        for (const { table, view } of STORED_VIEWS) {
+            // Named columns, in the table's order, so the copy can't depend on the view's column order.
+            const columns = db.prepare("SELECT name FROM pragma_table_info(?) ORDER BY cid").all(table)
+                .map((c) => c.name)
+                .join(", ");
+            db.exec(`DELETE FROM ${table}`);
+            db.exec(`INSERT INTO ${table} (${columns}) SELECT ${columns} FROM ${view}`);
+        }
+        db.prepare("INSERT INTO derive_meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(SIGNATURE_KEY, signature);
+    });
+    // Table statistics for the query planner: on real data they halved the page's queries again, for
+    // about 0.4 s here. They change how a query runs, never what it returns.
+    db.exec("ANALYZE");
+    return true;
+}
+//# sourceMappingURL=stored-views.js.map

package/dist/core/view/server.js

@@ -0,0 +1,142 @@
+/**
+ * @file The local server behind `nilometer view` (D-097, step G6.2).
+ *
+ * A saved page is a file, and a browser won't let a file run programs, so a Refresh button on it can't
+ * ingest. While `view` runs, this server shows the page on 127.0.0.1 and, when the page asks, ingests and
+ * rebuilds it. It's the only way in, so it accepts as little as it can:
+ * - it listens on the loopback address only, never on a network interface;
+ * - every path starts with a random token made for this run, so another page in the browser can't guess it;
+ * - the Host header must name this server, which defeats DNS rebinding, where a site re-points its own
+ *   name at 127.0.0.1;
+ * - a refresh must be a POST from this server's own origin, which a page on another site can't send;
+ * - it serves one page and does one thing, refresh; anything else is a 404.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+/**
+ * The hosts this server answers to: the loopback address and `localhost`, on its own port.
+ * @param port - The port it listens on.
+ * @returns Host header values, without a scheme.
+ */
+export function allowedHosts(port) {
+    return [`127.0.0.1:${port}`, `localhost:${port}`];
+}
+/**
+ * Compares two strings in time that doesn't depend on where they differ.
+ * @param a - One string.
+ * @param b - The other.
+ * @returns Whether they're equal.
+ */
+function sameSecret(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/**
+ * Decides what a request may do.
+ * @param request - Method, target, Host and Origin.
+ * @param token - This run's token.
+ * @param port - The port this server listens on.
+ * @returns The page, a refresh, or a refusal with its status.
+ */
+export function route(request, token, port) {
+    const hosts = allowedHosts(port);
+    if (request.host === undefined || !hosts.includes(request.host.toLowerCase())) {
+        return { kind: "refuse", status: 403, reason: "unknown host" };
+    }
+    // Only the path counts; a query string never changes what's served.
+    const path = request.url.split("?")[0] ?? "";
+    const match = /^\/([^/]+)\/(refresh)?$/.exec(path);
+    if (match === null || !sameSecret(match[1] ?? "", token)) {
+        return { kind: "refuse", status: 404, reason: "not found" };
+    }
+    if (match[2] === undefined) {
+        return request.method === "GET" || request.method === "HEAD"
+            ? { kind: "page" }
+            : { kind: "refuse", status: 405, reason: "the page is only read" };
+    }
+    if (request.method !== "POST") {
+        return { kind: "refuse", status: 405, reason: "a refresh is a POST" };
+    }
+    // A browser sends Origin with every POST from a page; none, or another one, isn't this page.
+    if (request.origin === undefined || !hosts.map((h) => `http://${h}`).includes(request.origin)) {
+        return { kind: "refuse", status: 403, reason: "a refresh must come from this page" };
+    }
+    return { kind: "refresh" };
+}
+/**
+ * Headers for every response. The policy lets the page run its own inline script and style and talk
+ * only to this server; the token stays out of any Referer.
+ */
+export const RESPONSE_HEADERS = {
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Content-Security-Policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+};
+/**
+ * Creates the server, not yet listening. Listen on 127.0.0.1 only.
+ * @param deps - Token, page, and refresh.
+ * @returns The server.
+ */
+export function createViewServer(deps) {
+    const server = createServer((request, response) => {
+        const address = server.address();
+        const port = typeof address === "object" && address !== null ? address.port : 0;
+        const decided = route({
+            method: request.method ?? "GET",
+            url: request.url ?? "/",
+            host: request.headers.host,
+            origin: request.headers.origin,
+        }, deps.token, port);
+        // The body is never read: no route takes one.
+        request.resume();
+        if (decided.kind === "refuse") {
+            response.writeHead(decided.status, {
+                ...RESPONSE_HEADERS,
+                "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end(`${decided.reason}\n`);
+            return;
+        }
+        if (decided.kind === "page") {
+            response.writeHead(200, { ...RESPONSE_HEADERS, "Content-Type": "text/html; charset=utf-8" });
+            response.end(request.method === "HEAD" ? undefined : deps.page());
+            return;
+        }
+        let result;
+        try {
+            result = deps.refresh();
+        }
+        catch (error) {
+            result = { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        response.writeHead(result.ok ? 200 : 500, {
+            ...RESPONSE_HEADERS,
+            "Content-Type": "application/json; charset=utf-8",
+        });
+        response.end(JSON.stringify(result));
+    });
+    return server;
+}
+/**
+ * Starts the server on the loopback address only. It runs until the process ends (Ctrl+C).
+ * @param options - Token, page, refresh, port, and callbacks.
+ * @returns The listening server.
+ */
+export function listenView(options) {
+    const server = createViewServer(options);
+    server.on("error", (error) => {
+        options.onError(error.code === "EADDRINUSE"
+            ? `port ${options.port} on 127.0.0.1 is in use; choose another with --port, or leave it out for any free port`
+            : error.message);
+    });
+    // 127.0.0.1 explicitly: listening on every interface would put the page on the network.
+    server.listen(options.port, "127.0.0.1", () => {
+        const address = server.address();
+        const port = typeof address === "object" && address !== null ? address.port : options.port;
+        options.onListening(`http://127.0.0.1:${port}/${options.token}/`);
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/viewer/html.js

@@ -28,6 +28,13 @@ export const EVENT_LIST_LIMIT = 200;
  */
 export const HTML_LABELS = {
     privacy: "Privacy: this file holds session IDs and the paths of your session logs, like nilometer explain output, and it makes no network requests. Think before sharing it.",
+    // D-097 (step G6.2): the page as nilometer view serves it.
+    privacyServed: "Privacy: nilometer view shows this page from your own computer (127.0.0.1) while it runs. Refresh asks it to read new log lines and rebuild the page; nothing leaves this computer. The page holds session IDs and the paths of your session logs.",
+    refresh: "Refresh",
+    refreshHint: "Read new log lines and status line readings, then rebuild this page",
+    refreshing: "Reading new log lines and rebuilding the page",
+    refreshFailed: "Refresh failed",
+    refreshStopped: "Couldn't reach nilometer view. Is it still running in your terminal?",
     // 2026-10-22 click-through: "What each number covers" with two bars didn't say why they differ.
     coverage: "Where the numbers come from",
     coverageWhy: "Session logs give tokens, models and limit hits. Usage percentages come only from status line readings, so they start later: when the collector was installed.",
@@ -353,9 +360,10 @@ function legend(entries) {
 /**
  * Renders the header: title, zone, last ingest, and the privacy note (README section Privacy).
  * @param data - Report data.
+ * @param serving - How `nilometer view` serves the page; omitted for a saved page.
  * @returns The header HTML.
  */
-function renderHeader(data) {
+function renderHeader(data, serving) {
     const zone = data.timeZone;
     const ingest = data.lastIngestAt === null ? "none yet" : formatInstant(data.lastIngestAt, zone);
     const meta = `Times are in ${zone}. Last ingest: ${ingest}. Report produced: ${formatInstant(data.generatedAtUtc, zone)}.`;
@@ -368,12 +376,22 @@ function renderHeader(data) {
             para(`${LABELS.hookMissingPath}: ${displayPath(data.missingHookPath, data.home)}`, "meta"),
             "</div>",
         ];
+    // Served by nilometer view: the button and where its progress shows (D-097).
+    const refresh = serving === undefined
+        ? []
+        : [
+            '<div class="nm-refresh">',
+            `<button type="button" id="nm-refresh" data-path="${escapeHtml(serving.refreshPath)}" title="${escapeHtml(HTML_LABELS.refreshHint)}">${escapeHtml(HTML_LABELS.refresh)}</button>`,
+            '<span id="nm-refresh-status" class="meta" role="status" aria-live="polite"></span>',
+            "</div>",
+        ];
     return [
         '<header class="nm-head">',
         `<h1>${escapeHtml(LABELS.title)}</h1>`,
         para(meta, "meta"),
+        ...refresh,
         ...hook,
-        para(HTML_LABELS.privacy, "privacy"),
+        para(serving === undefined ? HTML_LABELS.privacy : HTML_LABELS.privacyServed, "privacy"),
         "</header>",
     ].join("\n");
 }
@@ -1282,6 +1300,10 @@ p { margin: 0; }
 .nm-head { display: grid; gap: 6px; }
 .meta, .span, .note { font-family: var(--mono); font-size: 12px; color: var(--muted); }
 .privacy { font-size: 13px; color: var(--ink-2); }
+.nm-refresh { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
+.nm-refresh button { font: inherit; font-size: 14px; font-weight: 600; color: var(--ink); background: var(--surface); border: 1px solid var(--ink-2); border-radius: 6px; padding: 6px 14px; cursor: pointer; }
+.nm-refresh button:disabled { cursor: progress; opacity: .6; }
+@media print { .nm-refresh { display: none; } }
 .hook-warning { display: grid; gap: 4px; border-left: 3px solid var(--ink); padding: 8px 12px; background: var(--surface); font-weight: 600; }
 .eyebrow { font-family: var(--mono); font-size: 12px; letter-spacing: 0.07em; text-transform: uppercase; color: var(--water); font-weight: 600; }
 .eyebrow.projected { color: var(--silt); }
@@ -1595,15 +1617,54 @@ if (typeof document !== "undefined") {
   })();
 }
 `;
+/**
+ * The Refresh button's script, for a page `nilometer view` serves (D-097): it posts to the server,
+ * counts the seconds while the server ingests and rebuilds, then reloads the same address, so the
+ * tab in the address (#windows, #interruptions...) stays open.
+ * @returns The script, with its wording from {@link HTML_LABELS}.
+ */
+function refreshScript() {
+    const text = JSON.stringify({
+        refreshing: HTML_LABELS.refreshing,
+        failed: HTML_LABELS.refreshFailed,
+        stopped: HTML_LABELS.refreshStopped,
+    }).replace(/</g, "\\u003c");
+    return `
+"use strict";
+(function () {
+  var TEXT = ${text};
+  var button = document.getElementById("nm-refresh");
+  var status = document.getElementById("nm-refresh-status");
+  if (button === null || status === null) { return; }
+  button.addEventListener("click", function () {
+    var started = Date.now();
+    button.disabled = true;
+    function tick() { status.textContent = TEXT.refreshing + " (" + Math.round((Date.now() - started) / 1000) + " s)"; }
+    tick();
+    var timer = setInterval(tick, 1000);
+    function stop(message) { clearInterval(timer); button.disabled = false; status.textContent = message; }
+    fetch(button.getAttribute("data-path"), { method: "POST" })
+      .then(function (response) {
+        return response.json().then(function (body) {
+          if (response.ok && body.ok) { clearInterval(timer); location.reload(); return; }
+          stop(TEXT.failed + ": " + body.message);
+        });
+      })
+      .catch(function () { stop(TEXT.stopped); });
+  });
+})();
+`;
+}
 /**
  * Renders the whole page (step G1.3, D-070): header, coverage, the observed sections, the seam,
  * and the projected monthly section, in the text report's order, with the event table embedded for
  * the script and a table view under every chart.
  * @param data - Everything the report draws, from `loadHtmlData`.
+ * @param serving - How `nilometer view` serves the page (D-097); omitted for a saved page.
  * @returns One self-contained, ASCII-only HTML document; never throws for well-formed data.
  * @see D-070
  */
-function renderPage(data) {
+function renderPage(data, serving) {
     const options = { timeZone: data.timeZone, width: CHART_WIDTH };
     const embedded = embedJson({ timeZone: data.timeZone, files: data.files, events: data.events });
     return [
@@ -1617,7 +1678,7 @@ function renderPage(data) {
         "</head>",
         "<body>",
         "<main>",
-        renderHeader(data),
+        renderHeader(data, serving),
         // Navigation only: its labels name the tabs, so the projected group's label sits above the
         // seam, while every projected panel stays below it in the document (principle 2, D-084).
         renderTabBar(),
@@ -1639,6 +1700,8 @@ function renderPage(data) {
         "</main>",
         `<script type="application/json" id="nm-data">${embedded}</script>`,
         `<script>${PAGE_SCRIPT}</script>`,
+        // Only when served: a saved page makes no network requests (D-097).
+        ...(serving === undefined ? [] : [`<script>${refreshScript()}</script>`]),
         "</body>",
         "</html>",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nilometer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reports the observed cost of a Claude subscription: interruptions when the plan is too small, unused headroom when it is too big.",
   "license": "MIT",
   "author": "Mark Fariñas",