@adrrr/tarmac 0.1.2 → 0.3.0

package/dist/wrapper.js

@@ -16,13 +16,16 @@
 // below is in the POSIX shell command language, and `test/portability.test.ts` runs this
 // script under every POSIX shell present on the machine to keep it that way.
 //
-// Two invariants, both tested by running the real script:
+// Three invariants, all tested by running the real script:
 //   RULE 1 — never break the display. Missing chain, failing chain, unwritable directory:
 //            the status line still renders and the exit code is still 0. Telemetry loses,
 //            display wins, always.
 //   RULE 2 — never write outside the snapshot directory. `session_id` is external input
 //            that becomes a filename, so anything that is not UUID-shaped is REFUSED, not
 //            sanitised: a guessed name would be read back later as if it were certain.
+//   RULE 3 — the sweep may remove exactly what the writer may write, no more and no less.
+//            One rule, `SID_GLOB`, read by both — because when those two sets are merely
+//            written to agree, they stop agreeing quietly, in both directions at once (#7).
 /**
  * Prefix of every temp file the wrapper writes, and the ONLY thing that proves tarmac
  * wrote one. `.<sid>.<pid>.tmp` — what this used to emit — is a convention, not a
@@ -54,6 +57,55 @@ export const PRUNE_EVERY_MIN = 60;
  * so nothing was reading that file as current anyway.
  */
 export const SNAPSHOT_TTL_MIN = 48 * 60;
