@in-the-loop-labs/pair-review 3.4.1 → 3.5.0

package/public/js/pr.js

@@ -305,6 +305,21 @@ class PRManager {
       refreshBtn.addEventListener('click', () => this.refreshPR());
     }
 
+    // Refresh external (GitHub) review comments. Handler lives on the
+    // instance so unit tests can call it directly (avoids duplicating the
+    // production click logic in tests, per CLAUDE.md).
+    // Skip wiring entirely when the external_comments feature toggle is
+    // off — the button is also CSS-hidden via .external-comments-only, so
+    // this is belt-and-suspenders.
+    if (this._externalCommentsEnabled()) {
+      const refreshExternalBtnPanel = document.getElementById('refresh-external-comments-btn-panel');
+      if (refreshExternalBtnPanel) {
+        refreshExternalBtnPanel.addEventListener('click', () => {
+          void this._handleExternalCommentsRefreshClick({ button: refreshExternalBtnPanel });
+        });
+      }
+    }
+
     // PR description popover
     this.setupPRDescriptionPopover();
 
@@ -612,6 +627,15 @@ class PRManager {
       // Fire-and-forget staleness check — shows badge or auto-refreshes
       this._stalenessPromise = this._checkStalenessOnLoad(owner, repo, number);
 
+      // Fire-and-forget external review-comment sync + render.
+      // Runs after the diff and user comments have been rendered so the
+      // external-comment manager has DOM anchors to attach blue rows to.
+      // Failures are swallowed inside _loadExternalComments and surface via
+      // console.warn; they must never block the main PR-load path.
+      void this._loadExternalComments().catch((err) => {
+        console.warn('[external-comments] _loadExternalComments threw', err);
+      });
+
     } catch (error) {
       console.error('Error loading PR:', error);
       this.showError(error.message);
@@ -623,16 +647,260 @@ class PRManager {
   }
 
   /**
-   * Reload AI suggestions and user comments after an analysis completes.
-   * Shared by the foreground `analysis_completed` handler and the deferred
-   * `_dirtyAnalysis` branch in the visibilitychange listener.
+   * Sync external review comments against the source system and render the
+   * results. Non-blocking from the user's perspective: a sync failure does
+   * not prevent rendering of any cached rows from a previous run.
+   *
+   * No-op in local mode (external sources require a real GitHub PR).
+   */
+  /**
+   * Re-render every overlay (AI suggestions, user comments, external comments)
+   * after the underlying diff DOM has been rebuilt.
+   *
+   * Used by anything that destroys and re-mounts the diff (refreshPR, the
+   * whitespace toggle, pre-analysis refresh). Centralizing keeps the three
+   * renderers from drifting: each one has its own clear()/append cycle and
+   * forgetting any of them produces hard-to-spot bugs like "comments
+   * disappeared after refresh".
+   *
+   * @param {Object} [options]
+   * @param {string} [options.analysisRunId] - Optional run id to pin AI suggestions to.
+   * @param {boolean} [options.syncExternal=false] - When true, fire the
+   *   external-comments sync POST before re-rendering. Used by `refreshPR`
+   *   where the diff was just fetched fresh from GitHub and cached anchors
+   *   may not match the new commit. GET-only callers (whitespace toggle,
+   *   analysis rebuilds, post-analysis reload) pass the default and reuse
+   *   the existing mirror.
+   */
+  async _rerenderAllOverlays({ analysisRunId, syncExternal = false } = {}) {
+    const includeDismissed = window.aiPanel?.showDismissedComments || false;
+    await this.loadUserComments(includeDismissed);
+    await this.loadAISuggestions(null, analysisRunId);
+    // Skip external-comment re-rendering entirely when the feature is off.
+    // The manager is never populated with rows in that case, so there's
+    // nothing to re-anchor.
+    if (!this._externalCommentsEnabled()) return;
+    try {
+      if (typeof window !== 'undefined' && window.externalCommentManager) {
+        if (this.currentPR && this.currentPR.id) {
+          window.externalCommentManager.reviewId = this.currentPR.id;
+        }
+        if (syncExternal) {
+          // refreshPR path: full sync+load through the canonical entry
+          // point. `_loadExternalComments` already owns the toast + error
+          // wiring for the sync result.
+          await this._loadExternalComments();
+        } else {
+          // GET-only path: the local mirror is current; just re-anchor
+          // rows on the freshly-rebuilt diff DOM.
+          await window.externalCommentManager.loadAndRender();
+        }
+      }
+    } catch (err) {
+      console.warn('[external-comments] re-render after diff rebuild failed', err);
+    }
+  }
+
+  /**
+   * Click handler for the "refresh external comments" header button.
+   *
+   * Extracted from `setupEventListeners` so unit tests can exercise the
+   * production handler directly without re-implementing it (CLAUDE.md
+   * forbids duplicating production code in tests). The DOM button id is
+   * the canonical attach point — pass it in for tests that build their
+   * own button.
+   *
+   * @param {Object} [options]
+   * @param {HTMLElement} [options.button] - The button element to toggle. Defaults to `#refresh-external-comments-btn-panel`.
+   * @returns {Promise<void>}
+   */
+  async _handleExternalCommentsRefreshClick({ button } = {}) {
+    // Defensive guard: even if a stale caller invokes this with the
+    // feature disabled, swallow it. UI wiring already skips this path.
+    if (!this._externalCommentsEnabled()) return;
+    const btn = button
+      || (typeof document !== 'undefined' ? document.getElementById('refresh-external-comments-btn-panel') : null);
+    if (!btn || btn.disabled) return;
+    btn.disabled = true;
+    btn.classList.add('is-refreshing');
+    btn.setAttribute('aria-busy', 'true');
+    btn.removeAttribute('data-state');
+    try {
+      await this._loadExternalComments();
+    } finally {
+      btn.disabled = false;
+      btn.classList.remove('is-refreshing');
+      btn.removeAttribute('aria-busy');
+    }
+  }
+
+  /**
+   * Feature toggle for the external-comments (GitHub PR review-comment)
+   * subsystem. Reads `window.PAIR_REVIEW_RUNTIME_CONFIG` which is set
+   * synchronously by `/runtime-config.js` BEFORE this file loads, so the
+   * check is safe at any call site. Defaults to enabled when the flag is
+   * missing — preserves behavior for any environment that omits the
+   * runtime-config script (e.g., older test fixtures).
+   * @returns {boolean}
+   */
+  _externalCommentsEnabled() {
+    if (typeof window === 'undefined') return true;
+    return window.PAIR_REVIEW_RUNTIME_CONFIG?.external_comments_enabled !== false;
+  }
+
+  async _loadExternalComments() {
+    if (typeof window !== 'undefined' && window.PAIR_REVIEW_LOCAL_MODE) return;
+    if (!this._externalCommentsEnabled()) return;
+    if (!this.currentPR || !this.currentPR.id) return;
+    if (typeof window === 'undefined' || !window.externalCommentManager) return;
+
+    window.externalCommentManager.reviewId = this.currentPR.id;
+
+    // Route through the manager's `syncAndRender`. That method owns the
+    // in-flight guard for the FULL sync+load sequence, so a GET-only
+    // caller (analysis rebuild, whitespace toggle) that hits
+    // `loadAndRender` during this window joins the same promise instead
+    // of racing the POST with a stale GET. The manager surfaces sync
+    // result and sync error separately so this method can fire the
+    // status-aware toasts without intercepting render.
+    let result;
+    try {
+      result = await window.externalCommentManager.syncAndRender({
+        syncFn: () => this._syncExternalComments(),
+      });
+    } catch (err) {
+      console.warn('[external-comments] syncAndRender failed', err);
+      return;
+    }
+
+    if (result && result.syncError) {
+      // Sync failed but render proceeded against the previously-cached
+      // mirror. Toast + button-error cue so the reviewer knows the
+      // counts may lag upstream.
+      this._showExternalSyncErrorToast(result.syncError);
+      this._markExternalRefreshErrorState();
+      console.warn('[external-comments] sync failed; rendering cached data only', result.syncError);
+    } else if (result && result.syncResult && typeof result.syncResult.lostAnchors === 'number' && result.syncResult.lostAnchors > 0) {
+      // Surface lost-anchor counts so the reviewer knows why visible
+      // external-comment counts may lag what GitHub shows — these are
+      // comments whose anchors were destroyed upstream (force-push, file
+      // delete, etc.) and have no place to render in the current diff.
+      this._showExternalLostAnchorsToast(result.syncResult.lostAnchors);
+    }
+  }
+
+  /**
+   * Pick a toast message by HTTP status for a failed external-comment sync.
+   * Falls back to a generic message when status is missing or unknown.
+   * @private
+   */
+  _showExternalSyncErrorToast(err) {
+    const status = err && typeof err.status === 'number' ? err.status : 0;
+    let message;
+    if (status === 401) {
+      message = 'GitHub token missing or invalid — external comments not refreshed.';
+    } else if (status === 403) {
+      message = 'GitHub denied the request (403) — external comments not refreshed.';
+    } else if (status === 429) {
+      message = 'GitHub rate limited — external comments not refreshed.';
+    } else {
+      message = 'Could not refresh GitHub review comments.';
+    }
+    try {
+      if (typeof window !== 'undefined') {
+        if (window.toast && typeof window.toast.showError === 'function') {
+          window.toast.showError(message);
+          return;
+        }
+        if (typeof window.showToast === 'function') {
+          window.showToast(message, 'error');
+          return;
+        }
+      }
+    } catch {
+      // toast helpers must never break the page; swallow.
+    }
+  }
+
+  /**
+   * Show a warning toast describing how many external comments couldn't be
+   * anchored to the current diff (lost-anchor count from the sync result).
+   * Mirrors `_showExternalSyncErrorToast` so failures and partial successes
+   * have symmetrical UI treatment.
+   * @param {number} count - Number of lost-anchor comments
+   * @private
+   */
+  _showExternalLostAnchorsToast(count) {
+    if (typeof window === 'undefined') return;
+    const noun = count === 1 ? 'comment' : 'comments';
+    const message = `${count} ${noun} lost their anchor due to upstream changes`;
+    try {
+      if (window.toast && typeof window.toast.showWarning === 'function') {
+        window.toast.showWarning(message);
+        return;
+      }
+      if (window.toast && typeof window.toast.showInfo === 'function') {
+        window.toast.showInfo(message);
+        return;
+      }
+      if (typeof window.showToast === 'function') {
+        window.showToast(message, 'warn');
+        return;
+      }
+    } catch {
+      // toast helpers must never break the page; swallow.
+    }
+  }
+
+  /**
+   * Briefly mark the refresh button so the user notices the failure even if
+   * they dismissed the toast. Cleared after 4s; no state machine — best
+   * effort cue. No-op when the button isn't present.
+   * @private
+   */
+  _markExternalRefreshErrorState() {
+    if (typeof document === 'undefined') return;
+    const btn = document.getElementById('refresh-external-comments-btn-panel');
+    if (!btn) return;
+    btn.setAttribute('data-state', 'error');
+    setTimeout(() => {
+      if (btn.getAttribute('data-state') === 'error') {
+        btn.removeAttribute('data-state');
+      }
+    }, 4000);
+  }
+
+  /**
+   * POST to the sync endpoint for the GitHub source. Coalesced server-side
+   * for concurrent (review, source) calls; safe to invoke from page-load and
+   * the manual refresh button in parallel.
+   * @returns {Promise<{ count: number, lostAnchors: number, syncedAt: string }>}
+   */
+  async _syncExternalComments() {
+    const source = 'github';
+    const res = await fetch(
+      `/api/reviews/${this.currentPR.id}/external-comments/sync?source=${source}`,
+      { method: 'POST' }
+    );
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      const err = new Error(body.error || `Sync failed with status ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return res.json();
+  }
+
+  /**
+   * Reload AI suggestions, user comments, and external comments after an
+   * analysis completes. Shared by the foreground `analysis_completed`
+   * handler and the deferred `_dirtyAnalysis` branch in the
+   * visibilitychange listener. Routing through `_rerenderAllOverlays`
+   * keeps external-comment rows in sync with the other two overlays
+   * whenever post-analysis refresh fires.
    */
   _reloadAfterAnalysis() {
-    const includeDismissed = window.aiPanel?.showDismissedComments ?? false;
-    return Promise.all([
-      this.loadAISuggestions(),
-      this.loadUserComments(includeDismissed)
-    ]);
+    return this._rerenderAllOverlays();
   }
 
   /**
@@ -842,10 +1110,11 @@ class PRManager {
     // Re-fetch and re-render the diff
     await this.loadAndDisplayFiles(owner, repo, number);
 
-    // Re-anchor comments and suggestions on the fresh DOM
-    const includeDismissed = window.aiPanel?.showDismissedComments || false;
-    await this.loadUserComments(includeDismissed);
-    await this.loadAISuggestions(null, this.selectedRunId);
+    // Re-anchor every overlay (user comments, AI suggestions, external
+    // comments) via the shared helper so the three renderers can't drift.
+    // The diff DOM was just rebuilt, so external-comment rows are gone
+    // until loadAndRender re-inserts them.
+    await this._rerenderAllOverlays({ analysisRunId: this.selectedRunId });
 
     // Restore scroll position after the DOM settles
     requestAnimationFrame(() => {
@@ -5221,14 +5490,22 @@ class PRManager {
         // Reload the files/diff with fresh data
         await this.loadAndDisplayFiles(owner, repo, number);
 
-        // Re-render comments and AI suggestions on the fresh DOM
-        // (renderDiff clears the diff container, so we must re-populate)
-        const includeDismissed = window.aiPanel?.showDismissedComments || false;
-        await this.loadUserComments(includeDismissed);
-        // Note: Unlike loadPR() which skips this when analysisHistoryManager exists
-        // (because the manager triggers loadAISuggestions via onSelectionChange on init),
-        // refresh must call unconditionally since the manager won't re-fire its callback.
-        await this.loadAISuggestions(null, this.selectedRunId);
+        // Re-render the three independent overlay layers on the fresh DOM
+        // (renderDiff clears the diff container). Going through the shared
+        // helper guarantees the three renderers can't drift again — adding
+        // a fourth overlay only requires updating this one place.
+        // `syncExternal: true` because refreshPR fetched a brand-new diff
+        // (commit SHA may have changed). Cached external-comment anchors
+        // need a sync POST to re-evaluate which ones are outdated against
+        // the new HEAD — otherwise we'd render stale `is_outdated` flags.
+        // Note: Unlike loadPR() which skips loadAISuggestions when
+        // analysisHistoryManager exists (because the manager triggers it via
+        // onSelectionChange on init), refresh must call unconditionally
+        // since the manager won't re-fire its callback.
+        await this._rerenderAllOverlays({
+          analysisRunId: this.selectedRunId,
+          syncExternal: true,
+        });
 
         // Restore expanded folders
         this.expandedFolders = expandedFolders;

package/public/local.html

@@ -525,11 +525,20 @@
 
                     <!-- Segment Control -->
                     <div class="segment-control" id="segment-control">
-                        <div class="segment-control-inner">
-                            <button class="segment-btn active" data-segment="ai">AI <span class="segment-count">(0)</span></button>
-                            <button class="segment-btn" data-segment="comments">User <span class="segment-count">(0)</span></button>
-                            <button class="segment-btn" data-segment="all">All <span class="segment-count">(0)</span></button>
+                        <button type="button" class="segment-scroll segment-scroll--left" id="segment-scroll-left" hidden aria-label="Scroll segments left" tabindex="-1">
+                            <svg viewBox="0 0 16 16" width="12" height="12" fill="currentColor" aria-hidden="true"><path d="M9.78 12.78a.75.75 0 0 1-1.06 0L4.47 8.53a.75.75 0 0 1 0-1.06l4.25-4.25a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L6.06 8l3.72 3.72a.75.75 0 0 1 0 1.06Z"/></svg>
+                        </button>
+                        <div class="segment-control-scroll" id="segment-control-scroll">
+                            <div class="segment-control-inner">
+                                <button class="segment-btn active" data-segment="ai">AI <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="comments">User <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="external" hidden>External <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="all">All <span class="segment-count">(0)</span></button>
+                            </div>
                         </div>
+                        <button type="button" class="segment-scroll segment-scroll--right" id="segment-scroll-right" hidden aria-label="Scroll segments right" tabindex="-1">
+                            <svg viewBox="0 0 16 16" width="12" height="12" fill="currentColor" aria-hidden="true"><path d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06Z"/></svg>
+                        </button>
                     </div>
 
                     <!-- Level Filter -->
@@ -543,7 +552,9 @@
                     <!-- Findings Summary -->
                     <div class="findings-summary" id="findings-summary">
                         <div class="findings-header">
-                            <span class="findings-count" id="findings-count">0 items</span>
+                            <!-- Nav controls (prev | n of N | next) are injected by AIPanel.updateFindingsHeader.
+                                 Local mode has no external comments, so the actions slot stays empty. -->
+                            <div class="findings-nav" id="findings-nav"></div>
                         </div>
                         <div class="findings-list" id="findings-list">
                             <div class="findings-empty">
@@ -641,6 +652,11 @@
         window.PAIR_REVIEW_LOCAL_MODE = true;
     </script>
 
+    <!-- Runtime configuration: sets window.PAIR_REVIEW_RUNTIME_CONFIG and
+         the `external-comments-disabled` class on documentElement before
+         pr.js / AIPanel initialise. Must load BEFORE pr.js. -->
+    <script src="/runtime-config.js"></script>
+
     <!-- PR JavaScript (shared with local mode) -->
     <script src="/js/pr.js"></script>
 

package/public/pr.html

@@ -321,11 +321,20 @@
 
                     <!-- Segment Control -->
                     <div class="segment-control" id="segment-control">
-                        <div class="segment-control-inner">
-                            <button class="segment-btn active" data-segment="ai">AI <span class="segment-count">(0)</span></button>
-                            <button class="segment-btn" data-segment="comments">User <span class="segment-count">(0)</span></button>
-                            <button class="segment-btn" data-segment="all">All <span class="segment-count">(0)</span></button>
+                        <button type="button" class="segment-scroll segment-scroll--left" id="segment-scroll-left" hidden aria-label="Scroll segments left" tabindex="-1">
+                            <svg viewBox="0 0 16 16" width="12" height="12" fill="currentColor" aria-hidden="true"><path d="M9.78 12.78a.75.75 0 0 1-1.06 0L4.47 8.53a.75.75 0 0 1 0-1.06l4.25-4.25a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L6.06 8l3.72 3.72a.75.75 0 0 1 0 1.06Z"/></svg>
+                        </button>
+                        <div class="segment-control-scroll" id="segment-control-scroll">
+                            <div class="segment-control-inner">
+                                <button class="segment-btn active" data-segment="ai">AI <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="comments">User <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="external">External <span class="segment-count">(0)</span></button>
+                                <button class="segment-btn" data-segment="all">All <span class="segment-count">(0)</span></button>
+                            </div>
                         </div>
+                        <button type="button" class="segment-scroll segment-scroll--right" id="segment-scroll-right" hidden aria-label="Scroll segments right" tabindex="-1">
+                            <svg viewBox="0 0 16 16" width="12" height="12" fill="currentColor" aria-hidden="true"><path d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06Z"/></svg>
+                        </button>
                     </div>
 
                     <!-- Level Filter -->
@@ -339,7 +348,16 @@
                     <!-- Findings Summary -->
                     <div class="findings-summary" id="findings-summary">
                         <div class="findings-header">
-                            <span class="findings-count" id="findings-count">0 items</span>
+                            <!-- Nav controls (prev | n of N | next) are injected by AIPanel.updateFindingsHeader.
+                                 Kept as a static slot so the sibling actions container survives re-render. -->
+                            <div class="findings-nav" id="findings-nav"></div>
+                            <div class="findings-header-actions">
+                                <button class="findings-nav-btn btn-refresh-external-comments external-comments-only" id="refresh-external-comments-btn-panel" title="Refresh GitHub comments" aria-label="Refresh GitHub comments">
+                                    <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12" aria-hidden="true">
+                                        <path d="M1.705 8.005a.75.75 0 0 1 .834.656 5.5 5.5 0 0 0 9.592 2.97l-1.204-1.204a.25.25 0 0 1 .177-.427h3.646a.25.25 0 0 1 .25.25v3.646a.25.25 0 0 1-.427.177l-1.38-1.38A7.002 7.002 0 0 1 1.05 8.84a.75.75 0 0 1 .656-.834ZM8 2.5a5.487 5.487 0 0 0-4.131 1.869l1.204 1.204A.25.25 0 0 1 4.896 6H1.25A.25.25 0 0 1 1 5.75V2.104a.25.25 0 0 1 .427-.177l1.38 1.38A7.002 7.002 0 0 1 14.95 7.16a.75.75 0 0 1-1.49.178A5.5 5.5 0 0 0 8 2.5Z"/>
+                                    </svg>
+                                </button>
+                            </div>
                         </div>
                         <div class="findings-list" id="findings-list">
                             <div class="findings-empty">
@@ -429,9 +447,17 @@
     <!-- Chat Panel Component -->
     <script src="/js/components/ChatPanel.js"></script>
 
+    <!-- External review-comment renderer (must load after chat-panel + comment-manager) -->
+    <script src="/js/modules/external-comment-manager.js"></script>
+
     <!-- Panel Group Component -->
     <script src="/js/components/PanelGroup.js"></script>
 
+    <!-- Runtime configuration: sets window.PAIR_REVIEW_RUNTIME_CONFIG and
+         the `external-comments-disabled` class on documentElement before
+         pr.js / AIPanel initialise. Must load BEFORE pr.js. -->
+    <script src="/runtime-config.js"></script>
+
     <!-- PR JavaScript -->
     <script src="/js/pr.js"></script>
 </body>

package/src/chat/chat-providers.js

@@ -118,6 +118,9 @@ function getChatProvider(id) {
     };
     if (overrides.model) provider.model = overrides.model;
     if (overrides.provider) provider.provider = overrides.provider;
+    if (overrides.availability_command !== undefined) {
+      provider.availability_command = overrides.availability_command;
+    }
     if (overrides.extra_args && Array.isArray(overrides.extra_args)) {
       provider.args = [...provider.args, ...overrides.extra_args];
     }
@@ -136,6 +139,9 @@ function getChatProvider(id) {
   if (overrides.command) merged.command = overrides.command;
   if (overrides.model) merged.model = overrides.model;
   if (overrides.provider) merged.provider = overrides.provider;
+  if (overrides.availability_command !== undefined) {
+    merged.availability_command = overrides.availability_command;
+  }
   if (overrides.env) merged.env = { ...merged.env, ...overrides.env };
   if (overrides.args) {
     merged.args = overrides.args;
@@ -197,8 +203,10 @@ function isCodexProvider(id) {
 
 /**
  * Check availability of a single chat provider.
- * For Pi, delegates to the existing AI provider availability cache.
- * For ACP providers, spawns `<command> --version` to verify the binary exists.
+ * Providers with `availability_command` run that command first.
+ * Without an availability command, Pi delegates to the existing AI provider
+ * availability cache and other providers spawn `<command> --version` to verify
+ * the binary exists.
  * @param {string} id - Provider ID
  * @param {Object} [_deps] - Dependency overrides for testing
  * @returns {Promise<{available: boolean, error?: string}>}
@@ -209,6 +217,19 @@ async function checkChatProviderAvailability(id, _deps) {
     return { available: false, error: `Unknown provider: ${id}` };
   }
 
+  const deps = { ...defaults, ..._deps };
+
+  if (provider.availability_command) {
+    return runCommandAvailabilityCheck({
+      deps,
+      command: provider.availability_command,
+      args: [],
+      displayCommand: 'availability command',
+      shell: true,
+      env: provider.env,
+    });
+  }
+
   // Pi delegates to existing AI provider availability
   if (provider.type === 'pi') {
     const cached = getCachedAvailability('pi');
@@ -218,30 +239,61 @@ async function checkChatProviderAvailability(id, _deps) {
   // Codex uses the same binary-check pattern as ACP providers
   // (falls through to the spawn check below)
 
-  const deps = { ...defaults, ..._deps };
   const command = provider.command;
   const useShell = provider.useShell || false;
 
+  // For multi-word commands, use shell mode
+  const spawnCmd = useShell ? `${command} --version` : command;
+  const spawnArgs = useShell ? [] : ['--version'];
+  return runCommandAvailabilityCheck({
+    deps,
+    command: spawnCmd,
+    args: spawnArgs,
+    displayCommand: `${command} --version`,
+    shell: useShell,
+    env: provider.env,
+  });
+}
+
+/**
+ * Spawn a command and resolve based on its exit status. Shared by the
+ * configured `availability_command` path and the legacy `<command> --version`
+ * fallback.
+ *
+ * Notes on the option choices:
+ * - `stdio: ['ignore', 'ignore', 'ignore']` discards output so a verbose probe
+ *   cannot fill an OS pipe buffer and block while waiting for a reader.
+ * - `shell: true` allows multi-word configured commands to run through the
+ *   user's shell.
+ * - `once()` avoids leaking listeners or resolving twice if multiple child
+ *   process events fire.
+ * - `displayCommand` is used in error messages so user-configured shell strings
+ *   do not need to be printed verbatim.
+ *
+ * @param {{deps: {spawn: Function}, command: string, args: string[], displayCommand: string, shell: boolean, env?: Object}} opts
+ * @returns {Promise<{available: boolean, error?: string}>}
+ */
+function runCommandAvailabilityCheck({ deps, command, args, displayCommand, shell, env }) {
   return new Promise((resolve) => {
     try {
-      // For multi-word commands, use shell mode
-      const spawnCmd = useShell ? `${command} --version` : command;
-      const spawnArgs = useShell ? [] : ['--version'];
-      const proc = deps.spawn(spawnCmd, spawnArgs, {
-        stdio: ['ignore', 'pipe', 'pipe'],
+      const proc = deps.spawn(command, args, {
+        stdio: ['ignore', 'ignore', 'ignore'],
         timeout: 10000,
-        shell: useShell,
+        shell,
+        env: { ...process.env, ...(env || {}) },
       });
 
-      proc.on('error', (err) => {
+      proc.once('error', (err) => {
         resolve({ available: false, error: err.message });
       });
 
-      proc.on('close', (code) => {
+      proc.once('close', (code, signal) => {
         if (code === 0) {
           resolve({ available: true });
+        } else if (signal) {
+          resolve({ available: false, error: `${displayCommand} timed out or was terminated (${signal})` });
         } else {
-          resolve({ available: false, error: `${command} --version exited with code ${code}` });
+          resolve({ available: false, error: `${displayCommand} exited with code ${code}` });
         }
       });
     } catch (err) {

package/src/config.js

@@ -39,7 +39,8 @@ const DEFAULT_CONFIG = {
   assisted_by_url: "https://github.com/in-the-loop-labs/pair-review",  // URL for "Review assisted by" footer link
   hooks: {},  // Hook commands per event: { "review.started": { "my_hook": { "command": "..." } } }
   enable_graphite: false,  // When true, shows Graphite links alongside GitHub links
-  skip_update_notifier: false  // When true, suppresses the "update available" notification on exit
+  skip_update_notifier: false,  // When true, suppresses the "update available" notification on exit
+  external_comments: false  // Opt-in: set to true to enable GitHub PR review-comment sync (External segment, refresh button, /api/reviews/*/external-comments routes)
 };
 
 /**