@adrrr/tarmac 0.8.1 → 0.9.0

package/dist/demo.js

@@ -0,0 +1,392 @@
+// P6 — the fleet `tarmac serve --demo` shows.
+//
+// Why it ships. A first run is one session and no record: a table of one row and three charts
+// with nothing in them, which is the screen that sells this tool to everybody who has not
+// installed it yet (#150). `--demo` puts a plausible fleet and a day of its history in front of
+// that reader instead, and says on the page that it is invented.
+//
+// Where it plugs in, and why THERE. The product's pitch is that it parses no internal format:
+// it reads `claude agents --json` and the statusline payload, both documented, and joins them.
+// So this module feeds the structures those two are already PARSED into — `Session[]` and a map
+// of `Snapshot` — and hands them to the same `buildFleet` the real collector calls. It writes no
+// JSON for anyone to read back, prints no `claude agents --json` for anyone to parse, and there
+// is therefore no second parsing path to keep in step with the first. A demo built the other way
+// round — a fake CLI whose output the real reader re-parses — would be a copy of the one surface
+// this repo cannot afford to have two of.
+//
+// What it may not do, held by `test/demo.test.ts`: read this machine's FLEET, spawn anything, or
+// write a byte. Every path below hangs off an invented home, and the end-to-end checks run the
+// real `serve --demo` with no `claude` on the box and no snapshot directory anywhere.
+//
+// "Its fleet", precisely, and not "nothing at all": `serve` still resolves its settings, so a
+// config file naming a port or a trusted host is read under `--demo` exactly as it always was.
+// What is never opened is the snapshot directory, `claude`, and the journal.
+import { DEFAULT_STALE_AFTER_MS } from './config.js';
+import { buildFleet } from './fleet.js';
+import { createHistory, HISTORY_CADENCE_MS, HISTORY_SLOTS } from './history.js';
+/**
+ * The invented home every path here hangs off. Never `os.homedir()`, ever — a demo that
+ * borrowed one string off the machine it runs on would put somebody's directory names into
+ * every screenshot taken of it.
+ */
+export const DEMO_HOME = '/Users/jane';
+/** Where the invented sessions are working. Ordinary names, belonging to nobody. */
+const WORK = `${DEMO_HOME}/work`;
+/** How many sessions the shown minute holds. Eight is a fleet; one is the screen #150 is about. */
+export const DEMO_SESSIONS = 8;
+/**
+ * How many minutes of fleet the demo plays. One more than the ring holds, so the record served
+ * to the scrubber has dropped a slot and dates itself by its own oldest reading rather than by
+ * the moment the process started — which would be a day later than the day it is showing.
+ */
+export const DEMO_MINUTES = HISTORY_SLOTS + 1;
+/** The Claude Code whose payload shapes this repo has fixtures for, so nothing reads unchecked. */
+const CC_VERSION = '2.1.232';
+/** The context window every invented session is filling. */
+const CTX_WINDOW = 1_000_000;
+/** The five-hour window, in minutes, and how full each successive one gets. */
+const WINDOW_MINUTES = 300;
+const WINDOW_PEAKS = [58, 84, 71, 49, 77];
+/**
+ * Where the seven-day window stands at the newest minute, and what a day of this fleet costs
+ * it. Six points a day over the journal's seven days lands the oldest hour near 1% — a slope
+ * chosen against `DEMO_JOURNAL_DAYS`, because `readLimits` refuses a negative percentage and a
+ * steeper week would not draw a wrong line, it would draw nothing.
+ */
+const SEVEN_DAY_TOP = 43;
+const SEVEN_DAY_PER_DAY = 6;
+const OPUS = { id: 'claude-opus-5', display_name: 'Opus 5' };
+const FABLE = { id: 'claude-fable-5', display_name: 'Fable 5' };
+/**
+ * The eight. Ordinary project names under an invented home, and the two background agents are
+ * named after their prompt, which is what `claude agents --json` calls one.
+ *
+ * They arrive across the day rather than all at midnight — three at the start, eight by the end
+ * — because a record whose every minute holds the same fleet is a scrubber with nothing behind
+ * it, and flat charts are the thing #150 is replacing.
+ */
+const ACTORS = [
+    {
+        sid: '4e91c0a7-1d35-4b82-9f60-3a7c58d2e014',
+        cwd: `${WORK}/api-gateway`,
+        name: 'api-refactor',
+        kind: 'interactive',
+        pid: 30412,
+        model: OPUS,
+        effort: 'high',
+        born: 0,
+        ctxFrom: 8,
+        // Steep enough that this one ends the day near a compact. A fleet whose fullest window is
+        // two thirds is a fleet with nothing at stake, and the number most people install this to
+        // watch is the one that is about to run out.
+        ctxPerBusyMinute: 0.147,
+        costPerBusyMinute: 0.038,
+        ageMs: 2_000,
+        // The recycle at 642 is why its ramp restarts: a compacted session is a new window.
+        fresh: { from: 642, to: 654 },
+        segments: [
+            { from: 0, status: 'idle' },
+            { from: 126, status: 'busy' },
+            { from: 488, status: 'idle' },
+            { from: 654, status: 'busy' },
+            { from: 1088, status: 'idle' },
+            { from: 1297, status: 'busy' },
+        ],
+    },
+    {
+        sid: '9b2f47d1-6c08-4a53-8e19-2d4b70f6c385',
+        cwd: `${WORK}/docs-site`,
+        name: 'docs-site',
+        kind: 'interactive',
+        pid: 31877,
+        model: FABLE,
+        effort: 'medium',
+        born: 0,
+        ctxFrom: 5,
+        ctxPerBusyMinute: 0.07,
+        costPerBusyMinute: 0.019,
+        ageMs: 68_000,
+        segments: [
+            { from: 0, status: 'idle' },
+            { from: 318, status: 'busy' },
+            { from: 536, status: 'idle' },
+            { from: 1120, status: 'busy' },
+            { from: 1392, status: 'idle' },
+        ],
+    },
+    {
+        sid: '6a04d92e-8b17-4c60-95f3-0e2a6b48d1c7',
+        cwd: `${WORK}/data-pipeline`,
+        name: 'data-pipeline',
+        kind: 'interactive',
+        pid: 44120,
+        model: FABLE,
+        effort: 'max',
+        born: 0,
+        ctxFrom: 11,
+        ctxPerBusyMinute: 0.06,
+        costPerBusyMinute: 0.041,
+        ageMs: 3_000,
+        segments: [
+            { from: 0, status: 'busy' },
+            { from: 74, status: 'idle' },
+            { from: 412, status: 'busy' },
+            { from: 869, status: 'idle' },
+            { from: 1013, status: 'busy' },
+        ],
+    },
+    {
+        sid: '1c58e3b6-4f70-49a2-b3d8-6e015a9c7f24',
+        cwd: `${WORK}/auth-service`,
+        name: 'bugfix-auth',
+        kind: 'interactive',
+        pid: 42713,
+        model: OPUS,
+        effort: 'high',
+        born: 214,
+        ctxFrom: 4,
+        ctxPerBusyMinute: 0.09,
+        costPerBusyMinute: 0.033,
+        ageMs: 5_000,
+        segments: [
+            { from: 214, status: 'idle' },
+            { from: 266, status: 'busy' },
+            { from: 702, status: 'idle' },
+            { from: 1204, status: 'busy' },
+            // The one state that is work for the READER, and the only one that captions itself.
+            { from: 1398, status: 'waiting', waitingFor: 'permission prompt' },
+        ],
+    },
+    {
+        sid: '8e15fa03-7d62-4b91-83c0-5b9e14d6a07f',
+        cwd: `${WORK}/api-gateway`,
+        name: 're-run the payments suite until it is green',
+        kind: 'background',
+        pid: null,
+        model: FABLE,
+        effort: 'max',
+        born: 483,
+        ctxFrom: 4,
+        ctxPerBusyMinute: 0.05,
+        costPerBusyMinute: 0.017,
+        ageMs: 4_000,
+        segments: [{ from: 483, status: 'working' }],
+    },
+    {
+        sid: '3d76b18f-5029-4e74-a6c1-84f037b9e2d5',
+        cwd: `${WORK}/docs-site`,
+        name: 'release-notes',
+        kind: 'interactive',
+        pid: 46308,
+        model: OPUS,
+        effort: 'medium',
+        born: 908,
+        ctxFrom: 3,
+        ctxPerBusyMinute: 0.08,
+        costPerBusyMinute: 0.024,
+        ageMs: 9_000,
+        segments: [
+            { from: 908, status: 'idle' },
+            { from: 1004, status: 'busy' },
+            // A word `claude agents --json` prints and tarmac has no boolean for. It draws as
+            // `unknown`, never as idle, and the page names it above the fleet — which is the whole
+            // promise of the tool, so the demo shows it rather than a fleet with nothing to say.
+            { from: 1376, status: 'compacting' },
+        ],
+    },
+    {
+        sid: '2b90c47a-3e58-4fd6-9107-6ca85f2b0d93',
+        cwd: `${WORK}/data-pipeline`,
+        name: 'draft the migration notes',
+        kind: 'background',
+        pid: null,
+        model: OPUS,
+        effort: 'high',
+        born: 1017,
+        ctxFrom: 6,
+        ctxPerBusyMinute: 0.06,
+        costPerBusyMinute: 0.022,
+        ageMs: 7_000,
+        segments: [{ from: 1017, status: 'working' }],
+    },
+    {
+        sid: '5f8a63d0-9c14-4720-b8e5-71d3062fa4c8',
+        cwd: `${WORK}/storefront`,
+        name: 'checkout-flow',
+        kind: 'interactive',
+        pid: 47122,
+        model: FABLE,
+        effort: 'high',
+        born: 1183,
+        ctxFrom: 2,
+        ctxPerBusyMinute: 0.12,
+        costPerBusyMinute: 0.046,
+        ageMs: 47_000,
+        segments: [
+            { from: 1183, status: 'idle' },
+            { from: 1251, status: 'busy' },
+            { from: 1424, status: 'idle' },
+        ],
+    },
+];
+/** Whether a status word means the session is spending tokens right now. */
+const working = (status) => status === 'busy' || status === 'working';
+/** Which segment an actor is in at `minute`. */
+function segmentAt(actor, minute) {
+    let current = actor.segments[0];
+    for (const s of actor.segments)
+        if (s.from <= minute)
+            current = s;
+    return current;
+}
+/** How many minutes of work an actor has done by `minute` — what fills a window and costs money. */
+function busyMinutes(actor, minute) {
+    let total = 0;
+    for (let i = 0; i < actor.segments.length; i++) {
+        const s = actor.segments[i];
+        if (!working(s.status))
+            continue;
+        const until = Math.min(actor.segments[i + 1]?.from ?? Infinity, minute + 1);
+        total += Math.max(0, until - s.from);
+    }
+    return total;
+}
+/**
+ * The account's two windows at `minute`. The five-hour one is what the replay is really about:
+ * it fills, rolls over at the boundary and fills again, four or five times in a day.
+ *
+ * Both resets are measured from `now`, the clock that took the reading, and not from the start
+ * of the invented day. For a seeded minute the two are the same instant and this changes
+ * nothing. For the live view they are not: it answers the last minute of the day for as long as
+ * the serve is open, so a reset pinned to `dayStart` fell into the past about an hour in, and
+ * the header then read "reset was due 4h ago" over a percentage that had not moved. That phrase
+ * is this codebase's own way of saying the number beside it belongs to a window that is gone,
+ * and a demo has no business showing it about an account nobody has.
+ */
+function rateLimits(minute, now, cyclesBack = 0) {
+    const window = Math.floor(minute / WINDOW_MINUTES);
+    const elapsed = minute % WINDOW_MINUTES;
+    const peak = WINDOW_PEAKS[window % WINDOW_PEAKS.length];
+    return {
+        five_hour: {
+            used_percentage: Math.round((peak * elapsed) / WINDOW_MINUTES),
+            resets_at: Math.round((now + (WINDOW_MINUTES - elapsed) * 60_000) / 1000),
+        },
+        seven_day: {
+            // Climbing across the whole invented week, not the cycle: the day repeats, and a ramp
+            // relative to the cycle replayed itself — a 14-point fall at every boundary, drawn as a
+            // "7d reset" line no real account produces daily. `cyclesBack` is how many cycles before
+            // the newest day this reading belongs to, so consecutive cycles join to the point.
+            used_percentage: Math.max(0, Math.round(SEVEN_DAY_TOP - SEVEN_DAY_PER_DAY * (cyclesBack + 1 - minute / DEMO_MINUTES))),
+            // Mid-week: far enough out that the five-hour window above never rolls it over.
+            resets_at: Math.round((now + 4.5 * 24 * 3600 * 1000) / 1000),
+        },
+    };
+}
+/** How full an actor's window is at `minute`, and `null` for one that has taken no turn yet. */
+function contextAt(actor, minute) {
+    if (actor.fresh !== undefined && minute >= actor.fresh.from && minute < actor.fresh.to)
+        return null;
+    // A recycle does not reset the WORK an actor has done, so the ramp is measured from the
+    // minute it was recycled rather than from midnight — otherwise a compacted session comes back
+    // fuller than it was before, which is the opposite of what compacting does.
+    const since = actor.fresh !== undefined && minute >= actor.fresh.from ? busyMinutes(actor, actor.fresh.from) : 0;
+    return Math.min(97, Math.round(actor.ctxFrom + actor.ctxPerBusyMinute * (busyMinutes(actor, minute) - since)));
+}
+/**
+ * One minute of the invented day, as the two sources would have been PARSED into it.
+ *
+ * `now` is what dates the reading, and it is separate from the minute being played: the live
+ * view always shows the last minute of the day, dated by the clock that asked for it, so two
+ * captures taken an hour apart are the same picture.
+ */
+export function demoFleetAt(minute, dayStart, now = dayStart + minute * 60_000, staleAfterMs = DEFAULT_STALE_AFTER_MS, cyclesBack = 0) {
+    const live = ACTORS.filter((a) => minute >= a.born);
+    const sessions = live.map((a) => {
+        const segment = segmentAt(a, minute);
+        return {
+            sessionId: a.sid,
+            pid: a.pid,
+            cwd: a.cwd,
+            name: a.name,
+            kind: a.kind,
+            startedAt: dayStart + a.born * 60_000,
+            status: segment.status,
+            waitingFor: segment.waitingFor ?? null,
+            // The same rule the parser applies, spelled here rather than borrowed: a word it does not
+            // recognise is `null`, never `false`, and `compacting` below is exactly such a word.
+            busy: working(segment.status) ? true : segment.status === 'idle' || segment.status === 'done' ? false : null,
+        };
+    });
+    const limits = rateLimits(minute, now, cyclesBack);
+    const snapshots = new Map();
+    for (const a of live) {
+        const pct = contextAt(a, minute);
+        snapshots.set(a.sid, {
+            sessionId: a.sid,
+            // The discriminant is the PRESENCE of the key, never its value: a session that has taken
+            // no turn reads `fresh` and reports no percentage, which is not a session at zero.
+            ctxState: pct === null ? 'fresh' : 'ok',
+            ctxPct: pct,
+            ctxTokens: pct === null ? null : Math.round((pct / 100) * CTX_WINDOW),
+            ctxWindow: CTX_WINDOW,
+            model: a.model.display_name,
+            modelId: a.model.id,
+            effort: a.effort,
+            costUsd: round2(a.costPerBusyMinute * busyMinutes(a, minute)),
+            ccVersion: CC_VERSION,
+            rateLimits: limits,
+            ageMs: a.ageMs,
+            file: `${DEMO_HOME}/.local/state/tarmac/snapshots/${a.sid}.json`,
+        });
+    }
+    // Discovery's own health, which a shortcut here would drop: without it `discovered` and
+    // `noSessionId` are computed from the rows alone, and the page would report on a discovery
+    // that never happened rather than on the one the demo is standing in for.
+    const discovery = {
+        seen: sessions.length,
+        noSessionId: 0,
+        unknownStatus: sessions.filter((s) => s.busy === null && s.status !== 'waiting').length,
+    };
+    const fleet = buildFleet({ sessions, snapshots, now, staleAfterMs, discovery });
+    // What the collector fills in, filled in here for the same reason it does it there: these
+    // five are how the page tells "nothing to report" from "we could not look", and leaving them
+    // undefined would render the second as the first.
+    fleet.health.snapshotsError = null;
+    fleet.health.snapshotsUnreadable = 0;
+    fleet.health.snapshotsNotFiles = 0;
+    fleet.health.snapshotsDuplicates = 0;
+    fleet.health.snapshotsDir = `${DEMO_HOME}/.local/state/tarmac/snapshots`;
+    return fleet;
+}
+/** The day ends now, so its last minute is the fleet the live view shows. */
+export const demoDayStart = (now = Date.now()) => now - (DEMO_MINUTES - 1) * 60_000;
+/**
+ * The record behind the scrubber, played in whole at startup.
+ *
+ * The same fleets the live view is built from, through the same `record` a real sampler calls —
+ * so the replay is a reduction of the demo rather than a second account of it, kept in step by
+ * hand. Nothing here touches disk: this is the in-memory ring, which is where a real serve's
+ * last 24 hours live too.
+ */
+export function demoHistory(dayStart, cadence = HISTORY_CADENCE_MS) {
+    const history = createHistory({ since: dayStart, cadence });
+    for (let minute = 0; minute < DEMO_MINUTES; minute++)
+        history.record(demoFleetAt(minute, dayStart));
+    return history;
+}
+/**
+ * What `serve --demo` reads instead of the machine.
+ *
+ * Always the last minute of the invented day, dated by the clock that asked: the fleet does not
+ * walk on while a serve is open, so a screenshot of it now and one taken in an hour show the
+ * same eight sessions doing the same things, with the account's two windows counting down from
+ * whenever they were read rather than from a reset that has since gone past.
+ *
+ * The record behind the scrubber holds still too: a demo serve runs no sampler, so the day
+ * seeded below is the day it keeps for as long as it is open.
+ */
+export function demoCollector(dayStart, now = Date.now, staleAfterMs = DEFAULT_STALE_AFTER_MS) {
+    return () => Promise.resolve(demoFleetAt(DEMO_MINUTES - 1, dayStart, now(), staleAfterMs));
+}
+const round2 = (n) => Math.round(n * 100) / 100;

