@adrrr/tarmac 0.9.0 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@ documented surfaces only, never an internal format.
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/replay-dark.gif">
   <img src="docs/media/replay-light.gif" width="1100"
-       alt="The tarmac map, live and then replayed. It opens on the live fleet, whose nodes are grouped into a frame per working directory, each labelled with its project. As the scrubber is dragged the frames give way to the flat record: sessions drawn as dials, each arc a context window, background agents as strips of text, with the account's five-hour and seven-day gauges above them. Sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
+       alt="The tarmac map, live and then replayed. It opens on the live fleet: nodes grouped into a frame per working directory, each frame labelled with its project, sessions drawn as dials whose arc is the context window, background agents docked under the cards as strips of text, and the account's five-hour and seven-day gauges in the header. As the scrubber under the fleet is dragged the frames give way to the flat record, every node in a cell of one size, sessions still dials and agents still strips, each with its project and what it has cost. Sessions appear as the day walks past and the grid gains a cell for each, the arcs fill, the five-hour gauge fills and rolls over to zero, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
 </picture>
 
 [Quickstart](#quickstart) · [The map](#the-map) · [The curves](#the-curves) · [Install](#install) ·
@@ -26,15 +26,15 @@ documented surfaces only, never an internal format.
 npx @adrrr/tarmac              # one-shot fleet table
 npx @adrrr/tarmac --watch      # the same table, redrawn every 5s until ^C
 npx @adrrr/tarmac serve        # the same fleet in the browser
-npx @adrrr/tarmac serve --demo # an invented fleet with a week of history, to see it full
+npx @adrrr/tarmac serve --demo # an invented fleet with a month of history, to see it full
 npx @adrrr/tarmac install      # chain the status line: unlocks ctx, model, effort and cost
 npx @adrrr/tarmac uninstall    # hand your status line back
 ```
 
 On a fresh machine the first three of those are one session and no history, which is not much
 of a dashboard. `serve --demo` is the same dashboard over eight invented sessions, a day of
-their record and a week of journal under that, so the map, the replay and every range of the
-curves have something in them. It reads no fleet and writes nothing — the week it shows is
+their record and a month of journal under that, so the map, the replay and every range of the
+curves have something in them. It reads no fleet and writes nothing — the month it shows is
 invented in memory, like the rest of it — and the page it serves is badged `demo data`
 throughout.
 
@@ -84,7 +84,7 @@ listening rules are [there too](docs/MANUAL.md#what-serve-listens-on).
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/map-dark.png">
   <img src="docs/media/map-light.png" width="1100"
-       alt="The tarmac map, live. Four framed groups, one per working directory and labelled with its project: beacon, holding a session halted on a permission prompt; harbor, holding a session busy with its context arc at 90% and a background agent docked under the cards of that frame as a strip named after its prompt; quay, reporting a status tarmac does not know; and atlas, idle at 36%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
+       alt="The tarmac map, live. Five framed groups, one per working directory and labelled with its project: auth-service, holding a session halted on a permission prompt at 61%; api-gateway, holding a session busy with its context arc at 93% and a background agent docked under the cards of that frame as a strip named after its prompt; data-pipeline, busy at 69% with an agent of its own; docs-site, holding one session reporting a status tarmac does not know and one idle at 39%; and storefront, idle at 23%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit in the header, one warning above the fleet names the unrecognised status rather than filing it as idle, and the scrubber for the replay sits under the fleet.">
 </picture>
 
 The tabs in the header swap the table for the same fleet drawn as nodes: one per session, the
@@ -103,10 +103,13 @@ session gets its own frame rather than somebody else's.
 Above the fleet are the account's five-hour and seven-day
 [gauges](docs/MANUAL.md#the-accounts-two-windows). Under it is a scrubber over the day this
 serve has seen. Drag it and the nodes render the fleet as it was at that minute. Press play
-and the day walks past. Replayed, the nodes are drawn flat and unframed. The record keeps a
-project name and never the directory it was read in, and a basename is not a directory. Two
-checkouts of `atlas` answer to the same word, so a frame drawn on it would claim a shared
-directory nobody can check.
+and the day walks past. Replayed, the nodes are drawn flat and unframed, every one of them in a
+cell of one size: a session that appears between two minutes of a scrub moves nothing but the
+nodes after it in the sample's own order, and the banner naming the minute stands in a place the
+page keeps for it. A row the grid gains still pushes what is under it, and on a phone the banner
+wraps where the live line does not. The record keeps a project name and never the directory it
+was read in, and a basename is not a directory. Two checkouts of `atlas` answer to the same
+word, so a frame drawn on it would claim a shared directory nobody can check.
 
 The map follows the rules the table follows. A reading past the freshness threshold is drawn
 thin, amber and dated. A percentage nobody measured is an empty dotted dial, never a ring at
@@ -126,7 +129,7 @@ the journal, if you keep one. `<canvas>` and the page's own script, no library.
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/curves-dark.png">
   <img src="docs/media/curves-light.png" width="1100"
-       alt="The curves page of the demo fleet, on the 7d range out of the invented journal. Context is a row of small multiples, one line per session, each a sawtooth that climbs through the day and breaks where the session was recycled, the two still climbing labelled with an arrow. Cost is one stacked bar per day in a fixed project order, the current day shorter than the six complete ones. Quota is the seven-day line climbing over the five-hour window's highs. A banner above names one unrecognised status, and the header is badged demo data.">
+       alt="The curves page of the demo fleet, on the 7d range out of the invented journal. Context is a row of small multiples, one band per project: four sawtooths that climb through the day and break where the session was recycled, and storefront, a short stroke a day near the baseline. None carries the arrow that marks a climbing line, since the panel counts nothing climbing over this range. Cost is one stacked bar per day in a fixed project order, seven days between $128 and $221. Quota is the seven-day line climbing over the five-hour window's highs. A banner above names one unrecognised status, and the header is badged demo data.">
 </picture>
 
 A context line breaks where its session did, so a recycle at three in the morning reads as a
@@ -234,11 +237,12 @@ and what would have worked. Spellings, edge cases and the two health fields
 ```bash
 npm test                       # typecheck (src + test + scripts), then run the suite
 npm run build                  # flat JavaScript into dist/
-node scripts/demo-fleet.ts     # the invented fleet the captures above are taken of
+node scripts/demo-fleet.ts     # a second invented fleet, served on a port
 ```
 
-Every capture on this page is taken of a fleet that does not exist. A screenshot of a real
-machine carries working directories, prompts and costs, and nothing real enters this repo.
+Every capture on this page is taken of `serve --demo`, a fleet that does not exist. A
+screenshot of a real machine carries working directories, prompts and costs, and nothing real
+enters this repo.
 What CI covers, which Node version develops and which one ships:
 [the manual](docs/MANUAL.md#developing). Capturing the fixtures for a new Claude Code build:
 [the manual](docs/MANUAL.md#capturing-a-new-claude-code-version).

package/dist/demo-history.js

@@ -1,4 +1,4 @@
-// The week of journal `serve --demo` shows, invented in memory.
+// The month of journal `serve --demo` shows, invented in memory.
 //
 // Why it ships. `/history` was the one page of the demo that showed the product switched off:
 // "History is off.", the 7d and 30d pills greyed out, nothing for the range charts or the
@@ -18,8 +18,11 @@
 // and it exists to be reported and never to be opened.
 //
 // One story, not two. Every record is `demoFleetAt` played through the same `record` a real
-// sampler calls and then through the store's own allowlist, so the last day of the journal and
-// the ring behind the scrubber are the same readings, minute for minute.
+// sampler calls and then through the store's own allowlist, so every minute the journal and the
+// ring share is the same reading in both — which is the last TWO calendar days, the ring being
+// twenty-four hours long and midnights being where they are. The days before those are that same
+// day again, scaled: see `demoDayFactor`, which is where a month of columns stops being a month
+// of one column.
 import { demoFleetAt, DEMO_HOME, DEMO_MINUTES } from './demo.js';
 import { createHistory } from './history.js';
 import { readRange } from './history-range.js';
@@ -27,11 +30,48 @@ import { journalRecordOf } from './history-store.js';
 /**
  * How many local days of it there are, today included.
  *
- * Seven and not thirty. A month is four times the work for a page that says what it covers
- * anyway, and a `30d` that answers the week it has is a range showing what exists — which beats
- * one invented badly, and is what a real journal younger than its retention already does.
+ * Thirty, which is what the longest range asks for. A week answered both pills with the same
+ * seven columns, so `30d` and `7d` drew the identical picture on the one serve built to show
+ * them full — a range showing what exists is honest of a real journal younger than its
+ * retention, and pointless of a past that is invented anyway. Four times the records, and the
+ * whole month is built in about a third of a second.
  */
-export const DEMO_JOURNAL_DAYS = 7;
+export const DEMO_JOURNAL_DAYS = 30;
+/** A local day, in milliseconds. Used to count days apart, never to walk from one to the next. */
+const DAY = 86_400_000;
+/**
+ * What a day of the invented past cost, as a multiple of the day the ring holds.
+ *
+ * A month of identical columns at $147 is a chart that says "made up" before the reader has read
+ * the axis. A fleet's week has a shape — weekends nobody works, an ordinary run of weekdays, and
+ * now and then a day something big shipped — and that shape is the thing the cost chart exists
+ * to show, so the invented one has it too.
+ *
+ * Deterministic and stateless: a function of which day it is and nothing else, so two reads of
+ * one demo are one answer and a screenshot can be taken twice. The multiplier off Knuth's
+ * constant is a spread, not randomness — it just has to be unmemorable and stable.
+ *
+ * Never asked about a day the ring reaches into — `demoJournalDay` answers 1 for those without
+ * coming here, and there are two of them, the ring being twenty-four hours long. The one thing
+ * this journal may not do is disagree with the record behind the scrubber about a minute they
+ * both hold. What is left for this to scale is the past nobody can compare against.
+ *
+ * The long day is a weekday, which is what keeps the shape readable: the peaks are then above
+ * every ordinary day and the weekends below every one of them, rather than a Saturday at $220
+ * saying the opposite of what the chart is showing. Seventeen apart is at most two of them in a
+ * month and never none — seventeen days is three weekdays along, so the pair cannot both land on
+ * a weekend.
+ */
+export function demoDayFactor(back, weekday) {
+    if (back <= 0)
+        return 1;
+    const spread = ((back * 2_654_435_761) % 1000) / 1000;
+    if (weekday === 0 || weekday === 6)
+        return 0.55 + 0.12 * spread;
+    if (back % 17 === 6)
+        return 1.5;
+    return 0.85 + 0.38 * spread;
+}
 /**
  * Where the journal would live if there were one. Named because a store names its directory,
  * never opened by anything here — and under the invented home, so a capture of a demo carries
@@ -50,8 +90,9 @@ const MINUTE = 60_000;
  * whatever this says. A period shorter than the day plays the fleet arriving and going home
  * more than once between two midnights, which charges a fraction of a day's work to each of
  * them and can leave an actor born late in the day out of the week entirely. The suite holds
- * the consequence rather than the number: every full day of the invented week costs the same
- * and carries all five projects, which is true of a whole day repeated and of nothing else.
+ * the consequence rather than the number: every full day of the invented past carries all five
+ * projects, and each of them costs its own day's scale of one whole day's work — which is true
+ * of a whole day repeated and of nothing else.
  *
  * What is NOT held, because it cannot be seen: whether an older cycle replays the day's last
  * minute or stops one short of it. Both tile the past exactly and both leave every day the same
@@ -136,15 +177,34 @@ export function demoJournalDay(date, dayStart) {
     // call — what is wanted is the reduction, and a second copy of that reduction here would be
     // the one thing this module exists not to be.
     const ring = createHistory({ since: dayStart, cadence: MINUTE });
+    // What this whole day cost, against the day the ring holds. Decided once for the day rather
+    // than per reading: the reader charges a day what a session's highest reading in it exceeds its
+    // lowest, and a multiplier that moved inside the day would be charged that movement as spending.
+    //
+    // A day the RING reaches into is never scaled, and that is two calendar days rather than one:
+    // `dayStart` is twenty-four hours back, so the ring straddles a midnight on every clock but
+    // midnight itself. Scaled on the older of the two, 719 of the ring's 1440 minutes went into the
+    // journal at another price — the cost chart billing yesterday 14% above what the scrubber shows
+    // for the same minutes, which is the one disagreement this module exists to prevent. `end` is
+    // this day's last moment, so a day the ring reaches into is one that ends at or after its first.
+    const factor = end >= dayStart ? 1 : demoDayFactor(Math.round((midnightOf(dayOf(last)) - midnight) / DAY), d.getDay());
     let text = '';
     for (let k = from; k <= to; k++) {
         const t = dayStart + k * MINUTE;
         const cycleStart = cycleStartFor(t, dayStart);
         const minute = Math.round((t - cycleStart) / MINUTE);
         // How many cycles before the newest day this reading belongs to — what lets the seven-day
-        // window climb across the whole invented week instead of replaying one day's ramp.
-        const cyclesBack = Math.round((dayStart - cycleStart) / CYCLE_MS);
-        text += `${JSON.stringify(journalRecordOf(ring.record(demoFleetAt(minute, cycleStart, t, undefined, cyclesBack))))}\n`;
+        // window climb across a whole invented week instead of replaying one day's ramp. Modulo the
+        // week, because that is how long the window IS: a ramp running the length of the journal put
+        // the account four times over its plan by the middle of the month and then flat on the floor
+        // for the three weeks before it, where a real one rolls over every seven days.
+        const cyclesBack = Math.round((dayStart - cycleStart) / CYCLE_MS) % 7;
+        const record = journalRecordOf(ring.record(demoFleetAt(minute, cycleStart, t, undefined, cyclesBack)));
+        if (factor !== 1)
+            for (const s of record.sessions)
+                if (s.costUsd !== null)
+                    s.costUsd = Math.round(s.costUsd * factor * 100) / 100;
+        text += `${JSON.stringify(record)}\n`;
     }
     return text;
 }

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

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