@adrrr/tarmac 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Leboeuf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# tarmac
+
+**Fleet observability for Claude Code.** One table for every session you have running —
+busy or idle, how full its context is, which model, what it has cost so far.
+
+```
+$ npx @adrrr/tarmac list
+
+PROJECT            STATE  CTX      AS OF  MODEL    EFFORT  COST    UP
+apollo             busy   28%      7m     Fable 5  max     $53.98  8h
+mercury-dashboard  busy   27%      22m !  Fable 5  max     $70.62  8h
+gemini             idle   12%      3h !   Opus 5   high    $3.14   8h
+atlas              idle   — fresh  8h !   Opus 5   high    $0.00   8h
+
+! 3 reading(s) marked "!" are older than the freshness threshold
+
+4 sessions · 2 busy · $127.74
+```
+
+## Why it does not break
+
+Every other way to watch a Claude Code fleet reads something Claude Code never promised
+would stay put: transcript files, terminal panes, undocumented paths. Those tools break on
+an update, and — worse — they break *quietly*, reporting a calm empty fleet.
+
+tarmac reads two things instead:
+
+| Source | What it gives | How solid |
+|---|---|---|
+| `claude agents --json` | which sessions exist, busy or idle, cwd, uptime | a documented CLI surface (`--help`: *"Print active sessions … as a JSON array … for scripting"*) |
+| the status line payload | context %, model, effort, cost | the JSON Claude Code hands to your own `statusLine.command` on every frame — **observed, not published as a schema** |
+
+That second line is the honest caveat, and it is the reason the real defence is not
+immunity, it is **visible degradation**. When a field moves, tarmac says the field moved.
+It never turns a measurement it could not take into a confident `0`.
+
+| What tarmac sees | What it shows |
+|---|---|
+| a percentage | the percentage |
+| the key is there but null | `— no turn yet` (a session that has not taken a turn) |
+| the key is gone or retyped | `— schema drift`, and a warning if it happened to every session |
+| no snapshot for a live session | `— not chained` |
+| a reading older than the threshold | the value, **dated** — a stale number is still true, of an earlier moment |
+| a status string it does not know | that string, never "idle" |
+| a snapshot directory it could not read | the errno, not "run tarmac install" |
+| a cost key that is absent | `—` for the row, and a total qualified by how many sessions really report one |
+| a Claude Code version no fixture covers | a notice naming that version — nothing blocked, nothing hidden |
+
+That last line is the smoke detector to the rest's alarm. The fields above were *observed*
+on the Claude Code builds frozen in `fixtures/`; when a session shows up on a build nobody
+has captured, tarmac says so **before** anything breaks, and keeps reporting. It reads the
+version off the payload itself, so it tells you about builds actually writing to your fleet
+— not about the `claude` on your PATH.
+
+## Install
+
+```bash
+npx @adrrr/tarmac install      # chain the status line under ~/.claude, after showing you what changes
+npx @adrrr/tarmac list         # one-shot table
+npx @adrrr/tarmac list --watch # the same table, redrawn every 5s until ^C
+npx @adrrr/tarmac serve        # dashboard on http://127.0.0.1:4477
+npx @adrrr/tarmac uninstall    # put your status line back, exactly
+```
+
+Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing to audit.
+
+`install` and `uninstall` change a file your terminal reads on every frame, so neither runs
+on your say-so alone. Both print the plan first — the settings file, what `statusLine` says
+now, what it will say, the command that is being wrapped, and the exact command that undoes
+it — and then wait for you to **type the verb**:
+
+```
+tarmac install — your home
+
+  file             /Users/you/.claude/settings.json
+  statusLine now   ~/bin/my-line.sh
+  statusLine next  /Users/you/.claude/tarmac/statusline.sh
+  ↳ which calls    ~/bin/my-line.sh   (your display is unchanged)
+  undo             tarmac uninstall
+
+Type "install" to proceed, anything else to abort:
+```
+
+`y` is not an answer, and neither is silence: with stdin not a terminal — a pipe, a CI job —
+tarmac refuses rather than read consent from an unanswerable prompt. Scripts pass `--yes`,
+deliberately and in writing.
+
+`--home DIR` points either command at another home; it selects a target, nothing more.
+**Pass the same `--home` to `list` and `serve`**, which default to yours: installing into
+`DIR` and then running a bare `list` reads a directory nothing was ever written to, and
+reports `statusline chained on 0/1 sessions` — a true statement about the wrong directory.
+
+`install` does not replace your status line, it **wraps** it: the wrapper drops the payload
+in `DIR/.claude/tarmac/snapshots/` and then calls whatever command was already configured,
+so your display is byte-identical. `uninstall` restores the original `settings.json` verbatim
+when you have not edited it since, and surgically (statusLine key only) when you have. If
+someone else has taken over the status line in the meantime, tarmac leaves it alone and
+tells you it restored nothing.
+
+The only thing tarmac ever deletes is its own litter: at `serve` start it removes temp
+files an interrupted wrapper left behind — over an hour old, and **signed**, meaning named
+`.tarmac-<session>.<pid>.tmp`, a name nothing but tarmac writes. It will not touch a file
+merely *shaped* like one of ours, because `.<name>.<pid>.tmp` is the temp-file convention of
+half the world. Your snapshots survive `uninstall`; they are your data.
+
+The corollary is a small one-time chore: temp files left by a **pre-signature build** of the
+wrapper (named `.<session>.<pid>.tmp`, without the `tarmac-` mark) are never reaped either —
+nothing in that name says we wrote it. If you ran one, clear them yourself, once, looking
+before you delete in case the directory has another writer:
+
+```bash
+ls -l DIR/.claude/tarmac/snapshots/.*.tmp   # look first
+rm DIR/.claude/tarmac/snapshots/.*.tmp      # then remove what you recognise
+```
+
+## Commands
+
+| Command | What it does | Options |
+|---|---|---|
+| `tarmac list` | one-shot fleet table | `--home`, `--stale-after`, `--snapshots-dir`, `--claude-bin`, `--json`, `--watch` |
+| `tarmac serve` | local dashboard, `GET /` for the page, `GET /live` for the fragment it refreshes, `GET /api/fleet` for JSON | `--home`, `--port`, `--stale-after`, `--snapshots-dir`, `--claude-bin` |
+| `tarmac install` | chain the status line under `<home>/.claude/settings.json`, after confirmation | `--home`, `--yes` |
+| `tarmac uninstall` | restore it, and say which of the four restore modes ran | `--home`, `--yes` |
+
+`--help` works everywhere. An option handed to a command that does not read it is an
+**error**, not something quietly ignored — `tarmac serve --json` would otherwise parse
+cleanly and answer HTML anyway, which is indistinguishable from a bug.
+
+### Staying open
+
+Both live views owe you the same two facts, and neither is allowed to be quiet about them:
+**when the last good reading arrived**, and **whether the last attempt to refresh failed**.
+
+The page asks the server for `/live` every 5 seconds and swaps it in; the header carries an
+age that keeps climbing whether or not the refresh works, so numbers that have stopped moving
+cannot pass for live ones. When a poll fails, a banner names the reason and the table is
+framed off — the data stays, because it is still true of an earlier moment. `list --watch`
+does the same thing in the terminal, and prints `! refresh failing — <reason>` above a table
+it refuses to throw away.
+
+Three failures are handled by name, because each of them can otherwise look like health:
+
+- **A refusal** (`serve` is gone) — the banner names it on the next poll.
+- **An empty answer.** A 200 carrying nothing is not a fleet of nothing. Swapping it in would
+  blank the table and stamp it "updated 0s ago" with the dot still green, which is this tool's
+  own failure mode wearing its own colours. It counts as a failed refresh.
+- **No answer at all.** `fetch` has no timeout in any browser, so a server that accepts the
+  connection and goes quiet would leave the request pending forever. After 20 seconds — above
+  the collector's own 15s timeout, so a slow-but-healthy fleet always fails server-side first
+  with a real reason — the page gives up on it, says so, and asks again. An answer to a
+  request it already gave up on is discarded rather than allowed to overwrite a newer one.
+
+On a terminal `--watch` redraws once a second while it waits, so the age is never more than a
+second out of date and a hung read shows a counter that has visibly stopped. Piped, it writes
+one frame per read — there is no screen to keep current, and a frame a second is just noise.
+
+It is a poll and not a meta refresh or SSE, deliberately. A meta refresh cannot render its
+own failure: when `serve` dies the browser throws the page away and shows its own error page,
+taking the one useful fact with it. SSE would hold a socket per tab and drive
+`claude agents --json` from a server-side timer for readers whose laptop is asleep — with a
+poll, a hidden tab simply stops asking, and a waking one asks at once.
+
+Everything a reader interprets is rendered on the server. The browser owns two facts and no
+rules: re-deriving "a dash, never a zero" in page JavaScript would put a second copy of it
+where the test suite cannot reach.
+
+## Configuration
+
+Three of tarmac's numbers are opinions, not truths, so all three are yours to set. Nothing
+else is configurable, and every one of them keeps working with no configuration at all.
+
+| Setting | What it decides | Default |
+|---|---|---|
+| freshness threshold | how old a reading may be before it is marked `!` | `10m` |
+| port | where `serve` listens | `4477` |
+| snapshots directory | where `list` and `serve` **read** payloads from | `<home>/.claude/tarmac/snapshots` |
+
+**Flag beats environment beats config file beats default**, settled per setting — a port
+pinned in the file and a threshold tightened for one run is the normal case.
+
+| Setting | Flag | Environment | `~/.claude/tarmac/config.json` |
+|---|---|---|---|
+| freshness | `--stale-after 90s` \| `15m` \| `2h` | `TARMAC_STALE_AFTER` (same spelling) | `"staleAfterMs": 90000` |
+| port | `--port 8080` | `TARMAC_PORT` | `"port": 8080` |
+| snapshots | `--snapshots-dir DIR` | `TARMAC_SNAPSHOTS_DIR` | `"snapshotsDir": "DIR"` |
+
+```json
+{ "staleAfterMs": 900000, "port": 8080 }
+```
+
+`tarmac serve` opens by printing each effective value **and which of the four sources it
+came from**, and the freshness threshold is named in every warning that puts a `!` on a
+reading — a mark whose threshold is invisible is one you cannot argue with.
+
+Nothing here is ever silently dropped. A duration that will not parse, a port out of range,
+a key that does not exist, a file that is not JSON, a file that exists but cannot be read —
+each one stops the run and says what it got, where it came from, and what would have worked.
+**Including the ones that lose**: a broken `TARMAC_STALE_AFTER` is refused even when a flag
+was going to beat it, so a stale variable in a shell profile cannot lurk until the day you
+drop the flag.
+
+```
+$ TARMAC_STALE_AFTER=soon tarmac list
+tarmac: TARMAC_STALE_AFTER must be a positive duration like 90s, 15m or 2h, got: soon
+```
+
+A bare number is refused on purpose: `600000` is ten minutes in milliseconds and a week in
+seconds, and picking one for you is exactly the silent correction the rest of this tool
+refuses. An empty environment variable (`TARMAC_PORT= tarmac serve`) means unset, not empty.
+
+Two edges worth knowing:
+
+- **No config file is not an error** — it is the zero-config contract. `install` and
+  `uninstall` never read the file at all, so a typo in it can never be what stands between
+  you and putting your status line back.
+- The snapshots directory is a **read-side** setting, exactly like the flag it mirrors.
+  The wrapper writes where `install` put it, under `<home>/.claude/tarmac/snapshots`. Point
+  the reader at a directory that does not exist and tarmac says so, naming the path and the
+  setting that sent it there — it is only the **default** being absent that means "nothing
+  has been chained yet", because that is the one directory nobody chose.
+
+The dashboard binds to loopback and refuses any request whose `Host` is not loopback —
+a DNS-rebinding page in your own browser would otherwise read your cwd paths and costs.
+That guard runs before routing, so it covers `/live` and `/api/fleet` as well as the page.
+
+## What V1 does not do
+
+- **No "waiting for you" signal.** The obvious missing column — which session is blocked on
+  a human — is deliberately absent: the status line payload carries nothing that means it,
+  and `agents --json` reports `idle` for a session waiting on you and for one that finished.
+  Inferring it would mean reading a transcript, which is the one thing this tool will not do.
+- **No history.** Each run is a snapshot in time; context and cost curves come later.
+- **No Windows.** The generated wrapper is POSIX `sh`.
+- **No remote fleets.** It watches the machine it runs on.
+
+## Development
+
+```bash
+npm test           # typecheck (src + test + scripts), then run the suite
+npm run build      # flat JavaScript into dist/
+```
+
+CI runs the suite on Node 22 and 24, on Linux and macOS, with `TARMAC_REQUIRE_DASH=1` so a
+machine without dash cannot report a green build it did not earn; a separate job builds
+`dist/` and runs it on Node 20 — the oldest version `engines` promises, and the only place
+the published artefact is ever executed. Releases are cut by hand: see
+[PUBLISHING.md](PUBLISHING.md).
+
+### Capturing a new Claude Code version
+
+When tarmac reports a version it has never checked, capture the pair — both surfaces from
+one build, in one command, with tarmac installed and a session of that build having drawn
+at least one frame:
+
+```bash
+npm run fixtures:capture
+```
+
+It writes `fixtures/agents-<version>.json` and `fixtures/statusline-payload-<version>-*.json`
+verbatim, then tells you to add the version to `CHECKED_VERSIONS` in `src/schema.ts` — the
+suite fails while the constant and the directory disagree, which is what keeps the guard
+from claiming a coverage nobody verified. **Read both files before committing, and scrub
+them**: they come off your machine carrying real paths, session names and costs. The
+fixtures in this repo are the real shapes with synthetic values, and that is the standard a
+new one has to meet.
+
+The suite runs the TypeScript sources directly through Node's type stripping, so it needs
+Node ≥ 22.18 to *develop*; what ships in `dist/` is plain ES2022 and runs on Node ≥ 20.
+
+## License
+
+MIT

