@adrrr/tarmac 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,10 @@
 # tarmac
 
+[![npm](https://img.shields.io/npm/v/%40adrrr%2Ftarmac)](https://www.npmjs.com/package/@adrrr/tarmac)
+![node](https://img.shields.io/node/v/%40adrrr%2Ftarmac)
+![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 —
 busy or idle, how full its context is, which model, what it has cost so far.
 
@@ -17,41 +22,6 @@ atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 4 sessions · 2 busy · $127.74
 ```
 
-## Why it does not break
-
-Every other way to watch a Claude Code fleet reads something Claude Code never promised
-would stay put: transcript files, terminal panes, undocumented paths. Those tools 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 or idle, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
-| the status line payload | context %, model, effort, cost | the JSON Claude Code hands to your own `statusLine.command` on every frame — **observed, not published as a schema** |
-
-That second line is the honest caveat, and it is the reason the real defence is not
-immunity, it is **visible degradation**. When a field moves, tarmac says the field moved.
-It never turns a measurement it could not take into a confident `0`.
-
-| What tarmac sees | What it shows |
-|---|---|
-| a percentage | the percentage |
-| the key is there but null | `— no turn yet` (a session that has not taken a turn) |
-| the key is gone or retyped | `— schema drift`, and a warning if it happened to every session |
-| no snapshot for a live session | `— not chained` |
-| a reading older than the threshold | the value, **dated** — a stale number is still true, of an earlier moment |
-| a status string it does not know | that string, never "idle" |
-| a snapshot directory it could not read | the errno, not "run tarmac install" |
-| a cost key that is absent | `—` for the row, and a total qualified by how many sessions really report one |
-| a Claude Code version no fixture covers | a notice naming that version — nothing blocked, nothing hidden |
-
-That last line is the smoke detector to the rest's alarm. The fields above were *observed*
-on the Claude Code builds frozen in `fixtures/`; when a session shows up on a build nobody
-has captured, tarmac says so **before** anything breaks, and keeps reporting. It reads the
-version off the payload itself, so it tells you about builds actually writing to your fleet
-— not about the `claude` on your PATH.
-
 ## Install
 
 ```bash
@@ -64,54 +34,43 @@ npx @adrrr/tarmac uninstall    # put your status line back, exactly
 
 Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing to audit.
 
-`install` and `uninstall` change a file your terminal reads on every frame, so neither runs
-on your say-so alone. Both print the plan first — the settings file, what `statusLine` says
-now, what it will say, the command that is being wrapped, and the exact command that undoes
-it — and then wait for you to **type the verb**:
+`install` changes one line of `~/.claude/settings.json`, and never on your say-so alone:
+it prints the full plan — including the exact command that undoes it — and waits for a
+**typed word** (`y` is not an answer; scripts pass `--yes`, deliberately). Your status
+line is wrapped, not replaced: the display stays byte-identical, and `uninstall` restores
+the original exactly.
 
-```
-tarmac install — your home
+## The dashboard
 
-  file             /Users/you/.claude/settings.json
-  statusLine now   ~/bin/my-line.sh
-  statusLine next  /Users/you/.claude/tarmac/statusline.sh
-  ↳ which calls    ~/bin/my-line.sh   (your display is unchanged)
-  undo             tarmac uninstall
+`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:
 
-Type "install" to proceed, anything else to abort:
+```
+tarmac serving http://127.0.0.1:4477
 ```
 
-`y` is not an answer, and neither is silence: with stdin not a terminal — a pipe, a CI job —
-tarmac refuses rather than read consent from an unanswerable prompt. Scripts pass `--yes`,
-deliberately and in writing.
-
-`--home DIR` points either command at another home; it selects a target, nothing more.
-**Pass the same `--home` to `list` and `serve`**, which default to yours: installing into
-`DIR` and then running a bare `list` reads a directory nothing was ever written to, and
-reports `statusline chained on 0/1 sessions` — a true statement about the wrong directory.
-
-`install` does not replace your status line, it **wraps** it: the wrapper drops the payload
-in `DIR/.claude/tarmac/snapshots/` and then calls whatever command was already configured,
-so your display is byte-identical. `uninstall` restores the original `settings.json` verbatim
-when you have not edited it since, and surgically (statusLine key only) when you have. If
-someone else has taken over the status line in the meantime, tarmac leaves it alone and
-tells you it restored nothing.
-
-The only thing tarmac ever deletes is its own litter: at `serve` start it removes temp
-files an interrupted wrapper left behind — over an hour old, and **signed**, meaning named
-`.tarmac-<session>.<pid>.tmp`, a name nothing but tarmac writes. It will not touch a file
-merely *shaped* like one of ours, because `.<name>.<pid>.tmp` is the temp-file convention of
-half the world. Your snapshots survive `uninstall`; they are your data.
-
-The corollary is a small one-time chore: temp files left by a **pre-signature build** of the
-wrapper (named `.<session>.<pid>.tmp`, without the `tarmac-` mark) are never reaped either —
-nothing in that name says we wrote it. If you ran one, clear them yourself, once, looking
-before you delete in case the directory has another writer:
+It binds to loopback and refuses any request whose `Host` is not loopback — your cwd
+paths and costs never leave the machine.
 
-```bash
-ls -l DIR/.claude/tarmac/snapshots/.*.tmp   # look first
-rm DIR/.claude/tarmac/snapshots/.*.tmp      # then remove what you recognise
-```
+## Why it does not break
+
+Every other way to watch a Claude Code fleet reads something Claude Code never promised
+would stay put: transcript files, terminal panes, undocumented paths. Those tools 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 or idle, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
+| the status line payload | context %, model, effort, cost | the JSON Claude Code hands to your own `statusLine.command` on every frame — **observed, not published as a schema** |
+
+That second line is the honest caveat, and it is the reason the real defence is not
+immunity, it is **visible degradation**: a null renders as `— no turn yet`, a moved field
+as `— schema drift`, a stale reading as the value **dated** — never a confident `0`. And
+when a session shows up on a Claude Code build no fixture covers, tarmac names that
+version *before* anything breaks, and keeps reporting. The full state-by-state table is
+in `docs/MANUAL.md`.
 
 ## Commands
 
@@ -123,105 +82,29 @@ rm DIR/.claude/tarmac/snapshots/.*.tmp      # then remove what you recognise
 | `tarmac uninstall` | restore it, and say which of the four restore modes ran | `--home`, `--yes` |
 
 `--help` works everywhere. An option handed to a command that does not read it is an
-**error**, not something quietly ignored — `tarmac serve --json` would otherwise parse
-cleanly and answer HTML anyway, which is indistinguishable from a bug.
-
-### Staying open
-
-Both live views owe you the same two facts, and neither is allowed to be quiet about them:
-**when the last good reading arrived**, and **whether the last attempt to refresh failed**.
-
-The page asks the server for `/live` every 5 seconds and swaps it in; the header carries an
-age that keeps climbing whether or not the refresh works, so numbers that have stopped moving
-cannot pass for live ones. When a poll fails, a banner names the reason and the table is
-framed off — the data stays, because it is still true of an earlier moment. `list --watch`
-does the same thing in the terminal, and prints `! refresh failing — <reason>` above a table
-it refuses to throw away.
-
-Three failures are handled by name, because each of them can otherwise look like health:
-
-- **A refusal** (`serve` is gone) — the banner names it on the next poll.
-- **An empty answer.** A 200 carrying nothing is not a fleet of nothing. Swapping it in would
-  blank the table and stamp it "updated 0s ago" with the dot still green, which is this tool's
-  own failure mode wearing its own colours. It counts as a failed refresh.
-- **No answer at all.** `fetch` has no timeout in any browser, so a server that accepts the
-  connection and goes quiet would leave the request pending forever. After 20 seconds — above
-  the collector's own 15s timeout, so a slow-but-healthy fleet always fails server-side first
-  with a real reason — the page gives up on it, says so, and asks again. An answer to a
-  request it already gave up on is discarded rather than allowed to overwrite a newer one.
-
-On a terminal `--watch` redraws once a second while it waits, so the age is never more than a
-second out of date and a hung read shows a counter that has visibly stopped. Piped, it writes
-one frame per read — there is no screen to keep current, and a frame a second is just noise.
-
-It is a poll and not a meta refresh or SSE, deliberately. A meta refresh cannot render its
-own failure: when `serve` dies the browser throws the page away and shows its own error page,
-taking the one useful fact with it. SSE would hold a socket per tab and drive
-`claude agents --json` from a server-side timer for readers whose laptop is asleep — with a
-poll, a hidden tab simply stops asking, and a waking one asks at once.
-
-Everything a reader interprets is rendered on the server. The browser owns two facts and no
-rules: re-deriving "a dash, never a zero" in page JavaScript would put a second copy of it
-where the test suite cannot reach.
+**error**, not something quietly ignored.
 
-## Configuration
-
-Three of tarmac's numbers are opinions, not truths, so all three are yours to set. Nothing
-else is configurable, and every one of them keeps working with no configuration at all.
-
-| Setting | What it decides | Default |
-|---|---|---|
-| freshness threshold | how old a reading may be before it is marked `!` | `10m` |
-| port | where `serve` listens | `4477` |
-| snapshots directory | where `list` and `serve` **read** payloads from | `<home>/.claude/tarmac/snapshots` |
+Both live views tell you **when the last good reading arrived** and **whether the last
+refresh failed** — ages keep climbing whether or not the refresh works, failures are
+banners with names, and a table is never thrown away for one. How each failure mode is
+kept from looking like health: `docs/MANUAL.md`.
 
-**Flag beats environment beats config file beats default**, settled per setting — a port
-pinned in the file and a threshold tightened for one run is the normal case.
-
-| Setting | Flag | Environment | `~/.claude/tarmac/config.json` |
-|---|---|---|---|
-| freshness | `--stale-after 90s` \| `15m` \| `2h` | `TARMAC_STALE_AFTER` (same spelling) | `"staleAfterMs": 90000` |
-| port | `--port 8080` | `TARMAC_PORT` | `"port": 8080` |
-| snapshots | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` |
-
-```json
-{ "staleAfterMs": 900000, "port": 8080 }
-```
-
-`tarmac serve` opens by printing each effective value **and which of the four sources it
-came from**, and the freshness threshold is named in every warning that puts a `!` on a
-reading — a mark whose threshold is invisible is one you cannot argue with.
-
-Nothing here is ever silently dropped. A duration that will not parse, a port out of range,
-a key that does not exist, a file that is not JSON, a file that exists but cannot be read —
-each one stops the run and says what it got, where it came from, and what would have worked.
-**Including the ones that lose**: a broken `TARMAC_STALE_AFTER` is refused even when a flag
-was going to beat it, so a stale variable in a shell profile cannot lurk until the day you
-drop the flag.
-
-```
-$ TARMAC_STALE_AFTER=soon tarmac list
-tarmac: TARMAC_STALE_AFTER must be a positive duration like 90s, 15m or 2h, got: soon
-```
-
-A bare number is refused on purpose: `600000` is ten minutes in milliseconds and a week in
-seconds, and picking one for you is exactly the silent correction the rest of this tool
-refuses. An empty environment variable (`TARMAC_PORT= tarmac serve`) means unset, not empty.
+## Configuration
 
-Two edges worth knowing:
+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.
 
-- **No config file is not an error** — it is the zero-config contract. `install` and
-  `uninstall` never read the file at all, so a typo in it can never be what stands between
-  you and putting your status line back.
-- The snapshots directory is a **read-side** setting, exactly like the flag it mirrors.
-  The wrapper writes where `install` put it, under `<home>/.claude/tarmac/snapshots`. Point
-  the reader at a directory that does not exist and tarmac says so, naming the path and the
-  setting that sent it there — it is only the **default** being absent that means "nothing
-  has been chained yet", because that is the one directory nobody chose.
+| Setting | Flag | Environment | `~/.claude/tarmac/config.json` | Default |
+|---|---|---|---|---|
+| freshness threshold | `--stale-after 90s` \| `15m` \| `2h` | `TARMAC_STALE_AFTER` | `"staleAfterMs": 90000` | `10m` |
+| port | `--port 8080` | `TARMAC_PORT` | `"port": 8080` | `4477` |
+| snapshots dir (read side) | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` | `<home>/.claude/tarmac/snapshots` |
 
-The dashboard binds to loopback and refuses any request whose `Host` is not loopback —
-a DNS-rebinding page in your own browser would otherwise read your cwd paths and costs.
-That guard runs before routing, so it covers `/live` and `/api/fleet` as well as the page.
+**Flag beats environment beats config file beats default**, settled per setting. `serve`
+opens by printing each effective value and which source it came from. Nothing is ever
+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 — including values that were
+going to lose the precedence fight anyway. Full rules and edge cases: `docs/MANUAL.md`.
 
 ## What V1 does not do
 
@@ -243,26 +126,8 @@ npm run build      # flat JavaScript into dist/
 CI runs the suite on Node 22 and 24, on Linux and macOS, with `TARMAC_REQUIRE_DASH=1` so a
 machine without dash cannot report a green build it did not earn; a separate job builds
 `dist/` and runs it on Node 20 — the oldest version `engines` promises, and the only place
-the published artefact is ever executed. Releases are cut by hand: see
-[PUBLISHING.md](PUBLISHING.md).
-
-### Capturing a new Claude Code version
-
-When tarmac reports a version it has never checked, capture the pair — both surfaces from
-one build, in one command, with tarmac installed and a session of that build having drawn
-at least one frame:
-
-```bash
-npm run fixtures:capture
-```
-
-It writes `fixtures/agents-<version>.json` and `fixtures/statusline-payload-<version>-*.json`
-verbatim, then tells you to add the version to `CHECKED_VERSIONS` in `src/schema.ts` — the
-suite fails while the constant and the directory disagree, which is what keeps the guard
-from claiming a coverage nobody verified. **Read both files before committing, and scrub
-them**: they come off your machine carrying real paths, session names and costs. The
-fixtures in this repo are the real shapes with synthetic values, and that is the standard a
-new one has to meet.
+the published artefact is ever executed. Releases are cut by hand (`PUBLISHING.md`);
+capturing fixtures for a new Claude Code build: `docs/MANUAL.md`.
 
 The suite runs the TypeScript sources directly through Node's type stripping, so it needs
 Node ≥ 22.18 to *develop*; what ships in `dist/` is plain ES2022 and runs on Node ≥ 20.

package/dist/cli.js

@@ -11,12 +11,12 @@ import os from 'node:os';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parseArgs } from './args.js';
 import { collectFleet } from './collect.js';
-import { readConfigFile, resolveConfig, SOURCE_PHRASE } from './config.js';
-import { createFleetServer } from './server.js';
+import { readConfigFile, resolveConfig } from './config.js';
+import { createFleetServer, listenFleetServer } from './server.js';
 import { install, uninstall, paths, planInstall, planUninstall } from './install.js';
 import { confirmTyped } from './prompt.js';
 import { reapOrphanedTemps } from './reap.js';
-import { renderPlan, renderSettings, renderTable, restoreMeaning } from './render.js';
+import { renderPlan, renderSettings, renderTable, restoreMeaning, servingLine } from './render.js';
 import { runWatch } from './watch.js';
 const USAGE = `tarmac — fleet observability for Claude Code
 
@@ -36,7 +36,8 @@ const USAGE = `tarmac — fleet observability for Claude Code
   --yes            skip the typed confirmation — required when stdin is not a terminal
   --stale-after    how old a reading may be before it is marked "!" — 90s, 15m, 2h
                    (default: 10m)
-  --port           the dashboard's port (default: 4477)
+  --port           the dashboard's port (default: 4477 — a busy default walks up to the
+                   next free port, a port named here refuses instead)
   --snapshots-dir  where the chained statusline drops its payloads
                    (default: <home>/.claude/tarmac/snapshots)
   --claude-bin     path to the claude CLI (default: claude)
@@ -98,7 +99,7 @@ try {
         if (args.command === 'serve') {
             // 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 tarmac deletes anything: temp files its own wrapper left behind when a
+            // 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.
             const { reaped, failed } = reapOrphanedTemps(snapshotsDir);
@@ -109,17 +110,17 @@ try {
             const server = createFleetServer({
                 collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source }),
             });
-            // `listen` fails asynchronously, long after this try block has been left behind, so
-            // its refusal needs its own way out: a port already taken is the ordinary failure of a
-            // port pinned in a config file, and it has to read like every other refusal here.
+            // 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
+            // through the same catch as every other one here — one line, naming the knob to turn.
+            const bound = await listenFleetServer(server, { port: config.port.value, source: config.port.source });
+            // Past `listen`, an error on this socket is not a port refusal and must not be printed
+            // as one — nor reach the top as an unhandled event: `serve` runs unattended for hours.
             server.on('error', (e) => {
-                const why = e.code === 'EADDRINUSE' ? 'already in use' : e.message;
-                console.error(`tarmac: cannot listen on port ${config.port.value} (${SOURCE_PHRASE[config.port.source]}) — ${why}`);
+                console.error(`tarmac: the dashboard stopped listening — ${e.message}`);
                 process.exit(1);
             });
-            server.listen(config.port.value, '127.0.0.1', () => {
-                console.log(`tarmac serving http://127.0.0.1:${server.address().port}`);
-            });
+            console.log(servingLine(bound));
         }
         else {
             const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source });

package/dist/install.js

@@ -252,17 +252,102 @@ export function install({ home }) {
         writeWrapper(p, backup.previous?.command ?? null, root);
         return { alreadyInstalled: true, previous: backup.previous ?? null, ...p };
     }
-    fs.mkdirSync(p.dir, { recursive: true });
-    fs.mkdirSync(p.snapshots, { recursive: true });
-    writeWrapper(p, previous?.command ?? null, root);
-    // Order matters: the backup is the only way back, so it must be on disk BEFORE
-    // settings.json sends Claude Code to the wrapper. Crashing between the two otherwise
-    // locks the user out of install (backup missing) and uninstall (no install found) at once.
-    const installedText = JSON.stringify(next, null, 2) + '\n';
-    fs.writeFileSync(p.backup, JSON.stringify({ version: 1, originalText, installedText, previous, installedAt: new Date().toISOString() }, null, 2));
-    writeAtomic(p.settings, installedText);
+    // The other end of that order: everything from here CREATES, and the settings write is
+    // the step that can still throw — a symlinked settings.json whose target lives in a
+    // directory with entirely different permissions, or in one that is not there at all.
+    // Left behind, the wrapper and the backup describe an install that never happened, and
+    // that is precisely the state `uninstall` calls `foreign` and clears nothing of. So:
+    // remember what was already on disk, and unwind exactly what this run added.
+    const before = whatIsThere([p.dir, p.snapshots, p.wrapper, p.backup]);
+    try {
+        fs.mkdirSync(p.dir, { recursive: true });
+        fs.mkdirSync(p.snapshots, { recursive: true });
+        writeWrapper(p, previous?.command ?? null, root);
+        // Order matters: the backup is the only way back, so it must be on disk BEFORE
+        // settings.json sends Claude Code to the wrapper. Crashing between the two otherwise
+        // locks the user out of install (backup missing) and uninstall (no install found) at once.
+        const installedText = JSON.stringify(next, null, 2) + '\n';
+        fs.writeFileSync(p.backup, JSON.stringify({ version: 1, originalText, installedText, previous, installedAt: new Date().toISOString() }, null, 2));
+        writeAtomic(p.settings, installedText);
+    }
+    catch (failure) {
+        unwind(p, before);
+        throw failure;
+    }
     return { alreadyInstalled: false, previous, ...p };
 }
