@adrrr/tarmac 0.1.2 → 0.3.0

package/README.md

@@ -1,62 +1,111 @@
 # 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     $53.98  8h
-mercury-dashboard  busy   27%      22m !  Fable 5  max     $70.62  8h
-gemini             idle   12%      3h !   Opus 5   high    $3.14   8h
+apollo             busy   28%      7m     Fable 5  max     $41.20  8h
+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 · $127.74
+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):
 
-`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.
+```
+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
+
+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.
+
+### 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:
 
@@ -66,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"` | `<home>/.claude/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,
@@ -126,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/cli.js

@@ -13,7 +13,7 @@ import { parseArgs } from './args.js';
 import { collectFleet } from './collect.js';
 import { readConfigFile, resolveConfig } from './config.js';
 import { createFleetServer, listenFleetServer } from './server.js';
-import { install, uninstall, paths, planInstall, planUninstall } from './install.js';
+import { install, uninstall, paths, planInstall, planUninstall, installedSnapshotsDir, wrapperIsOurs } from './install.js';
 import { confirmTyped } from './prompt.js';
 import { reapOrphanedTemps } from './reap.js';
 import { renderPlan, renderSettings, renderTable, restoreMeaning, servingLine } from './render.js';
@@ -39,7 +39,8 @@ const USAGE = `tarmac — fleet observability for Claude Code
   --port           the dashboard's port (default: 4477 — a busy default walks up to the
                    next free port, a port named here refuses instead)
   --snapshots-dir  where the chained statusline drops its payloads
-                   (default: <home>/.claude/tarmac/snapshots)
+                   (default: $XDG_STATE_HOME/tarmac/snapshots, or
+                   <home>/.local/state/tarmac/snapshots)
   --claude-bin     path to the claude CLI (default: claude)
 
   Those three settings can also be set, in decreasing order of precedence, by the
@@ -78,6 +79,11 @@ try {
             console.log(res.alreadyInstalled
                 ? `install: already installed — wrapper regenerated, settings.json left alone`
                 : `install: statusLine wrapped — undo with \`${plan.undo}\``);
+            // What the plan promised, as it actually went: a frame of the OLD wrapper can land in
+            // that directory between the two, so the count is reported rather than assumed.
+            if (res.legacy !== null)
+                console.log(`install: cleared ${res.legacy.payloads} runtime payload(s) from ${res.legacy.dir} — they belong in ${res.snapshots}` +
+                    (res.legacy.kept > 0 ? ` (${res.legacy.kept} file(s) kept, so the directory stays)` : ''));
         }
         else {
             const { mode } = uninstall({ home });
@@ -88,11 +94,20 @@ try {
         // Only the reading commands resolve settings, and only they read the config file: a
         // typo in it must not be what stands between a user and `tarmac uninstall`.
         const p = paths(args.home ?? os.homedir());
+        // The installed wrapper's own path, when there is one: the default is where the WRITER
+        // writes, not where a reader's environment would have put it. Recomputing it here made
+        // `XDG_STATE_HOME` in one process and not the other a silent split.
+        const frozen = installedSnapshotsDir(p);
+        if (frozen === null && wrapperIsOurs(p))
+            console.error(`tarmac: ${p.wrapper} is ours but does not say where it writes — falling back to ${p.snapshots}`);
         const config = resolveConfig({
             flags: { staleAfter: args.staleAfter, port: args.port, snapshotsDir: args.snapshotsDir },
             env: process.env,
             file: readConfigFile(p.config),
-            defaultSnapshotsDir: p.snapshots,
+            // The installed wrapper's own path, when there is one: the default is where the
+            // WRITER writes, not where a reader's environment would have put it. Recomputing it
+            // here made `XDG_STATE_HOME` in one process and not the other a silent split.
+            defaultSnapshotsDir: frozen ?? p.snapshots,
         });
         const snapshotsDir = config.snapshotsDir.value;
         const staleAfterMs = config.staleAfterMs.value;
@@ -108,7 +123,7 @@ try {
             if (failed > 0)
                 console.error(`tarmac: could not remove ${failed} orphaned temp file(s) under ${snapshotsDir}`);
             const server = createFleetServer({
-                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source }),
+                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null }),
             });
             // A port nobody chose is not worth failing over: this walks past a busy 4477 and says
             // where it landed. A port that WAS chosen refuses instead, and the refusal leaves
@@ -123,7 +138,7 @@ try {
             console.log(servingLine(bound));
         }
         else {
-            const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source });
+            const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null });
             if (args.watch) {
                 // One redraws a screen, the other is meant to be piped once. Silently letting one win
                 // is how someone ends up parsing a frame of terminal art.

package/dist/collect.js

@@ -3,22 +3,30 @@ import { SOURCE_PHRASE } from './config.js';
 import { discoverSessions } from './discover.js';
 import { readSnapshots } from './snapshots.js';
 import { buildFleet } from './fleet.js';
-export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', }) {
+export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', installed = false, }) {
     const { sessions, health: discovery } = await discoverSessions({ claudeBin });
     const { snapshots, dirError, unreadable, duplicates, dirMissing } = readSnapshots(snapshotsDir, { now });
     const fleet = buildFleet({ sessions, snapshots, now, discovery, staleAfterMs });
     // Both blind spots travel with the data: a directory we could not read and files we
     // could not parse are OUR failures to report, not silence to render as "all clear".
     //
-    // An absent directory is judged HERE, because this is the layer that knows who chose it:
-    // the default may simply not exist yet (nothing has been chained), but a path someone
-    // typed — flag, environment, or a config file edited months ago — that is not there is a
-    // setting pointing at nothing. Rendered as "not chained yet" it sends the user to run
-    // `tarmac install`, which cannot fix it: install writes where install writes.
-    fleet.health.snapshotsError =
-        dirMissing && snapshotsDirSource !== 'default'
+    // An absent directory is judged HERE, because this is the layer that knows who chose it.
+    // A path someone typed — flag, environment, or a config file edited months ago — that is
+    // not there is a setting pointing at nothing; rendered as "not chained yet" it sends the
+    // user to run `tarmac install`, which cannot fix it: install writes where install writes.
+    //
+    // Exactly ONE case is innocent, and it is narrower than it used to be: no install here at
+    // all. Since #20 the default is the path the install FROZE into the wrapper — a directory
+    // that was chosen and created by a run that happened — so its absence means the writer and
+    // the reader have parted company, which renders as a healthy, empty fleet. That is the one
+    // failure this tool may not have.
+    fleet.health.snapshotsError = !dirMissing
+        ? dirError
+        : snapshotsDirSource !== 'default'
             ? `ENOENT: ${snapshotsDir} does not exist — set by ${SOURCE_PHRASE[snapshotsDirSource]}`
-            : dirError;
+            : installed
+                ? `ENOENT: ${snapshotsDir} does not exist — the installed wrapper writes there`
+                : dirError;
     fleet.health.snapshotsUnreadable = unreadable;
     fleet.health.snapshotsDuplicates = duplicates;
     fleet.health.snapshotsDir = snapshotsDir;

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