@adrrr/tarmac 0.5.0 → 0.7.0

package/README.md

@@ -6,14 +6,14 @@
 ![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 —
+**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. It reads
 documented surfaces only, never an internal format.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/replay-dark.gif">
   <img src="docs/media/replay-light.gif" width="1100"
-       alt="The tarmac map, live and then replayed. It opens on the live fleet, whose nodes are grouped into a frame per working directory, each labelled with its project. As the scrubber is dragged the frames give way to the flat record — sessions drawn as dials, each arc a context window, background agents as strips of text — with the account's five-hour and seven-day gauges above them. Sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
+       alt="The tarmac map, live and then replayed. It opens on the live fleet, whose nodes are grouped into a frame per working directory, each labelled with its project. As the scrubber is dragged the frames give way to the flat record: sessions drawn as dials, each arc a context window, background agents as strips of text, with the account's five-hour and seven-day gauges above them. Sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
 </picture>
 
 [Quickstart](#quickstart) · [The map](#the-map) · [Install](#install) ·
@@ -42,127 +42,139 @@ atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 ! 3 reading(s) marked "!" are older than 10m (--stale-after)
 
 4 sessions · 2 busy · $109.35
+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. 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.
+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.
 
-Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing to audit.
-`--help` works everywhere, and an option handed to a command that does not read it is an
-**error**, not something quietly ignored. Every command, flag and route:
+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 `—`. The line under the table counts how many sessions are covered.
+
+Node ≥ 20. Zero runtime dependencies: no framework, no bundler, nothing to audit.
+`--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: your cwd paths and costs never leave the machine. A client that
-sends no such mark — curl, a script — is left alone. 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">
   <img src="docs/media/map-light.png" width="1100"
-       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.">
+       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 is a strip of text rather than a dial that could never fill. It is
-the same reading in the same fragment, so the two views can never disagree.
+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 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. 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.
-
-The rules the table follows, the map 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, and where nothing was published at all — 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
+[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, 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
-quietly filed as `idle` — and raises one warning above the fleet naming it. The page is JSON
+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 —
-and waits for a **typed word** (`y` is not an answer; scripts pass `--yes`, deliberately).
+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.
 
-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`:
-[the manual](docs/MANUAL.md#installing-safely--the-full-contract).
+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 old layout that
+kept snapshots inside `.claude` are in
+[the manual](docs/MANUAL.md#installing-safely-the-full-contract).
 
 ## Why it does not break
 
 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.
+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, 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 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 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 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, not truths, so all three are yours; everything else is
-deliberately not configurable, and all of it works with no configuration at all.
+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.
 
 | Setting | Flag | Default |
 |---|---|---|
 | 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, 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 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).
+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 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 —
-  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 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. 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 — a
-  record that reaches no further back than the serve that took it, and goes when it goes.
-  None of it is written down.
+  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
+  it is written down.
 - **No Windows.** The generated wrapper is POSIX `sh`.
 - **No remote fleets.** It watches the machine it runs on.
 
@@ -174,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

@@ -3,7 +3,7 @@
 //
 // Unknown options and unknown commands are ERRORS. A typo silently ignored is how someone
 // ends up believing they pointed tarmac at a directory it never read.
-import { parsePort } from './config.js';
+import { parsePort, parseTrustHost } from './config.js';
 const COMMANDS = new Set(['list', 'serve', 'install', 'uninstall', 'help']);
 // `| undefined` is load-bearing, not decoration: without it the compiler types the lookup
 // below as always-present and the `if (!key) throw` guard reads as dead code — which is how
@@ -12,28 +12,37 @@ const OPTIONS = {
     '--port': 'port',
     '--stale-after': 'staleAfter',
     '--snapshots-dir': 'snapshotsDir',
+    '--trust-host': 'trustHost',
     '--home': 'home',
     '--claude-bin': 'claudeBin',
     '--json': 'json',
     '--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']);
 /**
  * Which options each command really reads. The doc-comment above refuses a flag nobody
  * implements; this refuses a flag THIS command does not implement, which is the same defect
  * 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', '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) {
@@ -51,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, 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]))
@@ -81,6 +90,11 @@ export function parseArgs(argv) {
             // in the same words wherever it was set.
             out.port = parsePort(value, '--port');
         }
+        else if (LISTS.has(key)) {
+            // Same rule, for the same reason — and the value is kept as the guard will compare it,
+            // so what `serve` prints on startup is what it will actually match against.
+            out[key].push(parseTrustHost(value, flag));
+        }
         else {
             out[key] = value;
         }

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';
@@ -24,13 +25,14 @@ const USAGE = `tarmac — fleet observability for Claude Code
                     [--claude-bin PATH] [--json] [--watch]
         one-shot fleet table — with --watch, redrawn every 5s until ^C
   tarmac serve      [--home DIR] [--port N] [--stale-after D] [--snapshots-dir DIR]
-                    [--claude-bin PATH]
+                    [--claude-bin PATH] [--trust-host HOST]
         local dashboard
   tarmac install    [--home DIR] [--yes]
         chain the statusline
   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
@@ -42,12 +44,32 @@ const USAGE = `tarmac — fleet observability for Claude Code
                    (default: $XDG_STATE_HOME/tarmac/snapshots, or
                    <home>/.local/state/tarmac/snapshots)
   --claude-bin     path to the claude CLI (default: claude)
+  --trust-host     a Host the dashboard also answers to, besides loopback — repeat it
+                   once per host (default: none). For a reverse proxy: give the name
+                   your browser shows, without the port, and remember that whoever can
+                   reach that name can read this fleet
 
-  Those three settings can also be set, in decreasing order of precedence, by the
-  environment (TARMAC_STALE_AFTER, TARMAC_PORT, TARMAC_SNAPSHOTS_DIR) and by
-  <home>/.claude/tarmac/config.json ({"staleAfterMs": …, "port": …, "snapshotsDir": …}).
-  \`serve\` prints which one won.
+  Those four settings can also be set, in decreasing order of precedence, by the
+  environment (TARMAC_STALE_AFTER, TARMAC_PORT, TARMAC_SNAPSHOTS_DIR, TARMAC_TRUST_HOST)
+  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
@@ -57,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
@@ -101,7 +130,7 @@ try {
         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 },
+            flags: { staleAfter: args.staleAfter, port: args.port, snapshotsDir: args.snapshotsDir, trustHosts: args.trustHost },
             env: process.env,
             file: readConfigFile(p.config),
             // The installed wrapper's own path, when there is one: the default is where the
@@ -124,6 +153,7 @@ try {
                 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, installed: frozen !== null }),
+                trustedHosts: config.trustHosts.value,
             });
             // 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

package/dist/config.js

@@ -65,7 +65,40 @@ function checkPort(n, label, shown = n) {
     }
     return n;
 }
-const KNOWN_KEYS = ['staleAfterMs', 'port', 'snapshotsDir'];
+/**
+ * The name out of a `Host` header, or out of a setting that has to match one: the port
+ * dropped, the brackets of an IPv6 literal dropped with it.
+ *
+ * Shared with the server's guard so that BOTH sides of that comparison are cut the same way.
+ * A normaliser written twice is a guard with two definitions of the same name.
+ */
+export const hostName = (host) => host.replace(/:\d+$/, '').replace(/^\[|\]$/g, '');
+/**
+ * A host `serve` will answer to besides loopback. Refuses everything that is not a name a
+ * `Host` header can carry — a scheme, a path, a wildcard, an IPv6 literal, an empty string —
+ * because each of those is accepted at the command line, printed on startup, and then matches
+ * nothing at all: a setting the tool appears to have taken and silently never applies.
+ *
+ * The port is DROPPED rather than refused, and the drop is visible in what `serve` prints. A
+ * proxy presents `name:8443` on one setup and a bare `name` on 443, and a list that matched
+ * the port would refuse half the setups it was typed for. It costs nothing: the port in a
+ * `Host` header is chosen by whoever sends it, so it never barred anybody.
+ *
+ * @param label how the source spells this setting, so the refusal names the knob to turn
+ */
+export function parseTrustHost(text, label) {
+    // Lowered because host names are case-insensitive and browsers send them lowered — a 403
+    // over a capital would be a setting typed, accepted, and never matched. It gives nothing
+    // away: the name still has to be the one the reader wrote down, character for character.
+    const name = hostName(text.trim()).toLowerCase();
+    if (!HOST_NAME.test(name)) {
+        throw new Error(`${label} must be a host name like example.ts.net — no scheme, no path, no wildcard, got: ${format(text)}`);
+    }
+    return name;
+}
+/** Letters, digits, dots and dashes, starting and ending on one that is not a dash or a dot. */
+const HOST_NAME = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+const KNOWN_KEYS = ['staleAfterMs', 'port', 'snapshotsDir', 'trustHosts'];
 /**
  * `~/.claude/tarmac/config.json`, if there is one.
  *
@@ -118,6 +151,20 @@ export function readConfigFile(file) {
         }
         out.snapshotsDir = v;
     }
+    if ('trustHosts' in body) {
+        const v = body.trustHosts;
+        if (!Array.isArray(v)) {
+            throw new Error(`${where('trustHosts')} must be an array of host names, got: ${format(v)}`);
+        }
+        out.trustHosts = v.map((h) => {
+            if (typeof h !== 'string') {
+                throw new Error(`${where('trustHosts')} must be an array of host names, got: ${format(h)}`);
+            }
+            // The same parser the flag and the environment go through: a host is refused, and kept,
+            // in the same words wherever it was written down.
+            return parseTrustHost(h, where('trustHosts'));
+        });
+    }
     return out;
 }
 /**
@@ -147,6 +194,9 @@ export function resolveConfig({ flags, env, file, defaultSnapshotsDir }) {
     const staleAfterEnv = parseIfSet(env.TARMAC_STALE_AFTER, (v) => parseDuration(v, 'TARMAC_STALE_AFTER'));
     const portEnv = parseIfSet(env.TARMAC_PORT, (v) => parsePort(v, 'TARMAC_PORT'));
     const dirEnv = read(env.TARMAC_SNAPSHOTS_DIR);
+    // Comma-separated, which a host name cannot contain — so the list needs no quoting rule of
+    // its own, and an empty item between two commas is refused rather than skipped.
+    const trustEnv = parseIfSet(env.TARMAC_TRUST_HOST, (v) => v.split(',').map((h) => parseTrustHost(h, 'TARMAC_TRUST_HOST')));
     return {
         staleAfterMs: flags.staleAfter !== null
             ? { value: parseDuration(flags.staleAfter, '--stale-after'), source: 'flag' }
@@ -169,6 +219,16 @@ export function resolveConfig({ flags, env, file, defaultSnapshotsDir }) {
                 : file.snapshotsDir !== undefined
                     ? { value: file.snapshotsDir, source: 'file' }
                     : { value: defaultSnapshotsDir, source: 'default' },
+        // The winning rung is the WHOLE list, like every other setting here. Adding the four
+        // together would leave nobody able to narrow, for one run, a list a config file widened —
+        // and this is the one setting where widening is the whole of the risk.
+        trustHosts: flags.trustHosts.length > 0
+            ? { value: flags.trustHosts, source: 'flag' }
+            : trustEnv !== null
+                ? { value: trustEnv, source: 'env' }
+                : file.trustHosts !== undefined
+                    ? { value: file.trustHosts, source: 'file' }
+                    : { value: [], source: 'default' },
     };
 }
 /**

package/dist/fleet.js

@@ -12,6 +12,7 @@
 // whose clock floats dies quietly the day it crosses a threshold.
 import path from 'node:path';
 import { DEFAULT_STALE_AFTER_MS } from './config.js';
+import { measured, windowsApart } from './limits.js';
 import { guardVersions } from './schema.js';
 import { isWaiting } from './sessions.js';
 import { SID_NAME } from './wrapper.js';
@@ -156,9 +157,15 @@ export function busyOnStaleFleet(rows) {
  * 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.
+ * rows normally 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.
+ *
+ * "Normally", because one thing can make that rule wrong, and it is why the count travels with
+ * the winner: readings that name different resets are not one allowance seen twice (see
+ * `windowsApart`). The freshest is still what gets drawn — there is nothing better to draw —
+ * but how many readings it speaks for, and how many describe some other window, go out with it
+ * so that no surface can present a picked winner as the fleet's one account.
  *
  * 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
@@ -169,17 +176,69 @@ export function busyOnStaleFleet(rows) {
  * 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)
+export function accountLimits(rows, now) {
+    // Dated readings only, and the same two exclusions on both sides of the question: a reading
+    // nothing can date cannot win on freshness, so it does not get to disagree either — it would
+    // put a number in the denominator that no surface is allowed to show.
+    const dated = rows
+        .filter((r) => r.rateLimits !== null && r.snapshotAgeMs !== null && r.snapshotAgeMs >= 0)
+        .map((r) => ({
+        rateLimits: r.rateLimits,
+        ageMs: r.snapshotAgeMs,
+        sessionId: r.sessionId,
+        measured: measured(r.rateLimits, now),
+    }));
+    if (dated.length === 0)
+        return null;
+    // Freshest AND measured, in that order. A session that has just started is guaranteed to be
+    // the youngest snapshot on the machine and is the likeliest to carry a window whose number
+    // has not been taken yet — freshest alone let it blank an account three other sessions were
+    // reporting. When nothing measured anything, the freshest still comes back, so the surfaces
+    // say "no reading" about a reading that exists rather than about no reading at all.
+    const readings = dated.filter((r) => r.measured);
+    const freshest = youngest(readings.length > 0 ? readings : dated);
+    // Every reading that measured something, the shown one included: it is compared with itself,
+    // which is the one comparison that can never come back apart. Skipping it explicitly was a
+    // line no test could ever have killed.
+    const apartWindows = new Set();
+    let apart = 0;
+    for (const r of readings) {
+        const windows = windowsApart(freshest.rateLimits, r.rateLimits, now);
+        if (windows.length === 0)
             continue;
-        if (freshest === null || r.snapshotAgeMs < freshest.ageMs) {
-            freshest = { rateLimits: r.rateLimits, ageMs: r.snapshotAgeMs };
-        }
+        apart += 1;
+        for (const w of windows)
+            apartWindows.add(w);
+    }
+    return {
+        rateLimits: freshest.rateLimits,
+        ageMs: freshest.ageMs,
+        readings: readings.length,
+        apart,
+        apartWindows: [...apartWindows],
+    };
+}
+/**
+ * The youngest reading, with a tie settled by session id rather than by the order the sources
+ * printed — the rule `preferred()` already applies to two snapshot files of the same age, for
+ * the same reason. `rows` is sorted on a key that is not total, so equal-aged readings keep
+ * whatever order `claude agents --json` emitted them in: without this, the number drawn AND the
+ * count published beside it move between two machines reading the same fleet. Which one it
+ * picks matters far less than that it picks the same one every time.
+ *
+ * An id nothing reported sorts last: it is the one value that cannot tell two readings apart.
+ */
+function youngest(readings) {
+    let best = readings[0];
+    for (const r of readings) {
+        if (r.ageMs < best.ageMs)
+            best = r;
+        else if (r.ageMs === best.ageMs && sortKey(r.sessionId) < sortKey(best.sessionId))
+            best = r;
     }
-    return freshest;
+    return best;
 }
+const sortKey = (sessionId) => (sessionId === null ? '￿' : sessionId);
 // Blocked on a human first, then busy, then unknown (it might be busy), then idle.
 //
 // Waiting leads because it is the only rank that is work for the reader: everything below it

package/dist/history.js

@@ -83,6 +83,6 @@ function sampleOf({ rows, health }) {
             costUsd: r.costUsd,
         })),
         // The reading, without its age: the ring keeps each reading and never how old it was.
-        rateLimits: accountLimits(rows)?.rateLimits ?? null,
+        rateLimits: accountLimits(rows, health.generatedAt)?.rateLimits ?? null,
     };
 }