package/dist/args.js

@@ -0,0 +1,93 @@
+// Tiny argv parser. `node:util.parseArgs` would do, but a hand-rolled one keeps the error
+// messages actionable and the surface exactly as wide as the commands we support.
+//
+// Unknown options and unknown commands are ERRORS. A typo silently ignored is how someone
+// ends up believing they pointed tarmac at a directory it never read.
+import { parsePort } from './config.js';
+const COMMANDS = new Set(['list', 'serve', 'install', 'uninstall', 'help']);
+// `| undefined` is load-bearing, not decoration: without it the compiler types the lookup
+// below as always-present and the `if (!key) throw` guard reads as dead code — which is how
+// a future cleanup deletes the one thing standing between a typo and a silently ignored flag.
+const OPTIONS = {
+    '--port': 'port',
+    '--stale-after': 'staleAfter',
+    '--snapshots-dir': 'snapshotsDir',
+    '--home': 'home',
+    '--claude-bin': 'claudeBin',
+    '--json': 'json',
+    '--watch': 'watch',
+    '--yes': 'yes',
+    '--help': 'help',
+};
+const FLAGS = new Set(['json', 'watch', 'yes', 'help']);
+/**
+ * Which options each command really reads. The doc-comment above refuses a flag nobody
+ * implements; this refuses a flag THIS command does not implement, which is the same defect
+ * one level down — `tarmac serve --json` parsed cleanly and changed nothing, and from the
+ * outside that is indistinguishable from a server that decided to answer HTML anyway.
+ *
+ * `help` is in every set on purpose: `--help` is answerable whatever else was typed.
+ */
+const ACCEPTS = {
+    list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help']),
+    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'help']),
+    install: new Set(['home', 'yes', 'help']),
+    uninstall: new Set(['home', 'yes', 'help']),
+    help: new Set(['help']),
+};
+/** The commands a misplaced flag would have been right on — an error that points somewhere. */
+function ownersOf(key) {
+    return Object.keys(ACCEPTS).filter((c) => c !== 'help' && ACCEPTS[c].has(key)).join(', ');
+}
+/** Every flag this parser knows, so a documentation check can enumerate rather than guess. */
+export const OPTION_FLAGS = Object.keys(OPTIONS);
+/**
+ * Does `command` read `flag`? Exported for the test that holds `--help` to this matrix:
+ * asking the parser is the only way to check that does not go through the wording of an
+ * error message, which a reword would silently turn into a test that greens on everything.
+ */
+export function accepts(command, flag) {
+    const key = OPTIONS[flag];
+    return key !== undefined && ACCEPTS[command].has(key);
+}
+export function parseArgs(argv) {
+    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, home: null, claudeBin: 'claude', json: false, watch: false, yes: false, help: false };
+    let i = 0;
+    if (argv[0] && !argv[0].startsWith('-')) {
+        if (!COMMANDS.has(argv[0]))
+            throw new Error(`unknown command: ${argv[0]}`);
+        out.command = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const [flag, inline] = splitInline(argv[i]);
+        const key = OPTIONS[flag];
+        if (!key)
+            throw new Error(`unknown option: ${flag}`);
+        if (!ACCEPTS[out.command].has(key))
+            throw new Error(`${flag} is not an option of \`tarmac ${out.command}\` — it belongs to: ${ownersOf(key)}`);
+        if (FLAGS.has(key)) {
+            out[key] = true;
+            continue;
+        }
+        const value = inline ?? argv[++i];
+        // An EMPTY value is no value: `--snapshots-dir=` used to sail through as an empty path,
+        // and the fleet then read the process's cwd and reported a calm "nothing is chained".
+        // The config file has always refused an empty path; the flags refuse it in the same words.
+        if (value === undefined || value.trim() === '')
+            throw new Error(`${flag} needs a value`);
+        if (key === 'port') {
+            // Same validator the environment and the config file go through, so a port is refused
+            // in the same words wherever it was set.
+            out.port = parsePort(value, '--port');
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function splitInline(arg) {
+    const eq = arg.indexOf('=');
+    return eq === -1 ? [arg, null] : [arg.slice(0, eq), arg.slice(eq + 1)];
+}

package/dist/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// tarmac — fleet observability for Claude Code.
+//
+// Two contractual surfaces, zero internal formats:
+//   `claude agents --json`   → which sessions exist, busy or idle
+//   statusLine payload       → context, model, effort, cost (via a chained wrapper)
+//
+// `install` / `uninstall` default to the home this process runs under, print what they are
+// about to change, and proceed only on the typed verb (or `--yes`, in writing, for scripts).
+import os from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs } from './args.js';
+import { collectFleet } from './collect.js';
+import { readConfigFile, resolveConfig, SOURCE_PHRASE } from './config.js';
+import { createFleetServer } from './server.js';
+import { install, uninstall, paths, planInstall, planUninstall } from './install.js';
+import { confirmTyped } from './prompt.js';
+import { reapOrphanedTemps } from './reap.js';
+import { renderPlan, renderSettings, renderTable, restoreMeaning } from './render.js';
+import { runWatch } from './watch.js';
+const USAGE = `tarmac — fleet observability for Claude Code
+
+  tarmac list       [--home DIR] [--stale-after D] [--snapshots-dir DIR]
+                    [--claude-bin PATH] [--json] [--watch]
+        one-shot fleet table — with --watch, redrawn every 5s until ^C
+  tarmac serve      [--home DIR] [--port N] [--stale-after D] [--snapshots-dir DIR]
+                    [--claude-bin PATH]
+        local dashboard
+  tarmac install    [--home DIR] [--yes]
+        chain the statusline
+  tarmac uninstall  [--home DIR] [--yes]
+        restore the statusline exactly
+
+  --watch          redraw the table every 5s until ^C, dating every reading
+  --home           whose .claude to read or change (default: this home)
+  --yes            skip the typed confirmation — required when stdin is not a terminal
+  --stale-after    how old a reading may be before it is marked "!" — 90s, 15m, 2h
+                   (default: 10m)
+  --port           the dashboard's port (default: 4477)
+  --snapshots-dir  where the chained statusline drops its payloads
+                   (default: <home>/.claude/tarmac/snapshots)
+  --claude-bin     path to the claude CLI (default: claude)
+
+  Those three settings can also be set, in decreasing order of precedence, by the
+  environment (TARMAC_STALE_AFTER, TARMAC_PORT, TARMAC_SNAPSHOTS_DIR) and by
+  <home>/.claude/tarmac/config.json ({"staleAfterMs": …, "port": …, "snapshotsDir": …}).
+  \`serve\` prints which one won.
+`;
+try {
+    // Parsing is inside the try so that a refusal — a typo'd flag, a duration nobody can read,
+    // a config file with a key that does not exist — reaches the user as one line naming the
+    // knob to turn, and never as a stack trace.
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || args.command === 'help') {
+        process.stdout.write(USAGE);
+        process.exit(0);
+    }
+    if (args.command === 'install' || args.command === 'uninstall') {
+        const home = args.home ?? os.homedir();
+        // The plan is computed first and printed whole: every refusal this operation has in it
+        // fires here, so the prompt never appears for something that was going to fail anyway.
+        const plan = args.command === 'install' ? planInstall({ home }) : planUninstall({ home });
+        process.stdout.write(renderPlan(plan));
+        const confirmed = await confirmTyped({
+            word: args.command,
+            input: process.stdin,
+            output: process.stdout,
+            isTTY: Boolean(process.stdin.isTTY),
+            yes: args.yes,
+        });
+        // One exit path for everything that refuses, so nothing can leave a half-written stream
+        // behind on the way out.
+        if (!confirmed)
+            throw new Error('not confirmed — nothing was changed');
+        if (plan.action === 'install') {
+            const res = install({ home });
+            console.log(res.alreadyInstalled
+                ? `install: already installed — wrapper regenerated, settings.json left alone`
+                : `install: statusLine wrapped — undo with \`${plan.undo}\``);
+        }
+        else {
+            const { mode } = uninstall({ home });
+            console.log(`uninstall: ${mode} — ${restoreMeaning(mode)}`);
+        }
+    }
+    else {
+        // Only the reading commands resolve settings, and only they read the config file: a
+        // typo in it must not be what stands between a user and `tarmac uninstall`.
+        const p = paths(args.home ?? os.homedir());
+        const config = resolveConfig({
+            flags: { staleAfter: args.staleAfter, port: args.port, snapshotsDir: args.snapshotsDir },
+            env: process.env,
+            file: readConfigFile(p.config),
+            defaultSnapshotsDir: p.snapshots,
+        });
+        const snapshotsDir = config.snapshotsDir.value;
+        const staleAfterMs = config.staleAfterMs.value;
+        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
+            // 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);
+            if (reaped > 0)
+                console.log(`tarmac: reaped ${reaped} orphaned snapshot temp file(s)`);
+            if (failed > 0)
+                console.error(`tarmac: could not remove ${failed} orphaned temp file(s) under ${snapshotsDir}`);
+            const server = createFleetServer({
+                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source }),
+            });
+            // `listen` fails asynchronously, long after this try block has been left behind, so
+            // its refusal needs its own way out: a port already taken is the ordinary failure of a
+            // port pinned in a config file, and it has to read like every other refusal here.
+            server.on('error', (e) => {
+                const why = e.code === 'EADDRINUSE' ? 'already in use' : e.message;
+                console.error(`tarmac: cannot listen on port ${config.port.value} (${SOURCE_PHRASE[config.port.source]}) — ${why}`);
+                process.exit(1);
+            });
+            server.listen(config.port.value, '127.0.0.1', () => {
+                console.log(`tarmac serving http://127.0.0.1:${server.address().port}`);
+            });
+        }
+        else {
+            const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source });
+            if (args.watch) {
+                // One redraws a screen, the other is meant to be piped once. Silently letting one win
+                // is how someone ends up parsing a frame of terminal art.
+                if (args.json)
+                    throw new Error('--watch and --json cannot be combined — a watch redraws a screen, --json prints once');
+                const stop = new AbortController();
+                // Ctrl-C leaves through the loop rather than through the window: the frame in flight
+                // finishes, and the process exits 0 like every other reading command.
+                //
+                // The second one is not politeness, it is the promise every frame prints. Registering
+                // a handler replaces Node's default terminate, and the loop only checks the flag
+                // between awaits — so a Ctrl-C during a slow `claude agents --json` was swallowed, and
+                // so was the next one, for as long as the read took. A watch that prints "^C to quit"
+                // has to be leavable with ^C.
+                process.on('SIGINT', () => {
+                    if (stop.signal.aborted)
+                        process.exit(130);
+                    stop.abort();
+                });
+                await runWatch({
+                    collect,
+                    write: (frame) => process.stdout.write(frame),
+                    // The abort lands DURING the wait, which is the whole point of the wait — so it
+                    // resolves rather than rejecting, and the loop's own check is what ends it.
+                    sleep: (ms) => sleep(ms, undefined, { signal: stop.signal }).then(() => { }, () => { }),
+                    now: () => Date.now(),
+                    isTTY: Boolean(process.stdout.isTTY),
+                    signal: stop.signal,
+                });
+            }
+            else {
+                const fleet = await collect();
+                process.stdout.write(args.json ? JSON.stringify(fleet, null, 2) + '\n' : renderTable(fleet));
+            }
+        }
+    }
+}
+catch (e) {
+    console.error(`tarmac: ${e.message}`);
+    process.exit(1);
+}

