@jhizzard/termdeck 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/client/public/app.js

@@ -25,7 +25,14 @@
       // works if the endpoint 404s on an older server during a rolling
       // upgrade — Claude only, anchored binary match.
       agentAdapters: [{ name: 'claude', sessionType: 'claude-code', binary: 'claude', costBand: 'pay-per-token' }],
-      focusedId: null
+      focusedId: null,
+      // Sprint 65 T1 — selected project-filter chip ('' = All). Hydrated from
+      // localStorage in init(); a TDZ on PROJECT_FILTER_KEY prevents reading
+      // it here in the state literal.
+      projectFilter: '',
+      // Sprint 65 T1 (c) — global terminal font size (xterm.js default 13).
+      // Hydrated from localStorage in init() (same TDZ reason as projectFilter).
+      fontSize: 13
     };
 
     // ===== API helpers =====
@@ -33,11 +40,25 @@
       const opts = { method, headers: { 'Content-Type': 'application/json' } };
       if (body) opts.body = JSON.stringify(body);
       const res = await fetch(`${API}${path}`, opts);
-      return res.json();
+      // Success path: unchanged — return the parsed JSON body verbatim.
+      if (res.ok) return res.json();
+      // Sprint 65 T1 (1.3b) — non-2xx: many callers gate on `.error` and
+      // otherwise treat the body as success. A 4xx/5xx body without an
+      // `error` key (e.g. the dead-panel shape 410 {ok:false,code,message})
+      // would be misreported as delivered. annotateApiFailure() synthesizes a
+      // uniform `error` field and surfaces `_httpStatus` for precise callers.
+      let data = null;
+      try { data = await res.json(); } catch (err) { /* non-JSON error body */ }
+      return annotateApiFailure(data, res.status);
     }
 
     // ===== Initialize =====
     async function init() {
+      // Sprint 65 T1 — hydrate saved client prefs before any panel mounts: the
+      // project-filter chip (so a new tile filters right from frame 1) and the
+      // terminal font size (so restored panels open at the operator's size).
+      state.projectFilter = loadProjectFilter();
+      state.fontSize = loadFontSize();
       // Load config
       state.config = await api('GET', '/api/config');
       updateRagIndicator();
@@ -105,6 +126,14 @@
 
       updateEmptyState();
 
+      // Sprint 65 T1 — initial restore complete: subsequent createTerminalPanel
+      // calls are user-initiated launches, so arm the born-hidden chip guard.
+      _initialLoadComplete = true;
+      // Render chips + route the ORCH row now that the restored panels exist.
+      refreshDashboardChrome();
+      // Sprint 65 T1 (c) — sync the topbar font-size label to the saved size.
+      applyFontSizeToAll();
+
       // Rumen insights badge + briefing (no-op when server reports enabled:false)
       setupRumen();
 
@@ -433,7 +462,9 @@
         </div>
       `;
 
-      document.getElementById('termGrid').appendChild(panel);
+      // Sprint 65 T1 (1.2) — orchestrator panels render in the pinned ORCH
+      // row above the grid; everything else goes in the grid.
+      placePanel(panel, meta);
 
       // Sprint 42 T4: drag/drop reorder. Inject identifier is the session
       // UUID, so DOM reorder is purely visual — Alt+1…9 (creation-order),
@@ -443,7 +474,7 @@
       // Create xterm.js instance
       const terminal = new Terminal({
         fontFamily: "'SF Mono', 'Cascadia Code', 'JetBrains Mono', 'Fira Code', Consolas, monospace",
-        fontSize: 13,
+        fontSize: state.fontSize,
         lineHeight: 1.3,
         cursorBlink: true,
         cursorStyle: 'bar',
@@ -499,6 +530,11 @@
               refreshPanelIndices();
               renderSwitcher();
               break;
+            case 'panel_exited':
+              // Sprint 65 T1 (1.3) — T2 broadcasts this when a PTY exits.
+              // Primary path for auto-removing the dead tile from the grid.
+              handlePanelExited(msg.sessionId, msg.exitCode);
+              break;
             case 'status_broadcast':
               updateGlobalStats(msg.sessions);
               break;
@@ -592,6 +628,11 @@
       if (replyBtn) replyBtn.disabled = state.sessions.size < 2;
       refreshAllReplyFormsFor(id);
       refreshPanelIndices();
+      // Sprint 65 T1 — a user-launched panel must never be born hidden behind a
+      // stale chip filter (T3 20:10 / T4 20:11): switch the filter to its
+      // project first, then refresh chrome so the new tile is visible.
+      revealNewPanelIfFiltered(meta);
+      refreshDashboardChrome();
 
       // Handle window resize
       const resizeObserver = new ResizeObserver(() => {
@@ -611,6 +652,486 @@
       return { terminal, ws, fitAddon };
     }
 
+    // ===== Sprint 65: project-filter chips + ORCH-panel pin + tile lifecycle =====
+    // Brad's 2026-05-13 v2 spec (BACKLOG § D.5) — three dashboard-reliability
+    // surfaces sharing one client-side lane:
+    //   1.1  project-filter chips — a per-project visibility filter above the grid
+    //   1.2  ORCH pin — panels with meta.role==='orchestrator' get a dedicated
+    //        always-visible row + gold/amber treatment, outside the chip filter
+    //   1.3  tile auto-removal — dead PTY panels leave the grid instead of
+    //        lingering as "dead" tiles (Brad's "18 windows, 10 dead codex cli")
+    //
+    // Design note: TermDeck panels are persistent DOM + live xterm.js + a
+    // per-panel WebSocket. They are created once (createTerminalPanel) and
+    // never re-rendered per frame — status_broadcast only mutates meta. So the
+    // chip row and filter work by toggling classes on existing tiles, never by
+    // tearing panels down; ORCH routing is decided at panel-create time and
+    // re-checked cheaply on each broadcast.
+
+    const PROJECT_FILTER_KEY = 'termdeck.dashboard.projectFilter';
+    // Belt-and-suspenders thresholds for tile reconciliation (reconcileExitedPanels).
+    // ORPHAN_GRACE_MS > the tile-exit grace so the primary panel_exited path
+    // always wins when the WS frame is delivered.
+    const ORPHAN_GRACE_MS = 5000;
+    const STALE_EXITED_MS = 60000;
+    let _chromeRefreshScheduled = false;
+    // false during init()'s panel-restore loop, true afterward. Gates the
+    // born-hidden chip guard so a saved filter is honored on reload but a
+    // user-launched panel is always revealed.
+    let _initialLoadComplete = false;
+
+    // --- Pure helpers (no DOM, no globals — unit-tested in
+    //     tests/dashboard-panels-client.test.js via the vm-extract pattern) ---
+
+    // Distinct non-null project tags across the given session-meta list, plus
+    // whether any panel carries no project at all. `metas` is an array of
+    // session.meta objects. Exited panels are excluded — chips count live work.
+    function discoverPanelProjects(metas) {
+      const projects = [];
+      const seen = Object.create(null);
+      let hasNullProject = false;
+      for (const m of (metas || [])) {
+        if (!m || m.status === 'exited') continue;
+        const p = m.project;
+        if (p === null || p === undefined || p === '') {
+          hasNullProject = true;
+          continue;
+        }
+        if (!seen[p]) {
+          seen[p] = true;
+          projects.push(p);
+        }
+      }
+      projects.sort();
+      return { projects: projects, hasNullProject: hasNullProject };
+    }
+
+    // Count of live (non-exited) panels for one chip. The "All" chip passes
+    // project==='' and counts every live panel; a project chip counts only its
+    // own. Orchestrator panels are counted under their project too — the ORCH
+    // pin is a placement, not an exclusion from the totals.
+    function countPanelsForProject(metas, project) {
+      let n = 0;
+      for (const m of (metas || [])) {
+        if (!m || m.status === 'exited') continue;
+        if (project === '' || project === null || project === undefined) { n++; continue; }
+        if (m.project === project) n++;
+      }
+      return n;
+    }
+
+    // Whether a grid tile with the given project should be visible under the
+    // current chip selection. The "All" selection ('') shows everything; a
+    // project selection shows only exact matches (null-project panels are
+    // hidden under any specific-project filter — they surface only under All).
+    function isPanelVisibleUnderFilter(panelProject, selectedFilter) {
+      if (selectedFilter === '' || selectedFilter === null || selectedFilter === undefined) return true;
+      return panelProject === selectedFilter;
+    }
+
+    // The chip row is only worth showing when there is real filtering to do:
+    // at least two project buckets, or one project plus some untagged panels.
+    function shouldShowChipRow(projects, hasNullProject) {
+      const n = (projects || []).length;
+      return n >= 2 || (n >= 1 && hasNullProject === true);
+    }
+
+    // Approach A (Brad's 2026-05-13 spec): orchestrator identity is the
+    // explicit meta.role flag, never inferred from cwd.
+    function isOrchestratorRole(role) {
+      return role === 'orchestrator';
+    }
+
+    // Belt-and-suspenders for missed panel_exited frames: panel ids the
+    // dashboard still has a tile for, but which no longer appear in the
+    // server's broadcast session list. Works whether or not T2 filters exited
+    // sessions out of status_broadcast.
+    function findOrphanedPanelIds(knownPanelIds, broadcastSessionIds) {
+      const live = Object.create(null);
+      for (const id of (broadcastSessionIds || [])) live[id] = true;
+      const orphaned = [];
+      for (const id of (knownPanelIds || [])) {
+        if (!live[id]) orphaned.push(id);
+      }
+      return orphaned;
+    }
+
+    // 1.3b — give a non-2xx API body a uniform failure signal. Many callers
+    // gate on `.error`; a 4xx/5xx body that lacks it (e.g. the Sprint 65
+    // dead-panel shape 410 {ok:false,code:'panel_exited',message}) would
+    // otherwise be misread as success. Pure: takes the parsed body + status,
+    // returns the body annotated with `error` + `_httpStatus`.
+    function annotateApiFailure(body, httpStatus) {
+      const out = (body && typeof body === 'object' && !Array.isArray(body)) ? body : {};
+      if (out.error === undefined || out.error === null) {
+        out.error = out.message || out.code || ('HTTP ' + httpStatus);
+      }
+      out._httpStatus = httpStatus;
+      return out;
+    }
+
+    // 1.1 born-hidden guard (T3 20:10 / T4 20:11) — a panel the operator just
+    // launched must never be hidden by a stale chip filter. Given the active
+    // filter and a newly-created panel, returns the filter value that keeps the
+    // panel visible, or null when no switch is needed. Pure.
+    function filterValueRevealingPanel(currentFilter, panelProject, isOrchPanel, initialLoadComplete) {
+      if (initialLoadComplete !== true) return null;  // initial restore — honor the saved filter
+      if (isOrchPanel === true) return null;          // ORCH panels bypass the chip filter
+      const proj = panelProject || '';
+      if (!currentFilter) return null;                // "All" already shows everything
+      if (currentFilter === proj) return null;        // already visible under this filter
+      return proj;                                    // switch the filter to the new panel's project
+    }
+
+    // --- localStorage-backed filter persistence (origin-scoped, per-tab) ---
+    function loadProjectFilter() {
+      try {
+        const v = localStorage.getItem(PROJECT_FILTER_KEY);
+        return typeof v === 'string' ? v : '';
+      } catch (err) {
+        console.warn('[client] projectFilter load failed:', err);
+        return '';
+      }
+    }
+    function saveProjectFilter(value) {
+      try {
+        localStorage.setItem(PROJECT_FILTER_KEY, value || '');
+      } catch (err) {
+        console.warn('[client] projectFilter save failed:', err);
+      }
+    }
+
+    // session.meta for every panel currently mounted on THIS dashboard. Skips
+    // the _mounting placeholder createTerminalPanel reserves at function entry
+    // before the real entry is written.
+    function dashboardPanelMetas() {
+      const metas = [];
+      for (const entry of state.sessions.values()) {
+        if (!entry || entry._mounting || !entry.session || !entry.session.meta) continue;
+        metas.push(entry.session.meta);
+      }
+      return metas;
+    }
+
+    // 1.1 — (re)render the project-filter chip row from the live panel set.
+    // Chips are built with createElement (not innerHTML) so project names need
+    // no attribute escaping and cannot inject markup.
+    function renderProjectChips() {
+      const row = document.getElementById('project-chips');
+      if (!row) return;
+      const metas = dashboardPanelMetas();
+      const discovered = discoverPanelProjects(metas);
+      const projects = discovered.projects;
+
+      if (!shouldShowChipRow(projects, discovered.hasNullProject)) {
+        row.replaceChildren();
+        return;
+      }
+
+      // If the selected project no longer has any live panels, fall back to
+      // "All" so the grid never strands empty behind a dead chip.
+      if (state.projectFilter && projects.indexOf(state.projectFilter) === -1) {
+        state.projectFilter = '';
+        saveProjectFilter('');
+      }
+
+      const chips = [{ project: '', label: 'All' }];
+      for (const p of projects) chips.push({ project: p, label: p });
+
+      const frag = document.createDocumentFragment();
+      for (const c of chips) {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'project-chip' + (((state.projectFilter || '') === c.project) ? ' active' : '');
+        btn.dataset.project = c.project;
+        const label = document.createElement('span');
+        label.className = 'project-chip-label';
+        label.textContent = c.label;
+        const count = document.createElement('span');
+        count.className = 'project-chip-count';
+        count.textContent = '(' + countPanelsForProject(metas, c.project) + ')';
+        btn.appendChild(label);
+        btn.appendChild(count);
+        frag.appendChild(btn);
+      }
+      row.replaceChildren(frag);
+    }
+
+    // 1.1 — apply the current chip selection to the grid by toggling
+    // .panel--filtered-out (display:none) on tiles. PTYs are never torn down —
+    // a filtered panel keeps running, just hidden. Orchestrator tiles live
+    // outside the grid and are never filtered.
+    function applyProjectFilter() {
+      for (const entry of state.sessions.values()) {
+        if (!entry || entry._mounting || !entry.el || !entry.session) continue;
+        if (isOrchestratorRole(entry.session.meta && entry.session.meta.role)) {
+          entry.el.classList.remove('panel--filtered-out');
+          continue;
+        }
+        const project = entry.session.meta ? entry.session.meta.project : null;
+        const visible = isPanelVisibleUnderFilter(project, state.projectFilter || '');
+        entry.el.classList.toggle('panel--filtered-out', !visible);
+      }
+    }
+
+    // 1.1 — chip click: single-select, persist, re-render + re-filter + refit.
+    function onProjectChipClick(e) {
+      const chip = e.target && e.target.closest ? e.target.closest('.project-chip') : null;
+      if (!chip) return;
+      const project = chip.getAttribute('data-project') || '';
+      state.projectFilter = project;
+      saveProjectFilter(project);
+      renderProjectChips();
+      applyProjectFilter();
+      requestAnimationFrame(function () { fitAll(); });
+    }
+
+    // 1.1 — born-hidden guard for a freshly-created panel: if an active chip
+    // filter would hide it, switch the filter to the panel's project so the
+    // operator sees what they just launched. No-op during the initial restore.
+    function revealNewPanelIfFiltered(meta) {
+      const next = filterValueRevealingPanel(
+        state.projectFilter,
+        meta && meta.project,
+        isOrchestratorRole(meta && meta.role),
+        _initialLoadComplete
+      );
+      if (next === null) return;
+      state.projectFilter = next;
+      saveProjectFilter(next);
+    }
+
+    // 1.2 — route a freshly-built panel into the ORCH pin row or the grid.
+    function placePanel(panel, meta) {
+      const orchRow = document.getElementById('orch-pin-row');
+      if (orchRow && isOrchestratorRole(meta && meta.role)) {
+        panel.classList.add('panel--role-orch');
+        orchRow.appendChild(panel);
+      } else {
+        document.getElementById('termGrid').appendChild(panel);
+      }
+    }
+
+    // 1.2 — defensive reconcile: keep every tile in the container its role
+    // dictates. meta.role is immutable post-spawn so this is a no-op after a
+    // panel's first placement; it only acts if a panel was somehow built
+    // before its role was known. Returns true if any tile moved.
+    function reconcileOrchRow() {
+      const orchRow = document.getElementById('orch-pin-row');
+      const grid = document.getElementById('termGrid');
+      if (!orchRow || !grid) return false;
+      let moved = false;
+      for (const entry of state.sessions.values()) {
+        if (!entry || entry._mounting || !entry.el || !entry.session) continue;
+        const isOrch = isOrchestratorRole(entry.session.meta && entry.session.meta.role);
+        const inOrchRow = entry.el.parentElement === orchRow;
+        if (isOrch && !inOrchRow) {
+          entry.el.classList.add('panel--role-orch');
+          entry.el.classList.remove('panel--filtered-out');
+          orchRow.appendChild(entry.el);
+          moved = true;
+        } else if (!isOrch && inOrchRow) {
+          entry.el.classList.remove('panel--role-orch');
+          grid.appendChild(entry.el);
+          moved = true;
+        }
+      }
+      return moved;
+    }
+
+    // Single entry point for keeping the dashboard chrome (ORCH row + chips +
+    // filter) in sync with the live panel set. Cheap — class toggles and a
+    // small chip-row rebuild.
+    function refreshDashboardChrome() {
+      const moved = reconcileOrchRow();
+      renderProjectChips();
+      applyProjectFilter();
+      if (moved) requestAnimationFrame(function () { fitAll(); });
+    }
+
+    // status_broadcast fires once per panel WebSocket; coalesce the resulting
+    // chrome refreshes into one per animation frame so an 18-panel dashboard
+    // doesn't rebuild the chip row 18× per 2s tick (T4's count-thrash concern).
+    function scheduleChromeRefresh() {
+      if (_chromeRefreshScheduled) return;
+      _chromeRefreshScheduled = true;
+      requestAnimationFrame(function () {
+        _chromeRefreshScheduled = false;
+        refreshDashboardChrome();
+      });
+    }
+
+    // --- 1.3: tile auto-removal on PTY exit ---
+
+    // Grace window before a dead tile is pulled, so the operator sees the
+    // final post-exit lines. Overridable via <body data-tile-exit-grace-ms>
+    // for deterministic tests.
+    function tileExitGraceMs() {
+      try {
+        const attr = document.body && document.body.getAttribute('data-tile-exit-grace-ms');
+        const n = attr != null ? parseInt(attr, 10) : NaN;
+        if (Number.isFinite(n) && n >= 0) return n;
+      } catch (err) {
+        console.warn('[client] tile-exit-grace read failed:', err);
+      }
+      return 3000;
+    }
+
+    // Tear down a panel's DOM + xterm + WebSocket and drop it from state.
+    // Idempotent: a second call for an already-removed id is a no-op. Shared
+    // by handlePanelExited (primary) and reconcileExitedPanels (fallback).
+    function removePanelTile(id) {
+      const entry = state.sessions.get(id);
+      if (!entry) return;
+      try { if (entry.terminal) entry.terminal.dispose(); } catch (err) { console.warn('[client] terminal dispose failed:', err); }
+      try { if (entry.ws) entry.ws.close(); } catch (err) { console.warn('[client] ws close failed:', err); }
+      try { if (entry.el) entry.el.remove(); } catch (err) { console.warn('[client] tile remove failed:', err); }
+      state.sessions.delete(id);
+      updateEmptyState();
+      renderSwitcher();
+      refreshAllReplyFormsFor(id);
+      refreshPanelIndices();
+      refreshDashboardChrome();
+    }
+
+    // 1.3 primary path — the server broadcast a panel_exited frame (T2 sub-task
+    // 2.4). Dim the tile for a grace window, then remove it. Guarded with
+    // _exitScheduled because panel_exited arrives on every panel's WebSocket.
+    function handlePanelExited(sessionId, exitCode) {
+      const entry = state.sessions.get(sessionId);
+      if (!entry || !entry.el) return;
+      if (entry._exitScheduled) return;
+      entry._exitScheduled = true;
+      entry.el.classList.add('panel--exiting');
+      const statusEl = document.getElementById('status-' + sessionId);
+      if (statusEl && exitCode !== undefined && exitCode !== null) {
+        statusEl.textContent = 'Exited (' + exitCode + ')';
+      }
+      setTimeout(function () { removePanelTile(sessionId); }, tileExitGraceMs());
+    }
+
+    // 1.3 belt-and-suspenders — covers a missed panel_exited frame. Two
+    // independent checks so the dashboard cannot strand a dead tile forever
+    // regardless of how T2 implements exited-session filtering:
+    //   (a) orphaned — a tile whose session id has dropped out of the
+    //       broadcast entirely (fires when T2 filters exited from the
+    //       broadcast); removed after ORPHAN_GRACE_MS.
+    //   (b) stale-exited — a tile still in the broadcast with status 'exited'
+    //       and lastActivity older than STALE_EXITED_MS (fires when T2 keeps
+    //       exited sessions in the broadcast).
+    function reconcileExitedPanels(broadcastSessions) {
+      const list = Array.isArray(broadcastSessions) ? broadcastSessions : [];
+      const broadcastIds = [];
+      const metaById = Object.create(null);
+      for (const s of list) {
+        if (s && s.id) { broadcastIds.push(s.id); metaById[s.id] = s.meta || {}; }
+      }
+      const knownIds = [];
+      for (const [id, entry] of state.sessions) {
+        if (entry && !entry._mounting && entry.el) knownIds.push(id);
+      }
+      const now = Date.now();
+
+      // (a) orphaned-from-broadcast
+      const orphaned = findOrphanedPanelIds(knownIds, broadcastIds);
+      const orphanSet = Object.create(null);
+      for (const id of orphaned) {
+        orphanSet[id] = true;
+        const entry = state.sessions.get(id);
+        if (!entry) continue;
+        if (!entry._orphanedSince) entry._orphanedSince = now;
+        if (now - entry._orphanedSince >= ORPHAN_GRACE_MS && !entry._exitScheduled) {
+          removePanelTile(id);
+        }
+      }
+      // clear the stamp for any panel that is back in the broadcast
+      for (const id of knownIds) {
+        const entry = state.sessions.get(id);
+        if (entry && entry._orphanedSince && !orphanSet[id]) entry._orphanedSince = null;
+      }
+
+      // (b) stale-exited still present in the broadcast
+      for (const id of knownIds) {
+        const meta = metaById[id];
+        if (!meta || meta.status !== 'exited') continue;
+        const entry = state.sessions.get(id);
+        if (!entry || entry._exitScheduled) continue;
+        const last = meta.lastActivity ? new Date(meta.lastActivity).getTime() : 0;
+        if (last && now - last >= STALE_EXITED_MS) {
+          removePanelTile(id);
+        }
+      }
+    }
+
+    // ===== Sprint 65 T1 (Joshua's 2026-05-16 ask c): terminal font size =====
+    // A single global xterm.js font size, adjusted from the topbar A-/A+
+    // stepper and persisted in localStorage. Applies to every panel (existing
+    // + future) — operators running dense CLI output wanted smaller text. The
+    // BACKLOG 2026-05-16 entry sanctions "per-panel OR global"; global is the
+    // simpler, lower-risk option for this contingent sub-task.
+
+    const FONT_SIZE_KEY = 'termdeck.dashboard.fontSize';
+
+    // Clamp a requested font size to the supported range, coercing non-numbers
+    // to the xterm.js default (13). Pure — unit-tested via the vm-extract path.
+    function clampFontSize(n) {
+      const v = Math.round(Number(n));
+      if (!Number.isFinite(v)) return 13;
+      if (v < 8) return 8;
+      if (v > 22) return 22;
+      return v;
+    }
+
+    function loadFontSize() {
+      try {
+        const raw = localStorage.getItem(FONT_SIZE_KEY);
+        return raw != null ? clampFontSize(raw) : 13;
+      } catch (err) {
+        console.warn('[client] fontSize load failed:', err);
+        return 13;
+      }
+    }
+    function saveFontSize(n) {
+      try {
+        localStorage.setItem(FONT_SIZE_KEY, String(n));
+      } catch (err) {
+        console.warn('[client] fontSize save failed:', err);
+      }
+    }
+
+    // Apply the global font size to every live terminal. Changing fontSize
+    // resizes the character cell but NOT the container, so the per-panel
+    // ResizeObserver does not fire — refit + push the new cols/rows explicitly.
+    function applyFontSizeToAll() {
+      for (const entry of state.sessions.values()) {
+        if (!entry || entry._mounting || !entry.terminal) continue;
+        try {
+          entry.terminal.options.fontSize = state.fontSize;
+          if (entry.fitAddon) entry.fitAddon.fit();
+          if (entry.ws && entry.ws.readyState === WebSocket.OPEN) {
+            entry.ws.send(JSON.stringify({
+              type: 'resize',
+              cols: entry.terminal.cols,
+              rows: entry.terminal.rows,
+            }));
+          }
+        } catch (err) {
+          console.warn('[client] fontSize apply failed for a panel:', err);
+        }
+      }
+      const label = document.getElementById('fontSizeLabel');
+      if (label) label.textContent = String(state.fontSize);
+    }
+
+    // Topbar A-/A+ stepper handler. delta is +1 or -1.
+    function stepFontSize(delta) {
+      const next = clampFontSize(state.fontSize + delta);
+      if (next === state.fontSize) return;
+      state.fontSize = next;
+      saveFontSize(next);
+      applyFontSizeToAll();
+    }
+
     // ===== Control dashboard (T1.6) =====
     async function enterControlMode() {
       // Pre-warm command history for every open session so the feed is dense.
@@ -1536,6 +2057,11 @@
               const p = document.getElementById(`panel-${id}`);
               if (p) p.classList.add('exited');
               break;
+            case 'panel_exited':
+              // Sprint 65 T1 (1.3) — parity with the main WS handler so the
+              // dead-tile removal still fires for reconnected panels.
+              handlePanelExited(msg.sessionId, msg.exitCode);
+              break;
             case 'status_broadcast':
               updateGlobalStats(msg.sessions);
               break;
@@ -1621,6 +2147,8 @@
       renderSwitcher();
       refreshAllReplyFormsFor(id);
       refreshPanelIndices();
+      // Sprint 65 T1 — closing a panel changes chip counts / may empty a chip.
+      refreshDashboardChrome();
     }
 
     function changeTheme(id, themeId) {
@@ -2954,6 +3482,10 @@
       document.getElementById('stat-thinking').textContent = thinking;
       document.getElementById('stat-idle').textContent = idle;
       renderSwitcher();
+      // Sprint 65 T1 — reconcile dead tiles against this broadcast, then
+      // refresh chips + ORCH-row chrome (coalesced to one rebuild per frame).
+      reconcileExitedPanels(sessions);
+      scheduleChromeRefresh();
     }
 
     function updateEmptyState() {
@@ -4246,6 +4778,17 @@
       btn.addEventListener('click', () => setLayout(btn.dataset.layout));
     });
 
+    // Sprint 65 T1 (1.1) — project-filter chip clicks (delegated; chips are
+    // rebuilt on every status_broadcast so a per-chip listener would go stale).
+    const projectChipsRow = document.getElementById('project-chips');
+    if (projectChipsRow) projectChipsRow.addEventListener('click', onProjectChipClick);
+
+    // Sprint 65 T1 (c) — topbar terminal font-size stepper.
+    const fontDecBtn = document.getElementById('btn-font-dec');
+    const fontIncBtn = document.getElementById('btn-font-inc');
+    if (fontDecBtn) fontDecBtn.addEventListener('click', () => stepFontSize(-1));
+    if (fontIncBtn) fontIncBtn.addEventListener('click', () => stepFontSize(1));
+
     document.getElementById('promptLaunch').addEventListener('click', launchTerminal);
     document.getElementById('promptInput').addEventListener('keydown', (e) => {
       if (e.key === 'Enter') launchTerminal();
@@ -4362,11 +4905,15 @@
           document.getElementById('promptInput').focus();
         }
       }
-      // Ctrl+Shift+1-7 OR Cmd+Shift+1-7 → layout switch (Mac friendly)
-      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key >= '1' && e.key <= '7') {
+      // Ctrl+Shift+1-9,0 OR Cmd+Shift+1-9,0 → layout switch (Mac friendly).
+      // Sprint 65 T1 (1.4) — keys 1-9 map to indices 0-8, key 0 maps to index
+      // 9. Keys 1-7 keep their pre-Sprint-65 layouts (muscle memory); 8/9/0 are
+      // the new dense presets. Topbar buttons cover every preset incl. 2x5/5x2/3x4.
+      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key >= '0' && e.key <= '9') {
         e.preventDefault();
-        const layouts = ['1x1', '2x1', '2x2', '3x2', '2x4', '4x2', 'orch'];
-        setLayout(layouts[parseInt(e.key) - 1]);
+        const layouts = ['1x1', '2x1', '2x2', '3x2', '2x4', '4x2', 'orch', '1x2', '4x3', '4x4'];
+        const idx = e.key === '0' ? 9 : parseInt(e.key, 10) - 1;
+        if (layouts[idx]) setLayout(layouts[idx]);
       }
       // Ctrl+Shift+] / [ → cycle between terminals
       if (e.ctrlKey && e.shiftKey && (e.key === ']' || e.key === '[')) {

package/packages/client/public/index.html

@@ -35,12 +35,18 @@
       </div>
 
       <div class="topbar-center">
-        <button class="layout-btn" data-layout="1x1">1x1</button>
-        <button class="layout-btn active" data-layout="2x1">2x1</button>
-        <button class="layout-btn" data-layout="2x2">2x2</button>
-        <button class="layout-btn" data-layout="3x2">3x2</button>
-        <button class="layout-btn" data-layout="2x4">2x4</button>
-        <button class="layout-btn" data-layout="4x2">4x2</button>
+        <button class="layout-btn" data-layout="1x1" title="1 panel">1x1</button>
+        <button class="layout-btn active" data-layout="2x1" title="2 panels — side by side">2x1</button>
+        <button class="layout-btn" data-layout="1x2" title="2 panels — stacked vertically">1x2</button>
+        <button class="layout-btn" data-layout="2x2" title="4 panels">2x2</button>
+        <button class="layout-btn" data-layout="3x2" title="6 panels">3x2</button>
+        <button class="layout-btn" data-layout="2x4" title="8 panels — 2 cols × 4 rows">2x4</button>
+        <button class="layout-btn" data-layout="4x2" title="8 panels — 4 cols × 2 rows">4x2</button>
+        <button class="layout-btn" data-layout="2x5" title="10 panels — 2 cols × 5 rows">2x5</button>
+        <button class="layout-btn" data-layout="5x2" title="10 panels — 5 cols × 2 rows">5x2</button>
+        <button class="layout-btn" data-layout="4x3" title="12 panels — 4 cols × 3 rows">4x3</button>
+        <button class="layout-btn" data-layout="3x4" title="12 panels — 3 cols × 4 rows">3x4</button>
+        <button class="layout-btn" data-layout="4x4" title="16 panels">4x4</button>
         <button class="layout-btn" data-layout="orch" title="Orchestrator: 4 workers across top, 1 full-width orchestrator across bottom">orch</button>
         <button class="layout-btn control-btn" data-layout="control" title="Aggregate activity feed">control</button>
       </div>
@@ -58,6 +64,13 @@
         <button class="topbar-ql-btn" onclick="quickLaunch('python3 -m http.server 8080')" title="Open a Python HTTP server on :8080">python</button>
       </div>
       <div class="topbar-row-2-spacer"></div>
+      <!-- TERMINAL FONT-SIZE STEPPER (Sprint 65 T1): global xterm.js font size,
+           persisted in localStorage, applied to every panel. -->
+      <div class="topbar-fontsize" title="Terminal font size (applies to all panels)">
+        <button type="button" id="btn-font-dec" class="font-step-btn" aria-label="Decrease terminal font size">A−</button>
+        <span id="fontSizeLabel" class="font-size-label">13</span>
+        <button type="button" id="btn-font-inc" class="font-step-btn" aria-label="Increase terminal font size">A+</button>
+      </div>
       <button id="btn-status" title="Global metrics: session counts, RAG mode, and memory bridge status">status</button>
       <button id="btn-config" title="Configuration: project list, theme defaults, and live RAG-mode toggle">config</button>      <button id="btn-sprint" title="Define and kick off a 4+1 sprint">sprint</button>
       <button id="btn-graph" title="Open the knowledge-graph view (memory_items + memory_relationships, force-directed)" onclick="window.open('/graph.html','_blank','noopener')">graph</button>
@@ -67,6 +80,15 @@
     </div>
   </div>
 
+  <!-- ORCHESTRATOR PIN ROW (Sprint 65 T1): panels with meta.role==='orchestrator'
+       render here — pinned, always visible, outside the chip filter. The row
+       collapses to zero height when no orchestrator panel exists. -->
+  <div class="orch-pin-row" id="orch-pin-row"></div>
+
+  <!-- PROJECT FILTER CHIPS (Sprint 65 T1): per-project visibility filter,
+       auto-discovered from meta.project and populated by app.js. -->
+  <div class="project-chips-row" id="project-chips"></div>
+
   <!-- TERMINAL GRID -->
   <div class="grid-container layout-2x1" id="termGrid">
     <div class="control-feed" id="controlFeed">

package/packages/client/public/style.css

@@ -10,6 +10,9 @@
       --tg-text-bright: #eef1ff;
       --tg-accent: #7aa2f7;
       --tg-accent-dim: #3d5a9e;
+      /* Sprint 65 T1 — orchestrator-panel accent (gold/amber). A theme can
+         override this var; the ORCH-pin CSS falls back to #d4a017 if unset. */
+      --tg-accent-orch: #d4a017;
       --tg-green: #9ece6a;
       --tg-amber: #e0af68;
       --tg-red: #f7768e;
@@ -317,6 +320,14 @@
     .grid-container.layout-3x2 { grid-template-columns: 1fr 1fr 1fr; grid-template-rows: 1fr 1fr; }
     .grid-container.layout-4x2 { grid-template-columns: 1fr 1fr 1fr 1fr; grid-template-rows: 1fr 1fr; }
     .grid-container.layout-2x4 { grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr 1fr; }
+    /* Sprint 65 T1 (1.4 / Path A) — denser presets for many-parallel-projects
+       work. layout-1x2 already exists above; these cover 10 / 12 / 16-panel
+       grids. WxH = columns × rows, consistent with the presets above. */
+    .grid-container.layout-2x5 { grid-template-columns: 1fr 1fr; grid-template-rows: repeat(5, 1fr); }
+    .grid-container.layout-5x2 { grid-template-columns: repeat(5, 1fr); grid-template-rows: 1fr 1fr; }
+    .grid-container.layout-4x3 { grid-template-columns: repeat(4, 1fr); grid-template-rows: 1fr 1fr 1fr; }
+    .grid-container.layout-3x4 { grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(4, 1fr); }
+    .grid-container.layout-4x4 { grid-template-columns: repeat(4, 1fr); grid-template-rows: repeat(4, 1fr); }
 
     /* Orchestrator: workers across the top (60%), one full-width orchestrator
        panel across the bottom (40%). The last panel is always the orchestrator.
@@ -370,6 +381,122 @@
     .term-panel.exited { opacity: 0.55; }
     .term-panel.exited .panel-terminal { pointer-events: none; }
 
+    /* ===== Sprint 65 T1: project-filter chips + ORCH pin + tile lifecycle =====
+       Brad's 2026-05-13 v2 spec (BACKLOG § D.5). Placed after the .term-panel
+       base + variants so .term-panel.panel--role-orch wins the cascade against
+       .term-panel:hover / .term-panel.exited (equal specificity → source order). */
+
+    /* 1.1 — project-filter chip row, above the grid. app.js leaves it empty
+       when there is only one project bucket (nothing worth filtering). */
+    .project-chips-row {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 6px;
+      padding: 6px 38px 0 6px;
+      flex-shrink: 0;
+    }
+    .project-chips-row:empty { display: none; }
+
+    .project-chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      font-family: var(--tg-mono);
+      font-size: 11px;
+      color: var(--tg-text-dim);
+      background: var(--tg-surface);
+      border: 1px solid var(--tg-border);
+      border-radius: 999px;
+      padding: 3px 11px;
+      cursor: pointer;
+      white-space: nowrap;
+      transition: color 0.1s, background 0.1s, border-color 0.1s;
+    }
+    .project-chip:hover {
+      color: var(--tg-text);
+      background: var(--tg-surface-hover);
+      border-color: var(--tg-border-active);
+    }
+    .project-chip.active {
+      color: var(--tg-accent);
+      border-color: var(--tg-accent);
+    }
+    .project-chip-count { font-size: 10px; opacity: 0.7; }
+
+    /* 1.1 — a tile hidden by the chip filter. display:none keeps the PTY +
+       xterm.js instance alive (no teardown); fitAll() / verifyLayoutHealth()
+       already skip display:none panels. Two classes → beats base .term-panel. */
+    .term-panel.panel--filtered-out { display: none; }
+
+    /* 1.2 — orchestrator pin row: above the chip row + grid. The orch tile is
+       always grid-column 1 for muscle-memory consistency; the row collapses to
+       zero height when no orchestrator panel exists. Right padding mirrors the
+       grid's 38px guide-rail reservation. */
+    .orch-pin-row {
+      display: grid;
+      grid-template-columns: minmax(280px, 1fr) 2fr;
+      gap: 6px;
+      height: clamp(180px, 24vh, 280px);
+      padding: 6px 38px 0 6px;
+      flex-shrink: 0;
+      box-sizing: border-box;
+    }
+    .orch-pin-row:empty { display: none; }
+
+    /* 1.2 — orchestrator panel: gold/amber border so the operator's primary
+       control surface is distinguishable at a glance (Brad's "from 6+ feet"
+       acceptance bar). */
+    .term-panel.panel--role-orch {
+      border: 2px solid var(--tg-accent-orch, #d4a017);
+      box-shadow: 0 0 0 1px rgba(212, 160, 23, 0.3);
+    }
+    .term-panel.panel--role-orch:hover {
+      border-color: var(--tg-accent-orch, #d4a017);
+    }
+    /* The ORCH text badge — prepended to the .panel-type slot so the header
+       reads "ORCH <type>". ORCH always wins the slot over the project label. */
+    .term-panel.panel--role-orch .panel-type::before {
+      content: "ORCH ";
+      font-weight: 700;
+      color: var(--tg-accent-orch, #d4a017);
+      margin-right: 4px;
+    }
+
+    /* 1.3 — a tile dimming out during the grace window before auto-removal. */
+    .term-panel.panel--exiting {
+      opacity: 0.5;
+      pointer-events: none;
+      transition: opacity 0.3s ease;
+    }
+
+    /* (c) — topbar terminal font-size stepper (Joshua's 2026-05-16 ask). */
+    .topbar-fontsize {
+      display: inline-flex;
+      align-items: center;
+      gap: 3px;
+      margin-right: 4px;
+    }
+    .font-step-btn {
+      background: var(--tg-surface);
+      border: 1px solid var(--tg-border);
+      color: var(--tg-text-dim);
+      font-family: var(--tg-mono);
+      font-size: 10px;
+      padding: 2px 6px;
+      border-radius: var(--tg-radius-sm);
+      cursor: pointer;
+      transition: color 0.1s, border-color 0.1s;
+    }
+    .font-step-btn:hover { color: var(--tg-text); border-color: var(--tg-border-active); }
+    .font-size-label {
+      font-family: var(--tg-mono);
+      font-size: 10px;
+      color: var(--tg-text-dim);
+      min-width: 14px;
+      text-align: center;
+    }
+
     /* --- Panel Header (metadata bar) --- */
     .panel-header {
       display: flex;

package/packages/server/src/database.js

@@ -66,7 +66,8 @@ function initDatabase(Database) {
       exit_code INTEGER,
       reason TEXT,
       theme TEXT DEFAULT 'tokyo-night',
-      theme_override TEXT
+      theme_override TEXT,
+      role TEXT
     );
 
     CREATE TABLE IF NOT EXISTS command_history (
@@ -137,6 +138,24 @@ function initDatabase(Database) {
     console.warn('[db] sessions.theme_override migration failed:', err.message);
   }
 
+  // Migration (Sprint 65 T2): add sessions.role for the explicit
+  // orchestrator/worker/reviewer/auditor panel-role flag (Brad's 2026-05-13
+  // v2 dashboard spec — Approach A). SQLite has no `ADD COLUMN IF NOT EXISTS`,
+  // so PRAGMA-check first — same pattern as the command_history.source and
+  // sessions.theme_override migrations above. No backfill: pre-Sprint-65 rows
+  // stay role=NULL (unroled), which is the correct default for sessions that
+  // pre-date the feature.
+  try {
+    const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+    const hasRole = cols.some((c) => c.name === 'role');
+    if (!hasRole) {
+      db.exec(`ALTER TABLE sessions ADD COLUMN role TEXT`);
+      console.log("[db] Migrated sessions: added 'role' column");
+    }
+  } catch (err) {
+    console.warn('[db] sessions.role migration failed:', err.message);
+  }
+
   // Migration (v0.7.0): drop the dead projects.default_theme column. It was
   // CREATE'd in early v0.1 but was never read or written by any code path
   // (see Sprint 32 T1 grep). Removing it eliminates a latent contract-drift

package/packages/server/src/index.js

@@ -150,6 +150,15 @@ const SECRETS_EXCLUDED_FROM_PTY = new Set([
   'NPM_TOKEN',
 ]);
 
+// Sprint 65 T2 (2.1) — explicit operator-role whitelist for the optional
+// `role` field on POST /api/sessions (Brad's 2026-05-13 v2 dashboard spec,
+// Approach A). `null` is the valid "unroled" value; an absent field also
+// defaults to null. The dashboard renders the ORCH pin when
+// `meta.role === 'orchestrator'`; worker/reviewer/auditor are accepted now
+// for forward-compat with the canonical 3+1+1 role taxonomy. Unknown values
+// are rejected with 400 at the route. Exported for the route-fence test.
+const ALLOWED_SESSION_ROLES = ['orchestrator', 'worker', 'reviewer', 'auditor', null];
+
 function readTermdeckSecretsForPty() {
   if (_termdeckSecretsCache !== null) return _termdeckSecretsCache;
   const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
@@ -1240,7 +1249,15 @@ function createServer(config) {
 
   // GET /api/sessions - list all active sessions
   app.get('/api/sessions', (req, res) => {
-    res.json(sessions.getAll());
+    // Sprint 65 T2 (2.2) — exited (dead-PTY) sessions are excluded by default
+    // so an orchestrator polling this endpoint doesn't see dead panels as
+    // live (Brad's "18 windows open, 10 were dead codex cli" — BACKLOG § D.5).
+    // `?includeExited=true` returns the legacy full shape for `termdeck
+    // doctor` + debug tooling. The 2s status_broadcast is intentionally NOT
+    // filtered (it calls bare getAll()) so the dashboard's missed-exit
+    // reconciliation still has exited sessions to work from.
+    const includeExited = req.query.includeExited === 'true';
+    res.json(sessions.getAll({ includeExited }));
   });
 
   // Reusable PTY spawn + wire helper. Used by POST /api/sessions and the
