@adrrr/tarmac 0.1.1 → 0.1.2

package/dist/cli.js

@@ -99,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);

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/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.1",
+  "version": "0.1.2",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",