From 2099c52a2e8181f52af7541fa1826678d07b0cf0 Mon Sep 17 00:00:00 2001
From: Jean-Baptiste <jean-baptiste@konvex-it.fr>
Date: Fri, 11 Sep 2026 22:06:50 +0200
Subject: [PATCH] (session-state): one icon slot per sidebar row, resolved by
 the domain module

Step 3b of #246. Each session and subagent row carries one .session-icon
element written only by the projection file from renderSessionIcon(); the
status dot and the spinner slot are absorbed into it. The rung is resolved in
session-state.js and exposed as a session-icon--<rung> class, so the CSS keys
on that class alone: the row-class :not() chains are gone, and a source test
keeps them out. Row classes stay for tint and tests; the age text stays next
to the slot for local and remote rows alike.
---
 .ai/contexts/session-state.md                 | 158 ++++++++++++++++--
 eslint.config.js                              |   7 +-
 public/app.js                                 |   6 +-
 public/session-activity-dom.js                |  45 ++++-
 public/session-state.js                       |  21 +--
 public/sidebar.js                             |  23 ++-
 public/style.css                              |  51 +++---
 test/dom-grid-sidebar-prune-collision.test.js |   3 +
 test/dom-sidebar-icon-slot.test.js            | 141 ++++++++++++++++
 test/dom-sidebar-subagent-running.test.js     |   4 +-
 test/dom-subagent-transcript.test.js          |   3 +
 test/dom-subagent-ttl-tick.test.js            |   3 +
 test/running-indicators.test.js               |  12 +-
 test/session-activity.test.js                 |  23 +--
 test/session-icon-slot-css-boundary.test.js   |  59 +++++++
 test/session-state.test.js                    |  36 +++-
 test/sidebar-busy-agents-tint.test.js         |  31 ++--
 17 files changed, 533 insertions(+), 93 deletions(-)
 create mode 100644 test/dom-sidebar-icon-slot.test.js
 create mode 100644 test/session-icon-slot-css-boundary.test.js

diff --git a/.ai/contexts/session-state.md b/.ai/contexts/session-state.md
index 85b2a6af..2972401e 100644
--- a/.ai/contexts/session-state.md
+++ b/.ai/contexts/session-state.md
@@ -6,17 +6,19 @@ what actually shipped, not the whole plan.
 
 ## Migration status
 
-- **Steps 1-3: done.** `public/session-activity.js` split into a state part
+- **Steps 1-3b: done.** `public/session-activity.js` split into a state part
   (itself) and a DOM part (`public/session-activity-dom.js`); `public/session-state.js`
   introduced and wired behind `applyActivityClasses` for local-pty, and behind
   a persistent `remote-ssh` adapter (`public/remote-activity-ui.js`) for
-  remote sessions — see "The remote-ssh adapter" below.
-- **Steps 3b/4/5: pending.** The unified icon-slot markup (dot + age + spinner
-  in one element) is a separate PR (3b). There is no `local-transcript`
-  adapter (step 4). Subagent attribution is not routed through
-  `session-state.js` (`agentsBusy` exists in the model but nothing local-pty feeds
-  it yet — sidebar.js's `has-busy-agents` is still computed by
-  `parentHasActiveSubagent()`, independent of the domain module) (step 5).
+  remote sessions — see "The remote-ssh adapter" below. Step 3b (one
+  `.session-icon` slot per sidebar row, replacing `.session-status-dot` for
+  session/subagent rows) shipped separately — see "The icon slot (step 3b)"
+  below.
+- **Steps 4/5: pending.** There is no `local-transcript` adapter (step 4).
+  Subagent attribution is not routed through `session-state.js` (`agentsBusy`
+  exists in the model but nothing local-pty feeds it yet — sidebar.js's
+  `has-busy-agents` row class is still computed by `parentHasActiveSubagent()`,
+  independent of the domain module) (step 5).
 
 ### The remote-ssh adapter (step 3)
 
