@hanzlaa/rcode 4.1.1 → 4.3.0

package/server/lib/html/client/components/dashboard/ProjectHealth.js

@@ -0,0 +1,80 @@
+/**
+ * ProjectHealth — progress mini-card used by the Sidebar.
+ *
+ * Reads `health { pct, label, points[] }` from the store. The scanner now
+ * emits real values only: pct is the story-completion percentage (null when
+ * nothing is tracked yet — shown as "—"), label is the real blocker count or
+ * "Not started", and points exist only when the project has recorded
+ * velocity_history. No sample fallback, no invented composite score.
+ * See .planning/campaign/DATA-CONTRACT.md. Reads store only — no fetch.
+ *
+ * No inline style= attributes — all styling via .phealth-* classes in css.js.
+ */
+
+import { html } from '../../preact.js';
+import { useStore } from '../../store.js';
+
+/**
+ * Tone class — driven by the real blocker count, not an invented score.
+ * Neutral when nothing is tracked yet.
+ */
+function healthTone(pct, blockerCount) {
+  if (pct == null) return 'phealth--none';
+  if (blockerCount >= 2) return 'phealth--risk';
+  if (blockerCount === 1) return 'phealth--warn';
+  return 'phealth--good';
+}
+
+/**
+ * Build an SVG polyline `points` string for the sparkline from a value series.
+ * Maps values into a 0..W × 0..H box, flipping Y so higher values sit higher.
+ */
+function sparkPoints(points, w, h) {
+  if (!points.length) return '';
+  const values = points.map(p => Number(p.value) || 0);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const span = max - min || 1;
+  const step = points.length > 1 ? w / (points.length - 1) : 0;
+  return values
+    .map((v, i) => {
+      const x = i * step;
+      const y = h - ((v - min) / span) * h;
+      return `${x.toFixed(1)},${y.toFixed(1)}`;
+    })
+    .join(' ');
+}
+
+export function ProjectHealth() {
+  const S = useStore();
+  const health = (S && S.health) || {};
+  const blockerCount = Array.isArray(S.blockers) ? S.blockers.length : 0;
+  const hasPct = typeof health.pct === 'number';
+  const pct = hasPct ? Math.max(0, Math.min(100, Math.round(health.pct))) : null;
+  const label = health.label || (hasPct ? '' : 'Not tracked');
+  const points = Array.isArray(health.points) ? health.points : [];
+  const tone = healthTone(pct, blockerCount);
+
+  const W = 180;
+  const H = 36;
+  // Sparkline only from real recorded velocity — 2+ points or nothing.
+  const line = points.length >= 2 ? sparkPoints(points, W, H) : '';
+  // Close the polygon down to the baseline for a soft area fill.
+  const area = line ? `0,${H} ${line} ${W},${H}` : '';
+
+  return html`
+    <section class=${'phealth ' + tone}>
+      <p class="phealth-title">Progress</p>
+      <div class="phealth-head">
+        <span class="phealth-pct">${pct != null ? pct : '—'}${pct != null ? html`<span class="phealth-pct-sign">%</span>` : null}</span>
+        <span class="phealth-label">${label}</span>
+      </div>
+      ${line ? html`
+        <svg class="phealth-spark" viewBox=${'0 0 ' + W + ' ' + H} preserveAspectRatio="none" aria-hidden="true">
+          <polygon class="phealth-spark-area" points=${area} />
+          <polyline class="phealth-spark-line" points=${line} />
+        </svg>
+      ` : null}
+    </section>
+  `;
+}

package/server/lib/html/client/components/dashboard/RecentDecisions.js

