@adrrr/tarmac 0.7.0 → 0.8.0

package/dist/history.js

@@ -42,6 +42,7 @@ export function createHistory({ since, cadence }) {
         record(fleet) {
             const sample = sampleOf(fleet);
             push({ t: sample.t, sample });
+            return sample;
         },
         miss(t) {
             push({ t, sample: null });

package/dist/reap.js

@@ -14,6 +14,12 @@
 //     that same constant: writer and deleter cannot drift apart.
 //   • only what is finished. A frame takes milliseconds; anything recent may be a write
 //     in flight, and deleting it would be the reaper causing the corruption it prevents.
+//
+// `history/` is not ours. The fleet journal a reader may opt into lives in a SIBLING directory
+// of the snapshots, and `history-store.ts` is its only writer and its only sweeper. Nothing
+// here reaches outside the directory it is handed, and that is why the journal is beside the
+// payloads rather than among them: three sweepers deciding by name over one directory is how a
+// file comes to be deleted by whoever matched it last.
 import fs from 'node:fs';
 import path from 'node:path';
 import { SID_GLOB, TEMP_PREFIX } from './wrapper.js';

package/dist/render.js

@@ -7,7 +7,9 @@
 // stays invisible for days. The two surfaces say the same things in their own words — so
 // they are written side by side, and the suite can reach both.
 import { formatDuration } from './config.js';
+import { HISTORY_MAX_BYTES } from './history-store.js';
 import { buildMap, INTERACTIVE, stateOf } from './map.js';
+import { HISTORY_CSS, HISTORY_PHONE_CSS, HISTORY_PALETTE, HISTORY_TOUCH_CSS, historyScript, renderHistoryView, } from './history-view.js';
 import { schemaNotice } from './schema.js';
 import { LIMIT_WINDOWS, RESET_HORIZON_MS, readLimits } from './limits.js';
 import { accountLimits, busyOnStaleFleet } from './fleet.js';
@@ -131,11 +133,24 @@ export const servingLine = ({ port, movedFrom }) => `tarmac serving http://127.0
  * one nobody can go and correct — and pointing at an empty snapshots directory looks exactly
  * like a fleet with no statusline chained.
  */
-export function renderSettings(config, configFile) {
+export function renderSettings(config, configFile, historyDir) {
+    const days = config.historyDays.value;
     const rows = [
         ['freshness', formatDuration(config.staleAfterMs.value), config.staleAfterMs.source],
         ['port', String(config.port.value), config.port.source],
         ['snapshots', config.snapshotsDir.value, config.snapshotsDir.source],
+        // Unlike the trusted hosts below, this line is printed either way. Off is the default and
+        // the product, and a reader who came looking for their week of history has to be able to
+        // read, in the same block as everything else, that there is none and which key starts it.
+        // On, it is the only setting here that writes to their disk, so it says all of it at once:
+        // how long it keeps, the ceiling they did not set, and the directory to go and look in.
+        [
+            'history',
+            days === null
+                ? 'off  (set history.days to keep more than 24 h)'
+                : `${days} days  (about 2 MB a day at 8 sessions, hard cap ${HISTORY_MAX_BYTES / (1024 * 1024)} MB)  ${historyDir}`,
+            config.historyDays.source,
+        ],
     ];
     // Only when there are any. An empty list is what every other run has, chosen by nobody —
     // a `(default)` line saying "none" on every serve is noise, and this line has to read as
@@ -561,7 +576,7 @@ function ago(ms) {
     const m = Math.round(s / 60);
     return m < 60 ? `${m}m` : `${Math.round(m / 60)}h`;
 }
-export function renderPage(fleet, view = 'table') {
+export function renderPage(fleet, view = 'table', { historyEnabled = false } = {}) {
     // The header's copy. `renderLive` below renders its own, out of this same fleet and through
     // this same function — two calls of one pure renderer over one reading, which is what keeps
     // the pair the reader sees and the pair the script will copy up from being two accounts.
@@ -576,6 +591,9 @@ export function renderPage(fleet, view = 'table') {
      a fault, and painting it amber puts it in the same column as "tarmac cannot read this". */
   :root { color-scheme: light dark; --fg:#111; --dim:#6b7280; --line:#e5e7eb; --bg:#fff; --warn:#b45309; --warnbg:#fffbeb; --busy:#047857; --wait:#1d4ed8; }
   @media (prefers-color-scheme: dark) { :root { --fg:#e5e7eb; --dim:#9ca3af; --line:#374151; --bg:#0b0f14; --warn:#fbbf24; --warnbg:#231a06; --busy:#34d399; --wait:#93c5fd; } }
+  /* Eight categorical hues for the history view, kept apart from the four above: those four
+     say what a session is DOING, and a chart that borrowed one would be colouring a project
+     with the word for busy. */${HISTORY_PALETTE}
   body { margin:0; padding:2rem 1.25rem; background:var(--bg); color:var(--fg);
          font:14px/1.5 ui-sans-serif,-apple-system,"Segoe UI",sans-serif; }
   header { display:flex; align-items:baseline; gap:1rem; flex-wrap:wrap; margin-bottom:1rem; }
@@ -652,13 +670,13 @@ export function renderPage(fleet, view = 'table') {
      Map, is 50), so a horizontal inset buys nothing — and at .3rem against a .15rem gap between
      the tabs it made their two overlays overlap by 7px, where a tap meant for Table landed on
      Map because Map's pseudo paints later. */
-  nav a, .replay button, .replaying-note button { position:relative; }
+  nav a, .replay button, .replaying-note button, .hist-range button, .to-now, .key { position:relative; }
   @media (pointer: coarse) {
     nav a::after, .replay button::after { content:''; position:absolute; inset:-.7rem 0; }
-    .replaying-note button::after { content:''; position:absolute; inset:-.85rem 0; }
-  }
+    .replaying-note button::after { content:''; position:absolute; inset:-.85rem 0; }${HISTORY_TOUCH_CSS}  }
   body[data-view="table"] .view-map { display:none; }
   body[data-view="map"] .view-table { display:none; }
+${HISTORY_CSS}
 
   /* ── the account's two windows ───────────────────────────────────────────────────────
      In the header, because a rate limit is the account's and not a node's. Slim on purpose:
@@ -1055,7 +1073,7 @@ export function renderPage(fleet, view = 'table') {
     td[data-label="Effort"] .v:has(.dim)::before { content:'· effort '; }
     td[data-label="Cost"] .v:has(.dim)::before { content:'· cost '; }
     .bar { display:none; }
-  }
+${HISTORY_PHONE_CSS}  }
 </style>
 </head><body data-view="${view}">
 <header>
@@ -1067,6 +1085,7 @@ export function renderPage(fleet, view = 'table') {
   <nav>
     <a href="/"${view === 'table' ? ' aria-current="page"' : ''}>Table</a>
     <a href="/map"${view === 'map' ? ' aria-current="page"' : ''}>Map</a>
+    <a href="/history"${view === 'history' ? ' aria-current="page"' : ''}>History</a>
   </nav>
   <!-- The account's two windows, page-level because that is what they are: a limit belongs to
        the account every session below is spending from, not to any one of them. Their VALUES
@@ -1118,7 +1137,8 @@ export function renderPage(fleet, view = 'table') {
   <input type="range" id="scrub" min="0" max="0" step="1" value="0" disabled aria-label="Replay position">
   <div class="covers" id="covers"></div>
 </div>
-<script>${pageScript(view)}</script>
+${view === 'history' ? renderHistoryView({ historyEnabled }) : ''}
+<script>${pageScript(view)}</script>${view === 'history' ? `\n<script>${historyScript()}</script>` : ''}
 </body></html>
 `;
 }

package/dist/server.js

@@ -6,6 +6,7 @@ import http from 'node:http';
 import { reason, renderLive, renderPage } from './render.js';
 import { hostName, SOURCE_PHRASE } from './config.js';
 import { createHistory, HISTORY_CADENCE_MS } from './history.js';
+import { HISTORY_RANGES, readRange } from './history-range.js';
 /**
  * On every answer, including the refusals and the 500s. The page swaps what this port returns
  * into `innerHTML`, and loopback proves where an answer came from, never who wrote it: a
@@ -19,8 +20,9 @@ const IDENTITY = { 'x-tarmac': '1' };
 const PAGES = new Map([
     ['/', 'table'],
     ['/map', 'map'],
+    ['/history', 'history'],
 ]);
-export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS, trustedHosts = [] }) {
+export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS, trustedHosts = [], store = null, rangeCacheMs = 60_000, report = (line) => console.error(line), }) {
     // Normalised HERE rather than trusted to arrive that way. This is the last thing between a
     // foreign origin and the fleet, so it owns both sides of its own comparison — the config
     // parser cuts a name the same way, and neither leans on the other having done it.
@@ -46,14 +48,76 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
     // than a slot would otherwise be answered with a queue of processes instead of one missed
     // minute — the tick that finds a read still running counts the slot and stands down.
     let reading = false;
+    // Said on the CHANGE, never on the tick. A read-only journal directory is a fact that holds
+    // for hours, and a line a minute about it is a log a reader learns to scroll past, which is
+    // the same as never having printed it. A failure that comes back after a run of good writes
+    // is a new fact and says so again, which is what the two flags below are for.
+    let misses = 0;
+    let failing = false;
+    let saidStopped = null;
+    const journal = (taken) => {
+        if (store === null)
+            return;
+        // Structurally best effort, not best effort by argument. The store swallows its own
+        // filesystem trouble, so nothing in here can throw today; but this is called from inside
+        // the sampler's try, where a throw would be caught as A FLEET READING THAT FAILED and
+        // counted as a missed minute in `/api/history` on top of the sample already pushed. The
+        // journal is not allowed to make the record of the fleet wrong, whatever it does to itself.
+        try {
+            store.append(taken);
+            const stats = store.stats();
+            if (stats.stopped !== saidStopped) {
+                saidStopped = stats.stopped;
+                if (stats.stopped !== null)
+                    report(`tarmac: the fleet journal has stopped, ${stats.stopped}`);
+            }
+            const missed = stats.misses > misses;
+            misses = stats.misses;
+            if (missed && !failing) {
+                report(`tarmac: could not write to the fleet journal in ${store.dir}; that reading is lost`);
+            }
+            failing = missed;
+        }
+        catch {
+            // Including a `report` a caller wrote that throws: this one is not ours to be right.
+        }
+    };
+    const ranges = new Map();
+    const rangeOf = (store, range) => {
+        const now = Date.now();
+        const held = ranges.get(range);
+        if (held !== undefined && (held.at === null || now - held.at < rangeCacheMs))
+            return held.reading;
+        const entry = { at: null, reading: undefined };
+        // Read once per range per minute rather than per request: `stats()` walks the directory, and
+        // a journal that stopped at its cap stays stopped for hours, so a minute-old answer to that
+        // question is the same answer.
+        entry.reading = readRange({ dir: store.dir, range, now, capped: store.stats().capped }).then((answer) => {
+            entry.at = Date.now();
+            return answer;
+        }, (e) => {
+            // A read that failed leaves nothing behind to be served for the rest of the minute. Only
+            // its own entry, though: a slow failure that cleared the map would drop the good answer a
+            // later request had already put there.
+            if (ranges.get(range) === entry)
+                ranges.delete(range);
+            throw e;
+        });
+        ranges.set(range, entry);
+        return entry.reading;
+    };
     const sample = async () => {
+        // First, and outside the try: the journal's lock says this process is alive, which is a
+        // fact about the tick and not about the reading. A collector that has been throwing for
+        // five minutes would otherwise leave the lock looking abandoned to the next serve.
+        store?.heartbeat();
         if (reading) {
             history.miss(Date.now());
             return;
         }
         reading = true;
         try {
-            history.record(await collect());
+            journal(history.record(await collect()));
         }
         catch {
             // A collector that throws is the normal weather here: `claude` missing, a laptop that
@@ -106,6 +170,41 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         // Served out of the ring, above the collect below and never through it: this route is
         // what the serve has ALREADY read, and one that collected would let a scrubber spawn
         // `claude agents --json` on every drag of its handle.
+        // The same route, one question further back: `range` sends it to the journal on disk for the
+        // week or the month the ring cannot hold. No range is the ring, and `24h` is the name of
+        // that, so a page may say which one it wants without asking for a different route.
+        if (url.pathname === '/api/history' && url.searchParams.has('range')) {
+            const asked = url.searchParams.get('range');
+            if (asked !== '24h') {
+                if (!isRange(asked)) {
+                    // The value is not quoted back, for the reason the refused Host is not: it is a string
+                    // the caller wrote, and the page swaps a refusal's text into `innerHTML` as its reason.
+                    res.writeHead(400, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(`tarmac serves /api/history for 24h, ${HISTORY_RANGES.join(' and ')}; no range is the last 24h\n`);
+                    return;
+                }
+                // Off is not the same answer as an empty week: a page that could not tell them apart
+                // would draw a flat line over a month the fleet was busy for.
+                let body;
+                try {
+                    body = store === null ? { enabled: false, range: asked } : { enabled: true, ...(await rangeOf(store, asked)) };
+                }
+                catch (e) {
+                    // Nothing in `readRange` is allowed to throw, and this is the seam that keeps a day
+                    // when something does from being a request that hangs instead of an answer.
+                    res.writeHead(500, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+                    res.end(`tarmac could not read the fleet journal:\n${reason(e)}\n`);
+                    return;
+                }
+                res.writeHead(200, {
+                    ...IDENTITY,
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'no-store',
+                });
+                res.end(JSON.stringify(body));
+                return;
+            }
+        }
         if (url.pathname === '/api/history') {
             res.writeHead(200, {
                 ...IDENTITY,
@@ -134,7 +233,13 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
             }
             else {
                 type = 'text/html; charset=utf-8';
-                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet, PAGES.get(url.pathname));
+                // Whether there is a journal is the config's answer and the server is the one holding
+                // it, so the view ships knowing — rather than drawing three live ranges and taking two
+                // of them back once a fetch has been out and come home refused.
+                body =
+                    url.pathname === '/live'
+                        ? renderLive(fleet)
+                        : renderPage(fleet, PAGES.get(url.pathname), { historyEnabled: store !== null });
             }
         }
         catch (e) {
@@ -161,6 +266,17 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
     server.on('listening', () => {
         if (sampler !== null)
             return;
+        // The journal's retention, applied before the first line of this run is written and once a
+        // local day after that (the store keeps that half itself). Here rather than in the CLI so
+        // that the store `serve` prunes with is, provably, the store `serve` writes with: a `serve`
+        // that built one and forgot to hand it over would otherwise sweep and journal nothing.
+        if (store !== null) {
+            const { removed, failed } = store.prune();
+            if (removed > 0)
+                report(`tarmac: removed ${removed} journal file(s) older than ${store.days} days from ${store.dir}`);
+            if (failed > 0)
+                report(`tarmac: could not remove ${failed} journal file(s) under ${store.dir}`);
+        }
         sampler = setInterval(() => void sample(), sampleEveryMs);
         sampler.unref();
     });
@@ -241,6 +357,8 @@ function attempt(server, port, host) {
         server.listen(port, host);
     });
 }
+/** One of the ranges the journal reader knows, matched whole. */
+const isRange = (asked) => HISTORY_RANGES.includes(asked);
 function isLoopbackHost(host) {
     if (!host)
         return false;

package/dist/wrapper.js

@@ -173,6 +173,11 @@ if [ -n "$sid" ] && mkdir -p "$TARMAC_DIR" 2>/dev/null; then
 fi
 
 # --- prune the snapshots of sessions that stopped rendering (amortized) ---
+# \`history/\` is not ours either: the journal a reader may opt into is a SIBLING directory of
+# this one, swept by \`history-store.ts\` alone. The find below is bounded to \`\$TARMAC_DIR\` and
+# matches the session-id shape, so it cannot reach it, and that is the point of the two
+# directories being separate.
+#
 # Nothing else would ever remove them: \`reap.ts\` collects this script's own temp litter and
 # refuses to touch a \`<sid>.json\`. A fleet that recycles its sessions nightly leaves one dead
 # file behind per session per night, forever. A LIVE session restamps its own snapshot on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",