@adrrr/tarmac 0.1.0

package/dist/schema.js

@@ -0,0 +1,87 @@
+// P4 — the schema guard: what tarmac has actually looked at, versus what it is being fed.
+//
+// Every field this tool reads was OBSERVED on a Claude Code build and frozen in `fixtures/`;
+// none of it is promised by a published schema. The defences already in place fire once a
+// field has broken — `ctxState: 'drift'` when a key is gone, `schemaBroken` when every
+// snapshot drifted. They are the alarm. This is the smoke detector: a build nobody has ever
+// captured is a reason to LOOK, never a reason to stop reporting, and never a reason to exit
+// non-zero.
+//
+// It judges EVERY distinct version in flight, not the newest one. A fleet is normally
+// running two builds at once — Claude Code updates itself, sessions live for days — and the
+// straggler is precisely the session on a shape nobody captured. A first cut compared only
+// the highest version seen, which meant one surviving session on a known build vouched for
+// six running an unknown one; a release that merely DROPPED `version` was silent that way.
+//
+// Membership is exact string equality: `2.1.226-rc.1` is not `2.1.226`, and a prerelease
+// must not inherit the silence of the release it prefixes.
+//
+// Known blind spot: the version is read off the statusline payload, so a machine with no
+// statusline chained gives this guard nothing to judge — including about `claude agents
+// --json`, which carries no version of its own. That fleet gets the "chained on 0/N"
+// warning instead, which is about installation, not about schema.
+/**
+ * The Claude Code versions whose payloads are frozen in `fixtures/` — and therefore the
+ * only ones any of this tool's field names have been seen to be true of.
+ *
+ * Baked into src on purpose: only `dist/` is published, so a released tarmac has no
+ * `fixtures/` to read at runtime. `test/schema.test.ts` compares this list against the
+ * directory, so the two cannot drift apart in the repo.
+ */
+export const CHECKED_VERSIONS = {
+    statusline: ['2.1.220', '2.1.226'],
+    agents: ['2.1.226'],
+};
+const SURFACE_LABEL = {
+    statusline: 'statusline payload',
+    agents: '`claude agents --json`',
+};
+/** Where a user of a published install can actually go — the script in scripts/ is not one. */
+const ISSUES_URL = 'https://github.com/adrrr/tarmac/issues';
+/**
+ * @param seen the `version` each live snapshot reported — `null` for the ones that had no
+ *        such key. Order only affects the order things are named in.
+ *
+ * The version comes from the statusline payload, which is written by the Claude Code that
+ * runs the session — not from `claude --version`, which would describe the binary on PATH
+ * and cost a subprocess on every collect. So this reports on the builds actually OBSERVED
+ * writing to the fleet.
+ */
+export function guardVersions(seen) {
+    if (seen.length === 0)
+        return { state: 'nothing', versions: [], noVersion: 0, unchecked: [] };
+    const versions = [...new Set(seen.filter((v) => typeof v === 'string' && v !== ''))];
+    const noVersion = seen.length - seen.filter((v) => typeof v === 'string' && v !== '').length;
+    const unchecked = [];
+    for (const surface of Object.keys(CHECKED_VERSIONS)) {
+        const missing = versions.filter((v) => !CHECKED_VERSIONS[surface].includes(v));
+        if (missing.length > 0)
+            unchecked.push({ surface, versions: missing });
+    }
+    // A snapshot that cannot even say which build wrote it is the worse fact, so it leads —
+    // but the notice below still reports both.
+    const state = noVersion > 0 ? 'no-version' : unchecked.length > 0 ? 'unchecked' : 'ok';
+    return { state, versions, noVersion, unchecked };
+}
+/** What a human should be told, or `null` when there is nothing worth saying. */
+export function schemaNotice(guard) {
+    if (guard.state === 'ok' || guard.state === 'nothing')
+        return null;
+    const said = [];
+    if (guard.noVersion > 0) {
+        const total = guard.noVersion + guard.versions.length;
+        said.push(`${guard.noVersion} of ${total} statusline payloads carry no \`version\` — the key tarmac checks its fixtures against is gone on those sessions. ` +
+            'That is drift in itself: the readings are still whatever Claude Code sent, but nothing can be checked against a shape anyone has seen.');
+    }
+    if (guard.unchecked.length > 0) {
+        const surfaces = guard.unchecked
+            .map((u) => `${SURFACE_LABEL[u.surface]} — ${u.versions.join(', ')} (checked ${CHECKED_VERSIONS[u.surface].join(', ')})`)
+            .join('; ');
+        said.push(`Claude Code payload shapes that have never been checked: ${surfaces}.`);
+    }
+    // The advice has to be doable by whoever is reading it — someone who installed with npx
+    // and has no scripts/ directory. Capturing a fixture is a maintainer's move, documented
+    // in the README, not something to send a user looking for.
+    said.push(`Nothing is blocked and no reading is hidden; if a column starts coming up empty, update tarmac or report it at ${ISSUES_URL}.`);
+    return said.join(' ');
+}