@@ -0,0 +1,57 @@
+/**
+ * RecentDecisions — Overview redesign, Row 3 Card 1 (Recent Decisions list).
+ *
+ * "Recent Decisions" card + "View all" link. Each row is a decision title with
+ * a status badge (only when the decision actually records a status — no
+ * default "Approved") and the date on the right. An empty array renders an
+ * honest "No decisions recorded yet" state, never sample data.
+ * See .planning/campaign/DATA-CONTRACT.md. Reads props/store only — no fetch.
+ */
+
+import { html } from '../../preact.js';
+import { useStore } from '../../store.js';
+import { humanDate, rowLink } from '../../util.js';
+
+// Map a free-form status string to a badge modifier class.
+function statusClass(status) {
+  const s = String(status || '').toLowerCase();
+  if (s === 'approved') return 'rd-badge--approved';
+  if (s === 'rejected') return 'rd-badge--rejected';
+  return 'rd-badge--proposed';
+}
+
+export function RecentDecisions() {
+  const S = useStore();
+  const decisions = Array.isArray(S.decisions) ? S.decisions : [];
+
+  return html`
+    <section class="dash-card">
+      <div class="rd-head">
+        <p class="dash-card-title">Recent Decisions</p>
+        <button class="rd-viewall" onClick=${() => { location.hash = 'decisions'; }}>
+          View all
+        </button>
+      </div>
+      ${decisions.length === 0
+        ? html`
+          <div class="dash-empty">
+            <span>No decisions recorded yet</span>
+            <code class="dash-empty-hint">/rcode-council</code>
+          </div>
+        `
+        : html`
+          <ul class="rd-list">
+            ${decisions.map((d, i) => html`
+              <li class="rd-row ovr-link" key=${d.title + i} ...${rowLink('decisions')}>
+                <span class="rd-title">${d.title}</span>
+                ${d.status
+                  ? html`<span class=${'rd-badge ' + statusClass(d.status)}>${d.status}</span>`
+                  : html`<span class="rd-status-none">—</span>`}
+                <span class="rd-date">${humanDate(d.date) || ''}</span>
+              </li>
+            `)}
+          </ul>
+        `}
+    </section>
+  `;
+}

package/server/lib/html/client/components/dashboard/Timeline.js

