@adrrr/tarmac 0.6.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:
@@ -988,7 +1006,19 @@ export function renderPage(fleet, view = 'table') {
        word. min-width:0 for the same reason the berths carry it: a flex item's automatic
        minimum is its min-content width, which without this is the whole unbroken string. */
     td[data-label="Project"] .v { order:1; font-weight:600; min-width:0; overflow-wrap:anywhere; }
-    td[data-label="Session"] .v { order:2; flex:1 1 0; min-width:0; color:var(--dim);
+    /* The basis is auto and not 0, which is what decides whether the name breaks INSIDE
+       itself. A basis of 0 puts it on the first line however little is left of one: at 390px
+       beside a 40-character project that is 44.6px of column, a session id cut across two
+       lines, the pill dropped alone underneath and a 63px strip standing at 105.7 — on
+       exactly the fleets whose checkout names are long. Its own width is the floor it wraps
+       at instead: beside the project where it fits, on the next line whole where it does not.
+       That floor is a trade, not a free fix: a name longer than one full line keeps a line of
+       its own at EVERY width, where a basis of 0 let it compress back beside the project as
+       the screen widened. The accepted side of #108: never cut a name mid-word, at the price
+       of a taller strip for prompt-named agents.
+       min-width:0 is what still lets it shrink once it is the widest thing on a line of its
+       own, which is the wrap the rule above is written for. */
+    td[data-label="Session"] .v { order:2; flex:1 1 auto; min-width:0; color:var(--dim);
          white-space:normal; overflow-wrap:anywhere; }
     /* The third value that can arrive as one unbroken token, and the one the two rules above
        missed: a waiting reason is FREE TEXT, so "permission prompt: /Users/…/foo.ts" is a path
@@ -1043,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>
@@ -1055,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
@@ -1106,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>
 `;
 }
@@ -1321,12 +1353,20 @@ function pageScript(view) {
   }
 
   function two(n) { return (n < 10 ? '0' : '') + n; }
-  function hhmm(t) { var d = new Date(t); return two(d.getHours()) + ':' + two(d.getMinutes()); }
+  // One page, one clock, and it is the one the summary line already dates the fleet on: an ISO
+  // instant in UTC. Spelled on the machine's own clock, these minutes and that stamp are the
+  // same fleet apparently living in two time zones, the first time anything shows both — an
+  // export, a log line, a screenshot with the header in it. Every minute below carries UTC
+  // where a reader meets it, because an unlabelled one reads as the reader's own clock and is
+  // the same lie facing the other way.
+  function hhmm(t) { var d = new Date(t); return two(d.getUTCHours()) + ':' + two(d.getUTCMinutes()); }
 
   // A day-long ring can straddle one midnight, and "09:14 – 08:59" reads as a span running
-  // backwards until the older edge says which day it is.
+  // backwards until the older edge says which day it is. Which midnight is UTC's, like the
+  // minutes it separates: counted otherwise, "yesterday" turns up between two minutes of one
+  // UTC day and goes missing across the midnight it exists for.
   function edge(t, ref) {
-    return hhmm(t) + (new Date(t).getDate() === new Date(ref).getDate() ? '' : ' yesterday');
+    return hhmm(t) + (new Date(t).getUTCDate() === new Date(ref).getUTCDate() ? '' : ' yesterday');
   }
 
   // What the range covers, in the record's own terms. Never "a day": that is the size of the
@@ -1338,13 +1378,13 @@ function pageScript(view) {
       // this was the one branch that threw that away: ten hours of a collector that could not
       // run read exactly like a serve thirty seconds old.
       return record.missed
-        ? 'Nothing recorded — this serve started at ' + hhmm(record.since) + ' and '
+        ? 'Nothing recorded — this serve started at ' + hhmm(record.since) + ' UTC and '
           + record.missed + ' minute' + (record.missed === 1 ? '' : 's') + ' were due and never read.'
-        : 'Nothing recorded yet — this serve started at ' + hhmm(record.since)
+        : 'Nothing recorded yet — this serve started at ' + hhmm(record.since) + ' UTC'
           + ' and takes a reading every ' + Math.round(record.cadence / 1000) + 's.';
     }
     var last = record.samples[n - 1].t;
-    return 'Covering ' + edge(record.since, last) + ' – ' + hhmm(last)
+    return 'Covering ' + edge(record.since, last) + ' – ' + hhmm(last) + ' UTC'
       // Not "when the page loaded": the record is asked for again when a tab that has been
       // away comes back, so the sentence names the last time this page asked rather than a
       // moment it may be hours past.
@@ -1579,8 +1619,9 @@ function pageScript(view) {
     scrub.value = String(i);
     // The handle's own value is an index, so a reader who cannot see the banner would be read
     // "3" while the fleet on screen is three hours old. The minute travels with the handle.
-    scrub.setAttribute('aria-valuetext', hhmm(s.t));
-    atEl.textContent = hhmm(s.t);
+    var minute = hhmm(s.t) + ' UTC';
+    scrub.setAttribute('aria-valuetext', minute);
+    atEl.textContent = minute;
     rmeta.textContent = metaOf(s);
     rmap.innerHTML = nodesOf(s);
     // The account of that minute, in the place the live pair occupies — which the body class

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.6.0",
+  "version": "0.8.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",