package/dist/collect.js

@@ -0,0 +1,26 @@
+// P3 — one call, both contractual sources, one fleet view. Strictly read-only.
+import { SOURCE_PHRASE } from './config.js';
+import { discoverSessions } from './discover.js';
+import { readSnapshots } from './snapshots.js';
+import { buildFleet } from './fleet.js';
+export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', }) {
+    const { sessions, health: discovery } = await discoverSessions({ claudeBin });
+    const { snapshots, dirError, unreadable, duplicates, dirMissing } = readSnapshots(snapshotsDir, { now });
+    const fleet = buildFleet({ sessions, snapshots, now, discovery, staleAfterMs });
+    // Both blind spots travel with the data: a directory we could not read and files we
+    // could not parse are OUR failures to report, not silence to render as "all clear".
+    //
+    // An absent directory is judged HERE, because this is the layer that knows who chose it:
+    // the default may simply not exist yet (nothing has been chained), but a path someone
+    // typed — flag, environment, or a config file edited months ago — that is not there is a
+    // setting pointing at nothing. Rendered as "not chained yet" it sends the user to run
+    // `tarmac install`, which cannot fix it: install writes where install writes.
+    fleet.health.snapshotsError =
+        dirMissing && snapshotsDirSource !== 'default'
+            ? `ENOENT: ${snapshotsDir} does not exist — set by ${SOURCE_PHRASE[snapshotsDirSource]}`
+            : dirError;
+    fleet.health.snapshotsUnreadable = unreadable;
+    fleet.health.snapshotsDuplicates = duplicates;
+    fleet.health.snapshotsDir = snapshotsDir;
+    return fleet;
+}