package/dist/server.js

@@ -0,0 +1,80 @@
+// P3 — the local dashboard. node:http, localhost, no dependency.
+//
+// The collector is injected so the server can be exercised without spawning `claude`, and
+// so a read-only snapshot directory (the fleet's own, for the demo) is just a parameter.
+import http from 'node:http';
+import { reason, renderLive, renderPage } from './render.js';
+/**
+ * On every answer, including the refusals and the 500s. The page swaps what this port returns
+ * into `innerHTML`, and loopback proves where an answer came from, never who wrote it: a
+ * process that takes the port after `tarmac serve` exits, or a proxy standing in front of it,
+ * answers 200 with whatever it likes — `<img src=x onerror=…>` included — into a page the
+ * user opened themselves. The page refuses to swap anything that does not carry this, so the
+ * failures carry it too: their text is what it quotes as the reason.
+ */
+const IDENTITY = { 'x-tarmac': '1' };
+export function createFleetServer({ collect }) {
+    return http.createServer(async (req, res) => {
+        // Loopback binding alone does not stop a DNS-rebinding page in the user's own browser
+        // from reading /api/fleet — which carries cwd paths, session ids and costs.
+        if (!isLoopbackHost(req.headers.host)) {
+            res.writeHead(403, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.end('tarmac serves loopback hosts only\n');
+            return;
+        }
+        // The Host check stops another origin READING this port; it does not stop one poking it.
+        // Any page the user visits can `fetch(…, {mode:'no-cors'})` here as fast as it likes —
+        // CORS hides the answer, but each request still spawns `claude agents --json`. Browsers
+        // label their own requests, so a label that says cross-site is refused before anything is
+        // spawned; a client that sends no label (curl, a script) is left alone.
+        const site = req.headers['sec-fetch-site'];
+        if (typeof site === 'string' && site !== 'same-origin' && site !== 'none') {
+            res.writeHead(403, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.end('tarmac serves same-origin requests only\n');
+            return;
+        }
+        // `url` is always set on a server-side request; the assertion adds no branch.
+        const url = new URL(req.url, 'http://localhost');
+        // `/live` is what the open page asks for every few seconds: the same render as `/`, minus
+        // the shell. Serving the whole page there would hand the running script a copy of itself.
+        if (url.pathname !== '/' && url.pathname !== '/live' && url.pathname !== '/api/fleet') {
+            res.writeHead(404, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.end('not found\n');
+            return;
+        }
+        // Read AND render inside the guard, and send nothing until there is something to send.
+        // Writing the 200 first and rendering after made the collector's failure a 500 and the
+        // renderer's failure a dead daemon: the headers were already on the wire, the throw
+        // became an unhandled rejection, and `tarmac serve` — which runs unattended for hours —
+        // left the browser holding an answer that never came.
+        let type;
+        let body;
+        try {
+            const fleet = await collect();
+            if (url.pathname === '/api/fleet') {
+                type = 'application/json; charset=utf-8';
+                body = JSON.stringify(fleet, null, 2);
+            }
+            else {
+                type = 'text/html; charset=utf-8';
+                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet);
+            }
+        }
+        catch (e) {
+            // Say why. A dashboard that goes blank when its source breaks teaches nothing.
+            res.writeHead(500, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.end(`tarmac could not read the fleet:\n${reason(e)}\n`);
+            return;
+        }
+        // A page whose entire claim is freshness must not be served from a cache: a restored tab
+        // re-running the script over stale HTML would re-stamp it "updated just now".
+        res.writeHead(200, { ...IDENTITY, 'content-type': type, 'cache-control': 'no-store' });
+        res.end(body);
+    });
+}
+function isLoopbackHost(host) {
+    if (!host)
+        return false;
+    const name = host.replace(/:\d+$/, '').replace(/^\[|\]$/g, '');
+    return name === 'localhost' || name === '127.0.0.1' || name === '::1';
+}

package/dist/sessions.js

@@ -0,0 +1,51 @@
+// P1 — Contractual session discovery.
+//
+// Single source: `claude agents --json`, a CLI surface Claude Code publishes on purpose.
+// Tarmac parses NO internal format here: no ~/.claude/projects/*.jsonl, no tmux pane pixels.
+//
+// Design rule carried over from the fleet's "3rd blindness": a status we do not recognise
+// is `null`, never `false`. A release that renames `busy` must make Tarmac say "I don't
+// know", not "everything is calm" — the second is a silent outage, the first is a signal.
+const KNOWN_STATUS = new Map([
+    ['busy', true],
+    ['idle', false],
+]);
+/** @param text raw stdout of `claude agents --json` */
+export function parseAgents(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error('`claude agents --json` output is not valid JSON');
+    }
+    if (!Array.isArray(raw)) {
+        throw new Error('`claude agents --json`: expected a JSON array');
+    }
+    const health = { seen: raw.length, noSessionId: 0, unknownStatus: 0 };
+    const sessions = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            health.noSessionId += 1;
+            continue;
+        }
+        const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null;
+        if (!sessionId)
+            health.noSessionId += 1;
+        const status = typeof entry.status === 'string' ? entry.status : null;
+        const busy = KNOWN_STATUS.has(status) ? KNOWN_STATUS.get(status) : null;
+        if (busy === null)
+            health.unknownStatus += 1;
+        sessions.push({
+            sessionId,
+            pid: typeof entry.pid === 'number' ? entry.pid : null,
+            cwd: typeof entry.cwd === 'string' ? entry.cwd : null,
+            name: typeof entry.name === 'string' ? entry.name : null,
+            kind: typeof entry.kind === 'string' ? entry.kind : null,
+            startedAt: typeof entry.startedAt === 'number' ? entry.startedAt : null,
+            status,
+            busy,
+        });
+    }
+    return { sessions, health };
+}

