@adrrr/tarmac 0.8.1 → 0.10.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/fleet.js

@@ -14,7 +14,7 @@ import path from 'node:path';
 import { DEFAULT_STALE_AFTER_MS } from './config.js';
 import { measured, windowsApart } from './limits.js';
 import { guardVersions } from './schema.js';
-import { isWaiting } from './sessions.js';
+import { anchoredOnKind, isBackgroundAgent, isWaiting } from './sessions.js';
 import { SID_NAME } from './wrapper.js';
 export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_STALE_AFTER_MS, discovery = null, }) {
     const rows = sessions.map((s) => {
@@ -43,7 +43,14 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
         };
     });
     rows.sort((a, b) => rank(a) - rank(b) || (b.ctxPct ?? -1) - (a.ctxPct ?? -1));
-    const covered = rows.filter((r) => r.ctxState !== 'absent').length;
+    // The population the coverage numbers are about. An agent has no TUI, so it never draws a
+    // frame and no statusline can ever file a snapshot for it: counted among the blind, one
+    // agent beside one chained terminal read as "chained on 1/2 sessions — run tarmac install",
+    // remediation that is already done and cannot work for the entry that raised it (#29). The
+    // map made the same call for the agent strip; this is the fleet-wide line catching up.
+    const anchored = anchoredOnKind(rows);
+    const chainable = rows.filter((r) => !isBackgroundAgent(r, anchored));
+    const covered = chainable.filter((r) => r.ctxState !== 'absent').length;
     // Blind AND unfilable, in that order — this number exists to say how many of the blind will
     // stay blind, and both renderers subtract it from them. A session can be unfilable and
     // covered at the same time: a snapshot written by a pre-upgrade wrapper under a non-UUID
@@ -51,8 +58,10 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
     // than on the filename. Counting that one would push this past the blind count and make the
     // renderers explain away someone else's missing telemetry.
     // A null id is `noSessionId`'s business — a discovery failure, not a naming one.
-    const unfilable = rows.filter((r) => r.ctxState === 'absent' && r.sessionId !== null && !SID_NAME.test(r.sessionId)).length;
-    const drift = rows.filter((r) => r.ctxState === 'drift').length;
+    const unfilable = chainable.filter((r) => r.ctxState === 'absent' && r.sessionId !== null && !SID_NAME.test(r.sessionId)).length;
+    // Over the same population as `covered`, because `schemaBroken` below compares the two and a
+    // comparison between two different populations answers a question nobody asked.
+    const drift = chainable.filter((r) => r.ctxState === 'drift').length;
     // Having a snapshot and having a cost are different facts, and only the second one is
     // allowed to feed the total.
     const costs = rows.map((r) => r.costUsd).filter((c) => typeof c === 'number');
@@ -67,6 +76,7 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
         rows,
         health: {
             sessions: rows.length,
+            chainable: chainable.length,
             covered,
             unfilable,
             drift,

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.
@@ -176,6 +221,8 @@ export async function readRange({ dir, range, now, capped = false }) {
     }
     return {
         range,
+        from: windowStart,
+        to: windowEnd,
         hours: [...hours.entries()]
             .sort(([a], [b]) => a - b)
             .map(([t, acc]) => ({

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 };