@adrrr/tarmac 0.4.1 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ documented surfaces only, never an internal format.
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/replay-dark.gif">
   <img src="docs/media/replay-light.gif" width="1100"
-       alt="The tarmac map with the scrubber dragged across the record: five sessions drawn as dials, each arc a context window, the account's five-hour and seven-day gauges above them. As the handle moves, sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed.">
+       alt="The tarmac map, live and then replayed. It opens on the live fleet, whose nodes are grouped into a frame per working directory, each labelled with its project. As the scrubber is dragged the frames give way to the flat record — sessions drawn as dials, each arc a context window, background agents as strips of text — with the account's five-hour and seven-day gauges above them. Sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
 </picture>
 
 [Quickstart](#quickstart) · [The map](#the-map) · [Install](#install) ·
@@ -58,30 +58,45 @@ Node ≥ 20. **Zero runtime dependencies** — no framework, no bundler, nothing
 
 `tarmac serve` puts the same fleet in the browser — every session a row, ages that keep
 climbing, and a banner the moment a refresh fails instead of a table quietly going stale. It
-binds to loopback and refuses any request whose `Host` is not loopback, or that a browser does
-not mark same-origin: your cwd paths and costs never leave the machine. The listening rules:
+binds to loopback and refuses any request whose `Host` is not loopback, or that a browser marks
+as coming from another origin: your cwd paths and costs never leave the machine. A client that
+sends no such mark — curl, a script — is left alone. The listening rules:
 [the manual](docs/MANUAL.md#what-serve-listens-on).
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/map-dark.png">
   <img src="docs/media/map-light.png" width="1100"
-       alt="The tarmac map, live. Five nodes: beacon halted on a permission prompt, harbor busy with its context arc at 90%, a background agent named after its prompt beside it, quay reporting a status tarmac does not know, and atlas idle at 36%. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
+       alt="The tarmac map, live. Four framed groups, one per working directory and labelled with its project: beacon, holding a session halted on a permission prompt; harbor, holding a session busy with its context arc at 90% and a background agent docked under the cards of that frame as a strip named after its prompt; quay, reporting a status tarmac does not know; and atlas, idle at 36%. A frame says only that its nodes were read in the same directory — nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
 </picture>
 
 The tab in the header swaps the table for the same fleet as nodes — one per session, the arc
-its context, the shape by the name its state. It is the same reading in the same fragment, so
-the two views can never disagree. Above the fleet are the account's five-hour and seven-day
+its context, the shape by the name its state. A background agent has no terminal behind it to
+draw a frame with, so it is a strip of text rather than a dial that could never fill. It is
+the same reading in the same fragment, so the two views can never disagree.
+
+The nodes are grouped by **working directory**: a frame per directory, labelled with its
+project, the sessions inside it as cards and the agents docked underneath as strips. That is
+the whole of what the frame claims — these were read in the same directory. It is not a
+parentage: `claude agents --json` publishes nothing that ties an agent to whoever dispatched
+it, so no label, no position and no line inside a frame says one node asked for another. An
+agent whose directory matches no session gets a frame of its own rather than somebody else's.
+
+Above the fleet are the account's five-hour and seven-day
 [gauges](docs/MANUAL.md#the-accounts-two-windows); under it a **scrubber over the day this
-serve has seen** — drag it and the dials render
-the fleet as it was at that minute, press play and the day walks past.
+serve has seen** — drag it and the nodes render
+the fleet as it was at that minute, press play and the day walks past. Replayed, they are
+drawn flat and unframed: the record keeps a project name and never the directory it was read
+in, and a basename is not a directory — two checkouts of `atlas` answer to the same word, so a
+frame drawn on it would claim a shared directory nobody can check.
 
 The rules the table follows, the map follows: a reading past the freshness threshold is drawn
 thin, amber and dated, a percentage nobody measured is an empty dotted dial rather than a ring
-at zero, and a word `claude agents --json` printed that tarmac has no boolean for is shown as
-it came rather than quietly filed as `idle` — and raises one warning above the fleet naming
-it. The page is JSON underneath: `GET /api/fleet` and `GET /api/history` serve exactly what
-the map draws. Details in
-[the manual](docs/MANUAL.md#the-map).
+at zero, and where nothing was published at all — the strip of an agent the join found no
+snapshot for — nothing is drawn in its place, neither a dial nor a dash. A word
+`claude agents --json` printed that tarmac has no boolean for is shown as it came rather than
+quietly filed as `idle` — and raises one warning above the fleet naming it. The page is JSON
+underneath: `GET /api/fleet` and `GET /api/history` serve exactly what the map draws. Details
+in [the manual](docs/MANUAL.md#the-map).
 
 ## Install
 
@@ -128,7 +143,7 @@ deliberately not configurable, and all of it works with no configuration at all.
 |---|---|---|
 | freshness threshold | `--stale-after 90s` \| `15m` \| `2h` | `10m` |
 | port | `--port 8080` | `4477` |
-| snapshots dir (read side) | `--snapshots-dir DIR` | the path frozen into the installed wrapper, so the reader follows the writer |
+| snapshots dir (read side) | `--snapshots-dir DIR` | the wrapper's frozen path when installed, else the XDG state directory |
 
 Each also has an environment variable and a key in `<home>/.claude/tarmac/config.json`.
 **Flag beats environment beats config file beats default**, settled per setting; `serve`

package/dist/map.js

@@ -3,6 +3,12 @@
 // A view over the fleet `buildFleet` already produced. It opens no second source: every
 // field below is derived from a row that is already on the page as a table line.
 import { isWaiting } from './sessions.js';
+/**
+ * What a berth is labelled when the source published no working directory for it. In the
+ * vocabulary the dials already use for a reading they do not have (`not chained`, `no turn
+ * yet`): a kind of nothing, named, rather than an empty frame that reads as a bug.
+ */
+const NO_DIRECTORY = 'no directory';
 /**
  * How recently a snapshot must have landed for its node to pulse. Two of the page's poll
  * intervals (5s): a session whose terminal keeps drawing frames keeps its heartbeat across
@@ -13,18 +19,20 @@ import { isWaiting } from './sessions.js';
  */
 export const PULSE_WITHIN_MS = 10_000;
 /**
- * Where an agent is placed, and why it is a placement rather than a link.
+ * Where a node goes, and why that is a grouping rather than a link.
  *
  * `claude agents --json` prints interactive and background sessions in one array, and
  * publishes nothing that ties an agent to whoever dispatched it. The working directory is
- * the only field both carry, so it is what an agent is placed BY — it lands next to the
- * session sharing its directory, and nothing is ever nested inside anything. Nesting would
- * assert a parentage the source does not contain, and it would let this page show a smaller
- * fleet than the table beside it.
+ * the only field both carry, so it is the only thing nodes are grouped BY — they share a
+ * berth, and nothing is ever nested inside anything. Nesting would assert a parentage the
+ * source does not contain, and it would let this page show a smaller fleet than the table
+ * beside it.
  *
- * The agents are gathered separately because the fleet sorts busy sessions first, so one can
- * arrive before the session it belongs beside. An agent whose directory matches no session
- * keeps a node of its own, at the end.
+ * One pass, in the fleet's own order, and each berth takes its place at its FIRST node: the
+ * rank that lifts a session halted on a human above everything else lifts the frame around it
+ * too, whether the node that earned it is a session or an agent. An agent whose directory
+ * matches no session is a berth of its own, ordered like any other — being last was the flat
+ * grid's arrangement of it, never the data's.
  */
 export function buildMap({ rows }, { pulseWithinMs = PULSE_WITHIN_MS } = {}) {
     // Whether this fleet still speaks the kind we know. If NOTHING calls itself `interactive`,
@@ -53,31 +61,30 @@ export function buildMap({ rows }, { pulseWithinMs = PULSE_WITHIN_MS } = {}) {
                 row.snapshotAgeMs <= pulseWithinMs,
         };
     };
-    const agents = rows.filter((r) => roleOf(r) === 'agent');
-    const placed = new Set();
-    const seen = new Set();
-    const nodes = [];
+    const berths = [];
+    const byCwd = new Map();
     for (const r of rows) {
-        if (roleOf(r) !== 'session')
-            continue;
-        nodes.push(node(r));
-        // Only the first session of a directory collects them, or two sessions in one checkout
-        // would each grow a copy of the same agents.
-        if (r.cwd === null || seen.has(r.cwd))
-            continue;
-        seen.add(r.cwd);
-        for (const a of agents) {
-            // Two directories nobody could read are not the same directory.
-            if (a.cwd === null || a.cwd !== r.cwd)
-                continue;
-            nodes.push(node(a));
-            placed.add(a);
+        const n = node(r);
+        // Two directories nobody could read are not the same directory, so an absent cwd joins no
+        // key: it opens a berth of its own every time, which is the one honest frame around it.
+        // Absent in both its shapes — `readSessions` carries a `cwd` of `''` through verbatim, and
+        // one module down that empty string is already read as no directory at all (`project` comes
+        // out null). Keyed on it, every such node shared a frame captioned "no directory": the one
+        // claim this shape refuses, made by the nodes that can least support it.
+        let berth = !r.cwd ? undefined : byCwd.get(r.cwd);
+        if (berth === undefined) {
+            // The project, the directory itself, then the words — and the middle one is not a page
+            // that prints paths. `path.basename` answers the empty string for exactly one directory,
+            // the root, so a fleet with a session in `/` had a project of `''`: not the absent cwd
+            // above, and no name either. The fallback names it `/`, which is what was read.
+            berth = { label: r.project || r.cwd || NO_DIRECTORY, sessions: [], agents: [] };
+            berths.push(berth);
+            if (r.cwd)
+                byCwd.set(r.cwd, berth);
         }
+        (n.role === 'session' ? berth.sessions : berth.agents).push(n);
     }
-    for (const a of agents)
-        if (!placed.has(a))
-            nodes.push(node(a));
-    return { nodes };
+    return { berths };
 }
 /**
  * The kind a terminal calls itself, and the anchor this module reasons from. A background

package/dist/render.js

@@ -607,22 +607,86 @@ export function renderPage(fleet, view = 'table') {
   /* ── 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)); }
+     landed moments ago. A background agent is drawn with none of the three — there is no
+     terminal behind it to draw a statusline frame with — and is a strip instead, docked
+     under the cards of its berth, printing as text whatever its snapshot did publish.
+
+     Two layouts, each named, because the two surfaces know different things. The live map
+     groups by working directory (the berths below); the replay behind the scrubber keeps a
+     project name and never the directory it was read in, and a basename is not a directory —
+     a frame drawn on it would group two checkouts of one repository into one. So it stays the
+     flat grid this view was before, which is the honest drawing of what it holds. */
+  .map { gap:.9rem; }
+  .map.berths { display:flex; flex-wrap:wrap; align-items:flex-start; }
+  .map.flat { display:grid; grid-template-columns:repeat(auto-fill,minmax(10.5rem,1fr)); }
+  /* The berth: a frame around the nodes read in one directory, and the label is the whole of
+     what it claims. Quiet on purpose — a hairline and a caption in the grey the rest of the
+     page uses for a heading, because the loud thing on this view is a session's state, and a
+     frame that competed with it would be a box drawn around a fact nobody asked about.
+
+     min-width:0 because a berth is a flex ITEM, and a flex item's automatic minimum size is
+     its min-content width — here the widest strip docked in it, whose prompt is one nowrap
+     line with no length limit. At auto the frame simply grows to fit the prompt: the
+     ellipsis on the strip still resolves, against a column that is never narrower than its own
+     text, so nothing is ever clipped and the page scrolls sideways instead. The flat grid gave
+     the strip a column to be cut to by being a grid; the frame has to say so. */
+  .berth { min-width:0; border:1px solid var(--line); border-radius:12px; padding:.6rem .7rem .7rem; }
+  .berth-label { margin:0 0 .5rem; font-size:.72rem; font-weight:600; text-transform:uppercase;
+          letter-spacing:.06em; color:var(--dim); }
+  /* The cards side by side at their own width, wrapping inside the frame when the directory
+     holds more of them than the row can take. */
+  .berth-cards { display:flex; flex-wrap:wrap; gap:.6rem; align-items:stretch; }
+  .berth-cards .node { width:10.5rem; }
+  /* And the strips docked underneath, full width of the frame, one under the other: a strip is
+     a line of text, and a line of text in a column half a card wide is an ellipsis where the
+     prompt was. Below the cards rather than among them because that is what it is — the
+     directory's background work, under the terminals someone is sitting at — and NOT because
+     one of those terminals dispatched it, which nothing here knows. */
+  .berth-strips { display:flex; flex-direction:column; gap:.4rem; margin-top:.6rem; }
   .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)); }
   .node[data-state="waiting"] { border-color:color-mix(in srgb, var(--wait) 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; }
+  /* An agent is not a smaller session — it is a strip. It was a card at three quarters scale,
+     which put a dial on a session that has no terminal to draw a statusline frame with: a ring
+     that can never fill, captioned with the words of a fault someone could go and repair. The
+     honest form is the one the table already speaks in — text on a line, left-aligned, its
+     state in the same glyph and in a three-pixel accent down the left edge. */
+  /* align-self, never the grid's own align-items: a strip is half the height of the card
+     beside it and must not be stretched to match, but the CARDS in a row still share one
+     height — telling the grid to stop stretching would have changed every session on the page
+     to make room for this one. Scoped to the flat grid, which is the only place a strip has a
+     card beside it: docked in a berth it is a full-width band, and "start" in that column
+     would shrink it to the width of its own prompt. */
+  .map.flat .node[data-role="agent"] { align-self:start; }
+  .node[data-role="agent"] { align-items:stretch; text-align:left;
+          padding:.5rem .7rem .55rem; border-radius:8px;
+          background:color-mix(in srgb, var(--line) 18%, transparent);
+          /* The box goes back to the neutral line the tinted rule above gave it: the accent is
+             the channel that carries state here, and a strip outlined in its hue as well was
+             the same fact said twice, in two weights, on a shape half the size of a card. */
+          border-color:var(--line); border-left-width:3px; border-left-color:var(--dim); }
+  .node[data-role="agent"][data-state="busy"] { border-left-color:var(--busy); }
+  .node[data-role="agent"][data-state="waiting"] { border-left-color:var(--wait); }
+  .node[data-role="agent"][data-state="unknown"] { border-left-color:var(--warn); }
+  .node[data-role="agent"] .who { margin-top:0; width:100%; }
+  /* A strip's project, which since the berths is the REPLAY's business alone: a live strip
+     prints none — the frame around it says the directory — and behind the scrubber there is no
+     frame, and the project is the only name the ring kept. The rule stayed when the markup
+     that used to need it went, or that name would sit at the body's own size, a size and a
+     half larger than the line it is on, on the one surface this suite renders no markup for. */
+  .node[data-role="agent"] .project { font-weight:600; font-size:.8rem; }
+  /* What the node calls itself, at the end of its line: an agent's line already reads as a
+     sentence, and the kind is the word that says it is not a terminal. This one and the prompt
+     below it are scoped to a node like every other rule here: both are words a table cell could
+     want the day it grows one, and unprefixed they would take it. */
+  .node .kind { margin-left:auto; font-size:.6rem; font-weight:700; text-transform:uppercase;
+          letter-spacing:.08em; color:var(--dim); }
+  /* The prompt a background session was named after — the strip's own line, now that the berth
+     around it carries the directory. One line, clipped: it is a sentence somebody typed, and
+     it is the only thing on the strip that has no length limit. */
+  .node .prompt { flex:1; min-width:0; color:var(--dim); font-size:.76rem;
+          overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
   /* 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; }
@@ -674,8 +738,12 @@ export function renderPage(fleet, view = 'table') {
   .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; }
+  /* Two fields in one slot, and they are not the same fact. A live card names the SESSION —
+     the berth above it says the directory, and two sessions in one checkout are told apart by
+     nothing else. A replayed card has only the project: the ring never kept a name, for any
+     kind of session, so there is no berth behind the scrubber and no name to put in front. */
+  .who .name, .who .project { font-weight:600; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .node[data-state="busy"] .who .name, .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="waiting"] .shape { color:var(--wait); }
@@ -686,7 +754,7 @@ export function renderPage(fleet, view = 'table') {
   .sub.waiting-for { color:var(--wait); font-weight:600; }
   .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; } }
+  @media (max-width: 30rem) { .map.flat { grid-template-columns:repeat(auto-fill,minmax(8.5rem,1fr)); } .map { 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
@@ -702,6 +770,24 @@ export function renderPage(fleet, view = 'table') {
     tr[data-state="busy"] { border-left-color:var(--busy); }
     tr[data-state="waiting"] { border-left-color:var(--wait); }
     tr[data-state="unknown"] { border-left-color:var(--warn); }
+    /* The frames stop sharing a row, and the cards inside one stop being a fixed column so two
+       of them still fit across a phone. The berth keeps its hairline: a border around a card
+       inside a border around a directory is two hairlines, which is not the weight worth
+       spending a claim on — and dropping the frame here would drop the claim with it. */
+    .berth { width:100%; padding:.5rem .55rem .6rem; }
+    .berth-cards { gap:.5rem; }
+    /* min-width:0 for the reason the berth carries it, and here it is the width that was doing
+       the capping: a card's automatic minimum is its min-content width unless a specified size
+       suggests otherwise, and dropping the fixed column to auto drops that suggestion. A card
+       is then as wide as the name on it, and .who .name is one nowrap line — with a
+       background session named after its prompt, a name with no length limit. Not the exotic
+       case: when nothing in the fleet calls itself interactive, every row is drawn as a card. */
+    .berth-cards .node { flex:1 1 8.5rem; width:auto; min-width:0; }
+    /* A strip sharing a phone's width with a card is an ellipsis where the prompt was — the
+       one line saying what this agent was told to do is the first thing a narrow column takes
+       away. It spans the row instead, like the cells below it. The berth docks its own strips
+       full width at every size, so what this rule is left covering is the REPLAY's flat grid. */
+    .node[data-role="agent"] { grid-column:1 / -1; }
     td, td:first-child { border:0; padding:.2rem 0; white-space:normal;
          display:flex; justify-content:space-between; align-items:baseline; gap:1rem; }
     td::before { content:attr(data-label); color:var(--dim); font-size:.72rem; font-weight:600;
@@ -759,7 +845,7 @@ export function renderPage(fleet, view = 'table') {
        would be a claim about nothing. -->
   <div class="limits" id="replay-limits" role="group" aria-label="account rate limits, at the minute being replayed" hidden></div>
   <div class="meta" id="replay-meta"></div>
-  <div class="map" id="replay-map"></div>
+  <div class="map flat" id="replay-map"></div>
 </div>
 <!-- A dead handle is worse than no handle: this is revealed once the record is in hand, and
      what it says it covers is whatever the record answered with. -->
@@ -978,7 +1064,18 @@ function pageScript(view) {
       // A gap that says it is a gap is not a gap. The handle steps through readings, not
       // through minutes, and a record with holes in it is not a smooth walk.
       + (record.missed ? ', ' + record.missed + ' minute' + (record.missed === 1 ? '' : 's') + ' with no reading' : '')
-      + '. The record keeps each reading, not how old that reading was, so nothing replayed here is dated.';
+      + '. The record keeps each reading, not how old that reading was, so nothing replayed here is dated.'
+      // The other thing the ring does not hold, said where the reader meets it: the argument
+      // for an ungrouped replay was written in the README, the manual, the changelog and a
+      // comment in this sheet, and nowhere the reader can see it. Shown less and told nothing,
+      // a reader reads it as a rendering that broke.
+      //
+      // A standing property of the record, never an event. This line sits in the scrubber's own
+      // block, outside the live fragment and outside the replay one, so it is on the page from
+      // the moment the record lands — and a sentence saying the grouping had gone would be
+      // printed under a live map with the grouping on it.
+      + ' It keeps a project name and never the directory a node was read in, so the past is'
+      + ' drawn ungrouped, in the order the sample carries.';
   }
 
   function ready() {
@@ -1040,6 +1137,26 @@ function pageScript(view) {
     // unescaped, and into the glyph slot as a function body.
     var state = own(SHAPE, x.state) ? x.state : 'unknown';
     var pct = typeof x.ctxPct === 'number' ? x.ctxPct : null;
+    // The live view's rule about agents, in the copy of it that ships to the browser: a strip,
+    // never a dial. A replay drawing agents as rings while the page one draws them as strips
+    // would read as two kinds of thing — and the ring is the surface that can LEAST fill a
+    // gauge, since it keeps a reading and never the terminal that produced it. No prompt line:
+    // a background session is named after the prompt it was given, and the record stores no
+    // names. What it does hold for one is a percentage and what it cost — printed like
+    // anywhere else, the percentage labelled as the live strip labels it, since neither a ring
+    // nor a column header is here to say which quantity it is. No model and no effort: a
+    // sample is not a snapshot, and the record was never given either.
+    if (role === 'agent') {
+      return '<article class="node" data-role="agent" data-state="' + state + '" data-reading="undatable">'
+        + '<div class="who"><span class="shape" aria-hidden="true">' + SHAPE[state] + '</span>'
+        + '<span class="sr">' + state + '</span>'
+        + '<span class="project">' + esc(x.project) + '</span>'
+        + '<span class="kind">' + esc(x.kind) + '</span></div>'
+        + (state === 'waiting' && x.waitingFor ? '<div class="sub waiting-for">' + esc(x.waitingFor) + '</div>' : '')
+        + (pct === null ? '' : '<div class="sub">ctx ' + pct + '%</div>')
+        + (typeof x.costUsd === 'number' ? '<div class="sub">$' + x.costUsd.toFixed(2) + '</div>' : '')
+        + '</article>';
+    }
     // The ring keeps each reading and never how old that reading was, so the arc weight that
     // says how much a reading may be believed cannot be earned here. It is not the live
     // default either: this third value is de-weighted in the stylesheet, and never the warning
@@ -1144,9 +1261,11 @@ function pageScript(view) {
   function nodesOf(s) {
     var anchored = false, html = '', i;
     for (i = 0; i < s.sessions.length; i++) if (s.sessions[i].kind === INTERACTIVE) anchored = true;
-    // In the order the sample carries. The live map places an agent beside the session it
-    // shares a directory with; the ring holds no directory, so the past is drawn in the order
-    // the fleet was sorted in rather than in a grouping this page would have to invent.
+    // In the order the sample carries, flat. The live map frames its nodes by working
+    // directory; the ring holds a project name and never the directory it was read in, and a
+    // basename is not a directory — a frame drawn on it would put two checkouts of one
+    // repository behind one label. So the past keeps the order the fleet was sorted in, rather
+    // than a grouping this page would have to invent a key for.
     for (i = 0; i < s.sessions.length; i++) html += nodeOf(s.sessions[i], anchored);
     return html;
   }
@@ -1300,21 +1419,45 @@ const stateLabel = (state, r) => state === 'waiting' && r.waitingFor ? `${stateW
  */
 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.
+ * The map: one node per session, grouped into berths rather than laid out as 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.
+ * one thing they do carry is the working directory, and that is what a berth is drawn around.
+ * A frame is the cheapest way to say "these were read in one place" and the hardest to
+ * misread as a line between two of them.
  *
  * 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>`;
+    return `<div class="map berths">${buildMap(fleet).berths.map(renderBerth).join('')}</div>`;
+}
+/**
+ * One berth: a frame, a label, the cards of the directory, and the strips docked under them.
+ *
+ * The label is the WHOLE of what the frame claims — these nodes were read in this directory.
+ * Nothing in here says which node dispatched which, because `claude agents --json` publishes
+ * no such field: no order, no position and no line inside the frame means "parent of". The day
+ * that relation is published it is drawn between nodes already sitting side by side, and this
+ * function is where it would go — inside a berth, without moving one.
+ *
+ * Named for the reader who is handed no border at all: the frame is a group with the project
+ * for its name, and the heading says the same word for one navigating by headings. Each half
+ * is drawn only if it has something in it, so an orphan agent's berth is a frame with a strip
+ * in it rather than a frame with an empty row above one.
+ *
+ * `role="group"` explicitly, which is what a named `<section>` would NOT be: that is a region,
+ * a landmark, and one per working directory turns a busy machine into a page of landmarks all
+ * named after a basename — several of them possibly the same basename, since two checkouts of
+ * `atlas` are two berths with one label. The name is what this frame is worth to a screen
+ * reader; a place in the landmark index is not, and `group` is the idiom the page already uses
+ * for every other named box on it.
+ */
+function renderBerth({ label, sessions, agents }) {
+    return `<section class="berth" role="group" aria-label="${esc(label)}"><h2 class="berth-label">${esc(label)}</h2>${sessions.length === 0 ? '' : `<div class="berth-cards">${sessions.map(renderNode).join('')}</div>`}${agents.length === 0 ? '' : `<div class="berth-strips">${agents.map(renderNode).join('')}</div>`}</section>`;
 }
 /**
  * One node. Five facts, in five channels that do not depend on colour alone: the arc is how
@@ -1326,6 +1469,11 @@ export function renderMap(fleet) {
  * One state brings a caption with it. A waiting session is the only one where the shape
  * leaves a question the source can answer — which human answer it is halted on — and it is
  * printed directly under the name, not hidden in a title attribute nobody hovers on a phone.
+ *
+ * Two shapes, and the split is what a node HAS rather than what it is worth: a session has a
+ * terminal, so the dial and its four facts are drawn for it. A background agent has no
+ * terminal to draw a frame with, and gets the strip below — same data attributes, same glyph,
+ * same words to a screen reader, and whatever its snapshot published, as text on one line.
  */
 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
@@ -1341,18 +1489,50 @@ function renderNode({ row: r, role, state, reading, measured, pulse }) {
         : 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.
+    // The strip. What it dropped was the dial, never the reading: the ring on an agent could
+    // never fill — there is no terminal here to draw a statusline frame with — and the middle of
+    // it read "not chained", the vocabulary of a repairable fault ("run `tarmac install`") said
+    // about a session no install can ever cover. So no gauge, no dash, no reason where the
+    // source published nothing, and the three fields it does publish about an agent in text: its
+    // state, the kind it calls itself, and the prompt it was named after.
+    //
+    // Nor a halo: it is a ring drawn inside the dial, and this shape has neither. What it says —
+    // a reading landed seconds ago — is the one claim on this page nobody can look away from,
+    // and it is not the fact a strip exists to carry.
+    //
+    // Nor the project: the berth around this strip says the directory once, for every node in
+    // it, and a strip that repeated it would print `harbor` four times inside one frame. What
+    // the line spends itself on instead is what tells two agents in one berth apart — the prompt
+    // it was named after, and the kind it calls itself. Nothing here points at a node beside it:
+    // sharing a frame is sharing a directory, and that is all it has ever been.
+    if (role === 'agent') {
+        // The rule for the rest: the strip prints what that session's snapshot published, and
+        // nothing where nothing was published. The percentage, the model and the effort come out
+        // of one file — `buildFleet` reads all three off the same object — so an agent the join
+        // found a payload for shows all of them, on one line, beside the reading's age when it is
+        // one nobody should take for current. The number carries its own label: a card has a ring
+        // around it and the table a column header over it, and a bare `61%` under a line of prompt
+        // reads as how much of the prompt is done. Each part is dropped on its own field being
+        // null — a snapshot with no turn behind it has a model in it and no percentage.
+        const published = [pct === null ? null : `ctx ${pct}%`, r.model, r.effort]
+            .filter((v) => v !== null && v !== '')
+            .map(esc)
+            .join(' · ');
+        return `<article class="node" data-role="${role}" data-state="${state}" data-reading="${reading}">
+      <div class="who"><span class="shape" aria-hidden="true">${SHAPE[state]}</span><span class="sr">${esc(stateWord(state, r))}</span><span class="prompt">${esc(r.name)}</span><span class="kind">${esc(r.kind)}</span></div>
+      ${state === 'waiting' && r.waitingFor ? `<div class="sub waiting-for">${esc(r.waitingFor)}</div>` : ''}
+      ${published === '' ? '' : `<div class="sub">${published}</div>`}
+      ${asOf}
+    </article>`;
+    }
     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="who"><span class="shape" aria-hidden="true">${SHAPE[state]}</span><span class="sr">${esc(stateWord(state, r))}</span><span class="name">${esc(r.name)}</span></div>
       ${state === 'waiting' && r.waitingFor ? `<div class="sub waiting-for">${esc(r.waitingFor)}</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}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",