@in-the-loop-labs/pair-review 3.5.2 → 3.6.0

package/public/js/utils/modal-detection.js

@@ -0,0 +1,77 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared modal-detection helpers.
+ *
+ * Used by KeyboardShortcuts and PRManager so keyboard handlers consistently
+ * defer to whatever modal/dialog is currently open. Single source of truth
+ * for both the selector list and the visibility check — keeping them in
+ * sync across consumers was the original motivation for extracting this.
+ *
+ * The help overlay (`#keyboard-shortcuts-help`) is intentionally excluded
+ * from the selectors so the shortcuts overlay itself doesn't suppress
+ * Escape handling for its own close button.
+ */
+
+/**
+ * Selectors that identify "a modal is open". Anything matched here will be
+ * treated as a blocker for unrelated keyboard shortcuts.
+ * @type {string[]}
+ */
+const MODAL_SELECTORS = [
+  '.modal-overlay:not(#keyboard-shortcuts-help)',
+  '.review-modal-overlay',
+  '.preview-modal-overlay',
+  '.confirm-dialog-overlay',
+  '.analysis-config-overlay',
+  '.ai-summary-modal-overlay',
+  '[role="dialog"]:not(#keyboard-shortcuts-help)'
+];
+
+/**
+ * Return true when `element` is visually present — i.e. not hidden via
+ * `display`, `visibility`, or zero opacity. Mirrors the legacy
+ * KeyboardShortcuts.isElementVisible behavior so existing call sites keep
+ * the same semantics.
+ *
+ * @param {Element|null|undefined} element
+ * @returns {boolean}
+ */
+function isElementVisible(element) {
+  if (!element) return false;
+  if (typeof window === 'undefined' || typeof window.getComputedStyle !== 'function') {
+    return true;
+  }
+  const style = window.getComputedStyle(element);
+  if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Return true when at least one of the registered modal selectors matches
+ * a visible element in the document.
+ *
+ * Excludes the keyboard-shortcuts help overlay so it doesn't block its own
+ * close behavior.
+ *
+ * @returns {boolean}
+ */
+function isModalOpen() {
+  if (typeof document === 'undefined') return false;
+  for (const selector of MODAL_SELECTORS) {
+    const el = document.querySelector(selector);
+    if (el && isElementVisible(el)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+if (typeof window !== 'undefined') {
+  window.ModalDetection = { isModalOpen, isElementVisible, MODAL_SELECTORS };
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { isModalOpen, isElementVisible, MODAL_SELECTORS };
+}

package/public/local.html

@@ -448,6 +448,16 @@
                             </svg>
                             <span class="btn-text">Analyze</span>
                         </button>
+                        <button class="btn btn-sm btn-icon btn-summary-toggle" id="summary-toggle-btn" title="Hide hunk summaries" aria-label="Toggle hunk summaries" aria-pressed="true" style="display: none;">
+                            <svg viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
+                                <path d="M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25Zm1.75-.25a.25.25 0 0 0-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25ZM3.5 6.25a.75.75 0 0 1 .75-.75h7a.75.75 0 0 1 0 1.5h-7a.75.75 0 0 1-.75-.75Zm.75 2.25h4a.75.75 0 0 1 0 1.5h-4a.75.75 0 0 1 0-1.5Z"/>
+                            </svg>
+                        </button>
+                        <button class="btn btn-sm btn-icon btn-tour-toggle" id="tour-toggle-btn" title="Start guided tour" aria-label="Start guided tour" aria-pressed="false" style="display: none;">
+                            <svg viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
+                                <path d="M7.75 0a.75.75 0 0 1 .75.75V3h3.634c.414 0 .814.144 1.13.406l2.501 2.071a1.75 1.75 0 0 1 0 2.696l-2.5 2.07a1.75 1.75 0 0 1-1.131.407H8.5v5.6a.75.75 0 0 1-1.5 0V10.65H3.75A1.75 1.75 0 0 1 2 8.9V4.75C2 3.784 2.784 3 3.75 3H7V.75A.75.75 0 0 1 7.75 0Zm-4 4.5a.25.25 0 0 0-.25.25V8.9c0 .138.112.25.25.25h8.384a.25.25 0 0 0 .16-.058l2.5-2.07a.25.25 0 0 0 0-.386l-2.5-2.07a.25.25 0 0 0-.16-.058H3.75Z"/>
+                            </svg>
+                        </button>
                         <button class="btn btn-sm btn-icon" id="chat-toggle-btn" title="Toggle Chat panel">
                             <svg class="chat-icon" viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
                                 <path d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.061l-2.574 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.458 1.458 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h1a.25.25 0 0 0 .25-.25Z"/>
@@ -597,6 +607,9 @@
     <!-- Timestamp parsing utility -->
     <script src="/js/utils/time.js"></script>
 
+    <!-- Modal detection (shared by KeyboardShortcuts and PRManager) -->
+    <script src="/js/utils/modal-detection.js"></script>
+
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
 
@@ -639,6 +652,10 @@
     <script src="/js/modules/analysis-history.js"></script>
     <script src="/js/modules/diff-context.js"></script>
     <script src="/js/modules/file-list-merger.js"></script>
+    <script src="/js/modules/hunk-summary-renderer.js"></script>
+    <script src="/js/modules/tour-renderer.js"></script>
+    <script src="/js/modules/cancel-background-job.js"></script>
+    <script src="/js/components/TourBar.js"></script>
 
     <!-- Chat Panel Component -->
     <script src="/js/components/ChatPanel.js"></script>

package/public/pr.html

@@ -244,6 +244,16 @@
                             </svg>
                             <span class="btn-text">Analyze</span>
                         </button>
+                        <button class="btn btn-sm btn-icon btn-summary-toggle" id="summary-toggle-btn" title="Hide hunk summaries" aria-label="Toggle hunk summaries" aria-pressed="true" style="display: none;">
+                            <svg viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
+                                <path d="M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25Zm1.75-.25a.25.25 0 0 0-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25ZM3.5 6.25a.75.75 0 0 1 .75-.75h7a.75.75 0 0 1 0 1.5h-7a.75.75 0 0 1-.75-.75Zm.75 2.25h4a.75.75 0 0 1 0 1.5h-4a.75.75 0 0 1 0-1.5Z"/>
+                            </svg>
+                        </button>
+                        <button class="btn btn-sm btn-icon btn-tour-toggle" id="tour-toggle-btn" title="Start guided tour" aria-label="Start guided tour" aria-pressed="false" style="display: none;">
+                            <svg viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
+                                <path d="M7.75 0a.75.75 0 0 1 .75.75V3h3.634c.414 0 .814.144 1.13.406l2.501 2.071a1.75 1.75 0 0 1 0 2.696l-2.5 2.07a1.75 1.75 0 0 1-1.131.407H8.5v5.6a.75.75 0 0 1-1.5 0V10.65H3.75A1.75 1.75 0 0 1 2 8.9V4.75C2 3.784 2.784 3 3.75 3H7V.75A.75.75 0 0 1 7.75 0Zm-4 4.5a.25.25 0 0 0-.25.25V8.9c0 .138.112.25.25.25h8.384a.25.25 0 0 0 .16-.058l2.5-2.07a.25.25 0 0 0 0-.386l-2.5-2.07a.25.25 0 0 0-.16-.058H3.75Z"/>
+                            </svg>
+                        </button>
                         <button class="btn btn-sm btn-icon" id="chat-toggle-btn" title="Toggle Chat panel">
                             <svg class="chat-icon" viewBox="0 0 16 16" fill="currentColor" width="14" height="14">
                                 <path d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.061l-2.574 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.458 1.458 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h1a.25.25 0 0 0 .25-.25Z"/>
@@ -400,6 +410,9 @@
     <!-- Timestamp parsing utility -->
     <script src="/js/utils/time.js"></script>
 
+    <!-- Modal detection (shared by KeyboardShortcuts and PRManager) -->
+    <script src="/js/utils/modal-detection.js"></script>
+
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
 
@@ -443,6 +456,10 @@
     <script src="/js/modules/analysis-history.js"></script>
     <script src="/js/modules/diff-context.js"></script>
     <script src="/js/modules/file-list-merger.js"></script>
+    <script src="/js/modules/hunk-summary-renderer.js"></script>
+    <script src="/js/modules/tour-renderer.js"></script>
+    <script src="/js/modules/cancel-background-job.js"></script>
+    <script src="/js/components/TourBar.js"></script>
 
     <!-- Chat Panel Component -->
     <script src="/js/components/ChatPanel.js"></script>

package/src/ai/abort-signal-wiring.js

@@ -0,0 +1,130 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const { spawn } = require('child_process');
+const logger = require('../utils/logger');
+
+/**
+ * Attach an `AbortSignal` to a spawned child process so that aborting the
+ * signal kills the child with `SIGTERM`. Returns a cleanup function that
+ * detaches the abort listener — call it from the `close` / `error` /
+ * `settle` handler so the listener never outlives the process.
+ *
+ * Pattern: every provider that spawns an upstream CLI for tour/summary
+ * generation calls this once right after `spawn(...)`. The returned
+ * `cancelled` getter is included so the post-exit path can distinguish a
+ * user-initiated cancel (exit due to SIGTERM we sent) from a real failure.
+ *
+ * If `signal` is already aborted at the time of wiring, the child is
+ * killed immediately and `cancelled` is set to true. Callers should still
+ * check `cancelled` before treating the eventual exit as a "real" error.
+ *
+ * Shell-mode caveat: when the caller spawned with `shell: true`, the
+ * `child` we hold is the shell, not the underlying CLI. `child.kill()`
+ * only terminates the shell; the grandchild CLI keeps burning tokens.
+ * Pass `{ shell: true }` here so we signal the whole process group via
+ * `process.kill(-pid, 'SIGTERM')` instead. On Windows we fall back to
+ * `taskkill /T /F /PID`. Prefer `shell: false` invocation when an
+ * abortSignal is in play — fewer moving parts.
+ *
+ * @param {import('child_process').ChildProcess} child - Spawned process.
+ * @param {AbortSignal | null | undefined} signal - Signal to listen on.
+ * @param {Object} [opts]
+ * @param {string} [opts.logPrefix] - Log prefix for diagnostics.
+ * @param {boolean} [opts.shell=false] - True when the child was spawned
+ *   with `shell: true`. Causes group-kill semantics so the grandchild CLI
+ *   dies along with the shell wrapper.
+ * @returns {{cancelled: () => boolean, detach: () => void}}
+ */
+function wireAbortToChild(child, signal, opts = {}) {
+  let cancelled = false;
+  if (!signal) {
+    return { cancelled: () => cancelled, detach: () => {} };
+  }
+  const prefix = opts.logPrefix || '';
+  const isShell = opts.shell === true;
+
+  const killChild = () => {
+    // `kill` / process group signaling returns false (or throws ESRCH) if
+    // the process is already gone, which is fine — we just need the side
+    // effect when it IS still alive.
+    if (isShell && child.pid && process.platform !== 'win32') {
+      // Group-kill the shell AND its CLI descendant. Requires the caller
+      // to have spawned with `detached: true` so the child became a
+      // process-group leader (`-pid` targets the group).
+      try {
+        process.kill(-child.pid, 'SIGTERM');
+        return;
+      } catch (err) {
+        if (err && err.code === 'ESRCH') {
+          // Group already gone — nothing to kill.
+          return;
+        }
+        // Fall through to single-process kill as a best effort.
+        logger.warn(
+          `${prefix} process.kill(-pid) failed (${err.message}); falling back to child.kill`
+        );
+      }
+    }
+    if (isShell && child.pid && process.platform === 'win32') {
+      // Windows has no process groups: spawn taskkill /T /F to wipe the
+      // tree rooted at our shell pid.
+      try {
+        spawn('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' })
+          .on('error', (err) => {
+            logger.warn(`${prefix} taskkill failed: ${err.message}`);
+          });
+        return;
+      } catch (err) {
+        logger.warn(
+          `${prefix} spawn(taskkill) failed (${err.message}); falling back to child.kill`
+        );
+      }
+    }
+    child.kill('SIGTERM');
+  };
+
+  const onAbort = () => {
+    cancelled = true;
+    try {
+      killChild();
+    } catch (err) {
+      logger.warn(`${prefix} child.kill on abort failed: ${err.message}`);
+    }
+  };
+
+  if (signal.aborted) {
+    // Pre-aborted: trigger the kill immediately. The eventual `close`
+    // handler will see `cancelled === true` and short-circuit.
+    onAbort();
+  } else {
+    signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  return {
+    cancelled: () => cancelled,
+    detach: () => {
+      try {
+        signal.removeEventListener('abort', onAbort);
+      } catch {
+        // Older AbortSignal polyfills may lack removeEventListener; safe to ignore.
+      }
+    },
+  };
+}
+
+/**
+ * Build a standardized cancellation error. Providers should throw this
+ * (or reject with it) when they detect the abort wiring fired, so the
+ * BackgroundQueue's broadcast can mark the job as `cancelled: true`.
+ *
+ * @param {string} [message] - Human-readable context (defaults to 'cancelled').
+ * @returns {Error}
+ */
+function makeAbortError(message) {
+  const err = new Error(message || 'cancelled');
+  err.name = 'AbortError';
+  err.isCancellation = true;
+  return err;
+}
+
+module.exports = { wireAbortToChild, makeAbortError };

package/src/ai/background-queue.js

@@ -0,0 +1,290 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const { broadcastReviewEvent } = require('../events/review-events');
+const logger = require('../utils/logger');
+const { makeAbortError } = require('./abort-signal-wiring');
+
+const BACKGROUND_QUEUE_CONCURRENCY = 2;
+
+const defaults = {
+  broadcast: broadcastReviewEvent,
+};
+
+/**
+ * Bounded-concurrency in-process queue with per-key dedup.
+ *
+ * Jobs are keyed by `${reviewId}:${jobType}`; concurrent enqueues
+ * for the same key share a single execution and a single promise.
+ *
+ * Cancellation: each enqueued job is associated with an `AbortController`.
+ * The worker thunk is invoked as `fn(signal)` so it can plumb the signal
+ * into downstream provider calls / `fetch` / `child_process.spawn`.
+ * Callers cancel via `cancel(reviewId, jobKey)`, which aborts the
+ * signal and removes the controller; the worker is expected to react
+ * to the abort and settle (typically by rejecting with an AbortError).
+ */
+class BackgroundQueue {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.concurrency] - Max concurrent jobs.
+   * @param {Object} [options._deps] - Override dependencies (testing).
+   * @param {Function} [options._deps.broadcast] - Broadcast hook.
+   */
+  constructor(options = {}) {
+    const { concurrency = BACKGROUND_QUEUE_CONCURRENCY, _deps = {} } = options;
+    this.concurrency = concurrency;
+    this.active = 0;
+    this.queue = [];
+    this.inFlight = new Map();
+    // Per-key AbortController covers both queued and running jobs so a
+    // single lookup can resolve cancellation against either state.
+    this.controllers = new Map();
+    this._deps = { ...defaults, ..._deps };
+  }
+
+  /**
+   * Enqueue a job for execution.
+   *
+   * Dedup contract: if a job for the same `(reviewId, jobType)` key is
+   * already queued or running, this returns the existing promise without
+   * invoking `fn`. The duplicate `fn` is silently dropped.
+   *
+   * The thunk is called as `fn(signal)` where `signal` is the `AbortSignal`
+   * for this job. Workers that touch the network, spawn processes, or
+   * otherwise burn upstream resources should thread the signal through so
+   * cancellation actually frees those resources.
+   *
+   * @param {string|number} reviewId - Review identifier.
+   * @param {string} jobType - Job category (e.g. 'summaries', 'tour').
+   * @param {Function} fn - Thunk `(signal) => value|Promise<value>`.
+   * @returns {Promise} Resolves/rejects with the job result.
+   */
+  enqueue(reviewId, jobType, fn) {
+    const key = `${reviewId}:${jobType}`;
+    if (this.inFlight.has(key)) {
+      return this.inFlight.get(key);
+    }
+    let resolve;
+    let reject;
+    const p = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.inFlight.set(key, p);
+    const controller = new AbortController();
+    this.controllers.set(key, controller);
+    this.queue.push({
+      key,
+      run: fn,
+      resolve,
+      reject,
+      reviewId,
+      jobType,
+      controller,
+      promise: p,
+    });
+    this._drain();
+    return p;
+  }
+
+  /**
+   * Cancel an in-flight or queued job. Aborts its `AbortSignal` so the
+   * worker can tear down upstream resources, then drops the controller.
+   *
+   * Matching is exact on `(reviewId, jobKey)`. For composite jobTypes
+   * like `summaries:${digest}`, callers may also pass a bare prefix
+   * (`summaries`) — this cancels ALL matching `summaries:*` jobs for the
+   * review. This is what the toolbar "Cancel Summaries" button needs:
+   * users don't know about digests, they just want the pulse to stop.
+   *
+   * @param {string|number} reviewId
+   * @param {string} jobKey - bare `jobType` (e.g. `tour`) or full key
+   *   suffix (e.g. `summaries:abc123`).
+   * @returns {{cancelled: number}} number of jobs aborted.
+   */
+  cancel(reviewId, jobKey) {
+    if (jobKey === undefined || jobKey === null || jobKey === '') {
+      return { cancelled: 0 };
+    }
+    const exact = `${reviewId}:${jobKey}`;
+    const prefix = `${exact}:`;
+    let cancelled = 0;
+    // Snapshot keys before aborting — settling a worker mid-iteration would
+    // mutate this.controllers (via _settle).
+    const keys = Array.from(this.controllers.keys());
+    for (const key of keys) {
+      if (key !== exact && !key.startsWith(prefix)) continue;
+      const controller = this.controllers.get(key);
+      if (!controller) continue;
+      try {
+        controller.abort();
+      } catch (err) {
+        logger.warn(`BackgroundQueue controller.abort() failed for ${key}: ${err.message}`);
+      }
+      // Eagerly evict the cancelled key from the dedup/controller maps and
+      // splice any not-yet-started descriptors out of the queue. Without
+      // this, a follow-up enqueue() for the same key would hit the dedup
+      // guard and inherit the about-to-reject promise, and _drain() could
+      // hand the worker an already-aborted signal. _settle()'s deletes are
+      // identity-guarded, so when the cancelled worker eventually rejects
+      // it won't clobber a replacement job installed under the same key.
+      this._evictKey(key);
+      cancelled++;
+    }
+    return { cancelled };
+  }
+
+  /**
+   * Remove a key from the dedup/controller maps and reject any queued (not
+   * yet started) descriptor with an AbortError. Safe to call when the key
+   * has already been cleaned up — Map.delete and Array.splice both no-op.
+   *
+   * @param {string} key - Composite `${reviewId}:${jobType}` key.
+   * @private
+   */
+  _evictKey(key) {
+    // Splice queued descriptors and reject their promises so the dedup'd
+    // caller (if any) sees a clean cancellation rather than a hung promise.
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      if (this.queue[i].key !== key) continue;
+      const [descriptor] = this.queue.splice(i, 1);
+      try {
+        descriptor.reject(makeAbortError('Job cancelled before start'));
+      } catch (rejectErr) {
+        logger.warn(
+          `BackgroundQueue descriptor.reject failed for ${key}: ${rejectErr.message}`
+        );
+      }
+    }
+    this.inFlight.delete(key);
+    this.controllers.delete(key);
+  }
+
+  /** Start as many queued jobs as concurrency allows. */
+  _drain() {
+    while (this.active < this.concurrency && this.queue.length > 0) {
+      const descriptor = this.queue.shift();
+      this.active++;
+      Promise.resolve()
+        .then(() => descriptor.run(descriptor.controller.signal))
+        .then(
+          (result) => this._settle(descriptor, null, result),
+          (error) => this._settle(descriptor, error, undefined)
+        );
+    }
+  }
+
+  /** Finalize a job: free its key, broadcast, settle, and drain. */
+  _settle(descriptor, error, result) {
+    // Identity-guarded cleanup: if cancel() evicted this descriptor and a
+    // replacement was enqueued under the same key, the maps now point at
+    // the new descriptor's controller/promise — unconditional deletes would
+    // wipe the replacement's bookkeeping (invisible to hasActiveForReview,
+    // immune to cancel, vulnerable to duplicate enqueue).
+    if (this.controllers.get(descriptor.key) === descriptor.controller) {
+      this.controllers.delete(descriptor.key);
+    }
+    if (this.inFlight.get(descriptor.key) === descriptor.promise) {
+      this.inFlight.delete(descriptor.key);
+    }
+    this.active--;
+    this._onComplete(descriptor.reviewId, descriptor.jobType, error);
+    if (error === null) {
+      descriptor.resolve(result);
+    } else {
+      descriptor.reject(error);
+    }
+    this._drain();
+  }
+
+  /**
+   * Is there an in-flight or queued job for this review whose jobType
+   * starts with the given prefix? Useful for surfacing a "generating"
+   * indicator on the frontend (`hasActiveForReview(id, 'summaries')`).
+   *
+   * Job keys are stored as `${reviewId}:${jobType}`; `summaries` jobs use
+   * the form `summaries:${digest}`, so a prefix match on
+   * `${reviewId}:summaries` catches every digest variant.
+   *
+   * @param {string|number} reviewId
+   * @param {string} jobTypePrefix
+   * @returns {boolean}
+   */
+  hasActiveForReview(reviewId, jobTypePrefix) {
+    if (!jobTypePrefix) return false;
+    const prefix = `${reviewId}:${jobTypePrefix}`;
+    for (const key of this.inFlight.keys()) {
+      if (key === prefix || key.startsWith(prefix + ':')) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Like `hasActiveForReview` but returns the in-flight/queued jobType string
+   * (without the `${reviewId}:` prefix), or null. Useful when callers track a
+   * versioned key like `summaries:${digest}` and need to know the *exact* key
+   * to cancel before re-enqueueing under a new digest.
+   *
+   * @param {string|number} reviewId
+   * @param {string} jobTypePrefix
+   * @returns {string|null}
+   */
+  findActiveJobType(reviewId, jobTypePrefix) {
+    if (!jobTypePrefix) return null;
+    const prefix = `${reviewId}:${jobTypePrefix}`;
+    for (const key of this.inFlight.keys()) {
+      if (key === prefix || key.startsWith(prefix + ':')) {
+        return key.slice(String(reviewId).length + 1);
+      }
+    }
+    return null;
+  }
+
+  /** Broadcast job completion; broadcast failures are logged, not thrown. */
+  _onComplete(reviewId, jobType, error) {
+    try {
+      // Include whether more jobs of the same type-prefix remain queued or
+      // in-flight so listeners (e.g. the summaries toolbar pulse) don't
+      // clear their "generating" state when a sibling job is still running.
+      // For composite types like `summaries:${digest}`, we strip the suffix
+      // so the prefix match catches every digest variant.
+      const colonIdx = jobType.indexOf(':');
+      const prefix = colonIdx >= 0 ? jobType.slice(0, colonIdx) : jobType;
+      const hasActiveForType = this.hasActiveForReview(reviewId, prefix);
+      this._deps.broadcast(reviewId, {
+        type: 'review:background_job_finished',
+        jobType,
+        ok: error === null,
+        hasActiveForType,
+        cancelled: isAbortError(error),
+      });
+    } catch (broadcastError) {
+      logger.warn(
+        `BackgroundQueue broadcast failed for ${reviewId}:${jobType}: ${broadcastError.message}`
+      );
+    }
+  }
+}
+
+/**
+ * Recognize errors that originated from `AbortController.abort()`.
+ * Node sets `name === 'AbortError'` on the DOMException for AbortSignal,
+ * but providers that wrap the abort in a custom Error may instead set
+ * `code === 'ABORT_ERR'` or surface `signal.aborted` themselves. Check
+ * the common shapes so the broadcast payload is honest about cancels.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isAbortError(err) {
+  if (!err) return false;
+  if (typeof err !== 'object') return false;
+  if (err.name === 'AbortError') return true;
+  if (err.code === 'ABORT_ERR') return true;
+  if (err.isCancellation === true) return true;
+  return false;
+}
+
+const backgroundQueue = new BackgroundQueue();
+
+module.exports = { BackgroundQueue, backgroundQueue, BACKGROUND_QUEUE_CONCURRENCY, isAbortError };

package/src/ai/claude-cli.js

@@ -100,7 +100,7 @@ class ClaudeCLI {
         }
 
         // Extract JSON from the text response using robust extraction strategies
-        const extracted = extractJSON(stdout, level);
+        const extracted = extractJSON(stdout, level, levelPrefix);
         if (extracted.success) {
           logger.success(`${levelPrefix} Successfully parsed JSON response`);
           resolve(extracted.data);