package/dist/settings.js

@@ -0,0 +1,65 @@
+// P2 — pure settings surgery. No filesystem here, so every branch is cheap to test.
+//
+// Two promises the product makes about `settings.json`:
+//   1. NON-DESTRUCTIVE — an existing statusLine is wrapped (still rendered), never replaced.
+//   2. REVERSIBLE — what we removed is handed back to the caller so it can be stored and
+//      put back verbatim.
+//
+// Anything we do not understand is REFUSED, not overwritten. A statusLine shape we cannot
+// chain is a user's working display; guessing would break their terminal.
+// Identity of "is this command OUR wrapper?" is NOT string equality. `/tmp/x` and
+// `/private/tmp/x` are the same file on macOS; so are a bind mount and a firmlink. Getting
+// this wrong makes tarmac wrap its own wrapper — an unbounded recursion at every TUI frame,
+// with the user's real statusline erased from the only file that named it. The comparator
+// is injected because this module stays pure; `install.ts` passes a filesystem-aware one.
+const stringEquality = (a, b) => a === b;
+/**
+ * @param settings parsed settings.json (may be {})
+ * @param wrapperPath absolute path to the tarmac wrapper
+ */
+export function chainStatusLine(settings, wrapperPath, { isSameCommand = stringEquality, commandSpelling } = {}) {
+    const next = structuredClone(settings ?? {});
+    const current = next.statusLine;
+    if (isOurs(current, wrapperPath, isSameCommand)) {
+        return { settings: next, previous: null, alreadyInstalled: true };
+    }
+    let previous = null;
+    if (current !== undefined && current !== null) {
+        if (!isChainableCommand(current)) {
+            throw new Error('refusing to replace an unrecognised statusLine (expected {type:"command", command:"…"})');
+        }
+        previous = structuredClone(current);
+    }
+    // Swap ONLY the command. Every other key (`padding: 0` is flush-left, and more may come)
+    // is the user's display configuration: dropping it changes what they see, which is the
+    // one thing chaining promises not to do.
+    next.statusLine = { ...(previous ?? {}), type: 'command', command: commandSpelling ?? wrapperPath };
+    return { settings: next, previous, alreadyInstalled: false };
+}
+/**
+ * @param settings parsed settings.json as it stands now
+ * @param previous the statusLine recorded at install time
+ * @param wrapperPath the wrapper we installed
+ */
+export function unchainStatusLine(settings, previous, wrapperPath, { isSameCommand = stringEquality } = {}) {
+    const next = structuredClone(settings ?? {});
+    // Someone else owns the statusLine now — hands off. The caller MUST learn that nothing
+    // was undone, or it deletes the wrapper that line still points at.
+    if (!isOurs(next.statusLine, wrapperPath, isSameCommand))
+        return { settings: next, restored: false };
+    if (previous)
+        next.statusLine = structuredClone(previous);
+    else
+        delete next.statusLine;
+    return { settings: next, restored: true };
+}
+function isChainableCommand(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        v.type === 'command' &&
+        typeof v.command === 'string' &&
+        v.command !== '');
+}
+function isOurs(v, wrapperPath, isSameCommand) {
+    return isChainableCommand(v) && isSameCommand(v.command, wrapperPath);
+}

