@adrrr/tarmac 0.4.1 → 0.6.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 with the scrubber dragged across the record: five sessions drawn as dials, each arc a context window, the account's five-hour and seven-day gauges above them. As the handle moves, 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.">
+       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,112 +42,135 @@ 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 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.
 
-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 `—`, and 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:
 [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
+`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 does
-not mark same-origin: your cwd paths and costs never leave the machine. The listening rules:
-[the manual](docs/MANUAL.md#what-serve-listens-on).
+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).
 
 <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. Five nodes: beacon halted on a permission prompt, harbor busy with its context arc at 90%, a background agent named after its prompt beside it, quay reporting a status tarmac does not know, and atlas idle at 36%. 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. It is the same reading in the same fragment, so
-the two views can never disagree. 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 dials render
-the fleet as it was at that minute, press play and the day walks past.
-
-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 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 underneath: `GET /api/fleet` and `GET /api/history` serve exactly what
-the map draws. Details in
-[the manual](docs/MANUAL.md#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. 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.
+
+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 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
+`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).
 
 ## 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 layout that kept
+snapshots inside `.claude`:
+[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** |
+| 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 manual](docs/MANUAL.md#degradation-state-by-state).
+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).
 
 ## 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 are opinions rather than truths, so all three are yours, 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 path frozen into the installed wrapper, so the reader follows the writer |
+| 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 |
 
 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: [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
+- **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 the surface, and no better.
+  the one thing this tool will not do. The signal is as good as its source, and no better.
 - **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.
 

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,6 +12,7 @@ const OPTIONS = {
     '--port': 'port',
     '--stale-after': 'staleAfter',
     '--snapshots-dir': 'snapshotsDir',
+    '--trust-host': 'trustHost',
     '--home': 'home',
     '--claude-bin': 'claudeBin',
     '--json': 'json',
@@ -20,6 +21,8 @@ const OPTIONS = {
     '--help': 'help',
 };
 const FLAGS = new Set(['json', 'watch', 'yes', 'help']);
+/** 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
@@ -30,7 +33,7 @@ const FLAGS = new Set(['json', 'watch', 'yes', 'help']);
  */
 const ACCEPTS = {
     list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help']),
-    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'home', 'claudeBin', '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']),
@@ -51,7 +54,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 };
     let i = 0;
     if (argv[0] && !argv[0].startsWith('-')) {
         if (!COMMANDS.has(argv[0]))
@@ -81,6 +84,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

@@ -24,7 +24,7 @@ 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
@@ -42,11 +42,15 @@ 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.
 `;
 try {
     // Parsing is inside the try so that a refusal — a typo'd flag, a duration nobody can read,
@@ -101,7 +105,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 +128,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,
     };
 }

package/dist/limits.js

@@ -37,18 +37,15 @@ export const LIMIT_WINDOWS = [
 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;
+        const w = windowAt(rateLimits, key);
+        const has = w !== undefined && 'used_percentage' in w;
+        const v = w?.used_percentage;
         // 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 at = has ? resetOf(w) : null;
         const resetsInMs = at === null ? null : at * 1000 - now;
         return {
             key,
@@ -60,3 +57,76 @@ export function readLimits(rateLimits, now) {
         };
     });
 }
+/**
+ * The windows two readings of the account describe DIFFERENTLY, by key, in the order above —
+ * meaning two windows that are BOTH still open at `now` and are not the same window.
+ *
+ * A fleet holds one reading per session and only one of them can be drawn, so the question is
+ * what the others were. It is settled on the reset and not the percentage: `resets_at` is where
+ * a window ENDS, so two readings naming the same one are two ages of a single allowance — the
+ * freshest is the one still true, and the age beside it says the rest. Percentages that differ
+ * under one reset are that same number caught at two frames, the normal state of a fleet, and
+ * warning about it would be a warning on every poll.
+ *
+ * The openness test is the other half, and without it this cries wolf every five hours. A
+ * session that idles keeps the frame it last drew, and the five-hour window rolls over four or
+ * five times a day: an overnight snapshot names the window it was taken in, which has since
+ * ended. That is not two accounts, it is one reading being old — a fact the fleet already
+ * prints, as that row's age and as the `!` beside it — so a window whose boundary is behind
+ * `now` is left out of the comparison rather than raised as a disagreement.
+ *
+ * What survives both rules is the thing nothing else on either surface can say: two windows
+ * open AT THE SAME TIME, which one allowance cannot have. Whether that is two accounts signed
+ * in at once or something stranger is published nowhere tarmac reads, so this reports that the
+ * readings are apart and never why.
+ *
+ * A reading that dates no window is not a reading that dates one differently: an absent
+ * boundary is compared with nothing, exactly as an absent percentage is drawn as nothing. And
+ * a boundary further out than `RESET_HORIZON_MS` is refused here as it is refused a countdown —
+ * a reset fifty thousand years away is not a window this account is in.
+ *
+ * Known blind spot, and the reason it is left open: two accounts whose windows happen to end at
+ * the same second read as one here, and their percentages then differ in silence. The only
+ * thing that would catch it is treating a percentage as evidence — and the shape that takes is
+ * "the fresher reading is lower than the older one", which cannot be true of one allowance and
+ * would be a false alarm the day a number is ever revised downward. A missed collision costs a
+ * warning nobody sees; the other rule costs a warning nobody can act on, on a fleet where
+ * nothing is wrong.
+ */
+export function windowsApart(a, b, now) {
+    const apart = [];
+    for (const { key } of LIMIT_WINDOWS) {
+        const at = openBoundary(windowAt(a, key), now);
+        const bt = openBoundary(windowAt(b, key), now);
+        if (at !== null && bt !== null && at !== bt)
+            apart.push(key);
+    }
+    return apart;
+}
+/** Whether this reading yielded a number for either window — a reading that measured something. */
+export const measured = (rateLimits, now) => readLimits(rateLimits, now).some((g) => g.pct !== null);
+/**
+ * The epoch a window rolls over at, when that window is still OPEN at `now` — and `null` for
+ * one that has already rolled over, one nothing dates, and one dated beyond the horizon.
+ */
+function openBoundary(w, now) {
+    const at = resetOf(w);
+    if (at === null)
+        return null;
+    const inMs = at * 1000 - now;
+    return inMs > 0 && inMs <= RESET_HORIZON_MS ? at : null;
+}
+/**
+ * The window filed under `key`, or `undefined` when the payload carries nothing usable there.
+ *
+ * `rate_limits: []` and `rate_limits: "none"` are legal JSON and not a pair of windows, and
+ * neither may reach an index or a property read as something to look inside.
+ */
+function windowAt(rateLimits, key) {
+    if (rateLimits === null || rateLimits === undefined || typeof rateLimits !== 'object' || Array.isArray(rateLimits))
+        return undefined;
+    const w = rateLimits[key];
+    return w !== null && typeof w === 'object' && !Array.isArray(w) ? w : undefined;
+}
+/** The epoch a window rolls over at, or `null` when this reading does not name one. */
+const resetOf = (w) => w !== undefined && typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;