@@ -0,0 +1,143 @@
+/**
+ * Timeline — Overview redesign, Row 1 Card 3.
+ *
+ * Target-launch card. With a configured launch date: countdown + a velocity
+ * sparkline drawn only from real recorded `velocity_history` + the real
+ * open-blocker count. Without one, the dead space becomes a "Milestone
+ * outlook": current milestone name, phases done/total, latest recorded
+ * velocity, and a hint that launch_date in .rcode/config.yaml enables the
+ * countdown — never a projected/invented date.
+ *
+ * Reads the `timeline { launchDate, onTrack, points[] }` slice plus
+ * `blockers`, `milestone`, and `phases` from the store. See DATA-CONTRACT.md.
+ * No fetch.
+ */
+
+import { html } from '../../preact.js';
+import { useStore } from '../../store.js';
+
+// SVG viewBox geometry for the sparkline.
+const VW = 280;
+const VH = 88;
+const PAD_X = 8;
+const PAD_Y = 12;
+
+/** Days from today until the launch date (>= 0; null when unparseable). */
+function daysUntil(launchDate) {
+  const target = new Date(launchDate);
+  if (isNaN(target.getTime())) return null;
+  const now = new Date();
+  const ms = target.setHours(0, 0, 0, 0) - now.setHours(0, 0, 0, 0);
+  return Math.max(0, Math.round(ms / 86400000));
+}
+
+/** Human display of an ISO date, falling back to the raw string. */
+function displayDate(launchDate) {
+  const d = new Date(launchDate);
+  if (isNaN(d.getTime())) return launchDate;
+  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+
+/** Map a value series to evenly-spaced SVG coordinates (y inverted). */
+function toCoords(points) {
+  const values = points.map(p => Number(p.value) || 0);
+  const max = Math.max(...values, 1);
+  const min = Math.min(...values, 0);
+  const span = max - min || 1;
+  const innerW = VW - PAD_X * 2;
+  const innerH = VH - PAD_Y * 2;
+  const step = points.length > 1 ? innerW / (points.length - 1) : 0;
+  return values.map((v, i) => ({
+    x: PAD_X + step * i,
+    y: PAD_Y + innerH - ((v - min) / span) * innerH,
+  }));
+}
+
+export function Timeline() {
+  const S = useStore();
+  const timeline = (S && S.timeline) || {};
+  const points = Array.isArray(timeline.points) ? timeline.points : [];
+  const blockers = Array.isArray(S.blockers) ? S.blockers : [];
+
+  const hasDate = !!timeline.launchDate;
+  const days = hasDate ? daysUntil(timeline.launchDate) : null;
+  const daysLine = days == null ? 'Launch scheduled' : `In ${days} day${days === 1 ? '' : 's'}`;
+
+  let chart = null;
+  if (points.length >= 2) {
+    const coords = toCoords(points);
+    const linePath = coords.map((c, i) => `${i === 0 ? 'M' : 'L'} ${c.x.toFixed(1)} ${c.y.toFixed(1)}`).join(' ');
+    const areaPath = `${linePath} L ${coords[coords.length - 1].x.toFixed(1)} ${VH - PAD_Y} L ${coords[0].x.toFixed(1)} ${VH - PAD_Y} Z`;
+    chart = html`
+      <svg class="tl-chart" viewBox=${`0 0 ${VW} ${VH}`} preserveAspectRatio="none" role="img"
+        aria-label="Recorded sprint velocity trend">
+        <defs>
+          <linearGradient id="tlFill" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0%" stop-color="var(--dash-teal)" stop-opacity="0.22"/>
+            <stop offset="100%" stop-color="var(--dash-teal)" stop-opacity="0"/>
+          </linearGradient>
+        </defs>
+        <path class="tl-area" d=${areaPath} fill="url(#tlFill)"/>
+        <path class="tl-line" d=${linePath} fill="none" stroke="var(--dash-teal)"
+          stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+        ${coords.map(c => html`
+          <circle class="tl-dot" cx=${c.x.toFixed(1)} cy=${c.y.toFixed(1)} r="3"
+            fill="var(--dash-bg)" stroke="var(--dash-teal)" stroke-width="2"/>
+        `)}
+      </svg>
+    `;
+  } else {
+    chart = html`<div class="tl-nochart">${points.length === 1 ? 'Not enough velocity history to chart yet' : 'No velocity history recorded'}</div>`;
+  }
+
+  const blockerNote = blockers.length
+    ? `${blockers.length} open blocker${blockers.length === 1 ? '' : 's'}`
+    : 'No open blockers';
+
+  const footer = html`
+    <div class="tl-footer">
+      <span class=${'tl-status' + (blockers.length ? ' tl-status-risk' : '')}>
+        <span class="tl-dot-badge"></span>${blockerNote}
+      </span>
+    </div>
+  `;
+
+  if (!hasDate) {
+    // No launch date configured — show a milestone outlook built from real
+    // store data instead of a dead "—" date.
+    const phases = Array.isArray(S.phases) ? S.phases : [];
+    const phasesDone = phases.filter(p => String(p.state).toLowerCase() === 'done').length;
+    const latest = points.length ? points[points.length - 1] : null;
+    return html`
+      <section class="dash-card tl-card">
+        <p class="dash-card-sub tl-label">Milestone Outlook</p>
+        <p class="tl-outlook-name">${S.milestone || 'No milestone set'}</p>
+        <ul class="tl-outlook">
+          <li class="tl-outlook-row">
+            <span class="tl-outlook-key">Phases</span>
+            <span class="tl-outlook-val">${phases.length ? `${phasesDone}/${phases.length} done` : 'None planned'}</span>
+          </li>
+          <li class="tl-outlook-row">
+            <span class="tl-outlook-key">Latest velocity</span>
+            <span class="tl-outlook-val">${latest ? `${latest.value} pts (${latest.label})` : 'Not recorded'}</span>
+          </li>
+        </ul>
+        ${chart}
+        <p class="tl-outlook-hint">Set <code>launch_date</code> in <code>.rcode/config.yaml</code> to track a launch countdown</p>
+        ${footer}
+      </section>
+    `;
+  }
+
+  return html`
+    <section class="dash-card tl-card">
+      <p class="dash-card-sub tl-label">Target Launch</p>
+      <p class="tl-date">${displayDate(timeline.launchDate)}</p>
+      <p class="tl-days">${daysLine}</p>
+
+      ${chart}
+
+      ${footer}
+    </section>
+  `;
+}

package/server/lib/html/client/components/shared.js

@@ -8,11 +8,14 @@
  */
 
 import { html, useState } from '../preact.js';
-import { pctNum, chip as chipDesc, humanDate, pct } from '../util.js';
+import { pctNum, chip as chipDesc, humanDate, pct, currentPhaseId } from '../util.js';
 import {
-  runAndOpenTerm, isSessionRunning, runningInSprint, runningInPhase,
+  isSessionRunning, runningInSprint, runningInPhase,
 } from '../orchestrator.js';
+import { getState } from '../store.js';
 import { Icon } from '../icons-client.js';
+import { TaskPipeline } from './TaskPipeline.js';
+import { openRunnerPicker } from './RunnerPicker.js';
 
 // ---- Toast helper (shared by CmdHint copy action and any view) ----
 export function showToast(msg) {
@@ -23,6 +26,29 @@ export function showToast(msg) {
   setTimeout(() => el.classList.remove('show'), 2000);
 }
 
+// ---- pressable ----
+/**
+ * Spreadable props that make a clickable non-button element keyboard
+ * accessible: focusable, announced as a button, activated by Enter/Space.
+ * Usage: html`<div class="item item-clickable" ...${pressable(fn)}>…</div>`
+ */
+export function pressable(onActivate) {
+  return {
+    role: 'button',
+    tabindex: 0,
+    onClick: onActivate,
+    onKeyDown: (e) => {
+      // Ignore keydown bubbling up from nested interactive elements
+      // (e.g. a Run button inside a clickable card row).
+      if (e.target !== e.currentTarget) return;
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        onActivate(e);
+      }
+    },
+  };
+}
+
 // ---- Chip ----
 /**
  * Status chip.
@@ -119,7 +145,7 @@ export function CmdHint({ cmd, desc }) {
       });
   }
   return html`
-    <div class="cmd-hint-item" onClick=${handleClick}>
+    <div class="cmd-hint-item" ...${pressable(handleClick)}>
       <span class="cmd-text">${cmd}</span>
       <span class="cmd-desc">${desc}</span>
       <${Icon} name="copy" size=${14} cls="cmd-copy"/>
@@ -145,16 +171,22 @@ export function CmdHints({ hints }) {
 
 // ---- RunBtn ----
 /**
- * Compact run button. Calls runAndOpenTerm from orchestrator.js.
+ * Compact run button. Opens the runner/model picker popover anchored to the
+ * button; the picker launches the session via runAndOpenTerm.
  * @param {{ storyId: string, cmd: string, label: string }} props
  */
 export function RunBtn({ storyId, cmd, label }) {
+  // Plain read (not a subscription) — every parent view already re-renders
+  // on store changes, so the disabled state stays current with the 4s poll.
+  const down = getState().orchOnline === false;
   function handleClick(e) {
     e.stopPropagation();
-    runAndOpenTerm(storyId, cmd, label);
+    openRunnerPicker(e.currentTarget, { kind: 'session', storyId, cmd, title: label });
   }
   return html`
-    <button class="card-run-btn" title=${'Run ' + label} onClick=${handleClick}>
+    <button class="card-run-btn" disabled=${down}
+      title=${down ? 'Orchestrator unreachable' : 'Run ' + label}
+      onClick=${handleClick}>
       ▶ Run
     </button>
   `;
@@ -180,12 +212,14 @@ export function PhaseCard({ phase: p, S }) {
   const sps = p.sprints || [];
   const stories = sps.flatMap(s => s.stories || []);
   const done = stories.filter(t => t.status === 'done' || t.status === 'completed').length;
-  const isCur = String(p.id) === String(S && S.currentPhase);
+  // currentPhase is the contract object (or legacy string) — compare by id.
+  const cpId = currentPhaseId(S && S.currentPhase);
+  const isCur = cpId !== '' && String(p.id) === cpId;
   const running = runningInPhase(p);
   const borderStyle = isCur ? 'border-left-color:var(--accent-amber)' : '';
   return html`
     <div class=${'item item-clickable'} style=${borderStyle}
-      onClick=${() => { location.hash = 'phases/' + p.id; }}>
+      ...${pressable(() => { location.hash = 'phases/' + p.id; })}>
       <div class="item-title">
         ${sps.length ? html`<${RunBtn} storyId=${'phase-' + p.id} cmd=${'/rcode-execute ' + p.id} label=${'Phase ' + p.id}/>` : null}
         Phase ${p.id} — ${p.name}
@@ -232,7 +266,7 @@ export function SprintCard({ sprint: s, S }) {
     : '';
   return html`
     <div class=${'item item-clickable' + (isCur ? ' sprint-current' : '')} style=${borderStyle}
-      onClick=${() => { location.hash = 'sprints/' + s.id; }}>
+      ...${pressable(() => { location.hash = 'sprints/' + s.id; })}>
       <div class="item-title">
         <${RunBtn} storyId=${'sprint-' + s.id} cmd=${'/rcode-execute-sprint ' + s.id} label=${'Sprint ' + s.id}/>
         Sprint ${s.id} — ${s.goal || 'No goal'}
@@ -290,7 +324,8 @@ export function TaskCard({ task: t }) {
   return html`
     <div class="item item-clickable" data-status=${t.status || ''}
       style=${done ? 'opacity:.65' : ''}
-      onClick=${() => setExpanded(e => !e)}>
+      aria-expanded=${expanded}
+      ...${pressable(() => setExpanded(e => !e))}>
       <div class="item-title" style=${done ? 'text-decoration:line-through' : ''}>
         ${t.id && !done ? html`<${RunBtn} storyId=${t.id} cmd=${'/rcode-dev-story ' + t.id} label=${'Story ' + t.id}/>` : null}
         ${done ? '✓ ' : ''}${t.title}
@@ -302,7 +337,8 @@ export function TaskCard({ task: t }) {
         ${t.id ? html`<${Tag}>${t.id}</${Tag}>` : null}
         ${t.sprintId ? html`<${Tag}>Sprint ${t.sprintId}</${Tag}>` : null}
         ${t.phaseId ? html`<${Tag}>Phase ${t.phaseId}</${Tag}>` : null}
-        ${t.id && running ? html`<span class="run-badge">● running</span>` : null}
+        ${t.id && running ? html`<span class="run-badge"><span class="live-dot"></span>running</span>` : null}
+        <${TaskPipeline} task=${t} running=${t.id && running}/>
       </div>
       ${expanded ? html`
         <div class="task-detail">

package/server/lib/html/client/filter-state.js

@@ -0,0 +1,72 @@
+/**
+ * filter-state.js — URL hash query-string filter module.
+ *
+ * This module owns the `?status=&milestone=&date=` filter query portion of
+ * location.hash ONLY. It never touches the `view` or `subId` path segments.
+ *
+ * Hash shape: `#view/subId?status=done&milestone=M3&date=2026-05`
+ *   - The path segment (`view/subId`) is managed by App.js parseHash.
+ *   - The query segment (`status=...`) is managed here.
+ *
+ * Recognised filter keys: `status`, `milestone`, `date`. All others are ignored.
+ */
+
+const FILTER_KEYS = ['status', 'milestone', 'date'];
+
+/**
+ * Parse filter state from a raw hash string.
+ *
+ * @param {string} hash — raw hash string (with or without leading `#`).
+ * @returns {{ status: string, milestone: string, date: string }} — each value
+ *   is a string or `''` when absent. Never throws on malformed input.
+ */
+export function parseFilters(hash) {
+  const result = { status: '', milestone: '', date: '' };
+  try {
+    const raw = typeof hash === 'string' ? hash.replace(/^#/, '') : '';
+    const qIdx = raw.indexOf('?');
+    if (qIdx === -1) return result;
+    const queryStr = raw.slice(qIdx + 1);
+    const params = new URLSearchParams(queryStr);
+    for (const key of FILTER_KEYS) {
+      const val = params.get(key);
+      if (val !== null) result[key] = val;
+    }
+  } catch {
+    // Malformed input — return all-empty object.
+  }
+  return result;
+}
+
+/**
+ * Serialise a filter object into a query string.
+ *
+ * @param {{ status: string, milestone: string, date: string }} filters
+ * @returns {string} — query string WITHOUT a leading `?`. Empty string when no
+ *   active filter. Keys are always appended in fixed order: status, milestone, date.
+ */
+export function serialiseFilters(filters) {
+  const params = new URLSearchParams();
+  for (const key of FILTER_KEYS) {
+    const val = filters?.[key];
+    if (typeof val === 'string' && val !== '') {
+      params.append(key, val);
+    }
+  }
+  return params.toString();
+}
+
+/**
+ * Build a full hash body from a view path and filter object.
+ *
+ * Used by FilterChips (34.2) to update `location.hash` without disturbing
+ * the view path segment.
+ *
+ * @param {string} viewPath — view path segment, e.g. `phases` or `sprints/3`.
+ * @param {{ status: string, milestone: string, date: string }} filters
+ * @returns {string} — hash body: `viewPath` or `viewPath?query`.
+ */
+export function applyFilters(viewPath, filters) {
+  const query = serialiseFilters(filters);
+  return query ? `${viewPath}?${query}` : viewPath;
+}

package/server/lib/html/client/icons-client.js

@@ -34,6 +34,7 @@ export const ICONS = {
   minimize:    '<line x1="5" y1="14" x2="19" y2="14"/>',
   maximize:    '<path d="M8 3H5a2 2 0 0 0-2 2v3"/><path d="M21 8V5a2 2 0 0 0-2-2h-3"/><path d="M3 16v3a2 2 0 0 0 2 2h3"/><path d="M16 21h3a2 2 0 0 0 2-2v-3"/>',
   clock:       '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
+  history:     '<path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/><path d="M12 7v5l4 2"/>',
   eye:         '<path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7z"/><circle cx="12" cy="12" r="3"/>',
   filePen:     '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h7"/><polyline points="14 2 14 8 20 8"/><path d="M18.4 12.6a2 2 0 0 1 3 3L17 20l-4 1 1-4z"/>',
   hourglass:   '<path d="M5 22h14M5 2h14M17 22v-4.17a2 2 0 0 0-.59-1.42L12 12l-4.41 4.41A2 2 0 0 0 7 17.83V22M7 2v4.17a2 2 0 0 0 .59 1.42L12 12l4.41-4.41A2 2 0 0 0 17 6.17V2"/>',
@@ -54,6 +55,12 @@ export const ICONS = {
   // Added in sprint 32.3 — App/Topbar theme toggle icons
   moon:            '<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>',
   sun:             '<circle cx="12" cy="12" r="4"/><line x1="12" y1="2" x2="12" y2="6"/><line x1="12" y1="18" x2="12" y2="22"/><line x1="4.22" y1="4.22" x2="7.05" y2="7.05"/><line x1="16.95" y1="16.95" x2="19.78" y2="19.78"/><line x1="2" y1="12" x2="6" y2="12"/><line x1="18" y1="12" x2="22" y2="12"/><line x1="4.22" y1="19.78" x2="7.05" y2="16.95"/><line x1="16.95" y1="7.05" x2="19.78" y2="4.22"/>',
+
+  // Added in sprint 36.1 — command palette search icon
+  search:          '<circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/>',
+
+  // Blocked-session notifications — topbar bell
+  bell:            '<path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9"/><path d="M10.3 21a1.94 1.94 0 0 0 3.4 0"/>',
 };
 
 /**

package/server/lib/html/client/notify.js

@@ -0,0 +1,75 @@
+/**
+ * notify.js — blocked-session notification tracker.
+ *
+ * Pure logic, no DOM. The 4s session poll (orchestrator.js _poll) calls
+ * trackBlocked(sessions) after each tick. This module diffs the blocked set
+ * against the previous tick and writes store.blockedAlerts — the persistent
+ * clickable toasts rendered by components/NotifyCenter.js.
+ *
+ * Browser Notification API is used ONLY when permission is already granted;
+ * we never call Notification.requestPermission().
+ */
+
+import { getState, setState } from './store.js';
+
+// storyIds that were blocked on the previous poll tick — transition detector.
+let _prevBlocked = new Set();
+
+/** True when the browser Notification API is usable without prompting. */
+function notificationsGranted() {
+  return typeof window !== 'undefined'
+    && 'Notification' in window
+    && window.Notification.permission === 'granted';
+}
+
+/** Fire a system notification for a newly-blocked session (granted-only). */
+function systemNotify(storyId) {
+  if (!notificationsGranted()) return;
+  try {
+    new window.Notification('Agent waiting for input', {
+      body: 'Session ' + storyId + ' is blocked on a question.',
+      tag: 'rcode-blocked-' + storyId, // dedupe: re-fires replace, not stack
+    });
+  } catch { /* notification constructor can throw in some embeds — ignore */ }
+}
+
+/**
+ * Diff the latest session list against the previous tick:
+ *   - session newly blocked  → append a persistent alert + system notification
+ *   - session left blocked   → drop its alert (answered / exited / stopped)
+ * Alerts: [{ storyId, cmd }] in store.blockedAlerts.
+ */
+export function trackBlocked(sessions) {
+  const nowBlocked = new Map();
+  for (const s of sessions || []) {
+    if (s.status === 'blocked') nowBlocked.set(s.storyId, s);
+  }
+
+  const alerts = (getState().blockedAlerts || [])
+    // Drop alerts for sessions that are no longer blocked.
+    .filter(a => nowBlocked.has(a.storyId));
+
+  let changed = alerts.length !== (getState().blockedAlerts || []).length;
+
+  for (const [storyId, s] of nowBlocked) {
+    if (_prevBlocked.has(storyId)) continue;            // already known
+    if (alerts.some(a => a.storyId === storyId)) continue; // already alerted
+    alerts.push({ storyId, cmd: s.cmd || '' });
+    systemNotify(storyId);
+    changed = true;
+  }
+
+  _prevBlocked = new Set(nowBlocked.keys());
+  if (changed) setState({ blockedAlerts: alerts });
+}
+
+/** Dismiss one alert toast without touching the session. */
+export function dismissBlockedAlert(storyId) {
+  const alerts = (getState().blockedAlerts || []).filter(a => a.storyId !== storyId);
+  setState({ blockedAlerts: alerts });
+}
+
+/** Sessions currently blocked (drives the topbar bell). */
+export function blockedSessions() {
+  return (getState().activeSessions || []).filter(s => s.status === 'blocked');
+}