@@ -1248,7 +1265,7 @@ function createServer(config) {
   // the same wiring (transcripts, RAG, Mnestra flashback) without copy-paste.
   // Returns the Session object regardless of PTY success — status will be
   // 'errored' if pty.spawn threw.
-  function spawnTerminalSession({ command, cwd, project, label, type, theme, reason }) {
+  function spawnTerminalSession({ command, cwd, project, label, type, theme, reason, role }) {
     const rawCwd = cwd || config.projects?.[project]?.path || os.homedir();
     const resolvedCwd = path.resolve(rawCwd.replace(/^~/, os.homedir()));
 
@@ -1259,7 +1276,10 @@ function createServer(config) {
       command: command || config.shell,
       cwd: resolvedCwd,
       theme: theme || config.projects?.[project]?.defaultTheme || config.defaultTheme,
-      reason: reason || 'launched via API'
+      reason: reason || 'launched via API',
+      // Sprint 65 T2 (2.1) — explicit operator role. Route validation has
+      // already rejected unknown values; here `undefined`/`null` → null.
+      role: role || null,
     });
 
     if (pty) {
@@ -1468,6 +1488,10 @@ function createServer(config) {
         term.onExit(({ exitCode, signal }) => {
           session.meta.status = 'exited';
           session.meta.exitCode = exitCode;
+          // Sprint 65 T2 (2.4) — stamp the exit timestamp so the panel_exited
+          // WS frame (below) and the 410 body on POST .../input can both
+          // report when the panel died.
+          session.meta.exitedAt = new Date().toISOString();
           session.meta.statusDetail = `Exited (${exitCode})${signal ? `, signal ${signal}` : ''}`;
 
           if (session.ws && session.ws.readyState === 1) {
@@ -1478,6 +1502,32 @@ function createServer(config) {
             }));
           }
 
+          // Sprint 65 T2 (2.4) — broadcast panel_exited to ALL dashboard WS
+          // clients so the grid can auto-remove the dead tile (Brad's
+          // 2026-05-12 item 2b — CLI panels must auto-close on PTY exit).
+          // Distinct from the `exit` frame above, which targets ONLY this
+          // panel's own socket; panel_exited goes to every connected client
+          // because any of them may be rendering this tile in its grid.
+          // Inlined wss.clients broadcast — same idiom as status_broadcast /
+          // config_changed / projects_changed elsewhere in this file.
+          try {
+            const exitPayload = JSON.stringify({
+              type: 'panel_exited',
+              sessionId: session.id,
+              exitCode,
+              signal: signal || null,
+              exitedAt: session.meta.exitedAt,
+            });
+            wss.clients.forEach((client) => {
+              if (client.readyState === 1) {
+                try { client.send(exitPayload); }
+                catch (err) { console.error('[ws] panel_exited send failed:', err); }
+              }
+            });
+          } catch (err) {
+            console.error('[ws] panel_exited broadcast failed:', err);
+          }
+
           rag.onSessionEnded(session);
 
           // Fire-and-forget session log (T2.5)
@@ -1663,8 +1713,17 @@ function createServer(config) {
 
   // POST /api/sessions - create a new terminal session
   app.post('/api/sessions', (req, res) => {
-    const { command, cwd, project, label, type, theme, reason } = req.body || {};
-    const session = spawnTerminalSession({ command, cwd, project, label, type, theme, reason });
+    const { command, cwd, project, label, type, theme, reason, role } = req.body || {};
+    // Sprint 65 T2 (2.1) — validate the optional explicit operator-role flag
+    // (Approach A). An absent field (`undefined`) is fine — it defaults to
+    // null in spawnTerminalSession. Any present value must be in the
+    // whitelist (case-sensitive exact match; `null` is allowed). Unknown
+    // values are a 400 so a typo'd role surfaces immediately rather than
+    // silently rendering as an unroled panel.
+    if (role !== undefined && !ALLOWED_SESSION_ROLES.includes(role)) {
+      return res.status(400).json({ ok: false, code: 'invalid_role', allowed: ALLOWED_SESSION_ROLES });
+    }
+    const session = spawnTerminalSession({ command, cwd, project, label, type, theme, reason, role });
     res.status(201).json(session.toJSON());
   });
 
@@ -1729,8 +1788,25 @@ function createServer(config) {
   app.post('/api/sessions/:id/input', (req, res) => {
     const session = sessions.get(req.params.id);
     if (!session) return res.status(404).json({ error: 'Session not found' });
+    // Sprint 65 T2 (2.3) — inject to a dead panel returns 410 Gone, not the
+    // pre-Sprint-65 silent 404. The orchestrator POSTing to an exited panel
+    // (Brad's D.5 item 3 — "10 dead codex cli") got a 404 that reads as
+    // "session never existed"; 410 = "the resource was here, has been
+    // intentionally removed" — the semantically correct + debuggable signal.
+    // Mirrors POST /api/sessions/:id/resize (Sprint 63). The body carries
+    // `error` (backward-compat with the client api()/sendReply() path that
+    // treats a missing `.error` as success — T4-CODEX 19:44) AND `code`
+    // (programmatic discriminator) AND `ok:false`.
     if (session.meta.status === 'exited' || !session.pty) {
-      return res.status(404).json({ error: 'Session is exited' });
+      const msg = `Panel ${req.params.id} has exited`;
+      return res.status(410).json({
+        ok: false,
+        code: 'panel_exited',
+        error: msg,
+        message: msg,
+        exitCode: session.meta.exitCode ?? null,
+        exitedAt: session.meta.exitedAt || null,
+      });
     }
 
     const { text, source, fromSessionId } = req.body || {};
@@ -2972,6 +3048,8 @@ module.exports = {
   // Sprint 64 T1 (ORCH SCOPE 16:29 item 4) — management-token exclusion list.
   // Exported for `packages/cli/tests/spawn-env-exclusion.test.js` fence.
   SECRETS_EXCLUDED_FROM_PTY,
+  // Sprint 65 T2 (2.1) — operator-role whitelist, exported for the route fence.
+  ALLOWED_SESSION_ROLES,
   // Sprint 50 T1 — exported for unit testing the per-agent SessionEnd
   // hook trigger (skip-claude, no-transcript, no-hook-installed,
   // payload shape, fire-and-forget).

package/packages/server/src/session.js

@@ -162,6 +162,13 @@ class Session {
     this.meta = {
       type: options.type || 'shell',        // shell, claude-code, gemini, python-server, one-shot
       project: options.project || null,
+      // Sprint 65 T2 (2.1) — explicit operator role (Approach A). One of
+      // orchestrator / worker / reviewer / auditor / null. Set at spawn time
+      // via POST /api/sessions (route-validated against ALLOWED_SESSION_ROLES);
+      // flows through status_broadcast unchanged so the dashboard can pin the
+      // ORCH panel. Distinct from `type` (the agent CLI) — role is operator
+      // intent, type is the running program.
+      role: options.role || null,
       label: options.label || '',
       command: options.command || '',
       cwd: options.cwd || os.homedir(),
@@ -575,8 +582,8 @@ class SessionManager {
     //                     a PATCH from the dropdown sets it (see updateMeta).
     if (this.db) {
       this.db.prepare(`
-        INSERT INTO sessions (id, type, project, label, command, cwd, created_at, reason, theme, theme_override)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO sessions (id, type, project, label, command, cwd, created_at, reason, theme, theme_override, role)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         session.id,
         session.meta.type,
@@ -587,7 +594,8 @@ class SessionManager {
         session.meta.createdAt,
         session.meta.reason,
         session.meta.theme,           // resolved snapshot, legacy column
-        session.theme_override        // NULL by default
+        session.theme_override,       // NULL by default
+        session.meta.role             // Sprint 65 T2 — operator role, NULL by default
       );
     }
 
@@ -599,8 +607,20 @@ class SessionManager {
     return this.sessions.get(id);
   }
 
-  getAll() {
-    return Array.from(this.sessions.values()).map(s => s.toJSON());
+  // Sprint 65 T2 (2.2) — `opts.includeExited` controls whether PTY-exited
+  // sessions appear in the listing. Default is legacy (include everything):
+  // the 2s status_broadcast (index.js:2675) and the projects-route live-PTY
+  // guard both call bare getAll() and must keep seeing the full set. Only
+  // GET /api/sessions opts into the filtered view (default on at the route).
+  // Brad's "18 windows open, 10 were dead codex cli" report (BACKLOG § D.5)
+  // is the orchestrator polling /api/sessions and seeing dead panels as live.
+  getAll(opts = {}) {
+    const all = Array.from(this.sessions.values());
+    const includeExited = opts.includeExited !== false;
+    const visible = includeExited
+      ? all
+      : all.filter((s) => s.meta.status !== 'exited');
+    return visible.map((s) => s.toJSON());
   }
 
   // Fields a client is allowed to modify via PATCH /api/sessions/:id.