beads-ui 0.1.2 → 0.3.0

package/server/ws.js

@@ -5,17 +5,175 @@
  */
 import { WebSocketServer } from 'ws';
 import { runBd, runBdJson } from './bd.js';
+import { fetchListForSubscription } from './list-adapters.js';
 import { isRequest, makeError, makeOk } from './protocol.js';
+import { keyOf, registry } from './subscriptions.js';
+import { validateSubscribeListPayload } from './validators.js';
+
+/**
+ * Debounced refresh scheduling for active list subscriptions.
+ * A trailing window coalesces rapid change bursts into a single refresh run.
+ */
+/** @type {ReturnType<typeof setTimeout> | null} */
+let REFRESH_TIMER = null;
+let REFRESH_DEBOUNCE_MS = 75;
+
+/**
+ * Mutation refresh window gate. When active, watcher-driven list refresh
+ * scheduling is suppressed. The gate resolves either when a watcher event
+ * arrives (via scheduleListRefresh) or when a timeout elapses, at which
+ * point a single refresh pass over all active list subscriptions is run.
+ */
+/**
+ * @typedef {Object} MutationGate
+ * @property {boolean} resolved
+ * @property {(reason: 'watcher'|'timeout') => void} resolve
+ * @property {ReturnType<typeof setTimeout>} timer
+ */
+/** @type {MutationGate | null} */
+let MUTATION_GATE = null;
+
+/**
+ * Start a mutation window gate if not already active. The gate resolves on the
+ * next watcher event or after `timeout_ms`, then triggers a single refresh run
+ * across all active list subscriptions. Watcher-driven refresh scheduling is
+ * suppressed during the window.
+ *
+ * Fire-and-forget; callers should not await this.
+ * @param {number} [timeout_ms]
+ */
+function triggerMutationRefreshOnce(timeout_ms = 500) {
+  if (MUTATION_GATE) {
+    return;
+  }
+  /** @type {(r: 'watcher'|'timeout') => void} */
+  let doResolve = () => {};
+  const p = new Promise((resolve) => {
+    doResolve = resolve;
+  });
+  MUTATION_GATE = {
+    resolved: false,
+    resolve: (reason) => {
+      if (!MUTATION_GATE || MUTATION_GATE.resolved) {
+        return;
+      }
+      MUTATION_GATE.resolved = true;
+      try {
+        doResolve(reason);
+      } catch {
+        // ignore resolve errors
+      }
+    },
+    timer: setTimeout(() => {
+      try {
+        MUTATION_GATE?.resolve('timeout');
+      } catch {
+        // ignore
+      }
+    }, timeout_ms)
+  };
+  MUTATION_GATE.timer.unref?.();
+
+  // After resolution, run a single refresh across active subs and clear gate
+  void p.then(async () => {
+    try {
+      await refreshAllActiveListSubscriptions();
+    } catch {
+      // ignore refresh errors
+    } finally {
+      try {
+        if (MUTATION_GATE?.timer) {
+          clearTimeout(MUTATION_GATE.timer);
+        }
+      } catch {
+        // ignore
+      }
+      MUTATION_GATE = null;
+    }
+  });
+}
+
+/**
+ * Collect unique active list subscription specs across all connected clients.
+ * @returns {Array<{ type: string, params?: Record<string,string|number|boolean> }>}
+ */
+function collectActiveListSpecs() {
+  /** @type {Array<{ type: string, params?: Record<string,string|number|boolean> }>} */
+  const specs = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  const wss = CURRENT_WSS;
+  if (!wss) {
+    return specs;
+  }
+  for (const ws of wss.clients) {
+    if (ws.readyState !== ws.OPEN) {
+      continue;
+    }
+    const s = ensureSubs(/** @type {any} */ (ws));
+    if (!s.list_subs) {
+      continue;
+    }
+    for (const { key, spec } of s.list_subs.values()) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        specs.push(spec);
+      }
+    }
+  }
+  return specs;
+}
+
+/**
+ * Run refresh for all active list subscription specs and publish deltas.
+ */
+async function refreshAllActiveListSubscriptions() {
+  const specs = collectActiveListSpecs();
+  // Run refreshes concurrently; locking is handled per key in the registry
+  await Promise.all(
+    specs.map(async (spec) => {
+      try {
+        await refreshAndPublish(spec);
+      } catch {
+        // ignore refresh errors per spec
+      }
+    })
+  );
+}
+
+/**
+ * Schedule a coalesced refresh of all active list subscriptions.
+ */
+export function scheduleListRefresh() {
+  // Suppress watcher-driven refreshes during an active mutation gate; resolve gate once
+  if (MUTATION_GATE) {
+    try {
+      MUTATION_GATE.resolve('watcher');
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  if (REFRESH_TIMER) {
+    clearTimeout(REFRESH_TIMER);
+  }
+  REFRESH_TIMER = setTimeout(() => {
+    REFRESH_TIMER = null;
+    // Fire and forget; callers don't await scheduling
+    void refreshAllActiveListSubscriptions();
+  }, REFRESH_DEBOUNCE_MS);
+  REFRESH_TIMER.unref?.();
+}
 
 /**
  * @typedef {{
- *   subscribed: boolean,
- *   list_filters?: { status?: 'open'|'in_progress'|'closed', ready?: boolean, limit?: number },
- *   show_id?: string | null
+ *   show_id?: string | null,
+ *   list_subs?: Map<string, { key: string, spec: { type: string, params?: Record<string, string | number | boolean> } }>,
+ *   list_revisions?: Map<string, number>
  * }} ConnectionSubs
  */
 
-/** @type {WeakMap<WebSocket, ConnectionSubs>} */
+/** @type {WeakMap<WebSocket, any>} */
 const SUBS = new WeakMap();
 
 /** @type {WebSocketServer | null} */
@@ -24,117 +182,224 @@ let CURRENT_WSS = null;
 /**
  * Get or initialize the subscription state for a socket.
  * @param {WebSocket} ws
- * @returns {ConnectionSubs}
+ * @returns {any}
  */
-function getSubs(ws) {
+function ensureSubs(ws) {
   let s = SUBS.get(ws);
   if (!s) {
-    s = { subscribed: false, show_id: null };
+    s = {
+      show_id: null,
+      list_subs: new Map(),
+      list_revisions: new Map()
+    };
     SUBS.set(ws, s);
   }
   return s;
 }
 
 /**
- * Emit an issues-changed event to relevant clients when possible, or broadcast to all.
- * Targeting rules:
- * - If `issue` is provided, send to clients that currently show the same id or whose
- *   last list filter likely includes the issue (status match or ready=true).
- * - If only `hint` is provided, but contains ids, send to clients that show one of those ids.
- * - Otherwise, send to all open clients.
- * @param {{ ts?: number, hint?: { ids?: string[] } }} payload
- * @param {{ issue?: any }} [options]
+ * Get next monotonically increasing revision for a subscription key on this connection.
+ * @param {WebSocket} ws
+ * @param {string} key
  */
-export function notifyIssuesChanged(payload, options = {}) {
-  const wss = CURRENT_WSS;
-  if (!wss) {
-    return;
+/**
+ * @param {WebSocket} ws
+ * @param {string} key
+ */
+function nextListRevision(ws, key) {
+  const s = ensureSubs(ws);
+  const m = s.list_revisions || new Map();
+  s.list_revisions = m;
+  const prev = m.get(key) || 0;
+  const next = prev + 1;
+  m.set(key, next);
+  return next;
+}
+
+/**
+ * Emit per-subscription envelopes to a specific client id on a socket.
+ * Helpers for snapshot / upsert / delete.
+ */
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {Array<Record<string, unknown>>} issues
+ */
+function emitSubscriptionSnapshot(ws, client_id, key, issues) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: /** @type {const} */ ('snapshot'),
+    id: client_id,
+    revision,
+    issues
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('snapshot'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch {
+    // ignore per-socket errors
   }
-  /** @type {Set<WebSocket>} */
-  const recipients = new Set();
+}
 
-  /** @type {any} */
-  const issue = options.issue;
-  /** @type {string[]} */
-  const hint_ids = Array.isArray(payload?.hint?.ids)
-    ? /** @type {string[]} */ (payload.hint.ids)
-    : [];
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {Record<string, unknown>} issue
+ */
+function emitSubscriptionUpsert(ws, client_id, key, issue) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: 'upsert',
+    id: client_id,
+    revision,
+    issue
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('upsert'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch {
+    // ignore
+  }
+}
 
-  if (issue && typeof issue === 'object' && issue.id) {
-    for (const ws of wss.clients) {
-      if (ws.readyState !== ws.OPEN) {
-        continue;
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {string} issue_id
+ */
+function emitSubscriptionDelete(ws, client_id, key, issue_id) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: 'delete',
+    id: client_id,
+    revision,
+    issue_id
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('delete'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch {
+    // ignore
+  }
+}
+
+// issues-changed removed in v2: detail and lists are pushed via subscriptions
+
+/**
+ * Refresh a subscription spec: fetch via adapter, apply to registry and emit
+ * per-subscription full-issue envelopes to subscribers. Serialized per key.
+ * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
+ */
+async function refreshAndPublish(spec) {
+  const key = keyOf(spec);
+  await registry.withKeyLock(key, async () => {
+    const res = await fetchListForSubscription(spec);
+    if (!res.ok) {
+      return;
+    }
+    const items = applyClosedIssuesFilter(spec, res.items);
+    const prevSize = registry.get(key)?.itemsById.size || 0;
+    const delta = registry.applyItems(key, items);
+    const entry = registry.get(key);
+    if (!entry || entry.subscribers.size === 0) {
+      return;
+    }
+    /** @type {Map<string, any>} */
+    const byId = new Map();
+    for (const it of items) {
+      if (it && typeof it.id === 'string') {
+        byId.set(it.id, it);
       }
-      const s = getSubs(/** @type {any} */ (ws));
-      if (!s.subscribed) {
-        continue;
+    }
+    for (const ws of entry.subscribers) {
+      if (ws.readyState !== ws.OPEN) continue;
+      const s = ensureSubs(ws);
+      const subs = s.list_subs || new Map();
+      /** @type {string[]} */
+      const clientIds = [];
+      for (const [cid, v] of subs.entries()) {
+        if (v.key === key) clientIds.push(cid);
       }
-      if (s.show_id && s.show_id === issue.id) {
-        recipients.add(ws);
+      if (clientIds.length === 0) continue;
+      if (prevSize === 0) {
+        for (const cid of clientIds) {
+          emitSubscriptionSnapshot(ws, cid, key, items);
+        }
         continue;
       }
-      if (s.list_filters) {
-        // Ready lists are conservatively invalidated on any change
-        if (s.list_filters.ready === true) {
-          recipients.add(ws);
-          continue;
+      for (const cid of clientIds) {
+        for (const id of [...delta.added, ...delta.updated]) {
+          const issue = byId.get(id);
+          if (issue) {
+            emitSubscriptionUpsert(ws, cid, key, issue);
+          }
         }
-        // Status lists: invalidate when status matches updated issue
-        if (
-          s.list_filters.status &&
-          String(s.list_filters.status) === String(issue.status || '')
-        ) {
-          recipients.add(ws);
-          continue;
+        for (const id of delta.removed) {
+          emitSubscriptionDelete(ws, cid, key, id);
         }
       }
     }
-  } else if (hint_ids.length > 0) {
-    for (const ws of wss.clients) {
-      if (ws.readyState !== ws.OPEN) {
-        continue;
-      }
-      const s = getSubs(/** @type {any} */ (ws));
-      if (!s.subscribed) {
-        continue;
-      }
-      if (s.show_id && hint_ids.includes(s.show_id)) {
-        recipients.add(ws);
-      }
-    }
-  }
-
-  /** @type {string} */
-  const msg = JSON.stringify({
-    id: `evt-${Date.now()}`,
-    ok: true,
-    type: /** @type {MessageType} */ ('issues-changed'),
-    payload: { ts: Date.now(), ...(payload || {}) }
   });
+}
 
-  if (recipients.size > 0) {
-    for (const ws of recipients) {
-      ws.send(msg);
-    }
-  } else {
-    // Fallback: full broadcast to keep clients consistent
-    for (const ws of wss.clients) {
-      if (ws.readyState === ws.OPEN) {
-        ws.send(msg);
-      }
+/**
+ * Apply pre-diff filtering for closed-issues lists based on spec.params.since (epoch ms).
+ * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
+ * @param {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
+ */
+function applyClosedIssuesFilter(spec, items) {
+  if (String(spec.type) !== 'closed-issues') {
+    return items;
+  }
+  const p = spec.params || {};
+  const since = typeof p.since === 'number' ? p.since : 0;
+  if (!Number.isFinite(since) || since <= 0) {
+    return items;
+  }
+  /** @type {typeof items} */
+  const out = [];
+  for (const it of items) {
+    const ca = it.closed_at;
+    if (typeof ca === 'number' && Number.isFinite(ca) && ca >= since) {
+      out.push(it);
     }
   }
+  return out;
 }
 
 /**
  * Attach a WebSocket server to an existing HTTP server.
  * @param {Server} http_server
- * @param {{ path?: string, heartbeat_ms?: number }} [options]
- * @returns {{ wss: WebSocketServer, broadcast: (type: MessageType, payload?: unknown) => void, notifyIssuesChanged: (payload: { ts?: number, hint?: { ids?: string[] } }) => void }}
+ * @param {{ path?: string, heartbeat_ms?: number, refresh_debounce_ms?: number }} [options]
+ * @returns {{ wss: WebSocketServer, broadcast: (type: MessageType, payload?: unknown) => void, scheduleListRefresh: () => void }}
  */
 export function attachWsServer(http_server, options = {}) {
   const path = options.path || '/ws';
   const heartbeat_ms = options.heartbeat_ms ?? 30000;
+  if (typeof options.refresh_debounce_ms === 'number') {
+    const n = options.refresh_debounce_ms;
+    if (Number.isFinite(n) && n >= 0) {
+      REFRESH_DEBOUNCE_MS = n;
+    }
+  }
 
   const wss = new WebSocketServer({ server: http_server, path });
   CURRENT_WSS = wss;
@@ -145,7 +410,7 @@ export function attachWsServer(http_server, options = {}) {
     ws.isAlive = true;
 
     // Initialize subscription state for this connection
-    getSubs(/** @type {any} */ (ws));
+    ensureSubs(ws);
 
     ws.on('pong', () => {
       // @ts-expect-error marker
@@ -155,6 +420,14 @@ export function attachWsServer(http_server, options = {}) {
     ws.on('message', (data) => {
       handleMessage(ws, data);
     });
+
+    ws.on('close', () => {
+      try {
+        registry.onDisconnect(ws);
+      } catch {
+        // ignore cleanup errors
+      }
+    });
   });
 
   const interval = setInterval(() => {
@@ -195,7 +468,12 @@ export function attachWsServer(http_server, options = {}) {
     }
   }
 
-  return { wss, broadcast, notifyIssuesChanged: (p) => notifyIssuesChanged(p) };
+  return {
+    wss,
+    broadcast,
+    scheduleListRefresh
+    // v2: list subscription refresh handles updates
+  };
 }
 
 /**
@@ -233,100 +511,50 @@ export async function handleMessage(ws, data) {
   const req = json;
 
   // Dispatch known types here as we implement them. For now, only a ping utility.
-  if (req.type === /** @type {any} */ ('ping')) {
+  if (req.type === /** @type {MessageType} */ ('ping')) {
     ws.send(JSON.stringify(makeOk(req, { ts: Date.now() })));
     return;
   }
 
-  // subscribe-updates: mark this connection as event subscriber
-  if (req.type === 'subscribe-updates') {
-    const s = getSubs(ws);
-    s.subscribed = true;
-    ws.send(JSON.stringify(makeOk(req, { subscribed: true })));
-    return;
-  }
-
-  // list-issues
-  if (req.type === 'list-issues') {
-    const { filters } = /** @type {any} */ (req.payload || {});
-    // When "ready" is requested, use the dedicated bd subcommand
-    if (filters && typeof filters === 'object' && filters.ready === true) {
-      const res = await runBdJson(['ready', '--json']);
-      if (res.code !== 0) {
-        const err = makeError(req, 'bd_error', res.stderr || 'bd failed');
-        ws.send(JSON.stringify(err));
-        return;
-      }
-      // Remember subscription scope for this connection
-      try {
-        const s = getSubs(ws);
-        s.list_filters = { ready: true };
-      } catch {
-        // ignore tracking errors
-      }
-      ws.send(JSON.stringify(makeOk(req, res.stdoutJson)));
-      return;
-    }
-
-    /** @type {string[]} */
-    const args = ['list', '--json'];
-    if (filters && typeof filters === 'object') {
-      if (typeof filters.status === 'string') {
-        // Use long flag for clarity and compatibility
-        args.push('--status', filters.status);
-      }
-      if (typeof filters.priority === 'number') {
-        args.push('--priority', String(filters.priority));
-      }
-      if (typeof filters.limit === 'number' && filters.limit > 0) {
-        args.push('--limit', String(filters.limit));
-      }
-    }
-    const res = await runBdJson(args);
-    if (res.code !== 0) {
-      const err = makeError(req, 'bd_error', res.stderr || 'bd failed');
-      ws.send(JSON.stringify(err));
+  // subscribe-list: payload { id: string, type: string, params?: object }
+  if (req.type === 'subscribe-list') {
+    const validation = validateSubscribeListPayload(
+      /** @type {any} */ (req.payload || {})
+    );
+    if (!validation.ok) {
+      ws.send(
+        JSON.stringify(makeError(req, validation.code, validation.message))
+      );
       return;
     }
-    // Remember last non-ready list filter
+    const client_id = validation.id;
+    const spec = validation.spec;
+    const s = ensureSubs(ws);
+    // Attach to registry
+    const { key } = registry.attach(spec, ws);
+    s.list_subs?.set(client_id, { key, spec });
+    // Send an initial snapshot for this client id only and store items
     try {
-      const s = getSubs(ws);
-      /** @type {{ status?: any, limit?: any }} */
-      const f = filters && typeof filters === 'object' ? filters : {};
-      /** @type {any} */
-      const st = f.status;
-      /** @type {any} */
-      const lim = f.limit;
-      s.list_filters = {};
-      if (st === 'open' || st === 'in_progress' || st === 'closed') {
-        s.list_filters.status = st;
-      }
-      if (typeof lim === 'number') {
-        s.list_filters.limit = lim;
-      }
+      await registry.withKeyLock(key, async () => {
+        const res = await fetchListForSubscription(spec);
+        if (!res.ok) {
+          return;
+        }
+        const items = applyClosedIssuesFilter(spec, res.items);
+        void registry.applyItems(key, items);
+        emitSubscriptionSnapshot(ws, client_id, key, items);
+      });
     } catch {
-      // ignore tracking errors
+      // ignore snapshot errors
     }
-    ws.send(JSON.stringify(makeOk(req, res.stdoutJson)));
+    ws.send(JSON.stringify(makeOk(req, { id: client_id, key })));
     return;
   }
 
-  // epic-status
-  if (req.type === /** @type {any} */ ('epic-status')) {
-    const res = await runBdJson(['epic', 'status', '--json']);
-    if (res.code !== 0) {
-      const err = makeError(req, 'bd_error', res.stderr || 'bd failed');
-      ws.send(JSON.stringify(err));
-      return;
-    }
-    ws.send(JSON.stringify(makeOk(req, res.stdoutJson)));
-    return;
-  }
-
-  // show-issue
-  if (req.type === 'show-issue') {
-    const { id } = /** @type {any} */ (req.payload);
-    if (typeof id !== 'string' || id.length === 0) {
+  // unsubscribe-list: payload { id: string }
+  if (req.type === 'unsubscribe-list') {
+    const { id: client_id } = /** @type {any} */ (req.payload || {});
+    if (typeof client_id !== 'string' || client_id.length === 0) {
       ws.send(
         JSON.stringify(
           makeError(req, 'bad_request', 'payload.id must be a non-empty string')
@@ -334,37 +562,38 @@ export async function handleMessage(ws, data) {
       );
       return;
     }
-    const res = await runBdJson(['show', id, '--json']);
-    if (res.code !== 0) {
-      const err = makeError(req, 'bd_error', res.stderr || 'bd failed');
-      ws.send(JSON.stringify(err));
-      return;
-    }
-    // bd show can return an array when it supports multiple ids;
-    // normalize to a single object for the single-id API.
-    /** @type {any} */
-    const out = Array.isArray(res.stdoutJson)
-      ? res.stdoutJson[0]
-      : res.stdoutJson;
-    if (!out) {
-      ws.send(JSON.stringify(makeError(req, 'not_found', 'issue not found')));
-      return;
-    }
-    // Track current detail subscription for this connection
-    try {
-      const s = getSubs(ws);
-      s.show_id = String(id);
-    } catch {
-      // ignore
-    }
-    ws.send(JSON.stringify(makeOk(req, out)));
+    const s = ensureSubs(ws);
+    const sub = s.list_subs?.get(client_id) || null;
+    let removed = false;
+    if (sub) {
+      try {
+        removed = registry.detach(sub.spec, ws);
+      } catch {
+        removed = false;
+      }
+      s.list_subs?.delete(client_id);
+    }
+    ws.send(
+      JSON.stringify(
+        makeOk(req, {
+          id: client_id,
+          unsubscribed: removed
+        })
+      )
+    );
     return;
   }
 
+  // Removed: subscribe-updates and subscribe-issues. No-ops in v2.
+
+  // list-issues and epic-status were removed in favor of push-only subscriptions
+
+  // Removed: show-issue. Details flow is push-only via `subscribe-list { type: 'issue-detail' }`.
+
   // type updates are not exposed via UI; no handler
 
   // update-assignee
-  if (req.type === /** @type {any} */ ('update-assignee')) {
+  if (req.type === 'update-assignee') {
     const { id, assignee } = /** @type {any} */ (req.payload || {});
     if (
       typeof id !== 'string' ||
@@ -398,6 +627,11 @@ export async function handleMessage(ws, data) {
       return;
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
+    try {
+      triggerMutationRefreshOnce();
+    } catch {
+      // ignore
+    }
     return;
   }
 
@@ -437,11 +671,11 @@ export async function handleMessage(ws, data) {
       return;
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
-    // Push targeted invalidation with updated issue context
+    // After mutation, refresh active subscriptions once (watcher or timeout)
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
-      // ignore fanout errors
+      // ignore
     }
     return;
   }
@@ -483,9 +717,9 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
-      // ignore fanout errors
+      // ignore
     }
     return;
   }
@@ -498,7 +732,9 @@ export async function handleMessage(ws, data) {
       id.length === 0 ||
       (field !== 'title' &&
         field !== 'description' &&
-        field !== 'acceptance') ||
+        field !== 'acceptance' &&
+        field !== 'notes' &&
+        field !== 'design') ||
       typeof value !== 'string'
     ) {
       ws.send(
@@ -506,20 +742,7 @@ export async function handleMessage(ws, data) {
           makeError(
             req,
             'bad_request',
-            "payload requires { id: string, field: 'title'|'description'|'acceptance', value: string }"
-          )
-        )
-      );
-      return;
-    }
-    // Description updates are currently not supported by bd
-    if (field === 'description') {
-      ws.send(
-        JSON.stringify(
-          makeError(
-            req,
-            'bd_error',
-            'editing description is not supported by bd'
+            "payload requires { id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', value: string }"
           )
         )
       );
@@ -527,8 +750,20 @@ export async function handleMessage(ws, data) {
     }
     // Map UI fields to bd CLI flags
     // title       → --title
+    // description → --description
     // acceptance  → --acceptance-criteria
-    const flag = field === 'title' ? '--title' : '--acceptance-criteria';
+    // notes       → --notes
+    // design      → --design
+    const flag =
+      field === 'title'
+        ? '--title'
+        : field === 'description'
+          ? '--description'
+          : field === 'acceptance'
+            ? '--acceptance-criteria'
+            : field === 'notes'
+              ? '--notes'
+              : '--design';
     const res = await runBd(['update', id, flag, value]);
     if (res.code !== 0) {
       ws.send(
@@ -545,15 +780,15 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
-      // ignore fanout errors
+      // ignore
     }
     return;
   }
 
   // create-issue
-  if (req.type === /** @type {any} */ ('create-issue')) {
+  if (req.type === 'create-issue') {
     const { title, type, priority, description } = /** @type {any} */ (
       req.payload || {}
     );
@@ -569,7 +804,6 @@ export async function handleMessage(ws, data) {
       );
       return;
     }
-    /** @type {string[]} */
     const args = ['create', title];
     if (
       typeof type === 'string' &&
@@ -594,13 +828,19 @@ export async function handleMessage(ws, data) {
       );
       return;
     }
-    // Rely on watcher to refresh clients; reply with a minimal ack
+    // Reply with a minimal ack
     ws.send(JSON.stringify(makeOk(req, { created: true })));
+    // Refresh active subscriptions once (watcher or timeout)
+    try {
+      triggerMutationRefreshOnce();
+    } catch {
+      // ignore
+    }
     return;
   }
 
   // dep-add: payload { a: string, b: string, view_id?: string }
-  if (req.type === /** @type {any} */ ('dep-add')) {
+  if (req.type === 'dep-add') {
     const { a, b, view_id } = /** @type {any} */ (req.payload || {});
     if (
       typeof a !== 'string' ||
@@ -636,16 +876,15 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      // Dependencies can affect readiness; conservatively target by issue id
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
-      // ignore fanout errors
+      // ignore
     }
     return;
   }
 
   // dep-remove: payload { a: string, b: string, view_id?: string }
-  if (req.type === /** @type {any} */ ('dep-remove')) {
+  if (req.type === 'dep-remove') {
     const { a, b, view_id } = /** @type {any} */ (req.payload || {});
     if (
       typeof a !== 'string' ||
@@ -681,15 +920,15 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
-      // ignore fanout errors
+      // ignore
     }
     return;
   }
 
   // label-add: payload { id: string, label: string }
-  if (req.type === /** @type {any} */ ('label-add')) {
+  if (req.type === 'label-add') {
     const { id, label } = /** @type {any} */ (req.payload || {});
     if (
       typeof id !== 'string' ||
@@ -724,7 +963,7 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
       // ignore
     }
@@ -732,7 +971,7 @@ export async function handleMessage(ws, data) {
   }
 
   // label-remove: payload { id: string, label: string }
-  if (req.type === /** @type {any} */ ('label-remove')) {
+  if (req.type === 'label-remove') {
     const { id, label } = /** @type {any} */ (req.payload || {});
     if (
       typeof id !== 'string' ||
@@ -767,7 +1006,7 @@ export async function handleMessage(ws, data) {
     }
     ws.send(JSON.stringify(makeOk(req, shown.stdoutJson)));
     try {
-      notifyIssuesChanged({ hint: { ids: [id] } }, { issue: shown.stdoutJson });
+      triggerMutationRefreshOnce();
     } catch {
       // ignore
     }