package/dist/shell.js

@@ -0,0 +1,73 @@
+// The two directions of one fact: `statusLine.command` is shell source.
+//
+// Claude Code documents that field as running in a shell, so tarmac writes a PATH into it
+// (which must survive word splitting) and later reads a path back out of it (to answer "is
+// this command my own wrapper?"). Those are inverse operations, and when they drifted apart
+// — quoting that escaped an apostrophe, reading that only stripped the outer quotes — a home
+// named `od d's` stopped being recognised as its own install: the wrapper chained itself,
+// and one frame forked until the process table gave up. Written as a pair, tested as a pair.
+/** Characters a shell leaves alone. Anything else has to be quoted to survive. */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+:,.\/-]+$/;
+/** `s` as shell source that evaluates back to exactly `s`. Quoted only when it needs to be. */
+export function quoteArg(s) {
+    return SHELL_SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The first word of a command line, with quoting removed — i.e. the file it runs. Arguments,
+ * pipes and redirects are none of our business; the file is what identity is decided on.
+ *
+ * @returns `''` when the line cannot be parsed (an unbalanced quote). A command we cannot
+ *          read is not one we may guess at: this answer decides whether tarmac deletes a
+ *          wrapper, and half a quoted string could name any file at all.
+ */
+export function firstWord(command) {
+    const s = command.trim();
+    let out = '';
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === ' ' || c === '\t' || c === '\n')
+            break;
+        if (c === "'") {
+            const end = s.indexOf("'", i + 1);
+            if (end === -1)
+                return '';
+            out += s.slice(i + 1, end);
+            i = end + 1;
+        }
+        else if (c === '"') {
+            const closed = readDoubleQuoted(s, i + 1);
+            if (closed === null)
+                return '';
+            out += closed.text;
+            i = closed.next;
+        }
+        else if (c === '\\') {
+            if (i + 1 >= s.length)
+                return '';
+            out += s[i + 1];
+            i += 2;
+        }
+        else {
+            out += c;
+            i += 1;
+        }
+    }
+    return out;
+}
+/** Inside double quotes only `\` before `"`, `\`, `$` and a backtick is an escape. */
+function readDoubleQuoted(s, from) {
+    let text = '';
+    for (let i = from; i < s.length; i++) {
+        const c = s[i];
+        if (c === '"')
+            return { text, next: i + 1 };
+        if (c === '\\' && i + 1 < s.length && ['"', '\\', '$', '`'].includes(s[i + 1])) {
+            text += s[i + 1];
+            i += 1;
+            continue;
+        }
+        text += c;
+    }
+    return null;
+}

