@adrrr/tarmac 0.2.0 → 0.3.0

package/README.md

@@ -1,15 +1,17 @@
 # tarmac
 
 [![npm](https://img.shields.io/npm/v/%40adrrr%2Ftarmac)](https://www.npmjs.com/package/@adrrr/tarmac)
+[![CI](https://github.com/adrrr/tarmac/actions/workflows/ci.yml/badge.svg)](https://github.com/adrrr/tarmac/actions/workflows/ci.yml)
 ![node](https://img.shields.io/node/v/%40adrrr%2Ftarmac)
 ![runtime dependencies](https://img.shields.io/badge/runtime_dependencies-0-brightgreen)
 ![license](https://img.shields.io/badge/license-MIT-blue)
 
 **Fleet observability for Claude Code.** One table for every session you have running —
-busy or idle, how full its context is, which model, what it has cost so far.
+busy or idle, how full its context is, which model, what it has cost so far. It reads
+documented surfaces only, never an internal format.
 
 ```
-$ npx @adrrr/tarmac list
+$ npx @adrrr/tarmac
 
 PROJECT            STATE  CTX      AS OF  MODEL    EFFORT  COST    UP
 apollo             busy   28%      7m     Fable 5  max     $41.20  8h
@@ -17,51 +19,93 @@ mercury-dashboard  busy   27%      22m !  Fable 5  max     $62.75  8h
 gemini             idle   12%      3h !   Opus 5   high    $5.40   8h
 atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 
-! 3 reading(s) marked "!" are older than the freshness threshold
+! 3 reading(s) marked "!" are older than 10m (--stale-after)
 
 4 sessions · 2 busy · $109.35
 ```
 
+That is the table with the status line chained. Without it — nothing installed at all — the
+same command still lists every session, its state and its uptime, straight from
+`claude agents --json`; the context column reads `— absent`, model, effort and cost fall to
+`—`, and the line under the table counts how many sessions are covered.
+
+Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing to audit.
+
+[Manual](docs/MANUAL.md) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/adrrr/tarmac/issues)
+
 ## Install
 
 ```bash
-npx @adrrr/tarmac install      # chain the status line under ~/.claude, after showing you what changes
-npx @adrrr/tarmac list         # one-shot table
-npx @adrrr/tarmac list --watch # the same table, redrawn every 5s until ^C
-npx @adrrr/tarmac serve        # dashboard on http://127.0.0.1:4477
-npx @adrrr/tarmac uninstall    # put your status line back, exactly
+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 install      # chain the status line: unlocks ctx, model, effort and cost
+npx @adrrr/tarmac uninstall    # hand your status line back
 ```
 
-Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing to audit.
+`install` changes the `statusLine` key of `~/.claude/settings.json`, and never on your
+say-so alone. It prints the whole plan first — including the exact command that undoes it —
+and waits for a **typed word** (`y` is not an answer; scripts pass `--yes`, deliberately):
+
+```
+tarmac install — your home
+
+  file             /Users/jane/.claude/settings.json
+  statusLine now   ~/bin/my-line.sh
+  statusLine next  /Users/jane/.claude/tarmac/statusline.sh
+  ↳ which calls    ~/bin/my-line.sh   (your display is unchanged)
+  snapshots        /Users/jane/.local/state/tarmac/snapshots
+  undo             tarmac uninstall
 
-`install` changes one line of `~/.claude/settings.json`, and never on your say-so alone:
-it prints the full plan — including the exact command that undoes it — and waits for a
-**typed word** (`y` is not an answer; scripts pass `--yes`, deliberately). Your status
-line is wrapped, not replaced: the display stays byte-identical, and `uninstall` restores
-the original exactly.
+Type "install" to proceed, anything else to abort:
+```
+
+A status line you already had is **wrapped, not replaced**: its display stays byte-identical,
+and `uninstall` names which of its four restore modes ran — `bytes`, the usual one, puts the
+original file back exactly. Note that the write re-serialises `settings.json`, so a
+version-controlled one shows a formatting diff, not a one-line diff.
 
-The only things it puts under `~/.claude/` are the wrapper and the `backup.json` that undoes
-it, neither of which changes at runtime — the snapshots the wrapper writes at every frame go
-to `$XDG_STATE_HOME/tarmac/snapshots` (`~/.local/state/tarmac/snapshots` by default), because
-`~/.claude` is a directory people commit.
+The only things that land under `~/.claude/` are that wrapper and the `backup.json` that
+undoes it, neither of which changes at runtime: the snapshots the wrapper writes at every
+frame go to `$XDG_STATE_HOME/tarmac/snapshots` (`~/.local/state/tarmac/snapshots` by
+default), because `~/.claude` is a directory people commit. Coming from 0.1.x, `install`
+clears the payloads an older version left in there, says how many and from where, and — when
+`~/.claude` is a git repository — prints the `.gitignore` line worth adding.
 
 ## The dashboard
 
 `tarmac serve` puts the same fleet in the browser — every session a row, ages that keep
-climbing, and a banner the moment a refresh fails instead of a table quietly going stale:
+climbing, and a banner the moment a refresh fails instead of a table quietly going stale. It
+prints the settings it resolved, then the URL it got:
 
 ```
 tarmac serving http://127.0.0.1:4477
 ```
 
-It binds to loopback and refuses any request whose `Host` is not loopback — your cwd
-paths and costs never leave the machine.
+It binds to loopback and refuses any request whose `Host` is not loopback, or that a browser
+does not mark same-origin — your cwd paths and costs never leave the machine. A busy
+**default** port walks up to the next free one and says so; a port you chose yourself — flag,
+environment or config file — refuses instead, because you chose it.
+
+### The map
+
+The tab in the header swaps the table for the same fleet as nodes — one per session, the arc
+its context, the shape by the name its state, and a single halo when a reading for it landed
+moments ago. It is the same reading in the same fragment, so the two views can never disagree.
+
+The rules the table follows, the map follows: a reading past the freshness threshold is drawn
+thin, amber and dated `! 3h ago` rather than as a live one, and a percentage nobody measured
+is an empty dotted dial that names which kind of nothing it is — never a ring at zero, and
+never a halo, however new the file it came in. A background agent is placed beside the session
+sharing its working directory, because the working directory is the only thing the two provably
+share; nothing is nested, and no edge is drawn for a relationship the sources do not publish.
+Details in [the manual](docs/MANUAL.md#the-map).
 
 ## Why it does not break
 
-Every other way to watch a Claude Code fleet reads something Claude Code never promised
-would stay put: transcript files, terminal panes, undocumented paths. Those tools break on
-an update, and — worse — they break *quietly*, reporting a calm empty fleet.
+The usual ways to watch a Claude Code fleet read something Claude Code never promised would
+stay put: transcript files, terminal panes, undocumented paths. Those break on an update,
+and — worse — they break *quietly*, reporting a calm empty fleet.
 
 tarmac reads two things instead:
 
@@ -71,47 +115,60 @@ tarmac reads two things instead:
 | the status line payload | context %, model, effort, cost | the JSON Claude Code hands to your own `statusLine.command` on every frame — **observed, not published as a schema** |
 
 That second line is the honest caveat, and it is the reason the real defence is not
-immunity, it is **visible degradation**: a null renders as `— no turn yet`, a moved field
-as `— schema drift`, a stale reading as the value **dated** — never a confident `0`. And
-when a session shows up on a Claude Code build no fixture covers, tarmac names that
-version *before* anything breaks, and keeps reporting. The full state-by-state table is
-in `docs/MANUAL.md`.
+immunity, it is **visible degradation**. A missing measurement is never a confident `0`: it
+is an em dash that names which kind of missing it is — `absent` for a session no status line
+ever wrote for, `fresh` for one that has taken no turn yet, `drift` for a release that moved
+the payload out from under us — and the fleet-wide count sits under the table, as
+`! statusline chained on 0/4 sessions`. A stale reading keeps its value and gets **dated**
+with a `!`. And when a session shows up on a Claude Code build no fixture covers, tarmac
+names that version *before* anything breaks, and keeps reporting. The full state-by-state
+table is in [`docs/MANUAL.md`](docs/MANUAL.md).
 
 ## Commands
 
 | Command | What it does | Options |
 |---|---|---|
-| `tarmac list` | one-shot fleet table | `--home`, `--stale-after`, `--snapshots-dir`, `--claude-bin`, `--json`, `--watch` |
-| `tarmac serve` | local dashboard, `GET /` for the page, `GET /live` for the fragment it refreshes, `GET /api/fleet` for JSON | `--home`, `--port`, `--stale-after`, `--snapshots-dir`, `--claude-bin` |
+| `tarmac list` | one-shot fleet table — the default, so bare `tarmac` runs it | `--home`, `--stale-after`, `--snapshots-dir`, `--claude-bin`, `--json`, `--watch` |
+| `tarmac serve` | local dashboard, `GET /` for the table, `GET /map` for the map, `GET /live` for the fragment both refresh from, `GET /api/fleet` for JSON | `--home`, `--port`, `--stale-after`, `--snapshots-dir`, `--claude-bin` |
 | `tarmac install` | chain the status line under `<home>/.claude/settings.json`, after confirmation | `--home`, `--yes` |
 | `tarmac uninstall` | restore it, and say which of the four restore modes ran | `--home`, `--yes` |
 
 `--help` works everywhere. An option handed to a command that does not read it is an
-**error**, not something quietly ignored.
-
-Both live views tell you **when the last good reading arrived** and **whether the last
-refresh failed** — ages keep climbing whether or not the refresh works, failures are
-banners with names, and a table is never thrown away for one. How each failure mode is
-kept from looking like health: `docs/MANUAL.md`.
+**error**, not something quietly ignored — and the error names the commands it does belong
+to. Both live views tell you **when the last good reading arrived** and **whether the last
+refresh failed**: ages keep climbing whether or not the refresh works, failures are banners
+with names, and a table is never thrown away for one.
 
 ## Configuration
 
 Three numbers are opinions, not truths, so all three are yours; everything else is
 deliberately not configurable, and all of it works with no configuration at all.
 
-| Setting | Flag | Environment | `~/.claude/tarmac/config.json` | Default |
+| Setting | Flag | Environment | `<home>/.claude/tarmac/config.json` | Default |
 |---|---|---|---|---|
 | freshness threshold | `--stale-after 90s` \| `15m` \| `2h` | `TARMAC_STALE_AFTER` | `"staleAfterMs": 90000` | `10m` |
 | port | `--port 8080` | `TARMAC_PORT` | `"port": 8080` | `4477` |
-| snapshots dir (read side) | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` | `$XDG_STATE_HOME/tarmac/snapshots`, else `<home>/.local/state/tarmac/snapshots` |
+| snapshots dir (read side) | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` | the path frozen into the installed wrapper — failing that `$XDG_STATE_HOME/tarmac/snapshots`, when it is absolute *and* the target home is your own, else `<home>/.local/state/tarmac/snapshots` |
+
+**Flag beats environment beats config file beats default**, settled per setting; `serve`
+opens by printing each effective value and where it came from. Nothing is silently dropped
+or silently corrected — a value that will not parse stops the run and says what it got,
+where it came from, and what would have worked, *including* values that were going to lose
+the precedence fight anyway.
+
+That last default is read out of the installed wrapper, never recomputed: a reader that
+recomputed it would disagree with the writer the moment the two saw different environments
+— `XDG_STATE_HOME` exported in your shell, absent from a LaunchAgent or cron — and the
+symptom is a healthy, empty fleet, the one failure a fleet monitor may not have. Anything
+else reading those payloads can ask where they are: `tarmac list --json` reports the path as
+`health.snapshotsDir`. Full rules and edge cases: [`docs/MANUAL.md`](docs/MANUAL.md).
 
-**Flag beats environment beats config file beats default**, settled per setting. `serve`
-opens by printing each effective value and which source it came from. Nothing is ever
-silently dropped or silently corrected: a value that will not parse stops the run and says
-what it got, where it came from, and what would have worked — including values that were
-going to lose the precedence fight anyway. Full rules and edge cases: `docs/MANUAL.md`.
+`tarmac list --json` also reports `health.unfilable`: how many live sessions carry an id
+tarmac will never file a snapshot under, so a reader can tell telemetry that is *late* from
+telemetry that is *not coming*. See [`docs/MANUAL.md`](docs/MANUAL.md) for what makes an id
+filable.
 
-## What V1 does not do
+## What it deliberately does not do
 
 - **No "waiting for you" signal.** The obvious missing column — which session is blocked on
   a human — is deliberately absent: the status line payload carries nothing that means it,
@@ -131,8 +188,8 @@ npm run build      # flat JavaScript into dist/
 CI runs the suite on Node 22 and 24, on Linux and macOS, with `TARMAC_REQUIRE_DASH=1` so a
 machine without dash cannot report a green build it did not earn; a separate job builds
 `dist/` and runs it on Node 20 — the oldest version `engines` promises, and the only place
-the published artefact is ever executed. Releases are cut by hand (`PUBLISHING.md`);
-capturing fixtures for a new Claude Code build: `docs/MANUAL.md`.
+the published artefact is ever executed. Releases are cut by hand ([`PUBLISHING.md`](PUBLISHING.md));
+capturing fixtures for a new Claude Code build: [`docs/MANUAL.md`](docs/MANUAL.md).
 
 The suite runs the TypeScript sources directly through Node's type stripping, so it needs
 Node ≥ 22.18 to *develop*; what ships in `dist/` is plain ES2022 and runs on Node ≥ 20.

package/dist/fleet.js

@@ -13,6 +13,7 @@
 import path from 'node:path';
 import { DEFAULT_STALE_AFTER_MS } from './config.js';
 import { guardVersions } from './schema.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) => {
         const t = (s.sessionId && snapshots.get(s.sessionId)) || null;
@@ -22,6 +23,7 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
             project: s.cwd ? path.basename(s.cwd) : null,
             cwd: s.cwd,
             pid: s.pid,
+            kind: s.kind,
             status: s.status,
             busy: s.busy,
             uptimeMs: typeof s.startedAt === 'number' ? now - s.startedAt : null,
@@ -39,6 +41,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;
+    // 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
+    // name is still READ, because the reader keys on the `session_id` inside the file rather
+    // 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;
     // Having a snapshot and having a cost are different facts, and only the second one is
     // allowed to feed the total.
@@ -55,6 +65,7 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
         health: {
             sessions: rows.length,
             covered,
+            unfilable,
             drift,
             stale: rows.filter((r) => r.stale).length,
             // Discovery's own blind spots. Dropping them turns a renamed `sessionId` into the

package/dist/install.js

@@ -238,22 +238,38 @@ function readLegacyDir(p) {
 /**
  * The three names the wrapper writes into its snapshot directory, and nothing else.
  *
- * `SNAPSHOT_NAME` is the PRUNER's shape (8-4-4-4-12), deliberately narrower than the ids the
- * writer accepts (`[0-9a-zA-Z-]{8,64}` — it refuses to guess what an id may look like). One
- * choice, made once, and it is what produces the residue this branch states: a session id
- * wider than a UUID is written here and swept by neither the pruner nor this. Widening it
- * would mean deleting, from inside a git repository, by a shape rather than by a signature.
+ * `SNAPSHOT_NAME` is the writer's own rule now, not a second reading of it (#7): this purge
+ * deletes from inside `~/.claude`, a directory people version-control, and a `<sid>.json` is
+ * recognised by SHAPE alone — so the shape had better be one the wrapper can actually
+ * produce, or this deletes by resemblance in the worst place to be wrong about it.
+ *
+ * `TEMP_PREFIX` is deliberately the whole test for a temp file, and deliberately looser than
+ * `reap.ts`'s `<prefix><sid>.<pid>.tmp`. The two answer different questions. `reap` runs on
+ * every `serve` tick, in a directory a reader may have been pointed at and another program
+ * may own, so it takes only the exact name this wrapper emits. This runs once, at install,
+ * behind `tarmacWasInstalledHere` — provenance already proven — over a directory whose whole
+ * purpose was to be ours, and its job is to leave nothing behind so the directory itself can
+ * go. There, a name only tarmac ever writes is signature enough.
  */
 const isPayloadName = (name) => SNAPSHOT_NAME.test(name) || name.startsWith(TEMP_PREFIX) || name === PRUNE_MARKER;
-/** `lstat`: the LINK's own kind decides, since `unlink` would remove the link, not its target. */
-const isPlainFile = (file) => {
+/**
+ * What is at that path, with the two "no"s kept apart so a plan can say which one it is:
+ * nothing there at all, or something there that is not ours to take.
+ *
+ * `lstat`: the LINK's own kind decides, since `unlink` would remove the link, not its target.
+ * A judgement by `existsSync` would follow a dead symlink to "nothing there" while the removal
+ * left the link exactly where it was.
+ */
+const markerState = (file) => {
     try {
-        return fs.lstatSync(file).isFile();
+        return fs.lstatSync(file).isFile() ? 'file' : 'not-a-file';
     }
     catch {
-        return false;
+        return 'none';
     }
 };
+/** The same question, for callers that only need the yes. */
+const isPlainFile = (file) => markerState(file) === 'file';
 /**
  * Did an install of OURS already exist here, before this run wrote anything?
  *
@@ -721,6 +737,7 @@ export function planUninstall({ home, realHome = os.homedir() }) {
         after = restored ? commandOf(settings.statusLine) : commandOf(current.statusLine);
     }
     const isRealHome = sameFile(root, realHome);
+    const snapshots = installedSnapshotsDir(p);
     return {
         action: 'uninstall',
         home: root,
@@ -732,8 +749,10 @@ export function planUninstall({ home, realHome = os.homedir() }) {
         after,
         mode,
         // Where they REALLY are: `uninstall` leaves them behind, so the path it prints has to be
-        // the wrapper's own, not one recomputed from this shell's environment.
-        snapshots: installedSnapshotsDir(p) ?? p.snapshots,
+        // the wrapper's own, not one recomputed from this shell's environment — and when the
+        // wrapper cannot answer, neither can the plan. The same `null` `uninstall` acts on.
+        snapshots,
+        marker: snapshots === null ? null : markerState(path.join(snapshots, PRUNE_MARKER)),
         undo: undoCommand('install', root, isRealHome),
     };
 }
@@ -743,10 +762,20 @@ function installedBackupOrRefuse(p) {
         throw new Error(`no tarmac install found under ${p.dir}`);
     return backup;
 }
+function removePruneMarker(snapshots) {
+    if (snapshots === null)
+        return;
+    const marker = path.join(snapshots, PRUNE_MARKER);
+    if (isPlainFile(marker))
+        fs.rmSync(marker, { force: true });
+}
 export function uninstall({ home }) {
     const root = requireHome(home);
     const p = paths(root);
     const backup = installedBackupOrRefuse(p);
+    // Read this before removing the wrapper: it is the source of truth when the install used
+    // XDG_STATE_HOME, and the marker is the only file in that directory uninstall owns.
+    const snapshots = installedSnapshotsDir(p);
     const currentText = fs.existsSync(p.settings) ? fs.readFileSync(p.settings, 'utf8') : null;
     let mode;
     if (currentText === backup.installedText) {
@@ -774,7 +803,10 @@ export function uninstall({ home }) {
         writeAtomic(p.settings, JSON.stringify(settings, null, 2) + '\n');
         mode = 'surgical';
     }
-    // Snapshots are data the user may still want; only what we generated goes.
+    // Restore settings before touching runtime state: even an unreadable snapshots directory
+    // must not strand statusLine on the wrapper we are uninstalling.
+    removePruneMarker(snapshots);
+    // Snapshot payloads are data the user may still want; only what we generated goes.
     fs.rmSync(p.wrapper, { force: true });
     fs.rmSync(p.backup, { force: true });
     return { mode };

package/dist/map.js

@@ -0,0 +1,110 @@
+// 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.
+/**
+ * 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';
+}
+export const stateOf = (r) => (r.busy === true ? 'busy' : 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;
 /**

package/dist/render.js

@@ -7,6 +7,7 @@
 // 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 { buildMap, INTERACTIVE, stateOf } from './map.js';
 import { schemaNotice } from './schema.js';
 /**
  * The other thing this module renders: the plan a user consents to before install or
@@ -52,9 +53,16 @@ export function renderPlan(plan) {
     }
     else {
         rows.push(['restore', `${plan.mode} — ${restoreMeaning(plan.mode)}`]);
-        // "Your snapshots survive uninstall" is a promise about a directory nobody can guess any
-        // more, so the command that leaves them behind says where it leaves them.
-        rows.push(['snapshots', `${plan.snapshots}   (left exactly as they are)`]);
+        // Nothing here says where the payloads are — no wrapper, or one that no longer carries
+        // the path, or one we cannot read. There is no directory to name, and `uninstall` opens
+        // none and removes nothing in one. Printing the default we would have computed, beside a
+        // promise to clear a marker out of it, is a plan disagreeing with what runs.
+        if (plan.snapshots === null) {
+            rows.push(['snapshots', 'unknown — nothing here says where; nothing there is opened or removed']);
+        }
+        else {
+            rows.push(['snapshots', `${plan.snapshots}   (snapshot files stay; ${markerFate(plan.mode, plan.marker)})`]);
+        }
     }
     rows.push(['undo', plan.undo]);
     const w = Math.max(...rows.map(([label]) => label.length));
@@ -75,6 +83,26 @@ const gitHint = (repo, hasLegacy) => `${repo.dir} is a git repository — ` +
     (hasLegacy
         ? `commit the removal above, and add \`${repo.ignore}\` to its .gitignore`
         : 'nothing tarmac writes there changes at runtime; the snapshots live outside it');
+/**
+ * What becomes of the prune marker, said only after looking at it.
+ *
+ * Three of these four answers are "it stays", each for its own reason: a foreign statusLine
+ * keeps the wrapper, so the marker keeps its owner; nothing is there to take; or what is there
+ * is not a plain file, which `removePruneMarker` refuses by design because `unlink` would take
+ * a link and not its target.
+ *
+ * Written so that ONLY `'file'` can reach the removal sentence, rather than letting it be the
+ * fallthrough: `marker` is nullable by type, and a null landing on "is removed" would be the
+ * exact promise this whole change exists to stop making. The safe answer is the default; the
+ * dangerous one is the special case.
+ */
+const markerFate = (mode, marker) => marker !== 'file'
+    ? marker === 'not-a-file'
+        ? "the prune marker's name is worn by something that is not a regular file, so it stays"
+        : 'no prune marker to remove'
+    : mode === 'foreign'
+        ? "tarmac's prune marker stays"
+        : "tarmac's prune marker is removed";
 /** What each restore mode means, in the words the plan and the report both use. */
 export const restoreMeaning = (mode) => RESTORE_MEANING[mode];
 const RESTORE_MEANING = {
@@ -148,7 +176,13 @@ export function renderTable({ rows, health }) {
     else if (health.schemaBroken)
         warns.push('! every snapshot drifted — the statusline payload schema moved');
     else if (health.covered < health.sessions)
-        warns.push(`! statusline chained on ${health.covered}/${health.sessions} sessions`);
+        warns.push(
+        // The count travels, for the same reason `unreadable` does one line up: without it
+        // this line reads as "run install", and for a session id the wrapper declines to file
+        // that is advice already taken which can never work.
+        health.unfilable > 0
+            ? `! statusline chained on ${health.covered}/${health.sessions} sessions — ${health.unfilable} session(s) with an id tarmac never files`
+            : `! statusline chained on ${health.covered}/${health.sessions} sessions`);
     if (health.stale > 0)
         warns.push(`! ${health.stale} reading(s) marked "!" are older than ${formatDuration(health.staleAfterMs)} (--stale-after)`);
     const skewed = rows.filter(ahead).length;
@@ -194,7 +228,8 @@ function age(ms) {
  * could not see) are hard-won and tested; re-deriving them in browser JavaScript to redraw a
  * polled row would put the second copy somewhere this suite cannot reach.
  */
-export function renderLive({ rows, health }) {
+export function renderLive(fleet) {
+    const { rows, health } = fleet;
     const warnings = [];
     if (health.noSessionId > 0) {
         // Never "no sessions found" when discovery DID find some it could not identify.
@@ -216,7 +251,12 @@ export function renderLive({ rows, health }) {
         warnings.push(`Every snapshot drifted — Claude Code's statusline schema has probably moved. Context readings are dead until the payload shape is re-checked.`);
     }
     else if (health.covered < health.sessions) {
-        warnings.push(`Statusline chained on ${health.covered}/${health.sessions} sessions — the rest report no context. Run \`tarmac install\` and give them one TUI frame.`);
+        const blind = health.sessions - health.covered;
+        warnings.push(health.unfilable === 0
+            ? `Statusline chained on ${health.covered}/${health.sessions} sessions — the rest report no context. Run \`tarmac install\` and give them one TUI frame.`
+            : health.unfilable >= blind
+                ? `Statusline chained on ${health.covered}/${health.sessions} sessions — the rest carry a session id that is not the UUID tarmac files snapshots under, so no frame will ever produce one. Installing again will not change that.`
+                : `Statusline chained on ${health.covered}/${health.sessions} sessions — ${blind} report no context, and ${health.unfilable} of them will never be filed: the session id is not the UUID tarmac files snapshots under. For the others, run \`tarmac install\` and give them one TUI frame.`);
     }
     if (health.unknownStatus > 0) {
         warnings.push(`${health.unknownStatus} session(s) report a status tarmac does not know — treated as unknown, not idle.`);
@@ -231,22 +271,34 @@ export function renderLive({ rows, health }) {
     const schema = schemaNotice(health.schemaGuard);
     if (schema)
         warnings.push(schema);
+    // Both views, every time, out of the one reading the page just asked for. The tabs are
+    // links and the shell decides which of the two is visible, so a fleet cannot be drawn as a
+    // table of one age beside a map of another.
+    //
+    // A fleet with nothing in it has no two ways to be laid out, so it gets one sentence above
+    // both of them rather than a copy inside each — the copy behind `display:none` was invisible
+    // on screen and read out all the same by anything going through the markup.
     const body = rows.length === 0
-        ? health.noSessionId > 0
-            ? // Discovery DID return entries — we just could not identify them. Saying "none
-                // found" here would hide a schema change behind a calm, wrong answer.
-                `<p class="empty">No session could be identified, though ${health.noSessionId} were discovered.</p>`
-            : `<p class="empty">No Claude Code sessions found. Is a session running?</p>`
-        : `<table>
+        ? empty(health)
+        : `<div class="view view-table"><div class="wrap"><table>
       <thead><tr>
         <th>Project</th><th>Session</th><th>State</th><th>Context</th><th>Model</th><th>Effort</th><th>Cost</th><th>Uptime</th>
       </tr></thead>
       <tbody>${rows.map(renderRow).join('')}</tbody>
-    </table>`;
+    </table></div></div>
+<div class="view view-map">${renderMap(fleet)}</div>`;
     return `<div class="meta">${health.sessions} session${health.sessions === 1 ? '' : 's'} · ${health.busy} busy · ${cost(health)} · ${esc(new Date(health.generatedAt).toISOString())}</div>
 ${warnings.map((w) => `<div class="warn">${esc(w)}</div>`).join('')}
-<div class="wrap">${body}</div>`;
+${body}`;
 }
+/**
+ * What to say instead of a fleet. Discovery returning entries we could not identify is not
+ * an empty fleet, and saying "none found" would hide a schema change behind a calm, wrong
+ * answer — so the two surfaces below share one wording rather than each keeping its own.
+ */
+const empty = (health) => health.noSessionId > 0
+    ? `<p class="empty">No session could be identified, though ${health.noSessionId} were discovered.</p>`
+    : `<p class="empty">No Claude Code sessions found. Is a session running?</p>`;
 /**
  * One frame of `tarmac list --watch`. It owes the reader exactly what the page owes: the
  * table, when the reading in it arrived, and whether the last attempt to refresh it failed.
@@ -293,7 +345,7 @@ function ago(ms) {
     const m = Math.round(s / 60);
     return m < 60 ? `${m}m` : `${Math.round(m / 60)}h`;
 }
-export function renderPage(fleet) {
+export function renderPage(fleet, view = 'table') {
     return `<!doctype html>
 <html lang="en"><head>
 <meta charset="utf-8">
@@ -344,6 +396,81 @@ export function renderPage(fleet) {
   body.failing .pulse { background:var(--warn); }
   body.failing #live { border:1px dashed var(--warn); border-radius:8px; padding:.5rem; }
   .offline strong { white-space:nowrap; }
+  /* The tabs, and what they hide. The shell owns the choice — not the fragment — so a poll
+     that swaps the fleet underneath cannot put the reader back on a view they left. */
+  nav { display:flex; gap:.15rem; }
+  nav a { color:var(--dim); text-decoration:none; font-size:.8rem; font-weight:600; text-transform:uppercase;
+          letter-spacing:.06em; padding:.15rem .55rem; border-radius:99px; border:1px solid transparent; }
+  nav a[aria-current="page"] { color:var(--fg); border-color:var(--line); }
+  body[data-view="table"] .view-map { display:none; }
+  body[data-view="map"] .view-table { display:none; }
+
+  /* ── the map ─────────────────────────────────────────────────────────────────────────
+     One node per session. The arc is the context, its weight is how much that reading may
+     be believed, and the halo — the only thing on this page that moves — says a frame
+     landed moments ago. */
+  .map { display:grid; gap:.9rem; grid-template-columns:repeat(auto-fill,minmax(10.5rem,1fr)); }
+  .node { border:1px solid var(--line); border-radius:10px; padding:.8rem .85rem .7rem;
+          display:flex; flex-direction:column; align-items:center; text-align:center; }
+  .node[data-state="busy"] { border-color:color-mix(in srgb, var(--busy) 45%, var(--line)); }
+  /* An agent is a smaller body in the same system, next to the session it shares a directory
+     with — never inside it. Tinted rather than outlined, and hooked, so it reads as the
+     session's dependent without a line claiming a parentage the source never published. */
+  .node[data-role="agent"] { padding-top:.55rem; border-color:transparent;
+          background:color-mix(in srgb, var(--line) 22%, transparent); }
+  .node[data-role="agent"] .dial { width:3.6rem; height:3.6rem; }
+  .node[data-role="agent"] .pct { font-size:.95rem; }
+  .node[data-role="agent"] .why { font-size:.6rem; max-width:3.4rem; }
+  .node[data-role="agent"] .why b { font-size:1rem; }
+  .node[data-role="agent"] .project { font-weight:400; }
+  /* Said, not shown: the three glyphs differ in silhouette, so a reader who cannot separate
+     two hues still has the state — but a screen reader is handed a bullet and nothing else. */
+  .sr { position:absolute; width:1px; height:1px; overflow:hidden; clip-path:inset(50%); white-space:nowrap; }
+  .dial { position:relative; width:5.5rem; height:5.5rem; }
+  .dial svg { width:100%; height:100%; display:block; overflow:visible; }
+  .track { fill:none; stroke:var(--line); stroke-width:5; }
+  /* Butt caps, not round: a rounded cap adds half a stroke width at each end, which draws a
+     1% reading at three times its extent. The prettier cap overstates every small number. */
+  .arc { fill:none; stroke:var(--dim); stroke-width:5; }
+  .node[data-state="busy"] .arc { stroke:var(--busy); }
+  /* A reading past the freshness threshold is drawn as what it is: thin, faded, and in the
+     warning hue — never the solid arc of a live one. Its EXTENT stays true, because the
+     number is still the truth of an earlier moment; and a dash pattern here would overwrite
+     stroke-dasharray, which is what carries the percentage. */
+  .node[data-reading="stale"] .arc, .node[data-reading="undated"] .arc {
+          stroke:var(--warn); stroke-width:2.5; opacity:.7; }
+  /* Nothing was measured. Keyed on the measurement and never on the age of the file: a
+     solid empty ring is what a session measured at 0% wears, and the two must not match. */
+  .track.unmeasured { stroke-dasharray:2 6; stroke-linecap:round; }
+  /* Once per arrival, not forever: the fragment is replaced on every poll, so a single run
+     per swap is what makes the fleet breathe at the rate its frames actually land. A looping
+     animation would say "a frame just arrived" for five seconds after it stopped being true. */
+  .halo { fill:none; stroke:var(--busy); stroke-width:2; opacity:0; transform-origin:50% 50%;
+          animation:halo 1.6s ease-out 1; }
+  .node[data-state="idle"] .halo { stroke:var(--dim); }
+  @keyframes halo { from { opacity:.5; transform:scale(1); } to { opacity:0; transform:scale(1.22); } }
+  /* Motion is the one thing here nobody can look away from, so it is the first thing a
+     reader who asked for less of it stops getting. The reading is still readable without it. */
+  /* Scaled, not merely stopped: at rest the halo sits inside the track's own stroke, so
+     "animation:none" alone left the one fact it carries invisible. */
+  @media (prefers-reduced-motion: reduce) { .halo { animation:none; opacity:.35; transform:scale(1.18); } }
+  .val { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
+         font-variant-numeric:tabular-nums; }
+  .pct { font-size:1.25rem; font-weight:650; letter-spacing:-.01em; }
+  .pct i { font-style:normal; font-size:.7em; font-weight:500; color:var(--dim); }
+  .why { font-size:.68rem; color:var(--dim); line-height:1.2; max-width:4.4rem; }
+  .why b { display:block; font-size:1.25rem; font-weight:400; }
+  .who { margin-top:.5rem; display:flex; align-items:baseline; gap:.3rem; max-width:100%; }
+  .who .project { font-weight:600; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .node[data-state="busy"] .who .project { font-weight:700; }
+  .shape { font-size:.7rem; color:var(--dim); }
+  .node[data-state="busy"] .shape { color:var(--busy); }
+  .node[data-state="unknown"] .shape { color:var(--warn); }
+  .sub { color:var(--dim); font-size:.76rem; max-width:100%; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .asof { font-size:.72rem; color:var(--dim); font-variant-numeric:tabular-nums; margin-top:.15rem; }
+  .asof.stale { color:var(--warn); font-weight:600; }
+  @media (max-width: 30rem) { .map { grid-template-columns:repeat(auto-fill,minmax(8.5rem,1fr)); gap:.6rem; } }
+
   /* Below this the table stops being a table: one card per session, every value keeping the
      name of the column it came from. Nothing is dropped — a phone that hides the context
      column would be a phone that renders "not measured" as nothing at all. */
@@ -365,9 +492,17 @@ export function renderPage(fleet) {
     .bar { display:none; }
   }
 </style>
-</head><body>
+</head><body data-view="${view}">
 <header>
   <h1>tarmac</h1>
+  <!-- Links, not buttons: the view survives a reload, a bookmark and a browser with
+       JavaScript off — the state of a page whose own noscript banner promises it is still
+       readable. Both views are in the fragment below either way, so switching costs the
+       server nothing and the two can never show readings of different ages. -->
+  <nav>
+    <a href="/"${view === 'table' ? ' aria-current="page"' : ''}>Table</a>
+    <a href="/map"${view === 'map' ? ' aria-current="page"' : ''}>Map</a>
+  </nav>
   <!-- Not "updated just now". If the script never runs — a policy-injected CSP without
        'unsafe-inline', a script error — that text would stand as a permanent lie, and
        <noscript> would not fire to correct it because JavaScript is enabled. The page's one
@@ -506,7 +641,7 @@ const SCRIPT = `
  */
 function renderRow(r) {
     const state = stateOf(r);
-    const word = r.busy === true ? 'busy' : r.busy === false ? 'idle' : (r.status ?? 'unknown');
+    const word = stateWord(state, r);
     // `data-label` is not decoration: below ~46rem the columns stack, the header row is gone,
     // and a value whose column has no name is a bare "—" that could mean anything.
     // Every cell holds exactly ONE element. Stacked on a phone the label sits left and the
@@ -523,12 +658,106 @@ function renderRow(r) {
     <td data-label="Uptime" class="num dim"><span class="v">${r.uptimeMs === null ? dash() : esc(duration(r.uptimeMs))}</span></td>
   </tr>`;
 }
-const stateOf = (r) => (r.busy === true ? 'busy' : r.busy === false ? 'idle' : 'unknown');
 const SHAPE = { busy: '●', unknown: '▲', idle: '○' };
+/**
+ * The state in words, for both surfaces — derived from the state the MODEL decided, never
+ * from the row a second time. Two expressions for one fact on one element is how a node ends
+ * up shaped `unknown` and captioned `idle`.
+ *
+ * An unrecognised status is quoted as it came rather than flattened to "unknown": the point
+ * of keeping it is that someone reading the page can go and find out what `compacting` means.
+ */
+const stateWord = (state, r) => state === 'unknown' ? (r.status ?? 'unknown') : state;
+/**
+ * Which kind of missing a missing percentage is. One lookup for both surfaces: the table
+ * says it beside a dash, the map says it inside an empty dial, and a second copy of these
+ * three words is a second chance to describe the same state differently.
+ */
+const CTX_WHY = { fresh: 'no turn yet', drift: 'schema drift', absent: 'not chained' };
+/**
+ * The map: one node per session, laid out as a grid rather than a graph. An empty fleet is not
+ * its business — `renderLive` says that once, above both views, rather than letting each of
+ * them render the same sentence and hide one of the two.
+ *
+ * There are no edges because the sources publish no relationship between two sessions — the
+ * one thing they do carry is the working directory, and that is expressed by putting an
+ * agent NEXT to the session it shares a directory with, never by drawing a line that would
+ * claim more than the data says.
+ *
+ * Everything a reader interprets is decided in `map.ts` and rendered here, on the server,
+ * for the same reason the table is: the rules that keep a reading honest are tested, and a
+ * copy of them re-derived in browser JavaScript would sit where this suite cannot reach.
+ */
+export function renderMap(fleet) {
+    return `<div class="map">${buildMap(fleet).nodes.map(renderNode).join('')}</div>`;
+}
+/**
+ * One node. Five facts, in five channels that do not depend on colour alone: the arc is how
+ * full the context is, the dial's weight is how much that reading may be believed, a dotted
+ * dial is no reading at all, the shape beside the name is the session's state, and the halo
+ * says one landed moments ago. The words under them are the same ones the table uses for the
+ * same conditions — including the halo's, which would otherwise live only in a drawing.
+ */
+function renderNode({ row: r, role, state, reading, measured, pulse }) {
+    // The model owns "is there a number"; this reads its verdict rather than asking the row a
+    // second question. `fresh` and `drift` are the two states where the age of the file and the
+    // presence of a reading disagree, and they are the two that matter most.
+    const pct = measured ? r.ctxPct : null;
+    const value = pct === null
+        ? `<span class="why"><b>&mdash;</b>${esc(CTX_WHY[r.ctxState] ?? 'no reading')}</span>`
+        : `<span class="pct">${pct}<i>%</i></span>`;
+    // The reading's own age, and only when it is one the reader must not take for current.
+    const asOf = reading === 'stale' && r.snapshotAgeMs !== null
+        ? `<div class="asof stale">! ${esc(asOfAge(r.snapshotAgeMs))} ago</div>`
+        : reading === 'undated'
+            ? `<div class="asof stale">! undated</div>`
+            : '';
+    // An agent carries its own project, like every other node. Placement is not a promise —
+    // the grid wraps where the viewport says, and the fleet's sort can hand the same agent a
+    // different neighbour on the next poll — so nothing here points at the node beside it.
+    return `<article class="node" data-role="${role}" data-state="${state}" data-reading="${reading}">
+      <div class="dial">
+        <svg viewBox="0 0 80 80" aria-hidden="true">${pulse ? `<circle class="halo" cx="40" cy="40" r="${DIAL_R}"/>` : ''}<circle class="track${measured ? '' : ' unmeasured'}" cx="40" cy="40" r="${DIAL_R}"/>${pct === null ? '' : arc(pct)}</svg>
+        <div class="val">${value}</div>
+        ${pulse ? `<span class="sr">a reading just landed</span>` : ''}
+      </div>
+      <div class="who"><span class="shape" aria-hidden="true">${SHAPE[state]}</span><span class="sr">${esc(stateWord(state, r))}</span><span class="project">${esc(r.project)}</span></div>
+      <div class="sub">${esc(r.name)}</div>
+      ${r.kind === null || r.kind === INTERACTIVE ? '' : `<div class="sub">${esc(r.kind)}</div>`}
+      <div class="sub">${esc(r.model)}${r.effort === null ? '' : ` · ${esc(r.effort)}`}</div>
+      ${asOf}
+    </article>`;
+}
+/**
+ * How old a dated reading is, in the words both surfaces use.
+ *
+ * `duration` floors to whole minutes, and `--stale-after` takes seconds — so a 30s reading
+ * judged against a 2s threshold rendered "! 0m ago": the "!" saying past the threshold and
+ * the "0m" saying brand new, in the same breath. Under a minute the age stops pretending to
+ * be a round number.
+ */
+const asOfAge = (ms) => (ms < 60_000 ? '<1m' : duration(ms));
+/** The dial's geometry. One radius, named once, so the arithmetic below cannot drift from it. */
+const DIAL_R = 30;
+const DIAL_C = 2 * Math.PI * DIAL_R;
+/**
+ * The filled part of the ring, as a fraction of the circle's real circumference.
+ *
+ * `pathLength="100"` would say the same thing in far prettier markup — "62 filled, 38 empty"
+ * — but it is an attribute browsers have not always honoured on basic shapes, and the way it
+ * fails is the one this page cannot afford: the dash array is ignored, the arc closes, and
+ * every session reads as a full context window. Two decimals is well under a pixel at this
+ * radius, and it keeps the markup diffable.
+ */
+function arc(pct) {
+    const filled = (Math.min(100, Math.max(0, pct)) / 100) * DIAL_C;
+    return (`<circle class="arc" cx="40" cy="40" r="${DIAL_R}" transform="rotate(-90 40 40)"` +
+        ` stroke-dasharray="${round2(filled)} ${round2(DIAL_C - filled)}"/>`);
+}
+const round2 = (n) => Math.round(n * 100) / 100;
 function ctxCell(r) {
     if (r.ctxPct === null) {
-        const why = { fresh: 'no turn yet', drift: 'schema drift', absent: 'not chained' }[r.ctxState] ?? '';
-        return `${dash()} <span class="dim">${esc(why)}</span>`;
+        return `${dash()} <span class="dim">${esc(CTX_WHY[r.ctxState] ?? '')}</span>`;
     }
     // A stale reading is still the truth — of an earlier moment. Show it, and date it, with
     // the same "!" the terminal marks it with: an age in the same grey as everything else is
@@ -539,7 +768,7 @@ function ctxCell(r) {
     // "! 0m ago" — a missing measurement as a zero, contradicting itself in the same breath
     // (the "!" says past the threshold, the "0m" says brand new). The terminal path already
     // re-checked it; the two surfaces are not allowed to disagree about the module's own rule.
-    const asOf = r.stale && r.snapshotAgeMs !== null ? ` <span class="stale">! ${esc(duration(r.snapshotAgeMs))} ago</span>` : '';
+    const asOf = r.stale && r.snapshotAgeMs !== null ? ` <span class="stale">! ${esc(asOfAge(r.snapshotAgeMs))} ago</span>` : '';
     return `<span class="bar"><i style="width:${Math.min(100, r.ctxPct)}%"></i></span>${r.ctxPct}%${asOf}`;
 }
 /** A partial sum is never presented as the fleet's total. */

package/dist/server.js

@@ -14,6 +14,11 @@ import { SOURCE_PHRASE } from './config.js';
  * failures carry it too: their text is what it quotes as the reason.
  */
 const IDENTITY = { 'x-tarmac': '1' };
+/** The addresses that serve the shell, and which view each one opens on. */
+const PAGES = new Map([
+    ['/', 'table'],
+    ['/map', 'map'],
+]);
 export function createFleetServer({ collect }) {
     return http.createServer(async (req, res) => {
         // Loopback binding alone does not stop a DNS-rebinding page in the user's own browser
@@ -38,7 +43,12 @@ 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') {
             res.writeHead(404, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
             res.end('not found\n');
             return;
@@ -58,7 +68,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) {

package/dist/sessions.js

@@ -6,9 +6,26 @@
 // 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],
 ]);
 /** @param text raw stdout of `claude agents --json` */
 export function parseAgents(text) {
@@ -32,7 +49,10 @@ 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)
             health.unknownStatus += 1;

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