@adrrr/tarmac 0.1.0

package/dist/config.js

@@ -0,0 +1,184 @@
+// P4 — configuration. Three numbers in this tool are opinions, not truths: how old a reading
+// may be before it is marked stale, which port the dashboard binds, and where the snapshots
+// are read from. This module is where they get their values, and — just as important — where
+// they remember who gave it to them.
+//
+// Two rules hold everything else up:
+//   1. NOTHING IS SILENT. A value we cannot parse, a key we do not know, a file that is not
+//      JSON — each one stops the run and says which knob to go and turn. A dropped setting is
+//      a lie about what the tool is doing.
+//   2. THE DEFAULTS DO NOT MOVE. With no flag, no environment and no file, every number here
+//      is the one that was baked into the source before this module existed.
+//
+// Pure: no filesystem outside `readConfigFile`, no imports from the rest of the project, so
+// the precedence rules can be exercised without a fleet, a home, or a process.
+import fs from 'node:fs';
+/** How to name a source in a sentence, when an error has to say who chose the value. */
+export const SOURCE_PHRASE = {
+    flag: 'a command-line flag',
+    env: 'the environment',
+    file: 'the config file',
+    default: 'the default',
+};
+const UNITS = { ms: 1, s: 1000, m: 60_000, h: 3600_000 };
+const DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+/**
+ * A human duration — `90s`, `15m`, `2h` — in milliseconds.
+ *
+ * A bare number is refused on purpose: `600000` is ten minutes in milliseconds and a week in
+ * seconds, and choosing for the user is exactly the silent correction this module forbids.
+ *
+ * @param label how the source spells this setting, so the refusal names the knob to turn
+ */
+export function parseDuration(text, label) {
+    const m = DURATION.exec(text.trim());
+    const ms = m ? Math.round(Number(m[1]) * UNITS[m[2]]) : NaN;
+    // Rounded BEFORE the guard: `0.4ms` clears a `> 0` test and then lands on 0, which marks
+    // every reading stale and explains itself with `older than 0h` — a spelling this very
+    // parser refuses to read back.
+    if (!Number.isFinite(ms) || ms <= 0) {
+        throw new Error(`${label} must be a positive duration like 90s, 15m or 2h, got: ${text}`);
+    }
+    return ms;
+}
+/**
+ * A duration back into the units it would have been typed in — the largest one that divides
+ * it evenly, so `600000` reads as `10m`. Printed next to every `!`: a threshold nobody can
+ * see is a mark nobody can argue with. Round-trips through `parseDuration`.
+ */
+export function formatDuration(ms) {
+    for (const unit of ['h', 'm', 's']) {
+        if (ms % UNITS[unit] === 0)
+            return `${ms / UNITS[unit]}${unit}`;
+    }
+    return `${ms}ms`;
+}
+/** A TCP port from text. `0` stays legal — it means "pick a free one", which `serve` uses. */
+export function parsePort(text, label) {
+    const trimmed = text.trim();
+    const n = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+    return checkPort(n, label, text);
+}
+function checkPort(n, label, shown = n) {
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 0 || n > 65535) {
+        throw new Error(`${label} must be a port number between 0 and 65535, got: ${shown}`);
+    }
+    return n;
+}
+const KNOWN_KEYS = ['staleAfterMs', 'port', 'snapshotsDir'];
+/**
+ * `~/.claude/tarmac/config.json`, if there is one.
+ *
+ * ABSENT IS SILENCE, UNREADABLE IS NOT. No file at all is the zero-config contract and
+ * returns `{}`. A file that exists and cannot be read, parsed, or understood stops the run:
+ * a settings file that turns out to have been ignored all along is worse than no file.
+ */
+export function readConfigFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return {};
+        throw new Error(`could not read ${file}: ${e.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON: ${e.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${file} must contain a JSON object with keys ${KNOWN_KEYS.join(', ')}`);
+    }
+    const body = raw;
+    const unknown = Object.keys(body).filter((k) => !KNOWN_KEYS.includes(k));
+    if (unknown.length > 0) {
+        throw new Error(`unknown key(s) in ${file}: ${unknown.join(', ')} — known keys are ${KNOWN_KEYS.join(', ')}`);
+    }
+    const out = {};
+    const where = (key) => `${file}: ${key}`;
+    if ('staleAfterMs' in body) {
+        const v = body.staleAfterMs;
+        // Rounded before the guard, same reason as `parseDuration`: 0.4 ms is not a threshold.
+        const ms = typeof v === 'number' && Number.isFinite(v) ? Math.round(v) : NaN;
+        if (!Number.isFinite(ms) || ms <= 0) {
+            throw new Error(`${where('staleAfterMs')} must be a positive number of milliseconds, got: ${format(v)}`);
+        }
+        out.staleAfterMs = ms;
+    }
+    if ('port' in body)
+        out.port = checkPort(body.port, where('port'), format(body.port));
+    if ('snapshotsDir' in body) {
+        const v = body.snapshotsDir;
+        if (typeof v !== 'string' || v.trim() === '') {
+            throw new Error(`${where('snapshotsDir')} must be a non-empty path, got: ${format(v)}`);
+        }
+        out.snapshotsDir = v;
+    }
+    return out;
+}
+/**
+ * Values come back from JSON as anything; the refusal has to be able to show them all —
+ * including the empty string, which as bare text turns `got: ` into a message that reads
+ * like the message itself is broken.
+ */
+const format = (v) => v === '' ? '(empty)' : typeof v === 'string' ? v : JSON.stringify(v) ?? String(v);
+// ── resolution ──────────────────────────────────────────────────────────────────────────
+/**
+ * A snapshot is written at every TUI frame, so its age is the age of the READING. An idle
+ * session redraws rarely: its number is not wrong, but it is "as of" hours ago, and must not
+ * render identically to one measured a minute ago. Threshold, not truth — hence settable.
+ */
+export const DEFAULT_STALE_AFTER_MS = 10 * 60_000;
+export const DEFAULT_PORT = 4477;
+/**
+ * Flag beats environment beats file beats default, settled INDEPENDENTLY per setting: a port
+ * pinned in the file and a threshold tightened for one run is the normal case, not an edge.
+ */
+export function resolveConfig({ flags, env, file, defaultSnapshotsDir }) {
+    // EVERY rung is parsed, including the ones about to lose. `readConfigFile` already refuses
+    // a bad key whoever wins; an environment that were only checked when it happens to win
+    // would make a stale TARMAC_STALE_AFTER in a shell profile break `tarmac list` on its own
+    // and pass the moment a flag is added — a setting silently dropped, which is the one thing
+    // this module exists to prevent.
+    const staleAfterEnv = parseIfSet(env.TARMAC_STALE_AFTER, (v) => parseDuration(v, 'TARMAC_STALE_AFTER'));
+    const portEnv = parseIfSet(env.TARMAC_PORT, (v) => parsePort(v, 'TARMAC_PORT'));
+    const dirEnv = read(env.TARMAC_SNAPSHOTS_DIR);
+    return {
+        staleAfterMs: flags.staleAfter !== null
+            ? { value: parseDuration(flags.staleAfter, '--stale-after'), source: 'flag' }
+            : staleAfterEnv !== null
+                ? { value: staleAfterEnv, source: 'env' }
+                : file.staleAfterMs !== undefined
+                    ? { value: file.staleAfterMs, source: 'file' }
+                    : { value: DEFAULT_STALE_AFTER_MS, source: 'default' },
+        port: flags.port !== null
+            ? { value: flags.port, source: 'flag' }
+            : portEnv !== null
+                ? { value: portEnv, source: 'env' }
+                : file.port !== undefined
+                    ? { value: file.port, source: 'file' }
+                    : { value: DEFAULT_PORT, source: 'default' },
+        snapshotsDir: flags.snapshotsDir !== null
+            ? { value: flags.snapshotsDir, source: 'flag' }
+            : dirEnv !== null
+                ? { value: dirEnv, source: 'env' }
+                : file.snapshotsDir !== undefined
+                    ? { value: file.snapshotsDir, source: 'file' }
+                    : { value: defaultSnapshotsDir, source: 'default' },
+    };
+}
+/**
+ * An empty environment variable is UNSET, not an empty value: `TARMAC_PORT= tarmac serve` is
+ * how a shell wrapper says "never mind", and refusing it there would break scripts that clear
+ * their own environment. The only place in this module where absence is inferred.
+ */
+const read = (v) => (v === undefined || v.trim() === '' ? null : v);
+/** Parse a variable that is set — win or lose — so a bad value is never carried in silence. */
+function parseIfSet(raw, parse) {
+    const v = read(raw);
+    return v === null ? null : parse(v);
+}