package/dist/history-range.js

@@ -42,9 +42,57 @@ const RESET_DROP_POINTS = 5;
  * the fleet on, and thirty files opened at once is thirty buffers of a day each in memory for
  * an answer that is a few hundred rows.
  */
-export async function readRange({ dir, range, now, capped = false }) {
+export async function readRange({ dir, range, now, capped = false, readDay }) {
     const daysRequested = RANGE_DAYS[range];
     const coverage = { daysRequested, lines: 0, skipped: 0, outOfRange: 0, droppedSessions: 0, capped };
+    // The default reader, built here rather than in the signature because it counts into
+    // `coverage`: a day file refused by kind is a record this range could not read, which is the
+    // question `skipped` answers — and only the DISK path can meet one. An injected reader
+    // (#156's invented week) never opens a name, so the guard is the default's own.
+    //
+    // What is behind the name is not this reader's to assume. The store writes day files into
+    // a directory that belongs to the user, and anything can land in it: `fs.readFile` on a
+    // FIFO blocks until someone writes to the other end, which hung this read, the request
+    // waiting on it, and every request that joined the cached read behind it (#136). So the
+    // kind is asked BEFORE the open, and only a regular file is opened.
+    //
+    // `lstat`, not `stat`, and NOT for the pipe: `stat` reports the target's kind, so it
+    // refuses a link pointing at a FIFO exactly as this does. The one shape the two disagree
+    // about is a link to a regular file, and that is the whole of the choice. A journal file
+    // is a file this store appended to; a symbolic link is a name somebody else put there,
+    // aimed at something nobody told this reader about, and following it reads whatever it
+    // is aimed at today. Only what we wrote, which is `reap.ts`'s rule for the same reason.
+    //
+    // A HARD link to a regular file is the shape neither call can see — it carries the
+    // target's inode, so it reads as a plain file and its day lands in `days[]`. No hang can
+    // come of it (a hard link to a FIFO is still refused by kind), so what this guard holds
+    // is "nothing that can block", not "nothing somebody else named".
+    //
+    // The cost, and it is real: `history-store.ts:386` measures the directory with `statSync`,
+    // so a linked day file is charged to the 256 MB cap and never read. The two readings of
+    // one directory disagree by exactly that shape, and this is the side that refuses.
+    //
+    // A check before an open is a race, and it stays one: nothing stops the name being
+    // replaced between the two. What it costs is bounded — one hung read, once, on a
+    // directory somebody is racing — and `serve` answers 504 rather than waiting for it.
+    const readDayFromDisk = async (date) => {
+        const file = path.join(dir, `${date}.jsonl`);
+        try {
+            if (!(await fs.lstat(file)).isFile()) {
+                // Counted rather than passed over, and counted here: a day file that is not a file is
+                // a record this range could not read, which is the question `skipped` answers.
+                coverage.skipped += 1;
+                return null;
+            }
+            return await fs.readFile(file, 'utf8');
+        }
+        catch {
+            // A day with no file is the normal case: `serve` was not running. A day whose file cannot
+            // be read is the same answer for this reader, and `serve` is not the process that fixes it.
+            return null;
+        }
+    };
+    const read = readDay ?? readDayFromDisk;
     const hours = new Map();
     const days = new Map();
     const resets = [];
@@ -64,15 +112,12 @@ export async function readRange({ dir, range, now, capped = false }) {
     const windowStart = startOfDay(now, daysRequested - 1);
     const windowEnd = startOfDay(now, -1);
     for (const date of days_) {
-        let text;
-        try {
-            text = await fs.readFile(path.join(dir, `${date}.jsonl`), 'utf8');
-        }
-        catch {
-            // A day with no file is the normal case: `serve` was not running. A day whose file cannot
-            // be read is the same answer for this reader, and `serve` is not the process that fixes it.
+        // A day with nothing for it is the normal case: `serve` was not running. A day whose file
+        // cannot be read is the same answer for this reader — both readers swallow their own
+        // failure — and `serve` is not the process that fixes it.
+        const text = await read(date);
+        if (text === null)
             continue;
-        }
         // The day a record is CHARGED to is the file it is in, and the hour it falls in is its own
         // clock. The file name is the day the writer decided on, so a reading taken a second before
         // midnight stays on the day it was journalled to rather than moving under the reader.

package/dist/history-store.js

@@ -23,6 +23,7 @@
 // write (#133).
 import fs from 'node:fs';
 import path from 'node:path';
+import { readRange } from './history-range.js';
 /**
  * The ceiling nobody can raise. The age limit is the reader's number and it is not a bound on
  * its own: it prices a fleet of eight sessions at about a megabyte a day, and a fleet of two
@@ -196,8 +197,11 @@ const oldestKept = (now, days) => {
  * added to `HistorySession` tomorrow does not compile here until somebody has decided whether
  * it belongs in a file that outlives the process. The omission that has to survive every future
  * edit cannot be written as a subtraction from a shape that is free to grow.
+ *
+ * Exported for the demo's invented journal, which is the one other thing that produces a line
+ * of this shape: a second allowlist written out by hand there is a second thing to keep true.
  */
-const lineOf = ({ t, sessions, rateLimits }) => ({
+export const journalRecordOf = ({ t, sessions, rateLimits }) => ({
     t,
     sessions: sessions.map(({ sid, project, kind, state, ctxState, ctxPct, costUsd }) => ({
         sid,
@@ -350,7 +354,7 @@ export function createHistoryStore({ dir, days, now = Date.now, maxBytes = HISTO
                 prunedDay = day;
             // One line, one reading, terminated: a reader tailing this file sees whole records, and a
             // process killed between two appends leaves the last one complete.
-            const line = JSON.stringify(lineOf(sample)) + '\n';
+            const line = JSON.stringify(journalRecordOf(sample)) + '\n';
             const bytes = Buffer.byteLength(line);
             const onDisk = measure().bytes;
             if (onDisk + bytes > maxBytes) {
@@ -373,6 +377,12 @@ export function createHistoryStore({ dir, days, now = Date.now, maxBytes = HISTO
             }
         },
         prune,
+        read(range, at) {
+            // `capped` is read here rather than passed in by the caller: it is a fact about this
+            // writer, and a journal at its ceiling looks from the disk alone exactly like a fleet
+            // that went quiet.
+            return readRange({ dir, range, now: at, capped });
+        },
         stats() {
             const { files, bytes } = measure();
             return { files, bytes, misses, stopped, capped };

package/dist/history-view.js

@@ -620,7 +620,7 @@ export const HISTORY_CSS = `
      two account-wide charts side by side under it; the phone block stacks them, one chart to
      a screen. */
   .view-history { display:grid; grid-template-columns:1fr 1fr; gap:1rem; align-items:start; }
-  #ctx, .hist-off, .view-history > .note { grid-column:1 / -1; }
+  #ctx, .hist-off, .hist-empty, .view-history > .note { grid-column:1 / -1; }
   .view-history > .note { margin-top:0; }
   .chart { border:1px solid var(--line); border-radius:12px; padding:.65rem .8rem .7rem; min-width:0; }
   /* The margin is what the way-back-to-now's tap target is drawn into. That overlay reaches
@@ -679,7 +679,11 @@ export const HISTORY_CSS = `
   /* Off is not a fault, so it is not a .warn: a framed sentence in the page's own ink, with
      the one key that turns it on. */
   .hist-off { border:1px solid var(--line); border-radius:8px; padding:.5rem .7rem; font-size:.8rem; line-height:1.5; }
-  .hist-off code, .view-history .note code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.95em; }
+  /* Same frame as "off" above, and for the same reason: a serve that has been running a minute
+     is not a fault either. It sits directly over the charts it is about, because "where are my
+     curves" is a question asked while looking at the place they will be. */
+  .hist-empty { border:1px solid var(--line); border-radius:8px; padding:.5rem .7rem; font-size:.8rem; line-height:1.5; }
+  .hist-off code, .hist-empty code, .view-history .note code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.95em; }
   /* The other two views are in the shell on every address — the tabs between them are meant to
      cost nothing — so the one being read hides the pair it stands in front of. History is the
      exception and ships only on its own address: it carries a script and three canvases, and a
@@ -739,12 +743,13 @@ const chart = (id, name, sub) => `<section class="chart" id="${id}" role="group"
  * script after a round trip. A reader with no journal never sees a range flicker from live to
  * refused, and a browser with no JavaScript still gets told why the page is empty.
  */
-export function renderHistoryView({ historyEnabled }) {
+export function renderHistoryView({ historyEnabled, demo = false }) {
     const off = !historyEnabled;
     return `<div class="view view-history">
 ${off
         ? `  <div class="hist-off" id="hist-off" role="status"><strong>History is off.</strong> The last 24h live in memory while <code>tarmac serve</code> runs and go when it stops; nothing is written to disk. To keep 7 and 30 days, add <code>{"history": {"days": 30}}</code> to <code>~/.claude/tarmac/config.json</code> and start <code>serve</code> again.</div>\n`
-        : ''}${chart('ctx', 'Context', 'per session &middot; 24h')}
+        : ''}  <div class="hist-empty" id="hist-empty" role="status" hidden><strong>Nothing to draw yet.</strong> <code>tarmac serve</code> reads the fleet once a minute, so the context lines start within a minute or two, the cost bars fill an hour at a time, and the quota curve needs a few readings before it has a shape. A session has to be open for any of them to have a subject. Leave the serve running and come back. To see all three full right now, without waiting: <code>tarmac serve --demo</code>.</div>
+${chart('ctx', 'Context', 'per session &middot; 24h')}
 ${chart('cost', 'Cost', 'per project &middot; hourly &middot; 24h')}
 ${chart('quota', 'Quota', 'account &middot; 24h')}
   <p class="note">Recorded once a minute, only while <code>tarmac serve</code> runs. A minute it was not running is a minute with no reading, drawn as a gap and never as a zero. A session recycled overnight comes back as a new line from its first frame.${off ? '' : ' The journal keeps the same fields as the ring, no names and no paths.'}</p>
@@ -753,9 +758,11 @@ ${chart('quota', 'Quota', 'account &middot; 24h')}
     <button type="button" id="range-24h" data-range="24h" aria-pressed="true">24h</button>
     <button type="button" id="range-7d" data-range="7d" aria-pressed="false"${off ? ' disabled' : ''}>7d</button>
     <button type="button" id="range-30d" data-range="30d" aria-pressed="false"${off ? ' disabled' : ''}>30d</button>
-    <div class="covers" id="hist-covers">${off
+    <div class="covers" id="hist-covers"${demo ? ' data-days="days invented"' : ''}>${off
         ? '24h from memory &middot; 7d and 30d need the journal, which is off'
-        : '24h from memory &middot; 7d and 30d from the journal on disk'}</div>
+        : demo
+            ? '24h from memory &middot; 7d and 30d from a journal invented in memory'
+            : '24h from memory &middot; 7d and 30d from the journal on disk'}</div>
   </div>
 </div>`;
 }
@@ -790,6 +797,24 @@ ${PURE.map((fn) => String(fn)).join('\n\n')}
   // and not this page's — and a copy of both, kept in step by hand, is how the two come to
   // disagree.
   var covers24 = covers.textContent;
+  // Whether this serve has a journal at all. It decides which of the two blocks a page with
+  // nothing in it raises: with no journal the server has already shipped the one that names that
+  // cause and its fix, and a second block under it offering a minute of patience is one screen
+  // saying two things (#157).
+  //
+  // Read off the page rather than asked for down the wire, for the reason the sentence above is:
+  // it is the config's answer, the server has it, and a round trip to be told it would leave the
+  // question open for as long as the request took. Off the PILL and not off the block it is
+  // really about, which would read better — the eighty-line DOM the suite executes this script
+  // on hands back an element for every id asked of it, so an assertion about a block the server
+  // did not ship cannot be written there, while a disabled attribute it did ship can. The two
+  // are the same fact: one flag in the view above writes both.
+  var journalOff = el('range-7d').disabled;
+  // What this serve calls the days behind its two long ranges. The sentence above is the
+  // server's and is kept rather than written again; this is the half of it the script rebuilds
+  // per range, and where a day came from is no more this page's answer there than it is here.
+  // Absent is what every serve that reads its journal off a disk says, which is most of them.
+  var daysWord = covers.getAttribute('data-days') || 'days on disk';
   var state = { range: '24h', data: null, err: null, iso: {}, cursor: {}, loading: false, gen: 0 };
   // Which series a chart is isolated on, or null. Read through a function and compared against
   // null rather than tested for truth: path.basename('/') is the empty string, so a project
@@ -1161,9 +1186,57 @@ ${PURE.map((fn) => String(fn)).join('\n\n')}
     el(id + '-legend').hidden = true;
   }
 
+  /*
+   * Is there a single number in the ring? The three charts plot exactly three things, and this
+   * asks whether the record holds any of them: a context percentage, a cost, or a window
+   * reading. Nothing else counts as something to draw.
+   *
+   * A first cut asked whether the ring held any SAMPLE, and those two part company sixty
+   * seconds in, which is the worst possible moment. A serve started before the statusline is
+   * chained, or with no session open, records a sample a minute carrying nothing at all: the
+   * sample count says "we are away" while the charts are still empty, and the block came down
+   * over a page no more explanatory than it was at the start. Counting blank canvases does not
+   * fix it either, because two of the three draw an empty grid rather than blanking whenever
+   * the span is non-zero, however little is in it.
+   */
+  function drawable() {
+    var s = state.data && state.data.samples, i, j, ses, lim, k;
+    if (!s) return false;
+    for (i = 0; i < s.length; i++) {
+      lim = s[i].rateLimits;
+      for (k in lim) if (lim[k] && typeof lim[k].used_percentage === 'number') return true;
+      ses = s[i].sessions || [];
+      for (j = 0; j < ses.length; j++) {
+        if (typeof ses[j].ctxPct === 'number' || typeof ses[j].costUsd === 'number') return true;
+      }
+    }
+    return false;
+  }
+
+  /*
+   * Whether this is a serve with nothing to draw, which is what a first run looks like (#151).
+   *
+   * The ring only. An empty 7d is a journal that was not running for a week, and this block's
+   * answer, wait a minute and the lines will come, is not true of that. The canvas goes on
+   * saying "no readings in this range" there, which is the honest verdict.
+   *
+   * Neither loading nor an error counts: both are states in which nothing has been read yet,
+   * and a block raised over a request still in flight would be answering a question the
+   * record is about to answer itself. Same rule the blank canvas applies one function up.
+   *
+   * Nor does a serve with no journal, which is the FIRST default run and where both blocks
+   * used to come up together (#157): the server has already raised the other one there.
+   */
+  function firstRun() {
+    if (journalOff) return false;
+    if (state.range !== '24h' || state.loading || state.err !== null) return false;
+    return !drawable();
+  }
+
   var draw = { ctx: drawCtx, cost: drawCost, quota: drawQuota };
   function redraw() {
     covers.textContent = coversText();
+    el('hist-empty').hidden = !firstRun();
     if (!state.data) { ids.forEach(function (id) { blank(id, state.range); }); return; }
     ids.forEach(function (id) { draw[id](); });
   }
@@ -1202,7 +1275,7 @@ ${PURE.map((fn) => String(fn)).join('\n\n')}
     if (state.loading) return 'reading ' + state.range + '…';
     if (state.range === '24h') return covers24;
     if (!d || !d.coverage) return state.range + ' from the journal';
-    var c = d.coverage, said = state.range + ' from the journal · ' + d.days.length + ' of ' + c.daysRequested + ' days on disk';
+    var c = d.coverage, said = state.range + ' from the journal · ' + d.days.length + ' of ' + c.daysRequested + ' ' + daysWord;
     // Said once and quietly: a journal that stopped at its cap, and readings the reader could
     // not use. Neither is a fault to shout about, and both change what the charts above mean.
     if (c.capped) said += ' · journal capped';