@adrrr/tarmac 0.7.0 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ documented surfaces only, never an internal format.
        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) ·
+[Quickstart](#quickstart) · [The map](#the-map) · [The curves](#the-curves) · [Install](#install) ·
 [Configuration](#configuration) · [Commands](docs/MANUAL.md#commands-and-options) ·
 [Manual](docs/MANUAL.md) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/adrrr/tarmac/issues)
 
@@ -79,10 +79,11 @@ listening rules are [there too](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 drawn as nodes: one per session, the
+The tabs in the header swap 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.
+views render the same reading into the same fragment, so they can never disagree. A third tab
+draws the record rather than the reading: see [the curves](#the-curves) below.
 
 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
@@ -108,6 +109,26 @@ filed as `idle`, and raises one warning above the fleet naming it. The page is J
 underneath: `GET /api/fleet` and `GET /api/history` serve exactly what the map draws. Details
 are in [the manual](docs/MANUAL.md#the-map).
 
+## The curves
+
+The third tab draws what moved rather than what is: context per session, cost per project, and
+the account's two windows, over the last 24 hours out of the ring or over 7 and 30 days out of
+the journal, if you keep one. `<canvas>` and the page's own script, no library.
+
+A context line breaks where its session did, so a recycle at three in the morning reads as a
+break and not as a cliff, and a minute nobody read is a hole rather than a fall to zero. The
+lines that gained fifteen points or more in the last three hours are drawn full and labelled,
+which is the question the chart exists for: what has to be recycled tonight. Cost is stacked
+bars, built in a fixed order so a project keeps its place in the column all week, with the
+legend sorted by what each one spent. Quota is the seven-day line over the five-hour window,
+and a turnover the serve slept through is drawn faint and marked `≈` rather than as a firm line
+through a minute nobody measured.
+
+No hover: a tap puts a cursor on a chart and every number on it becomes that moment's, with
+`Back to now` to undo it. Without `history.days` the two longer ranges are greyed out and the
+view says which key turns them on. Details are in
+[the manual](docs/MANUAL.md#the-curves).
+
 ## Install
 
 `install` changes the `statusLine` key of `~/.claude/settings.json`, and never on your
@@ -146,9 +167,9 @@ and tarmac keeps reporting. The full state-by-state table is in
 
 ## Configuration
 
-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.
+The settings below are judgement calls, so they are yours: three numbers, the hosts `serve`
+answers to behind a reverse proxy, and whether it keeps a journal on disk. Everything else is
+deliberately not configurable, and all of it works with no configuration at all.
 
 | Setting | Flag | Default |
 |---|---|---|
@@ -156,6 +177,7 @@ configurable, and all of it works with no configuration at all.
 | 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 |
+| journal retention | `--history-days 30`, on `serve` | none, so nothing is written to disk |
 
 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
@@ -171,10 +193,25 @@ and what would have worked. Spellings, edge cases and the two health fields
   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
-  it is written down.
+- **Nothing on disk unless you ask for it.** `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. Nothing of it is written down, and that is what every install that never asked
+  otherwise does.
+
+  Set `history.days` and `serve` also appends one JSON line a minute to
+  `~/.local/state/tarmac/history/YYYY-MM-DD.jsonl`, beside the snapshots. The line is the same
+  record the page replays, minus one field: per session, the session id, the project basename,
+  the kind, the state, the context percentage and the cost, plus the account's rate limits. No
+  session name, no working directory, and not the reason a waiting session gave, which is free
+  text off `claude agents --json` and does not belong in a file that outlives the process.
+  About 2 MB a day at eight sessions. Files older than the retention you set are removed when
+  `serve` starts and once a day after that, and writing stops altogether at 256 MB, which is
+  not a number you can raise. `serve` names the retention, the cap and the directory in its
+  settings block, before it serves anything. `GET /api/history?range=7d`, or `30d`, reads those
+  files back aggregated by hour and by project, where the same route with no range is the last
+  24 hours out of memory, and the third tab of the page draws both. To stop it, unset the
+  retention wherever you set it; to erase what is there, remove the directory.
 - **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, parseTrustHost } from './config.js';
+import { parseHistoryDays, 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
@@ -13,6 +13,7 @@ const OPTIONS = {
     '--stale-after': 'staleAfter',
     '--snapshots-dir': 'snapshotsDir',
     '--trust-host': 'trustHost',
+    '--history-days': 'historyDays',
     '--home': 'home',
     '--claude-bin': 'claudeBin',
     '--json': 'json',
@@ -39,7 +40,7 @@ const LISTS = new Set(['trustHost']);
  */
 const ACCEPTS = {
     list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help', 'version']),
-    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'home', 'claudeBin', 'help', 'version']),
+    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'historyDays', 'home', 'claudeBin', 'help', 'version']),
     install: new Set(['home', 'yes', 'help', 'version']),
     uninstall: new Set(['home', 'yes', 'help', 'version']),
     help: new Set(['help', 'version']),
@@ -60,7 +61,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, version: false };
+    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, trustHost: [], historyDays: null, 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]))
@@ -90,6 +91,11 @@ export function parseArgs(argv) {
             // in the same words wherever it was set.
             out.port = parsePort(value, '--port');
         }
+        else if (key === 'historyDays') {
+            // Same validator the environment and the config file go through, so a retention is
+            // refused in the same words wherever it was set.
+            out.historyDays = parseHistoryDays(value, '--history-days');
+        }
         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.

package/dist/cli.js

@@ -17,6 +17,7 @@ import { createFleetServer, listenFleetServer } from './server.js';
 import { install, uninstall, paths, planInstall, planUninstall, installedSnapshotsDir, wrapperIsOurs } from './install.js';
 import { confirmTyped } from './prompt.js';
 import { reapOrphanedTemps } from './reap.js';
+import { acquireJournalLock, createHistoryStore, historyDirFor } from './history-store.js';
 import { renderPlan, renderSettings, renderTable, restoreMeaning, servingLine } from './render.js';
 import { runWatch } from './watch.js';
 const USAGE = `tarmac — fleet observability for Claude Code
@@ -25,13 +26,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] [--trust-host HOST]
+                    [--claude-bin PATH] [--trust-host HOST] [--history-days N]
         local dashboard
   tarmac install    [--home DIR] [--yes]
         chain the statusline
   tarmac uninstall  [--home DIR] [--yes]
         restore the statusline exactly
 
+  --help           print this text and exit — on any command
   --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)
@@ -48,11 +50,17 @@ const USAGE = `tarmac — fleet observability for Claude Code
                    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
+  --history-days   keep a fleet journal for N days, in a directory beside the snapshots
+                   (default: none, and nothing is written to disk). On \`serve\` only,
+                   which is the command that samples: one JSON line a minute, no session
+                   name and no working directory, about 2 MB a day at eight sessions,
+                   and writing stops at 256 MB whatever N says
 
-  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.
+  Those five settings can also be set, in decreasing order of precedence, by the
+  environment (TARMAC_STALE_AFTER, TARMAC_PORT, TARMAC_SNAPSHOTS_DIR, TARMAC_TRUST_HOST,
+  TARMAC_HISTORY_DAYS) and by <home>/.claude/tarmac/config.json ({"staleAfterMs": …,
+  "port": …, "snapshotsDir": …, "trustHosts": […], "history": {"days": …}}). \`serve\`
+  prints which one won.
 `;
 /**
  * What this build calls itself, read from the `package.json` that ships beside it — the one
@@ -130,7 +138,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, trustHosts: args.trustHost },
+            flags: { staleAfter: args.staleAfter, port: args.port, snapshotsDir: args.snapshotsDir, trustHosts: args.trustHost, historyDays: args.historyDays },
             env: process.env,
             file: readConfigFile(p.config),
             // The installed wrapper's own path, when there is one: the default is where the
@@ -141,11 +149,51 @@ try {
         const snapshotsDir = config.snapshotsDir.value;
         const staleAfterMs = config.staleAfterMs.value;
         if (args.command === 'serve') {
+            // Beside the snapshots, never among them: `reap.ts`, the wrapper's own sweep and the
+            // legacy purge in `install.ts` all decide by name inside that directory.
+            const historyDir = historyDirFor(snapshotsDir);
             // Unattended for hours, so it opens by saying what it decided and on whose authority.
-            process.stdout.write(renderSettings(config, p.config));
-            // The one place the CLI deletes anything: temp files its own wrapper left behind when a
-            // terminal died mid-write. Best effort, and it says what it did rather than doing it
-            // quietly — this is the user's directory.
+            process.stdout.write(renderSettings(config, p.config, historyDir));
+            // One journal, one owner (#133). The retention is a property of the DIRECTORY and the
+            // process applying it was whichever `serve` started last, so a `--history-days 1` run to
+            // try the setting out swept the thirty days another serve was keeping. A second serve
+            // journals nothing now, and serves everything else exactly as it did.
+            const days = config.historyDays.value;
+            const { lock, heldBy } = days === null ? { lock: null, heldBy: null } : acquireJournalLock({ dir: historyDir });
+            // On stdout, under the settings block it corrects: that block has just named a retention
+            // and a directory, and a reader piping it must not be left holding the half of it that
+            // did not happen. Same reason `serve` says on stdout which port it walked to.
+            if (days !== null && lock === null) {
+                const why = heldBy === null ? `could not take the journal lock in ${historyDir}` : `pid ${heldBy} holds the journal in ${historyDir}`;
+                console.log(`tarmac: ${why}, so this serve keeps no journal`);
+            }
+            // Given back on the way out, signals included: Node's default for each of these ends the
+            // process without running an exit hook, so a Ctrl-C would leave the lock behind and the
+            // next serve would wait five minutes for its heartbeat to go quiet. SIGHUP is in the list
+            // because closing the terminal, or losing the ssh session, is how a foreground serve
+            // usually dies.
+            //
+            // Each handler releases and then re-raises, rather than exiting with a number: a serve
+            // that answered a supervisor `exited 143` where every other serve answers `killed by
+            // SIGTERM` would have made the journal visible to systemd and launchd, which know nothing
+            // about it. Nothing about how this process ends may depend on a file in a directory.
+            if (lock !== null) {
+                process.on('exit', () => lock.release());
+                for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+                    // Removing THIS handler rather than every handler for the signal: the next hand to
+                    // register one here would otherwise be dropped by ours, in silence.
+                    const bye = () => {
+                        lock.release();
+                        process.off(signal, bye);
+                        process.kill(process.pid, signal);
+                    };
+                    process.on(signal, bye);
+                }
+            }
+            // Temp files its own wrapper left behind when a terminal died mid-write. Best effort, and
+            // it says what it did rather than doing it quietly, this being the user's directory. It
+            // is no longer the only deletion a `serve` makes: a journal that was asked for applies
+            // its retention on `listening`, and says that too. Nothing else here removes anything.
             const { reaped, failed } = reapOrphanedTemps(snapshotsDir);
             if (reaped > 0)
                 console.log(`tarmac: reaped ${reaped} orphaned snapshot temp file(s)`);
@@ -154,6 +202,10 @@ try {
             const server = createFleetServer({
                 collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null }),
                 trustedHosts: config.trustHosts.value,
+                // No key anywhere is no store, which is no directory and no file: the default is that
+                // nothing of this fleet is written down, and it is the default that is the product.
+                // No lock is no store either, and for the same reason: no store, no sweep, no line.
+                store: days === null || lock === null ? null : createHistoryStore({ dir: historyDir, days, lock }),
             });
             // 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,6 +65,27 @@ function checkPort(n, label, shown = n) {
     }
     return n;
 }
+/**
+ * How many local days of fleet journal to keep on disk, today included.
+ *
+ * The one setting here whose absence is the product: with no `history` key there is no journal,
+ * which is what every install that never asked for one gets. So ZERO is refused rather than read
+ * as "off". It is the number a reader reaches for to mean off, and reading it that way would
+ * leave a file growing all day under a retention that keeps none of it. Off is the absence of
+ * the key, which is also what deleting it does: one way to stop, not two.
+ *
+ * @param label how the source spells this setting, so the refusal names the knob to turn
+ */
+export function parseHistoryDays(text, label) {
+    const trimmed = text.trim();
+    return checkHistoryDays(/^\d+$/.test(trimmed) ? Number(trimmed) : NaN, label, text);
+}
+function checkHistoryDays(n, label, shown = n) {
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+        throw new Error(`${label} must be a whole number of days, 1 or more, got: ${format(shown)}`);
+    }
+    return n;
+}
 /**
  * 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.
@@ -98,7 +119,7 @@ export function parseTrustHost(text, label) {
 }
 /** 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'];
+const KNOWN_KEYS = ['staleAfterMs', 'port', 'snapshotsDir', 'trustHosts', 'history'];
 /**
  * `~/.claude/tarmac/config.json`, if there is one.
  *
@@ -165,6 +186,23 @@ export function readConfigFile(file) {
             return parseTrustHost(h, where('trustHosts'));
         });
     }
+    if ('history' in body) {
+        const v = body.history;
+        if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+            throw new Error(`${where('history')} must be an object like {"days": 30}, got: ${format(v)}`);
+        }
+        const inner = v;
+        const unknownInner = Object.keys(inner).filter((k) => k !== 'days');
+        if (unknownInner.length > 0) {
+            throw new Error(`unknown key(s) in ${file}: ${unknownInner.map((k) => `history.${k}`).join(', ')} (the only key of history is days)`);
+        }
+        // An unfinished key, not an off switch. `"history": {}` reads as a setting the tool took
+        // and silently never applied, which is the one thing this module exists to prevent.
+        if (!('days' in inner)) {
+            throw new Error(`${where('history.days')} must be set to a whole number of days; remove the history key to keep nothing on disk`);
+        }
+        out.history = { days: checkHistoryDays(inner.days, where('history.days')) };
+    }
     return out;
 }
 /**
@@ -197,6 +235,7 @@ export function resolveConfig({ flags, env, file, defaultSnapshotsDir }) {
     // 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')));
+    const historyEnv = parseIfSet(env.TARMAC_HISTORY_DAYS, (v) => parseHistoryDays(v, 'TARMAC_HISTORY_DAYS'));
     return {
         staleAfterMs: flags.staleAfter !== null
             ? { value: parseDuration(flags.staleAfter, '--stale-after'), source: 'flag' }
@@ -229,6 +268,15 @@ export function resolveConfig({ flags, env, file, defaultSnapshotsDir }) {
                 : file.trustHosts !== undefined
                     ? { value: file.trustHosts, source: 'file' }
                     : { value: [], source: 'default' },
+        // The only default here that is not a number: no key anywhere means no journal, and that
+        // is the behaviour every install had before this setting existed.
+        historyDays: flags.historyDays !== null
+            ? { value: flags.historyDays, source: 'flag' }
+            : historyEnv !== null
+                ? { value: historyEnv, source: 'env' }
+                : file.history !== undefined
+                    ? { value: file.history.days, source: 'file' }
+                    : { value: null, source: 'default' },
     };
 }
 /**