@adrrr/tarmac 0.1.2 → 0.3.0

package/dist/render.js

@@ -7,6 +7,7 @@
 // stays invisible for days. The two surfaces say the same things in their own words — so
 // they are written side by side, and the suite can reach both.
 import { formatDuration } from './config.js';
+import { buildMap, INTERACTIVE, stateOf } from './map.js';
 import { schemaNotice } from './schema.js';
 /**
  * The other thing this module renders: the plan a user consents to before install or
@@ -27,9 +28,41 @@ export function renderPlan(plan) {
             rows.push(['↳ which calls', `${plan.chained}   (your display is unchanged)`]);
         if (plan.alreadyInstalled)
             rows.push(['note', 'already installed — the wrapper is regenerated, settings.json is left alone']);
+        // The snapshots directory is no longer under `.claude`, so it is no longer guessable
+        // from the path above it: naming it here is how a reader of `list`, `serve` or any other
+        // tool finds out where the payloads land.
+        rows.push(['snapshots', plan.snapshots]);
+        // A relocation is a change to where the telemetry lands, so it is never implied.
+        if (plan.movingFrom !== null)
+            rows.push(['↳ moving from', `${plan.movingFrom}   (its payloads are left there, and nothing collects them)`]);
+        // This operation now DELETES files, inside a directory people commit. A plan that can
+        // disagree with what runs is worse than no plan — so it says how many, and where.
+        // A directory that is THERE but holds none of our payloads is the state the previous
+        // install left behind: nothing to announce, and nothing to ask anyone to commit.
+        const clearing = plan.legacy !== null && plan.legacy.payloads > 0;
+        if (clearing) {
+            rows.push([
+                '↳ clearing',
+                `${plan.legacy.payloads} runtime payload(s) under ${plan.legacy.dir} — each one is written again on the next frame`,
+            ]);
+            if (plan.legacy.kept > 0)
+                rows.push(['↳ keeping', `${plan.legacy.kept} file(s) nothing here wrote, so that directory stays`]);
+        }
+        if (plan.gitRepo !== null)
+            rows.push(['git', gitHint(plan.gitRepo, clearing)]);
     }
     else {
         rows.push(['restore', `${plan.mode} — ${restoreMeaning(plan.mode)}`]);
+        // Nothing here says where the payloads are — no wrapper, or one that no longer carries
+        // the path, or one we cannot read. There is no directory to name, and `uninstall` opens
+        // none and removes nothing in one. Printing the default we would have computed, beside a
+        // promise to clear a marker out of it, is a plan disagreeing with what runs.
+        if (plan.snapshots === null) {
+            rows.push(['snapshots', 'unknown — nothing here says where; nothing there is opened or removed']);
+        }
+        else {
+            rows.push(['snapshots', `${plan.snapshots}   (snapshot files stay; ${markerFate(plan.mode, plan.marker)})`]);
+        }
     }
     rows.push(['undo', plan.undo]);
     const w = Math.max(...rows.map(([label]) => label.length));
@@ -37,6 +70,39 @@ export function renderPlan(plan) {
         rows.map(([label, value]) => `  ${label.padEnd(w)}  ${value}\n`).join('') +
         '\n');
 }
+/**
+ * The line #20 asked for, said once, to the only people it concerns: those whose `.claude`
+ * is a git repository.
+ *
+ * It has two jobs, and which one is live depends on whether the payloads are still there:
+ * an install that clears them produces a DELETION the user has to commit, and a `.gitignore`
+ * line keeps them from coming back if that directory is ever pointed at again. With nothing
+ * to clear, the only thing left to say is that this install adds nothing that churns.
+ */
+const gitHint = (repo, hasLegacy) => `${repo.dir} is a git repository — ` +
+    (hasLegacy
+        ? `commit the removal above, and add \`${repo.ignore}\` to its .gitignore`
+        : 'nothing tarmac writes there changes at runtime; the snapshots live outside it');
+/**
+ * What becomes of the prune marker, said only after looking at it.
+ *
+ * Three of these four answers are "it stays", each for its own reason: a foreign statusLine
+ * keeps the wrapper, so the marker keeps its owner; nothing is there to take; or what is there
+ * is not a plain file, which `removePruneMarker` refuses by design because `unlink` would take
+ * a link and not its target.
+ *
+ * Written so that ONLY `'file'` can reach the removal sentence, rather than letting it be the
+ * fallthrough: `marker` is nullable by type, and a null landing on "is removed" would be the
+ * exact promise this whole change exists to stop making. The safe answer is the default; the
+ * dangerous one is the special case.
+ */
+const markerFate = (mode, marker) => marker !== 'file'
+    ? marker === 'not-a-file'
+        ? "the prune marker's name is worn by something that is not a regular file, so it stays"
+        : 'no prune marker to remove'
+    : mode === 'foreign'
+        ? "tarmac's prune marker stays"
+        : "tarmac's prune marker is removed";
 /** What each restore mode means, in the words the plan and the report both use. */
 export const restoreMeaning = (mode) => RESTORE_MEANING[mode];
 const RESTORE_MEANING = {
@@ -110,7 +176,13 @@ export function renderTable({ rows, health }) {
     else if (health.schemaBroken)
         warns.push('! every snapshot drifted — the statusline payload schema moved');
     else if (health.covered < health.sessions)
-        warns.push(`! statusline chained on ${health.covered}/${health.sessions} sessions`);
+        warns.push(
+        // The count travels, for the same reason `unreadable` does one line up: without it
+        // this line reads as "run install", and for a session id the wrapper declines to file
+        // that is advice already taken which can never work.
+        health.unfilable > 0
+            ? `! statusline chained on ${health.covered}/${health.sessions} sessions — ${health.unfilable} session(s) with an id tarmac never files`
+            : `! statusline chained on ${health.covered}/${health.sessions} sessions`);
     if (health.stale > 0)
         warns.push(`! ${health.stale} reading(s) marked "!" are older than ${formatDuration(health.staleAfterMs)} (--stale-after)`);
     const skewed = rows.filter(ahead).length;
@@ -156,7 +228,8 @@ function age(ms) {
  * could not see) are hard-won and tested; re-deriving them in browser JavaScript to redraw a
  * polled row would put the second copy somewhere this suite cannot reach.
  */
-export function renderLive({ rows, health }) {
+export function renderLive(fleet) {
+    const { rows, health } = fleet;
     const warnings = [];
     if (health.noSessionId > 0) {
         // Never "no sessions found" when discovery DID find some it could not identify.
@@ -178,7 +251,12 @@ export function renderLive({ rows, health }) {
         warnings.push(`Every snapshot drifted — Claude Code's statusline schema has probably moved. Context readings are dead until the payload shape is re-checked.`);
     }
     else if (health.covered < health.sessions) {
-        warnings.push(`Statusline chained on ${health.covered}/${health.sessions} sessions — the rest report no context. Run \`tarmac install\` and give them one TUI frame.`);
+        const blind = health.sessions - health.covered;
+        warnings.push(health.unfilable === 0
+            ? `Statusline chained on ${health.covered}/${health.sessions} sessions — the rest report no context. Run \`tarmac install\` and give them one TUI frame.`
+            : health.unfilable >= blind
+                ? `Statusline chained on ${health.covered}/${health.sessions} sessions — the rest carry a session id that is not the UUID tarmac files snapshots under, so no frame will ever produce one. Installing again will not change that.`
+                : `Statusline chained on ${health.covered}/${health.sessions} sessions — ${blind} report no context, and ${health.unfilable} of them will never be filed: the session id is not the UUID tarmac files snapshots under. For the others, run \`tarmac install\` and give them one TUI frame.`);
     }
     if (health.unknownStatus > 0) {
         warnings.push(`${health.unknownStatus} session(s) report a status tarmac does not know — treated as unknown, not idle.`);
@@ -193,22 +271,34 @@ export function renderLive({ rows, health }) {
     const schema = schemaNotice(health.schemaGuard);
     if (schema)
         warnings.push(schema);
+    // Both views, every time, out of the one reading the page just asked for. The tabs are
+    // links and the shell decides which of the two is visible, so a fleet cannot be drawn as a
+    // table of one age beside a map of another.
+    //
+    // A fleet with nothing in it has no two ways to be laid out, so it gets one sentence above
+    // both of them rather than a copy inside each — the copy behind `display:none` was invisible
+    // on screen and read out all the same by anything going through the markup.
     const body = rows.length === 0
-        ? health.noSessionId > 0
-            ? // Discovery DID return entries — we just could not identify them. Saying "none
-                // found" here would hide a schema change behind a calm, wrong answer.
-                `<p class="empty">No session could be identified, though ${health.noSessionId} were discovered.</p>`
-            : `<p class="empty">No Claude Code sessions found. Is a session running?</p>`
-        : `<table>
+        ? empty(health)
+        : `<div class="view view-table"><div class="wrap"><table>
       <thead><tr>
         <th>Project</th><th>Session</th><th>State</th><th>Context</th><th>Model</th><th>Effort</th><th>Cost</th><th>Uptime</th>
       </tr></thead>
       <tbody>${rows.map(renderRow).join('')}</tbody>
-    </table>`;
+    </table></div></div>
+<div class="view view-map">${renderMap(fleet)}</div>`;
     return `<div class="meta">${health.sessions} session${health.sessions === 1 ? '' : 's'} · ${health.busy} busy · ${cost(health)} · ${esc(new Date(health.generatedAt).toISOString())}</div>
 ${warnings.map((w) => `<div class="warn">${esc(w)}</div>`).join('')}
-<div class="wrap">${body}</div>`;
+${body}`;
 }
+/**
+ * What to say instead of a fleet. Discovery returning entries we could not identify is not
+ * an empty fleet, and saying "none found" would hide a schema change behind a calm, wrong
+ * answer — so the two surfaces below share one wording rather than each keeping its own.
+ */
+const empty = (health) => health.noSessionId > 0
+    ? `<p class="empty">No session could be identified, though ${health.noSessionId} were discovered.</p>`
+    : `<p class="empty">No Claude Code sessions found. Is a session running?</p>`;
 /**
  * One frame of `tarmac list --watch`. It owes the reader exactly what the page owes: the
  * table, when the reading in it arrived, and whether the last attempt to refresh it failed.
@@ -255,7 +345,7 @@ function ago(ms) {
     const m = Math.round(s / 60);
     return m < 60 ? `${m}m` : `${Math.round(m / 60)}h`;
 }
-export function renderPage(fleet) {
+export function renderPage(fleet, view = 'table') {
     return `<!doctype html>
 <html lang="en"><head>
 <meta charset="utf-8">
@@ -306,6 +396,81 @@ export function renderPage(fleet) {
   body.failing .pulse { background:var(--warn); }
   body.failing #live { border:1px dashed var(--warn); border-radius:8px; padding:.5rem; }
   .offline strong { white-space:nowrap; }
+  /* The tabs, and what they hide. The shell owns the choice — not the fragment — so a poll
+     that swaps the fleet underneath cannot put the reader back on a view they left. */
+  nav { display:flex; gap:.15rem; }
+  nav a { color:var(--dim); text-decoration:none; font-size:.8rem; font-weight:600; text-transform:uppercase;
+          letter-spacing:.06em; padding:.15rem .55rem; border-radius:99px; border:1px solid transparent; }
+  nav a[aria-current="page"] { color:var(--fg); border-color:var(--line); }
+  body[data-view="table"] .view-map { display:none; }
+  body[data-view="map"] .view-table { display:none; }
+
+  /* ── the map ─────────────────────────────────────────────────────────────────────────
+     One node per session. The arc is the context, its weight is how much that reading may
+     be believed, and the halo — the only thing on this page that moves — says a frame
+     landed moments ago. */
+  .map { display:grid; gap:.9rem; grid-template-columns:repeat(auto-fill,minmax(10.5rem,1fr)); }
+  .node { border:1px solid var(--line); border-radius:10px; padding:.8rem .85rem .7rem;
+          display:flex; flex-direction:column; align-items:center; text-align:center; }
+  .node[data-state="busy"] { border-color:color-mix(in srgb, var(--busy) 45%, var(--line)); }
+  /* An agent is a smaller body in the same system, next to the session it shares a directory
+     with — never inside it. Tinted rather than outlined, and hooked, so it reads as the
+     session's dependent without a line claiming a parentage the source never published. */
+  .node[data-role="agent"] { padding-top:.55rem; border-color:transparent;
+          background:color-mix(in srgb, var(--line) 22%, transparent); }
+  .node[data-role="agent"] .dial { width:3.6rem; height:3.6rem; }
+  .node[data-role="agent"] .pct { font-size:.95rem; }
+  .node[data-role="agent"] .why { font-size:.6rem; max-width:3.4rem; }
+  .node[data-role="agent"] .why b { font-size:1rem; }
+  .node[data-role="agent"] .project { font-weight:400; }
+  /* Said, not shown: the three glyphs differ in silhouette, so a reader who cannot separate
+     two hues still has the state — but a screen reader is handed a bullet and nothing else. */
+  .sr { position:absolute; width:1px; height:1px; overflow:hidden; clip-path:inset(50%); white-space:nowrap; }
+  .dial { position:relative; width:5.5rem; height:5.5rem; }
+  .dial svg { width:100%; height:100%; display:block; overflow:visible; }
+  .track { fill:none; stroke:var(--line); stroke-width:5; }
+  /* Butt caps, not round: a rounded cap adds half a stroke width at each end, which draws a
+     1% reading at three times its extent. The prettier cap overstates every small number. */
+  .arc { fill:none; stroke:var(--dim); stroke-width:5; }
+  .node[data-state="busy"] .arc { stroke:var(--busy); }
+  /* A reading past the freshness threshold is drawn as what it is: thin, faded, and in the
+     warning hue — never the solid arc of a live one. Its EXTENT stays true, because the
+     number is still the truth of an earlier moment; and a dash pattern here would overwrite
+     stroke-dasharray, which is what carries the percentage. */
+  .node[data-reading="stale"] .arc, .node[data-reading="undated"] .arc {
+          stroke:var(--warn); stroke-width:2.5; opacity:.7; }
+  /* Nothing was measured. Keyed on the measurement and never on the age of the file: a
+     solid empty ring is what a session measured at 0% wears, and the two must not match. */
+  .track.unmeasured { stroke-dasharray:2 6; stroke-linecap:round; }
+  /* Once per arrival, not forever: the fragment is replaced on every poll, so a single run
+     per swap is what makes the fleet breathe at the rate its frames actually land. A looping
+     animation would say "a frame just arrived" for five seconds after it stopped being true. */
+  .halo { fill:none; stroke:var(--busy); stroke-width:2; opacity:0; transform-origin:50% 50%;
+          animation:halo 1.6s ease-out 1; }
+  .node[data-state="idle"] .halo { stroke:var(--dim); }
+  @keyframes halo { from { opacity:.5; transform:scale(1); } to { opacity:0; transform:scale(1.22); } }
+  /* Motion is the one thing here nobody can look away from, so it is the first thing a
+     reader who asked for less of it stops getting. The reading is still readable without it. */
+  /* Scaled, not merely stopped: at rest the halo sits inside the track's own stroke, so
+     "animation:none" alone left the one fact it carries invisible. */
+  @media (prefers-reduced-motion: reduce) { .halo { animation:none; opacity:.35; transform:scale(1.18); } }
+  .val { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
+         font-variant-numeric:tabular-nums; }
+  .pct { font-size:1.25rem; font-weight:650; letter-spacing:-.01em; }
+  .pct i { font-style:normal; font-size:.7em; font-weight:500; color:var(--dim); }
+  .why { font-size:.68rem; color:var(--dim); line-height:1.2; max-width:4.4rem; }
+  .why b { display:block; font-size:1.25rem; font-weight:400; }
+  .who { margin-top:.5rem; display:flex; align-items:baseline; gap:.3rem; max-width:100%; }
+  .who .project { font-weight:600; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .node[data-state="busy"] .who .project { font-weight:700; }
+  .shape { font-size:.7rem; color:var(--dim); }
+  .node[data-state="busy"] .shape { color:var(--busy); }
+  .node[data-state="unknown"] .shape { color:var(--warn); }
+  .sub { color:var(--dim); font-size:.76rem; max-width:100%; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .asof { font-size:.72rem; color:var(--dim); font-variant-numeric:tabular-nums; margin-top:.15rem; }
+  .asof.stale { color:var(--warn); font-weight:600; }
+  @media (max-width: 30rem) { .map { grid-template-columns:repeat(auto-fill,minmax(8.5rem,1fr)); gap:.6rem; } }
+
   /* Below this the table stops being a table: one card per session, every value keeping the
      name of the column it came from. Nothing is dropped — a phone that hides the context
      column would be a phone that renders "not measured" as nothing at all. */
@@ -327,9 +492,17 @@ export function renderPage(fleet) {
     .bar { display:none; }
   }
 </style>
-</head><body>
+</head><body data-view="${view}">
 <header>
   <h1>tarmac</h1>
+  <!-- Links, not buttons: the view survives a reload, a bookmark and a browser with
+       JavaScript off — the state of a page whose own noscript banner promises it is still
+       readable. Both views are in the fragment below either way, so switching costs the
+       server nothing and the two can never show readings of different ages. -->
+  <nav>
+    <a href="/"${view === 'table' ? ' aria-current="page"' : ''}>Table</a>
+    <a href="/map"${view === 'map' ? ' aria-current="page"' : ''}>Map</a>
+  </nav>
   <!-- Not "updated just now". If the script never runs — a policy-injected CSP without
        'unsafe-inline', a script error — that text would stand as a permanent lie, and
        <noscript> would not fire to correct it because JavaScript is enabled. The page's one
@@ -468,7 +641,7 @@ const SCRIPT = `
  */
 function renderRow(r) {
     const state = stateOf(r);
-    const word = r.busy === true ? 'busy' : r.busy === false ? 'idle' : (r.status ?? 'unknown');
+    const word = stateWord(state, r);
     // `data-label` is not decoration: below ~46rem the columns stack, the header row is gone,
     // and a value whose column has no name is a bare "—" that could mean anything.
     // Every cell holds exactly ONE element. Stacked on a phone the label sits left and the
@@ -485,12 +658,106 @@ function renderRow(r) {
     <td data-label="Uptime" class="num dim"><span class="v">${r.uptimeMs === null ? dash() : esc(duration(r.uptimeMs))}</span></td>
   </tr>`;
 }
-const stateOf = (r) => (r.busy === true ? 'busy' : r.busy === false ? 'idle' : 'unknown');
 const SHAPE = { busy: '●', unknown: '▲', idle: '○' };
+/**
+ * The state in words, for both surfaces — derived from the state the MODEL decided, never
+ * from the row a second time. Two expressions for one fact on one element is how a node ends
+ * up shaped `unknown` and captioned `idle`.
+ *
+ * An unrecognised status is quoted as it came rather than flattened to "unknown": the point
+ * of keeping it is that someone reading the page can go and find out what `compacting` means.
+ */
+const stateWord = (state, r) => state === 'unknown' ? (r.status ?? 'unknown') : state;
+/**
+ * Which kind of missing a missing percentage is. One lookup for both surfaces: the table
+ * says it beside a dash, the map says it inside an empty dial, and a second copy of these
+ * three words is a second chance to describe the same state differently.
+ */
+const CTX_WHY = { fresh: 'no turn yet', drift: 'schema drift', absent: 'not chained' };
+/**
+ * The map: one node per session, laid out as a grid rather than a graph. An empty fleet is not
+ * its business — `renderLive` says that once, above both views, rather than letting each of
+ * them render the same sentence and hide one of the two.
+ *
+ * There are no edges because the sources publish no relationship between two sessions — the
+ * one thing they do carry is the working directory, and that is expressed by putting an
+ * agent NEXT to the session it shares a directory with, never by drawing a line that would
+ * claim more than the data says.
+ *
+ * Everything a reader interprets is decided in `map.ts` and rendered here, on the server,
+ * for the same reason the table is: the rules that keep a reading honest are tested, and a
+ * copy of them re-derived in browser JavaScript would sit where this suite cannot reach.
+ */
+export function renderMap(fleet) {
+    return `<div class="map">${buildMap(fleet).nodes.map(renderNode).join('')}</div>`;
+}
+/**
+ * One node. Five facts, in five channels that do not depend on colour alone: the arc is how
+ * full the context is, the dial's weight is how much that reading may be believed, a dotted
+ * dial is no reading at all, the shape beside the name is the session's state, and the halo
+ * says one landed moments ago. The words under them are the same ones the table uses for the
+ * same conditions — including the halo's, which would otherwise live only in a drawing.
+ */
+function renderNode({ row: r, role, state, reading, measured, pulse }) {
+    // The model owns "is there a number"; this reads its verdict rather than asking the row a
+    // second question. `fresh` and `drift` are the two states where the age of the file and the
+    // presence of a reading disagree, and they are the two that matter most.
+    const pct = measured ? r.ctxPct : null;
+    const value = pct === null
+        ? `<span class="why"><b>&mdash;</b>${esc(CTX_WHY[r.ctxState] ?? 'no reading')}</span>`
+        : `<span class="pct">${pct}<i>%</i></span>`;
+    // The reading's own age, and only when it is one the reader must not take for current.
+    const asOf = reading === 'stale' && r.snapshotAgeMs !== null
+        ? `<div class="asof stale">! ${esc(asOfAge(r.snapshotAgeMs))} ago</div>`
+        : reading === 'undated'
+            ? `<div class="asof stale">! undated</div>`
+            : '';
+    // An agent carries its own project, like every other node. Placement is not a promise —
+    // the grid wraps where the viewport says, and the fleet's sort can hand the same agent a
+    // different neighbour on the next poll — so nothing here points at the node beside it.
+    return `<article class="node" data-role="${role}" data-state="${state}" data-reading="${reading}">
+      <div class="dial">
+        <svg viewBox="0 0 80 80" aria-hidden="true">${pulse ? `<circle class="halo" cx="40" cy="40" r="${DIAL_R}"/>` : ''}<circle class="track${measured ? '' : ' unmeasured'}" cx="40" cy="40" r="${DIAL_R}"/>${pct === null ? '' : arc(pct)}</svg>
+        <div class="val">${value}</div>
+        ${pulse ? `<span class="sr">a reading just landed</span>` : ''}
+      </div>
+      <div class="who"><span class="shape" aria-hidden="true">${SHAPE[state]}</span><span class="sr">${esc(stateWord(state, r))}</span><span class="project">${esc(r.project)}</span></div>
+      <div class="sub">${esc(r.name)}</div>
+      ${r.kind === null || r.kind === INTERACTIVE ? '' : `<div class="sub">${esc(r.kind)}</div>`}
+      <div class="sub">${esc(r.model)}${r.effort === null ? '' : ` · ${esc(r.effort)}`}</div>
+      ${asOf}
+    </article>`;
+}
+/**
+ * How old a dated reading is, in the words both surfaces use.
+ *
+ * `duration` floors to whole minutes, and `--stale-after` takes seconds — so a 30s reading
+ * judged against a 2s threshold rendered "! 0m ago": the "!" saying past the threshold and
+ * the "0m" saying brand new, in the same breath. Under a minute the age stops pretending to
+ * be a round number.
+ */
+const asOfAge = (ms) => (ms < 60_000 ? '<1m' : duration(ms));
+/** The dial's geometry. One radius, named once, so the arithmetic below cannot drift from it. */
+const DIAL_R = 30;
+const DIAL_C = 2 * Math.PI * DIAL_R;
+/**
+ * The filled part of the ring, as a fraction of the circle's real circumference.
+ *
+ * `pathLength="100"` would say the same thing in far prettier markup — "62 filled, 38 empty"
+ * — but it is an attribute browsers have not always honoured on basic shapes, and the way it
+ * fails is the one this page cannot afford: the dash array is ignored, the arc closes, and
+ * every session reads as a full context window. Two decimals is well under a pixel at this
+ * radius, and it keeps the markup diffable.
+ */
+function arc(pct) {
+    const filled = (Math.min(100, Math.max(0, pct)) / 100) * DIAL_C;
+    return (`<circle class="arc" cx="40" cy="40" r="${DIAL_R}" transform="rotate(-90 40 40)"` +
+        ` stroke-dasharray="${round2(filled)} ${round2(DIAL_C - filled)}"/>`);
+}
+const round2 = (n) => Math.round(n * 100) / 100;
 function ctxCell(r) {
     if (r.ctxPct === null) {
-        const why = { fresh: 'no turn yet', drift: 'schema drift', absent: 'not chained' }[r.ctxState] ?? '';
-        return `${dash()} <span class="dim">${esc(why)}</span>`;
+        return `${dash()} <span class="dim">${esc(CTX_WHY[r.ctxState] ?? '')}</span>`;
     }
     // A stale reading is still the truth — of an earlier moment. Show it, and date it, with
     // the same "!" the terminal marks it with: an age in the same grey as everything else is
@@ -501,7 +768,7 @@ function ctxCell(r) {
     // "! 0m ago" — a missing measurement as a zero, contradicting itself in the same breath
     // (the "!" says past the threshold, the "0m" says brand new). The terminal path already
     // re-checked it; the two surfaces are not allowed to disagree about the module's own rule.
-    const asOf = r.stale && r.snapshotAgeMs !== null ? ` <span class="stale">! ${esc(duration(r.snapshotAgeMs))} ago</span>` : '';
+    const asOf = r.stale && r.snapshotAgeMs !== null ? ` <span class="stale">! ${esc(asOfAge(r.snapshotAgeMs))} ago</span>` : '';
     return `<span class="bar"><i style="width:${Math.min(100, r.ctxPct)}%"></i></span>${r.ctxPct}%${asOf}`;
 }
 /** A partial sum is never presented as the fleet's total. */

package/dist/server.js

@@ -14,6 +14,11 @@ import { SOURCE_PHRASE } from './config.js';
  * failures carry it too: their text is what it quotes as the reason.
  */
 const IDENTITY = { 'x-tarmac': '1' };
+/** The addresses that serve the shell, and which view each one opens on. */
+const PAGES = new Map([
+    ['/', 'table'],
+    ['/map', 'map'],
+]);
 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
@@ -38,7 +43,12 @@ export function createFleetServer({ collect }) {
         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') {
+        //
+        // `/map` is the same page opened on the other view, and deliberately not `/?view=map`:
+        // the tabs are plain links, so the view has to be somewhere a reload and a bookmark can
+        // both find it. There is no second fragment — one `/live` carries both views, which is
+        // what keeps them from ever showing readings of different ages.
+        if (!PAGES.has(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;
@@ -58,7 +68,7 @@ export function createFleetServer({ collect }) {
             }
             else {
                 type = 'text/html; charset=utf-8';
-                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet);
+                body = url.pathname === '/live' ? renderLive(fleet) : renderPage(fleet, PAGES.get(url.pathname));
             }
         }
         catch (e) {

package/dist/sessions.js

@@ -6,9 +6,26 @@
 // 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.
+/**
+ * What each word this surface prints says about the one question the boolean asks: is this
+ * session working. A word that does not answer it is absent, and absent means `null` — "we do
+ * not know" — which is the whole point of the file.
+ *
+ * The first two arrive on a session with a process of its own; the other two are a background
+ * agent's `state`, which is where its word lives instead.
+ *
+ * Some words are left out ON PURPOSE rather than for want of a payload. `failed` and `stopped`
+ * are "not working", and that is the least interesting true thing about them; `blocked` and
+ * `waiting` are a session halted until a human answers something, where `false` reads as calm
+ * on a session that needs you and `true` as fine on one that has stopped. Unknown is the only
+ * bucket whose node prints the word itself, so those keep it: an amber node captioned `failed`
+ * says what neither boolean could.
+ */
 const KNOWN_STATUS = new Map([
     ['busy', true],
     ['idle', false],
+    ['working', true],
+    ['done', false],
 ]);
 /** @param text raw stdout of `claude agents --json` */
 export function parseAgents(text) {
@@ -32,7 +49,10 @@ export function parseAgents(text) {
         const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null;
         if (!sessionId)
             health.noSessionId += 1;
-        const status = typeof entry.status === 'string' ? entry.status : null;
+        // A background agent carries no `status` at all — its word is under `state`. `status`
+        // still wins where both are present: it comes from the agent's own process, and `state`
+        // is what the dispatcher believes about an agent whose process may not be on this machine.
+        const status = typeof entry.status === 'string' ? entry.status : typeof entry.state === 'string' ? entry.state : null;
         const busy = KNOWN_STATUS.has(status) ? KNOWN_STATUS.get(status) : null;
         if (busy === null)
             health.unknownStatus += 1;

package/dist/snapshots.js

@@ -102,8 +102,25 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
             mtimeMs = fs.statSync(file).mtimeMs;
             payload = JSON.parse(fs.readFileSync(file, 'utf8'));
         }
-        catch {
-            unreadable += 1; // corrupt, half-written or unreadable: skip, but never forget
+        catch (e) {
+            // ENOENT: a name listed a moment ago that resolves to nothing now. Almost always the
+            // sweep, deleting a cold snapshot out of the very directory we are reading — its job,
+            // and a race with our own housekeeping rather than a payload we failed to parse.
+            // Counting it made tarmac drive its own format-drift warning (up to 2675 phantom
+            // unreadable on one read of a 20k directory, and `list --watch` and `serve` redraw
+            // often enough to be inside that window).
+            //
+            // The cost, said out loud: `statSync` follows symlinks, so a DANGLING one named like a
+            // snapshot is ENOENT too, and it goes silent forever — a permanent state skipped as if
+            // it were a passing race. Deliberate. There is no payload behind a dead link either,
+            // and telling the two apart (an `lstat` first) buys a warning about a file `ls` already
+            // shows. Note it is the opposite call from `reap.ts:75`, which lstats PRECISELY so a
+            // dead link is not ENOENT: it deletes, and `unlink` takes a link away just fine. Reader
+            // and reaper ask different questions of the same shape.
+            //
+            // ENOENT only. A file we were not ALLOWED to open still counts, and must.
+            if (e.code !== 'ENOENT')
+                unreadable += 1; // corrupt, half-written or unreadable: skip, but never forget
             continue;
         }
         const t = extractTelemetry(payload);