@worca/ui 0.30.0 → 0.32.0

package/app/styles.css

@@ -766,6 +766,13 @@ h1, h2, h3, h4, h5, h6 {
   to { transform: rotate(360deg); }
 }
 
+.effort-zap-icon {
+  width: 12px;
+  height: 12px;
+  vertical-align: -1px;
+  margin-right: 2px;
+}
+
 /* --- 13. Stage Connector --- */
 .stage-connector {
   width: 36px;
@@ -2418,6 +2425,13 @@ sl-details.agent-prompt-section::part(content) {
   margin-bottom: 12px;
 }
 
+/* Divider + gap before the user message header */
+.agent-prompt-block + .agent-prompt-block {
+  margin-top: 18px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border-subtle);
+}
+
 .agent-prompt-label-row {
   display: flex;
   align-items: center;
@@ -2448,12 +2462,14 @@ sl-details.agent-prompt-section::part(content) {
   flex-shrink: 0;
 }
 
+/* Accent the section headers (not the message bodies) so each block reads as
+   a labelled section; the bodies stay neutral. */
 .agent-prompt-label {
-  font-size: 11px;
-  font-weight: 600;
-  color: var(--muted);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--accent);
   text-transform: uppercase;
-  letter-spacing: 0.5px;
+  letter-spacing: 0.6px;
   margin-bottom: 4px;
 }
 