+/**
+ * What is on disk before we touch it: the paths that are already there, mapped to the bytes
+ * we would have to put back. `null` when there are no bytes to save — a directory, a dangling
+ * link (whose target we would be CREATING, not restoring), a FIFO.
+ *
+ * The two stats answer two different questions, and using one for both is how this went
+ * wrong twice:
+ *   • PRESENCE is `lstatSync` — the link itself. `existsSync` follows it, so a DANGLING
+ *     symlink reads as absent and the unwind unlinks something this run never created.
+ *   • CONTENT is `statSync` — through the link. `writeFileSync` follows it too, so when the
+ *     dotfiles repo IS cloned the bytes this run destroys are the TARGET's: the user's own
+ *     statusline script, which an `lstat`-only reading called "not a file" and left to die.
+ */
+function whatIsThere(targets) {
+    const before = new Map();
+    for (const target of targets) {
+        try {
+            fs.lstatSync(target);
+        }
+        catch {
+            continue; // not there: ours to create, and ours to take back
+        }
+        before.set(target, statThroughLink(target)?.isFile() ? readOrNull(target) : null);
+    }
+    return before;
+}
+const statThroughLink = (file) => {
+    try {
+        return fs.statSync(file);
+    }
+    catch {
+        return null; // a dangling link: present, but with nothing behind it to save
+    }
+};
+const readOrNull = (file) => {
+    try {
+        return fs.readFileSync(file);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Put the tree back as this run found it: remove what it created, newest first, and restore
+ * what it overwrote. Both halves matter — a re-install that fails must not carry off the way
+ * back from the install that succeeded, and leaving that backup in place with `previous:
+ * null` written into it loses the user's statusline just as surely as deleting the file
+ * would. A directory that holds the user's own config.json is not ours either way.
+ */
+function unwind(p, before) {
+    const attempt = (undo) => {
+        try {
+            undo();
+        }
+        catch {
+            // What we cannot take back must never stand in for the failure that brought us here.
+        }
+    };
+    const drop = (target, remove) => {
+        if (!before.has(target))
+            return attempt(() => remove(target));
+        const original = before.get(target) ?? null;
+        if (original !== null)
+            attempt(() => fs.writeFileSync(target, original));
+    };
+    drop(p.backup, (f) => fs.rmSync(f, { force: true }));
+    drop(p.wrapper, (f) => fs.rmSync(f, { force: true }));
+    // `rmdir`, not a recursive remove: a directory that has gained snapshots or a config since
+    // we made it holds someone else's data now, and ENOTEMPTY is the answer we want.
+    drop(p.snapshots, (d) => fs.rmdirSync(d));
+    drop(p.dir, (d) => fs.rmdirSync(d));
+}
 /** Never let the wrapper chain to itself, whatever spelling the caller used. */
 function writeWrapper(p, chainCommand, home) {
     if (chainCommand && isWrapperCommand(chainCommand, home, p.wrapper)) {
@@ -279,14 +364,31 @@ function writeWrapper(p, chainCommand, home) {
 //     restore puts the link back. So the write follows the link and lands on its target.
 //   • the MODE. `-rw-------` is a decision; a restore that hands the file back
 //     world-readable is not the file the user had, whatever the bytes say.
+// The temp file is cleaned up even when the rename is what fails — a target the user has
+// locked, or a read-only directory reached through a symlink. It lands NEXT TO their
+// settings.json rather than under `~/.claude/tarmac/`, so the unwind above cannot see it and
+// `reap` never looks there: nothing else would ever clear a full copy of their settings.
+// After a successful rename it is already gone, and `force` makes the removal a no-op.
 function writeAtomic(file, text) {
     const target = resolveWriteTarget(file);
     const tmp = `${target}${TEMP_PREFIX}${process.pid}.tmp`;
-    fs.writeFileSync(tmp, text);
-    const mode = modeOf(target);
-    if (mode !== null)
-        fs.chmodSync(tmp, mode); // after the write: umask masks the create mode
-    fs.renameSync(tmp, target);
+    try {
+        fs.writeFileSync(tmp, text);
+        const mode = modeOf(target);
+        if (mode !== null)
+            fs.chmodSync(tmp, mode); // after the write: umask masks the create mode
+        fs.renameSync(tmp, target);
+    }
+    finally {
+        // In a `finally`, so a removal that throws would REPLACE the failure that stopped the
+        // install — the user reading about a temp file instead of why nothing was written.
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // The temp file outliving the run is the smaller harm, every time.
+        }
+    }
 }
 /** The permission bits of an existing file, or `null` when we are creating it. */
 function modeOf(file) {

package/dist/reap.js

@@ -1,4 +1,5 @@
-// Wrapper hygiene — the one thing tarmac deletes.
+// Wrapper hygiene — the litter, which is one of the two things tarmac deletes (the other is
+// the wrapper's own amortized prune of dead sessions' snapshots, see `src/wrapper.ts`).
 //
 // The generated wrapper writes `<dir>/.tarmac-<session_id>.<pid>.tmp` and renames it over
 // `<session_id>.json`, so the snapshot a reader sees is never half-written. Kill the

package/dist/render.js

@@ -45,6 +45,18 @@ const RESTORE_MEANING = {
     absent: 'settings.json is removed — there was none before install',
     foreign: 'the statusLine is someone else\'s now, so nothing is restored and nothing is deleted',
 };
+/**
+ * Where the dashboard is, in one line — and, when the port it was given was taken, which one
+ * that was.
+ *
+ * `tarmac serving ` leads in BOTH shapes, and that is a contract rather than a preference:
+ * two of this project's own test harnesses start `serve` and block until that substring
+ * appears, with no timeout behind them. A moved line that opened with anything else would not
+ * fail them, it would hang them — on the first day 4477 happened to be busy.
+ */
+// Structural on purpose: `server.ts` already imports this module, so naming its `Listening`
+// here would close a cycle for two numbers.
+export const servingLine = ({ port, movedFrom }) => `tarmac serving http://127.0.0.1:${port}` + (movedFrom === null ? '' : ` — port ${movedFrom} was in use`);
 /**
  * What this run decided, and on whose authority. `serve` prints it once at startup because
  * it then runs unattended for hours: a threshold or a directory whose origin is invisible is

package/dist/server.js

@@ -4,6 +4,7 @@
 // so a read-only snapshot directory (the fleet's own, for the demo) is just a parameter.
 import http from 'node:http';
 import { reason, renderLive, renderPage } from './render.js';
+import { SOURCE_PHRASE } from './config.js';
 /**
  * On every answer, including the refusals and the 500s. The page swaps what this port returns
  * into `innerHTML`, and loopback proves where an answer came from, never who wrote it: a
@@ -72,6 +73,75 @@ export function createFleetServer({ collect }) {
         res.end(body);
     });
 }
+/**
+ * How far past a port NOBODY CHOSE `serve` may walk. A corridor, not a search: wide enough
+ * to step over a dashboard someone left running, narrow enough that the refusal at the end
+ * of it can still name every port it tried.
+ */
+export const PORT_FALLBACK_TRIES = 10;
+/**
+ * Binds the dashboard, and says where it ended up.
+ *
+ * Rejects rather than exiting: `serve`'s refusals all leave through one catch, as one line
+ * naming the knob to turn, and a `listen` that failed on an event three ticks later used to
+ * be the single exception to that.
+ *
+ * It resolves with NO `error` listener left on the server — every one it attached is its own
+ * and comes off. A caller that then awaits anything before attaching one is a caller whose
+ * next socket error is an unhandled event.
+ */
+export async function listenFleetServer(server, { port, source, host = '127.0.0.1' }) {
+    const walks = source === 'default';
+    // `resolveConfig` reports `default` for one number only — 4477 — so the far end of the
+    // corridor cannot fall outside the legal range of a port.
+    const last = walks ? port + PORT_FALLBACK_TRIES : port;
+    for (let candidate = port;; candidate++) {
+        const failure = await attempt(server, candidate, host);
+        // The socket, never the number asked for: port 0 is legal and means "pick a free one",
+        // and answering `0` there sent `serve` to print a URL nobody can open.
+        if (failure === null) {
+            return { port: server.address().port, movedFrom: candidate === port ? null : port };
+        }
+        // A taken port is the only failure the next port can fix. A privileged port, an address
+        // this machine does not have, a descriptor limit — none of them get better ten ports
+        // later, and reporting them as "all in use" sends the user hunting a process that was
+        // never there.
+        if (failure.code === 'EADDRINUSE' && candidate < last)
+            continue;
+        if (failure.code === 'EADDRINUSE' && walks) {
+            throw new Error(`ports ${port}-${last} all in use — pick one with --port <n>`);
+        }
+        // The source chose `port`. If the walk has moved on, saying "4479 (the default)" would be
+        // false — 4479 is a port this module picked, and this module's whole discipline is that a
+        // value is reported with whoever actually chose it.
+        const whose = candidate === port ? SOURCE_PHRASE[source] : `walked to from ${port}, ${SOURCE_PHRASE[source]}`;
+        const why = failure.code === 'EADDRINUSE' ? 'already in use, --port <n> picks another' : failure.message;
+        throw new Error(`cannot listen on port ${candidate} (${whose}) — ${why}`);
+    }
+}
+/**
+ * One bind. Resolves with the error instead of rejecting, so "busy, try the next one" and
+ * "this run is over" stay two different things at the call site.
+ *
+ * Both listeners come off before it settles: `listen` reports through events, and the same
+ * server object is reused for every attempt — a handler left behind would answer for the
+ * attempt after it.
+ */
+function attempt(server, port, host) {
+    return new Promise((resolve) => {
+        const onError = (e) => {
+            server.removeListener('listening', onListening);
+            resolve(e);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve(null);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
 function isLoopbackHost(host) {
     if (!host)
         return false;

package/dist/wrapper.js

@@ -1,9 +1,11 @@
 // P2 — the generated statusline wrapper.
 //
 // Claude Code calls `statusLine.command` on EVERY frame of its TUI, passing a documented
-// JSON payload on stdin. The wrapper does exactly two things:
+// JSON payload on stdin. The wrapper does exactly three things:
 //   1. drop that payload as-is under <snapshotDir>/<session_id>.json (the telemetry);
-//   2. hand stdin to the command that was already configured, so the user's display is
+//   2. prune the snapshots of sessions that stopped rendering — amortized, because every
+//      line here is paid on every frame (see PRUNE_MARKER below);
+//   3. hand stdin to the command that was already configured, so the user's display is
 //      untouched.
 //
 // Written as POSIX sh rather than Node on purpose: this sits in the render path of every
@@ -38,6 +40,20 @@ export const TEMP_PREFIX = '.tarmac-';
  * is, in itself, whatever the spelling that reached it.
  */
 export const WRAPPER_MARKER = 'tarmac statusline wrapper — GENERATED';
+/**
+ * Bookkeeping file of the amortized prune below — its mtime is the date of the last sweep.
+ * A dotfile, because `readSnapshots` skips those: the wrapper's own paperwork must never be
+ * read back as if it were a session's telemetry.
+ */
+export const PRUNE_MARKER = '.tarmac-last-prune';
+/** At most one sweep per hour, whatever the frame rate. R3's number, and its whole point. */
+export const PRUNE_EVERY_MIN = 60;
+/**
+ * How long a snapshot nobody rewrites survives. A live session restamps its own file on
+ * every frame, so 48h without one is a session that is gone — and far beyond `--stale-after`,
+ * so nothing was reading that file as current anyway.
+ */
+export const SNAPSHOT_TTL_MIN = 48 * 60;
 /** Single-quotes a string for POSIX sh. */
 function shQuote(s) {
     return `'${String(s).replace(/'/g, `'\\''`)}'`;
@@ -90,13 +106,82 @@ fi
 # --- drop the snapshot (best effort, atomic: temp file + rename in the same dir) ---
 if [ -n "$sid" ] && mkdir -p "$TARMAC_DIR" 2>/dev/null; then
   tmp="$TARMAC_DIR/${TEMP_PREFIX}$sid.$$.tmp"
-  if printf '%s\\n' "$payload" > "$tmp" 2>/dev/null; then
+  # \`2>/dev/null\` comes FIRST, and the order is the whole point: redirections are applied
+  # left to right, so \`> "$tmp" 2>/dev/null\` opens the temp file while stderr is STILL the
+  # user's terminal — the shell prints its own \`cannot create …: Permission denied\` there,
+  # and the \`2>\` that was meant to swallow it only takes effect afterwards. On a snapshot
+  # directory that has become read-only that is one line of noise per FRAME, on the terminal
+  # of a script whose first rule is to be invisible. Exit code and display are untouched
+  # (\`printf\` is a regular built-in, so a failed redirection only fails the command), which
+  # is exactly why nothing but stderr itself catches this. RULE 1.
+  if printf '%s\\n' "$payload" 2>/dev/null > "$tmp"; then
     mv -f "$tmp" "$TARMAC_DIR/$sid.json" 2>/dev/null || rm -f "$tmp" 2>/dev/null
   else
     rm -f "$tmp" 2>/dev/null
   fi
 fi
 
+# --- prune the snapshots of sessions that stopped rendering (amortized) ---
+# Nothing else would ever remove them: \`reap.ts\` collects this script's own temp litter and
+# refuses to touch a \`<sid>.json\`. A fleet that recycles its sessions nightly leaves one dead
+# file behind per session per night, forever. A LIVE session restamps its own snapshot on
+# every frame, so mtime is what tells the dead from the living.
+#
+# Amortized, because this is the render path: the frame pays one \`find\` on ONE file — the
+# marker — and the DIRECTORY is walked at most once an hour. The marker is stamped BEFORE the
+# sweep and only if stamping works, so a sweep that cannot finish is not retried on the next
+# frame. (A directory where the stamp itself keeps failing does pay one \`touch\` per frame,
+# forever — a fork, not a directory walk, and it means nothing can be written there anyway.)
+#
+# Two known holes, both of them the safe way round, and both inherited from the fleet script
+# this transposes:
+#   • a marker dated in the FUTURE (clock skew, a restored backup, a network mount) is never
+#     stale, so pruning stops until the wall clock catches up. Silent, and it fails towards
+#     "keep files" rather than "delete files".
+#   • \`-mmin\` is the one thing here POSIX does not require. GNU, BSD and toybox find have it,
+#     busybox has it unless the build dropped CONFIG_FEATURE_FIND_MMIN; \`-mtime\` could not
+#     replace it (it cannot express hours, and it rounds UP on BSD and DOWN on GNU, so one
+#     expression would mean 24h on macOS and 48h on Linux). Where it is missing \`find\` fails,
+#     the substitution is empty, and the sweep simply never runs.
+# In both cases snapshots pile up exactly as they did before this block existed, and the
+# display is never at risk.
+#
+# One race, priced and accepted: a sweep can stat a cold snapshot in the microseconds before
+# another session's frame renames a fresh one over that same name, and then unlink the fresh
+# inode. The session writes another one on its next frame — seconds later, on a live session
+# — whereas a lock would cost every frame of every session, forever.
+if [ -d "$TARMAC_DIR" ]; then
+  marker="$TARMAC_DIR/${PRUNE_MARKER}"
+  # Only a plain file, or nothing at all, is a marker — and the braces are load-bearing,
+  # since \`&&\` and \`||\` have EQUAL precedence in sh. Both refusals are real:
+  #   • a symlink — \`touch\` follows it, so a dangling one has the status line CREATE the
+  #     link's target, a file outside the snapshot directory. RULE 2.
+  #   • a directory — \`touch\` SUCCEEDS on one, so every frame reads as freshly stamped while
+  #     \`-mmin\` never gets a regular file to judge: the sweep would run on every frame and
+  #     the amortization would be gone, silently.
+  if [ ! -h "$marker" ] && { [ ! -e "$marker" ] || { [ -f "$marker" ] && [ -n "$(find "$marker" -mmin +${PRUNE_EVERY_MIN} 2>/dev/null)" ]; }; }; then
+    # \`touch\`, and NOT \`: > "$marker"\`: POSIX says a redirection error on a special
+    # built-in — and \`:\` is one — shall abort a non-interactive shell. On a snapshot
+    # directory that has become read-only that spelling exits dash 2 and ksh 1 with the
+    # status line never printed, while bash carries on: RULE 1, broken on Debian and Ubuntu
+    # only. An ordinary utility just reports a non-zero status, which is what this \`if\` is
+    # asking about.
+    if touch "$marker" 2>/dev/null; then
+      # \`<dir>/.\` with \`! -name . -prune\` is how POSIX spells \`-maxdepth 1\`, and \`-type f\`
+      # keeps a directory or a symlink wearing a session id's name out of it.
+      #
+      # The glob is the sid SHAPE, not \`*.json\`, and that is the same rule \`reap.ts\` states
+      # for the temp files: only what we wrote. A bare \`*.json\` would take \`settings.json\`
+      # or \`fleet.json\` with it — data this script never wrote, deleted from inside a status
+      # line. 8-4-4-4-12 is the UUID Claude Code emits (every fixture here, and the live
+      # fleet directory). The wrapper accepts wider ids than that because it refuses to guess
+      # what an id may look like; a sid outside this shape is therefore written and never
+      # pruned, which is the direction this trade has to fail in.
+      find "$TARMAC_DIR"/. ! -name . -prune -name '????????-????-????-????-????????????.json' -type f -mmin +${SNAPSHOT_TTL_MIN} -exec rm -f {} + 2>/dev/null
+    fi
+  fi
+fi
+
 # --- hand over to the status line that was already there ---
 if [ -n "$TARMAC_CHAIN" ]; then
   printf '%s\\n' "$payload" | sh -c "$TARMAC_CHAIN"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",
@@ -19,7 +19,7 @@
     "node": ">=20"
   },
   "bin": {
-    "tarmac": "./dist/cli.js"
+    "tarmac": "dist/cli.js"
   },
   "files": [
     "dist"