@adrrr/tarmac 0.6.0 → 0.7.0

package/README.md

@@ -45,30 +45,33 @@ atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 account  5h 17% resets in 2h 14m · 7d 42% resets in 3d 11h · as of 7m
 ```
 
-That is the table with the status line chained. The last line is the account's, not any
-session's: every row above spends from the same five-hour and seven-day
-[window](docs/MANUAL.md#the-accounts-two-windows), so it is printed once, dated like every
-other reading here, and `— no reading` rather than `0%` when no snapshot carried one.
+That is the table with the status line chained. The last line belongs to the account, not to
+any one session. Every row above spends from the same five-hour and seven-day
+[window](docs/MANUAL.md#the-accounts-two-windows), so it is printed once. It is dated like
+every other reading here, and it reads `— no reading` rather than `0%` when no snapshot
+carried one.
 
 With nothing installed, 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.
+straight from `claude agents --json`. The context column reads `— absent`. Model, effort and
+cost fall to `—`. The line under the table counts how many sessions are covered.
 
 Node ≥ 20. Zero runtime dependencies: no framework, no bundler, nothing to audit.
-`--help` works everywhere. An option handed to a command that does not read it is an error,
-not something quietly ignored. Every command, flag and route:
+`--help` and `--version` (`-v`) work everywhere. An option handed to a command that does not
+read it is an error, never something quietly ignored. Every command, flag and route is in
 [the manual](docs/MANUAL.md#commands-and-options).
 
 ## The map
 
-`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. It
-binds to loopback and refuses any request whose `Host` is not loopback, or that a browser
-marks as coming from another origin, so your cwd paths and costs never leave the machine. A
-client that sends no such mark, curl or a script, is left alone. Behind a reverse proxy, which
-presents a `Host` of its own, `--trust-host <name>` names the one to let through and says who
-that lets in: [the manual](docs/MANUAL.md#putting-it-behind-a-reverse-proxy). The listening
-rules: [the manual](docs/MANUAL.md#what-serve-listens-on).
+`tarmac serve` puts the same fleet in the browser. Every session is a row, the ages keep
+climbing, and a banner goes up the moment a refresh fails, so the table never goes stale in
+silence.
+
+It binds to loopback. It refuses any request whose `Host` is not loopback, and any request a
+browser marks as coming from another origin, so your cwd paths and costs never leave the
+machine. A client that sends no such mark, curl or a script, is left alone. A reverse proxy
+presents a `Host` of its own, so `--trust-host <name>` names the one to let through;
+[the manual](docs/MANUAL.md#putting-it-behind-a-reverse-proxy) says who that lets in. The
+listening rules are [there too](docs/MANUAL.md#what-serve-listens-on).
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/map-dark.png">
@@ -76,47 +79,47 @@ rules: [the manual](docs/MANUAL.md#what-serve-listens-on).
        alt="The tarmac map, live. Four framed groups, one per working directory and labelled with its project: beacon, holding a session halted on a permission prompt; harbor, holding a session busy with its context arc at 90% and a background agent docked under the cards of that frame as a strip named after its prompt; quay, reporting a status tarmac does not know; and atlas, idle at 36%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
 </picture>
 
-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. A background agent has no terminal behind it to
-draw a frame with, so it gets a strip of text rather than a dial that could never fill. Both
+The tab in the header swaps the table for the same fleet drawn as nodes: one per session, the
+arc its context, the shape by the name its state. A background agent has no terminal behind it
+to draw a frame with, so it gets a strip of text rather than a dial that could never fill. Both
 views render the same reading into the same fragment, so they can never disagree.
 
 The nodes are grouped by working directory: a frame per directory, labelled with its project,
-the sessions inside it as cards and the agents docked underneath as strips. That is the whole
-of what the frame claims: these were read in the same directory. It is not a parentage.
-`claude agents --json` publishes nothing that ties an agent to whoever dispatched it, so no
-label, no position and no line inside a frame says one node asked for another. An agent whose
-directory matches no session gets a frame of its own rather than somebody else's.
+the sessions inside it as cards and the agents docked underneath as strips. A frame claims one
+thing and no more: these nodes were read in the same directory. `claude agents --json`
+publishes nothing that ties an agent to whoever dispatched it, so no label, no position and no
+line inside a frame says one node asked for another. An agent whose directory matches no
+session gets its own frame rather than somebody else's.
 
 Above the fleet are the account's five-hour and seven-day
-[gauges](docs/MANUAL.md#the-accounts-two-windows); under it a scrubber over the day this
-serve has seen. Drag it and the nodes render the fleet as it was at that minute, press play
-and the day walks past. Replayed, they are drawn flat and unframed: the record keeps a project
-name and never the directory it was read in, and a basename is not a directory. Two checkouts
-of `atlas` answer to the same word, so a frame drawn on it would claim a shared directory
-nobody can check.
+[gauges](docs/MANUAL.md#the-accounts-two-windows). Under it is a scrubber over the day this
+serve has seen. Drag it and the nodes render the fleet as it was at that minute. Press play
+and the day walks past. Replayed, the nodes are drawn flat and unframed. The record keeps a
+project name and never the directory it was read in, and a basename is not a directory. Two
+checkouts of `atlas` answer to the same word, so a frame drawn on it would claim a shared
+directory nobody can check.
 
 The map follows the rules the table follows. A reading past the freshness threshold is drawn
-thin, amber and dated. A percentage nobody measured is an empty dotted dial rather than a ring
-at zero. Where nothing was published at all, such as the strip of an agent the join found no
-snapshot for, nothing is drawn in its place, neither a dial nor a dash. A word
+thin, amber and dated. A percentage nobody measured is an empty dotted dial, never a ring at
+zero. Where nothing was published at all, such as the strip of an agent the join found no
+snapshot for, nothing is drawn in its place: no dial, no dash. A word
 `claude agents --json` printed that tarmac has no boolean for is shown as it came rather than
 filed as `idle`, and raises one warning above the fleet naming it. The page is JSON
 underneath: `GET /api/fleet` and `GET /api/history` serve exactly what the map draws. Details
-in [the manual](docs/MANUAL.md#the-map).
+are in [the manual](docs/MANUAL.md#the-map).
 
 ## Install
 
 `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,
-then waits for a typed word. `y` is not an answer; scripts pass `--yes`, deliberately.
+then waits for a typed word. `y` is not an answer. Scripts pass `--yes`, deliberately.
 
 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. Two files land under `~/.claude/`, the
 wrapper and the `backup.json` that undoes it, and neither changes at runtime. The snapshots go
 to `~/.local/state/tarmac/snapshots` (`$XDG_STATE_HOME` when set), because `~/.claude` is a
-directory people commit. The plan, the restore modes and the cleanup of the layout that kept
-snapshots inside `.claude`:
+directory people commit. The plan, the restore modes and the cleanup of the old layout that
+kept snapshots inside `.claude` are in
 [the manual](docs/MANUAL.md#installing-safely-the-full-contract).
 
 ## Why it does not break
@@ -132,17 +135,18 @@ tarmac reads two things instead:
 | `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. The real defence is not 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. A
-stale reading keeps its value and gets dated with a `!`. A Claude Code build no fixture covers
-gets its version named *before* anything breaks, and tarmac keeps reporting. The full
-state-by-state table is in [the manual](docs/MANUAL.md#degradation-state-by-state).
+That second row is the honest caveat. tarmac does not promise the payload will hold still.
+It promises that a measurement it could not take never renders as a confident `0`. What you
+get instead is an em dash naming 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. A stale reading keeps its value and gets dated with a
+`!`. A Claude Code build no fixture covers gets its version named *before* anything breaks,
+and tarmac keeps reporting. The full state-by-state table is in
+[the manual](docs/MANUAL.md#degradation-state-by-state).
 
 ## Configuration
 
-Three numbers are opinions rather than truths, so all three are yours, and behind a reverse
+Three numbers here are judgement calls, so all three are yours to set, and behind a reverse
 proxy the hosts `serve` answers to are yours as well. Everything else is deliberately not
 configurable, and all of it works with no configuration at all.
 
@@ -151,22 +155,22 @@ configurable, and all of it works with no configuration at all.
 | freshness threshold | `--stale-after 90s` \| `15m` \| `2h` | `10m` |
 | port | `--port 8080` | `4477` |
 | snapshots dir (read side) | `--snapshots-dir DIR` | the wrapper's frozen path when installed, else the XDG state directory |
-| trusted hosts | `--trust-host HOST`, once per host | none — loopback only |
+| trusted hosts | `--trust-host HOST`, once per host | none, so loopback only |
 
 Each also has an environment variable and a key in `<home>/.claude/tarmac/config.json`.
-Flag beats environment beats config file beats default, settled per setting; `serve` opens by
+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. Spellings, edge cases and the two health fields
-`tarmac list --json` reports: [the manual](docs/MANUAL.md#configuration).
+`tarmac list --json` reports are in [the manual](docs/MANUAL.md#configuration).
 
 ## What it deliberately does not do
 
 - **No inferred "waiting for you".** `agents --json` reports `waiting` with a reason, such as
   a permission prompt or an open dialog, and tarmac draws exactly that, in the table and on
-  the map. 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 its source, and no better.
+  the map. It does not guess at the rest. A session that asked you a question in prose still
+  reports `idle`, because the only way to know better is to read a transcript, and this tool
+  does not read transcripts.
 - **No history on disk.** `tarmac list` is a snapshot in time. A running `serve` holds the
   last 24 hours of the readings it took itself, in memory, so the page can replay them. That
   record reaches no further back than the serve that took it, and goes when it goes. None of
@@ -182,9 +186,9 @@ npm run build                  # flat JavaScript into dist/
 node scripts/demo-fleet.ts     # the invented fleet the captures above are taken of
 ```
 
-Every capture on this page is taken of a fleet that does not exist, because a screenshot of a
-real machine carries working directories, prompts and costs, and nothing real enters this
-repo. What CI covers, which Node version develops and which one ships:
+Every capture on this page is taken of a fleet that does not exist. A screenshot of a real
+machine carries working directories, prompts and costs, and nothing real enters this repo.
+What CI covers, which Node version develops and which one ships:
 [the manual](docs/MANUAL.md#developing). Capturing the fixtures for a new Claude Code build:
 [the manual](docs/MANUAL.md#capturing-a-new-claude-code-version).
 

package/dist/args.js

@@ -19,8 +19,13 @@ const OPTIONS = {
     '--watch': 'watch',
     '--yes': 'yes',
     '--help': 'help',
+    '--version': 'version',
+    // The one short spelling this parser knows, and it is here because it is what people type
+    // before they read anything (#110). No other flag gets one: a letter is a scarce name, and
+    // `-h` for help would be the next request and the one after that.
+    '-v': 'version',
 };
-const FLAGS = new Set(['json', 'watch', 'yes', 'help']);
+const FLAGS = new Set(['json', 'watch', 'yes', 'help', 'version']);
 /** Options that ACCUMULATE rather than overwrite — passed twice, both values are kept. */
 const LISTS = new Set(['trustHost']);
 /**
@@ -29,14 +34,15 @@ const LISTS = new Set(['trustHost']);
  * one level down — `tarmac serve --json` parsed cleanly and changed nothing, and from the
  * outside that is indistinguishable from a server that decided to answer HTML anyway.
  *
- * `help` is in every set on purpose: `--help` is answerable whatever else was typed.
+ * `help` is in every set on purpose: `--help` is answerable whatever else was typed, and
+ * `version` is there for the same reason — what build this is does not depend on the verb.
  */
 const ACCEPTS = {
-    list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help']),
-    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'home', 'claudeBin', 'help']),
-    install: new Set(['home', 'yes', 'help']),
-    uninstall: new Set(['home', 'yes', 'help']),
-    help: new Set(['help']),
+    list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help', 'version']),
+    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'home', 'claudeBin', 'help', 'version']),
+    install: new Set(['home', 'yes', 'help', 'version']),
+    uninstall: new Set(['home', 'yes', 'help', 'version']),
+    help: new Set(['help', 'version']),
 };
 /** The commands a misplaced flag would have been right on — an error that points somewhere. */
 function ownersOf(key) {
@@ -54,7 +60,7 @@ export function accepts(command, flag) {
     return key !== undefined && ACCEPTS[command].has(key);
 }
 export function parseArgs(argv) {
-    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, trustHost: [], home: null, claudeBin: 'claude', json: false, watch: false, yes: false, help: false };
+    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, trustHost: [], home: null, claudeBin: 'claude', json: false, watch: false, yes: false, help: false, version: false };
     let i = 0;
     if (argv[0] && !argv[0].startsWith('-')) {
         if (!COMMANDS.has(argv[0]))

package/dist/cli.js

@@ -7,6 +7,7 @@
 //
 // `install` / `uninstall` default to the home this process runs under, print what they are
 // about to change, and proceed only on the typed verb (or `--yes`, in writing, for scripts).
+import fs from 'node:fs';
 import os from 'node:os';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parseArgs } from './args.js';
@@ -31,6 +32,7 @@ const USAGE = `tarmac — fleet observability for Claude Code
   tarmac uninstall  [--home DIR] [--yes]
         restore the statusline exactly
 
+  --version, -v    print the version of this build and exit — on any command
   --watch          redraw the table every 5s until ^C, dating every reading
   --home           whose .claude to read or change (default: this home)
   --yes            skip the typed confirmation — required when stdin is not a terminal
@@ -52,6 +54,22 @@ const USAGE = `tarmac — fleet observability for Claude Code
   and by <home>/.claude/tarmac/config.json ({"staleAfterMs": …, "port": …,
   "snapshotsDir": …, "trustHosts": […]}). \`serve\` prints which one won.
 `;
+/**
+ * What this build calls itself, read from the `package.json` that ships beside it — the one
+ * file npm puts in every tarball whatever `files` says, and the only place the number is
+ * written down. `dist/cli.js` sits one directory in exactly as `src/cli.ts` does, so a single
+ * relative path answers for the published CLI and for the suite, which runs the source.
+ *
+ * A version it could not read is not a version: rather than print an "unknown" nobody can act
+ * on, this throws and leaves through the same catch as every other refusal here.
+ */
+function version() {
+    const at = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(at, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version === '')
+        throw new Error(`${at.href} carries no version`);
+    return pkg.version;
+}
 try {
     // Parsing is inside the try so that a refusal — a typo'd flag, a duration nobody can read,
     // a config file with a key that does not exist — reaches the user as one line naming the
@@ -61,6 +79,13 @@ try {
         process.stdout.write(USAGE);
         process.exit(0);
     }
+    // After `--help`, which answers the wider question, and before any command has begun: a
+    // `tarmac install --version` that printed a plan and then waited for a typed word would be
+    // a one-line question that hangs a script. Bare, so something other than a person can read it.
+    if (args.version) {
+        process.stdout.write(`${version()}\n`);
+        process.exit(0);
+    }
     if (args.command === 'install' || args.command === 'uninstall') {
         const home = args.home ?? os.homedir();
         // The plan is computed first and printed whole: every refusal this operation has in it

package/dist/render.js

@@ -988,7 +988,19 @@ export function renderPage(fleet, view = 'table') {
        word. min-width:0 for the same reason the berths carry it: a flex item's automatic
        minimum is its min-content width, which without this is the whole unbroken string. */
     td[data-label="Project"] .v { order:1; font-weight:600; min-width:0; overflow-wrap:anywhere; }
-    td[data-label="Session"] .v { order:2; flex:1 1 0; min-width:0; color:var(--dim);
+    /* The basis is auto and not 0, which is what decides whether the name breaks INSIDE
+       itself. A basis of 0 puts it on the first line however little is left of one: at 390px
+       beside a 40-character project that is 44.6px of column, a session id cut across two
+       lines, the pill dropped alone underneath and a 63px strip standing at 105.7 — on
+       exactly the fleets whose checkout names are long. Its own width is the floor it wraps
+       at instead: beside the project where it fits, on the next line whole where it does not.
+       That floor is a trade, not a free fix: a name longer than one full line keeps a line of
+       its own at EVERY width, where a basis of 0 let it compress back beside the project as
+       the screen widened. The accepted side of #108: never cut a name mid-word, at the price
+       of a taller strip for prompt-named agents.
+       min-width:0 is what still lets it shrink once it is the widest thing on a line of its
+       own, which is the wrap the rule above is written for. */
+    td[data-label="Session"] .v { order:2; flex:1 1 auto; min-width:0; color:var(--dim);
          white-space:normal; overflow-wrap:anywhere; }
     /* The third value that can arrive as one unbroken token, and the one the two rules above
        missed: a waiting reason is FREE TEXT, so "permission prompt: /Users/…/foo.ts" is a path
@@ -1321,12 +1333,20 @@ function pageScript(view) {
   }
 
   function two(n) { return (n < 10 ? '0' : '') + n; }
-  function hhmm(t) { var d = new Date(t); return two(d.getHours()) + ':' + two(d.getMinutes()); }
+  // One page, one clock, and it is the one the summary line already dates the fleet on: an ISO
+  // instant in UTC. Spelled on the machine's own clock, these minutes and that stamp are the
+  // same fleet apparently living in two time zones, the first time anything shows both — an
+  // export, a log line, a screenshot with the header in it. Every minute below carries UTC
+  // where a reader meets it, because an unlabelled one reads as the reader's own clock and is
+  // the same lie facing the other way.
+  function hhmm(t) { var d = new Date(t); return two(d.getUTCHours()) + ':' + two(d.getUTCMinutes()); }
 
   // A day-long ring can straddle one midnight, and "09:14 – 08:59" reads as a span running
-  // backwards until the older edge says which day it is.
+  // backwards until the older edge says which day it is. Which midnight is UTC's, like the
+  // minutes it separates: counted otherwise, "yesterday" turns up between two minutes of one
+  // UTC day and goes missing across the midnight it exists for.
   function edge(t, ref) {
-    return hhmm(t) + (new Date(t).getDate() === new Date(ref).getDate() ? '' : ' yesterday');
+    return hhmm(t) + (new Date(t).getUTCDate() === new Date(ref).getUTCDate() ? '' : ' yesterday');
   }
 
   // What the range covers, in the record's own terms. Never "a day": that is the size of the
@@ -1338,13 +1358,13 @@ function pageScript(view) {
       // this was the one branch that threw that away: ten hours of a collector that could not
       // run read exactly like a serve thirty seconds old.
       return record.missed
-        ? 'Nothing recorded — this serve started at ' + hhmm(record.since) + ' and '
+        ? 'Nothing recorded — this serve started at ' + hhmm(record.since) + ' UTC and '
           + record.missed + ' minute' + (record.missed === 1 ? '' : 's') + ' were due and never read.'
-        : 'Nothing recorded yet — this serve started at ' + hhmm(record.since)
+        : 'Nothing recorded yet — this serve started at ' + hhmm(record.since) + ' UTC'
           + ' and takes a reading every ' + Math.round(record.cadence / 1000) + 's.';
     }
     var last = record.samples[n - 1].t;
-    return 'Covering ' + edge(record.since, last) + ' – ' + hhmm(last)
+    return 'Covering ' + edge(record.since, last) + ' – ' + hhmm(last) + ' UTC'
       // Not "when the page loaded": the record is asked for again when a tab that has been
       // away comes back, so the sentence names the last time this page asked rather than a
       // moment it may be hours past.
@@ -1579,8 +1599,9 @@ function pageScript(view) {
     scrub.value = String(i);
     // The handle's own value is an index, so a reader who cannot see the banner would be read
     // "3" while the fleet on screen is three hours old. The minute travels with the handle.
-    scrub.setAttribute('aria-valuetext', hhmm(s.t));
-    atEl.textContent = hhmm(s.t);
+    var minute = hhmm(s.t) + ' UTC';
+    scrub.setAttribute('aria-valuetext', minute);
+    atEl.textContent = minute;
     rmeta.textContent = metaOf(s);
     rmap.innerHTML = nodesOf(s);
     // The account of that minute, in the place the live pair occupies — which the body class

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",