@@ -4779,9 +4795,9 @@ sl-details.learnings-panel::part(content) {
 
 .bead-tooltip-header {
   display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
 }
 
 sl-tooltip.bead-tooltip::part(body) {
@@ -4790,6 +4806,7 @@ sl-tooltip.bead-tooltip::part(body) {
 
 .bead-tooltip-badges {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 4px;
 }
@@ -4825,7 +4842,7 @@ sl-tooltip.bead-tooltip::part(body) {
 
 .bead-tooltip-excerpt {
   font-size: 12px;
-  white-space: pre-wrap;
+  white-space: normal;
   margin-bottom: 2px;
 }
 
@@ -6240,6 +6257,47 @@ sl-dialog.markdown-dialog::part(body) {
   text-align: left;
 }
 
+/* --- Markdown context overrides --- */
+
+.markdown-inline.markdown-body {
+  display: inline;
+  font-size: inherit;
+  line-height: inherit;
+}
+.markdown-inline.markdown-body p {
+  display: inline;
+  margin: 0;
+}
+.markdown-inline.markdown-body code {
+  font-size: 0.85em;
+}
+
+.agent-prompt-content .markdown-body {
+  white-space: normal;
+  font-size: 12px;
+  line-height: 1.5;
+}
+.agent-prompt-content .markdown-body h1,
+.agent-prompt-content .markdown-body h2,
+.agent-prompt-content .markdown-body h3 {
+  margin: 0.8em 0 0.3em;
+}
+
+.bead-tooltip-excerpt.markdown-body {
+  white-space: normal;
+  font-size: 12px;
+  max-height: 200px;
+  overflow-y: auto;
+}
+.bead-tooltip-excerpt.markdown-body p {
+  margin: 0.3em 0;
+}
+.bead-tooltip-excerpt.markdown-body pre {
+  font-size: 11px;
+  max-height: 120px;
+  overflow: auto;
+}
+
 .workspace-run-card .workspace-card-root,
 .workspace-run-card .workspace-card-name {
   font-family: var(--font-mono);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/ui",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Pipeline monitoring UI for worca-cc",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -65,6 +65,7 @@
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-search": "^0.16.0",
     "@xterm/xterm": "^6.0.0",
+    "dompurify": "^3.4.5",
     "express": "^5.2.1",
     "lit-html": "^3.3.1",
     "lucide": "^0.577.0",

package/server/beads-reader.js

@@ -14,6 +14,13 @@ async function runBd(args, dbPath) {
   return JSON.parse(stdout);
 }
 
+export function extractEffortFromLabels(labels) {
+  if (!labels || labels.length === 0) return null;
+  const match = labels.find((l) => l.startsWith('worca-effort:'));
+  if (!match) return null;
+  return match.slice('worca-effort:'.length);
+}
+
 function transformIssue(issue, deps) {
   const depends_on = (deps || []).map((d) => d.id);
   const blocked_by = (deps || [])
@@ -29,30 +36,39 @@ function transformIssue(issue, deps) {
     external_ref: issue.external_ref || null,
     depends_on,
     blocked_by,
+    effort: extractEffortFromLabels(issue.labels),
   };
 }
 
-async function enrichWithDeps(issues, dbPath) {
-  const needDeps = issues.filter((i) => i.dependency_count > 0);
-  if (needDeps.length === 0) {
-    return issues.map((i) => transformIssue(i, []));
-  }
-  const detailed = await runBd(['show', ...needDeps.map((i) => i.id)], dbPath);
-  const depMap = new Map(detailed.map((d) => [d.id, d.dependencies || []]));
-  return issues.map((i) => transformIssue(i, depMap.get(i.id) || []));
+export async function enrichIssuesWithDeps(issues, dbPath) {
+  if (issues.length === 0) return [];
+  const detailed = await runBd(['show', ...issues.map((i) => i.id)], dbPath);
+  const detailMap = new Map(detailed.map((d) => [d.id, d]));
+  return issues.map((i) => {
+    const d = detailMap.get(i.id);
+    return transformIssue(d || i, d?.dependencies || []);
+  });
 }
 
 export function dbExists(beadsDb) {
   return existsSync(beadsDb);
 }
 
+export async function listIssuesShallow(beadsDb) {
+  try {
+    return await runBd(['list', '--limit', '0'], beadsDb);
+  } catch {
+    return [];
+  }
+}
+
 export async function listIssues(beadsDb) {
   try {
     const issues = await runBd(['list', '--limit', '0'], beadsDb);
-    // Must await here — without it, an enrichWithDeps rejection (e.g. bd show
+    // Must await here — without it, an enrichIssuesWithDeps rejection (e.g. bd show
     // SIGTERM under daemon contention) escapes the try/catch and propagates
     // to the WS handler as an unhandled rejection, crashing Node.
-    return await enrichWithDeps(issues, beadsDb);
+    return await enrichIssuesWithDeps(issues, beadsDb);
   } catch {
     return [];
   }
@@ -64,7 +80,7 @@ export async function listIssuesByLabel(beadsDb, label) {
       ['list', '--label-any', label, '--all', '--limit', '0'],
       beadsDb,
     );
-    return await enrichWithDeps(issues, beadsDb);
+    return await enrichIssuesWithDeps(issues, beadsDb);
   };
   try {
     return await attempt();
@@ -89,10 +105,9 @@ export async function listUnlinkedIssues(beadsDb) {
       const labels = d?.labels || [];
       return !labels.some((l) => l.startsWith('run:'));
     });
-    // detailed already has dependencies, use them directly
     return unlinked.map((i) => {
       const d = detailMap.get(i.id);
-      return transformIssue(i, d?.dependencies || []);
+      return transformIssue(d || i, d?.dependencies || []);
     });
   } catch {
     return [];

package/server/index.js

@@ -90,22 +90,21 @@ server.on('error', (err) => {
   process.exit(1);
 });
 
-const { broadcast, scheduleRefresh, resolveRunProject } = attachWsServer(
-  server,
-  {
+const { broadcast, scheduleRefresh, resolveRunProject, getBeadsCounts } =
+  attachWsServer(server, {
     worcaDir,
     settingsPath,
     prefsPath: preferencesPath(),
     prefsDir,
     webhookInbox,
     projectRoot,
-  },
-);
+  });
 
-// Expose broadcast, scheduleRefresh, and resolveRunProject to REST route handlers
+// Expose broadcast, scheduleRefresh, resolveRunProject, and getBeadsCounts to REST route handlers
 app.locals.broadcast = broadcast;
 app.locals.scheduleRefresh = scheduleRefresh;
 app.locals.resolveRunProject = resolveRunProject;
+app.locals.getBeadsCounts = getBeadsCounts;
 
 // Boot chat integrations only in global mode — project-scoped instances skip
 // integrations to avoid duplicate Telegram long-poll connections on the same bot.

package/server/integrations/commands/global.js

@@ -211,6 +211,11 @@ export function createGlobalHandlers({ chatContext, prefsDir, restClient }) {
           } else if (elapsed) {
             parts.push(`   **Duration:** ${elapsed}`);
           }
+          if (run.beads_total > 0) {
+            parts.push(
+              `   **Beads:** ${run.beads_done ?? 0}/${run.beads_total}`,
+            );
+          }
           lines.push(parts.join('\n'));
         }
       }

package/server/integrations/commands/project.js

@@ -181,6 +181,9 @@ function fmtStatusBlock(run) {
     const iterPart = iteration ? ` (iteration ${iteration})` : '';
     parts.push(`   **Stage:** ${stage}${iterPart}`);
   }
+  if (run.beads_total > 0) {
+    parts.push(`   **Beads:** ${run.beads_done ?? 0}/${run.beads_total}`);
+  }
   if (elapsed) parts.push(`   **Duration:** ${elapsed}`);
   if (cost) parts.push(`   **Cost:** ${cost}`);
   if (ps === 'completed' && run.pr_url)

package/server/integrations/renderers.js

@@ -114,6 +114,9 @@ function renderStageCompleted(envelope) {
   parts.push(`   **Stage:** ${p.stage ?? 'unknown'} completed`);
   const dur = fmtMs(p.duration_ms);
   if (dur) parts.push(`   **Duration:** ${dur}`);
+  if (p.beads_total > 0) {
+    parts.push(`   **Beads:** ${p.beads_done ?? 0}/${p.beads_total}`);
+  }
   return mdMsg(parts.join('\n'), 'success');
 }
 
@@ -504,6 +507,17 @@ function renderWorkspaceGuideConflict(envelope) {
   return mdMsg(parts.join('\n'), 'warning');
 }
 
+function renderBeadNext(envelope) {
+  const p = envelope.payload;
+  const parts = [`⚙ **Run:** \`${runId(envelope)}\``];
+  const label =
+    p.max_beads != null
+      ? `${p.bead_iteration}/${p.max_beads}`
+      : `${p.bead_iteration}`;
+  parts.push(`   **Bead:** ${label}`);
+  return mdMsg(parts.join('\n'), 'info');
+}
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -550,6 +564,7 @@ const EVENT_RENDERERS = {
 // than Tier-1 defaults. Callers that want them can pull from this export and
 // register them in their own pipeline.
 export const OPT_IN_RENDERERS = {
+  'pipeline.bead.next': renderBeadNext,
   'fleet.launched': renderFleetLaunched,
   'workspace.launched': renderWorkspaceLaunched,
   'workspace.plan.started': renderWorkspacePlanStarted,

package/server/project-routes.js

@@ -360,10 +360,29 @@ export function createProjectScopedRoutes({
   });
 
   // GET /api/projects/:projectId/runs — list runs for this project
-  router.get('/runs', requireWorcaDir, (req, res) => {
+  router.get('/runs', requireWorcaDir, async (req, res) => {
     try {
       const runs = discoverRuns(req.project.worcaDir);
       const default_branch = getDefaultBranch(req.project.projectRoot);
+
+      const { getBeadsCounts } = req.app.locals;
+      if (getBeadsCounts) {
+        try {
+          const counts = await getBeadsCounts(req.project.name);
+          if (counts) {
+            for (const run of runs) {
+              const c = counts[run.id];
+              if (c) {
+                run.beads_done = c.done;
+                run.beads_total = c.total;
+              }
+            }
+          }
+        } catch {
+          /* non-fatal — runs returned without bead counts */
+        }
+      }
+
       const response = { ok: true, runs, default_branch };
       // Include settings so multi-project clients can use loop limits, etc.
       const { settingsPath } = req.project;

package/server/ws-beads-watcher.js

@@ -4,32 +4,108 @@
  * because fs.watch on macOS misses SQLite WAL writes done via mmap.
  */
 
-import { existsSync, unwatchFile, watch, watchFile } from 'node:fs';
+import { existsSync, statSync, unwatchFile, watch, watchFile } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { countIssuesByRunLabel, listIssues } from './beads-reader.js';
+import {
+  countIssuesByRunLabel,
+  enrichIssuesWithDeps,
+  listIssuesShallow,
+} from './beads-reader.js';
 
 const BEADS_DEBOUNCE_MS = 500;
 const BEADS_POLL_MS = 2000;
 
+/**
+ * Resolve the beads.db path for a project's worcaDir, independent of any
+ * watcher instance. Used by tier-independent count lookups (chat-only mode,
+ * where no beadsWatcher exists because the WatcherSet is in TIER_POLLING).
+ * @param {string} worcaDir
+ * @returns {string}
+ */
+export function beadsDbPathFor(worcaDir) {
+  return resolve(join(worcaDir, '..', '.beads', 'beads.db'));
+}
+
 /**
  * @param {{ worcaDir: string, broadcaster: { broadcast: Function }, projectId?: string }} deps
  */
 export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
-  const beadsDbPath = resolve(join(worcaDir, '..', '.beads', 'beads.db'));
+  const beadsDbPath = beadsDbPathFor(worcaDir);
   const beadsDir = resolve(join(worcaDir, '..', '.beads'));
   const beadsWalPath = `${beadsDbPath}-wal`;
   let fsWatcher = null;
   let BEADS_REFRESH_TIMER = null;
+  let lastPayloadJson = null;
+  let lastSelfReadWalStat = null;
+  let latestCounts = {};
+  // In-flight guard + trailing coalesce. The refresh body spawns several `bd`
+  // subprocesses (listIssuesShallow, then enrichIssuesWithDeps +
+  // countIssuesByRunLabel when the fingerprint changes) that, on a large beads
+  // db, take seconds. The debounce only collapses scheduling — once the async body
+  // is awaiting, a fresh db/WAL event would otherwise start an overlapping
+  // refresh and pile up bd processes unbounded. Allow at most one refresh in
+  // flight; events arriving mid-refresh collapse into a single trailing pass.
+  let refreshing = false;
+  let refreshPending = false;
+  let lastListFingerprint = null;
+
+  function computeFingerprint(issues) {
+    const sorted = [...issues].sort((a, b) => (a.id < b.id ? -1 : 1));
+    return JSON.stringify(
+      sorted.map((i) => ({
+        id: i.id,
+        status: i.status,
+        priority: i.priority,
+        title: i.title,
+        updated_at: i.updated_at,
+        // dependency_count/dependent_count come free in `bd list` (no `bd show`).
+        // They catch dependency-edge changes (`bd dep add/remove`) that don't
+        // bump an issue's own updated_at — without them the fingerprint would
+        // bail and leave depends_on/blocked_by (and blocked badges) stale.
+        dependency_count: i.dependency_count,
+        dependent_count: i.dependent_count,
+      })),
+    );
+  }
+
+  function recordWalStat() {
+    try {
+      const s = statSync(beadsWalPath);
+      lastSelfReadWalStat = { mtimeMs: s.mtimeMs, size: s.size };
+    } catch {
+      lastSelfReadWalStat = null;
+    }
+  }
 
   function scheduleBeadsRefresh() {
     if (BEADS_REFRESH_TIMER) clearTimeout(BEADS_REFRESH_TIMER);
-    BEADS_REFRESH_TIMER = setTimeout(async () => {
-      BEADS_REFRESH_TIMER = null;
-      try {
-        const [issues, counts] = await Promise.all([
-          listIssues(beadsDbPath),
-          countIssuesByRunLabel(beadsDbPath).catch(() => ({})),
-        ]);
+    BEADS_REFRESH_TIMER = setTimeout(runBeadsRefresh, BEADS_DEBOUNCE_MS);
+  }
+
+  async function runBeadsRefresh() {
+    BEADS_REFRESH_TIMER = null;
+    if (refreshing) {
+      refreshPending = true;
+      return;
+    }
+    refreshing = true;
+    try {
+      const shallowIssues = await listIssuesShallow(beadsDbPath);
+      const fingerprint = computeFingerprint(shallowIssues);
+      if (fingerprint === lastListFingerprint) {
+        recordWalStat();
+        return;
+      }
+      lastListFingerprint = fingerprint;
+
+      const [issues, counts] = await Promise.all([
+        enrichIssuesWithDeps(shallowIssues, beadsDbPath),
+        countIssuesByRunLabel(beadsDbPath).catch(() => ({})),
+      ]);
+      latestCounts = counts;
+      const payloadJson = JSON.stringify({ issues, counts });
+      if (payloadJson !== lastPayloadJson) {
+        lastPayloadJson = payloadJson;
         broadcaster.broadcast(
           'beads-update',
           {
@@ -40,10 +116,17 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
           },
           projectId,
         );
-      } catch {
-        /* ignore */
       }
-    }, BEADS_DEBOUNCE_MS);
+      recordWalStat();
+    } catch {
+      /* ignore */
+    } finally {
+      refreshing = false;
+      if (refreshPending) {
+        refreshPending = false;
+        scheduleBeadsRefresh();
+      }
+    }
   }
 
   if (existsSync(beadsDir)) {
@@ -60,6 +143,13 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
     // on macOS. watchFile tolerates a missing file; it starts firing once created.
     watchFile(beadsWalPath, { interval: BEADS_POLL_MS }, (curr, prev) => {
       if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) {
+        if (
+          lastSelfReadWalStat &&
+          curr.mtimeMs === lastSelfReadWalStat.mtimeMs &&
+          curr.size === lastSelfReadWalStat.size
+        ) {
+          return;
+        }
         scheduleBeadsRefresh();
       }
     });
@@ -78,5 +168,108 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
     }
   }
 
-  return { getBeadsDbPath, destroy };
+  function getLatestCounts() {
+    return latestCounts;
+  }
+
+  return { getBeadsDbPath, getLatestCounts, destroy };
+}
+
+// Throttle window for the cold-path bead-count read (used by REST /runs and chat
+// when no live watcher is warm). The read costs seconds on a large db, so a short
+// TTL lets repeated /runs across many projects re-spawn `bd` too often. Counts are
+// advisory and the live watcher keeps a viewed project fresh, so 30s is ample.
+const FALLBACK_TTL_MS = 30000;
+/** @type {Map<string, { ts: number, counts: object }>} */
+const fallbackCache = new Map();
+/** @type {Map<string, Promise<object>>} */
+const fallbackInflight = new Map();
+
+/**
+ * Resolve per-run bead counts for a WatcherSet, independent of its tier.
+ *
+ * Fast path: the live watcher cache, populated only while a UI client is
+ * subscribed (TIER_FULL). Fallback: an on-demand DB read for callers that
+ * have no active watcher — e.g. chat integrations hitting REST with no
+ * browser open, where the WatcherSet sits in TIER_POLLING and `beadsWatcher`
+ * is null. The fallback is TTL-cached and in-flight-deduplicated so repeated
+ * chat polling does not spawn a `bd` subprocess per request.
+ *
+ * @param {{ projectId?: string, worcaDir?: string, beadsWatcher?: { getLatestCounts: () => object } | null }} [wset]
+ * @returns {Promise<Record<string, { total: number, done: number }>>}
+ */
+export async function resolveBeadsCounts(wset) {
+  if (!wset || !wset.worcaDir) return {};
+
+  const live = wset.beadsWatcher?.getLatestCounts();
+  if (live && Object.keys(live).length > 0) return live;
+
+  const key = wset.projectId ?? wset.worcaDir;
+  const cached = fallbackCache.get(key);
+  if (cached && Date.now() - cached.ts < FALLBACK_TTL_MS) return cached.counts;
+  if (fallbackInflight.has(key)) return fallbackInflight.get(key);
+
+  const dbPath = beadsDbPathFor(wset.worcaDir);
+  if (!existsSync(dbPath)) return {};
+
+  const promise = (async () => {
+    try {
+      const counts = await countIssuesByRunLabel(dbPath);
+      fallbackCache.set(key, { ts: Date.now(), counts });
+      return counts;
+    } catch {
+      return {};
+    } finally {
+      fallbackInflight.delete(key);
+    }
+  })();
+  fallbackInflight.set(key, promise);
+  return promise;
+}
+
+/**
+ * Non-blocking variant of {@link resolveBeadsCounts}: returns whatever counts
+ * are already available (the live watcher cache, or a fresh TTL-cached fallback)
+ * WITHOUT ever awaiting the cold `bd` query. When nothing is cached it kicks off
+ * a background refresh (reusing the same TTL cache + in-flight dedup) so a later
+ * caller gets real data, and returns {} immediately.
+ *
+ * Used by the REST `/runs` endpoint: a cold `bd show` on a large beads db
+ * (worca-cc has hundreds of issues — the cold read takes ~10s) would otherwise
+ * block the run list and, fanned out across every project, stall the whole UI.
+ * Bead counts on run cards are advisory and arrive via the `beads-update`
+ * broadcast once warm; the web run-detail does not use them at all.
+ *
+ * @param {{ projectId?: string, worcaDir?: string, beadsWatcher?: { getLatestCounts: () => object } | null }} [wset]
+ * @returns {Record<string, { total: number, done: number }>}
+ */
+export function peekBeadsCounts(wset) {
+  if (!wset || !wset.worcaDir) return {};
+
+  const live = wset.beadsWatcher?.getLatestCounts();
+  if (live && Object.keys(live).length > 0) return live;
+
+  const key = wset.projectId ?? wset.worcaDir;
+  const cached = fallbackCache.get(key);
+  if (cached && Date.now() - cached.ts < FALLBACK_TTL_MS) return cached.counts;
+
+  // Cold cache: warm it in the background (dedup'd), but never block the caller.
+  if (!fallbackInflight.has(key)) {
+    const dbPath = beadsDbPathFor(wset.worcaDir);
+    if (existsSync(dbPath)) {
+      const promise = (async () => {
+        try {
+          const counts = await countIssuesByRunLabel(dbPath);
+          fallbackCache.set(key, { ts: Date.now(), counts });
+          return counts;
+        } catch {
+          return {};
+        } finally {
+          fallbackInflight.delete(key);
+        }
+      })();
+      fallbackInflight.set(key, promise);
+    }
+  }
+  return {};
 }

package/server/ws-message-router.js

@@ -11,7 +11,6 @@ import { join } from 'node:path';
 import { isRequest, makeError, makeOk } from '../app/protocol.js';
 import {
   dbExists as beadsDbExists,
-  countIssuesByRunLabel,
   getIssue,
   listDistinctRunLabels,
   listIssues,
@@ -35,6 +34,7 @@ import {
 import { resolveRunDir } from './run-dir-resolver.js';
 import { readSettings } from './settings-reader.js';
 import { discoverRuns } from './watcher.js';
+import { resolveBeadsCounts } from './ws-beads-watcher.js';
 
 /**
  * @param {{
@@ -643,19 +643,12 @@ export function createMessageRouter({
       return;
     }
 
-    // list-beads-counts
+    // list-beads-counts — tier-independent: resolveBeadsCounts falls back to
+    // an on-demand DB read when no beadsWatcher exists (TIER_POLLING), so
+    // chat/REST callers with no browser open still get counts.
     if (req.type === 'list-beads-counts') {
       const proj = resolveProject(ws, req.payload);
-      if (!proj.wset.beadsWatcher) {
-        ws.send(JSON.stringify(makeOk(req, { counts: {} })));
-        return;
-      }
-      const beadsDbPath = proj.wset.beadsWatcher.getBeadsDbPath();
-      if (!beadsDbExists(beadsDbPath)) {
-        ws.send(JSON.stringify(makeOk(req, { counts: {} })));
-        return;
-      }
-      const counts = await countIssuesByRunLabel(beadsDbPath);
+      const counts = await resolveBeadsCounts(proj.wset);
       ws.send(JSON.stringify(makeOk(req, { counts })));
       return;
     }

package/server/ws-modular.js

@@ -13,6 +13,7 @@ import { fleetRunsDir, workspaceRunsDir } from './paths.js';
 import { readProjects, synthesizeDefaultProject } from './project-registry.js';
 import { TIER_FULL, TIER_POLLING, WatcherSet } from './watcher-set.js';
 import { readProjectWorcaVersion } from './worca-setup.js';
+import { peekBeadsCounts } from './ws-beads-watcher.js';
 import { createBroadcaster } from './ws-broadcaster.js';
 import { createClientManager } from './ws-client-manager.js';
 import { createFleetManifestWatcher } from './ws-fleet-manifest-watcher.js';
@@ -330,10 +331,17 @@ export function attachWsServer(httpServer, config) {
     return null;
   }
 
+  // Non-blocking: returns cached/live counts and warms cold caches in the
+  // background. The REST /runs endpoint must never block on a slow `bd` read.
+  function getBeadsCounts(projectId) {
+    return peekBeadsCounts(watcherSets.get(projectId));
+  }
+
   return {
     wss,
     broadcast: broadcaster.broadcast,
     scheduleRefresh,
     resolveRunProject,
+    getBeadsCounts,
   };
 }