@@ -104,11 +106,141 @@ mutually exclusive — going busy or attention clears the other two (and
 `renderSessionIcon(snapshot)` resolves the priority order — attention >
 responseReady > busy > agentsBusy > waitingForInput > idle+age > stale >
 archived — defensively (it does not trust the caller kept exclusivity) and
-returns `{ classes, glyph, title }` for **one icon slot**. Only the four
-rungs that map to an existing CSS class (`needs-attention`, `response-ready`,
-`cli-busy`, `has-busy-agents`) carry a class today; the rest carry a glyph/title
-only — the sidebar HTML/CSS shape (replacing the dot/pip with the icon slot)
-is a later step, not part of this migration.
+returns `{ classes, slotClasses, glyph, title }` for **one icon slot**. Only
+the four rungs that map to an existing row-level CSS class (`needs-attention`,
+`response-ready`, `cli-busy`, `has-busy-agents`, in `classes`) carry one; every
+rung — including those four — also carries exactly one `slotClasses` entry
+(`session-icon--attention`, `session-icon--response-ready`, `session-icon--busy`,
+`session-icon--agents-busy`, `session-icon--waiting`, `session-icon--idle`,
+`session-icon--stale`, `session-icon--archived`). See "The icon slot (step 3b)"
+below for how `classes` and `slotClasses` are used differently.
+
+## The icon slot (step 3b)
+
+One `.session-icon` element per session/subagent row (`public/sidebar.js`'s
+`buildSessionItem`/`buildSubagentItem`), replacing `.session-status-dot` for
+those two rows — `.remote-host-dot` (the project header's per-host
+reachability indicator, a different row entirely) is untouched and still
+composes `class="session-status-dot remote-host-dot ..."`; both base CSS
+rules (`.session-status-dot`, `.session-icon`) exist side by side in
+`style.css` for exactly this reason. `.session-icon`'s box (6px, same as the
+old dot) is fixed regardless of rung, so the row never shifts as the glyph
+underneath it changes.
+
+`session-activity-dom.js` is the only file that writes the slot:
+
+- `writeIconSlot(el, icon)` clears any previous `session-icon--*` class
+  (robust to a rung's `slotClasses` shrinking or changing shape — a plain
+  diff of the old vs. new class would also work but this needs no diffing),
+  applies `icon.slotClasses`, and sets `el.title`/`el.dataset.glyph` from
+  `icon.title`/`icon.glyph`. The `session-icon--*` namespace is deliberately
+  distinct from the row-level `classes` (`cli-busy` etc.) both for the eslint
+  boundary (see "Enforcement" below) and so a reader never confuses "this
+  paints the row" with "this paints the slot".
+- `session-activity-dom.js` also references `parentHasActiveSubagent`
+  (`sidebar.js`) and `sessionMap` (`app.js`) now, alongside the pre-existing
+  `sessionBusyState`/`responseReadySessions`/`attentionSessions`
+  (`session-activity.js`). Safe despite loading before all three in
+  index.html's script order — every reference is inside a function body,
+  resolved at call time after the whole page has loaded, same pattern
+  `sidebar.js`'s own header comment documents for its dependencies.
+- `snapshotForLocal(sessionId, session)` builds a local-pty snapshot the same
+  way `computeBusyReadyClasses` does for busy/responseReady, extended with
+  `attention` (`attentionSessions`), `agentsBusy` (`parentHasActiveSubagent()`),
+  and `liveness`/`descriptorStatus` from `session.status`/`statusUpdatedAt`
+  when present — cli-session-state.js only keeps an entry while the pid is
+  alive (`.ai/contexts/cli-session-state.md`), so `session.status` being
+  present at all is itself the local liveness signal; `session` is optional
+  and falls back to a `sessionMap` lookup for call sites that only have a
+  sessionId.
+- `paintSessionIcon(el, sessionId, session)` composes the two:
+  `writeIconSlot(el, renderSessionIcon(snapshotForLocal(sessionId, session)))`.
+  Called from `sidebar.js` at row construction (both `buildSessionItem` and
+  `buildSubagentItem`), from `applyActivityClassesToElement` on every local
+  busy/ready/attention/subagent transition, and from
+  `reflectSubagentRunningState` on the **parent** row (agentsBusy is part of
+  the priority ladder the slot resolves, so a subagent spawn/complete must
+  repaint the parent's slot, not just its `has-busy-agents` row class).
+- `applyStateClasses(sessionId, snapshot)` (the remote-ssh path, called from
+  `remote-activity-ui.js`'s `projectRemoteState`) now also calls
+  `writeIconSlot` with the same `renderSessionIcon(snapshot)` result it uses
+  for the row's `cli-busy`/`response-ready` classes — this is what makes a
+  local busy row and a remote busy row render the identical slot markup
+  (classes, title, glyph), pinned in `test/dom-sidebar-icon-slot.test.js`.
+
+The `.running` class on `.session-icon` is **not** part of this model — it is
+the old dot's orthogonal "a PTY/subagent process is attached" boolean
+(`activePtyIds`/`isSubagentActive`), toggled exactly as before by
+`app.js`/`sidebar.js`, independent of `renderSessionIcon`'s priority ladder.
+
+### The slot's CSS keys on its own rung class alone (coordinator follow-up, 2026-09-11)
+
+First pass of this step left `style.css` still resolving the slot's visual
+with row-class `:not()` chains carried over verbatim from the old
+`.session-status-dot` rules (`.session-item.cli-busy:not(.needs-attention)
+.session-icon`, `.session-item.has-busy-agents:not(.cli-busy):not(...):not(...)
+.session-icon`) — exactly the row-class arbitration this migration exists to
+retire, just renamed. `renderSessionIcon()` already picks the single active
+rung in JS before `writeIconSlot()` ever touches the DOM, so the CSS never
+needs to re-derive it: every rung's visual now keys on its own
+`.session-icon--<rung>` class alone, no ancestor `:not()` chain —
+
+```css
+.session-icon--busy { background: transparent !important; animation: none !important; ... }
+.session-icon--busy::before { content: "\280B"; animation: braille-spin ...; color: #4fc3f7; ... }
+.session-icon--agents-busy { background: transparent !important; ... }
+.session-icon--agents-busy::before { content: "\283F"; color: #8088ff; ... }
+.session-icon--response-ready { background: #4fc3f7 !important; ... }
+.session-icon--attention { background: #f0a050 !important; ... }
+```
+
+`background` (the only property `.session-icon.running`'s plain green also
+sets) carries `!important` on every rung — busy/attention/response-ready/
+agentsBusy rows are very often also `.running` (a busy session almost always
+has a live PTY), and unlike the old code the rung is now a single class with
+no extra row-ancestor classes to lean on for specificity.
+
+**`has-busy-agents` is the one exception, and it stays row-level on purpose**
+(point 1 of the original brief: "`.has-busy-agents` stays a row-level class
+— a tint — but its glyph rung lives in the slot when nothing higher is
+active"). A busy session with live subagents needs the busy spinner tinted
+violet instead of its default blue; since `agentsBusy` never wins the JS
+priority race while `busy` is active, there is no `session-icon--agents-busy`
+class to key on in that case — so the tint is a **plain compound selector**,
+row tint class + slot rung class, not a priority tie-break:
+
+```css
+.session-item.has-busy-agents .session-icon--busy::before { color: #8088ff; }
+```
+
+This is the only place a row-level class still appears next to `.session-icon`
+in the slot's own visual rules, and `test/session-icon-slot-css-boundary.test.js`
+allows it explicitly (it only forbids `:not(`, not row classes generally) —
+the boundary is "no priority re-arbitration in CSS", not "no row class may
+ever touch the slot's selector".
+
+`test/session-icon-slot-css-boundary.test.js` source-greps `style.css`
+(comments stripped first — a couple of them, including the one you're
+reading in source, mention `:not()` in prose and would otherwise
+false-positive a naive scan) for any selector mentioning `.session-icon` and
+asserts none contains `:not(`; `.session-status-dot`/`.remote-host-dot` (the
+project header's per-host reachability dot, a different row, untouched by
+this migration) are excluded. Mutation-proven: reintroducing
+`.session-item.cli-busy:not(.needs-attention) .session-icon--busy { ... }`
+turns it red.
+
+`test/dom-sidebar-icon-slot.test.js` pins the slot markup itself (mutation-
+proven: swapping the `busy`/`agentsBusy` entries in `ICON_BY_RUNG` turns three
+of its DOM tests red, plus the pure-unit tests in `test/session-state.test.js`).
+The five tests named in issue #246's step 3b brief
+(`dom-sidebar-local-status`, `dom-sidebar-remote-session`,
+`dom-sidebar-remote-freshness`, `sidebar-busy-agents-tint`,
+`dom-sidebar-remote-activity-pip`) needed no markup changes beyond
+`sidebar-busy-agents-tint.test.js`'s CSS-selector regexes (retargeted first
+from `.session-status-dot` to `.session-icon`, then from the row-class
+`:not()` chains to the flat `session-icon--<rung>` selectors above) — none of
+the others assert on the dot/slot element itself, only on row classes and
+`.session-status`.
 
 ## Design notes (deviations from the issue's literal text)
 
diff --git a/eslint.config.js b/eslint.config.js
index 3b37eb45..6b5580c4 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -154,15 +154,20 @@ const rendererCrossFileGlobals = {
   createSessionState: 'readonly',
   renderSessionIcon: 'readonly',
   // public/session-activity-dom.js — the only file allowed to write
-  // .cli-busy/.needs-attention/.response-ready/.has-busy-agents.
+  // .cli-busy/.needs-attention/.response-ready/.has-busy-agents, and the only
+  // file allowed to write the .session-icon slot (issue #246, step 3b).
   applyActivityClassesToElement: 'readonly',
   applyStateClasses: 'readonly',
   setNeedsAttention: 'readonly',
   setResponseReady: 'readonly',
   setCliBusy: 'readonly',
   setHasBusyAgents: 'readonly',
+  paintSessionIcon: 'readonly',
   // public/remote-activity-ui.js (remote-ssh adapter, see .ai/contexts/session-state.md)
   setRemoteAttached: 'readonly',
+  // public/sidebar.js, consumed by session-activity-dom.js's snapshotForLocal
+  // (see .ai/contexts/session-state.md, "The icon slot (step 3b)")
+  parentHasActiveSubagent: 'readonly',
 
   // Third-party renderer libs loaded as <script>
   morphdom: 'readonly',
diff --git a/public/app.js b/public/app.js
index 674d9f59..0757a036 100644
--- a/public/app.js
+++ b/public/app.js
@@ -822,9 +822,9 @@ function updateRunningIndicators() {
         clearActiveSubagentsFor(id);
       }
       if (item.dataset.remoteAlias) setRemoteAttached(id, running);
-      const dot = item.querySelector('.session-status-dot');
-      if (dot) dot.classList.toggle('running', running);
-      if (window.ATRACE) window.atrace('class.toggle', id, { el: item.id || null, cls: 'has-running-pty', on: running, dot: !!dot, fn: 'updateRunningIndicators' });
+      const icon = item.querySelector('.session-icon');
+      if (icon) icon.classList.toggle('running', running);
+      if (window.ATRACE) window.atrace('class.toggle', id, { el: item.id || null, cls: 'has-running-pty', on: running, icon: !!icon, fn: 'updateRunningIndicators' });
     });
     // Update slug group running dots
     document.querySelectorAll('.slug-group').forEach(group => {
diff --git a/public/session-activity-dom.js b/public/session-activity-dom.js
index 098a3145..262e42f5 100644
--- a/public/session-activity-dom.js
+++ b/public/session-activity-dom.js
@@ -38,6 +38,7 @@ function applyActivityClassesToElement(item, sessionId) {
   const busy = classes.includes('cli-busy');
   setResponseReady(item, ready);
   setCliBusy(item, busy);
+  paintSessionIcon(item.querySelector('.session-icon'), sessionId);
   if (window.ATRACE) window.atrace('class.apply', sessionId, { el: item.id || null, 'response-ready': ready, 'cli-busy': busy, fn: 'applyActivityClasses' });
 }
 
@@ -49,10 +50,48 @@ function applyActivityClasses(sessionId) {
 function applyStateClasses(sessionId, snapshot) {
   const item = sessionItemEl(sessionId);
   if (!item) return;
-  const classes = renderSessionIcon(snapshot).classes;
-  const ready = classes.includes('response-ready');
-  const busy = classes.includes('cli-busy');
+  const icon = renderSessionIcon(snapshot);
+  const ready = icon.classes.includes('response-ready');
+  const busy = icon.classes.includes('cli-busy');
   setResponseReady(item, ready);
   setCliBusy(item, busy);
+  writeIconSlot(item.querySelector('.session-icon'), icon);
   if (window.ATRACE) window.atrace('class.apply', sessionId, { el: item.id || null, 'response-ready': ready, 'cli-busy': busy, fn: 'applyStateClasses', kind: snapshot && snapshot.kind });
 }
+
+// One icon slot per row, written here and nowhere else — see .ai/contexts/session-state.md
+function writeIconSlot(el, icon) {
+  if (!el || !icon) return;
+  for (const cls of Array.from(el.classList)) {
+    if (cls.indexOf('session-icon--') === 0) el.classList.remove(cls);
+  }
+  for (const cls of icon.slotClasses) el.classList.add(cls);
+  el.title = icon.title || '';
+  el.dataset.glyph = icon.glyph || '';
+}
+
+// local-pty snapshot for the icon slot (full priority ladder, unlike computeBusyReadyClasses) — see .ai/contexts/session-state.md
+function snapshotForLocal(sessionId, session) {
+  const state = createSessionState('local-pty');
+  const busy = sessionBusyState.get(sessionId) === true;
+  const ready = !busy && responseReadySessions.has(sessionId);
+  if (busy) state.apply({ type: 'busy', active: true });
+  else if (ready) state.apply({ type: 'busy', active: false, armReady: true });
+  if (attentionSessions.has(sessionId)) state.apply({ type: 'attention', active: true });
+  if (typeof parentHasActiveSubagent === 'function' && parentHasActiveSubagent(sessionId)) {
+    state.apply({ type: 'subagentSpawned' });
+  }
+  const sess = session || (typeof sessionMap !== 'undefined' && sessionMap.get(sessionId));
+  if (sess && sess.status !== undefined) {
+    // session.status present is itself the liveness signal — see .ai/contexts/cli-session-state.md
+    state.apply({ type: 'liveness', value: 'alive' });
+    state.apply({ type: 'descriptorStatus', status: sess.status, at: sess.statusUpdatedAt });
+  }
+  return state.snapshot();
+}
+
+// Paints a local-pty row's icon slot — see .ai/contexts/session-state.md
+function paintSessionIcon(el, sessionId, session) {
+  if (!el) return;
+  writeIconSlot(el, renderSessionIcon(snapshotForLocal(sessionId, session)));
+}
diff --git a/public/session-state.js b/public/session-state.js
index bcce1ee8..deb30814 100644
--- a/public/session-state.js
+++ b/public/session-state.js
@@ -3,15 +3,16 @@
 
 const PRIORITY = ['attention', 'responseReady', 'busy', 'agentsBusy', 'waitingForInput', 'idle', 'stale', 'archived'];
 
+// slotClasses use their own session-icon--* namespace, distinct from classes — see .ai/contexts/session-state.md
 const ICON_BY_RUNG = {
-  attention: { classes: ['needs-attention'], glyph: '!', title: 'Needs your attention' },
-  responseReady: { classes: ['response-ready'], glyph: '●', title: 'Response ready' },
-  busy: { classes: ['cli-busy'], glyph: '⠋', title: 'Working' },
-  agentsBusy: { classes: ['has-busy-agents'], glyph: '◆', title: 'Subagents running' },
-  waitingForInput: { classes: [], glyph: '○', title: 'Waiting for input' },
-  idle: { classes: [], glyph: '', title: 'Idle' },
-  stale: { classes: [], glyph: '', title: 'Stale' },
-  archived: { classes: [], glyph: '', title: 'Archived' },
+  attention: { classes: ['needs-attention'], slotClasses: ['session-icon--attention'], glyph: '!', title: 'Needs your attention' },
+  responseReady: { classes: ['response-ready'], slotClasses: ['session-icon--response-ready'], glyph: '●', title: 'Response ready' },
+  busy: { classes: ['cli-busy'], slotClasses: ['session-icon--busy'], glyph: '⠋', title: 'Working' },
+  agentsBusy: { classes: ['has-busy-agents'], slotClasses: ['session-icon--agents-busy'], glyph: '◆', title: 'Subagents running' },
+  waitingForInput: { classes: [], slotClasses: ['session-icon--waiting'], glyph: '○', title: 'Waiting for input' },
+  idle: { classes: [], slotClasses: ['session-icon--idle'], glyph: '', title: 'Idle' },
+  stale: { classes: [], slotClasses: ['session-icon--stale'], glyph: '', title: 'Stale' },
+  archived: { classes: [], slotClasses: ['session-icon--archived'], glyph: '', title: 'Archived' },
 };
 
 function createSessionState(kind) {
@@ -134,11 +135,11 @@ function renderSessionIcon(snapshot) {
   for (const rung of PRIORITY) {
     if (rungActive(s, rung)) {
       const icon = ICON_BY_RUNG[rung];
-      return { classes: icon.classes.slice(), glyph: icon.glyph, title: icon.title };
+      return { classes: icon.classes.slice(), slotClasses: icon.slotClasses.slice(), glyph: icon.glyph, title: icon.title };
     }
   }
   const idle = ICON_BY_RUNG.idle;
-  return { classes: idle.classes.slice(), glyph: idle.glyph, title: idle.title };
+  return { classes: idle.classes.slice(), slotClasses: idle.slotClasses.slice(), glyph: idle.glyph, title: idle.title };
 }
 
 function rungActive(s, rung) {
diff --git a/public/sidebar.js b/public/sidebar.js
index 140bd30c..7cc98b33 100644
--- a/public/sidebar.js
+++ b/public/sidebar.js
@@ -224,8 +224,8 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
   const el = document.getElementById(subagentDomId(parentSessionId, agentId));
   if (el) {
     el.classList.toggle('running', running);
-    const dot = el.querySelector('.session-status-dot');
-    if (dot) dot.classList.toggle('running', running);
+    const icon = el.querySelector('.session-icon');
+    if (icon) icon.classList.toggle('running', running);
   }
   const caret = document.getElementById(caretIdFor(parentSessionId));
   if (caret) caret.classList.toggle('has-running-child', parentHasActiveSubagent(parentSessionId));
@@ -236,6 +236,8 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
   // precedence over it.
   const parentEl = document.getElementById('si-' + parentSessionId);
   setHasBusyAgents(parentEl, parentHasActiveSubagent(parentSessionId));
+  // Re-paint the parent's icon slot too — see .ai/contexts/session-state.md
+  if (parentEl) paintSessionIcon(parentEl.querySelector('.session-icon'), parentSessionId);
   if (window.ATRACE) window.atrace('class.subagent', parentSessionId, { agentId, running, childEl: el ? el.id : null, caretEl: caret ? caret.id : null, parentEl: parentEl ? parentEl.id : null, 'has-busy-agents': parentHasActiveSubagent(parentSessionId), fn: 'reflectSubagentRunningState' });
 }
 
@@ -304,8 +306,10 @@ function buildSubagentItem(session) {
   typePill.style.background = bg;
   typePill.style.borderColor = border;
 
-  const dot = document.createElement('span');
-  dot.className = 'session-status-dot' + (isRunning ? ' running' : '');
+  // One icon slot per row, painted by session-activity-dom.js — see .ai/contexts/session-state.md
+  const icon = document.createElement('span');
+  icon.className = 'session-icon' + (isRunning ? ' running' : '');
+  paintSessionIcon(icon, session.sessionId, session);
 
   const info = document.createElement('div');
   info.className = 'session-info';
@@ -322,7 +326,7 @@ function buildSubagentItem(session) {
   info.appendChild(metaEl);
 
   row.appendChild(typePill);
-  row.appendChild(dot);
+  row.appendChild(icon);
   row.appendChild(info);
   item.appendChild(row);
 
@@ -1334,9 +1338,10 @@ function buildSessionItem(session) {
     ? '<svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path d="M9.828.722a.5.5 0 0 1 .354.146l4.95 4.95a.5.5 0 0 1-.707.707c-.28-.28-.576-.49-.888-.656L10.073 9.333l-.07 3.181a.5.5 0 0 1-.853.354l-3.535-3.536-4.243 4.243a.5.5 0 1 1-.707-.707l4.243-4.243L1.372 5.11a.5.5 0 0 1 .354-.854l3.18-.07L8.37 .722A3.37 3.37 0 0 1 9.12.074a.5.5 0 0 1 .708.002l-.707.707z"/></svg>'
     : '<svg width="12" height="12" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.2"><path d="M9.828.722a.5.5 0 0 1 .354.146l4.95 4.95a.5.5 0 0 1-.707.707c-.28-.28-.576-.49-.888-.656L10.073 9.333l-.07 3.181a.5.5 0 0 1-.853.354l-3.535-3.536-4.243 4.243a.5.5 0 1 1-.707-.707l4.243-4.243L1.372 5.11a.5.5 0 0 1 .354-.854l3.18-.07L8.37 .722A3.37 3.37 0 0 1 9.12.074a.5.5 0 0 1 .708.002l-.707.707z"/></svg>';
 
-  // Running status dot
-  const dot = document.createElement('span');
-  dot.className = 'session-status-dot' + (activePtyIds.has(session.sessionId) ? ' running' : '');
+  // One icon slot per row, painted by session-activity-dom.js — see .ai/contexts/session-state.md
+  const icon = document.createElement('span');
+  icon.className = 'session-icon' + (activePtyIds.has(session.sessionId) ? ' running' : '');
+  paintSessionIcon(icon, session.sessionId, session);
 
   // Info block
   const info = document.createElement('div');
@@ -1432,7 +1437,7 @@ function buildSessionItem(session) {
   }
 
   row.appendChild(pin);
-  row.appendChild(dot);
+  row.appendChild(icon);
   row.appendChild(info);
   row.appendChild(actions);
   item.appendChild(row);
diff --git a/public/style.css b/public/style.css
index 954c9bbb..2c451307 100644
--- a/public/style.css
+++ b/public/style.css
@@ -955,7 +955,7 @@ body { display: flex; flex-direction: column; }
   color: #f5be3c;
 }
 
-/* ---- Running dot ---- */
+/* ---- Running dot ---- kept for .remote-host-dot — see .ai/contexts/session-state.md */
 .session-status-dot {
   width: 6px;
   height: 6px;
@@ -969,18 +969,32 @@ body { display: flex; flex-direction: column; }
   background: #3ecf5a;
 }
 
+/* ---- Icon slot ---- see .ai/contexts/session-state.md */
+.session-icon {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  margin-top: 7px;
+  background: rgba(255,255,255,0.18);
+}
+
+.session-icon.running {
+  background: #3ecf5a;
+}
+
+/* ---- Icon slot rungs ---- keyed on session-icon--<rung> alone, no :not() chains — see .ai/contexts/session-state.md */
+
 /* ---- CLI busy spinner (braille spinner detected) ---- */
-/* needs-attention takes precedence — when both are set, the attention indicator shows */
 /* Braille spinner via content keyframes — see docs/decisions/0002 */
-.session-item.cli-busy:not(.needs-attention) .session-status-dot,
-.session-item.cli-busy:not(.needs-attention) .session-status-dot.running {
+.session-icon--busy {
   background: transparent !important;
   animation: none !important;
   box-shadow: none !important;
   position: relative;
 }
 
-.session-item.cli-busy:not(.needs-attention) .session-status-dot::before {
+.session-icon--busy::before {
   content: "\280B";
   animation: braille-spin 0.8s steps(1) infinite;
   color: #4fc3f7;
@@ -1015,21 +1029,18 @@ body { display: flex; flex-direction: column; }
 
 /* ---- Subagents running under this session (has-busy-agents) ---- */
 /* Parent is at the prompt while spawned subagents still work in the
-   background. The session's own states win: needs-attention,
-   response-ready and the cli-busy braille spinner all take precedence,
-   so this only shows on an otherwise-idle parent item.
+   background — see .ai/contexts/session-state.md.
    Static full braille cell in violet — deliberately no animation
    (docs/decisions/0002: new indicators default to static), and both hue
    and stillness distinguish it from the light-blue animated cli-busy
    spinner. */
-.session-item.has-busy-agents:not(.cli-busy):not(.needs-attention):not(.response-ready) .session-status-dot,
-.session-item.has-busy-agents:not(.cli-busy):not(.needs-attention):not(.response-ready) .session-status-dot.running {
+.session-icon--agents-busy {
   background: transparent !important;
   box-shadow: none !important;
   position: relative;
 }
 
-.session-item.has-busy-agents:not(.cli-busy):not(.needs-attention):not(.response-ready) .session-status-dot::before {
+.session-icon--agents-busy::before {
   content: "\283F"; /* ⠿ — all dots lit: agents at work */
   color: #8088ff;
   font-size: 11px;
@@ -1040,8 +1051,8 @@ body { display: flex; flex-direction: column; }
 }
 
 /* Busy session WITH live subagents: the same spinner, same cadence, violet
-   hue. See docs/subagents.md "Live status". */
-.session-item.cli-busy.has-busy-agents:not(.needs-attention) .session-status-dot::before {
+   hue — see .ai/contexts/session-state.md. See docs/subagents.md "Live status". */
+.session-item.has-busy-agents .session-icon--busy::before {
   color: #8088ff;
 }
 
@@ -1216,8 +1227,9 @@ body { display: flex; flex-direction: column; }
 }
 
 /* ---- Response ready indicator (Claude finished, unread output) ---- */
-.session-item.response-ready .session-status-dot {
-  background: #4fc3f7;
+/* background is !important — see .ai/contexts/session-state.md */
+.session-icon--response-ready {
+  background: #4fc3f7 !important;
   box-shadow: 0 0 8px rgba(79,195,247,0.7);
   animation: none;
 }
@@ -1236,10 +1248,9 @@ body { display: flex; flex-direction: column; }
 }
 
 /* ---- Needs attention indicator (blinking LED + halo) ---- */
-/* Replaces the ripple — see docs/decisions/0002 */
-.session-item.needs-attention .session-status-dot,
-.session-item.needs-attention .session-status-dot.running {
-  background: #f0a050;
+/* Replaces the ripple — see docs/decisions/0002. background is !important — see .ai/contexts/session-state.md */
+.session-icon--attention {
+  background: #f0a050 !important;
   box-shadow: 0 0 0 3px rgba(240,160,80,0.25);
   animation: led-blink 1s steps(1) infinite;
   position: relative;
@@ -4225,7 +4236,7 @@ body { display: flex; flex-direction: column; }
 }
 
 /* Terminal sessions: green status dot */
-.session-item.is-terminal .session-status-dot.running {
+.session-item.is-terminal .session-icon.running {
   background: #3ecf5a;
   box-shadow: 0 0 6px rgba(62,207,90,0.5);
 }
diff --git a/test/dom-grid-sidebar-prune-collision.test.js b/test/dom-grid-sidebar-prune-collision.test.js
index 065a8264..2c15599d 100644
--- a/test/dom-grid-sidebar-prune-collision.test.js
+++ b/test/dom-grid-sidebar-prune-collision.test.js
@@ -75,6 +75,9 @@ function setupCombinedDom() {
     setResponseReady: (el, on) => { if (el) el.classList.toggle('response-ready', !!on); },
     setCliBusy: (el, on) => { if (el) el.classList.toggle('cli-busy', !!on); },
     setHasBusyAgents: (el, on) => { if (el) el.classList.toggle('has-busy-agents', !!on); },
+    // issue #246 step 3b — sidebar.js calls this to paint the .session-icon
+    // slot; a no-op here is fine, this harness doesn't assert on it.
+    paintSessionIcon: () => {},
     pollActiveSessions: () => {},
     showNewSessionPopover: () => {},
     openSettingsViewer: () => {},
diff --git a/test/dom-sidebar-icon-slot.test.js b/test/dom-sidebar-icon-slot.test.js
new file mode 100644
index 00000000..e890d483
--- /dev/null
+++ b/test/dom-sidebar-icon-slot.test.js
@@ -0,0 +1,141 @@
+// Issue #246, step 3b — one icon slot per sidebar row, driven by
+// renderSessionIcon(snapshot) (public/session-state.js) and painted only by
+// public/session-activity-dom.js. See .ai/contexts/session-state.md.
+//
+// The pinned tests in dom-sidebar-local-status.test.js,
+// dom-sidebar-remote-session.test.js, dom-sidebar-remote-freshness.test.js,
+// sidebar-busy-agents-tint.test.js and dom-sidebar-remote-activity-pip.test.js
+// cover the row-level classes and the .session-status age line, unchanged by
+// this migration. This file pins the new .session-icon slot markup itself.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { setupSidebarDom, makeSampleProject } = require('./dom-setup');
+
+function remoteProject(session) {
+  return makeSampleProject({
+    projectPath: '/srv/supervision',
+    folder: 'planificator::-srv-supervision',
+    remoteAlias: 'planificator',
+    sessions: [session],
+  });
+}
+
+function slotClassesOf(el) {
+  return [...el.classList].filter((c) => c.indexOf('session-icon--') === 0);
+}
+
+// Mutation-provable: renderSessionIcon's ICON_BY_RUNG table maps 'busy' to
+// { slotClasses: ['session-icon--busy'], glyph: '⠋', title: 'Working' }.
+// Swapping the busy/agentsBusy (or any two) entries in that table changes
+// what a busy row's slot actually renders — this test goes red on that swap,
+// not just the pure-unit test in test/session-state.test.js.
+test('a busy local row carries the busy icon-slot markup (mutation-provable against renderSessionIcon\'s table)', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sessionBusyState.set('local-busy', true);
+    ctx.sidebar.renderProjects([makeSampleProject({
+      sessions: [{
+        sessionId: 'local-busy', summary: 'busy local', modified: '2026-09-06T10:00:00.000Z',
+        starred: false, archived: 0, messageCount: 1,
+      }],
+    })], true);
+
+    const slot = ctx.document.querySelector('#si-local-busy .session-icon');
+    assert.ok(slot, 'the row must carry a .session-icon slot');
+    assert.deepEqual(slotClassesOf(slot), ['session-icon--busy']);
+    assert.equal(slot.title, 'Working');
+    assert.equal(slot.dataset.glyph, '⠋');
+  } finally { ctx.destroy(); }
+});
+
+test('a local busy row and a remote busy row produce the same icon-slot markup', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sessionBusyState.set('local-busy-2', true);
+    const localProj = makeSampleProject({
+      sessions: [{
+        sessionId: 'local-busy-2', summary: 'busy local', modified: '2026-09-06T10:00:00.000Z',
+        starred: false, archived: 0, messageCount: 1,
+      }],
+    });
+    const remoteProj = remoteProject({
+      sessionId: 'remote-busy-2', summary: 'busy remote', modified: '2026-09-06T10:00:00.000Z',
+      starred: false, archived: 0, messageCount: 1,
+    });
+
+    ctx.sidebar.renderProjects([localProj, remoteProj], true);
+    // Real watch-channel dispatcher (remote-activity-ui.js) — same path
+    // main.js's 'remote-activity' IPC drives in production.
+    ctx.window.onRemoteActivityEvent({ sessionId: 'remote-busy-2' });
+
+    const localSlot = ctx.document.querySelector('#si-local-busy-2 .session-icon');
+    const remoteSlot = ctx.document.querySelector('#si-remote-busy-2 .session-icon');
+    assert.ok(localSlot && remoteSlot, 'both rows must carry an icon slot');
+    assert.deepEqual(slotClassesOf(localSlot), slotClassesOf(remoteSlot));
+    assert.equal(localSlot.title, remoteSlot.title);
+    assert.equal(localSlot.dataset.glyph, remoteSlot.dataset.glyph);
+    assert.deepEqual(slotClassesOf(remoteSlot), ['session-icon--busy'], 'precondition: the remote row is actually busy');
+  } finally { ctx.destroy(); }
+});
+
+test('a remote row past the decay window shows the age with no response-ready glyph', () => {
+  const ctx = setupSidebarDom();
+  try {
+    const now = Date.parse('2026-09-09T12:00:00Z');
+    const realNow = ctx.window.Date.now;
+    ctx.window.Date.now = () => now;
+    try {
+      const session = {
+        sessionId: 'remote-decayed', summary: 'quiet now', modified: '2026-09-08T10:00:00.000Z',
+        starred: false, archived: 0, messageCount: 1,
+        remoteAlias: 'planificator', status: 'idle', statusUpdatedAt: now - 5000,
+      };
+      ctx.sidebar.renderProjects([remoteProject(session)], true);
+
+      // Drive the adapter's own busy -> silence-decay transition directly
+      // (same effect as its 20s timer, without arming a real one) — see
+      // .ai/contexts/session-state.md ("a remote row must never reach
+      // .response-ready, it has no PTY to confirm a turn actually ended").
+      ctx.window.markRemoteBusy('remote-decayed', 'remote-watch', now - 25000);
+      ctx.window.decayRemoteBusy('remote-decayed');
+
+      const slot = ctx.document.querySelector('#si-remote-decayed .session-icon');
+      assert.ok(slot);
+      assert.ok(!slot.classList.contains('session-icon--response-ready'),
+        'a silence-based decay must never claim response-ready');
+      assert.equal(slot.title, 'Waiting for input');
+
+      const statusEl = ctx.document.querySelector('#si-remote-decayed .session-status');
+      assert.ok(statusEl, 'the age must still show via .session-status');
+      assert.match(statusEl.textContent, /idle.*5s ago/);
+    } finally {
+      ctx.window.Date.now = realNow;
+    }
+  } finally { ctx.destroy(); }
+});
+
+test('a subagent row also gets an icon slot, painted the same way as a session row', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sessionBusyState.set('sub:s-top-1:agent-1', true);
+    ctx.sidebar.renderProjects([makeSampleProject({
+      sessions: [
+        {
+          sessionId: 's-top-1', name: 'main session', summary: 'top level 1',
+          modified: '2026-05-22T10:00:00.000Z', starred: false, archived: 0, messageCount: 1,
+        },
+        {
+          sessionId: 'sub:s-top-1:agent-1', parentSessionId: 's-top-1', agentId: 'agent-1',
+          subagentType: 'explore', description: 'explore subagent',
+          modified: '2026-05-22T09:59:00.000Z', messageCount: 1,
+        },
+      ],
+    })], true);
+
+    const slot = ctx.document.querySelector('#si-sub\\:s-top-1\\:agent-1 .session-icon');
+    assert.ok(slot, 'the subagent row must carry a .session-icon slot');
+    assert.deepEqual(slotClassesOf(slot), ['session-icon--busy']);
+  } finally { ctx.destroy(); }
+});
diff --git a/test/dom-sidebar-subagent-running.test.js b/test/dom-sidebar-subagent-running.test.js
index 159dbacd..a2179180 100644
--- a/test/dom-sidebar-subagent-running.test.js
+++ b/test/dom-sidebar-subagent-running.test.js
@@ -60,7 +60,7 @@ test('subagent-spawned: .running lands on the subagent item + its dot', () => {
     ctx.emitSubagentSpawned({ parentSessionId: 's-top-1', agentId: 'agent-1', subagentType: 'explore' });
 
     assert.ok(item.classList.contains('running'), '.running set on the subagent item after spawn');
-    const dot = item.querySelector('.session-status-dot');
+    const dot = item.querySelector('.session-icon');
     assert.ok(dot.classList.contains('running'), '.running set on the dot after spawn');
   } finally {
     ctx.destroy();
@@ -78,7 +78,7 @@ test('subagent-completed: .running is removed again', () => {
 
     ctx.emitSubagentCompleted({ parentSessionId: 's-top-1', agentId: 'agent-1' });
     assert.ok(!item.classList.contains('running'), '.running removed after completed');
-    assert.ok(!item.querySelector('.session-status-dot').classList.contains('running'), 'dot no longer running');
+    assert.ok(!item.querySelector('.session-icon').classList.contains('running'), 'dot no longer running');
   } finally {
     ctx.destroy();
   }
diff --git a/test/dom-subagent-transcript.test.js b/test/dom-subagent-transcript.test.js
index 72b28ed5..480b1929 100644
--- a/test/dom-subagent-transcript.test.js
+++ b/test/dom-subagent-transcript.test.js
@@ -123,6 +123,9 @@ function setupDom({ readSubagentJsonlResult = { entries: SAMPLE_ENTRIES }, readS
     setResponseReady: (el, on) => { if (el) el.classList.toggle('response-ready', !!on); },
     setCliBusy: (el, on) => { if (el) el.classList.toggle('cli-busy', !!on); },
     setHasBusyAgents: (el, on) => { if (el) el.classList.toggle('has-busy-agents', !!on); },
+    // issue #246 step 3b — sidebar.js calls this to paint the .session-icon
+    // slot; a no-op here is fine, this harness doesn't assert on it.
+    paintSessionIcon: () => {},
 
     // remote-activity-ui.js is not loaded in this harness — renderProjects
     // calls it unconditionally, and no fixture session here is remote.
diff --git a/test/dom-subagent-ttl-tick.test.js b/test/dom-subagent-ttl-tick.test.js
index f5130e04..2f630594 100644
--- a/test/dom-subagent-ttl-tick.test.js
+++ b/test/dom-subagent-ttl-tick.test.js
@@ -72,6 +72,9 @@ function setupCombinedDom() {
     setResponseReady: (el, on) => { if (el) el.classList.toggle('response-ready', !!on); },
     setCliBusy: (el, on) => { if (el) el.classList.toggle('cli-busy', !!on); },
     setHasBusyAgents: (el, on) => { if (el) el.classList.toggle('has-busy-agents', !!on); },
+    // issue #246 step 3b — sidebar.js calls this to paint the .session-icon
+    // slot; a no-op here is fine, this harness doesn't assert on it.
+    paintSessionIcon: () => {},
     // remote-activity-ui.js is not loaded in this harness — renderProjects
     // calls it unconditionally, and no fixture session here is remote.
     seedRemoteActivity: () => {},
diff --git a/test/running-indicators.test.js b/test/running-indicators.test.js
index 47d4f99b..50f0fbe4 100644
--- a/test/running-indicators.test.js
+++ b/test/running-indicators.test.js
@@ -39,10 +39,10 @@ function buildDom() {
       <div class="slug-group" id="sg1">
         <div class="slug-group-dot"></div>
         <div class="session-item" data-session-id="s1">
-          <div class="session-status-dot"></div>
+          <div class="session-icon"></div>
         </div>
         <div class="session-item" data-session-id="s2">
-          <div class="session-status-dot"></div>
+          <div class="session-icon"></div>
         </div>
       </div>
     </div>
@@ -82,8 +82,8 @@ function makeIndicatorFn(doc, state) {
           // clearActiveSubagentsFor) instead of waiting for the 60s TTL.
           if (state.clearActiveSubagentsFor) state.clearActiveSubagentsFor(id);
         }
-        const dot = item.querySelector('.session-status-dot');
-        if (dot) dot.classList.toggle('running', running);
+        const icon = item.querySelector('.session-icon');
+        if (icon) icon.classList.toggle('running', running);
       });
       doc.querySelectorAll('.slug-group').forEach(group => {
         const hasRunning = group.querySelector('.session-item.has-running-pty') !== null;
@@ -290,7 +290,7 @@ test('makeIndicatorFn replica: subagent items (dataset.subagent) are untouched b
   subagentItem.className = 'session-item running';
   subagentItem.dataset.sessionId = 'sub:s-top-1:agent-1';
   subagentItem.dataset.subagent = '1';
-  subagentItem.innerHTML = '<div class="session-status-dot running"></div>';
+  subagentItem.innerHTML = '<div class="session-icon running"></div>';
   sidebarContent.appendChild(subagentItem);
 
   const state = {
@@ -308,7 +308,7 @@ test('makeIndicatorFn replica: subagent items (dataset.subagent) are untouched b
   update();
 
   assert.ok(subagentItem.classList.contains('running'), 'subagent item keeps .running across an unrelated pty-set change');
-  assert.ok(subagentItem.querySelector('.session-status-dot').classList.contains('running'), 'subagent dot keeps .running');
+  assert.ok(subagentItem.querySelector('.session-icon').classList.contains('running'), 'subagent icon slot keeps .running');
   assert.ok(!subagentItem.classList.contains('has-running-pty'), 'subagent item never gets has-running-pty (no PTY, guard short-circuits before that toggle)');
 
   window.close();
diff --git a/test/session-activity.test.js b/test/session-activity.test.js
index 4380c981..2c42b388 100644
--- a/test/session-activity.test.js
+++ b/test/session-activity.test.js
@@ -393,19 +393,20 @@ test('busy wins over response-ready: the two classes are mutually exclusive by c
   t.destroy();
 });
 
-test('style.css: even if both classes were set, the cli-busy spinner still wins on the dot', () => {
-  // Belt and braces for the mutual exclusion above — jsdom does not resolve
-  // ::before content, so this pins the cascade at the source level. The
-  // response-ready rule (.session-item.response-ready .session-status-dot)
-  // comes LATER in the file, so without !important + the extra :not() class
-  // it would repaint the dot over the spinner.
+test('style.css: the busy icon-slot rung always wins over .session-icon.running', () => {
+  // Issue #246 step 3b (coordinator follow-up, 2026-09-11): renderSessionIcon()
+  // now resolves rung exclusivity in JS (the mutual exclusion tested above),
+  // so the slot's CSS no longer arbitrates between row classes — it keys on
+  // session-icon--busy alone. jsdom does not resolve ::before content, so
+  // this pins the cascade at the source level: background is !important
+  // because a busy row is very often also .session-icon.running (green).
   const css = fs.readFileSync(path.join(__dirname, '..', 'public', 'style.css'), 'utf8');
-  const busyRule = css.match(/\.session-item\.cli-busy:not\(\.needs-attention\) \.session-status-dot,[\s\S]*?\}/);
-  assert.ok(busyRule, 'the cli-busy status-dot rule must still exist');
+  const busyRule = css.match(/\.session-icon--busy \{[\s\S]*?\}/);
+  assert.ok(busyRule, 'the cli-busy icon-slot rule must still exist');
   assert.match(busyRule[0], /background:\s*transparent\s*!important/,
-    'the cli-busy dot must clear its background with !important so response-ready cannot repaint over the spinner');
-  assert.match(css, /\.session-item\.cli-busy:not\(\.needs-attention\) \.session-status-dot::before/,
-    'the braille spinner ::before must still be keyed on cli-busy');
+    'the cli-busy slot must clear its background with !important so .session-icon.running cannot repaint over the spinner');
+  assert.match(css, /\.session-icon--busy::before/,
+    'the braille spinner ::before must still be keyed on the busy rung');
 });
 
 // ---------------------------------------------------------------------------
diff --git a/test/session-icon-slot-css-boundary.test.js b/test/session-icon-slot-css-boundary.test.js
new file mode 100644
index 00000000..85d1da40
--- /dev/null
+++ b/test/session-icon-slot-css-boundary.test.js
@@ -0,0 +1,59 @@
+// Issue #246 step 3b (coordinator follow-up, 2026-09-11) — the icon slot's
+// visual must key on its own session-icon--<rung> class alone.
+// renderSessionIcon() (public/session-state.js) already resolves rung
+// priority in JS — attention > responseReady > busy > agentsBusy >
+// waitingForInput > idle > stale > archived — before the slot's classList is
+// ever written (session-activity-dom.js's writeIconSlot). style.css must
+// never re-arbitrate that priority itself with a :not() row-class chain
+// targeting .session-icon: that was the pre-slot mechanism, back when the
+// four row classes (cli-busy/needs-attention/response-ready/has-busy-agents)
+// could disagree with each other and CSS had to pick a winner. See
+// .ai/contexts/session-state.md ("The icon slot (step 3b)").
+//
+// Same source-grep shape as test/sidebar-busy-agents-tint.test.js's CSS pins
+// — no real CSS parser, just brace/comment stripping good enough to isolate
+// selector text.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CSS = fs.readFileSync(path.join(__dirname, '..', 'public', 'style.css'), 'utf8');
+
+// Strip comments first — a couple of them (deliberately) mention ":not()" and
+// ".session-icon" in prose explaining what NOT to do, which would otherwise
+// false-positive a naive selector-text scan.
+const CSS_NO_COMMENTS = CSS.replace(/\/\*[\s\S]*?\*\//g, '');
+
+test('style.css: no :not() chain targets .session-icon (the slot resolves priority in JS, not CSS)', () => {
+  const ruleBlocks = CSS_NO_COMMENTS.match(/[^{}]+\{[^{}]*\}/g) || [];
+  const offenders = [];
+  for (const block of ruleBlocks) {
+    // Only the last physical line before `{` is the actual selector — guards
+    // against a stray non-comment run of text picking up unrelated content.
+    const lines = block.split('{')[0].split('\n');
+    const selector = lines[lines.length - 1].trim();
+    if (!selector) continue;
+    if (!/\.session-icon\b/.test(selector)) continue;
+    // .remote-host-dot / .session-status-dot are a different row (the
+    // project header's per-host reachability dot) — untouched by #246 and
+    // out of scope for this guard.
+    if (/\.session-status-dot|\.remote-host-dot/.test(selector)) continue;
+    if (/:not\(/.test(selector)) offenders.push(selector);
+  }
+  assert.deepEqual(offenders, [],
+    'a .session-icon selector must never use :not() row-class tie-breaking — offending selector(s): ' + JSON.stringify(offenders));
+});
+
+test('style.css: sanity — the guard above actually inspects .session-icon rules (not vacuously empty)', () => {
+  const ruleBlocks = CSS_NO_COMMENTS.match(/[^{}]+\{[^{}]*\}/g) || [];
+  const sessionIconSelectors = ruleBlocks
+    .map((block) => {
+      const lines = block.split('{')[0].split('\n');
+      return lines[lines.length - 1].trim();
+    })
+    .filter((selector) => /\.session-icon\b/.test(selector) && !/\.session-status-dot|\.remote-host-dot/.test(selector));
+  assert.ok(sessionIconSelectors.length >= 8,
+    'expected at least the base slot, .running, and the four rung rules to be picked up — got: ' + JSON.stringify(sessionIconSelectors));
+});
diff --git a/test/session-state.test.js b/test/session-state.test.js
index 9a15023b..38b0cd0b 100644
--- a/test/session-state.test.js
+++ b/test/session-state.test.js
@@ -175,8 +175,8 @@ test('priority: archived is the lowest rung', () => {
 });
 
 test('priority: an empty snapshot resolves to idle', () => {
-  assert.deepEqual(renderSessionIcon({}), { classes: [], glyph: '', title: 'Idle' });
-  assert.deepEqual(renderSessionIcon(undefined), { classes: [], glyph: '', title: 'Idle' });
+  assert.deepEqual(renderSessionIcon({}), { classes: [], slotClasses: ['session-icon--idle'], glyph: '', title: 'Idle' });
+  assert.deepEqual(renderSessionIcon(undefined), { classes: [], slotClasses: ['session-icon--idle'], glyph: '', title: 'Idle' });
 });
 
 // ---------------------------------------------------------------------------
@@ -201,3 +201,35 @@ test('renderSessionIcon: every rung returns a distinct, well-shaped icon', () =>
     assert.deepEqual(renderSessionIcon(snap).classes, []);
   }
 });
+
+// ---------------------------------------------------------------------------
+// slotClasses — the icon slot's own namespace (step 3b, issue #246), distinct
+// from `classes` (the legacy row-level names) so the slot never trips the
+// eslint rule guarding cli-busy/needs-attention/response-ready/has-busy-agents.
+// ---------------------------------------------------------------------------
+
+test('renderSessionIcon: every rung carries exactly one session-icon-- slot class', () => {
+  const cases = [
+    [{ attention: true }, 'session-icon--attention'],
+    [{ responseReady: true }, 'session-icon--response-ready'],
+    [{ busy: true }, 'session-icon--busy'],
+    [{ agentsBusy: true }, 'session-icon--agents-busy'],
+    [{ waitingForInput: true }, 'session-icon--waiting'],
+    [{ stale: true }, 'session-icon--stale'],
+    [{ archived: true }, 'session-icon--archived'],
+    [{}, 'session-icon--idle'],
+  ];
+  for (const [snap, slotCls] of cases) {
+    const icon = renderSessionIcon(snap);
+    assert.deepEqual(icon.slotClasses, [slotCls], `expected slot class ${slotCls} for ${JSON.stringify(snap)}`);
+  }
+});
+
+// Mutation-provable: swapping any two rungs' table entries must turn this red.
+test('renderSessionIcon: slot class, glyph and title move together with the rung', () => {
+  const busy = renderSessionIcon({ busy: true });
+  const agentsBusy = renderSessionIcon({ agentsBusy: true });
+  assert.deepEqual(busy, { classes: ['cli-busy'], slotClasses: ['session-icon--busy'], glyph: '⠋', title: 'Working' });
+  assert.deepEqual(agentsBusy, { classes: ['has-busy-agents'], slotClasses: ['session-icon--agents-busy'], glyph: '◆', title: 'Subagents running' });
+  assert.notDeepEqual(busy, agentsBusy);
+});
diff --git a/test/sidebar-busy-agents-tint.test.js b/test/sidebar-busy-agents-tint.test.js
index aa727e86..b9388227 100644
--- a/test/sidebar-busy-agents-tint.test.js
+++ b/test/sidebar-busy-agents-tint.test.js
@@ -75,15 +75,24 @@ test('a busy session with live subagents carries cli-busy AND has-busy-agents at
 
 // --- source-level pins: jsdom does not resolve ::before, so the cascade is pinned here
 
+// Issue #246 step 3b (coordinator follow-up, 2026-09-11): the slot's visual
+// now keys on its own session-icon--<rung> class alone — renderSessionIcon()
+// already resolved which single rung applies in JS, so needs-attention/
+// cli-busy precedence is no longer a CSS :not()-chain concern (see
+// test/session-icon-slot-css-boundary.test.js for the source-level guard that
+// no such chain ever targets .session-icon again). The tests below pin what's
+// left: the busy glyph itself, and the has-busy-agents row tint layered on
+// top of it (has-busy-agents stays a row-level class, not a slot rung).
+
 test('style.css: cli-busy alone paints the spinner blue', () => {
-  const rule = CSS.match(/\.session-item\.cli-busy:not\(\.needs-attention\) \.session-status-dot::before \{[\s\S]*?\}/);
+  const rule = CSS.match(/\.session-icon--busy::before \{[\s\S]*?\}/);
   assert.ok(rule, 'the cli-busy spinner rule must still exist');
   assert.match(rule[0], new RegExp('color:\\s*' + BLUE), 'the plain busy spinner stays light blue');
   assert.match(rule[0], /animation:\s*braille-spin/, 'the spinner animation is the existing one');
 });
 
 test('style.css: cli-busy + has-busy-agents tints the same spinner violet', () => {
-  const rule = CSS.match(/\.session-item\.cli-busy\.has-busy-agents:not\(\.needs-attention\) \.session-status-dot::before \{[\s\S]*?\}/);
+  const rule = CSS.match(/\.session-item\.has-busy-agents \.session-icon--busy::before \{[\s\S]*?\}/);
   assert.ok(rule, 'a rule must tint the busy spinner when subagents are live');
   assert.match(rule[0], new RegExp('color:\\s*' + VIOLET), 'it reuses the has-busy-agents violet');
   assert.ok(!/content\s*:/.test(rule[0]), 'the glyph must not change — colour only');
@@ -91,28 +100,24 @@ test('style.css: cli-busy + has-busy-agents tints the same spinner violet', () =
 });
 
 test('style.css: the violet tint wins the cascade over the blue one', () => {
-  const blueAt = CSS.indexOf('.session-item.cli-busy:not(.needs-attention) .session-status-dot::before');
-  const violetAt = CSS.indexOf('.session-item.cli-busy.has-busy-agents:not(.needs-attention) .session-status-dot::before');
+  const blueAt = CSS.indexOf('.session-icon--busy::before');
+  const violetAt = CSS.indexOf('.session-item.has-busy-agents .session-icon--busy::before');
   assert.notEqual(blueAt, -1);
   assert.notEqual(violetAt, -1);
   assert.ok(violetAt > blueAt, 'the tint must come after the rule it overrides');
 });
 
 test('style.css: subagents without cli-busy still get the static glyph, unchanged', () => {
-  const rule = CSS.match(/\.session-item\.has-busy-agents:not\(\.cli-busy\):not\(\.needs-attention\):not\(\.response-ready\) \.session-status-dot::before \{[\s\S]*?\}/);
-  assert.ok(rule, 'the idle-parent indicator must still be keyed on :not(.cli-busy)');
+  // No :not(.cli-busy) chain needed any more: renderSessionIcon() only ever
+  // resolves the agentsBusy rung (session-icon--agents-busy) when busy is
+  // not active — see .ai/contexts/session-state.md priority order.
+  const rule = CSS.match(/\.session-icon--agents-busy::before \{[\s\S]*?\}/);
+  assert.ok(rule, 'the idle-parent indicator rule must still exist');
   assert.match(rule[0], /content:\s*"\\283F"/, 'still the static ⠿ cell');
   assert.match(rule[0], new RegExp('color:\\s*' + VIOLET), 'still violet');
   assert.ok(!/animation\s*:/.test(rule[0]), 'still static');
 });
 
-test('style.css: needs-attention keeps precedence over the tinted spinner', () => {
-  const rule = CSS.match(/\.session-item\.cli-busy\.has-busy-agents:not\(\.needs-attention\) \.session-status-dot::before \{[\s\S]*?\}/);
-  assert.ok(rule, 'the tint rule must exist');
-  assert.match(rule[0].split('{')[0], /:not\(\.needs-attention\)/,
-    'the tint must not paint over the attention indicator');
-});
-
 test('the tint can never collide with response-ready: renderSessionIcon keeps them exclusive', () => {
   // Moved from a source-level regex pin on session-activity.js to a real
   // exercise of session-state.js (the split introduced in .ai/contexts/session-state.md).