(session-state): one domain module, one icon slot, enforced single writer across local/remote/subagent sources

[devsuitup]

Why

Session indicators are computed by different code paths depending on the source: PTY-attached local sessions get .cli-busy / .needs-attention / .response-ready from OSC parsing; remote sessions get an activity pip from the watch channel (#241, #242) plus a state + age text; local sessions launched outside Switchboard get nothing; subagents light their parent only through activeSessions. Each new source (a second host, OpenCode, Codex) would add another path.

public/session-activity.js:27 declares itself the single writer of .cli-busy / .response-ready. That rule holds by discipline only: the first version of the remote spinner alignment bypassed setActivity() from two files and neither lint nor tests went red. Nothing in the codebase makes a violation fail.

A full audit with file:line for every indicator, the divergences and the proposed shapes exists as a local note (.work-files/switchboard/audit-indicateurs-2026-09-10.md); its substance is below.

What

A pure domain module for session state, one projection, and enforcement.

Domain — session-state.js, dual-loadable like public/restore-plan.js (#239) and public/subagent-timing.js: no DOM, no IPC, no electron, loadable under node:test as is.

createSessionState(kind)  // local-pty | local-transcript | remote-ssh | later: opencode, codex
  .apply(event)
  .snapshot() -> { kind, liveness, busy, waitingForInput, attention, agentsBusy,
                   lastActivityAt, lastActivitySource, label, labelConfidence,
                   attachable, archived, stale }

Invariants live here, not in CSS :not() chains: busy / waitingForInput / attention exclusivity, and the priority order (attention > response-ready > busy > agentsBusy > waitingForInput > idle+age > stale > archived).

Ports — the events a source may push. What each adapter can honestly emit:

event	local-pty	local-transcript	remote-ssh
ptyBusy / attention (OSC 0 / 9)	yes	never	only while attached
transcriptTouched(mtime)	yes	yes (only signal)	yes (watch channel)
descriptorStatus(status, at)	yes	no (no live CLI)	yes (already, main.js:539)
subagentSpawned / Completed	yes	no	no today

Only a PTY can tell "thinking" from "waiting for input". An adapter without one must never claim waitingForInput; it produces busy: unknown plus lastActivityAt.

Projection — renderSessionIcon(snapshot) returns classes, glyph and title for one icon slot per row. It absorbs today's .session-status-dot, the busy spinner, .has-busy-agents, and the remote state + age text. .remote-badge (identity) and .remote-host-dot (per-project reachability) legitimately stay separate.

Enforcement — a violation fails, it is not discouraged:

• ESLint no-restricted-syntax forbidding classList.add/toggle with cli-busy / needs-attention / response-ready / has-busy-agents outside the projection file (no no-restricted-* rule exists in eslint.config.js today).
• A boundary test asserting the domain module references neither document, window nor electron (same shape as test/main-ctx-db-wiring.test.js).
• DOM tests go through the real renderSessionIcon(), never a replica (Five test files exercise a hand-written replica, not the production module #171).

Migration order (least churn first)

1. Split public/session-activity.js into state (the Maps/Sets + setActivity) and DOM (applyActivityClasses). This is the seam that does not exist yet.
2. Introduce session-state.js + renderSessionIcon() behind the existing applyActivityClasses call, local-pty only, with the ESLint rule active.
3. Move remote-activity-ui.js and remote-activity.js (already a pure factory) onto the remote-ssh adapter.
4. Add the local-transcript adapter: transcript growth via the existing ~/.claude/projects watcher, for sessions launched outside Switchboard.
5. Subagent attribution through the adapters (separate issue).

Not now

ssh transport (remote-transport.js, remote-mirror.js) — already isolated. Grid vs sidebar unification — separate, deliberate parallel implementations. The non-namespaced session_cache.sessionId primary key.

Cost, stated

main.js is ~2600 lines and mixes transport and decision (OSC parsing 1910-1974, annotateRemoteAttachable 520-545); the renderer is classic scripts sharing a global scope. The dual-load pattern already exists, so the new module is not a new cost; the split of session-activity.js and a unified session notion in main.js are.

[devsuitup]

Step 3 of the alignment sequence: #244 → #245 → #246 → #247. Data gaps closed first by #244 (sidecar inventory) and #245 (local status/age); #247 rides on the adapters introduced here.

[devsuitup]

Lifecycle decisions (2026-09-11)

Two facts the domain must carry, separately: process liveness (the CLI is running — local pid or remote descriptor with an ALIVE marker, #262) and attached view (Switchboard holds a PTY / an ssh attach for it). A row is active because the process is alive, not because a tab is open; the tab is a marker on top.

Two verbs, implemented per adapter:

verb	local-pty	remote-ssh
detach	not offered (closing the tab is a stop, current behaviour kept)	close the attach, restore tmux options (#256) — current close
stop	kill the PTY (current)	kill the process on the host (tmux kill-session or kill of the descriptor pid over ssh), same control and same confirmation dialog as local

No lock on any remote session by name or role: the stop is a real stop everywhere. Ships after the icon slot; tracked here so the state model reserves the fields (liveness, attached) and the projection does not conflate them.

[devsuitup]

Delivered, in order:

• (session-state): pure domain module, single DOM writer, enforced by lint #266 — pure domain module session-state.js (createSessionState(kind), renderSessionIcon), state/DOM split, single class writer enforced by ESLint + boundary test.
• (session-state): feed remote sessions through the remote-ssh adapter #267 — remote-ssh adapter on the watch channel, descriptor and attach state.
• (session-state): one icon slot per sidebar row, resolved by the domain module #268 — one icon slot per row, rung resolved in the domain (session-icon--<rung>), no :not() chains in CSS (source test).
• (session-state): local-transcript adapter for sessions launched outside the app #269 — local-transcript adapter for sessions launched outside the app (session-transcript-activity).
• (subagents): attribute subagent activity to its parent from every source #270 — subagent attribution to the parent from every source ((activity): light has-busy-agents for remote parents and local parents without a PTY #247).
• (remote): stop a remote session for real, behind the same dialog as a local one #272 / (sidebar): archive and delete stop a live remote session on its host first #276 — lifecycle verbs: real remote stop, archive/delete = stop then act.
• (session-state): attached remote row is written by two owners — response-ready flap and a 20 s busy tail after exit #273 ((session-state): one owner per remote row — local-pty while attached, the adapter otherwise #275) — ownership rule: attached remote row → local-pty path, otherwise the adapter.
• (session-state): local-pty rows carry a persistent state like the other adapters #282 — local-pty as a persistent state like the other adapters; legacy Maps are views; exclusivity lives only in the domain. Decided semantics recorded in session-state.md (attention orthogonal to busy and consuming the unseen-response state; local idle-while-active reads "Waiting for input").

Out of scope, unchanged: the grid view stays a parallel implementation of the sidebar; ports exist for other agent kinds (OpenCode, Codex) but no adapter is written; activeSubagentsByParent keeps its own per-agent TTL tracking (aggregate mirrored into the adapter).

Shipped in v0.0.77 (#266–#276) and v0.0.78 (#279, #280); #282 lands in the next release. Reference: .ai/contexts/session-state.md.