package/dist/snapshots.js

@@ -0,0 +1,137 @@
+// P3 — reading the telemetry the wrapper dropped.
+//
+// The snapshot is a verbatim copy of Claude Code's own statusLine payload, so this module
+// reads a DOCUMENTED shape — no transcript resummation, no window size hardcoded, no regex
+// over terminal pixels.
+//
+// The one rule everything else leans on: "no value" is never rendered as 0. `ctxPct: null`
+// means "not measured"; a 0 could only ever mean "measured at 0". And "not measured" has
+// two opposite causes that must not be confused:
+//   fresh — the key is present and null: a session that has taken no turn yet. Normal,
+//           transient, true of a whole fleet for a few minutes after a nightly recycle.
+//   drift — the key is gone or changed type: a Claude Code release moved the schema and
+//           the context reading of the entire fleet just died, snapshots still flowing.
+// The discriminant is the PRESENCE of the key, never its value.
+import fs from 'node:fs';
+import path from 'node:path';
+export function extractTelemetry(payload) {
+    const p = payload;
+    const cw = p?.context_window;
+    let ctxState = 'drift';
+    let ctxPct = null;
+    if (cw && typeof cw === 'object' && !Array.isArray(cw) && 'used_percentage' in cw) {
+        const v = cw.used_percentage;
+        if (v === null)
+            ctxState = 'fresh';
+        // A number by TYPE is not yet a percentage. `1e999` is legal JSON and parses to
+        // `Infinity`, which printed as "Infinity%" in the terminal and as a bar clamped to 100%
+        // on the page; a negative one reached that bar as `width:-3%`, an element that renders as
+        // nothing at all beside a confident "-3%". Both are values no reading can have, so they
+        // are treated as what they are — a shape that moved — rather than shown to anyone.
+        else if (Number.isFinite(v) && v >= 0 && v <= 100) {
+            ctxState = 'ok';
+            ctxPct = Math.floor(v);
+        }
+    }
+    // Same rule as above, one level down: sum only what is really a number, and return null
+    // when NONE of the four expected keys is one. Coercing absent keys to 0 would turn a
+    // renamed schema into a confident `ctxTokens: 0` sitting next to a healthy `ctxState`.
+    const ctxTokens = sumUsage(cw?.current_usage);
+    return {
+        sessionId: str(p?.session_id),
+        ctxState,
+        ctxPct,
+        ctxTokens,
+        ctxWindow: typeof cw?.context_window_size === 'number' ? cw.context_window_size : null,
+        model: str(p?.model?.display_name),
+        modelId: str(p?.model?.id),
+        effort: str(p?.effort?.level),
+        costUsd: typeof p?.cost?.total_cost_usd === 'number' ? p.cost.total_cost_usd : null,
+        ccVersion: str(p?.version),
+        rateLimits: p?.rate_limits && typeof p.rate_limits === 'object' ? p.rate_limits : null,
+    };
+}
+const USAGE_KEYS = ['input_tokens', 'output_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens'];
+function sumUsage(usage) {
+    if (!usage || typeof usage !== 'object' || Array.isArray(usage))
+        return null;
+    let sum = 0;
+    let seen = false;
+    for (const k of USAGE_KEYS) {
+        const v = usage[k];
+        if (typeof v === 'number') {
+            sum += v;
+            seen = true;
+        }
+    }
+    return seen ? sum : null;
+}
+/**
+ * Read-only sweep of a snapshot directory, keyed by the session id found INSIDE each
+ * payload. `now` is an argument so tests can pin the clock.
+ *
+ * "Nothing there" and "I was not allowed to look" must not answer alike: the first is a
+ * fleet that has not been chained yet, the second is a permission bug that would otherwise
+ * render as "0/7 chained — run tarmac install", blaming the user for our own blindness.
+ */
+export function readSnapshots(dir, { now = Date.now() } = {}) {
+    const snapshots = new Map();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (e) {
+        const code = e.code;
+        return {
+            snapshots,
+            dirError: code === 'ENOENT' ? null : `${code}: ${dir}`,
+            unreadable: 0,
+            duplicates: 0,
+            dirMissing: code === 'ENOENT',
+        };
+    }
+    let unreadable = 0;
+    let duplicates = 0;
+    for (const name of entries) {
+        if (!name.endsWith('.json') || name.startsWith('.'))
+            continue;
+        const file = path.join(dir, name);
+        let payload;
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(file).mtimeMs;
+            payload = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            unreadable += 1; // corrupt, half-written or unreadable: skip, but never forget
+            continue;
+        }
+        const t = extractTelemetry(payload);
+        if (!t.sessionId) {
+            unreadable += 1;
+            continue;
+        }
+        const snapshot = { ...t, ageMs: Math.round(now - mtimeMs), file };
+        const already = snapshots.get(t.sessionId);
+        if (already)
+            duplicates += 1;
+        snapshots.set(t.sessionId, already ? preferred(already, snapshot) : snapshot);
+    }
+    return { snapshots, dirError: null, unreadable, duplicates, dirMissing: false };
+}
+/**
+ * Which of two snapshots claiming one session a reader is shown.
+ *
+ * Freshest first — but "freshest" decides nothing when the two carry the same mtime, and
+ * that is precisely the case this rule exists for: `cp -p`, `rsync -a` and `tar -x` all
+ * preserve mtime, so a snapshot copied between directories arrives as a perfect twin. The
+ * loser of a tie was then whichever one readdir happened to hand over first — an order no
+ * filesystem promises (ext4 with dir_index and APFS both answer in hash order), so the SAME
+ * two files could show a different number on two machines, silently.
+ *
+ * The filename breaks the tie because it is the only thing left that both files carry and
+ * neither shares. Which one it picks matters far less than that it picks the same one every
+ * time, everywhere.
+ */
+export const preferred = (a, b) => a.ageMs !== b.ageMs ? (a.ageMs < b.ageMs ? a : b) : a.file <= b.file ? a : b;
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);

