@adrrr/tarmac 0.6.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)
 
@@ -45,30 +45,33 @@ atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 account  5h 17% resets in 2h 14m · 7d 42% resets in 3d 11h · as of 7m
 ```
 
-That is the table with the status line chained. The last line is the account's, not any
-session's: every row above spends from the same five-hour and seven-day
-[window](docs/MANUAL.md#the-accounts-two-windows), so it is printed once, dated like every
-other reading here, and `— no reading` rather than `0%` when no snapshot carried one.
+That is the table with the status line chained. The last line belongs to the account, not to
+any one session. Every row above spends from the same five-hour and seven-day
+[window](docs/MANUAL.md#the-accounts-two-windows), so it is printed once. It is dated like
+every other reading here, and it reads `— no reading` rather than `0%` when no snapshot
+carried one.
 
 With nothing installed, the same command still lists every session, its state and its uptime,
-straight from `claude agents --json`. The context column reads `— absent`, model, effort and
-cost fall to `—`, and the line under the table counts how many sessions are covered.
+straight from `claude agents --json`. The context column reads `— absent`. Model, effort and
+cost fall to `—`. The line under the table counts how many sessions are covered.
 
 Node ≥ 20. Zero runtime dependencies: no framework, no bundler, nothing to audit.
-`--help` works everywhere. An option handed to a command that does not read it is an error,
-not something quietly ignored. Every command, flag and route:
+`--help` and `--version` (`-v`) work everywhere. An option handed to a command that does not
+read it is an error, never something quietly ignored. Every command, flag and route is in
 [the manual](docs/MANUAL.md#commands-and-options).
 
 ## The map
 
-`tarmac serve` puts the same fleet in the browser: every session a row, ages that keep
-climbing, and a banner the moment a refresh fails instead of a table quietly going stale. It
-binds to loopback and refuses any request whose `Host` is not loopback, or that a browser
-marks as coming from another origin, so your cwd paths and costs never leave the machine. A
-client that sends no such mark, curl or a script, is left alone. Behind a reverse proxy, which
-presents a `Host` of its own, `--trust-host <name>` names the one to let through and says who
-that lets in: [the manual](docs/MANUAL.md#putting-it-behind-a-reverse-proxy). The listening
-rules: [the manual](docs/MANUAL.md#what-serve-listens-on).
+`tarmac serve` puts the same fleet in the browser. Every session is a row, the ages keep
+climbing, and a banner goes up the moment a refresh fails, so the table never goes stale in
+silence.
+
+It binds to loopback. It refuses any request whose `Host` is not loopback, and any request a
+browser marks as coming from another origin, so your cwd paths and costs never leave the
+machine. A client that sends no such mark, curl or a script, is left alone. A reverse proxy
+presents a `Host` of its own, so `--trust-host <name>` names the one to let through;
+[the manual](docs/MANUAL.md#putting-it-behind-a-reverse-proxy) says who that lets in. The
+listening rules are [there too](docs/MANUAL.md#what-serve-listens-on).
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/map-dark.png">
@@ -76,47 +79,68 @@ rules: [the manual](docs/MANUAL.md#what-serve-listens-on).
        alt="The tarmac map, live. Four framed groups, one per working directory and labelled with its project: beacon, holding a session halted on a permission prompt; harbor, holding a session busy with its context arc at 90% and a background agent docked under the cards of that frame as a strip named after its prompt; quay, reporting a status tarmac does not know; and atlas, idle at 36%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
 </picture>
 
-The tab in the header swaps the table for the same fleet as nodes: one per session, the arc
-its context, the shape by the name its state. A background agent has no terminal behind it to
-draw a frame with, so it gets a strip of text rather than a dial that could never fill. Both
-views render the same reading into the same fragment, so they can never disagree.
+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. 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. That is the whole
-of what the frame claims: these were read in the same directory. It is not a parentage.
-`claude agents --json` publishes nothing that ties an agent to whoever dispatched it, so no
-label, no position and no line inside a frame says one node asked for another. An agent whose
-directory matches no session gets a frame of its own rather than somebody else's.
+the sessions inside it as cards and the agents docked underneath as strips. A frame claims one
+thing and no more: these nodes were read in the same directory. `claude agents --json`
+publishes nothing that ties an agent to whoever dispatched it, so no label, no position and no
+line inside a frame says one node asked for another. An agent whose directory matches no
+session gets its own frame rather than somebody else's.
 
 Above the fleet are the account's five-hour and seven-day
-[gauges](docs/MANUAL.md#the-accounts-two-windows); under it a scrubber over the day this
-serve has seen. Drag it and the nodes render the fleet as it was at that minute, press play
-and the day walks past. Replayed, they are drawn flat and unframed: the record keeps a project
-name and never the directory it was read in, and a basename is not a directory. Two checkouts
-of `atlas` answer to the same word, so a frame drawn on it would claim a shared directory
-nobody can check.
+[gauges](docs/MANUAL.md#the-accounts-two-windows). Under it is a scrubber over the day this
+serve has seen. Drag it and the nodes render the fleet as it was at that minute. Press play
+and the day walks past. Replayed, the nodes are drawn flat and unframed. The record keeps a
+project name and never the directory it was read in, and a basename is not a directory. Two
+checkouts of `atlas` answer to the same word, so a frame drawn on it would claim a shared
+directory nobody can check.
 
 The map follows the rules the table follows. A reading past the freshness threshold is drawn
-thin, amber and dated. A percentage nobody measured is an empty dotted dial rather than a ring
-at zero. Where nothing was published at all, such as the strip of an agent the join found no
-snapshot for, nothing is drawn in its place, neither a dial nor a dash. A word
+thin, amber and dated. A percentage nobody measured is an empty dotted dial, never a ring at
+zero. Where nothing was published at all, such as the strip of an agent the join found no
+snapshot for, nothing is drawn in its place: no dial, no dash. A word
 `claude agents --json` printed that tarmac has no boolean for is shown as it came rather than
 filed as `idle`, and raises one warning above the fleet naming it. The page is JSON
 underneath: `GET /api/fleet` and `GET /api/history` serve exactly what the map draws. Details
-in [the manual](docs/MANUAL.md#the-map).
+are in [the manual](docs/MANUAL.md#the-map).
+
+## 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
 say-so alone. It prints the whole plan first, including the exact command that undoes it,
-then waits for a typed word. `y` is not an answer; scripts pass `--yes`, deliberately.
+then waits for a typed word. `y` is not an answer. Scripts pass `--yes`, deliberately.
 
 A status line you already had is wrapped, not replaced: its display stays byte-identical, and
 `uninstall` names which of its four restore modes ran. Two files land under `~/.claude/`, the
 wrapper and the `backup.json` that undoes it, and neither changes at runtime. The snapshots go
 to `~/.local/state/tarmac/snapshots` (`$XDG_STATE_HOME` when set), because `~/.claude` is a
-directory people commit. The plan, the restore modes and the cleanup of the layout that kept
-snapshots inside `.claude`:
+directory people commit. The plan, the restore modes and the cleanup of the old layout that
+kept snapshots inside `.claude` are in
 [the manual](docs/MANUAL.md#installing-safely-the-full-contract).
 
 ## Why it does not break
@@ -132,45 +156,62 @@ tarmac reads two things instead:
 | `claude agents --json` | which sessions exist, busy, idle or waiting on you, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
 | the status line payload | context %, model, effort, cost | the JSON Claude Code hands to your own `statusLine.command` on every frame. Observed, not published as a schema |
 
-That second line is the honest caveat. The real defence is not immunity, it is visible
-degradation. A missing measurement is never a confident `0`. It is an em dash that names which
-kind of missing it is: `absent` for a session no status line ever wrote for, `fresh` for one
-that has taken no turn yet, `drift` for a release that moved the payload out from under us. A
-stale reading keeps its value and gets dated with a `!`. A Claude Code build no fixture covers
-gets its version named *before* anything breaks, and tarmac keeps reporting. The full
-state-by-state table is in [the manual](docs/MANUAL.md#degradation-state-by-state).
+That second row is the honest caveat. tarmac does not promise the payload will hold still.
+It promises that a measurement it could not take never renders as a confident `0`. What you
+get instead is an em dash naming which kind of missing it is: `absent` for a session no status
+line ever wrote for, `fresh` for one that has taken no turn yet, `drift` for a release that
+moved the payload out from under us. A stale reading keeps its value and gets dated with a
+`!`. A Claude Code build no fixture covers gets its version named *before* anything breaks,
+and tarmac keeps reporting. The full state-by-state table is in
+[the manual](docs/MANUAL.md#degradation-state-by-state).
 
 ## Configuration
 
-Three numbers are opinions rather than truths, so all three are yours, and behind a reverse
-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 |
 |---|---|---|
 | freshness threshold | `--stale-after 90s` \| `15m` \| `2h` | `10m` |
 | port | `--port 8080` | `4477` |
 | snapshots dir (read side) | `--snapshots-dir DIR` | the wrapper's frozen path when installed, else the XDG state directory |
-| trusted hosts | `--trust-host HOST`, once per host | none — loopback only |
+| trusted hosts | `--trust-host HOST`, once per host | none, so loopback only |
+| 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
+Flag beats environment beats config file beats default, settled per setting. `serve` opens by
 printing each effective value and where it came from. Nothing is silently dropped or silently
 corrected. A value that will not parse stops the run and says what it got, where it came from,
 and what would have worked. Spellings, edge cases and the two health fields
-`tarmac list --json` reports: [the manual](docs/MANUAL.md#configuration).
+`tarmac list --json` reports are in [the manual](docs/MANUAL.md#configuration).
 
 ## What it deliberately does not do
 
 - **No inferred "waiting for you".** `agents --json` reports `waiting` with a reason, such as
   a permission prompt or an open dialog, and tarmac draws exactly that, in the table and on
-  the map. What it will not do is guess at the rest: a session that asked you a question in prose
-  still reports `idle`, and the only way to know better is to read a transcript, which is
-  the one thing this tool will not do. The signal is as good as its source, and no better.
-- **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.
+  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.
+- **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.
 
@@ -182,9 +223,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, 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,14 +13,20 @@ const OPTIONS = {
     '--stale-after': 'staleAfter',
     '--snapshots-dir': 'snapshotsDir',
     '--trust-host': 'trustHost',
+    '--history-days': 'historyDays',
     '--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']);
 /**
@@ -29,14 +35,15 @@ const LISTS = new Set(['trustHost']);
  * one level down — `tarmac serve --json` parsed cleanly and changed nothing, and from the
  * outside that is indistinguishable from a server that decided to answer HTML anyway.
  *
- * `help` is in every set on purpose: `--help` is answerable whatever else was typed.
+ * `help` is in every set on purpose: `--help` is answerable whatever else was typed, and
+ * `version` is there for the same reason — what build this is does not depend on the verb.
  */
 const ACCEPTS = {
-    list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help']),
-    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'home', 'claudeBin', 'help']),
-    install: new Set(['home', 'yes', 'help']),
-    uninstall: new Set(['home', 'yes', 'help']),
-    help: new Set(['help']),
+    list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help', 'version']),
+    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'historyDays', 'home', 'claudeBin', 'help', 'version']),
+    install: new Set(['home', 'yes', 'help', 'version']),
+    uninstall: new Set(['home', 'yes', 'help', 'version']),
+    help: new Set(['help', 'version']),
 };
 /** The commands a misplaced flag would have been right on — an error that points somewhere. */
 function ownersOf(key) {
@@ -54,7 +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 };
+    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]))
@@ -84,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

@@ -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';
@@ -16,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
@@ -24,13 +26,15 @@ 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)
   --yes            skip the typed confirmation — required when stdin is not a terminal
@@ -46,12 +50,34 @@ 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
+ * file npm puts in every tarball whatever `files` says, and the only place the number is
+ * written down. `dist/cli.js` sits one directory in exactly as `src/cli.ts` does, so a single
+ * relative path answers for the published CLI and for the suite, which runs the source.
+ *
+ * A version it could not read is not a version: rather than print an "unknown" nobody can act
+ * on, this throws and leaves through the same catch as every other refusal here.
+ */
+function version() {
+    const at = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(at, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version === '')
+        throw new Error(`${at.href} carries no version`);
+    return pkg.version;
+}
 try {
     // Parsing is inside the try so that a refusal — a typo'd flag, a duration nobody can read,
     // a config file with a key that does not exist — reaches the user as one line naming the
@@ -61,6 +87,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
@@ -105,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
@@ -116,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)`);
@@ -129,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' },
     };
 }
 /**