@adrrr/tarmac 0.1.2 → 0.3.0

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,189 @@ 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 writer's own rule now, not a second reading of it (#7): this purge
+ * deletes from inside `~/.claude`, a directory people version-control, and a `<sid>.json` is
+ * recognised by SHAPE alone — so the shape had better be one the wrapper can actually
+ * produce, or this deletes by resemblance in the worst place to be wrong about it.
+ *
+ * `TEMP_PREFIX` is deliberately the whole test for a temp file, and deliberately looser than
+ * `reap.ts`'s `<prefix><sid>.<pid>.tmp`. The two answer different questions. `reap` runs on
+ * every `serve` tick, in a directory a reader may have been pointed at and another program
+ * may own, so it takes only the exact name this wrapper emits. This runs once, at install,
+ * behind `tarmacWasInstalledHere` — provenance already proven — over a directory whose whole
+ * purpose was to be ours, and its job is to leave nothing behind so the directory itself can
+ * go. There, a name only tarmac ever writes is signature enough.
+ */
+const isPayloadName = (name) => SNAPSHOT_NAME.test(name) || name.startsWith(TEMP_PREFIX) || name === PRUNE_MARKER;
+/**
+ * What is at that path, with the two "no"s kept apart so a plan can say which one it is:
+ * nothing there at all, or something there that is not ours to take.
+ *
+ * `lstat`: the LINK's own kind decides, since `unlink` would remove the link, not its target.
+ * A judgement by `existsSync` would follow a dead symlink to "nothing there" while the removal
+ * left the link exactly where it was.
+ */
+const markerState = (file) => {
+    try {
+        return fs.lstatSync(file).isFile() ? 'file' : 'not-a-file';
+    }
+    catch {
+        return 'none';
+    }
+};
+/** The same question, for callers that only need the yes. */
+const isPlainFile = (file) => markerState(file) === 'file';
+/**
+ * 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 +388,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 +454,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 +551,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 +568,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 +584,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 +655,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. */
@@ -422,6 +737,7 @@ export function planUninstall({ home, realHome = os.homedir() }) {
         after = restored ? commandOf(settings.statusLine) : commandOf(current.statusLine);
     }
     const isRealHome = sameFile(root, realHome);
+    const snapshots = installedSnapshotsDir(p);
     return {
         action: 'uninstall',
         home: root,
@@ -432,6 +748,11 @@ 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 — and when the
+        // wrapper cannot answer, neither can the plan. The same `null` `uninstall` acts on.
+        snapshots,
+        marker: snapshots === null ? null : markerState(path.join(snapshots, PRUNE_MARKER)),
         undo: undoCommand('install', root, isRealHome),
     };
 }
@@ -441,10 +762,20 @@ function installedBackupOrRefuse(p) {
         throw new Error(`no tarmac install found under ${p.dir}`);
     return backup;
 }
