@adrrr/tarmac 0.2.0 → 0.4.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,106 +19,179 @@ 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
 
-`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.
+  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
 
-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.
+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 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.
+
+In the header are the account's **two rate-limit gauges** — the five-hour window and the
+seven-day one, each with its used percentage and its reset spelled as the time left. They are
+page-level because that is what a rate limit is: one account, which every session below is
+spending from. A fleet whose snapshots carry no limits says `— no reading` on a dotted rail
+rather than drawing a window at 0%, and a reading past the freshness threshold is dated
+`! 40m ago` — the countdown is recomputed every poll, the percentage is as old as its snapshot,
+and a page that showed both as now would be lying with the moving one.
+
+### 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).
+
+Under the map is a **scrubber over the day this serve has seen**. Drag it and the dials render
+the fleet as it was at that minute; press play and the day walks past. The record is fetched on
+load, never per position, so scrubbing asks the server nothing. A replay never poses as the present: a banner names
+the minute and holds the way back, the live fragment is hidden while it is up, halos stay off
+because a sample never "just landed", and a session absent from a minute is absent from the
+map. The range says what it truly covers — a serve ten minutes old offers ten minutes. The
+account's gauges replay too, counted from the minute being shown rather than from now, so the
+five-hour window can be watched draining and refilling across a day.
 
 ## 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:
 
 | Source | What it gives | How solid |
 |---|---|---|
-| `claude agents --json` | which sessions exist, busy or idle, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
+| `claude agents --json` | which sessions exist, busy, idle or waiting on you, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
 | 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, `GET /api/history` for the last 24h of readings it took while it ran | `--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` |
-
-**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`.
-
-## What V1 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,
-  and `agents --json` reports `idle` for a session waiting on you and for one that finished.
-  Inferring it would mean reading a transcript, which is the one thing this tool will not do.
+| 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).
+
+`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 it deliberately does not do
+
+- **No inferred "waiting for you".** `agents --json` reports `waiting` with a reason —
+  a permission prompt, an open dialog — and tarmac draws exactly that, on both surfaces.
+  What it will not do is guess at the rest: a session that asked you a question in prose
+  still reports `idle`, and the only way to know better is to read a transcript, which is
+  the one thing this tool will not do. The signal is as good as the surface, and no better.
 - **No history.** Each run is a snapshot in time; context and cost curves come later.
 - **No Windows.** The generated wrapper is POSIX `sh`.
 - **No remote fleets.** It watches the machine it runs on.
@@ -131,8 +206,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,8 @@
 import path from 'node:path';
 import { DEFAULT_STALE_AFTER_MS } from './config.js';
 import { guardVersions } from './schema.js';
+import { isWaiting } from './sessions.js';
+import { SID_NAME } from './wrapper.js';
 export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_STALE_AFTER_MS, discovery = null, }) {
     const rows = sessions.map((s) => {
         const t = (s.sessionId && snapshots.get(s.sessionId)) || null;
@@ -22,7 +24,9 @@ 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,
+            waitingFor: s.waitingFor,
             busy: s.busy,
             uptimeMs: typeof s.startedAt === 'number' ? now - s.startedAt : null,
             ctxState: t ? t.ctxState : 'absent',
@@ -39,6 +43,14 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
     });
     rows.sort((a, b) => rank(a) - rank(b) || (b.ctxPct ?? -1) - (a.ctxPct ?? -1));
     const covered = rows.filter((r) => r.ctxState !== 'absent').length;
+    // 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 +67,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
@@ -65,7 +78,10 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
             // Tested tolerance from the fleet: `fresh` never counts, or a recycled fleet would
             // raise this every single night.
             schemaBroken: covered > 0 && drift === covered,
-            unknownStatus: rows.filter((r) => r.busy === null).length,
+            // Recomputed from the rows rather than taken from `discovery`, which may be null — so
+            // the exemption the reader grants a waiting session has to be granted again here, or
+            // the banner accuses a session both surfaces are drawing as waiting.
+            unknownStatus: rows.filter((r) => r.busy === null && !isWaiting(r)).length,
             busy: rows.filter((r) => r.busy === true).length,
             // A sum over 3 of 7 sessions is not the fleet's cost. Same rule as `sumUsage` one
             // layer down: add only what is really a number, and count those — a payload with no
@@ -80,6 +96,34 @@ export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_ST
         },
     };
 }
+/**
+ * The account's rate limits, as this fleet's sessions report them.
+ *
+ * They belong to the ACCOUNT and not to any one session, but they arrive per snapshot — so the
+ * rows do not carry contradicting numbers, they carry the same number at different ages, and
+ * the youngest is the one still true. Same rule as everything else in this module: the freshest
+ * reading wins.
+ *
+ * A snapshot dated AFTER the clock that read it is refused rather than believed, which is the
+ * verdict `map.ts` reaches on the same value: an NTP correction or a mount whose time runs
+ * ahead does not produce a small age, it produces something that is not an age at all — and
+ * being negative it would beat every real reading for as long as the skew lasts.
+ *
+ * Here rather than in either of its readers: the ring samples it every minute and the page's
+ * header draws it, and two copies of "which session's word counts" is two answers about one
+ * account the day either one is touched.
+ */
+export function accountLimits(rows) {
+    let freshest = null;
+    for (const r of rows) {
+        if (r.rateLimits === null || r.snapshotAgeMs === null || r.snapshotAgeMs < 0)
+            continue;
+        if (freshest === null || r.snapshotAgeMs < freshest.ageMs) {
+            freshest = { rateLimits: r.rateLimits, ageMs: r.snapshotAgeMs };
+        }
+    }
+    return freshest;
+}
 // busy first, then unknown (it might be busy), then idle
 const rank = (r) => (r.busy === true ? 0 : r.busy === null ? 1 : 2);
 const round2 = (n) => Math.round(n * 100) / 100;

package/dist/history.js

@@ -0,0 +1,88 @@
+// P5 — what the serve already read, kept for a day.
+//
+// The dashboard reads the whole fleet on every request and forgets it on the next one, so a
+// number that moved is a number nobody can point at afterwards. This is that reading, held.
+//
+// In memory and nowhere else, by design. A fleet journal on disk is the one file this tool
+// promised never to write — it would outlive the process that made it, sit in someone's home
+// carrying session ids, working directories and costs, and turn "tarmac reads, it does not
+// keep" into a sentence with an asterisk. What a serve remembers therefore starts when that
+// serve started, which is exactly what `since` says out loud.
+//
+// The ring is bounded before it is anything else: a serve is left open for days, and one
+// sample a minute for a day is a size, while "everything since Tuesday" is a leak with a
+// nicer name.
+import { stateOf } from './map.js';
+import { isWaiting } from './sessions.js';
+import { accountLimits } from './fleet.js';
+/** One sample a minute. Not a setting: see `HISTORY_SLOTS`. */
+export const HISTORY_CADENCE_MS = 60_000;
+/**
+ * 24 hours of them. One minute and one day are the product — a cadence knob would let a
+ * reader ask this process to spawn `claude agents --json` every second, and a retention knob
+ * would let them ask it to hold a week of fleets in RAM. A page that needs to say what it
+ * covers reads `since`.
+ */
+export const HISTORY_SLOTS = 1440;
+export function createHistory({ since, cadence }) {
+    const slots = [];
+    // Whether anything has aged out yet, which is the only thing that can move `since` off the
+    // moment the serve started. A ring that is exactly full has dropped nothing.
+    let dropped = false;
+    const push = (slot) => {
+        slots.push(slot);
+        // Trimmed on the way in and never on the way out: the array's own length is the
+        // guarantee, so no reader has to be told the ring is bounded for it to be true.
+        if (slots.length > HISTORY_SLOTS) {
+            slots.splice(0, slots.length - HISTORY_SLOTS);
+            dropped = true;
+        }
+    };
+    return {
+        record(fleet) {
+            const sample = sampleOf(fleet);
+            push({ t: sample.t, sample });
+        },
+        miss(t) {
+            push({ t, sample: null });
+        },
+        // Rebuilt per read, and never the ring itself: this is the only copy there is and no file
+        // to restore it from, so a reader that spliced what it was handed would edit the record.
+        read: () => {
+            const samples = slots.filter((s) => s.sample !== null).map((s) => s.sample);
+            return {
+                since: dropped ? slots[0].t : since,
+                cadence,
+                samples,
+                missed: slots.length - samples.length,
+            };
+        },
+    };
+}
+/**
+ * A fleet reading, reduced to what a replay reads back.
+ *
+ * The names are the omission that matters, and it is not an oversight to be commented — it is
+ * pinned by a test. `claude agents --json` names a background session after the PROMPT it was
+ * given, so a fleet's names are a record of what its agents were told to do. The live view may
+ * show that, because someone is looking at their own screen in the present tense; a day of
+ * them, retained by a process and served back on a route, is a different object. No name for
+ * anyone, so there is no rule about kinds to get wrong later.
+ */
+function sampleOf({ rows, health }) {
+    return {
+        t: health.generatedAt,
+        sessions: rows.map((r) => ({
+            sid: r.sessionId,
+            project: r.project,
+            kind: r.kind,
+            state: stateOf(r),
+            waitingFor: isWaiting(r) ? r.waitingFor : null,
+            ctxState: r.ctxState,
+            ctxPct: r.ctxPct,
+            costUsd: r.costUsd,
+        })),
+        // The reading, without its age: the ring keeps each reading and never how old it was.
+        rateLimits: accountLimits(rows)?.rateLimits ?? null,
+    };
+}

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/limits.js

@@ -0,0 +1,62 @@
+// P3 — the account's two windows.
+//
+// Every session on the page spends from the same two allowances, so they belong to the page
+// and not to a node: five hours, and seven days. The statusline payload carries both, as a
+// used percentage and the epoch each one rolls over at.
+//
+// This module reads a shape someone else versions, which is why it reads it the way
+// `snapshots.ts` reads the context window: the PRESENCE of a key says whether a number was
+// ever taken, and the value says what it was. A key that is gone, or holding something that is
+// not a percentage, is a schema that moved — and neither one is 0%. There is exactly one thing
+// a dashboard must never do with an account's limits, and that is report a window it could not
+// read as a window with room to spare.
+//
+// The reset is turned into a stretch of time HERE, against the clock the reading was taken
+// with, so that no renderer has to go and find a clock of its own: the live page subtracts from
+// the moment it read the fleet, and a replay subtracts from the minute its sample was taken.
+// Both then have one rule about what a negative answer means.
+/**
+ * The two windows, in the order they are read. A table rather than two hand-written branches:
+ * the page script draws the same pair in the browser for a replayed minute, and it is handed
+ * this list rather than keeping a second copy of the vocabulary.
+ */
+export const LIMIT_WINDOWS = [
+    { key: 'five_hour', label: '5h', said: 'five-hour window' },
+    { key: 'seven_day', label: '7d', said: 'seven-day window' },
+];
+/**
+ * How far from the reading a reset may land and still be one.
+ *
+ * The same discipline the percentage gets, one field over: `used_percentage` outside 0-100 is
+ * refused rather than drawn, and a `resets_at` outside a plausible distance is refused for the
+ * same reason. The longest window here is seven days, so nothing this account resets at is more
+ * than eight away — while the two ways this field can move are both far outside that: the same
+ * number in milliseconds lands fifty thousand years out, and `0`, the sentinel an unset field so
+ * often is, lands in 1970. Both were rendered with a straight face ("resets in 19656250d").
+ */
+export const RESET_HORIZON_MS = 8 * 24 * 3600 * 1000;
+/** Both windows, always — a window that could not be read is a gauge that says so. */
+export function readLimits(rateLimits, now) {
+    // `rate_limits: []` and `rate_limits: "none"` are legal JSON and not a pair of windows.
+    // Neither may reach the lookup below as something to index.
+    const ok = rateLimits !== null && typeof rateLimits === 'object' && !Array.isArray(rateLimits);
+    return LIMIT_WINDOWS.map(({ key, label, said }) => {
+        const w = ok ? rateLimits[key] : undefined;
+        const has = w !== null && typeof w === 'object' && !Array.isArray(w) && 'used_percentage' in w;
+        const v = has ? w.used_percentage : undefined;
+        // Present and null: a window whose number has not been taken yet. Absent, or holding
+        // something that is not a percentage: the shape moved. The discriminant is the key.
+        const pct = has && typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 100 ? Math.floor(v) : null;
+        const why = pct !== null ? null : rateLimits == null || (has && v === null) ? 'absent' : 'drift';
+        const at = has && typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;
+        const resetsInMs = at === null ? null : at * 1000 - now;
+        return {
+            key,
+            label,
+            said,
+            pct,
+            why,
+            resetsInMs: resetsInMs === null || Math.abs(resetsInMs) > RESET_HORIZON_MS ? null : resetsInMs,
+        };
+    });
+}