package/dist/watch.js

@@ -0,0 +1,49 @@
+// P3 — `tarmac list --watch`: the terminal's half of the live view.
+//
+// The loop holds one piece of state the one-shot `list` never needed — the last fleet it
+// managed to read — because that is what makes an honest failure possible. When `claude`
+// stops answering, the table stays (it is still true, of an earlier moment), the reason is
+// printed above it, and the age underneath it keeps climbing. A watch that simply redrew the
+// same numbers would be the frozen dashboard, in a smaller window.
+//
+// Clock and sleeping are injected: a suite that waits five real seconds per frame is a suite
+// nobody runs.
+import { reason, renderWatch, REFRESH_MS } from './render.js';
+/** Home, then erase — in that order, so the scrollback above is not what gets redrawn into. */
+const CLEAR = '\x1b[H\x1b[2J';
+export async function runWatch({ collect, write, sleep, now, everyMs = REFRESH_MS, isTTY = false, signal, }) {
+    let fleet = null;
+    let lastOk = now();
+    let error = null;
+    const draw = () => write((isTTY ? CLEAR : '') + renderWatch({ fleet, error, ageMs: now() - lastOk, everyMs }));
+    while (!signal.aborted) {
+        try {
+            fleet = await collect();
+            lastOk = now();
+            error = null;
+        }
+        catch (e) {
+            // Kept, not thrown: one unreadable tick is a thing to report, not a reason to quit and
+            // take the last good reading off the screen with it. `reason` rather than `.message`
+            // because a non-Error rejection yields `undefined`, which is falsy — the failure line
+            // would not have printed badly, it would not have printed at all.
+            error = reason(e);
+        }
+        draw();
+        if (signal.aborted)
+            break;
+        // A terminal redraws while it waits, so the age on screen is never more than a second
+        // stale — and a collector that hangs shows a counter that has visibly stopped rather than
+        // a table still claiming to be current. Down a pipe there is no screen to keep current,
+        // and a frame a second would be nothing but noise, so the wait stays one sleep.
+        if (!isTTY) {
+            await sleep(everyMs);
+            continue;
+        }
+        for (let left = everyMs; left > 0 && !signal.aborted; left -= 1000) {
+            await sleep(Math.min(1000, left));
+            if (!signal.aborted)
+                draw();
+        }
+    }
+}