+function removePruneMarker(snapshots) {
+    if (snapshots === null)
+        return;
+    const marker = path.join(snapshots, PRUNE_MARKER);
+    if (isPlainFile(marker))
+        fs.rmSync(marker, { force: true });
+}
 export function uninstall({ home }) {
     const root = requireHome(home);
     const p = paths(root);
     const backup = installedBackupOrRefuse(p);
+    // Read this before removing the wrapper: it is the source of truth when the install used
+    // XDG_STATE_HOME, and the marker is the only file in that directory uninstall owns.
+    const snapshots = installedSnapshotsDir(p);
     const currentText = fs.existsSync(p.settings) ? fs.readFileSync(p.settings, 'utf8') : null;
     let mode;
     if (currentText === backup.installedText) {
@@ -472,7 +803,10 @@ export function uninstall({ home }) {
         writeAtomic(p.settings, JSON.stringify(settings, null, 2) + '\n');
         mode = 'surgical';
     }
-    // Snapshots are data the user may still want; only what we generated goes.
+    // Restore settings before touching runtime state: even an unreadable snapshots directory
+    // must not strand statusLine on the wrapper we are uninstalling.
+    removePruneMarker(snapshots);
+    // Snapshot payloads are data the user may still want; only what we generated goes.
     fs.rmSync(p.wrapper, { force: true });
     fs.rmSync(p.backup, { force: true });
     return { mode };

package/dist/map.js

@@ -0,0 +1,110 @@
+// P4 — the map's model.
+//
+// A view over the fleet `buildFleet` already produced. It opens no second source: every
+// field below is derived from a row that is already on the page as a table line.
+/**
+ * How recently a snapshot must have landed for its node to pulse. Two of the page's poll
+ * intervals (5s): a session whose terminal keeps drawing frames keeps its heartbeat across
+ * consecutive renders, and one that has stopped goes quiet within two of them.
+ *
+ * It is a display window, not a health threshold — `--stale-after` is the one that judges,
+ * and it wins wherever the two disagree.
+ */
+export const PULSE_WITHIN_MS = 10_000;
+/**
+ * Where an agent is placed, and why it is a placement rather than a link.
+ *
+ * `claude agents --json` prints interactive and background sessions in one array, and
+ * publishes nothing that ties an agent to whoever dispatched it. The working directory is
+ * the only field both carry, so it is what an agent is placed BY — it lands next to the
+ * session sharing its directory, and nothing is ever nested inside anything. Nesting would
+ * assert a parentage the source does not contain, and it would let this page show a smaller
+ * fleet than the table beside it.
+ *
+ * The agents are gathered separately because the fleet sorts busy sessions first, so one can
+ * arrive before the session it belongs beside. An agent whose directory matches no session
+ * keeps a node of its own, at the end.
+ */
+export function buildMap({ rows }, { pulseWithinMs = PULSE_WITHIN_MS } = {}) {
+    // Whether this fleet still speaks the kind we know. If NOTHING calls itself `interactive`,
+    // the word moved rather than every terminal on the machine going background at once — and
+    // the map says so by drawing them all as what they almost certainly still are. It is the
+    // tolerance `buildFleet` already applies to telemetry: a signal true of every row is a
+    // change in the source.
+    const anchored = rows.some((r) => r.kind === INTERACTIVE);
+    const roleOf = (r) => !anchored || r.kind === null || r.kind === INTERACTIVE ? 'session' : 'agent';
+    const node = (row) => {
+        const reading = readingOf(row);
+        return {
+            row,
+            role: roleOf(row),
+            state: stateOf(row),
+            reading,
+            measured: row.ctxPct !== null,
+            // Three conditions, and each one is a way the halo could otherwise lie. `live` first,
+            // and not merely "young": a reading the fleet calls stale may not be animated as
+            // though it were breathing, and with `--stale-after 2s` a three-second-old reading is
+            // both stale and inside the window below. `measured` last: a file landing is not a
+            // reading landing, and a drifted fleet still writes a snapshot every frame.
+            pulse: reading === 'live' &&
+                row.ctxPct !== null &&
+                row.snapshotAgeMs !== null &&
+                row.snapshotAgeMs <= pulseWithinMs,
+        };
+    };
+    const agents = rows.filter((r) => roleOf(r) === 'agent');
+    const placed = new Set();
+    const seen = new Set();
+    const nodes = [];
+    for (const r of rows) {
+        if (roleOf(r) !== 'session')
+            continue;
+        nodes.push(node(r));
+        // Only the first session of a directory collects them, or two sessions in one checkout
+        // would each grow a copy of the same agents.
+        if (r.cwd === null || seen.has(r.cwd))
+            continue;
+        seen.add(r.cwd);
+        for (const a of agents) {
+            // Two directories nobody could read are not the same directory.
+            if (a.cwd === null || a.cwd !== r.cwd)
+                continue;
+            nodes.push(node(a));
+            placed.add(a);
+        }
+    }
+    for (const a of agents)
+        if (!placed.has(a))
+            nodes.push(node(a));
+    return { nodes };
+}
+/**
+ * The kind a terminal calls itself, and the anchor this module reasons from. A background
+ * entry has since been seen beside them — `kind: 'background'`, no `pid`, its word under
+ * `state` rather than `status` — so the two are no longer a reading of that CLI's help. It is
+ * still the anchor and never the list: one observed alternative is not the vocabulary, and the
+ * heuristic above asks only whether anything on this machine still calls itself `interactive`.
+ *
+ * An ABSENT kind is not evidence of an agent either: the same rule the session status follows
+ * one module down, where unrecognised means unknown, never "the quiet one". The two mistakes
+ * are not the same size — an agent drawn as a session is a node in the wrong shape, while a
+ * session drawn as an agent is a terminal someone is working in, reduced to a footnote of a
+ * directory it merely shares.
+ */
+export const INTERACTIVE = 'interactive';
+/**
+ * `stale` is not recomputed here — it is the collector's verdict, reached against the
+ * threshold this run resolved (`--stale-after`, the environment, the config file). A second
+ * opinion in this module would let the map and the table disagree about the same session on
+ * the same page.
+ */
+function readingOf(r) {
+    if (r.snapshotAgeMs === null)
+        return 'none';
+    // A snapshot dated after the clock reading it: an NTP correction, a mount whose time runs
+    // ahead. Its age is not a small number, it is not a number at all.
+    if (r.snapshotAgeMs < 0)
+        return 'undated';
+    return r.stale ? 'stale' : 'live';
+}
+export const stateOf = (r) => (r.busy === true ? 'busy' : r.busy === false ? 'idle' : 'unknown');

package/dist/reap.js

@@ -16,12 +16,17 @@
 //     in flight, and deleting it would be the reaper causing the corruption it prevents.
 import fs from 'node:fs';
 import path from 'node:path';
-import { TEMP_PREFIX } from './wrapper.js';
+import { SID_GLOB, TEMP_PREFIX } from './wrapper.js';
 /** Exported so a test can build the same expectation from the same constant, escaped. */
 export const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// `<TEMP_PREFIX><sid>.<pid>.tmp` — the sid charset and length are the ones the wrapper
-// enforces before it agrees to use the value as a filename, and the pid is what `$$` emits.
-const TEMP_NAME = new RegExp(`^${escapeRe(TEMP_PREFIX)}[0-9A-Za-z-]{8,64}\\.\\d+\\.tmp$`);
+// `<TEMP_PREFIX><sid>.<pid>.tmp` — the pid is what `$$` emits, and the sid is the wrapper's
+// own rule, read from the constant rather than transcribed: a set of its own is how this
+// matcher came to accept names the writer had stopped producing (#7).
+//
+// `SID_GLOB` goes in RAW, unlike the prefix: it is a shell pattern made of bracket
+// expressions and literal `-`, which is already valid regex meaning the same set. Escaping
+// it would turn the classes into literal brackets and match nothing at all.
+const TEMP_NAME = new RegExp(`^${escapeRe(TEMP_PREFIX)}${SID_GLOB}\\.\\d+\\.tmp$`);
 /** An hour is orders of magnitude beyond any real frame, and cheap to be wrong about. */
 const DEFAULT_OLDER_THAN_MS = 60 * 60_000;
 /**