@adrrr/tarmac 0.1.2 → 0.2.0

package/README.md

@@ -12,14 +12,14 @@ busy or idle, how full its context is, which model, what it has cost so far.
 $ npx @adrrr/tarmac list
 
 PROJECT            STATE  CTX      AS OF  MODEL    EFFORT  COST    UP
-apollo             busy   28%      7m     Fable 5  max     $53.98  8h
-mercury-dashboard  busy   27%      22m !  Fable 5  max     $70.62  8h
-gemini             idle   12%      3h !   Opus 5   high    $3.14   8h
+apollo             busy   28%      7m     Fable 5  max     $41.20  8h
+mercury-dashboard  busy   27%      22m !  Fable 5  max     $62.75  8h
+gemini             idle   12%      3h !   Opus 5   high    $5.40   8h
 atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
 
 ! 3 reading(s) marked "!" are older than the freshness threshold
 
-4 sessions · 2 busy · $127.74
+4 sessions · 2 busy · $109.35
 ```
 
 ## Install
@@ -40,6 +40,11 @@ it prints the full plan — including the exact command that undoes it — and w
 line is wrapped, not replaced: the display stays byte-identical, and `uninstall` restores
 the original exactly.
 
+The only things it puts under `~/.claude/` are the wrapper and the `backup.json` that undoes
+it, neither of which changes at runtime — the snapshots the wrapper writes at every frame go
+to `$XDG_STATE_HOME/tarmac/snapshots` (`~/.local/state/tarmac/snapshots` by default), because
+`~/.claude` is a directory people commit.
+
 ## The dashboard
 
 `tarmac serve` puts the same fleet in the browser — every session a row, ages that keep
@@ -98,7 +103,7 @@ deliberately not configurable, and all of it works with no configuration at all.
 |---|---|---|---|---|
 | 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` |
+| snapshots dir (read side) | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` | `$XDG_STATE_HOME/tarmac/snapshots`, else `<home>/.local/state/tarmac/snapshots` |
 
 **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

package/dist/cli.js

@@ -13,7 +13,7 @@ import { parseArgs } from './args.js';
 import { collectFleet } from './collect.js';
 import { readConfigFile, resolveConfig } from './config.js';
 import { createFleetServer, listenFleetServer } from './server.js';
-import { install, uninstall, paths, planInstall, planUninstall } from './install.js';
+import { install, uninstall, paths, planInstall, planUninstall, installedSnapshotsDir, wrapperIsOurs } from './install.js';
 import { confirmTyped } from './prompt.js';
 import { reapOrphanedTemps } from './reap.js';
 import { renderPlan, renderSettings, renderTable, restoreMeaning, servingLine } from './render.js';
@@ -39,7 +39,8 @@ const USAGE = `tarmac — fleet observability for Claude Code
   --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)
+                   (default: $XDG_STATE_HOME/tarmac/snapshots, or
+                   <home>/.local/state/tarmac/snapshots)
   --claude-bin     path to the claude CLI (default: claude)
 
   Those three settings can also be set, in decreasing order of precedence, by the
@@ -78,6 +79,11 @@ try {
             console.log(res.alreadyInstalled
                 ? `install: already installed — wrapper regenerated, settings.json left alone`
                 : `install: statusLine wrapped — undo with \`${plan.undo}\``);
+            // What the plan promised, as it actually went: a frame of the OLD wrapper can land in
+            // that directory between the two, so the count is reported rather than assumed.
+            if (res.legacy !== null)
+                console.log(`install: cleared ${res.legacy.payloads} runtime payload(s) from ${res.legacy.dir} — they belong in ${res.snapshots}` +
+                    (res.legacy.kept > 0 ? ` (${res.legacy.kept} file(s) kept, so the directory stays)` : ''));
         }
         else {
             const { mode } = uninstall({ home });
@@ -88,11 +94,20 @@ try {
         // Only the reading commands resolve settings, and only they read the config file: a
         // typo in it must not be what stands between a user and `tarmac uninstall`.
         const p = paths(args.home ?? os.homedir());
+        // The installed wrapper's own path, when there is one: the default is where the WRITER
+        // writes, not where a reader's environment would have put it. Recomputing it here made
+        // `XDG_STATE_HOME` in one process and not the other a silent split.
+        const frozen = installedSnapshotsDir(p);
+        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 },
             env: process.env,
             file: readConfigFile(p.config),
-            defaultSnapshotsDir: p.snapshots,
+            // The installed wrapper's own path, when there is one: the default is where the
+            // WRITER writes, not where a reader's environment would have put it. Recomputing it
+            // here made `XDG_STATE_HOME` in one process and not the other a silent split.
+            defaultSnapshotsDir: frozen ?? p.snapshots,
         });
         const snapshotsDir = config.snapshotsDir.value;
         const staleAfterMs = config.staleAfterMs.value;
