@adrrr/tarmac 0.3.0 → 0.4.1

package/dist/schema.js

@@ -29,8 +29,8 @@
  * directory, so the two cannot drift apart in the repo.
  */
 export const CHECKED_VERSIONS = {
-    statusline: ['2.1.220', '2.1.226'],
-    agents: ['2.1.226'],
+    statusline: ['2.1.220', '2.1.226', '2.1.232'],
+    agents: ['2.1.226', '2.1.232'],
 };
 const SURFACE_LABEL = {
     statusline: 'statusline payload',

package/dist/server.js

@@ -5,6 +5,7 @@
 import http from 'node:http';
 import { reason, renderLive, renderPage } from './render.js';
 import { SOURCE_PHRASE } from './config.js';
+import { createHistory, HISTORY_CADENCE_MS } from './history.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,36 @@ const PAGES = new Map([
     ['/', 'table'],
     ['/map', 'map'],
 ]);
-export function createFleetServer({ collect }) {
-    return http.createServer(async (req, res) => {
+export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS }) {
+    // What this serve has already read, kept for a day and never written down. `since` is the
+    // moment this server was made, not the first sample that landed: the span it covers is how
+    // long the process has been up, and an hour of it with nothing in it is a fact worth
+    // showing rather than an empty record pretending to be a young one.
+    const history = createHistory({ since: Date.now(), cadence: sampleEveryMs });
+    // One at a time. `claude agents --json` has a 15s deadline of its own, and a fleet slower
+    // 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;
+    const sample = async () => {
+        if (reading) {
+            history.miss(Date.now());
+            return;
+        }
+        reading = true;
+        try {
+            history.record(await collect());
+        }
+        catch {
+            // A collector that throws is the normal weather here: `claude` missing, a laptop that
+            // was asleep. It costs a slot and nothing else — a throw out of this timer would be an
+            // unhandled rejection, and `serve` runs unattended for hours.
+            history.miss(Date.now());
+        }
+        finally {
+            reading = false;
+        }
+    };
+    const server = http.createServer(async (req, res) => {
         // Loopback binding alone does not stop a DNS-rebinding page in the user's own browser
         // from reading /api/fleet — which carries cwd paths, session ids and costs.
         if (!isLoopbackHost(req.headers.host)) {
@@ -48,11 +77,30 @@ export function createFleetServer({ collect }) {
         // the tabs are plain links, so the view has to be somewhere a reload and a bookmark can
         // both find it. There is no second fragment — one `/live` carries both views, which is
         // what keeps them from ever showing readings of different ages.
-        if (!PAGES.has(url.pathname) && url.pathname !== '/live' && url.pathname !== '/api/fleet') {
+        if (!PAGES.has(url.pathname) &&
+            url.pathname !== '/live' &&
+            url.pathname !== '/api/fleet' &&
+            url.pathname !== '/api/history') {
             res.writeHead(404, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
             res.end('not found\n');
             return;
         }
+        // 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.
+        if (url.pathname === '/api/history') {
+            res.writeHead(200, {
+                ...IDENTITY,
+                'content-type': 'application/json; charset=utf-8',
+                'cache-control': 'no-store',
+            });
+            // Not indented, alone among the JSON answers here. `/api/fleet` pretty-prints ONE
+            // reading, which a person reads in a terminal; this is up to 1440 of them, where the
+            // indentation is 40% of a body no human will ever open — megabytes of whitespace on
+            // every poll of the replay.
+            res.end(JSON.stringify(history.read()));
+            return;
+        }
         // Read AND render inside the guard, and send nothing until there is something to send.
         // Writing the 200 first and rendering after made the collector's failure a 500 and the
         // renderer's failure a dead daemon: the headers were already on the wire, the throw
@@ -82,6 +130,29 @@ export function createFleetServer({ collect }) {
         res.writeHead(200, { ...IDENTITY, 'content-type': type, 'cache-control': 'no-store' });
         res.end(body);
     });
+    // The sampler lives exactly as long as the serving does. Started at construction it kept
+    // reading the fleet for a server whose `listen` had refused — a port named on the command
+    // line and taken — into a ring no request could ever reach; and never cleared, it did the
+    // same for every server a suite had closed behind it.
+    //
+    // `close` is the only shutdown this module has. `tarmac serve` itself has no graceful one:
+    // Ctrl-C ends the process, which takes the timer with it. Unref'ing is the belt to that
+    // braces — it keeps the sampler from being a reason `node --test`, or anything else that
+    // embeds this server, stays alive — and it is deliberately not the thing relied on.
+    let sampler = null;
+    server.on('listening', () => {
+        if (sampler !== null)
+            return;
+        sampler = setInterval(() => void sample(), sampleEveryMs);
+        sampler.unref();
+    });
+    server.on('close', () => {
+        if (sampler === null)
+            return;
+        clearInterval(sampler);
+        sampler = null;
+    });
+    return server;
 }
 /**
  * How far past a port NOBODY CHOSE `serve` may walk. A corridor, not a search: wide enough

package/dist/sessions.js

@@ -27,6 +27,15 @@ const KNOWN_STATUS = new Map([
     ['working', true],
     ['done', false],
 ]);
+/**
+ * The word for a session halted until a human answers, and the only one with a field saying
+ * which answer. It stays out of the map above — the boolean it would have to fill still has
+ * no honest value — but it is no longer counted as a word we failed to recognise: it has a
+ * state of its own on both surfaces, and a reason to print beside it.
+ */
+const WAITING = 'waiting';
+/** Whether this reading is halted on a human. The one status the renderers treat as a state. */
+export const isWaiting = (s) => s.status === WAITING;
 /** @param text raw stdout of `claude agents --json` */
 export function parseAgents(text) {
     let raw;
@@ -54,7 +63,11 @@ export function parseAgents(text) {
         // is what the dispatcher believes about an agent whose process may not be on this machine.
         const status = typeof entry.status === 'string' ? entry.status : typeof entry.state === 'string' ? entry.state : null;
         const busy = KNOWN_STATUS.has(status) ? KNOWN_STATUS.get(status) : null;
-        if (busy === null)
+        // Two different questions, and only the second one is a blind spot: `busy` is null here
+        // for a word we cannot answer the boolean with, and `waiting` is one of those — while
+        // being a word this tool knows by name. Counting it would put "reports a status tarmac
+        // does not know" on the banner over a session tarmac is drawing, captioned, as waiting.
+        if (busy === null && status !== WAITING)
             health.unknownStatus += 1;
         sessions.push({
             sessionId,
@@ -64,6 +77,7 @@ export function parseAgents(text) {
             kind: typeof entry.kind === 'string' ? entry.kind : null,
             startedAt: typeof entry.startedAt === 'number' ? entry.startedAt : null,
             status,
+            waitingFor: typeof entry.waitingFor === 'string' ? entry.waitingFor : null,
             busy,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",
@@ -36,7 +36,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "npm run typecheck && node --test \"test/*.test.ts\"",
+    "test": "npm run typecheck && node --test --test-timeout=120000 \"test/*.test.ts\"",
     "fixtures:capture": "node scripts/capture-fixtures.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build && TARMAC_REQUIRE_DASH=1 npm test && node dist/cli.js --help > /dev/null"