+/**
+ * A session id — ONE rule, and the only one the writer below, the sweep below and the
+ * TypeScript that reads this directory are allowed to know. Written as a shell pattern
+ * because two of the three consumers are shell; the third derives its regex from it.
+ *
+ * It is the canonical UUID, 8-4-4-4-12 hex: every fixture in this repo, every file in the
+ * snapshot directory of the fleet this was built for, every transcript file observed. The
+ * statusline payload documents `session_id` only as a "unique session identifier", so that
+ * is an observation and not a promise — and the direction of the bet is deliberate. An id
+ * that is not a UUID is refused at write time, which surfaces as a live session with
+ * `absent` telemetry: a state `fleet.ts` already names and shows. The other bet — file
+ * whatever arrives, and widen the deleters to match — would put every stem of 8..64
+ * characters of `[0-9A-Za-z-]` within reach of `rm`, in a directory whose location comes
+ * from `XDG_STATE_HOME` and can therefore be `~/.claude` itself, where the legacy purge
+ * already deletes and where people keep a git repository. A missing row is recoverable.
+ *
+ * Bracket expressions, not `?`: `?` matches a leading dot (fnmatch without FNM_PERIOD), so
+ * the old glob reached dotfiles the writer's own charset forbids it to produce (#7).
+ *
+ * And an ENUMERATION, not the range `[0-9a-fA-F]`: a range is collated by the locale, which
+ * for a status line is whatever the TUI that spawned it carries. Under `en_US.UTF-8` — the
+ * ordinary case on macOS, where `/bin/sh` is bash — `a-f` reaches `é`, `ç` and fullwidth `ａ`
+ * in bash, in ksh and in BSD `find`, while the regex below is ASCII code points and always
+ * will be. That is one string meaning two different sets depending on `LANG`, which is this
+ * whole rule undone: a sid filed in a Terminal, refused under `LC_ALL=C`, and a file written
+ * by the first frame that no TypeScript consumer here can ever recognise. Sixteen digits
+ * spelled out roughly doubles the pattern — 356 characters to 772 — and costs nothing
+ * measurable per frame.
+ */
+const HEX = '[0123456789abcdefABCDEF]';
+export const SID_GLOB = [8, 4, 4, 4, 12].map((n) => HEX.repeat(n)).join('-');
+/**
+ * The names the sweep below is allowed to remove: the sid rule, and a `.json`. 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.
+ */
+export const SNAPSHOT_GLOB = `${SID_GLOB}.json`;
+/**
+ * The same rule, in Node — the pattern goes in RAW, because a bracket expression means the
+ * same set in both languages and `-` is literal in both. Only the extension is spelled twice,
+ * once per language, which is the one thing a translation could get wrong and so the one
+ * thing that is written out rather than derived.
+ *
+ * `SID_NAME` is the sid alone: `fleet.ts` asks it whether a LIVE session's id is one the
+ * wrapper would ever file, which is the difference between "no frame drawn yet" and "no frame
+ * will ever help" — two states that look identical on a row.
+ */
+export const SID_NAME = new RegExp(`^${SID_GLOB}$`);
+export const SNAPSHOT_NAME = new RegExp(`^${SID_GLOB}\\.json$`);
 /** Single-quotes a string for POSIX sh. */
 function shQuote(s) {
     return `'${String(s).replace(/'/g, `'\\''`)}'`;
@@ -92,16 +144,15 @@ case "$payload" in
     esac
     ;;
 esac
-# refuse anything that is not UUID-shaped — this value becomes a filename
+# Refuse anything that is not a session id — this value becomes a filename, and it is the
+# same rule the sweep below deletes by: what this line declines to write, that one cannot
+# unlink, and the reverse. An empty sid matches nothing here, so it stays empty.
 case "$sid" in
-  ''|*[!0-9a-zA-Z-]*) sid='' ;;
+  ${SID_GLOB}) ;;
+  *) sid='' ;;
 esac
 # refuse an ambiguous payload outright
 [ "$payload_has_two_ids" = 1 ] && sid=''
-if [ -n "$sid" ]; then
-  len=\${#sid}
-  if [ "$len" -lt 8 ] || [ "$len" -gt 64 ]; then sid=''; fi
-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
@@ -133,6 +184,53 @@ fi
 # 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.)
 #
+# And DETACHED, because amortized is an average and the average was never the problem: on an
+# install that has never pruned, the one frame that sweeps pays for the entire backlog at
+# once — a directory walk plus ten thousand unlinks on 20 000 snapshots, measured at 0.5 s in
+# the report and at 0.6-0.9 s by \`test/sweep-perf.test.ts\`, in front of the status line (#8).
+# Bounding the work per sweep instead would only spread that cost, at one bounded batch an
+# hour, over weeks of frames that each still stop to walk the
+# same directory; the frame has no business waiting for any of it. So the sweep is handed to a
+# child and the frame goes on to the chain: the frame's cost becomes one fork, whatever the
+# directory holds, and NOTHING on the nominal path — a frame with no sweep due — changes at all.
+# What that costs, all of it on the sweep's side of the fork:
+#   • the child outlives the frame. It is orphaned when the shell exits and reaped by init;
+#     nothing waits for it, so no zombie can accumulate in the TUI's process tree.
+#   • if the session dies mid-sweep, the sweep normally finishes on its own: it holds no state
+#     but the marker, already stamped, and an orphan is not interrupted by the death of its
+#     parent. It does NOT go away with a Ctrl-C either — POSIX has the shell set SIGINT and
+#     SIGQUIT to ignored in an asynchronous list where job control is off, which is here. Only
+#     a signal aimed at the process group (a SIGHUP or a SIGTERM from whatever supervises the
+#     TUI) takes it, and then what is left is what the next hour's sweep will find, which is
+#     where it was heading anyway.
+#   • the redirections are not hygiene, they are the point. A child that inherits the frame's
+#     stdout puts whatever it prints INTO the status line, and holds the pipe open after this
+#     shell has exited — the reader waits on EOF, so the frame would still block, having only
+#     moved where. \`</dev/null\` is the belt to those braces: POSIX already hands an
+#     asynchronous list \`/dev/null\` for stdin wherever job control is off — every shell that
+#     will ever run this — and stdin was drained by \`\$(cat)\` at the top anyway.
+#   • two frames that reach the marker check together both sweep, as they always could. The
+#     window is not the \`touch\` — it is the \`find\` that reads the marker's age, a whole
+#     process, which is why two frames drawn simultaneously fork two sweeps almost every time.
+#     Detaching improves that case rather than widening it: what used to be two frozen frames
+#     is now two detached walks. What matters is that a frame drawn AFTER a sweep has started
+#     sees a stamped marker and starts nothing, which is the ordinary case and the reason the
+#     stamping stayed in the frame rather than moving into the child. Across HOURS they can
+#     overlap — a sweep slower than the window is joined by the
+#     next one — and that is harmless: \`rm -f\` on a name another sweep already unlinked is
+#     not an error, and the marker is the only state either of them writes.
+#   • a \`find\` that HANGS (a stale network mount, a directory that never answers) is no longer
+#     one frozen frame; it is one orphaned process per hour that nothing here reaps. The trade
+#     is deliberate — a frozen frame breaks RULE 1, an idle process does not — but it is
+#     unbounded over time in a way the blocking shape was not.
+#   • the chain now runs BESIDE the sweep instead of after it, so anything reading this same
+#     directory can watch a file vanish under it mid-frame. Nothing here breaks on that — the
+#     display is untouched and no data is lost — but it is not free either: \`snapshots.ts\`
+#     counts a file that disappears between its \`readdir\` and its \`readFile\` as UNREADABLE,
+#     and \`list\`/\`serve\` report that as "the schema may have moved". Same window on the
+#     blocking shape (a sweep and a reader have always been able to overlap), so this is not
+#     a regression, and it is the READER's to fix: #17.
+#
 # 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
@@ -171,13 +269,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 {} + >/dev/null 2>&1 </dev/null &
     fi
   fi
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.1.2",
+  "version": "0.3.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"