package/dist/wrapper.js

@@ -0,0 +1,121 @@
+// 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:
+//   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
+//      untouched.
+//
+// Written as POSIX sh rather than Node on purpose: this sits in the render path of every
+// frame. A `node` boot per frame (~40 ms) is an order of magnitude more than a `sh` one,
+// and the fleet measured the sh version at ≈ +10 ms/frame in production.
+//
+// POSIX means POSIX: on Debian and Ubuntu `/bin/sh` is dash, not bash. Every construct
+// 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:
+//   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.
+/**
+ * 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
+ * signature: the fleet's own production statusline wrapper emits byte-identical names into
+ * a directory the docs tell you to point `--snapshots-dir` at. `src/reap.ts` builds
+ * its match from this constant so the writer and the deleter can never drift apart.
+ */
+export const TEMP_PREFIX = '.tarmac-';
+/**
+ * The line every generated wrapper carries, and the last word on "is this file one of
+ * ours?". Path identity answers that question only for the spellings `stat` can resolve —
+ * `~/…`, quoted, or written relative to somewhere else all stat to nothing, and a tarmac
+ * that fails to recognise itself wraps its own wrapper: unbounded recursion at every frame,
+ * with the real statusline erased from the only file that named it. The file says what it
+ * is, in itself, whatever the spelling that reached it.
+ */
+export const WRAPPER_MARKER = 'tarmac statusline wrapper — GENERATED';
+/** Single-quotes a string for POSIX sh. */
+function shQuote(s) {
+    return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+/** @returns the sh source of the wrapper */
+export function renderWrapper({ snapshotDir, chainCommand }) {
+    return `#!/bin/sh
+# ${WRAPPER_MARKER}, do not edit.
+# Removed by \`tarmac uninstall\`, which also puts back the statusLine it wrapped.
+TARMAC_DIR=${shQuote(snapshotDir)}
+TARMAC_CHAIN=${shQuote(chainCommand ?? '')}
+
+payload=$(cat)
+
+# --- extract "session_id" without forking (no jq, no python: this runs every frame) ---
+# The match is positional (first occurrence). If the payload ever gains a NESTED id — a
+# parent or subagent block — the first one is not ours, the snapshot would be filed under
+# a wrong name, and a second session would silently clobber it. Ambiguity is refused, not
+# resolved by guessing: same rule as the UUID shape check below.
+sid=''
+rest=\${payload#*'"session_id"'}
+case "\${rest}" in
+  *'"session_id"'*) payload_has_two_ids=1 ;;
+  *) payload_has_two_ids=0 ;;
+esac
+
+case "$payload" in
+  *'"session_id"'*)
+    rest=\${payload#*'"session_id"'}
+    rest=\${rest#*:}
+    case "$rest" in
+      *'"'*)
+        rest=\${rest#*'"'}
+        sid=\${rest%%'"'*}
+        ;;
+    esac
+    ;;
+esac
+# refuse anything that is not UUID-shaped — this value becomes a filename
+case "$sid" in
+  ''|*[!0-9a-zA-Z-]*) 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
+  tmp="$TARMAC_DIR/${TEMP_PREFIX}$sid.$$.tmp"
+  if printf '%s\\n' "$payload" > "$tmp" 2>/dev/null; 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
+
+# --- hand over to the status line that was already there ---
+if [ -n "$TARMAC_CHAIN" ]; then
+  printf '%s\\n' "$payload" | sh -c "$TARMAC_CHAIN"
+else
+  # nothing to chain: print the model name so the line is never blank
+  case "$payload" in
+    *'"display_name"'*)
+      rest=\${payload#*'"display_name"'}
+      rest=\${rest#*:}
+      case "$rest" in
+        *'"'*)
+          rest=\${rest#*'"'}
+          printf '%s\\n' "\${rest%%'"'*}"
+          ;;
+      esac
+      ;;
+  esac
+fi
+
+exit 0
+`;
+}