@in-the-loop-labs/pair-review 3.7.0 → 3.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",

package/public/css/pr.css

@@ -1661,6 +1661,23 @@
   scroll-margin-top: var(--toolbar-height, 0px);
 }
 
+/* Suggestion / finding / comment / chat-line navigation lands the target at
+   the TOP of the diff panel (scrollIntoView block:'start'). Offset it below
+   the sticky toolbar AND the sticky file header so it isn't hidden behind
+   them. `--diff-file-header-height` is measured in JS (_measureFileHeaderHeight)
+   with a sane fallback. Suppressed during a tour, which scrolls to center and
+   manages its own sticky offsets. */
+:root {
+  --diff-scroll-offset: calc(var(--toolbar-height, 0px) + var(--diff-file-header-height, 38px));
+}
+body:not(.tour-active) .d2h-file-wrapper tr,
+body:not(.tour-active) .ai-suggestion,
+body:not(.tour-active) .file-comment-card,
+body:not(.tour-active) .user-comment-row,
+body:not(.tour-active) .external-comment-row {
+  scroll-margin-top: var(--diff-scroll-offset);
+}
+
 /* Hide diff content when collapsed */
 .d2h-file-wrapper.collapsed .d2h-file-body,
 .d2h-file-wrapper.collapsed .d2h-diff-table {

package/public/js/components/AIPanel.js

@@ -44,6 +44,10 @@ class AIPanel {
         // Track selected item by stable identifier for restoration
         this.selectedItemKey = null; // Format: "file:lineNumber:itemType:identity"
 
+        // Monotonic token so a fast move between items that supersedes an
+        // in-flight scrollTo* can tell the older call to bail after its await.
+        this._navGen = 0;
+
         // Canonical file order for consistent sorting across components
         this.fileOrder = new Map(); // Map of file path -> index
 
@@ -1178,9 +1182,18 @@ class AIPanel {
     /**
      * Scroll to an AI finding/suggestion in the diff view
      */
-    scrollToFinding(findingId, file, line) {
+    async scrollToFinding(findingId, file, line) {
+        const myGen = ++this._navGen;
         // Expand the file first if it's collapsed
         const expansion = this.expandFileIfCollapsed(file);
+        if (expansion && typeof expansion.then === 'function') await expansion;
+        // Always render the target's lazy body — an expanded-but-offscreen
+        // body has no suggestion rows until rendered, so the lookup below
+        // would miss on the first attempt (expansion only covers the
+        // collapsed case).
+        if (file && window.prManager?.ensureFileBodyRendered) {
+            try { await window.prManager.ensureFileBodyRendered(file); } catch { /* best effort */ }
+        }
 
         const doScroll = () => {
             let targetSuggestion = null;
@@ -1216,36 +1229,54 @@ class AIPanel {
 
             if (targetSuggestion) {
                 const minimizer = window.prManager?.commentMinimizer;
+                let scrollTarget = targetSuggestion;
                 if (minimizer?.active) {
                     // Expand file-level comments so the target becomes visible
                     minimizer.expandForElement(targetSuggestion);
                     // Comments are minimized — scroll to the parent diff line instead
-                    const diffRow = minimizer.findDiffRowFor(targetSuggestion);
-                    (diffRow || targetSuggestion).scrollIntoView({ behavior: 'smooth', block: 'center' });
-                } else {
-                    targetSuggestion.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                    scrollTarget = minimizer.findDiffRowFor(targetSuggestion) || targetSuggestion;
                 }
+                this._scrollDiffTarget(scrollTarget);
                 targetSuggestion.classList.add('current-suggestion');
                 setTimeout(() => targetSuggestion.classList.remove('current-suggestion'), 2000);
             }
         };
 
-        // When expansion routed through the async lazy-body render, wait for it
-        // to settle so the row lookup runs against a rendered, visible body.
-        // Otherwise scroll synchronously (fast path: file already expanded).
-        if (expansion && typeof expansion.then === 'function') {
-            expansion.then(doScroll);
+        // A newer navigation took over while we awaited — let it win.
+        if (myGen !== this._navGen) return;
+        doScroll();
+    }
+
+    /**
+     * Scroll a diff-panel element into view, preferring the stable helper
+     * (re-corrects after lazy file bodies render mid-scroll and shift
+     * layout). Fire-and-forget.
+     * @param {Element} target
+     */
+    _scrollDiffTarget(target) {
+        // Land the target at the top of the diff panel (scroll-margin-top in
+        // pr.css offsets it below the sticky toolbar + file header).
+        const options = { behavior: 'smooth', block: 'start' };
+        if (window.ScrollUtils?.scrollIntoViewStable) {
+            window.ScrollUtils.scrollIntoViewStable(target, options);
         } else {
-            doScroll();
+            target.scrollIntoView(options);
         }
     }
 
     /**
      * Scroll to a user comment in the diff view
      */
-    scrollToComment(commentId, file, line) {
+    async scrollToComment(commentId, file, line) {
+        const myGen = ++this._navGen;
         // Expand the file first if it's collapsed
         const expansion = this.expandFileIfCollapsed(file);
+        if (expansion && typeof expansion.then === 'function') await expansion;
+        // Always render the target's lazy body — comment rows don't exist
+        // inside an unrendered body, so the lookup below would miss.
+        if (file && window.prManager?.ensureFileBodyRendered) {
+            try { await window.prManager.ensureFileBodyRendered(file); } catch { /* best effort */ }
+        }
 
         const doScroll = () => {
             let targetElement = null;
@@ -1288,13 +1319,13 @@ class AIPanel {
 
             if (targetElement) {
                 const minimizer = window.prManager?.commentMinimizer;
+                let scrollTarget = targetElement;
                 if (minimizer?.active) {
                     minimizer.expandForElement(targetElement);
                     const diffRow = isFileLevel ? null : minimizer.findDiffRowFor(targetElement);
-                    (diffRow || targetElement).scrollIntoView({ behavior: 'smooth', block: 'center' });
-                } else {
-                    targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                    scrollTarget = diffRow || targetElement;
                 }
+                this._scrollDiffTarget(scrollTarget);
                 // Add highlight effect
                 const commentDiv = isFileLevel ? targetElement : targetElement.querySelector('.user-comment');
                 if (commentDiv) {
@@ -1304,13 +1335,9 @@ class AIPanel {
             }
         };
 
-        // Await the async lazy-body render when expansion triggered one;
-        // scroll synchronously otherwise.
-        if (expansion && typeof expansion.then === 'function') {
-            expansion.then(doScroll);
-        } else {
-            doScroll();
-        }
+        // A newer navigation took over while we awaited — let it win.
+        if (myGen !== this._navGen) return;
+        doScroll();
     }
 
     /**
@@ -1325,9 +1352,16 @@ class AIPanel {
      * @param {string} file - File path for collapse-expand fallback
      * @param {string|number} line - Anchor line; used for file/line fallback
      */
-    scrollToExternalThread(threadId, source, file, line) {
+    async scrollToExternalThread(threadId, source, file, line) {
+        const myGen = ++this._navGen;
         // Expand the file first if it's collapsed
         const expansion = this.expandFileIfCollapsed(file);
+        if (expansion && typeof expansion.then === 'function') await expansion;
+        // Always render the target's lazy body — external thread rows don't
+        // exist inside an unrendered body, so the lookup below would miss.
+        if (file && window.prManager?.ensureFileBodyRendered) {
+            try { await window.prManager.ensureFileBodyRendered(file); } catch { /* best effort */ }
+        }
 
         const doScroll = () => {
             let target = null;
@@ -1368,13 +1402,12 @@ class AIPanel {
 
             if (target) {
                 const minimizer = window.prManager?.commentMinimizer;
+                let scrollTarget = target;
                 if (minimizer?.active) {
                     minimizer.expandForElement(target);
-                    const diffRow = minimizer.findDiffRowFor(target);
-                    (diffRow || target).scrollIntoView({ behavior: 'smooth', block: 'center' });
-                } else {
-                    target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                    scrollTarget = minimizer.findDiffRowFor(target) || target;
                 }
+                this._scrollDiffTarget(scrollTarget);
 
                 // Transient focus flash. The class is removed after 2s — if
                 // the row is rebuilt before then, the class is lost with it,
@@ -1384,13 +1417,9 @@ class AIPanel {
             }
         };
 
-        // Await the async lazy-body render when expansion triggered one;
-        // scroll synchronously otherwise.
-        if (expansion && typeof expansion.then === 'function') {
-            expansion.then(doScroll);
-        } else {
-            doScroll();
-        }
+        // A newer navigation took over while we awaited — let it win.
+        if (myGen !== this._navGen) return;
+        doScroll();
     }
 
     // ========================================

package/public/js/components/ChatPanel.js

@@ -4613,7 +4613,17 @@ class ChatPanel {
     const isVisible = rect.top >= 0 && rect.bottom <= window.innerHeight;
 
     if (!isVisible) {
-      primaryRow.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      // Stable variant re-corrects after lazy file bodies render mid-scroll
+      // and shift the layout (plain scrollIntoView lands off target the
+      // first time on large diffs). Fire-and-forget.
+      // Land the target at the top of the diff panel (scroll-margin-top in
+      // pr.css offsets it below the sticky toolbar + file header).
+      const scrollOptions = { behavior: 'smooth', block: 'start' };
+      if (window.ScrollUtils?.scrollIntoViewStable) {
+        window.ScrollUtils.scrollIntoViewStable(primaryRow, scrollOptions);
+      } else {
+        primaryRow.scrollIntoView(scrollOptions);
+      }
     }
 
     // Apply the highlight to all target rows

package/public/js/components/SuggestionNavigator.js

@@ -10,7 +10,10 @@ class SuggestionNavigator {
     this.isCollapsed = this.loadCollapsedState();
     this.element = null;
     this.collapseToggle = null;
-    
+    // Monotonic token so a fast Next/Prev that supersedes an in-flight
+    // goToSuggestion can tell the older call to bail after its await.
+    this._navGen = 0;
+
     this.init();
     this.bindEvents();
   }
@@ -236,7 +239,7 @@ class SuggestionNavigator {
   /**
    * Navigate to specific suggestion by index
    */
-  goToSuggestion(index) {
+  async goToSuggestion(index) {
     if (index < 0 || index >= this.suggestions.length) {
       return;
     }
@@ -244,10 +247,42 @@ class SuggestionNavigator {
     this.currentSuggestionIndex = index;
     this.updateCounter();
     this.updateNavigationButtons();
+    // The suggestion's row only exists once its file body has rendered
+    // (lazy bodies start empty), so render it before the highlight/scroll
+    // lookups below — otherwise both silently miss on the first attempt.
+    // A collapsed file is expanded first so the row is actually visible.
+    const myGen = ++this._navGen;
+    await this.ensureSuggestionVisible(this.suggestions[index]);
+    // A newer goToSuggestion ran while we awaited and moved
+    // this.currentSuggestionIndex — let it own the highlight/scroll.
+    if (myGen !== this._navGen) return;
     this.highlightCurrentSuggestion();
     this.scrollToSuggestion();
   }
 
+  /**
+   * Make sure a suggestion's file is expanded and its lazy diff body is
+   * rendered so the suggestion row exists in the DOM. Best effort: any
+   * failure falls through to the old lookup-miss behavior.
+   * @param {Object} suggestion
+   */
+  async ensureSuggestionVisible(suggestion) {
+    const file = suggestion?.file;
+    const pm = window.prManager;
+    if (!file || !pm) return;
+    try {
+      const wrapper = pm.findFileElement?.(file);
+      if (wrapper?.classList.contains('collapsed') && pm.toggleFileCollapse) {
+        // Renders the lazy body and removes `collapsed`.
+        await pm.toggleFileCollapse(wrapper.dataset.fileName || file);
+      } else if (pm.ensureFileBodyRendered) {
+        await pm.ensureFileBodyRendered(file);
+      }
+    } catch (err) {
+      console.warn('[SuggestionNavigator] could not prepare suggestion file', file, err);
+    }
+  }
+
   /**
    * Check if a suggestion should be skipped during navigation
    */
@@ -370,18 +405,22 @@ class SuggestionNavigator {
       
       if (suggestionEl) {
         const minimizer = window.prManager?.commentMinimizer;
+        let scrollTarget = suggestionEl;
         if (minimizer?.active) {
           // Expand file-level comments so the target becomes visible
           minimizer.expandForElement(suggestionEl);
           // Comments are minimized — scroll to the parent diff line instead
-          const diffRow = minimizer.findDiffRowFor(suggestionEl);
-          if (diffRow) {
-            diffRow.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
-          } else {
-            suggestionEl.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
-          }
+          scrollTarget = minimizer.findDiffRowFor(suggestionEl) || suggestionEl;
+        }
+        // Land the target at the top of the diff panel (scroll-margin-top in
+        // pr.css offsets it below the sticky toolbar + file header).
+        const options = { behavior: 'smooth', block: 'start', inline: 'nearest' };
+        // Stable variant re-corrects after lazy file bodies render
+        // mid-scroll and shift the layout. Fire-and-forget.
+        if (window.ScrollUtils?.scrollIntoViewStable) {
+          window.ScrollUtils.scrollIntoViewStable(scrollTarget, options);
         } else {
-          suggestionEl.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
+          scrollTarget.scrollIntoView(options);
         }
       }
     }
@@ -474,4 +513,10 @@ class SuggestionNavigator {
 }
 
 // Export for use
-window.SuggestionNavigator = SuggestionNavigator;
+if (typeof window !== 'undefined') {
+  window.SuggestionNavigator = SuggestionNavigator;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = SuggestionNavigator;
+}

package/public/js/modules/tour-renderer.js

@@ -488,10 +488,20 @@ class TourRenderer {
   scrollToStop(index) {
     const row = this._mounted.get(index);
     if (!row || !row.isConnected) return;
-    row.scrollIntoView({
+    const options = {
       behavior: this._reduceMotion ? 'auto' : 'smooth',
       block: 'center'
-    });
+    };
+    // Lazy bodies between the viewport and the stop render as the scroll
+    // passes them, shifting layout so a plain scrollIntoView lands off
+    // target. The stable variant re-corrects once the scroll settles.
+    // Fire-and-forget: it bails on its own if the row unmounts (tour exit)
+    // or the user scrolls.
+    if (window.ScrollUtils?.scrollIntoViewStable) {
+      window.ScrollUtils.scrollIntoViewStable(row, options);
+    } else {
+      row.scrollIntoView(options);
+    }
   }
 
   /**

package/public/js/pr.js

@@ -402,6 +402,22 @@ class PRManager {
     }
   }
 
+  /**
+   * Keep --diff-file-header-height in sync with the rendered sticky file
+   * header so navigation (block:'start' + scroll-margin-top in pr.css) lands
+   * targets just below the header rather than hidden behind it. Headers are
+   * single-line and uniform, so measuring the first one is representative.
+   * Call after renderDiff appends the headers.
+   */
+  _measureFileHeaderHeight() {
+    const header = document.querySelector('.d2h-file-wrapper .d2h-file-header');
+    if (header && header.offsetHeight) {
+      document.documentElement.style.setProperty(
+        '--diff-file-header-height', header.offsetHeight + 'px'
+      );
+    }
+  }
+
   /**
    * Set up event handlers
    */
@@ -1674,8 +1690,12 @@ class PRManager {
       label = 'Exit guided tour';
     } else if (this._tourStops && this._tourStops.length > 0) {
       label = 'Start guided tour';
+    } else if (this._toursAutoGenerate === false) {
+      // No stops yet and auto-generation is off: a click kicks off manual
+      // generation (see startOrToggleTour), so the verb is "Generate".
+      label = 'Generate guided tour';
     } else {
-      label = 'Start guided tour (none available yet)';
+      label = 'Guided tour (none available yet)';
     }
     btn.title = label;
     btn.setAttribute('aria-label', label);
@@ -3323,6 +3343,10 @@ class PRManager {
 
       // NOTE: end-of-file gap validation runs per-file inside _renderFileBodyNow
       // now (bodies render lazily), not once globally here.
+
+      // Measure the now-rendered sticky file header so navigation can offset
+      // targets below it (scroll-margin-top in pr.css).
+      this._measureFileHeaderHeight();
     } else {
       diffContainer.innerHTML = '<div class="no-diff">No files changed</div>';
     }
@@ -6383,7 +6407,16 @@ class PRManager {
       if (!fileWrapper.classList.contains('collapsed')) {
         await this.ensureFileBodyRendered(filePath);
       }
-      fileWrapper.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      // Stable variant: lazy bodies between here and the target render as
+      // the smooth scroll passes them, shifting layout mid-flight. The
+      // helper re-corrects after the scroll settles so the first attempt
+      // lands where the second used to.
+      const scrollOptions = { behavior: 'smooth', block: 'start' };
+      if (window.ScrollUtils?.scrollIntoViewStable) {
+        await window.ScrollUtils.scrollIntoViewStable(fileWrapper, scrollOptions);
+      } else {
+        fileWrapper.scrollIntoView(scrollOptions);
+      }
     }
   }
 
@@ -7750,7 +7783,7 @@ class PRManager {
    * @param {string} file - File path
    * @param {number} [lineStart] - Optional line number to highlight
    */
-  scrollToContextFile(file, lineStart, contextId) {
+  async scrollToContextFile(file, lineStart, contextId) {
     // Use contextId to find a specific chunk tbody within a merged wrapper,
     // or fall back to a standalone wrapper or the file-level wrapper.
     let target;
@@ -7769,23 +7802,30 @@ class PRManager {
     }
     if (!target) return;
 
-    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    // Stable variant ensures the target's lazy body is rendered and
+    // re-corrects after lazy renders along the scroll path shift layout.
+    const scrollOptions = { behavior: 'smooth', block: 'start' };
+    if (window.ScrollUtils?.scrollIntoViewStable) {
+      await window.ScrollUtils.scrollIntoViewStable(target, scrollOptions);
+    } else {
+      target.scrollIntoView(scrollOptions);
+    }
 
     if (lineStart) {
       // Search for the line row within the wrapper (not just the target chunk)
       const wrapper = target.closest('.d2h-file-wrapper') || target;
-      // Brief delay to let scroll settle, then highlight the target line
-      setTimeout(() => {
-        const row = wrapper.querySelector(`tr[data-line-number="${lineStart}"]`);
-        if (row) {
+      // The awaited stable scroll has already settled (and rendered the lazy
+      // body), so the row exists now — highlight it immediately rather than
+      // pulsing on a stale timer that would fire after the scroll completes.
+      const row = wrapper.querySelector(`tr[data-line-number="${lineStart}"]`);
+      if (row) {
+        row.classList.remove('chat-line-highlight');
+        void row.offsetWidth;
+        row.classList.add('chat-line-highlight');
+        row.addEventListener('animationend', () => {
           row.classList.remove('chat-line-highlight');
-          void row.offsetWidth;
-          row.classList.add('chat-line-highlight');
-          row.addEventListener('animationend', () => {
-            row.classList.remove('chat-line-highlight');
-          }, { once: true });
-        }
-      }, 400);
+        }, { once: true });
+      }
     }
   }
 

package/public/js/utils/scroll-into-view.js

@@ -0,0 +1,164 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Stable scroll-into-view for the lazily rendered diff panel.
+ *
+ * Since the large-PR perf fix, expanded file bodies start as empty
+ * placeholders (`minHeight` ≈ patch lines × APPROX_DIFF_LINE_PX) and only
+ * render real rows when an IntersectionObserver sees them near the viewport.
+ * A plain `scrollIntoView()` therefore lands wrong on the first attempt:
+ * the browser computes the destination from placeholder heights, then the
+ * bodies passed during the scroll render and change height, shifting the
+ * target away from where the animation ends. A second attempt "works"
+ * because everything along the path has rendered by then.
+ *
+ * `scrollIntoViewStable()` fixes this by:
+ *   1. Rendering the target's own file body first (rows inside a lazy body
+ *      don't exist until rendered, and its placeholder height is wrong).
+ *   2. Issuing the caller's scroll (smooth behavior preserved).
+ *   3. Waiting for the viewport-relative position of the target to stop
+ *      moving (scroll animation done AND observer-triggered renders settled),
+ *      then re-issuing an instant scroll. If that correction moved the
+ *      target, newly revealed placeholders rendered and shifted layout
+ *      again — so settle and correct again, up to MAX_CORRECTIONS times.
+ *
+ * The settle loop aborts if the user starts scrolling themselves (wheel /
+ * touch / scroll-intent keys) so corrections never fight real input, and
+ * whenever the target leaves the DOM (file list re-render, tour unmount).
+ */
+
+/** Corrective re-scroll attempts after the initial scroll. */
+const MAX_CORRECTIONS = 4;
+/** Position delta (px) treated as "didn't move". */
+const STABLE_PX = 2;
+/** Consecutive same-position frames before the target counts as settled. */
+const SETTLE_FRAMES = 3;
+/** Hard cap on one settle wait — covers the longest smooth animation. */
+const SETTLE_TIMEOUT_MS = 2000;
+
+/** Keys that express scroll intent and should cancel pending corrections. */
+const SCROLL_KEYS = new Set([
+  'ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '
+]);
+
+/**
+ * Latest-scroll-wins token. Every call captures `++activeGeneration`; any
+ * call whose captured value no longer matches has been superseded by a newer
+ * scroll and must bow out so stale settle loops don't fight or snap the
+ * viewport back to an old target.
+ */
+let activeGeneration = 0;
+
+/**
+ * Wait until `target`'s viewport-relative top is unchanged for
+ * SETTLE_FRAMES consecutive animation frames (or SETTLE_TIMEOUT_MS passes).
+ * Resolves early when the target is disconnected or `isCancelled()` trips.
+ * @param {Element} target
+ * @param {() => boolean} isCancelled
+ * @returns {Promise<void>}
+ */
+function waitForStablePosition(target, isCancelled) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    let lastTop = null;
+    let stableFrames = 0;
+    const tick = () => {
+      if (isCancelled() || !target.isConnected || Date.now() - start > SETTLE_TIMEOUT_MS) {
+        resolve();
+        return;
+      }
+      const top = target.getBoundingClientRect().top;
+      if (lastTop !== null && Math.abs(top - lastTop) <= STABLE_PX) {
+        stableFrames += 1;
+        if (stableFrames >= SETTLE_FRAMES) {
+          resolve();
+          return;
+        }
+      } else {
+        stableFrames = 0;
+      }
+      lastTop = top;
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+}
+
+/**
+ * Scroll `target` into view and keep it there while lazy file bodies render.
+ * Safe to call on any element; outside a lazy diff it degrades to one
+ * `scrollIntoView` plus a settle wait. Fire-and-forget friendly.
+ * @param {Element} target - Element to bring into view
+ * @param {ScrollIntoViewOptions} [options] - Passed to the initial scroll;
+ *   corrective re-scrolls force `behavior: 'auto'`.
+ * @returns {Promise<void>} resolves once the position is stable (or aborted)
+ */
+async function scrollIntoViewStable(target, options = {}) {
+  if (!target || !target.isConnected || typeof target.scrollIntoView !== 'function') return;
+
+  // Claim the active-scroll slot. A later call bumps activeGeneration past
+  // ours, at which point isCancelled() trips and this call bows out.
+  const myGen = ++activeGeneration;
+
+  // Render the target's own lazy body first: until then its rows don't
+  // exist and the wrapper's height is the placeholder estimate. Skip
+  // collapsed wrappers — their body is display:none (zero height), so
+  // rendering would pay full renderPatch cost without changing the scroll.
+  // Skip file-level comment/suggestion cards too: they live in
+  // `.file-comments-zone`, which sits above the lazy body, so rendering the
+  // body can't move them — only burn the renderPatch cost we want to avoid.
+  const prManager = (typeof window !== 'undefined') ? window.prManager : null;
+  const wrapper = target.closest?.('.d2h-file-wrapper');
+  if (wrapper && !target.closest?.('.file-comments-zone')
+      && !wrapper.classList.contains('collapsed')
+      && typeof prManager?.ensureFileBodyRendered === 'function') {
+    try {
+      await prManager.ensureFileBodyRendered(wrapper);
+    } catch (err) {
+      console.warn('[ScrollUtils] ensureFileBodyRendered failed; scrolling anyway', err);
+    }
+    if (!target.isConnected || myGen !== activeGeneration) return;
+  }
+
+  // Cancel corrections when the user scrolls on their own OR when a newer
+  // scrollIntoViewStable call supersedes this one (latest-scroll-wins).
+  let cancelled = false;
+  const isCancelled = () => cancelled || myGen !== activeGeneration;
+  const cancel = () => { cancelled = true; };
+  const onKeyDown = (e) => {
+    // Scroll-intent keys are also everyday caret/typing keys inside form
+    // fields — there they mean "move the cursor", not "scroll the page", so
+    // they must not abort the correction loop.
+    if (e.target?.closest?.('input, textarea, select') || e.target?.isContentEditable) return;
+    if (SCROLL_KEYS.has(e.key)) cancelled = true;
+  };
+  window.addEventListener('wheel', cancel, { capture: true, passive: true });
+  window.addEventListener('touchstart', cancel, { capture: true, passive: true });
+  window.addEventListener('keydown', onKeyDown, { capture: true });
+
+  try {
+    target.scrollIntoView(options);
+    for (let i = 0; i < MAX_CORRECTIONS; i++) {
+      await waitForStablePosition(target, isCancelled);
+      if (isCancelled() || !target.isConnected) return;
+      // Re-issue instantly: a no-op when the smooth scroll landed true, a
+      // snap to the real position when lazy renders shifted the layout.
+      const before = target.getBoundingClientRect().top;
+      target.scrollIntoView({ ...options, behavior: 'auto' });
+      if (Math.abs(target.getBoundingClientRect().top - before) <= STABLE_PX) return;
+      // The correction moved us — newly revealed bodies may render and
+      // shift layout once more; loop to settle and verify again.
+    }
+  } finally {
+    window.removeEventListener('wheel', cancel, { capture: true });
+    window.removeEventListener('touchstart', cancel, { capture: true });
+    window.removeEventListener('keydown', onKeyDown, { capture: true });
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.ScrollUtils = { scrollIntoViewStable, waitForStablePosition };
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { scrollIntoViewStable, waitForStablePosition, MAX_CORRECTIONS, STABLE_PX, SETTLE_FRAMES, SETTLE_TIMEOUT_MS };
+}

package/public/local.html

@@ -614,6 +614,9 @@
     <!-- Modal detection (shared by KeyboardShortcuts and PRManager) -->
     <script src="/js/utils/modal-detection.js"></script>
 
+    <!-- Stable scroll-into-view for lazily rendered diff bodies -->
+    <script src="/js/utils/scroll-into-view.js"></script>
+
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
 

package/public/pr.html

@@ -417,6 +417,9 @@
     <!-- Modal detection (shared by KeyboardShortcuts and PRManager) -->
     <script src="/js/utils/modal-detection.js"></script>
 
+    <!-- Stable scroll-into-view for lazily rendered diff bodies -->
+    <script src="/js/utils/scroll-into-view.js"></script>
+
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
 

package/src/ai/claude-provider.js

@@ -26,12 +26,40 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
  * in the constructor's base args; individual models can override this via extra_args
  * (e.g., Haiku uses adaptive thinking for efficiency).
  *
- * Effort support by model (newest CLIs): Opus 4.8 / 4.7 support low|medium|high|
- * xhigh|max; Opus 4.6 & Sonnet 4.6 support low|medium|high|max (no xhigh); Haiku
- * has no effort levels.
+ * Effort support by model (newest CLIs): Fable 5 and Opus 4.8 / 4.7 support
+ * low|medium|high|xhigh|max; Opus 4.6 & Sonnet 4.6 support low|medium|high|max
+ * (no xhigh); Haiku has no effort levels.
  */
 const CLAUDE_MODELS = [
   // ── Thorough tier ───────────────────────────────────────────────────────
+  {
+    id: 'fable',
+    aliases: ['fable-5-xhigh'],
+    cli_model: 'claude-fable-5',
+    env: { CLAUDE_CODE_EFFORT_LEVEL: 'xhigh' },
+    name: 'Fable 5 XHigh',
+    tier: 'thorough',
+    tagline: 'New Model Tier',
+    description: 'Fable 5 (new tier above Opus) with extra-high effort',
+    badge: 'Extra-High Effort',
+    badgeClass: 'badge-power',
+    // Fable 5 is adaptive-thinking-only: an explicit "enabled"/"disabled"
+    // thinking mode is rejected by the API, so override the global
+    // `--thinking enabled` base arg (last occurrence wins in commander).
+    extra_args: ['--thinking', 'adaptive']
+  },
+  {
+    id: 'fable-5-high',
+    cli_model: 'claude-fable-5',
+    env: { CLAUDE_CODE_EFFORT_LEVEL: 'high' },
+    name: 'Fable 5 High',
+    tier: 'thorough',
+    tagline: 'New Model Tier',
+    description: 'Fable 5 with high effort — quicker than XHigh',
+    badge: 'High Effort',
+    badgeClass: 'badge-power',
+    extra_args: ['--thinking', 'adaptive']
+  },
   {
     id: 'opus',
     aliases: ['opus-4.7-xhigh'],

package/src/main.js

@@ -159,8 +159,9 @@ OPTIONS:
                             The web UI also starts for the human reviewer.
     --model <name>          Override the AI model. Claude Code is the default provider.
                             Available models: opus, sonnet, haiku (Claude Code);
-                            also: opus-4.8-xhigh, opus-4.8-high, opus-4.7-xhigh,
-                                  opus-4.7-high, opus-4.6-high, opus-4.6-1m, sonnet-4.6
+                            also: fable-5-xhigh, fable-5-high, opus-4.8-xhigh,
+                                  opus-4.8-high, opus-4.7-xhigh, opus-4.7-high,
+                                  opus-4.6-high, opus-4.6-1m, sonnet-4.6
                             (opus is Opus 4.7 XHigh, the default)
                             or use provider-specific models with Gemini/Codex
     --use-checkout          Use current directory instead of creating worktree

package/src/routes/stack-analysis.js

@@ -19,7 +19,7 @@ const { normalizeRepository } = require('../utils/paths');
 const { mergeInstructions } = require('../utils/instructions');
 const { GitWorktreeManager } = require('../git/worktree');
 const { GitHubClient } = require('../github/client');
-const { getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
+const { getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR, resolveRepoOptions, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
 const { setupStackPR } = require('../setup/stack-setup');
 const Analyzer = require('../ai/analyzer');
 const { getProviderClass, createProvider } = require('../ai/provider');
@@ -166,6 +166,7 @@ const defaults = {
   getGitHubToken,
   resolveHostBinding,
   resolveBindingRepositoryFromPR,
+  resolveRepoOptions,
   setupStackPR,
   Analyzer,
   getProviderClass,
@@ -205,8 +206,23 @@ async function executeStackAnalysis(params) {
   if (!state) return;
 
   try {
+    // 0. Resolve the config-binding key once. It drives both the per-repo
+    //    worktree config (just below) and the host binding (step 3). For
+    //    monorepo-style `url_pattern` configs this differs from the PR
+    //    identity `${owner}/${repo}`.
+    const bindingRepository = deps.resolveBindingRepositoryFromPR(owner, repo, config);
+    // Honor the repo's configured worktree options so stack worktrees match the
+    // non-stack path. This carries through:
+    //  - worktreeConfig (worktree_name_template / worktree_directory) so they
+    //    don't fall back to pair-review's default naming and location, and
+    //  - the checkout script + timeout and sparse-checkout inheritance used
+    //    during per-PR worktree creation (forwarded to createWorktreeForPR).
+    // These derive purely from file config, so DB repo_settings (pool config)
+    // are not needed here.
+    const { worktreeConfig, checkoutScript, checkoutTimeout } = deps.resolveRepoOptions(config, bindingRepository);
+
     // 1. Resolve repositoryPath from trigger worktree
-    const worktreeManager = new deps.GitWorktreeManager(db);
+    const worktreeManager = new deps.GitWorktreeManager(db, worktreeConfig || {});
     let repositoryPath;
     try {
       const owningRepoGit = await worktreeManager.resolveOwningRepo(triggerWorktreePath);
@@ -230,13 +246,13 @@ async function executeStackAnalysis(params) {
       logger.warn(`Bulk git fetch failed, will fetch per-PR: ${fetchError.message}`);
     }
 
-    // 3. Fetch all PR data from GitHub in parallel
-    // Use the per-repo binding so alt-host stack analyses target the right host.
-    // The PR identity (`${owner}/${repo}`) is used for DB rows and worktree
-    // identity. For host-binding lookups we MUST use the config-binding key,
-    // which differs from the PR identity for monorepo-style `url_pattern`
-    // configs (one `repos[...]` entry serves many captured owner/repo pairs).
-    const bindingRepository = deps.resolveBindingRepositoryFromPR(owner, repo, config);
+    // 3. Fetch all PR data from GitHub in parallel.
+    // `bindingRepository` (resolved in step 0) is the config-binding key. We use
+    // it — not the PR identity `${owner}/${repo}` — for host-binding lookups so
+    // alt-host stack analyses target the right host. The two differ for
+    // monorepo-style `url_pattern` configs (one `repos[...]` entry serves many
+    // captured owner/repo pairs). The PR identity is still used for DB rows and
+    // worktree identity.
     const stackBinding = deps.resolveHostBinding(bindingRepository, config);
     const githubToken = stackBinding.token;
     const prDataMap = new Map();
@@ -275,7 +291,16 @@ async function executeStackAnalysis(params) {
 
         const prInfo = { owner, repo, number: prNum };
         const { path: perPRWorktreePath } = await worktreeManager.createWorktreeForPR(
-          prInfo, prData, repositoryPath
+          prInfo, prData, repositoryPath,
+          {
+            checkoutScript,
+            checkoutTimeout,
+            // No checkout script → inherit the trigger worktree's sparse-checkout
+            // layout instead of a full checkout from the repo root. When a script is
+            // configured it sets up sparse-checkout itself, so worktreeSourcePath is
+            // unused (and omitted) in that case.
+            ...(checkoutScript ? {} : { worktreeSourcePath: triggerWorktreePath }),
+          }
         );
         worktreePathMap.set(prNum, perPRWorktreePath);
       } catch (wtError) {
@@ -307,6 +332,7 @@ async function executeStackAnalysis(params) {
           worktreePath: worktreePathMap.get(prNum),
           analysisConfig, stackAnalysisId, state,
           githubToken, binding: stackBinding, prData: prDataMap.get(prNum),
+          worktreeConfig, checkoutScript,
           onAnalysisIdReady
         }).then(result => {
           state.prStatuses.set(prNum, {
@@ -346,6 +372,7 @@ async function executeStackAnalysis(params) {
 async function analyzeStackPR(deps, db, config, {
   owner, repo, repository, bindingRepository, prNum, worktreePath,
   analysisConfig, stackAnalysisId, state, githubToken, binding, prData,
+  worktreeConfig, checkoutScript,
   onAnalysisIdReady
 }) {
   // Build a GitHubClient for analyzer-side dedup pre-fetch. The stack
@@ -357,12 +384,17 @@ async function analyzeStackPR(deps, db, config, {
   if (stackGithubClient) {
     logger.debug(`analyzer githubClient wired for ${owner}/${repo}#${prNum} (stack)`);
   }
-  // 1. Setup PR (generates diff, stores metadata)
-  const worktreeManager = new deps.GitWorktreeManager(db);
+  // 1. Setup PR (expands sparse-checkout, generates diff, stores metadata)
+  // Construct with the repo's resolved worktreeConfig for consistency with the
+  // creation manager. setupStackPR operates against the explicit worktreePath
+  // (diff generation + sparse-cone expansion), so the worktreeConfig naming /
+  // directory options are not exercised today — threading them through guards
+  // against silent latent regressions if that changes.
+  const worktreeManager = new deps.GitWorktreeManager(db, worktreeConfig || {});
   await deps.setupStackPR({
     db, owner, repo, prNumber: prNum,
     githubToken, binding, bindingRepository,
-    worktreePath, worktreeManager, prData
+    worktreePath, worktreeManager, prData, checkoutScript
   });
 
   // 2. Fetch prMetadata from DB

package/src/setup/stack-setup.js

@@ -32,9 +32,12 @@ const logger = require('../utils/logger');
  * @param {string} params.worktreePath - Path to the per-PR worktree
  * @param {import('../git/worktree').GitWorktreeManager} params.worktreeManager - Worktree manager instance
  * @param {Object} [params.prData] - Pre-fetched PR data from GitHub (skips API call when provided)
+ * @param {string|null} [params.checkoutScript] - Repo's configured checkout script, if any. When set,
+ *   the script owns all sparse-checkout setup, so built-in sparse-cone expansion is skipped (mirrors
+ *   the non-stack `pr-setup.js` contract).
  * @returns {Promise<{ reviewId: number, prMetadata: Object, prData: Object, isNew: boolean }>}
  */
-async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, bindingRepository, worktreePath, worktreeManager, prData: prefetchedPRData }) {
+async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, bindingRepository, worktreePath, worktreeManager, prData: prefetchedPRData, checkoutScript }) {
   // `bindingRepository` is accepted so callers (e.g. `executeStackAnalysis`)
   // can thread the resolved config-binding key through to any downstream
   // per-repo lookups added in this function. Currently unused inside this
@@ -56,13 +59,38 @@ async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, b
   const prFiles = await githubClient.fetchPullRequestFiles(owner, repo, prNumber);
   logger.info(`PR #${prNumber} has ${prFiles.length} changed files`);
 
-  // 3. Generate diff in the worktree (SHA-based, works after checkout)
+  // 3. Expand sparse-checkout for PR-changed directories (mirrors pr-setup.js).
+  // Stack worktrees inherit the trigger worktree's sparse-checkout layout, which
+  // may omit directories a sibling PR touches. The SHA-based diff below reads
+  // commit objects (not the working tree) so it is unaffected, but the later
+  // file-context and codebase-context analysis steps DO read files from disk —
+  // an unexpanded cone would silently under-review those files. Expanding here
+  // ensures every PR-changed directory is present on disk.
+  //
+  // IMPORTANT: when a checkout_script is configured the script owns all
+  // sparse-checkout setup, so we must NOT auto-expand — doing so would override
+  // the cone the script just configured. This matches the pr-setup.js contract.
+  if (!checkoutScript && prFiles.length > 0) {
+    const isSparse = await worktreeManager.isSparseCheckoutEnabled(worktreePath);
+    if (isSparse) {
+      try {
+        const addedDirs = await worktreeManager.ensurePRDirectoriesInSparseCheckout(worktreePath, prFiles);
+        if (addedDirs.length > 0) {
+          logger.info(`Stack PR #${prNumber}: expanded sparse-checkout for: ${addedDirs.join(', ')}`);
+        }
+      } catch (sparseError) {
+        logger.warn(`Stack PR #${prNumber}: sparse-checkout expansion failed (non-fatal): ${sparseError.message}`);
+      }
+    }
+  }
+
+  // 4. Generate diff in the worktree (SHA-based, works after checkout)
   const diff = await worktreeManager.generateUnifiedDiff(worktreePath, prData);
 
-  // 4. Get changed files with stats
+  // 5. Get changed files with stats
   const changedFiles = await worktreeManager.getChangedFiles(worktreePath, prData);
 
-  // 5. Store via storePRData (creates/updates pr_metadata, reviews, worktrees records)
+  // 6. Store via storePRData (creates/updates pr_metadata, reviews, worktrees records)
   const prInfo = { owner, repo, number: prNumber };
   const { isNewReview, reviewId } = await storePRData(db, prInfo, prData, diff, changedFiles, worktreePath);