Optimize broadcast handling and debounce WS session reloads

[txj36]

Summary

Changes

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (no functional changes)
• Documentation update
• Infrastructure / CI / DevOps
• Dependency update

How to Test

Checklist

• I have read the contributing guidelines
• I have signed the CLA (the 🖋️ CLA Assistant bot will prompt me on my first PR)
• My code follows the project's coding standards
• I have added/updated tests that prove my fix or feature works
• All new and existing tests pass (npm test)
• Code is formatted (npm run format:check)
• I have updated documentation where necessary

Screenshots

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

txj seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[gemini-code-assist]

Code Review

This pull request introduces a deferred broadcast queue to decouple WebSocket notifications from SQLite transactions, reducing database lock hold times and deduplicating redundant broadcasts. It also adds a debounced reload mechanism on the client side to handle rapid bursts of events. The review feedback highlights several critical areas for improvement in the queue implementation: preserving the chronological order of events during deduplication, wrapping asynchronous database reads in try-catch blocks to prevent server crashes, adding defensive checks for null or undefined references, and clearing the queue if a transaction rolls back to prevent stale event broadcasts.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current deduplication logic pushes all DB-backed events to the end of the queue, which alters the original chronological order of events. For example, a session_created event could be sent after a subsequent new_event (like SessionStart), which can break client-side state assumptions or cause UI glitches.

We can preserve the exact chronological order of all events by first finding the last index of each dedup-able key, and then filtering the original array in-place.

  // Deduplicate: for DB-backed types, keep only the last entry per (type, id)
  // while preserving the original chronological order of all events.
  const seen = new Map();
  for (let i = 0; i < items.length; i++) {
    const key = dedupeKey(items[i]);
    if (key) {
      seen.set(key, i);
    }
  }

  const deduped = [];
  for (let i = 0; i < items.length; i++) {
    const item = items[i];
    const key = dedupeKey(item);
    if (key) {
      if (seen.get(key) === i) {
        deduped.push(item);
      }
    } else {
      // Inline data — always keep
      deduped.push(item);
    }
  }

[txj36]

Fixed in this PR. The deduplication logic now uses a two-pass approach: first pass records the last index for each dedup key in a Map (overwriting keeps the last occurrence), then second pass filters items to only those indices (plus keyless inline items), preserving the original insertion order. DB-backed events are no longer appended to the end — they remain at their original position in the queue.

[txj36]

Fixed. The deduplication logic now uses a two-pass approach: first pass records the last index per dedup key in a seen Map (overwriting keeps the last occurrence), second pass filters items to only those kept indices (plus keyless inline items), preserving the original insertion order. DB-backed events remain at their original position in the queue — they are no longer appended to the end. (Verified: 631 server tests pass.)

[gemini-code-assist]

Since flush() is executed asynchronously outside the main request-response cycle (via setImmediate), any unhandled exception thrown during loadData(item) (e.g., due to database lock or query failure) will result in an uncaught exception that crashes the entire Node.js process.

Wrapping the broadcast loop in a try-catch block ensures that a single failed broadcast or database read does not bring down the server.

  // Send broadcasts (DB reads happen here, outside the transaction)
  for (const item of deduped) {
    try {
      const data = loadData(item);
      if (data !== undefined && data !== null) {
        broadcast(item.type, data);
      }
    } catch (err) {
      console.error(`[BROADCAST-QUEUE] Failed to broadcast ${item.type}:`, err);
    }
  }

[txj36]

Fixed. The broadcast loop in flush() now wraps each item dispatch in an individual try-catch. If loadData() or broadcast() throws for one item, the error is logged via console.error and the loop continues processing remaining items. No unhandled exception can escape to crash the process.

[txj36]

Fixed. The broadcast loop in flush() now wraps each item dispatch in an individual try-catch. If loadData() or broadcast() throws for one item, the error is logged via console.error and the loop continues processing remaining items. No unhandled exception can escape to crash the process.

[gemini-code-assist]

If ref is null or undefined, accessing ref.data will throw a TypeError and crash the execution. Adding a defensive guard at the beginning of dedupeKey prevents potential crashes.