package/dist/discover.js

@@ -0,0 +1,26 @@
+// P1 — runs the contractual discovery command and hands its stdout to the parser.
+//
+// Fails loudly on every failure mode (binary missing, non-zero exit, unparseable output).
+// An observability tool that answers "0 sessions" when it simply could not look is worse
+// than one that answers nothing.
+import { execFile } from 'node:child_process';
+import { parseAgents } from './sessions.js';
+export function discoverSessions({ claudeBin = 'claude', timeoutMs = 15000 } = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(claudeBin, ['agents', '--json'], { timeout: timeoutMs, maxBuffer: 8 << 20 }, (err, stdout) => {
+            if (err) {
+                const why = err.code === 'ENOENT'
+                    ? `${claudeBin}: not found`
+                    : `${claudeBin} agents --json: exited ${err.code ?? '?'}${err.signal ? ` (${err.signal})` : ''}`;
+                reject(new Error(why));
+                return;
+            }
+            try {
+                resolve(parseAgents(stdout));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    });
+}

package/dist/fleet.js

@@ -0,0 +1,85 @@
+// P3 — the join. Two contractual sources, one row per live session.
+//
+//   `claude agents --json`  → who exists, and whether it is busy   (the spine)
+//   statusline snapshots    → context, model, effort, cost         (the flesh)
+//
+// The session list is the spine on purpose: a snapshot outlives its session (a recycled
+// fleet leaves seven dead files behind), so a snapshot with no live session is a ghost and
+// is dropped. The reverse — a session with no snapshot — is a real state and stays visible,
+// with telemetry marked `absent` rather than zeroed.
+//
+// `now` is a parameter, never `Date.now()` inside: a suite whose fixtures are absolute and
+// whose clock floats dies quietly the day it crosses a threshold.
+import path from 'node:path';
+import { DEFAULT_STALE_AFTER_MS } from './config.js';
+import { guardVersions } from './schema.js';
+export function buildFleet({ sessions, snapshots, now, staleAfterMs = DEFAULT_STALE_AFTER_MS, discovery = null, }) {
+    const rows = sessions.map((s) => {
+        const t = (s.sessionId && snapshots.get(s.sessionId)) || null;
+        return {
+            sessionId: s.sessionId,
+            name: s.name,
+            project: s.cwd ? path.basename(s.cwd) : null,
+            cwd: s.cwd,
+            pid: s.pid,
+            status: s.status,
+            busy: s.busy,
+            uptimeMs: typeof s.startedAt === 'number' ? now - s.startedAt : null,
+            ctxState: t ? t.ctxState : 'absent',
+            ctxPct: t ? t.ctxPct : null,
+            ctxTokens: t ? t.ctxTokens : null,
+            ctxWindow: t ? t.ctxWindow : null,
+            model: t ? t.model : null,
+            effort: t ? t.effort : null,
+            costUsd: t ? t.costUsd : null,
+            snapshotAgeMs: t ? t.ageMs : null,
+            stale: t ? t.ageMs > staleAfterMs : false,
+            rateLimits: t ? t.rateLimits : null,
+        };
+    });
+    rows.sort((a, b) => rank(a) - rank(b) || (b.ctxPct ?? -1) - (a.ctxPct ?? -1));
+    const covered = rows.filter((r) => r.ctxState !== 'absent').length;
+    const drift = rows.filter((r) => r.ctxState === 'drift').length;
+    // Having a snapshot and having a cost are different facts, and only the second one is
+    // allowed to feed the total.
+    const costs = rows.map((r) => r.costUsd).filter((c) => typeof c === 'number');
+    // Versions from the LIVE snapshots only — the same `sessions`-is-the-spine rule as
+    // everything else here. A recycled fleet leaves dead files behind, and a dead session's
+    // Claude Code is not the one running now.
+    const ccVersions = sessions
+        .map((s) => (s.sessionId ? snapshots.get(s.sessionId) : undefined))
+        .filter((t) => t !== undefined)
+        .map((t) => t.ccVersion);
+    return {
+        rows,
+        health: {
+            sessions: rows.length,
+            covered,
+            drift,
+            stale: rows.filter((r) => r.stale).length,
+            // Discovery's own blind spots. Dropping them turns a renamed `sessionId` into the
+            // cheerful "No Claude Code sessions found" — the exact lie the module forbids.
+            discovered: discovery?.seen ?? rows.length,
+            noSessionId: discovery?.noSessionId ?? 0,
+            // All the telemetry we DO have is drifting: that is a schema change, not a hiccup.
+            // Tested tolerance from the fleet: `fresh` never counts, or a recycled fleet would
+            // raise this every single night.
+            schemaBroken: covered > 0 && drift === covered,
+            unknownStatus: rows.filter((r) => r.busy === null).length,
+            busy: rows.filter((r) => r.busy === true).length,
+            // A sum over 3 of 7 sessions is not the fleet's cost. Same rule as `sumUsage` one
+            // layer down: add only what is really a number, and count those — a payload with no
+            // `cost` key used to contribute a confident 0 while counting as covered, which made a
+            // partial sum print as a complete one. Null when nothing was measured; the renderers
+            // qualify the total with `costReporting` whenever it is partial.
+            costUsd: costs.length === 0 ? null : round2(costs.reduce((sum, c) => sum + c, 0)),
+            costReporting: costs.length,
+            schemaGuard: guardVersions(ccVersions),
+            staleAfterMs,
+            generatedAt: now,
+        },
+    };
+}
+// busy first, then unknown (it might be busy), then idle
+const rank = (r) => (r.busy === true ? 0 : r.busy === null ? 1 : 2);
+const round2 = (n) => Math.round(n * 100) / 100;

package/dist/install.js

@@ -0,0 +1,387 @@
+// P2 — the installer, on disk.
+//
+// CONSENT, NOT A GUARD: the spike refused the real HOME outright, which is exactly the one
+// thing a released tool must be able to do. What stands in its place is `planInstall` /
+// `planUninstall` — a dry run that reads only, names the file, quotes the command it will
+// wrap and spells out the way back — plus the typed confirmation in `prompt.ts`. Nothing
+// here decides on the user's behalf; every refusal below is about a state we cannot undo,
+// never about which directory it is.
+//
+// The suite still never reaches the real home: `os.homedir()` reads $HOME, so the tests
+// that exercise the default target run under a throwaway one.
+//
+// Reversibility model — two levels, because "byte for byte" and "do not clobber the user's
+// later edits" cannot both hold unconditionally:
+//   • settings.json untouched since we wrote it  → restore the ORIGINAL BYTES verbatim
+//     (indentation, key order, trailing newline — everything).
+//   • settings.json edited since                 → surgical restore of the statusLine key
+//     only, everything else the user wrote is kept (re-serialised, so formatting may move).
+// Which of the two ran is reported back to the caller, never guessed at silently.
+import fs from 'node:fs';
+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) {
+    const claude = path.join(home, '.claude');
+    const dir = path.join(claude, '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'),
+        config: path.join(dir, 'config.json'),
+    };
+}
+// 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) {
+    try {
+        const sa = fs.statSync(a);
+        const sb = fs.statSync(b);
+        return sa.dev === sb.dev && sa.ino === sb.ino;
+    }
+    catch {
+        // one of them does not exist yet — fall back to the strongest textual comparison
+        return realpathOrSelf(a) === realpathOrSelf(b);
+    }
+}
+function realpathOrSelf(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+// A home that is not there is a typo, not an instruction. Creating `<typo>/.claude/tarmac/`
+// and reporting success is how someone ends up believing tarmac watches a directory nothing
+// will ever write to — the same failure `args.ts` refuses for a misspelled flag.
+function requireHome(home) {
+    if (!home)
+        throw new Error('a HOME is required');
+    const root = path.resolve(home);
+    let stat;
+    try {
+        stat = fs.statSync(root);
+    }
+    catch {
+        throw new Error(`${root} does not exist — pass --home a directory that does`);
+    }
+    if (!stat.isDirectory())
+        throw new Error(`${root} is not a directory`);
+    return root;
+}
+/** @throws if settings.json exists and is not JSON — the one file we must never mangle. */
+function readSettings(p) {
+    const text = fs.existsSync(p.settings) ? fs.readFileSync(p.settings, 'utf8') : null;
+    let settings = {};
+    if (text !== null && text.trim() !== '') {
+        try {
+            settings = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${p.settings} is not valid JSON — refusing to touch it`);
+        }
+    }
+    return { text, settings };
+}
+/**
+ * On a re-install the original statusLine lives in the backup — never in the current
+ * settings, which already point at us. If that backup is gone, unreadable or shapeless we
+ * can no longer NAME what we wrapped: regenerating the wrapper from that hole would
+ * silently drop the user's real statusline forever. Refuse, and touch nothing.
+ */
+function backupOrRefuse(p) {
+    const backup = readBackup(p);
+    if (!isUsableBackup(backup)) {
+        throw new Error(`${p.settings} already points at the tarmac wrapper but its backup (${p.backup}) is missing, unreadable or incomplete — ` +
+            `refusing to regenerate the wrapper, which would drop the statusline it wraps. ` +
+            `Restore the backup, or point statusLine back at your own command and install again.`);
+    }
+    return backup;
+}
+// "The exact command that undoes it" has to survive being pasted back into a shell, and a
+// home with a space in its name is an ordinary macOS home — `quoteArg` lives in `shell.ts`
+// next to the reader that undoes it.
+const undoCommand = (verb, home, isRealHome) => isRealHome ? `tarmac ${verb}` : `tarmac ${verb} --home ${quoteArg(home)}`;
+/**
+ * The file a write to `file` really reaches. `realpath` cannot answer this: it fails on a
+ * DANGLING link — a dotfiles repo not cloned yet is exactly that — and the fallback then
+ * renames over the link, replacing it with a regular file. Following the links by hand
+ * lands where a shell's `>` would, and creates the file the link names.
+ */
+function resolveWriteTarget(file) {
+    let current = file;
+    for (let hops = 0; hops < 10; hops++) {
+        let link;
+        try {
+            link = fs.readlinkSync(current);
+        }
+        catch {
+            return current; // not a link (or unreadable): this is the file
+        }
+        current = path.resolve(path.dirname(current), link);
+    }
+    return current; // a loop of links: stop somewhere rather than spin
+}
+/** …and say so, when that is not the path the plan names. */
+function writesInstead(file) {
+    const target = resolveWriteTarget(file);
+    return target === file ? null : target;
+}
+export function planInstall({ home, realHome = os.homedir() }) {
+    const root = requireHome(home);
+    const p = paths(root);
+    const { settings } = readSettings(p);
+    const { previous, alreadyInstalled } = chainStatusLine(settings, p.wrapper, {
+        isSameCommand: (command, wrapper) => isWrapperCommand(command, root, wrapper),
+        commandSpelling: quoteArg(p.wrapper),
+    });
+    const isRealHome = sameFile(root, realHome);
+    const before = commandOf(settings.statusLine);
+    return {
+        action: 'install',
+        home: root,
+        settings: p.settings,
+        wrapper: p.wrapper,
+        isRealHome,
+        writes: writesInstead(p.settings),
+        before,
+        // A re-install regenerates the wrapper and leaves settings.json alone, so announcing a
+        // new value there would be a plan disagreeing with what runs.
+        after: alreadyInstalled ? before : quoteArg(p.wrapper),
+        chained: alreadyInstalled ? (backupOrRefuse(p).previous?.command ?? null) : (previous?.command ?? null),
+        alreadyInstalled,
+        undo: undoCommand('uninstall', root, isRealHome),
+    };
+}
+/** The statusLine command as written, or `null` when there is none to read. */
+function commandOf(statusLine) {
+    const command = statusLine?.command;
+    return typeof command === 'string' ? command : null;
+}
+/**
+ * Is `command` the very wrapper at `wrapperPath`, under any spelling?
+ *
+ * `stat` of the raw string is not an answer: `statusLine.command` is read by a shell, and
+ * `~/…` — how this machine's own production statusline is written — stats to nothing. A
+ * tarmac that fails to recognise itself there wraps its own wrapper (unbounded recursion at
+ * every frame) AND rewrites the backup with the wrapper as "what we wrapped", erasing the
+ * only record of the user's real statusline. So: resolve the spellings a shell would, then
+ * ask the file itself, which carries a marker no other file has a reason to.
+ */
+function isOurWrapperPath(command, home, wrapperPath) {
+    return sameFile(commandTarget(command, home), wrapperPath);
+}
+/**
+ * Deciding whether to WRAP something: path identity, or the file saying what it is. Over-
+ * claiming here fails closed — tarmac refuses instead of nesting a wrapper in a wrapper.
+ *
+ * Deciding whether to OVERWRITE something (uninstall) is the opposite risk, so it asks
+ * `isOurWrapperPath` alone: a script of the user's that merely mentions the wrapper stays
+ * foreign, and foreign still means "nothing is restored and nothing is deleted".
+ */
+function isWrapperCommand(command, home, wrapperPath) {
+    return isOurWrapperPath(command, home, wrapperPath) || carriesWrapperMarker(commandTarget(command, home));
+}
+/**
+ * The file a statusLine command refers to.
+ *
+ * `~`, `$HOME` and `${HOME}` are resolved against `home` — the home whose settings.json this
+ * is — not against the process's own. `--home` exists precisely to work on someone else's
+ * `.claude`, and the shell that will run that line runs under THAT home.
+ */
+function commandTarget(command, home) {
+    const s = command.trim();
+    for (const [prefix, cut] of [['~/', 2], ['$HOME/', 6], ['${HOME}/', 8]]) {
+        if (s.startsWith(prefix))
+            return path.join(home, firstWord(s.slice(cut)));
+    }
+    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.
+ */
+function carriesWrapperMarker(file) {
+    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);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * 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
+ * is the PRESENCE of the key — the same rule this codebase applies to `used_percentage`.
+ */
+function isUsableBackup(b) {
+    return (!!b &&
+        typeof b === 'object' &&
+        b.version === 1 &&
+        'previous' in b &&
+        'originalText' in b);
+}
+export function install({ home }) {
+    const root = requireHome(home);
+    const p = paths(root);
+    const { text: originalText, settings } = readSettings(p);
+    const { settings: next, previous, alreadyInstalled } = chainStatusLine(settings, p.wrapper, {
+        isSameCommand: (command, wrapper) => isWrapperCommand(command, root, wrapper),
+        commandSpelling: quoteArg(p.wrapper),
+    });
+    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 };
+    }
+    fs.mkdirSync(p.dir, { recursive: true });
+    fs.mkdirSync(p.snapshots, { recursive: true });
+    writeWrapper(p, previous?.command ?? null, root);
+    // Order matters: the backup is the only way back, so it must be on disk BEFORE
+    // settings.json sends Claude Code to the wrapper. Crashing between the two otherwise
+    // locks the user out of install (backup missing) and uninstall (no install found) at once.
+    const installedText = JSON.stringify(next, null, 2) + '\n';
+    fs.writeFileSync(p.backup, JSON.stringify({ version: 1, originalText, installedText, previous, installedAt: new Date().toISOString() }, null, 2));
+    writeAtomic(p.settings, installedText);
+    return { alreadyInstalled: false, previous, ...p };
+}
+/** Never let the wrapper chain to itself, whatever spelling the caller used. */
+function writeWrapper(p, chainCommand, home) {
+    if (chainCommand && isWrapperCommand(chainCommand, home, p.wrapper)) {
+        throw new Error(`refusing to chain the tarmac wrapper to itself (${chainCommand})`);
+    }
+    fs.writeFileSync(p.wrapper, renderWrapper({ snapshotDir: p.snapshots, chainCommand }), { mode: 0o755 });
+}
+// Claude Code re-reads settings.json at frame cadence: a truncated read window is real.
+//
+// Two things the rename must not quietly destroy, both invisible in a diff of the contents:
+//   • a SYMLINK. settings.json kept in a dotfiles repo and linked into place is the normal
+//     setup for the people who install a tool like this; renaming over the link replaces it
+//     with a regular file, the dotfile silently stops being the source of truth, and no
+//     restore puts the link back. So the write follows the link and lands on its target.
+//   • the MODE. `-rw-------` is a decision; a restore that hands the file back
+//     world-readable is not the file the user had, whatever the bytes say.
+function writeAtomic(file, text) {
+    const target = resolveWriteTarget(file);
+    const tmp = `${target}${TEMP_PREFIX}${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text);
+    const mode = modeOf(target);
+    if (mode !== null)
+        fs.chmodSync(tmp, mode); // after the write: umask masks the create mode
+    fs.renameSync(tmp, target);
+}
+/** The permission bits of an existing file, or `null` when we are creating it. */
+function modeOf(file) {
+    try {
+        return fs.statSync(file).mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}
+export function planUninstall({ home, realHome = os.homedir() }) {
+    const root = requireHome(home);
+    const p = paths(root);
+    const backup = installedBackupOrRefuse(p);
+    // Through `readSettings`, so a settings.json that stopped being JSON since install is
+    // named, not reported as a raw parser position nobody can act on.
+    const { text: currentText, settings: current } = readSettings(p);
+    // Predicted by asking the same two questions `uninstall` asks, in the same order. The
+    // surgical branch is a pure function, so the prediction runs it and throws the result away.
+    let mode;
+    let after;
+    if (currentText === backup.installedText) {
+        mode = backup.originalText === null ? 'absent' : 'bytes';
+        after = backup.previous?.command ?? null;
+    }
+    else {
+        const { settings, restored } = unchainStatusLine(current, backup.previous, p.wrapper, {
+            isSameCommand: (command, wrapper) => isOurWrapperPath(command, root, wrapper),
+        });
+        mode = restored ? 'surgical' : 'foreign';
+        after = restored ? commandOf(settings.statusLine) : commandOf(current.statusLine);
+    }
+    const isRealHome = sameFile(root, realHome);
+    return {
+        action: 'uninstall',
+        home: root,
+        settings: p.settings,
+        wrapper: p.wrapper,
+        isRealHome,
+        writes: writesInstead(p.settings),
+        before: commandOf(current.statusLine),
+        after,
+        mode,
+        undo: undoCommand('install', root, isRealHome),
+    };
+}
+function installedBackupOrRefuse(p) {
+    const backup = readBackup(p);
+    if (!isUsableBackup(backup))
+        throw new Error(`no tarmac install found under ${p.dir}`);
+    return backup;
+}
+export function uninstall({ home }) {
+    const root = requireHome(home);
+    const p = paths(root);
+    const backup = installedBackupOrRefuse(p);
+    const currentText = fs.existsSync(p.settings) ? fs.readFileSync(p.settings, 'utf8') : null;
+    let mode;
+    if (currentText === backup.installedText) {
+        // untouched since install → put the original bytes back, or remove the file we created
+        if (backup.originalText === null) {
+            fs.rmSync(p.settings, { force: true });
+            mode = 'absent';
+        }
+        else {
+            writeAtomic(p.settings, backup.originalText);
+            mode = 'bytes';
+        }
+    }
+    else {
+        const current = currentText ? JSON.parse(currentText) : {};
+        const { settings, restored } = unchainStatusLine(current, backup.previous, p.wrapper, {
+            isSameCommand: (command, wrapper) => isOurWrapperPath(command, root, wrapper),
+        });
+        if (!restored) {
+            // The statusLine is someone else's now — possibly still pointing AT our wrapper's
+            // path through another route. Deleting the wrapper here would leave that line
+            // executing a file that no longer exists, at every frame, with no way back.
+            return { mode: 'foreign' };
+        }
+        writeAtomic(p.settings, JSON.stringify(settings, null, 2) + '\n');
+        mode = 'surgical';
+    }
+    // Snapshots 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 };
+}
+function readBackup(p) {
+    if (!fs.existsSync(p.backup))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p.backup, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}