aicodeman 1.34.0 → 1.40.0

package/dist/web/public/{constants.d95fade9.js → constants.c0f8f9de.js}

@@ -207,6 +207,9 @@ function shouldAutoWrapTabs(input) {
   if (!input || input.deviceType !== 'desktop') return false;
   if (input.manualTwoRows) return false;
   if ((input.tabCount || 0) < 2) return false;
+  // A box in the strip already wraps inside itself (a case cluster wider than the
+  // whole strip): the strip has rows although nothing overflows.
+  if (input.innerWrap) return true;
 
   const scrollWidth = Number(input.scrollWidth) || 0;
   const clientWidth = Number(input.clientWidth) || 0;
@@ -296,139 +299,307 @@ function computeTabScrollLeft(input) {
   return Math.min(Math.max(Math.round(target), 0), maxScroll);
 }
 
-// Session lineage lines — geometry for the arc drawn between a tab and a tab it
+// Session lineage lines: geometry for the lines joining a tab to the tabs it
 // spawned (a worker started through the codeman agent skill, which passes its own
 // id as parentSessionId). Pure: the caller measures and appends, this decides.
 //
-// ONE shape, because both endpoints live in the same horizontal strip and the subagent
-// shape (tab-bottom → window-top) has nothing to aim at: a U-bridge HANGING BELOW the
-// strip, from the parent's bottom edge to the child's bottom edge, so it reads as a
-// bracket joining two tabs rather than as a line crossing them. The dip grows with
-// horizontal distance and with `depth` (the child's index among its siblings), so
-// several children of one parent nest instead of overprinting.
+// ONE TREE PER SPAWNING TAB. Every family is drawn, the selected tab's emphasized
+// (session-lineage.js). Every route starts at the PARENT and ends at one child, so
+// a parent's routes share their first stretch exactly: overlaid, they read as one
+// trunk with a branch per child, and a dashed (working) route stays in phase with
+// its siblings along the shared part.
 //
-// ⚠ A WRAPPED STRIP USED TO GET ITS OWN SHAPE, AND THAT SHAPE WAS THE BUG. When the
-// desktop strip wraps (`tabs-two-rows` / `tabs-auto-wrap`) a parent on row 1 and its
-// child on row 2 are ~4px apart vertically, so the old parent-bottom → child-TOP bezier
-// had a 4px span to work with and drew a flat horizontal line inside the row gap
-// (reported as "they connect already, but the lines are straight and not easy visible"),
-// and three siblings drew three of them on top of each other. Aiming BOTH ends at the
-// tab BOTTOMS and putting the control points below the LOWER row gives the wrapped case
-// the same bracket as the flat case: it leaves the parent downward, crosses the lower
-// row once, and comes back up under the child. Same formula, no branch.
+// ⚠ ROUTES RUN IN THE GAPS, NEVER THROUGH A TAB. This replaced one bezier per
+// child hanging below the strip, which in a wrapped strip crossed every lower
+// row's labels and the terminal text (owner screenshot 2026-10-06: a parent on
+// row 3 with ten children, "too confusing"). A route now moves horizontally only
+// inside a row gap, and vertically only along a tab's own stem (its bottom edge to
+// the gap right under it) or along the SPINE, a channel left of every row that
+// joins the gaps of different rows. styles.css reserves that room
+// (`.session-tabs.lineage-tree`: a wider row gap, bottom padding for the last
+// row's gap, and the spine channel on the left of a wrapped strip).
 //
-// Returns null when the edge must not be drawn: a missing/degenerate rect, or an
-// endpoint scrolled outside the strip. `.session-tabs` is `overflow-x: auto`, so a
-// scrolled-out tab still HAS a rect — one lying over the logo or the header
-// buttons. Skipping is honest; clamping would point at a tab that isn't there.
-// ⚠ THE DIP IS WHAT MAKES THE ARC AN ARC, and it has now been mis-tuned in BOTH
-// directions, so treat these numbers as a corridor rather than a dial to crank:
-// - Too shallow (the first ship, 44px cap): a skill worker is appended to the END of
-//   the strip, so a lead-to-worker span is 800-1500px, and a 44px cap over 1300px is
-//   a 33px sag, a line that reads as STRAIGHT across the terminal (#285).
-// - Too deep (the 104px cap that replaced it): in the wrapped-strip case the cap and
-//   the FULL row offset stacked, bowing the bracket ~106px into the terminal text
-//   (owner screenshot 2026-08-15, "die Linien machen einen grossen Bogen nach unten").
-// The dip is measured from the STRIP'S BOTTOM EDGE (falling back to the lower tab
-// bottom when the strip rect is missing or shorter than its tabs), which buys two
-// things at once: the bow needs no per-row offsets stacked on top, and a same-row
-// arc between ROW-1 tabs of a wrapped strip clears row 2's labels instead of being
-// drawn through them (the retune's own first draft had exactly that regression).
-const LINEAGE_DIP_BASE_PX = 14;
-const LINEAGE_DIP_PER_PX = 0.06;
-const LINEAGE_DIP_MIN_PX = 22;
-const LINEAGE_DIP_MAX_PX = 64;
-// Siblings nest by this much. Widened with the stroke: at 2.5px plus its glow, arcs 6px
-// apart bled into one thick band instead of reading as three separate lines.
-const LINEAGE_SIBLING_STEP_PX = 8;
+// The channel is at the strip's left edge, except where a tab arrangement puts
+// something there: grouped by state, the edge holds the label column and the
+// channel opens between the labels and the tabs. session-lineage.js measures it
+// and passes its left edge as `spineLeft`; without one it is the strip's edge.
+//
+// Rows come from computeLineageRows() over EVERY tab in the strip, not only the
+// endpoints: a row's gap sits under its TALLEST tab (the active tab is 2px
+// taller), or siblings in one row would hang their bus at different heights.
+//
+// computeLineageTree() returns null when the parent cannot be drawn (missing or
+// degenerate rect, scrolled out of the strip); a child that cannot be drawn is
+// left out of `routes`. `.session-tabs` scrolls, so a scrolled-out tab still HAS a
+// rect, lying over the logo or the header buttons. Skipping is honest; clamping
+// would point at a tab that is not there.
+//
+// A child is also left out when its route has nowhere to run: rows whose spans
+// overlap are one row (no gap between them), a row with no gap under it routes
+// nothing, and a route that would still cross a tab is dropped whole. So no tab
+// arrangement can put a line through a tab; a layout without the reserved room
+// loses lines instead.
+const LINEAGE_CORNER_RADIUS_PX = 10;
+// Families drawn together take separate lanes: gap lines this far apart, spines
+// LINEAGE_SPINE_STEP_PX apart.
+const LINEAGE_LANE_STEP_PX = 3.5;
+// Every family is drawn at once, and a 12px row gap only fits this many lanes at
+// LINEAGE_LANE_STEP_PX; session-lineage.js cycles families through them.
+const LINEAGE_MAX_LANES = 3;
+const LINEAGE_SPINE_INSET_PX = 6;
+const LINEAGE_SPINE_STEP_PX = 4;
+// The last row has no row below it; with no strip rect to measure, its gap is
+// taken to be this deep.
+const LINEAGE_LAST_GAP_PX = 12;
+// Narrower than this, the space between two rows is not a gap a route can run in.
+const LINEAGE_MIN_GAP_PX = 2;
+const LINEAGE_ROW_TOLERANCE_PX = 6;
 const LINEAGE_STRIP_TOLERANCE_PX = 4;
-// How far the vertical bracket sits in from the rail's left edge. It has to
-// clear the VIEWPORT edge, not just the tabs: the line carries an 11px outer
-// glow, so a track at 6px had half of that glow clipped away and the arc read
-// as a thin thread pinned to the window frame. The rail reserves the channel
-// itself (`--lineage-vertical-gutter` on the rail's .session-tabs), and
-// computeLineagePath still clamps the track to stay left of both tabs.
+// How far the vertical rail's track sits in from the rail's left edge. It has to
+// clear the VIEWPORT edge, not just the tabs, or the line reads as a thread pinned
+// to the window frame. The rail reserves the channel itself
+// (`--lineage-vertical-gutter` on the rail's .session-tabs), and the track is
+// still clamped to stay left of every endpoint.
 const LINEAGE_VERTICAL_TRACK_INSET_PX = 10;
-const LINEAGE_VERTICAL_SIBLING_STEP_PX = 3;
+const LINEAGE_VERTICAL_LANE_STEP_PX = 4;
 const LINEAGE_VERTICAL_ANCHOR_CLEARANCE_PX = 4;
 // Lineage palette, assigned per SPAWNING TAB in first-seen order and cycled
-// (session-lineage.js). Every arc leaving one tab shares its colour however many
-// workers it spawns; a child that spawns in turn gets its own for the arcs below it.
+// (session-lineage.js). Every line leaving one tab shares its colour however many
+// workers it spawns; a child that spawns in turn gets its own for the lines below it.
 // The empty FIRST entry means "no override": the CSS then falls back to --session-blue,
-// which every skin block tunes for its own background, so a lone arc keeps the
+// which every skin block tunes for its own background, so a lone family keeps the
 // skin-aware blue that shipped in 1.18.2. The fixed entries are deliberately vivid
-// (owner call 2026-08-15: matrix green, pinkish, violet, red, turquoise "and so on");
-// they ride the same double glow as the blue, which is what keeps them legible over
-// terminal text on every skin.
+// (owner call 2026-08-15: matrix green, pinkish, violet, red, turquoise "and so on").
 const LINEAGE_COLORS = ['', '#00ff66', '#ff5ea8', '#a78bfa', '#ff5252', '#2dd4bf', '#ffa940'];
 
-function computeLineagePath(input) {
-  const parent = input?.parent;
-  const child = input?.child;
-  if (!parent || !child) return null;
+/** A rect normalized to numbers with its edges and center, or null if unusable. */
+function lineageRect(rect) {
+  if (!rect) return null;
+  const left = Number(rect.left);
+  const top = Number(rect.top);
+  const width = Number(rect.width);
+  const height = Number(rect.height);
+  if (![left, top, width, height].every(Number.isFinite) || width <= 0 || height <= 0) return null;
+  return {
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    cx: left + width / 2,
+    cy: top + height / 2,
+  };
+}
+
+/**
+ * Group tab rects into the strip's visual rows, top to bottom. A row spans from its
+ * highest top to its LOWEST bottom, so a taller tab (the active one) sets the row's
+ * gap for everyone in it.
+ *
+ * ⚠ Rows never overlap. Tabs whose spans overlap are in one row however far apart
+ * their tops are: case clusters stack and centre tabs inside their boxes, and two
+ * overlapping "rows" put the gap of one in the middle of the other's tabs.
+ */
+function computeLineageRows(rects) {
+  const sorted = [];
+  for (const raw of rects || []) {
+    const r = lineageRect(raw);
+    if (r) sorted.push(r);
+  }
+  sorted.sort((a, b) => a.top - b.top);
+  const rows = [];
+  for (const r of sorted) {
+    // Sorted by top, so only the last row can take this rect, and merging into it
+    // keeps every earlier row clear of it.
+    const row = rows[rows.length - 1];
+    if (row && (r.top < row.bottom || r.top - row.top <= LINEAGE_ROW_TOLERANCE_PX)) {
+      row.bottom = Math.max(row.bottom, r.bottom);
+    } else {
+      rows.push({ top: r.top, bottom: r.bottom });
+    }
+  }
+  return rows;
+}
+
+/** Does an axis-aligned segment pass through the inside of a rect? Touching an edge is fine. */
+function lineageSegmentCrosses([x1, y1], [x2, y2], r) {
+  const eps = 0.5;
+  if (Math.max(x1, x2) <= r.left + eps || Math.min(x1, x2) >= r.right - eps) return false;
+  return Math.max(y1, y2) > r.top + eps && Math.min(y1, y2) < r.bottom - eps;
+}
 
-  const pw = Number(parent.width) || 0;
-  const ph = Number(parent.height) || 0;
-  const cw = Number(child.width) || 0;
-  const ch = Number(child.height) || 0;
-  if (pw <= 0 || ph <= 0 || cw <= 0 || ch <= 0) return null;
+/**
+ * An orthogonal polyline as an SVG path, each corner rounded by up to `radius`
+ * (never more than half of either segment, so short stems stay short). Repeated and
+ * collinear points are dropped first, so a degenerate corner draws nothing odd.
+ */
+function lineagePolylinePath(points, radius) {
+  const pts = [];
+  for (const p of points) {
+    const prev = pts[pts.length - 1];
+    if (prev && Math.abs(prev[0] - p[0]) < 0.5 && Math.abs(prev[1] - p[1]) < 0.5) continue;
+    const before = pts[pts.length - 2];
+    if (before && prev) {
+      const cross = (prev[0] - before[0]) * (p[1] - prev[1]) - (prev[1] - before[1]) * (p[0] - prev[0]);
+      if (Math.abs(cross) < 0.01) pts.pop();
+    }
+    pts.push(p);
+  }
+  if (pts.length < 2) return null;
+  let d = `M ${r1(pts[0][0])} ${r1(pts[0][1])}`;
+  for (let i = 1; i < pts.length - 1; i++) {
+    const [x0, y0] = pts[i - 1];
+    const [x1, y1] = pts[i];
+    const [x2, y2] = pts[i + 1];
+    const lenIn = Math.hypot(x1 - x0, y1 - y0);
+    const lenOut = Math.hypot(x2 - x1, y2 - y1);
+    const r = Math.min(radius, lenIn / 2, lenOut / 2);
+    if (!(r > 0.5)) {
+      d += ` L ${r1(x1)} ${r1(y1)}`;
+      continue;
+    }
+    const ax = x1 - ((x1 - x0) / lenIn) * r;
+    const ay = y1 - ((y1 - y0) / lenIn) * r;
+    const bx = x1 + ((x2 - x1) / lenOut) * r;
+    const by = y1 + ((y2 - y1) / lenOut) * r;
+    d += ` L ${r1(ax)} ${r1(ay)} Q ${r1(x1)} ${r1(y1)} ${r1(bx)} ${r1(by)}`;
+  }
+  const last = pts[pts.length - 1];
+  return d + ` L ${r1(last[0])} ${r1(last[1])}`;
+}
 
+/**
+ * Routes from one parent tab to each of its children.
+ *
+ * input: { parent, children: [{ id, rect }], strip?, tabs?, spineLeft?,
+ *          orientation?, lane?, laneCount?, radius? }. `tabs` is every tab rect in
+ *          the strip (rows are derived from it); `spineLeft` is the left edge of the
+ *          spine channel (default: the strip's left edge); `lane`/`laneCount`
+ *          separate families drawn together.
+ * Returns { routes: [{ id, points, d, endX, endY }] } or null.
+ */
+function computeLineageTree(input) {
+  const parent = lineageRect(input?.parent);
+  if (!parent) return null;
+  const strip = lineageRect(input?.strip);
   const orientation = input?.orientation === 'vertical' ? 'vertical' : 'horizontal';
-  const strip = input?.strip;
-  const depth = Math.max(0, Math.min(6, Number(input?.depth) || 0));
-  const pLeft = Number(parent.left);
-  const cLeft = Number(child.left);
-  const pTop = Number(parent.top);
-  const cTop = Number(child.top);
-  if (![pLeft, cLeft, pTop, cTop].every(Number.isFinite)) return null;
+  const laneCount = Math.max(1, Math.floor(Number(input?.laneCount)) || 1);
+  const lane = Math.max(0, Math.min(laneCount - 1, Math.floor(Number(input?.lane)) || 0));
+  const radius = Number.isFinite(Number(input?.radius)) ? Math.max(0, Number(input.radius)) : LINEAGE_CORNER_RADIUS_PX;
+  const children = [];
+  for (const child of input?.children || []) {
+    const rect = lineageRect(child?.rect);
+    if (rect) children.push({ id: child.id, rect });
+  }
+
+  const tol = LINEAGE_STRIP_TOLERANCE_PX;
+  const inStripY = (r) => !strip || (r.cy >= strip.top - tol && r.cy <= strip.bottom + tol);
+  const inStripX = (r) => !strip || (r.cx >= strip.left - tol && r.cx <= strip.right + tol);
+  const routes = [];
 
   if (orientation === 'vertical') {
-    const py = pTop + ph / 2;
-    const cy = cTop + ch / 2;
-    if (strip && Number(strip.height) > 0) {
-      const min = Number(strip.top) - LINEAGE_STRIP_TOLERANCE_PX;
-      const max = Number(strip.top) + Number(strip.height) + LINEAGE_STRIP_TOLERANCE_PX;
-      if (py < min || py > max || cy < min || cy > max) return null;
+    // The rail: one track down the empty left gutter, shared by every sibling.
+    if (!inStripY(parent)) return null;
+    const visible = children.filter((c) => inStripY(c.rect));
+    if (visible.length === 0) return { routes };
+    const minLeft = Math.min(parent.left, ...visible.map((c) => c.rect.left));
+    const base = strip ? strip.left : minLeft - LINEAGE_VERTICAL_TRACK_INSET_PX * 2;
+    const trackX = Math.min(
+      base + LINEAGE_VERTICAL_TRACK_INSET_PX + lane * LINEAGE_VERTICAL_LANE_STEP_PX,
+      minLeft - LINEAGE_VERTICAL_ANCHOR_CLEARANCE_PX
+    );
+    for (const { id, rect } of visible) {
+      const points = [
+        [parent.left, parent.cy],
+        [trackX, parent.cy],
+        [trackX, rect.cy],
+        [rect.left, rect.cy],
+      ];
+      const d = lineagePolylinePath(points, radius);
+      if (d) routes.push({ id, points: roundPoints(points), d, endX: r1(rect.left), endY: r1(rect.cy) });
     }
-
-    const stripLeft =
-      strip && Number.isFinite(Number(strip.left))
-        ? Number(strip.left)
-        : Math.min(pLeft, cLeft) - LINEAGE_VERTICAL_TRACK_INSET_PX * 2;
-    const requestedTrack =
-      stripLeft + LINEAGE_VERTICAL_TRACK_INSET_PX + depth * LINEAGE_VERTICAL_SIBLING_STEP_PX;
-    const trackX = Math.min(requestedTrack, Math.min(pLeft, cLeft) - LINEAGE_VERTICAL_ANCHOR_CLEARANCE_PX);
-    const d = `M ${r1(pLeft)} ${r1(py)} H ${r1(trackX)} V ${r1(cy)} H ${r1(cLeft)}`;
-    return { d, endX: cLeft, endY: cy, sameRow: false };
+    return { routes };
   }
 
-  const px = pLeft + pw / 2;
-  const cx = cLeft + cw / 2;
-  if (strip && Number(strip.width) > 0) {
-    const min = Number(strip.left) - LINEAGE_STRIP_TOLERANCE_PX;
-    const max = Number(strip.left) + Number(strip.width) + LINEAGE_STRIP_TOLERANCE_PX;
-    if (px < min || px > max || cx < min || cx > max) return null;
+  if (!inStripX(parent) || !inStripY(parent)) return null;
+  const visible = children.filter((c) => inStripX(c.rect) && inStripY(c.rect));
+  if (visible.length === 0) return { routes };
+
+  const rows = computeLineageRows([...(input?.tabs || []), parent, ...visible.map((c) => c.rect)]);
+  const rowOf = (r) => rows.findIndex((row) => r.cy >= row.top - tol && r.cy <= row.bottom + tol);
+  const laneOffset = (lane - (laneCount - 1) / 2) * LINEAGE_LANE_STEP_PX;
+  // Y of the gap under row i, this family's lane. The offset is clamped so a busy
+  // gap never pushes a lane into the tabs on either side of it. Null when there is
+  // no gap: the row is not found, or the next row starts (nearly) where it ends.
+  const gapUnder = (i) => {
+    const row = rows[i];
+    if (!row) return null;
+    const next = rows[i + 1];
+    let bottom;
+    if (next) bottom = next.top;
+    else if (strip && strip.bottom > row.bottom + 1) bottom = strip.bottom;
+    else bottom = row.bottom + LINEAGE_LAST_GAP_PX;
+    if (!(bottom - row.bottom >= LINEAGE_MIN_GAP_PX)) return null;
+    const half = Math.max(0, (bottom - row.bottom) / 2 - 1);
+    return (row.bottom + bottom) / 2 + Math.max(-half, Math.min(half, laneOffset));
+  };
+  const pRow = rowOf(parent);
+  const gp = gapUnder(pRow);
+  if (gp === null) return { routes };
+  // The spine runs from one row's gap to another's, so it only ever passes BESIDE
+  // rows after the first, and only their tabs bound it. The first row may start
+  // left of the channel (grouped by state it starts after the brand and a label
+  // of its own width), and clamping to it would pull the spine back over the
+  // label column.
+  const lowerLefts = [parent, ...visible.map((c) => c.rect), ...(input?.tabs || []).map(lineageRect)]
+    .filter((r) => r && rowOf(r) > 0)
+    .map((r) => r.left);
+  const minLeft = lowerLefts.length
+    ? Math.min(...lowerLefts)
+    : Math.min(parent.left, ...visible.map((c) => c.rect.left));
+  const channelLeft = Number(input?.spineLeft);
+  const spineBase = strip
+    ? Math.max(strip.left, Number.isFinite(channelLeft) ? channelLeft : strip.left)
+    : minLeft - LINEAGE_SPINE_INSET_PX * 2;
+  const spineX = Math.min(spineBase + LINEAGE_SPINE_INSET_PX + lane * LINEAGE_SPINE_STEP_PX, minLeft - 2);
+
+  // Every tab a route must stay out of. A segment can only cross one if the rows
+  // above failed to describe the layout, so this is a backstop that drops the
+  // route whole rather than drawing it through a tab.
+  const obstacles = [parent, ...visible.map((c) => c.rect), ...(input?.tabs || []).map(lineageRect)].filter(Boolean);
+  for (const { id, rect } of visible) {
+    const cRow = rowOf(rect);
+    const gc = gapUnder(cRow);
+    if (gc === null) continue;
+    const points =
+      cRow === pRow
+        ? [
+            [parent.cx, parent.bottom],
+            [parent.cx, gp],
+            [rect.cx, gp],
+            [rect.cx, rect.bottom],
+          ]
+        : [
+            [parent.cx, parent.bottom],
+            [parent.cx, gp],
+            [spineX, gp],
+            [spineX, gc],
+            [rect.cx, gc],
+            [rect.cx, rect.bottom],
+          ];
+    // The rounded corners cut inside each turn by a few pixels at most
+    // (lineagePolylinePath), so the segments are what has to clear the tabs.
+    const blocked = points.some((p, i) => i > 0 && obstacles.some((r) => lineageSegmentCrosses(points[i - 1], p, r)));
+    if (blocked) continue;
+    const d = lineagePolylinePath(points, radius);
+    if (d) routes.push({ id, points: roundPoints(points), d, endX: r1(rect.cx), endY: r1(rect.bottom) });
   }
+  return { routes };
+}
 
-  const pBottom = pTop + ph;
-  const cBottom = cTop + ch;
-  const sameRow = Math.abs(pTop + ph / 2 - (cTop + ch / 2)) <= Math.min(ph, ch) / 2;
-
-  // Both ends anchor on the tab BOTTOM, and the control points hang below the WHOLE
-  // strip, so one formula covers a flat strip, a wrapped pair, and a same-row pair
-  // sitting above further rows (see the corridor note above the constants).
-  const span = Math.abs(cx - px);
-  const stripBottom =
-    strip && Number(strip.height) > 0 && Number.isFinite(Number(strip.top))
-      ? Number(strip.top) + Number(strip.height)
-      : Number.NEGATIVE_INFINITY;
-  const baseline = Math.max(pBottom, cBottom, stripBottom);
-  const dip =
-    Math.min(LINEAGE_DIP_MAX_PX, Math.max(LINEAGE_DIP_MIN_PX, LINEAGE_DIP_BASE_PX + span * LINEAGE_DIP_PER_PX)) +
-    depth * LINEAGE_SIBLING_STEP_PX;
-  const yc = baseline + dip;
-  const d = `M ${r1(px)} ${r1(pBottom)} C ${r1(px)} ${r1(yc)}, ${r1(cx)} ${r1(yc)}, ${r1(cx)} ${r1(cBottom)}`;
-  return { d, endX: cx, endY: cBottom, sameRow };
+function roundPoints(points) {
+  return points.map(([x, y]) => [r1(x), r1(y)]);
 }
 
 // One decimal is plenty for a screen-space path and keeps the `d` string short.
@@ -658,6 +829,194 @@ function sortSessionsByActivity(rows) {
   return (Array.isArray(rows) ? rows.slice() : []).sort(compareSessionActivity);
 }
 
+// Tab grouping by state (`tabArrangement: 'state'`, Discussion #426 option C).
+//
+// The tab list answers "who wants me?" the way the home screens do: a row (the
+// header strip) or a section (the flat side rail, the sidebar) per state, most
+// urgent on top. The states are the home screens' own, from
+// `_mobileOverviewState()` (mobile-overview.js); this only folds the six into
+// four groups a strip can hold:
+//
+//   needs   red: a permission or question dialog is blocking the agent. A
+//           failed session joins it, since it also needs a human and the home
+//           screens rank it right below.
+//   waiting yellow: the agent finished its turn and is waiting on you.
+//   working a turn is running.
+//   idle    everything quiet: idle, ended, and an agent that exited inside a
+//           live pane (#446), which may still read as working on screen but is
+//           running nothing. Web tabs close the group.
+//
+// Applied as the flex `order` property, never by reordering the DOM, the same
+// design as the sorted rail (`_tabRailSortOrder`, app.js): `#sessionTabs` stays
+// in `sessionOrder`, so Alt+N, drag-and-drop and the keyboard walk keep reading
+// the list they always read, and a state change moves one inline style instead
+// of rebuilding the strip. Each group owns a band of `TAB_TRIAGE_STRIDE` order
+// values: its heading at the start of the band, its rows after it, its web tabs
+// after those and the line break that ends the header row at the very end.
+//
+// Pure: no DOM, no `this`. Unit-tested in test/tab-triage.test.ts.
+// `quiet` groups keep their heading element (it anchors the row and holds the
+// row's place beside the brand) but draw no text: everything quiet is the
+// default state of a tab, so naming it only adds noise.
+const TAB_TRIAGE_GROUPS = [
+  { key: 'needs', label: 'Needs you' },
+  { key: 'waiting', label: 'Waiting' },
+  { key: 'working', label: 'Working' },
+  { key: 'idle', label: 'Idle', quiet: true },
+];
+
+const TAB_TRIAGE_GROUP_OF_STATE = {
+  needs: 'needs',
+  error: 'needs',
+  waiting: 'waiting',
+  working: 'working',
+  idle: 'idle',
+  done: 'idle',
+};
+
+const TAB_TRIAGE_STRIDE = 10000;
+/** Offset of a group's web tabs inside its band, past any plausible session count. */
+const TAB_TRIAGE_WEB_OFFSET = 5000;
+
+/**
+ * Which group a session belongs to.
+ * @param {string} state a `_mobileOverviewState()` value
+ * @param {boolean} exited the agent inside the pane has exited (`_mobileOverviewExit()` non-null)
+ * @returns {'needs'|'waiting'|'working'|'idle'}
+ */
+function tabTriageGroupFor(state, exited) {
+  const group = TAB_TRIAGE_GROUP_OF_STATE[state] || 'idle';
+  return exited && group === 'working' ? 'idle' : group;
+}
+
+/**
+ * Order values and visible groups for one pass.
+ *
+ * @param {Array<{id: string, state: string, exited?: boolean, pos?: number}>} rows
+ *   live sessions; `pos` ranks a row inside its group (tab order on the header
+ *   strip, the activity sort's position on a sorted rail). Rows without one keep
+ *   the order they were passed in.
+ * @param {Array<string>} webviewIds open web tabs, in their own tab order
+ * @param {{reverse?: boolean}} [options] `reverse` puts the groups the other
+ *   way up (`tabStateOrder: 'urgent-last'`): idle first, needs you last, for a
+ *   strip read from the bottom. Rows inside a group keep their order.
+ * @returns {{
+ *   order: Map<string, number>,
+ *   webOrder: Map<string, number>,
+ *   groups: Array<{key: string, label: string, quiet: boolean, count: number, headOrder: number, breakOrder: number}>
+ * }} `groups` lists only the non-empty groups, in display order (most urgent
+ *   first, or last with `reverse`).
+ */
+function computeTabTriageLayout(rows, webviewIds, options) {
+  const list = Array.isArray(rows) ? rows : [];
+  const webs = Array.isArray(webviewIds) ? webviewIds : [];
+  const sequence = options && options.reverse ? TAB_TRIAGE_GROUPS.slice().reverse() : TAB_TRIAGE_GROUPS;
+  const baseOf = {};
+  const counts = {};
+  sequence.forEach((group, i) => {
+    baseOf[group.key] = (i + 1) * TAB_TRIAGE_STRIDE;
+    counts[group.key] = 0;
+  });
+
+  const placed = list
+    .filter((row) => row && typeof row.id === 'string')
+    .map((row, i) => ({
+      id: row.id,
+      group: tabTriageGroupFor(row.state, !!row.exited),
+      pos: Number.isFinite(row.pos) ? row.pos : i,
+      index: i,
+    }));
+  const byGroup = {};
+  for (const row of placed) (byGroup[row.group] = byGroup[row.group] || []).push(row);
+
+  const order = new Map();
+  for (const key of Object.keys(byGroup)) {
+    // Stable: equal positions keep the order the caller passed.
+    byGroup[key].sort((a, b) => a.pos - b.pos || a.index - b.index);
+    byGroup[key].forEach((row, i) => order.set(row.id, baseOf[key] + 1 + i));
+    counts[key] = byGroup[key].length;
+  }
+
+  const webOrder = new Map();
+  webs.forEach((id, i) => {
+    if (typeof id === 'string' && id) webOrder.set(id, baseOf.idle + TAB_TRIAGE_WEB_OFFSET + i);
+  });
+  counts.idle += webOrder.size;
+
+  const groups = sequence.filter((group) => counts[group.key] > 0).map((group) => ({
+    key: group.key,
+    label: group.label,
+    quiet: !!group.quiet,
+    count: counts[group.key],
+    headOrder: baseOf[group.key],
+    breakOrder: baseOf[group.key] + TAB_TRIAGE_STRIDE - 1,
+  }));
+
+  return { order, webOrder, groups };
+}
+
+// Tab clusters by case (`tabArrangement: 'case'`, Discussion #426 option A).
+//
+// One cluster per case, in the order the case first appears in the tab order,
+// so the strip keeps the user's arrangement at the case level. Inside a cluster
+// with two or more tabs the `-<case>` part of a generated `w<n>-<case>` name is
+// redundant and is hidden (`tabClusterNameSplit()`), which is what lets 18 tabs
+// read as 7 things. A case with one tab is still its own (unlabelled) box.
+//
+// Cluster colours come from the session palette (`--session-<colour>`) by a
+// stable hash of the case key, so a case keeps its colour across reloads and
+// devices without anything being stored.
+//
+// Pure: no DOM, no `this`. Unit-tested in test/tab-clusters.test.ts.
+const TAB_CLUSTER_COLORS = ['blue', 'green', 'purple', 'orange', 'pink', 'yellow', 'red'];
+
+/** Palette colour for a cluster key: a djb2 hash, so the same key always gets the same colour. */
+function tabClusterColorFor(key) {
+  const text = String(key || '');
+  let hash = 5381;
+  for (let i = 0; i < text.length; i++) hash = ((hash << 5) + hash + text.charCodeAt(i)) | 0;
+  return TAB_CLUSTER_COLORS[Math.abs(hash) % TAB_CLUSTER_COLORS.length];
+}
+
+/**
+ * Group tabs by case.
+ * @param {Array<{id: string, key: string, label: string}>} rows live sessions in
+ *   tab order; `key` identifies the case (its path), `label` names it
+ * @returns {Array<{key: string, label: string, color: string, ids: string[]}>}
+ *   clusters in first-appearance order, members in tab order
+ */
+function computeTabClusters(rows) {
+  const clusters = [];
+  const byKey = new Map();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!row || typeof row.id !== 'string') continue;
+    const key = typeof row.key === 'string' && row.key ? row.key : `session:${row.id}`;
+    let cluster = byKey.get(key);
+    if (!cluster) {
+      cluster = { key, label: typeof row.label === 'string' ? row.label : '', color: tabClusterColorFor(key), ids: [] };
+      byKey.set(key, cluster);
+      clusters.push(cluster);
+    }
+    cluster.ids.push(row.id);
+  }
+  return clusters;
+}
+
+/**
+ * Split a generated `w<n>-<case>` / `s<n>-<case>` name into the part a cluster
+ * shows and the case suffix it hides, or null when the name is anything else
+ * (a custom name, a described `w3-x: fix login`, another case's name). Case is
+ * compared case-insensitively; the hidden part keeps its original spelling so
+ * the full name is still in the DOM.
+ * @returns {{shown: string, hidden: string}|null}
+ */
+function tabClusterNameSplit(name, label) {
+  if (typeof name !== 'string' || typeof label !== 'string' || !label) return null;
+  const match = name.match(/^([ws]\d+)(-.+)$/);
+  if (!match) return null;
+  return match[2].slice(1).toLowerCase() === label.toLowerCase() ? { shown: match[1], hidden: match[2] } : null;
+}
+
 // Terminal font stack — the single source for every xterm surface (the main
 // terminal in terminal-ui.js, the log-viewer terminal in panels-ui.js).
 // "Symbols Nerd Font Mono" is a bundled icons-only webfont (fonts/ +
@@ -961,12 +1320,13 @@ if (typeof window !== 'undefined') {
     plan: planWsReconnect,
   };
   window.CodemanLineage = {
-    computePath: computeLineagePath,
-    DIP_MIN_PX: LINEAGE_DIP_MIN_PX,
-    DIP_MAX_PX: LINEAGE_DIP_MAX_PX,
-    SIBLING_STEP_PX: LINEAGE_SIBLING_STEP_PX,
+    computeTree: computeLineageTree,
+    computeRows: computeLineageRows,
+    CORNER_RADIUS_PX: LINEAGE_CORNER_RADIUS_PX,
+    LANE_STEP_PX: LINEAGE_LANE_STEP_PX,
+    MAX_LANES: LINEAGE_MAX_LANES,
+    SPINE_INSET_PX: LINEAGE_SPINE_INSET_PX,
     VERTICAL_TRACK_INSET_PX: LINEAGE_VERTICAL_TRACK_INSET_PX,
-    VERTICAL_SIBLING_STEP_PX: LINEAGE_VERTICAL_SIBLING_STEP_PX,
     COLORS: LINEAGE_COLORS,
   };
   window.CodemanConnectionLoss = {
@@ -983,6 +1343,18 @@ if (typeof window !== 'undefined') {
     compare: compareSessionActivity,
     sort: sortSessionsByActivity,
   };
+  window.CodemanTabClusters = {
+    COLORS: TAB_CLUSTER_COLORS,
+    colorFor: tabClusterColorFor,
+    compute: computeTabClusters,
+    nameSplit: tabClusterNameSplit,
+  };
+  window.CodemanTabTriage = {
+    GROUPS: TAB_TRIAGE_GROUPS,
+    STRIDE: TAB_TRIAGE_STRIDE,
+    groupFor: tabTriageGroupFor,
+    layout: computeTabTriageLayout,
+  };
   window.CodemanInputLimit = {
     FRAME_MAX_CHARS: INPUT_FRAME_MAX_CHARS,
     PASTE_MAX_CHARS: INPUT_PASTE_MAX_CHARS,
@@ -1458,7 +1830,7 @@ function computeRewriteScrollLine(input) {
  * a `/g` regex, so {@link absoluteFilePathPattern} mints a fresh one per call.
  */
 const FILE_PATH_LINK_PATTERN =
-  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|mp4|webm|mov|mp3|wav))\b/g;
+  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|mp3|wav))\b/g;
 
 /** A fresh, zero-state instance of {@link FILE_PATH_LINK_PATTERN}. */
 function absoluteFilePathPattern() {
@@ -1476,7 +1848,7 @@ function absoluteFilePathPattern() {
  * file in /tmp played fine. test/media-extension-parity.test.ts pins the sync.
  */
 const FILE_PREVIEW_EXTENSIONS = new Set(
-  ('png jpg jpeg gif webp avif bmp ico svg pdf docx pptx mp4 webm mov m4v ogv mp3 wav ogg oga m4a aac flac opus').split(' ')
+  ('png jpg jpeg gif webp avif bmp ico svg pdf docx pptx xlsx mp4 webm mov m4v ogv mp3 wav ogg oga m4a aac flac opus').split(' ')
 );
 
 /** Whether a path's extension is one {@link FILE_PREVIEW_EXTENSIONS} covers. */
@@ -1612,27 +1984,459 @@ function buildSplitPickerSessions(sessions, sessionOrder, excludeId, detachedIds
   const result = [];
   for (const id of sessionOrder) {
     if (id === excludeId) continue;
-    // A detached (popped-out) session's own window already yields its PTY
-    // size (see sendResize's detachedElsewhere guard in terminal-ui.js) —
-    // Pane B's SplitTerminalPane._sendResize() has no such check, so letting
-    // one into the picker put its detached window and Pane B in a fight over
-    // the same PTY's dimensions.
+    // A detached (popped-out) session's own window owns its PTY size (see
+    // sendResize's detachedElsewhere guard in terminal-ui.js;
+    // TerminalTile._sendResize() stands aside the same way), so Pane B could
+    // only show it at a size it cannot set.
     if (detachedIds?.has?.(id)) continue;
     const session = sessions.get(id);
     if (!session) continue;
     // A session with no PTY attached (exited CLI, a crash-looped session
     // whose breaker tripped, a restore that failed to re-attach) has nothing
-    // reading its tmux pane. SplitTerminalPane never does selectSession()'s
-    // re-attach POST, so its socket would open onto a pane nothing feeds:
-    // no terminal events, and Session.write() silently drops every keystroke
-    // with no ack either way (Pane B sends no `seq`), so the loss is
-    // invisible — the healthy socket never trips the disconnect banner.
+    // reading its tmux pane, and the split never does selectSession()'s
+    // re-attach POST: Pane B would open a healthy-looking socket onto a pane
+    // that nothing feeds and nothing reads.
     if (session.pid === null) continue;
     result.push({ id, label: session.name || 'Session' });
   }
   return result;
 }
 
+// ── Tile grid (tile-grid.js) ───────────────────────────────────────────────
+//
+// Pure layout and state helpers for the tile grid (docs/tile-grid-plan.md):
+// 1 to TILE_GRID_MAX live sessions side by side, each in its own TerminalTile.
+// Desktop only, behind the same 1180px gate as the split pane.
+
+/**
+ * Hard cap on tiles in one grid: the ONE place it is set (owner decision 7 in
+ * docs/tile-grid-plan.md). Six was tested smooth on a real desktop; nine missed
+ * the headless frame bar and is untested on hardware. Everything that limits
+ * the grid reads this, and the layout table still covers up to TILE_LAYOUT_MAX,
+ * so raising the cap is this one line.
+ */
+const TILE_GRID_MAX = 6;
+/** The largest count the layout table covers (3x3). Never a cap by itself. */
+const TILE_LAYOUT_MAX = 9;
+// The smallest tile worth showing: about 60 columns and a dozen rows at the
+// default tile font. Bounds how many tiles a window can hold.
+const TILE_MIN_W = 480;
+const TILE_MIN_H = 240;
+// Three tiles go side by side (3x1) only when each still gets ~600px;
+// otherwise they take three cells of a 2x2.
+const TILE_GRID_WIDE_3X1 = 1800;
+// A tile's xterm keeps this many lines, not DEFAULT_SCROLLBACK: a grid of DOM
+// renderers at 50k lines each is a real memory cost, and a tile's load is a
+// bounded 1 MiB window anyway, so more scrollback only fills with live output.
+const TILE_SCROLLBACK = 10000;
+// Tiles have their own per-device font size (a tile is a fraction of the screen).
+const TILE_FONT_SIZE_DEFAULT = 13;
+// What the page's SSE filter names while tiles own the terminal: a value no
+// session id takes (ids are UUIDs), so the server, whose filter gates only
+// session:terminal batches, sends none. The tiles carry their own output over
+// their own sockets, and the parked main terminal only parsed those frames to
+// drop them (16 to 18 a second for one busy shell). Every other event still
+// arrives (test/sse-tile-grid-filter.test.ts pins the server's side of this).
+const TILE_GRID_SSE_FILTER = 'tile-grid';
+
+/**
+ * Columns and rows for `count` tiles, by count (the spec's table), and whether
+ * that layout gives every cell at least the minimum tile size (TILE_MIN_W x
+ * TILE_MIN_H) in a grid area of `width` x `height` px.
+ *
+ * @param {{count: number, width?: number, height?: number}} p
+ * @returns {{cols: number, rows: number, fits: boolean}}
+ */
+function computeTileLayout({ count, width = Infinity, height = Infinity }) {
+  const n = Math.min(Math.max(0, Math.floor(Number(count) || 0)), TILE_LAYOUT_MAX);
+  let cols;
+  let rows;
+  if (n === 0) return { cols: 0, rows: 0, fits: true };
+  if (n === 1) { cols = 1; rows = 1; }
+  else if (n === 2) { cols = 2; rows = 1; }
+  else if (n === 3) {
+    if (width >= TILE_GRID_WIDE_3X1) { cols = 3; rows = 1; }
+    else { cols = 2; rows = 2; }
+  }
+  else if (n === 4) { cols = 2; rows = 2; }
+  else if (n <= 6) { cols = 3; rows = 2; }
+  else { cols = 3; rows = 3; }
+  const fits = width / cols >= TILE_MIN_W && height / rows >= TILE_MIN_H;
+  return { cols, rows, fits };
+}
+
+/**
+ * How many tiles a grid area can hold: the largest count up to TILE_GRID_MAX
+ * whose layout, and every smaller count's layout, fits. 0 when not even one
+ * tile fits.
+ *
+ * @param {{width: number, height: number}} p
+ * @returns {number}
+ */
+function tileGridCapacity({ width, height }) {
+  let capacity = 0;
+  for (let n = 1; n <= TILE_GRID_MAX; n++) {
+    if (!computeTileLayout({ count: n, width, height }).fits) break;
+    capacity = n;
+  }
+  return capacity;
+}
+
+/**
+ * The stored grid (`codeman:tile-grid`, ids only) made safe to apply: unknown,
+ * deleted, detached and duplicate ids are dropped, the list is capped at
+ * TILE_GRID_MAX, `focused` / `zoomed` must name a kept id, and track fractions
+ * must be 1 to 3 finite positive numbers. Anything that is not a v1 object
+ * (or its JSON) gives null.
+ *
+ * The stored `ids` are the grid's CELLS in reading order, `null` for an empty
+ * one (a hole can be any cell). The old packed list (no nulls) reads as cells
+ * with no hole. `ids` comes back packed (the tiles in reading order, what
+ * every list consumer wants) and `cells` keeps the holes: a dropped id (gone,
+ * detached, a duplicate, past the cap) becomes `null` there, never a shift.
+ *
+ * @param {unknown} raw - the parsed value, or the stored JSON string
+ * @param {{has(id: string): boolean}|Iterable<string>} liveSessions - ids that exist now
+ * @param {{has(id: string): boolean}} [detachedIds] - sessions popped out to their own window
+ * @returns {{v: 1, open: boolean, ids: string[], cells: (string|null)[], focused: string|null,
+ *   zoomed: string|null, colFr: number[]|null, rowFr: number[]|null}|null}
+ */
+function sanitizeTileGridState(raw, liveSessions, detachedIds) {
+  let value = raw;
+  if (typeof value === 'string') {
+    try { value = JSON.parse(value); } catch { return null; }
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.v !== 1) return null;
+  const live = liveSessions && typeof liveSessions.has === 'function' ? liveSessions : new Set(liveSessions || []);
+  const ids = [];
+  const cells = [];
+  for (const id of (Array.isArray(value.ids) ? value.ids : []).slice(0, TILE_LAYOUT_MAX)) {
+    const keep =
+      typeof id === 'string' && id && !ids.includes(id) && live.has(id) && !detachedIds?.has?.(id) &&
+      ids.length < TILE_GRID_MAX;
+    if (keep) ids.push(id);
+    // A malformed entry (not a string, not null) is a hole too.
+    cells.push(keep ? id : null);
+  }
+  const fractions = (fr) => {
+    if (!Array.isArray(fr) || fr.length < 1 || fr.length > 3) return null;
+    return fr.every((x) => typeof x === 'number' && Number.isFinite(x) && x > 0) ? fr.slice() : null;
+  };
+  return {
+    v: 1,
+    open: value.open === true && ids.length > 0,
+    ids,
+    cells,
+    focused: ids.includes(value.focused) ? value.focused : (ids[0] ?? null),
+    zoomed: ids.includes(value.zoomed) ? value.zoomed : null,
+    colFr: fractions(value.colFr),
+    rowFr: fractions(value.rowFr),
+  };
+}
+
+/**
+ * New track fractions after a divider drag (grid-template `fr` values): the two
+ * tracks either side of divider `index` trade `deltaPx` of size, each kept at
+ * least `minPx` (or half the pair, if the pair cannot give both the minimum).
+ * Every other track keeps its size. Computed from the fractions the drag
+ * STARTED with and the pointer's total travel, so a drag never drifts.
+ *
+ * @param {number[]} fr - the fractions when the drag started
+ * @param {number} index - the divider: between track `index` and `index + 1`
+ * @param {number} deltaPx - pointer travel since the drag started
+ * @param {number} totalPx - the size the tracks share (dividers and padding excluded)
+ * @param {number} minPx - the smallest a track may get
+ * @returns {number[]} new fractions, same length
+ */
+function dragTrackFractions(fr, index, deltaPx, totalPx, minPx) {
+  const out = fr.slice();
+  if (index < 0 || index + 1 >= fr.length || !(totalPx > 0)) return out;
+  const sum = fr.reduce((a, b) => a + b, 0);
+  if (!(sum > 0)) return out;
+  const a = (fr[index] / sum) * totalPx;
+  const b = (fr[index + 1] / sum) * totalPx;
+  const pair = a + b;
+  const lo = Math.min(minPx, pair / 2);
+  const hi = pair - lo;
+  const nextA = Math.min(Math.max(a + (Number(deltaPx) || 0), lo), hi);
+  out[index] = (nextA / totalPx) * sum;
+  out[index + 1] = ((pair - nextA) / totalPx) * sum;
+  return out;
+}
+
+/**
+ * The sessions the Tiles button can open (case c of tileGridOpenSet, and the
+ * ones a count fills a grid with), in tab order: live ones only, never a session popped out to
+ * its own window (that window owns its PTY size). A session with no PTY
+ * attached IS offered: its tile shows the Attach overlay.
+ *
+ * @param {Map<string, {name?: string}>} sessions
+ * @param {string[]} sessionOrder
+ * @param {{has(id: string): boolean}} [detachedIds]
+ * @returns {Array<{id: string, label: string}>}
+ */
+function buildTilePickerSessions(sessions, sessionOrder, detachedIds) {
+  const result = [];
+  for (const id of sessionOrder) {
+    if (detachedIds?.has?.(id)) continue;
+    const session = sessions.get(id);
+    if (!session) continue;
+    result.push({ id, label: session.name || 'Session' });
+  }
+  return result;
+}
+
+/**
+ * What the Tiles button and Ctrl+Shift+G open, at once and without asking
+ * (owner decision 8). In order:
+ *   a. the grid this tab last had (`stored`, already sanitized: live, not
+ *      detached, at most the cap), if any of its sessions survive;
+ *   b. else an open split's two sessions, Pane A focused;
+ *   c. else the open sessions in tab order (buildTilePickerSessions: no
+ *      detached ones), up to `limit`, the active session always among them and focused
+ *      (when it sits past the limit, the first `limit - 1` others come with it).
+ * Null when there is nothing to open.
+ *
+ * @param {{stored?: {ids: string[], focused: string|null, zoomed: string|null}|null,
+ *   split?: string[]|null, sessions: Map<string, object>, sessionOrder: string[],
+ *   detachedIds?: {has(id: string): boolean}, activeId?: string|null, limit: number}} p
+ * @returns {{source: 'stored'|'split'|'tabs', ids: string[], focusedId: string|null}|null}
+ */
+function tileGridOpenSet({ stored = null, split = null, sessions, sessionOrder, detachedIds, activeId = null, limit }) {
+  if (stored?.ids?.length) {
+    const focus = stored.zoomed || stored.focused;
+    return { source: 'stored', ids: stored.ids.slice(), focusedId: stored.ids.includes(focus) ? focus : stored.ids[0] };
+  }
+  const usable = (id) => typeof id === 'string' && sessions.has(id) && !detachedIds?.has?.(id);
+  const pair = (split || []).filter(usable);
+  if (split && pair.length) return { source: 'split', ids: [...new Set(pair)], focusedId: pair[0] };
+  const max = Math.max(1, Math.min(Math.floor(Number(limit) || 0), TILE_GRID_MAX));
+  const all = buildTilePickerSessions(sessions, sessionOrder, detachedIds).map((c) => c.id);
+  if (all.length === 0) return null;
+  let ids = all.slice(0, max);
+  if (all.includes(activeId) && !ids.includes(activeId)) {
+    ids = [...all.filter((id) => id !== activeId).slice(0, max - 1), activeId];
+  }
+  return { source: 'tabs', ids, focusedId: ids.includes(activeId) ? activeId : ids[0] };
+}
+
+/**
+ * The tile counts the Tiles button's right-click menu offers, and the count a
+ * click opens until one is picked (owner decision 10 in docs/tile-grid-plan.md).
+ */
+const TILE_GRID_COUNTS = [2, 4, 6];
+const TILE_GRID_COUNT_DEFAULT = 6;
+
+/** A remembered tile count made safe: one of TILE_GRID_COUNTS, else the default. */
+function sanitizeTileCount(raw) {
+  const n = Number(raw);
+  return TILE_GRID_COUNTS.includes(n) ? n : TILE_GRID_COUNT_DEFAULT;
+}
+
+/**
+ * `base` (what the grid would open, or what an open grid shows, in its order)
+ * trimmed or filled to `n` tiles: trimmed from the end, the session to focus
+ * (`keepId`) always kept (it takes the last place when it sat past `n`, as in
+ * tileGridOpenSet's case c); filled from `all` (the open sessions in tab order)
+ * with the ones not in it yet. Fewer sessions than `n` give fewer tiles.
+ *
+ * @param {string[]} base
+ * @param {string[]} all
+ * @param {number} n - at most TILE_GRID_MAX
+ * @param {string|null} [keepId]
+ * @returns {string[]}
+ */
+function tileGridSetForCount(base, all, n, keepId = null) {
+  const max = Math.max(1, Math.min(Math.floor(Number(n) || 0), TILE_GRID_MAX));
+  const ids = [];
+  for (const id of [...(base || []), ...(all || [])]) {
+    if (typeof id === 'string' && id && !ids.includes(id)) ids.push(id);
+  }
+  // Every `base` id comes before every filler, so a trim never drops a base id
+  // in favour of one.
+  let out = ids.slice(0, max);
+  if (keepId && ids.includes(keepId) && !out.includes(keepId)) out = [...out.slice(0, max - 1), keepId];
+  return out;
+}
+
+/**
+ * Which tile takes focus when `id` leaves the grid: the next one in grid
+ * order, else the previous one, else null.
+ *
+ * @param {string[]} ids - the grid's tiles, in reading order
+ * @param {string} id - the tile that is leaving
+ * @returns {string|null}
+ */
+function tileNeighbor(ids, id) {
+  const i = ids.indexOf(id);
+  if (i === -1) return ids[0] ?? null;
+  return ids[i + 1] ?? ids[i - 1] ?? null;
+}
+
+/**
+ * The tile a directional focus chord moves to, in a row-major grid of `cols`
+ * columns whose empty cells are `null` (a hole can be any cell) or simply
+ * missing at the end. Focus never lands on a hole. Left and right go along
+ * the row, past any hole, and never leave it. Up and down take the nearest
+ * row in that direction that has a tile: the tile in the same column, else
+ * the one in the nearest column (the lower column on a tie), so moving down
+ * onto a short or holed last row lands on its nearest tile. Null when there
+ * is no tile in that direction.
+ *
+ * @param {(string|null)[]} cells - the grid's cells in reading order (or its packed tiles)
+ * @param {string} focusedId - the tile the keyboard is in
+ * @param {'left'|'right'|'up'|'down'} direction
+ * @param {number} cols - the layout's column count
+ * @returns {string|null}
+ */
+function tileInDirection(cells, focusedId, direction, cols) {
+  const i = focusedId ? cells.indexOf(focusedId) : -1;
+  if (i === -1 || !(cols >= 1)) return null;
+  const rows = Math.ceil(cells.length / cols);
+  const row = Math.floor(i / cols);
+  const col = i % cols;
+  const at = (r, c) => cells[r * cols + c] || null;
+  if (direction === 'left' || direction === 'right') {
+    const step = direction === 'left' ? -1 : 1;
+    for (let c = col + step; c >= 0 && c < cols; c += step) {
+      if (at(row, c)) return at(row, c);
+    }
+    return null;
+  }
+  if (direction !== 'up' && direction !== 'down') return null;
+  const step = direction === 'up' ? -1 : 1;
+  for (let r = row + step; r >= 0 && r < rows; r += step) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (let c = 0; c < cols; c++) {
+      const id = at(r, c);
+      if (id && Math.abs(c - col) < bestDistance) {
+        best = id;
+        bestDistance = Math.abs(c - col);
+      }
+    }
+    if (best) return best;
+  }
+  return null;
+}
+
+/**
+ * The cell next to cell `index` in that direction (Move Tile: a tile moves
+ * into an empty neighbour cell, or swaps with a tiled one), or -1 at the
+ * edge. Adjacent only: a move never jumps over a cell.
+ *
+ * @param {number} index - the cell, in reading order
+ * @param {'left'|'right'|'up'|'down'} direction
+ * @param {number} cols - the layout's column count
+ * @param {number} cellCount - cols x rows
+ * @returns {number}
+ */
+function tileCellInDirection(index, direction, cols, cellCount) {
+  if (!(cols >= 1) || index < 0 || index >= cellCount) return -1;
+  const col = index % cols;
+  let j = -1;
+  if (direction === 'left') j = col > 0 ? index - 1 : -1;
+  else if (direction === 'right') j = col < cols - 1 ? index + 1 : -1;
+  else if (direction === 'up') j = index - cols;
+  else if (direction === 'down') j = index + cols;
+  return j >= 0 && j < cellCount ? j : -1;
+}
+
+/**
+ * The grid's cells after its shape changed (or to fill one for the first
+ * time): `cols` x `rows` cells, `null` for an empty one. The same shape keeps
+ * every cell as it is. A new shape keeps each tile at its row and column when
+ * every tile still fits there (2x2 growing to 3x2: the four tiles stay put),
+ * and otherwise packs the tiles in reading order from the first cell, holes
+ * collapsed (positions do not map between shapes). `oldCols` 0 (no layout
+ * yet) always packs.
+ *
+ * @param {(string|null)[]} cells - the current cells, laid out `oldCols` wide
+ * @param {number} oldCols - the column count they were laid out with
+ * @param {number} cols
+ * @param {number} rows
+ * @returns {(string|null)[]}
+ */
+function fitTileCells(cells, oldCols, cols, rows) {
+  const size = Math.max(0, cols * rows);
+  if (oldCols === cols && cells.length === size) return cells.slice();
+  const out = new Array(size).fill(null);
+  const placed = cells.map((id, k) => (id ? { id, row: Math.floor(k / oldCols), col: k % oldCols } : null));
+  const keep = oldCols >= 1 && placed.every((p) => !p || (p.row < rows && p.col < cols));
+  if (keep) {
+    for (const p of placed) if (p) out[p.row * cols + p.col] = p.id;
+    return out;
+  }
+  cells.filter(Boolean).slice(0, size).forEach((id, k) => {
+    out[k] = id;
+  });
+  return out;
+}
+
+/**
+ * How many columns a grid of `length` cells was laid out with: stored cells
+ * carry no shape of their own, and the layout table gives each cell count one
+ * shape (computeTileLayout: 1x1, 2x1, 3x1, 2x2, 3x2, 3x3). 0 for any other
+ * length (fitTileCells then packs).
+ *
+ * @param {number} length
+ * @returns {number}
+ */
+function tileCellCols(length) {
+  // Every cell count is some count's shape on a wide grid area (2x2, the
+  // narrow 3-tile shape, is also the 4-tile one).
+  for (let n = 1; n <= TILE_LAYOUT_MAX; n++) {
+    const { cols, rows } = computeTileLayout({ count: n });
+    if (cols * rows === length) return cols;
+  }
+  return 0;
+}
+
+/**
+ * The cells of a grid re-formed to another set of tiles (a count picked in the
+ * Tiles menu, or the Tiles button bringing back a remembered grid with more or
+ * fewer tiles): the tiles in `keep` stay in their cells and every other cell
+ * empties, then the cell model's shape rule (fitTileCells: each tile keeps its
+ * row and column when all fit, else they pack in reading order), then the
+ * tiles in `add` fill the empty cells in reading order, holes first.
+ *
+ * @param {(string|null)[]} cells - the cells now, laid out `oldCols` wide
+ * @param {number} oldCols
+ * @param {string[]} keep - tiles that stay
+ * @param {string[]} add - tiles that join, in the order they fill
+ * @param {number} cols - the new shape
+ * @param {number} rows
+ * @returns {(string|null)[]}
+ */
+function reformTileCells(cells, oldCols, keep, add, cols, rows) {
+  const kept = (cells || []).map((id) => (id && keep.includes(id) ? id : null));
+  const out = fitTileCells(kept, oldCols, cols, rows);
+  for (const id of add) {
+    if (!id || out.includes(id)) continue;
+    const k = out.indexOf(null);
+    // Not for a shape made for the count; a full grid takes no more.
+    if (k === -1) break;
+    out[k] = id;
+  }
+  return out;
+}
+
+/**
+ * The tile Ctrl+Tab / Alt+] (delta 1) or Alt+[ (delta -1) moves to while the
+ * grid is open: tiles cycle in reading order and wrap.
+ *
+ * @param {string[]} ids
+ * @param {string} focusedId
+ * @param {number} delta - +1 or -1
+ * @returns {string|null}
+ */
+function cycleTile(ids, focusedId, delta) {
+  if (ids.length === 0) return null;
+  const i = ids.indexOf(focusedId);
+  if (i === -1) return ids[0];
+  return ids[(i + delta + ids.length) % ids.length];
+}
+
 // ── Renderer liveness ──────────────────────────────────────────────────────
 //
 // iOS DISCARDS scheduled requestAnimationFrame callbacks when a PWA goes to
@@ -1869,7 +2673,59 @@ function sessionIdFromFragment(hash) {
   return id && id.trim() ? id.trim() : null;
 }
 
+/** Longest model name a session header shows (the server caps it as well). */
+const SESSION_MODEL_MAX_CHARS = 64;
+/** A CLI registry id (src/config/cli-registry/schema.ts); anything else is not a class name. */
+const CLI_ID_PATTERN = /^[a-z][a-z0-9-]{0,23}$/;
+
+/**
+ * What a session's header says about its harness: the CLI id (the
+ * `run-mode-dot <id>` logo class), the registry's label for it, the model the
+ * session runs when the server knows it (`SessionState.displayModel`), and the
+ * tooltip naming both.
+ *
+ * The id is data: the label comes from the injected CLI catalog and falls back
+ * to the id, so a CLI added through clis.json still gets a name. The model is
+ * untrusted text (read off a pane, or a CLI's own report): control characters
+ * are dropped and the length capped here too, and callers render it with
+ * textContent. The tooltip says where a model that is not the CLI's own report
+ * came from, so it never claims more than the server knows: one the session
+ * was launched with may have been switched since, one read from the CLI's
+ * config is what it is configured to run, and a custom endpoint's model is the
+ * endpoint's, whatever the CLI calls it.
+ *
+ * @param {object} session - a session from app.sessions
+ * @param {Array<{id: string, label?: string}>} [catalog] - window.__codemanCliCatalog
+ * @returns {{id: string, label: string, model: string, title: string}}
+ */
+function describeSessionHarness(session, catalog) {
+  const id = typeof session?.mode === 'string' && CLI_ID_PATTERN.test(session.mode) ? session.mode : '';
+  const entry = id && Array.isArray(catalog) ? catalog.find((cli) => cli?.id === id) : null;
+  const label = (typeof entry?.label === 'string' && entry.label.trim()) || id;
+  const raw = session?.displayModel?.model;
+  const model =
+    typeof raw === 'string'
+      ? raw
+          .replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+          .trim()
+          .slice(0, SESSION_MODEL_MAX_CHARS)
+      : '';
+  const source = session?.displayModel?.source;
+  const qualifier = !model
+    ? ''
+    : source === 'launch'
+      ? ' (set at launch)'
+      : source === 'custom-endpoint'
+        ? ' (custom endpoint)'
+        : source === 'config'
+          ? ' (from config)'
+          : '';
+  const title = [label, model].filter(Boolean).join(' \u00B7 ') + qualifier;
+  return { id, label, model, title };
+}
+
 if (typeof window !== 'undefined') {
+  window.CodemanSessionHarness = { describeSessionHarness, SESSION_MODEL_MAX_CHARS };
   window.CodemanHistoryFormat = { formatHistoryBytes, computeHistoryTruncationNotice, computeRewriteScrollLine };
   window.CodemanFilePaths = { absoluteFilePathPattern, previewsInFileViewer, FILE_PREVIEW_EXTENSIONS };
   window.CodemanTerminalLines = { terminalLogicalLine };
@@ -1879,6 +2735,32 @@ if (typeof window !== 'undefined') {
     buildSplitPickerSessions,
     SPLIT_PANE_MIN_WIDTH,
   };
+  window.CodemanTileGrid = {
+    computeTileLayout,
+    tileGridCapacity,
+    sanitizeTileGridState,
+    buildTilePickerSessions,
+    dragTrackFractions,
+    tileNeighbor,
+    tileInDirection,
+    tileCellInDirection,
+    fitTileCells,
+    cycleTile,
+    tileGridOpenSet,
+    sanitizeTileCount,
+    tileGridSetForCount,
+    tileCellCols,
+    reformTileCells,
+    TILE_GRID_COUNTS,
+    TILE_GRID_COUNT_DEFAULT,
+    TILE_GRID_MAX,
+    TILE_LAYOUT_MAX,
+    TILE_MIN_W,
+    TILE_MIN_H,
+    TILE_SCROLLBACK,
+    TILE_FONT_SIZE_DEFAULT,
+    TILE_GRID_SSE_FILTER,
+  };
   window.CodemanRenderLiveness = { shouldKickRenderer, RENDER_STALL_MS, RENDER_LIVENESS_POLL_MS };
   window.CodemanFetchDeadline = {
     terminalFetchDeadlineMs,