Suggested change

	function dedupeKey(item) {
	const { type, ref } = item;
	if (ref.data !== undefined) return null; // inline payload, don't dedup
	if (ref.sessionId) return `${type}:session:${ref.sessionId}`;
	if (ref.agentId) return `${type}:agent:${ref.agentId}`;
	return null;
	}
	function dedupeKey(item) {
	const { type, ref } = item;
	if (!ref) return null;
	if (ref.data !== undefined) return null; // inline payload, don't dedup
	if (ref.sessionId) return `${type}:session:${ref.sessionId}`;
	if (ref.agentId) return `${type}:agent:${ref.agentId}`;
	return null;
	}

[txj36]

Fixed. Added a defensive guard at the top of dedupeKey(): if (!ref) return null; — a null/undefined ref is treated as non-dedup-able (same as inline data), preventing TypeError on ref.data access.

[txj36]

Fixed. Added a defensive guard at the top of dedupeKey(): if (!ref) return null; — a null/undefined ref is treated as non-dedup-able (same as inline data), preventing TypeError on ref.data access.

[gemini-code-assist]

Similarly, if ref is null or undefined, accessing ref.data in loadData will throw a TypeError. Adding a defensive guard here ensures robust execution.

Suggested change

	function loadData(item) {
	const { type, ref } = item;
	// Inline payload — no DB read needed
	if (ref.data !== undefined) return ref.data;
	function loadData(item) {
	const { type, ref } = item;
	if (!ref) return null;
	// Inline payload — no DB read needed
	if (ref.data !== undefined) return ref.data;

[txj36]

Fixed. Added a defensive guard at the top of loadData(): if (!ref) return null; — a null/undefined ref returns null immediately, preventing TypeError on ref.data access.

[txj36]

Fixed. Added a defensive guard at the top of loadData(): if (!ref) return null; — a null/undefined ref returns null immediately, preventing TypeError on ref.data access.

[gemini-code-assist]

If processEvent throws an error and the transaction rolls back, any items already enqueued in broadcastQueue during the transaction will remain in the queue because flush() is never called. These stale items will then be incorrectly flushed during the next successful event.

Consider clearing the queue if an error occurs (e.g., by wrapping processEvent in a try-catch block in the route handler to call broadcastQueue.clear(), or clearing the queue at the start of processEvent).

[txj36]

Fixed. The /event route now wraps processEvent in a try-catch. If the transaction throws (rollback), broadcastQueue.clear() is called to purge any items that were enqueued inside the failed transaction, preventing stale broadcasts from being sent on the next flush cycle. The error is then re-thrown so the existing Express error handling still applies.

[txj36]

Fixed. The /event route now wraps processEvent in a try-catch. If the transaction throws (rollback), broadcastQueue.clear() is called to purge any items that were enqueued inside the failed transaction, preventing stale broadcasts from being sent on the next flush cycle. The error is then re-thrown so the existing Express error handling still applies.

[theraihanrakibb]

Good, well-motivated optimization — the "22+ concurrent Claude processes saturating the event loop" rationale is clear, and the broadcast-queue.js deferral + dedup plus the 800 ms Sessions.tsx debounce are the right shape. Tests were updated too (_clearProbeCache for isolation). A few notes:

1. flush() reorders inline events before DB-backed updates (worth a look): in flush(), the first loop pushes every inline new_event item (in source order) and only records indices for DB-backed types; the second loop appends DB-backed items after. So within one flush a new_event is broadcast before its session_updated/agent_updated, whereas the original code emitted in source order. Clients may render an event for a session before receiving the session's updated state. Consider preserving source order while still deduping (keep the last index but emit in original sequence), or explicitly flush inline events after the DB-backed ones.

2. run_status not debounced: Sessions.tsx debounces session_updated and new_event(Stop/SessionEnd) but calls load() immediately for run_status. Route it through the same timer for consistency.

3. Dedup drops distinct create/update signals (edge): for DB-backed keys only the last per (type, id) survives, so a session_created + later session_updated for the same session in one batch collapses to just the update. Confirm the client doesn't rely on the create event specifically.

4. busy_timeout 5s to 60s: reasonable band-aid for contention, but it masks lock contention rather than fixing it — a one-line comment noting it's intentional would help.

(Verified /api/events exists, so the ccam.js change fetching events separately is correctly backed.)