@adrrr/tarmac 0.2.0 → 0.4.0

package/dist/map.js

@@ -0,0 +1,119 @@
+// P4 — the map's model.
+//
+// A view over the fleet `buildFleet` already produced. It opens no second source: every
+// field below is derived from a row that is already on the page as a table line.
+import { isWaiting } from './sessions.js';
+/**
+ * How recently a snapshot must have landed for its node to pulse. Two of the page's poll
+ * intervals (5s): a session whose terminal keeps drawing frames keeps its heartbeat across
+ * consecutive renders, and one that has stopped goes quiet within two of them.
+ *
+ * It is a display window, not a health threshold — `--stale-after` is the one that judges,
+ * and it wins wherever the two disagree.
+ */
+export const PULSE_WITHIN_MS = 10_000;
+/**
+ * Where an agent is placed, and why it is a placement rather than a link.
+ *
+ * `claude agents --json` prints interactive and background sessions in one array, and
+ * publishes nothing that ties an agent to whoever dispatched it. The working directory is
+ * the only field both carry, so it is what an agent is placed BY — it lands next to the
+ * session sharing its directory, and nothing is ever nested inside anything. Nesting would
+ * assert a parentage the source does not contain, and it would let this page show a smaller
+ * fleet than the table beside it.
+ *
+ * The agents are gathered separately because the fleet sorts busy sessions first, so one can
+ * arrive before the session it belongs beside. An agent whose directory matches no session
+ * keeps a node of its own, at the end.
+ */
+export function buildMap({ rows }, { pulseWithinMs = PULSE_WITHIN_MS } = {}) {
+    // Whether this fleet still speaks the kind we know. If NOTHING calls itself `interactive`,
+    // the word moved rather than every terminal on the machine going background at once — and
+    // the map says so by drawing them all as what they almost certainly still are. It is the
+    // tolerance `buildFleet` already applies to telemetry: a signal true of every row is a
+    // change in the source.
+    const anchored = rows.some((r) => r.kind === INTERACTIVE);
+    const roleOf = (r) => !anchored || r.kind === null || r.kind === INTERACTIVE ? 'session' : 'agent';
+    const node = (row) => {
+        const reading = readingOf(row);
+        return {
+            row,
+            role: roleOf(row),
+            state: stateOf(row),
+            reading,
+            measured: row.ctxPct !== null,
+            // Three conditions, and each one is a way the halo could otherwise lie. `live` first,
+            // and not merely "young": a reading the fleet calls stale may not be animated as
+            // though it were breathing, and with `--stale-after 2s` a three-second-old reading is
+            // both stale and inside the window below. `measured` last: a file landing is not a
+            // reading landing, and a drifted fleet still writes a snapshot every frame.
+            pulse: reading === 'live' &&
+                row.ctxPct !== null &&
+                row.snapshotAgeMs !== null &&
+                row.snapshotAgeMs <= pulseWithinMs,
+        };
+    };
+    const agents = rows.filter((r) => roleOf(r) === 'agent');
+    const placed = new Set();
+    const seen = new Set();
+    const nodes = [];
+    for (const r of rows) {
+        if (roleOf(r) !== 'session')
+            continue;
+        nodes.push(node(r));
+        // Only the first session of a directory collects them, or two sessions in one checkout
+        // would each grow a copy of the same agents.
+        if (r.cwd === null || seen.has(r.cwd))
+            continue;
+        seen.add(r.cwd);
+        for (const a of agents) {
+            // Two directories nobody could read are not the same directory.
+            if (a.cwd === null || a.cwd !== r.cwd)
+                continue;
+            nodes.push(node(a));
+            placed.add(a);
+        }
+    }
+    for (const a of agents)
+        if (!placed.has(a))
+            nodes.push(node(a));
+    return { nodes };
+}
+/**
+ * The kind a terminal calls itself, and the anchor this module reasons from. A background
+ * entry has since been seen beside them — `kind: 'background'`, no `pid`, its word under
+ * `state` rather than `status` — so the two are no longer a reading of that CLI's help. It is
+ * still the anchor and never the list: one observed alternative is not the vocabulary, and the
+ * heuristic above asks only whether anything on this machine still calls itself `interactive`.
+ *
+ * An ABSENT kind is not evidence of an agent either: the same rule the session status follows
+ * one module down, where unrecognised means unknown, never "the quiet one". The two mistakes
+ * are not the same size — an agent drawn as a session is a node in the wrong shape, while a
+ * session drawn as an agent is a terminal someone is working in, reduced to a footnote of a
+ * directory it merely shares.
+ */
+export const INTERACTIVE = 'interactive';
+/**
+ * `stale` is not recomputed here — it is the collector's verdict, reached against the
+ * threshold this run resolved (`--stale-after`, the environment, the config file). A second
+ * opinion in this module would let the map and the table disagree about the same session on
+ * the same page.
+ */
+function readingOf(r) {
+    if (r.snapshotAgeMs === null)
+        return 'none';
+    // A snapshot dated after the clock reading it: an NTP correction, a mount whose time runs
+    // ahead. Its age is not a small number, it is not a number at all.
+    if (r.snapshotAgeMs < 0)
+        return 'undated';
+    return r.stale ? 'stale' : 'live';
+}
+/**
+ * The four words a node can be, out of a boolean that only has three answers.
+ *
+ * `waiting` is asked BEFORE the boolean's `null`, and that order is the point: a session
+ * halted until a human answers carries `busy: null` — "is it working" has no honest answer —
+ * which is the same null an unrecognised word gets. Left to the boolean alone, the one
+ * session that is blocked on YOU drew as the amber "tarmac does not know this word".
+ */
+export const stateOf = (r) => r.busy === true ? 'busy' : isWaiting(r) ? 'waiting' : r.busy === false ? 'idle' : 'unknown';

package/dist/reap.js

@@ -16,12 +16,17 @@
 //     in flight, and deleting it would be the reaper causing the corruption it prevents.
 import fs from 'node:fs';
 import path from 'node:path';
-import { TEMP_PREFIX } from './wrapper.js';
+import { SID_GLOB, TEMP_PREFIX } from './wrapper.js';
 /** Exported so a test can build the same expectation from the same constant, escaped. */
 export const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// `<TEMP_PREFIX><sid>.<pid>.tmp` — the sid charset and length are the ones the wrapper
-// enforces before it agrees to use the value as a filename, and the pid is what `$$` emits.
-const TEMP_NAME = new RegExp(`^${escapeRe(TEMP_PREFIX)}[0-9A-Za-z-]{8,64}\\.\\d+\\.tmp$`);
+// `<TEMP_PREFIX><sid>.<pid>.tmp` — the pid is what `$$` emits, and the sid is the wrapper's
+// own rule, read from the constant rather than transcribed: a set of its own is how this
+// matcher came to accept names the writer had stopped producing (#7).
+//
+// `SID_GLOB` goes in RAW, unlike the prefix: it is a shell pattern made of bracket
+// expressions and literal `-`, which is already valid regex meaning the same set. Escaping
+// it would turn the classes into literal brackets and match nothing at all.
+const TEMP_NAME = new RegExp(`^${escapeRe(TEMP_PREFIX)}${SID_GLOB}\\.\\d+\\.tmp$`);
 /** An hour is orders of magnitude beyond any real frame, and cheap to be wrong about. */
 const DEFAULT_OLDER_THAN_MS = 60 * 60_000;
 /**