@@ -108,7 +123,7 @@ try {
             if (failed > 0)
                 console.error(`tarmac: could not remove ${failed} orphaned temp file(s) under ${snapshotsDir}`);
             const server = createFleetServer({
-                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source }),
+                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null }),
             });
             // 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
@@ -123,7 +138,7 @@ try {
             console.log(servingLine(bound));
         }
         else {
-            const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source });
+            const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null });
             if (args.watch) {
                 // One redraws a screen, the other is meant to be piped once. Silently letting one win
                 // is how someone ends up parsing a frame of terminal art.

package/dist/collect.js

@@ -3,22 +3,30 @@ import { SOURCE_PHRASE } from './config.js';
 import { discoverSessions } from './discover.js';
 import { readSnapshots } from './snapshots.js';
 import { buildFleet } from './fleet.js';
-export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', }) {
+export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', installed = false, }) {
     const { sessions, health: discovery } = await discoverSessions({ claudeBin });
     const { snapshots, dirError, unreadable, duplicates, dirMissing } = readSnapshots(snapshotsDir, { now });
     const fleet = buildFleet({ sessions, snapshots, now, discovery, staleAfterMs });
     // Both blind spots travel with the data: a directory we could not read and files we
     // could not parse are OUR failures to report, not silence to render as "all clear".
     //
-    // An absent directory is judged HERE, because this is the layer that knows who chose it:
-    // the default may simply not exist yet (nothing has been chained), but a path someone
-    // typed — flag, environment, or a config file edited months ago — that is not there is a
-    // setting pointing at nothing. Rendered as "not chained yet" it sends the user to run
-    // `tarmac install`, which cannot fix it: install writes where install writes.
-    fleet.health.snapshotsError =
-        dirMissing && snapshotsDirSource !== 'default'
+    // An absent directory is judged HERE, because this is the layer that knows who chose it.
+    // A path someone typed — flag, environment, or a config file edited months ago — that is
+    // not there is a setting pointing at nothing; rendered as "not chained yet" it sends the
+    // user to run `tarmac install`, which cannot fix it: install writes where install writes.
+    //
+    // Exactly ONE case is innocent, and it is narrower than it used to be: no install here at
+    // all. Since #20 the default is the path the install FROZE into the wrapper — a directory
+    // that was chosen and created by a run that happened — so its absence means the writer and
+    // the reader have parted company, which renders as a healthy, empty fleet. That is the one
+    // failure this tool may not have.
+    fleet.health.snapshotsError = !dirMissing
+        ? dirError
+        : snapshotsDirSource !== 'default'
             ? `ENOENT: ${snapshotsDir} does not exist — set by ${SOURCE_PHRASE[snapshotsDirSource]}`
-            : dirError;
+            : installed
+                ? `ENOENT: ${snapshotsDir} does not exist — the installed wrapper writes there`
+                : dirError;
     fleet.health.snapshotsUnreadable = unreadable;
     fleet.health.snapshotsDuplicates = duplicates;
     fleet.health.snapshotsDir = snapshotsDir;

package/dist/install.js

@@ -22,25 +22,72 @@ import os from 'node:os';
 import path from 'node:path';
 import { chainStatusLine, unchainStatusLine } from './settings.js';
 import { firstWord, quoteArg } from './shell.js';
-import { renderWrapper, TEMP_PREFIX, WRAPPER_MARKER } from './wrapper.js';
-export function paths(home) {
+import { renderWrapper, PRUNE_MARKER, SNAPSHOT_NAME, TEMP_PREFIX, WRAPPER_MARKER } from './wrapper.js';
+export function paths(home, { env = process.env, realHome } = {}) {
     const claude = path.join(home, '.claude');
     const dir = path.join(claude, 'tarmac');
+    const stateDir = path.join(stateRoot(home, env, realHome), 'tarmac');
     return {
         claude,
         settings: path.join(claude, 'settings.json'),
         dir,
         wrapper: path.join(dir, 'statusline.sh'),
         backup: path.join(dir, 'backup.json'),
-        snapshots: path.join(dir, 'snapshots'),
+        snapshots: path.join(stateDir, 'snapshots'),
+        stateDir,
+        legacySnapshots: path.join(dir, 'snapshots'),
         config: path.join(dir, 'config.json'),
     };
 }
+/**
+ * `$XDG_STATE_HOME`, or `<home>/.local/state` — the XDG default, for "state data that should
+ * persist between restarts but is not important enough for the data directory". A snapshot
+ * is exactly that: a reading of one frame, rewritten by the next.
+ *
+ * The environment is only honoured FOR THE HOME THAT EXPORTED IT, which is the same rule
+ * `commandTarget` applies to a `~` in someone's statusLine: `--home` exists to work on
+ * someone else's `.claude`, and this process's `XDG_STATE_HOME` says nothing about theirs.
+ * Read unconditionally, `tarmac install --home /home/jane` would point jane's wrapper at our
+ * state directory. (It is NOT what keeps this project's own suite out of the developer's
+ * real one — every CLI test there replaces $HOME, so both anchors coincide by construction
+ * and this guard reads true. Removing the variable is the test helper's job, and it does it.)
+ *
+ * A relative value is ignored, as the spec asks: it would resolve against the working
+ * directory, which for a status line is wherever Claude Code happened to be started.
+ */
+function stateRoot(home, env, realHome) {
+    const xdg = env.XDG_STATE_HOME?.trim();
+    // Short-circuited on purpose: the real home is a QUESTION ABOUT THIS VARIABLE. Asking it
+    // unconditionally — as a default parameter — made `paths()`, which never touched the
+    // environment before, able to throw on a container with no passwd entry and no $HOME.
+    if (xdg && path.isAbsolute(xdg) && sameFile(home, thisHome(realHome)))
+        return xdg;
+    return path.join(home, '.local', 'state');
+}
+/**
+ * Which home this process runs under, or `null` when the system cannot say. Unanswerable
+ * reads as "this is NOT the home that exported the variable" — the safe direction: the
+ * default under the home actually being targeted, rather than a throw or someone else's
+ * directory.
+ */
+function thisHome(realHome) {
+    if (realHome !== undefined)
+        return realHome;
+    try {
+        return os.homedir();
+    }
+    catch {
+        return null;
+    }
+}
 // Two paths name the same directory far more often than string equality admits: `/tmp` is
 // a symlink to `/private/tmp`, `/System/Volumes/Data/Users/x` is a macOS firmlink onto
 // `/Users/x` (same inode, and `realpath` does NOT collapse it), plus bind mounts and
 // relative spellings. Device + inode is the only identity that holds through all of them.
 function sameFile(a, b) {
+    // `null` is "the question could not be answered" — never an accidental match.
+    if (b === null)
+        return false;
     try {
         const sa = fs.statSync(a);
         const sb = fs.statSync(b);
@@ -135,6 +182,173 @@ function writesInstead(file) {
     const target = resolveWriteTarget(file);
     return target === file ? null : target;
 }
+// ── the payloads left inside `.claude` by the versions that wrote them there ────────────
+//
+// Moving the directory is only half of #20: the machines that hit the bug already have the
+// files, committed, and nothing would ever remove them. They are PURGED rather than moved —
+// a snapshot is a reading of the frame that wrote it, every live session writes a fresh one
+// within seconds, and carrying them across would import into the new directory the very
+// files the issue is about, dated from before the move.
+/**
+ * What is in the legacy directory: the payloads this tool wrote, and everything else.
+ *
+ * The "ours" set is the WRITER'S RULE, not merely the writer's names. The wrapper's own
+ * sweep is `-name '<sid shape>' -type f`, and both halves are the rule — `wrapper.ts` refuses
+ * a directory or a symlink wearing a session id's name, because a name is not provenance.
+ * Matching only the name here removed a symlink the shell sweep would have left. Everything
+ * else is someone's, and one of them is enough to keep the directory (`rmdir`, never a
+ * recursive remove: the same rule the unwind states, and this one runs inside a git repo).
+ */
+function readLegacyDir(p) {
+    // The directory the wrapper is ABOUT TO WRITE TO is never the directory we clear, however
+    // the two came to be the same path — `XDG_STATE_HOME=$HOME/.claude` is enough. Purging it
+    // would delete the payloads while announcing the very same path as their new home.
+    if (sameFile(p.snapshots, p.legacySnapshots))
+        return null;
+    const dir = p.legacySnapshots;
+    // `lstat`, not `readdir` alone: a SYMLINK here is the workaround someone will already have
+    // applied to #20 — the directory pointed at a disk outside the repo. `readdir` follows it,
+    // so an unguarded sweep would delete their snapshots at the far end and leave the link.
+    // A directory this tool did not make is not this tool's to empty.
+    try {
+        if (!fs.lstatSync(dir).isDirectory())
+            return null;
+    }
+    catch {
+        return null; // absent, which is the normal case from #20 on
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        // Unreadable is not ours to fix from inside an install.
+        return null;
+    }
+    const ours = [];
+    let kept = 0;
+    for (const name of entries) {
+        if (isPayloadName(name) && isPlainFile(path.join(dir, name)))
+            ours.push(name);
+        else
+            kept += 1;
+    }
+    return { ours, kept };
+}
+/**
+ * The three names the wrapper writes into its snapshot directory, and nothing else.
+ *
+ * `SNAPSHOT_NAME` is the PRUNER's shape (8-4-4-4-12), deliberately narrower than the ids the
+ * writer accepts (`[0-9a-zA-Z-]{8,64}` — it refuses to guess what an id may look like). One
+ * choice, made once, and it is what produces the residue this branch states: a session id
+ * wider than a UUID is written here and swept by neither the pruner nor this. Widening it
+ * would mean deleting, from inside a git repository, by a shape rather than by a signature.
+ */
+const isPayloadName = (name) => SNAPSHOT_NAME.test(name) || name.startsWith(TEMP_PREFIX) || name === PRUNE_MARKER;
+/** `lstat`: the LINK's own kind decides, since `unlink` would remove the link, not its target. */
+const isPlainFile = (file) => {
+    try {
+        return fs.lstatSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Did an install of OURS already exist here, before this run wrote anything?
+ *
+ * `~/.claude/tarmac/snapshots` is a documented path — this project's own docs invite you to
+ * point a reader at one — and the "ours" set is a SHAPE: a UUID name, a `.tarmac-` prefix.
+ * Shape is not provenance. Without this, a FIRST install on a home tarmac had never touched
+ * deleted another writer's files, under a plan promising they would be "written again on the
+ * next frame" by a wrapper that had never written them. It is the same reasoning that spares
+ * a symlink two functions up, applied where it was missing.
+ *
+ * Three independent proofs, any one of which is enough: the statusLine already points at us
+ * (the update path), our marker is in the wrapper (an install whose settings.json was lost),
+ * or a usable backup is on disk (a wrapper someone deleted by hand). All three must be read
+ * BEFORE this run writes anything — by the time the purge runs it has written two of them.
+ */
+export function tarmacWasInstalledHere(p, alreadyInstalled) {
+    return alreadyInstalled || carriesWrapperMarker(p.wrapper) || isUsableBackup(readBackup(p));
+}
+/** Read-only, for the plan: what an install would clear, before a byte is written. */
+export function countLegacySnapshots(p, wasInstalled) {
+    if (!wasInstalled)
+        return null;
+    const found = readLegacyDir(p);
+    return found === null ? null : { dir: p.legacySnapshots, payloads: found.ours.length, kept: found.kept };
+}
+/**
+ * …and the deed. Best effort throughout: a payload we cannot remove is counted as KEPT, not
+ * as removed — which is both honest and exactly what decides whether the directory goes.
+ *
+ * Runs LAST in an install, after the wrapper has been rewritten: until those bytes land, the
+ * OLD wrapper is still the one Claude Code calls, and still dropping a file in here at every
+ * frame. That frame cannot be locked out — and its first act is `mkdir -p`, so it can put the
+ * whole directory back between the `rmdir` and this function returning. Hence the read-back:
+ * what is reported is what is ON DISK afterwards, never what was asked for. A user told to
+ * commit a removal that had already been undone is worse served than one told it did not take.
+ */
+export function purgeLegacySnapshots(p, wasInstalled) {
+    if (!wasInstalled)
+        return null;
+    const found = readLegacyDir(p);
+    if (found === null)
+        return null;
+    let payloads = 0;
+    let kept = found.kept;
+    for (const name of found.ours) {
+        try {
+            fs.unlinkSync(path.join(p.legacySnapshots, name));
+            payloads += 1;
+        }
+        catch {
+            kept += 1;
+        }
+    }
+    if (kept === 0) {
+        // Twice at most. The first `rmdir` can lose a race with a frame's `mkdir -p`, and what
+        // that recreates is an EMPTY directory — which the second attempt takes. A second failure
+        // means the frame also wrote a payload into it: reported, not chased, because this is an
+        // install and not a daemon. Either way what is reported is read back from disk.
+        for (let pass = 0; pass < 2; pass++) {
+            try {
+                fs.rmdirSync(p.legacySnapshots);
+            }
+            catch {
+                // ENOTEMPTY from a frame that landed mid-sweep — the read-back below reports it.
+            }
+            const after = readLegacyDir(p);
+            if (after === null)
+                break; // gone, which is the whole point
+            kept = after.ours.length + after.kept;
+        }
+    }
+    return { dir: p.legacySnapshots, payloads, kept };
+}
+/**
+ * The version-controlled directory this install writes into, nearest first — `.claude` under
+ * its own repo, else a home that is one (`git init ~` is an ordinary dotfiles setup, and the
+ * hint was silent for it while the purge ran just the same). Nearest wins, so the advice is
+ * always about the repository the files are actually in.
+ *
+ * `.git` is a FILE in a worktree or a submodule — a `gitdir:` pointer — and the people who
+ * keep `.claude` in a dotfiles repo are exactly the people who use those, so this asks
+ * whether the name exists at all rather than what it is. A bare-repo setup (`yadm`, a
+ * `--git-dir` alias) has no `.git` anywhere and is not detected: stated, not papered over.
+ *
+ * Only ever used to SAY something. Nothing here reads, writes or runs git.
+ */
+function gitRepoOf(p, home) {
+    const dir = [p.claude, home].find((d) => fs.existsSync(path.join(d, '.git')));
+    if (dir === undefined)
+        return null;
+    // Relative to the repository that will carry the `.gitignore`, with a trailing slash so it
+    // names a directory. A fixed `tarmac/snapshots/` was right for `.claude` and INERT for a
+    // home — `git check-ignore` says so, and a test now asks it rather than asking us.
+    return { dir, ignore: `${path.relative(dir, p.legacySnapshots)}/` };
+}
 export function planInstall({ home, realHome = os.homedir() }) {
     const root = requireHome(home);
     const p = paths(root);
@@ -158,9 +372,27 @@ export function planInstall({ home, realHome = os.homedir() }) {
         after: alreadyInstalled ? before : quoteArg(p.wrapper),
         chained: alreadyInstalled ? (backupOrRefuse(p).previous?.command ?? null) : (previous?.command ?? null),
         alreadyInstalled,
+        snapshots: p.snapshots,
+        legacy: countLegacySnapshots(p, tarmacWasInstalledHere(p, alreadyInstalled)),
+        gitRepo: gitRepoOf(p, root),
+        movingFrom: movedFrom(p),
         undo: undoCommand('uninstall', root, isRealHome),
     };
 }
+/**
+ * The directory the installed wrapper writes to today, when this install is about to freeze a
+ * different one into it — `null` when nothing moves.
+ *
+ * `install` re-derives the path from ITS OWN environment, so a shell that exports
+ * `XDG_STATE_HOME` and a cron job that does not relocate the writer back and forth. The
+ * relocation itself is a separate question; a plan that changes where the telemetry lands
+ * without saying so is not, and the payloads left in the old directory are collected by
+ * nothing.
+ */
+function movedFrom(p) {
+    const current = installedSnapshotsDir(p);
+    return current === null || current === p.snapshots ? null : current;
+}
 /** The statusLine command as written, or `null` when there is none to read. */
 function commandOf(statusLine) {
     const command = statusLine?.command;
@@ -206,26 +438,83 @@ function commandTarget(command, home) {
     return firstWord(s);
 }
 /**
- * Only install-time code asks, never the render path — but the path comes out of someone's
- * settings.json, so it may be a FIFO with no writer or a dead network mount. `O_NONBLOCK`,
- * because a tool that hangs before printing anything is indistinguishable from one that died.
+ * The first `size` bytes of a file, or `null` when there are none to be had.
+ *
+ * `O_NONBLOCK`, because the path can come out of someone's settings.json: a FIFO with no
+ * writer or a dead network mount would otherwise hang a tool before it printed anything.
  */
-function carriesWrapperMarker(file) {
+function readHead(file, size) {
     let fd;
     try {
         fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
-        const head = Buffer.alloc(512);
-        const read = fs.readSync(fd, head, 0, head.length, 0);
-        return head.subarray(0, read).toString('utf8').includes(WRAPPER_MARKER);
+        const head = Buffer.alloc(size);
+        const read = fs.readSync(fd, head, 0, size, 0);
+        return head.subarray(0, read).toString('utf8');
     }
     catch {
-        return false;
+        return null;
     }
     finally {
         if (fd !== undefined)
             fs.closeSync(fd);
     }
 }
+/** Only install-time code asks this, never the render path. */
+function carriesWrapperMarker(file) {
+    return readHead(file, 512)?.includes(WRAPPER_MARKER) ?? false;
+}
+/**
+ * Is the file at the wrapper's path one of ours? Lets a caller tell "no install here" from
+ * "an install whose path we could not read" — two answers `installedSnapshotsDir` collapses
+ * into `null`, and only one of which is worth a word on stderr.
+ */
+export const wrapperIsOurs = (p) => carriesWrapperMarker(p.wrapper);
+/**
+ * Where the INSTALLED wrapper actually writes — read out of the wrapper itself.
+ *
+ * The wrapper carries an absolute path, frozen into the file at install time. `list` and
+ * `serve` used to RECOMPUTE the default instead, from their own `process.env` — so an
+ * `XDG_STATE_HOME` set in an interactive shell and absent from a LaunchAgent, a systemd user
+ * unit, cron or `sudo` without `-E` had the writer filing into A while the reader watched B.
+ *
+ * That split was silent by construction: a default directory that does not exist is the
+ * zero-config case, so `collect.ts` says nothing about it, and the only symptom was
+ * `statusline chained on 0/N sessions` — which the manual itself calls "a true statement
+ * about the wrong directory". A fleet monitor whose failure looks like a healthy empty fleet
+ * is the one failure it may not have.
+ *
+ * Reading our own generated file is not parsing an internal format: this is the file this
+ * module writes, and the marker is the same one `carriesWrapperMarker` trusts everywhere
+ * else. Nothing new is stored, and an install left by an older version is picked up as it
+ * stands. `null` means "no install here to ask" — the caller then computes the default.
+ */
+export function installedSnapshotsDir(p) {
+    const head = readHead(p.wrapper, 8192);
+    if (head === null || !head.includes(WRAPPER_MARKER))
+        return null;
+    const line = /^TARMAC_DIR=(.*)$/m.exec(head);
+    return line === null ? null : shUnquote(line[1]);
+}
+/**
+ * The inverse of the single-quoting `renderWrapper` applies (`shQuote`, in `wrapper.ts`) —
+ * the exact one, never a guess.
+ *
+ * Double quotes are accepted too. Nothing here emits them, but a hand-edited wrapper, or one
+ * written by another generation of this file, exists; refusing a spelling every shell reads
+ * the same way would send the reader back to guessing from its own environment, which is the
+ * bug this function closes.
+ *
+ * An EMPTY value is not a path — it is a wrapper that writes nowhere. `args.ts` refuses
+ * `--snapshots-dir=` and `config.ts` refuses `"snapshotsDir": ""` for exactly that reason.
+ */
+function shUnquote(text) {
+    const s = text.trim();
+    const quote = s.startsWith("'") ? "'" : s.startsWith('"') ? '"' : null;
+    if (quote === null || s.length < 2 || !s.endsWith(quote))
+        return null;
+    const body = quote === "'" ? s.slice(1, -1).split(`'\\''`).join("'") : s.slice(1, -1);
+    return body === '' ? null : body;
+}
 /**
  * A backup we cannot trust is worse than none: it is the only record of the statusline we
  * wrapped. `previous: null` is legitimate ("there was no statusLine"), so the discriminant
@@ -246,11 +535,16 @@ export function install({ home }) {
         isSameCommand: (command, wrapper) => isWrapperCommand(command, root, wrapper),
         commandSpelling: quoteArg(p.wrapper),
     });
+    // Read here and nowhere later: two of its three proofs are things this function is about
+    // to write, so asking afterwards would always answer yes.
+    const wasInstalled = tarmacWasInstalledHere(p, alreadyInstalled);
     if (alreadyInstalled) {
         const backup = backupOrRefuse(p);
         fs.mkdirSync(p.snapshots, { recursive: true });
         writeWrapper(p, backup.previous?.command ?? null, root);
-        return { alreadyInstalled: true, previous: backup.previous ?? null, ...p };
+        // After the wrapper, always: this is the update path, and until that write lands the
+        // frames are still filing into the directory being cleared.
+        return { alreadyInstalled: true, previous: backup.previous ?? null, legacy: purgeLegacySnapshots(p, wasInstalled), ...p };
     }
     // 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
@@ -258,7 +552,7 @@ export function install({ home }) {
     // 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]);
+    const before = whatIsThere([p.dir, p.stateDir, p.snapshots, p.wrapper, p.backup]);
     try {
         fs.mkdirSync(p.dir, { recursive: true });
         fs.mkdirSync(p.snapshots, { recursive: true });
@@ -274,7 +568,7 @@ export function install({ home }) {
         unwind(p, before);
         throw failure;
     }
-    return { alreadyInstalled: false, previous, ...p };
+    return { alreadyInstalled: false, previous, legacy: purgeLegacySnapshots(p, wasInstalled), ...p };
 }
 /**
  * What is on disk before we touch it: the paths that are already there, mapped to the bytes
@@ -345,7 +639,12 @@ function unwind(p, before) {
     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.
+    //
+    // The state directory goes back too, deepest first — `mkdir -p` made both rungs. What is
+    // ABOVE it (`~/.local/state`) is XDG's, not ours: we may have created it on a home that
+    // had none, and unmaking it would be reaching past what this tool owns.
     drop(p.snapshots, (d) => fs.rmdirSync(d));
+    drop(p.stateDir, (d) => fs.rmdirSync(d));
     drop(p.dir, (d) => fs.rmdirSync(d));
 }
 /** Never let the wrapper chain to itself, whatever spelling the caller used. */
@@ -432,6 +731,9 @@ export function planUninstall({ home, realHome = os.homedir() }) {
         before: commandOf(current.statusLine),
         after,
         mode,
+        // Where they REALLY are: `uninstall` leaves them behind, so the path it prints has to be
+        // the wrapper's own, not one recomputed from this shell's environment.
+        snapshots: installedSnapshotsDir(p) ?? p.snapshots,
         undo: undoCommand('install', root, isRealHome),
     };
 }

package/dist/render.js

@@ -27,9 +27,34 @@ export function renderPlan(plan) {
             rows.push(['↳ which calls', `${plan.chained}   (your display is unchanged)`]);
         if (plan.alreadyInstalled)
             rows.push(['note', 'already installed — the wrapper is regenerated, settings.json is left alone']);
+        // The snapshots directory is no longer under `.claude`, so it is no longer guessable
+        // from the path above it: naming it here is how a reader of `list`, `serve` or any other
+        // tool finds out where the payloads land.
+        rows.push(['snapshots', plan.snapshots]);
+        // A relocation is a change to where the telemetry lands, so it is never implied.
+        if (plan.movingFrom !== null)
+            rows.push(['↳ moving from', `${plan.movingFrom}   (its payloads are left there, and nothing collects them)`]);
+        // This operation now DELETES files, inside a directory people commit. A plan that can
+        // disagree with what runs is worse than no plan — so it says how many, and where.
+        // A directory that is THERE but holds none of our payloads is the state the previous
+        // install left behind: nothing to announce, and nothing to ask anyone to commit.
+        const clearing = plan.legacy !== null && plan.legacy.payloads > 0;
+        if (clearing) {
+            rows.push([
+                '↳ clearing',
+                `${plan.legacy.payloads} runtime payload(s) under ${plan.legacy.dir} — each one is written again on the next frame`,
+            ]);
+            if (plan.legacy.kept > 0)
+                rows.push(['↳ keeping', `${plan.legacy.kept} file(s) nothing here wrote, so that directory stays`]);
+        }
+        if (plan.gitRepo !== null)
+            rows.push(['git', gitHint(plan.gitRepo, clearing)]);
     }
     else {
         rows.push(['restore', `${plan.mode} — ${restoreMeaning(plan.mode)}`]);
+        // "Your snapshots survive uninstall" is a promise about a directory nobody can guess any
+        // more, so the command that leaves them behind says where it leaves them.
+        rows.push(['snapshots', `${plan.snapshots}   (left exactly as they are)`]);
     }
     rows.push(['undo', plan.undo]);
     const w = Math.max(...rows.map(([label]) => label.length));
@@ -37,6 +62,19 @@ export function renderPlan(plan) {
         rows.map(([label, value]) => `  ${label.padEnd(w)}  ${value}\n`).join('') +
         '\n');
 }
+/**
+ * The line #20 asked for, said once, to the only people it concerns: those whose `.claude`
+ * is a git repository.
+ *
+ * It has two jobs, and which one is live depends on whether the payloads are still there:
+ * an install that clears them produces a DELETION the user has to commit, and a `.gitignore`
+ * line keeps them from coming back if that directory is ever pointed at again. With nothing
+ * to clear, the only thing left to say is that this install adds nothing that churns.
+ */
+const gitHint = (repo, hasLegacy) => `${repo.dir} is a git repository — ` +
+    (hasLegacy
+        ? `commit the removal above, and add \`${repo.ignore}\` to its .gitignore`
+        : 'nothing tarmac writes there changes at runtime; the snapshots live outside it');
 /** What each restore mode means, in the words the plan and the report both use. */
 export const restoreMeaning = (mode) => RESTORE_MEANING[mode];
 const RESTORE_MEANING = {

package/dist/wrapper.js

@@ -54,6 +54,22 @@ export const PRUNE_EVERY_MIN = 60;
  * so nothing was reading that file as current anyway.
  */
 export const SNAPSHOT_TTL_MIN = 48 * 60;
+/**
+ * The names the sweep below is allowed to remove: the 8-4-4-4-12 session id Claude Code
+ * emits, which is every fixture here and every file the live fleet directory holds. NOT
+ * `*.json` — that would take a `settings.json` or a `fleet.json` sitting next to them, data
+ * this script never wrote, deleted from inside a status line.
+ *
+ * The wrapper WRITES ids wider than this on purpose (it refuses to guess what an id may look
+ * like), so such a file is written and never pruned. That is the only direction this trade
+ * may fail in.
+ */
+export const SNAPSHOT_GLOB = '????????-????-????-????-????????????.json';
+/**
+ * The same set, in Node — derived from the glob itself so the shell that deletes and the
+ * TypeScript that deletes can never drift apart. `?` is any single character, `.` is literal.
+ */
+export const SNAPSHOT_NAME = new RegExp(`^${SNAPSHOT_GLOB.replace(/\./g, '\\.').replace(/\?/g, '.')}$`);
 /** Single-quotes a string for POSIX sh. */
 function shQuote(s) {
     return `'${String(s).replace(/'/g, `'\\''`)}'`;
@@ -171,13 +187,9 @@ if [ -d "$TARMAC_DIR" ]; then
       # 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
+      # for the temp files: only what we wrote — see SNAPSHOT_GLOB, which the legacy purge in
+      # \`install.ts\` reads from the same constant.
+      find "$TARMAC_DIR"/. ! -name . -prune -name '${SNAPSHOT_GLOB}' -type f -mmin +${SNAPSHOT_TTL_MIN} -exec rm -f {} + 2>/dev/null
     fi
   fi
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",
@@ -14,6 +14,14 @@
   ],
   "license": "MIT",
   "author": "Adrien Leboeuf",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrrr/tarmac.git"
+  },
+  "homepage": "https://github.com/adrrr/tarmac#readme",
+  "bugs": {
+    "url": "https://github.com/adrrr/tarmac/issues"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"