@adrrr/tarmac 0.2.0 → 0.4.0

package/dist/schema.js

@@ -30,7 +30,7 @@
  */
 export const CHECKED_VERSIONS = {
     statusline: ['2.1.220', '2.1.226'],
-    agents: ['2.1.226'],
+    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
@@ -14,8 +15,41 @@ import { SOURCE_PHRASE } from './config.js';
  * failures carry it too: their text is what it quotes as the reason.
  */
 const IDENTITY = { 'x-tarmac': '1' };
-export function createFleetServer({ collect }) {
-    return http.createServer(async (req, res) => {
+/** The addresses that serve the shell, and which view each one opens on. */
+const PAGES = new Map([
+    ['/', 'table'],
+    ['/map', 'map'],
+]);
+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)) {
@@ -38,11 +72,35 @@ export function createFleetServer({ collect }) {
         const url = new URL(req.url, 'http://localhost');
         // `/live` is what the open page asks for every few seconds: the same render as `/`, minus
         // the shell. Serving the whole page there would hand the running script a copy of itself.
-        if (url.pathname !== '/' && url.pathname !== '/live' && url.pathname !== '/api/fleet') {
+        //
+        // `/map` is the same page opened on the other view, and deliberately not `/?view=map`:
+        // 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' &&
+            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
@@ -58,7 +116,7 @@ export function createFleetServer({ collect }) {
             }
             else {
                 type = 'text/html; charset=utf-8';
-                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet);
+                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet, PAGES.get(url.pathname));
             }
         }
         catch (e) {
@@ -72,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

@@ -6,10 +6,36 @@
 // Design rule carried over from the fleet's "3rd blindness": a status we do not recognise
 // is `null`, never `false`. A release that renames `busy` must make Tarmac say "I don't
 // know", not "everything is calm" — the second is a silent outage, the first is a signal.
+/**
+ * What each word this surface prints says about the one question the boolean asks: is this
+ * session working. A word that does not answer it is absent, and absent means `null` — "we do
+ * not know" — which is the whole point of the file.
+ *
+ * The first two arrive on a session with a process of its own; the other two are a background
+ * agent's `state`, which is where its word lives instead.
+ *
+ * Some words are left out ON PURPOSE rather than for want of a payload. `failed` and `stopped`
+ * are "not working", and that is the least interesting true thing about them; `blocked` and
+ * `waiting` are a session halted until a human answers something, where `false` reads as calm
+ * on a session that needs you and `true` as fine on one that has stopped. Unknown is the only
+ * bucket whose node prints the word itself, so those keep it: an amber node captioned `failed`
+ * says what neither boolean could.
+ */
 const KNOWN_STATUS = new Map([
     ['busy', true],
     ['idle', false],
+    ['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;
@@ -32,9 +58,16 @@ export function parseAgents(text) {
         const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null;
         if (!sessionId)
             health.noSessionId += 1;
-        const status = typeof entry.status === 'string' ? entry.status : null;
+        // A background agent carries no `status` at all — its word is under `state`. `status`
+        // still wins where both are present: it comes from the agent's own process, and `state`
+        // 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,
@@ -44,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/dist/snapshots.js

@@ -102,8 +102,25 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
             mtimeMs = fs.statSync(file).mtimeMs;
             payload = JSON.parse(fs.readFileSync(file, 'utf8'));
         }
-        catch {
-            unreadable += 1; // corrupt, half-written or unreadable: skip, but never forget
+        catch (e) {
+            // ENOENT: a name listed a moment ago that resolves to nothing now. Almost always the
+            // sweep, deleting a cold snapshot out of the very directory we are reading — its job,
+            // and a race with our own housekeeping rather than a payload we failed to parse.
+            // Counting it made tarmac drive its own format-drift warning (up to 2675 phantom
+            // unreadable on one read of a 20k directory, and `list --watch` and `serve` redraw
+            // often enough to be inside that window).
+            //
+            // The cost, said out loud: `statSync` follows symlinks, so a DANGLING one named like a
+            // snapshot is ENOENT too, and it goes silent forever — a permanent state skipped as if
+            // it were a passing race. Deliberate. There is no payload behind a dead link either,
+            // and telling the two apart (an `lstat` first) buys a warning about a file `ls` already
+            // shows. Note it is the opposite call from `reap.ts:75`, which lstats PRECISELY so a
+            // dead link is not ENOENT: it deletes, and `unlink` takes a link away just fine. Reader
+            // and reaper ask different questions of the same shape.
+            //
+            // ENOENT only. A file we were not ALLOWED to open still counts, and must.
+            if (e.code !== 'ENOENT')
+                unreadable += 1; // corrupt, half-written or unreadable: skip, but never forget
             continue;
         }
         const t = extractTelemetry(payload);

package/dist/wrapper.js

@@ -16,13 +16,16 @@
 // below is in the POSIX shell command language, and `test/portability.test.ts` runs this
 // script under every POSIX shell present on the machine to keep it that way.
 //
-// Two invariants, both tested by running the real script:
+// Three invariants, all tested by running the real script:
 //   RULE 1 — never break the display. Missing chain, failing chain, unwritable directory:
 //            the status line still renders and the exit code is still 0. Telemetry loses,
 //            display wins, always.
 //   RULE 2 — never write outside the snapshot directory. `session_id` is external input
 //            that becomes a filename, so anything that is not UUID-shaped is REFUSED, not
 //            sanitised: a guessed name would be read back later as if it were certain.
+//   RULE 3 — the sweep may remove exactly what the writer may write, no more and no less.
+//            One rule, `SID_GLOB`, read by both — because when those two sets are merely
+//            written to agree, they stop agreeing quietly, in both directions at once (#7).
 /**
  * Prefix of every temp file the wrapper writes, and the ONLY thing that proves tarmac
  * wrote one. `.<sid>.<pid>.tmp` — what this used to emit — is a convention, not a
@@ -55,21 +58,54 @@ export const PRUNE_EVERY_MIN = 60;
  */
 export const SNAPSHOT_TTL_MIN = 48 * 60;
 /**
- * The names the sweep below is allowed to remove: the 8-4-4-4-12 session id Claude Code
- * emits, which is every fixture here and every file the live fleet directory holds. NOT
- * `*.json` — that would take a `settings.json` or a `fleet.json` sitting next to them, data
- * this script never wrote, deleted from inside a status line.
+ * A session id — ONE rule, and the only one the writer below, the sweep below and the
+ * TypeScript that reads this directory are allowed to know. Written as a shell pattern
+ * because two of the three consumers are shell; the third derives its regex from it.
  *
- * The wrapper WRITES ids wider than this on purpose (it refuses to guess what an id may look
- * like), so such a file is written and never pruned. That is the only direction this trade
- * may fail in.
+ * It is the canonical UUID, 8-4-4-4-12 hex: every fixture in this repo, every file in the
+ * snapshot directory of the fleet this was built for, every transcript file observed. The
+ * statusline payload documents `session_id` only as a "unique session identifier", so that
+ * is an observation and not a promise — and the direction of the bet is deliberate. An id
+ * that is not a UUID is refused at write time, which surfaces as a live session with
+ * `absent` telemetry: a state `fleet.ts` already names and shows. The other bet — file
+ * whatever arrives, and widen the deleters to match — would put every stem of 8..64
+ * characters of `[0-9A-Za-z-]` within reach of `rm`, in a directory whose location comes
+ * from `XDG_STATE_HOME` and can therefore be `~/.claude` itself, where the legacy purge
+ * already deletes and where people keep a git repository. A missing row is recoverable.
+ *
+ * Bracket expressions, not `?`: `?` matches a leading dot (fnmatch without FNM_PERIOD), so
+ * the old glob reached dotfiles the writer's own charset forbids it to produce (#7).
+ *
+ * And an ENUMERATION, not the range `[0-9a-fA-F]`: a range is collated by the locale, which
+ * for a status line is whatever the TUI that spawned it carries. Under `en_US.UTF-8` — the
+ * ordinary case on macOS, where `/bin/sh` is bash — `a-f` reaches `é`, `ç` and fullwidth `ａ`
+ * in bash, in ksh and in BSD `find`, while the regex below is ASCII code points and always
+ * will be. That is one string meaning two different sets depending on `LANG`, which is this
+ * whole rule undone: a sid filed in a Terminal, refused under `LC_ALL=C`, and a file written
+ * by the first frame that no TypeScript consumer here can ever recognise. Sixteen digits
+ * spelled out roughly doubles the pattern — 356 characters to 772 — and costs nothing
+ * measurable per frame.
  */
-export const SNAPSHOT_GLOB = '????????-????-????-????-????????????.json';
+const HEX = '[0123456789abcdefABCDEF]';
+export const SID_GLOB = [8, 4, 4, 4, 12].map((n) => HEX.repeat(n)).join('-');
 /**
- * The same set, in Node — derived from the glob itself so the shell that deletes and the
- * TypeScript that deletes can never drift apart. `?` is any single character, `.` is literal.
+ * The names the sweep below is allowed to remove: the sid rule, and a `.json`. NOT `*.json` —
+ * that would take a `settings.json` or a `fleet.json` sitting next to them, data this script
+ * never wrote, deleted from inside a status line.
  */
-export const SNAPSHOT_NAME = new RegExp(`^${SNAPSHOT_GLOB.replace(/\./g, '\\.').replace(/\?/g, '.')}$`);
+export const SNAPSHOT_GLOB = `${SID_GLOB}.json`;
+/**
+ * The same rule, in Node — the pattern goes in RAW, because a bracket expression means the
+ * same set in both languages and `-` is literal in both. Only the extension is spelled twice,
+ * once per language, which is the one thing a translation could get wrong and so the one
+ * thing that is written out rather than derived.
+ *
+ * `SID_NAME` is the sid alone: `fleet.ts` asks it whether a LIVE session's id is one the
+ * wrapper would ever file, which is the difference between "no frame drawn yet" and "no frame
+ * will ever help" — two states that look identical on a row.
+ */
+export const SID_NAME = new RegExp(`^${SID_GLOB}$`);
+export const SNAPSHOT_NAME = new RegExp(`^${SID_GLOB}\\.json$`);
 /** Single-quotes a string for POSIX sh. */
 function shQuote(s) {
     return `'${String(s).replace(/'/g, `'\\''`)}'`;
@@ -108,16 +144,15 @@ case "$payload" in
     esac
     ;;
 esac
-# refuse anything that is not UUID-shaped — this value becomes a filename
+# Refuse anything that is not a session id — this value becomes a filename, and it is the
+# same rule the sweep below deletes by: what this line declines to write, that one cannot
+# unlink, and the reverse. An empty sid matches nothing here, so it stays empty.
 case "$sid" in
-  ''|*[!0-9a-zA-Z-]*) sid='' ;;
+  ${SID_GLOB}) ;;
+  *) sid='' ;;
 esac
 # refuse an ambiguous payload outright
 [ "$payload_has_two_ids" = 1 ] && sid=''
-if [ -n "$sid" ]; then
-  len=\${#sid}
-  if [ "$len" -lt 8 ] || [ "$len" -gt 64 ]; then sid=''; fi
-fi
 
 # --- drop the snapshot (best effort, atomic: temp file + rename in the same dir) ---
 if [ -n "$sid" ] && mkdir -p "$TARMAC_DIR" 2>/dev/null; then
@@ -149,6 +184,53 @@ fi
 # frame. (A directory where the stamp itself keeps failing does pay one \`touch\` per frame,
 # forever — a fork, not a directory walk, and it means nothing can be written there anyway.)
 #
+# And DETACHED, because amortized is an average and the average was never the problem: on an
+# install that has never pruned, the one frame that sweeps pays for the entire backlog at
+# once — a directory walk plus ten thousand unlinks on 20 000 snapshots, measured at 0.5 s in
+# the report and at 0.6-0.9 s by \`test/sweep-perf.test.ts\`, in front of the status line (#8).
+# Bounding the work per sweep instead would only spread that cost, at one bounded batch an
+# hour, over weeks of frames that each still stop to walk the
+# same directory; the frame has no business waiting for any of it. So the sweep is handed to a
+# child and the frame goes on to the chain: the frame's cost becomes one fork, whatever the
+# directory holds, and NOTHING on the nominal path — a frame with no sweep due — changes at all.
+# What that costs, all of it on the sweep's side of the fork:
+#   • the child outlives the frame. It is orphaned when the shell exits and reaped by init;
+#     nothing waits for it, so no zombie can accumulate in the TUI's process tree.
+#   • if the session dies mid-sweep, the sweep normally finishes on its own: it holds no state
+#     but the marker, already stamped, and an orphan is not interrupted by the death of its
+#     parent. It does NOT go away with a Ctrl-C either — POSIX has the shell set SIGINT and
+#     SIGQUIT to ignored in an asynchronous list where job control is off, which is here. Only
+#     a signal aimed at the process group (a SIGHUP or a SIGTERM from whatever supervises the
+#     TUI) takes it, and then what is left is what the next hour's sweep will find, which is
+#     where it was heading anyway.
+#   • the redirections are not hygiene, they are the point. A child that inherits the frame's
+#     stdout puts whatever it prints INTO the status line, and holds the pipe open after this
+#     shell has exited — the reader waits on EOF, so the frame would still block, having only
+#     moved where. \`</dev/null\` is the belt to those braces: POSIX already hands an
+#     asynchronous list \`/dev/null\` for stdin wherever job control is off — every shell that
+#     will ever run this — and stdin was drained by \`\$(cat)\` at the top anyway.
+#   • two frames that reach the marker check together both sweep, as they always could. The
+#     window is not the \`touch\` — it is the \`find\` that reads the marker's age, a whole
+#     process, which is why two frames drawn simultaneously fork two sweeps almost every time.
+#     Detaching improves that case rather than widening it: what used to be two frozen frames
+#     is now two detached walks. What matters is that a frame drawn AFTER a sweep has started
+#     sees a stamped marker and starts nothing, which is the ordinary case and the reason the
+#     stamping stayed in the frame rather than moving into the child. Across HOURS they can
+#     overlap — a sweep slower than the window is joined by the
+#     next one — and that is harmless: \`rm -f\` on a name another sweep already unlinked is
+#     not an error, and the marker is the only state either of them writes.
+#   • a \`find\` that HANGS (a stale network mount, a directory that never answers) is no longer
+#     one frozen frame; it is one orphaned process per hour that nothing here reaps. The trade
+#     is deliberate — a frozen frame breaks RULE 1, an idle process does not — but it is
+#     unbounded over time in a way the blocking shape was not.
+#   • the chain now runs BESIDE the sweep instead of after it, so anything reading this same
+#     directory can watch a file vanish under it mid-frame. Nothing here breaks on that — the
+#     display is untouched and no data is lost — but it is not free either: \`snapshots.ts\`
+#     counts a file that disappears between its \`readdir\` and its \`readFile\` as UNREADABLE,
+#     and \`list\`/\`serve\` report that as "the schema may have moved". Same window on the
+#     blocking shape (a sweep and a reader have always been able to overlap), so this is not
+#     a regression, and it is the READER's to fix: #17.
+#
 # Two known holes, both of them the safe way round, and both inherited from the fleet script
 # this transposes:
 #   • a marker dated in the FUTURE (clock skew, a restored backup, a network mount) is never
@@ -189,7 +271,7 @@ if [ -d "$TARMAC_DIR" ]; then
       # The glob is the sid SHAPE, not \`*.json\`, and that is the same rule \`reap.ts\` states
       # for the temp files: only what we wrote — see SNAPSHOT_GLOB, which the legacy purge in
       # \`install.ts\` reads from the same constant.
-      find "$TARMAC_DIR"/. ! -name . -prune -name '${SNAPSHOT_GLOB}' -type f -mmin +${SNAPSHOT_TTL_MIN} -exec rm -f {} + 2>/dev/null
+      find "$TARMAC_DIR"/. ! -name . -prune -name '${SNAPSHOT_GLOB}' -type f -mmin +${SNAPSHOT_TTL_MIN} -exec rm -f {} + >/dev/null 2>&1 </dev/null &
     fi
   fi
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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-force-exit \"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"