ghcrawl 0.4.0 → 0.6.0

package/dist/tui/app.js

@@ -1,4 +1,8 @@
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import blessed from 'neo-blessed';
 import { getTuiRepositoryPreference, writeTuiRepositoryPreference } from '@ghcrawl/api-core';
 import { buildMemberRows, cycleFocusPane, cycleMinSizeFilter, cycleSortMode, findSelectableIndex, moveSelectableIndex, preserveSelectedId, selectedThreadIdFromRow, } from './state.js';
@@ -22,6 +26,30 @@ function createScreen(options) {
 const ACTIVITY_LOG_LIMIT = 200;
 const FOOTER_LOG_LINES = 3;
 const UPDATE_TASK_ORDER = ['sync', 'embed', 'cluster'];
+export function buildRefreshCliArgs(target, selection) {
+    const args = ['refresh', `${target.owner}/${target.repo}`];
+    if (!selection.sync)
+        args.push('--no-sync');
+    if (!selection.embed)
+        args.push('--no-embed');
+    if (!selection.cluster)
+        args.push('--no-cluster');
+    return args;
+}
+function createCliLaunch(args) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const distEntrypoint = path.resolve(here, '..', 'main.js');
+    if (existsSync(distEntrypoint)) {
+        return { command: process.execPath, args: [distEntrypoint, ...args] };
+    }
+    const sourceEntrypoint = path.resolve(here, '..', 'main.ts');
+    const require = createRequire(import.meta.url);
+    const tsxLoader = require.resolve('tsx');
+    return {
+        command: process.execPath,
+        args: ['--conditions=development', '--import', tsxLoader, sourceEntrypoint, ...args],
+    };
+}
 export async function startTui(params) {
     const selectedRepository = params.owner && params.repo ? { owner: params.owner, repo: params.repo } : null;
     let currentRepository = selectedRepository ?? { owner: '', repo: '' };
@@ -36,6 +64,8 @@ export async function startTui(params) {
     let showClosed = true;
     let search = '';
     let snapshot = null;
+    let clusterItems = ['Pick a repository with p'];
+    let clusterIndexById = new Map();
     let clusterDetail = null;
     let threadDetail = null;
     let selectedClusterId = null;
@@ -49,18 +79,41 @@ export async function startTui(params) {
     let syncJobRunning = false;
     let embedJobRunning = false;
     let clusterJobRunning = false;
+    let activeJob = null;
     let modalOpen = false;
+    let exitRequested = false;
     const clearCaches = () => {
         clusterDetailCache.clear();
         threadDetailCache.clear();
     };
-    const pushActivity = (message) => {
-        activityLines.push(`${formatActivityTimestamp()} ${message}`);
+    const rebuildClusterItems = () => {
+        if (!snapshot) {
+            clusterItems = ['Pick a repository with p'];
+            clusterIndexById = new Map();
+            widgets.clusters.setItems(clusterItems);
+            return;
+        }
+        clusterIndexById = new Map();
+        clusterItems = snapshot.clusters.map((cluster, index) => {
+            clusterIndexById.set(cluster.clusterId, index);
+            const updated = formatClusterDateColumn(cluster.latestUpdatedAt);
+            const label = `${String(cluster.totalCount).padStart(3, ' ')}  C${String(cluster.clusterId).padStart(5, ' ')}  ${String(cluster.pullRequestCount).padStart(2, ' ')}P/${String(cluster.issueCount).padStart(2, ' ')}I  ${updated}  ${cluster.displayTitle}`;
+            return cluster.isClosed ? `{gray-fg}${escapeBlessedText(label)}{/gray-fg}` : escapeBlessedText(label);
+        });
+        widgets.clusters.setItems(clusterItems);
+    };
+    const pushActivity = (message, options) => {
+        activityLines.push(options?.raw === true ? message : `${formatActivityTimestamp()} ${message}`);
         if (activityLines.length > ACTIVITY_LOG_LIMIT) {
             activityLines.splice(0, activityLines.length - ACTIVITY_LOG_LIMIT);
         }
         render();
     };
+    const setActiveJobFlags = (selection) => {
+        syncJobRunning = selection?.sync === true;
+        embedJobRunning = selection?.embed === true;
+        clusterJobRunning = selection?.cluster === true;
+    };
     const loadClusterDetail = (clusterId) => {
         const cached = clusterDetailCache.get(clusterId);
         if (cached)
@@ -69,6 +122,7 @@ export async function startTui(params) {
             owner: currentRepository.owner,
             repo: currentRepository.repo,
             clusterId,
+            clusterRunId: snapshot?.clusterRunId ?? undefined,
         });
         clusterDetailCache.set(clusterId, detail);
         return detail;
@@ -102,7 +156,14 @@ export async function startTui(params) {
                 return false;
             }
             selectedClusterId = cluster.clusterId;
-            clusterDetail = loadClusterDetail(cluster.clusterId);
+            try {
+                clusterDetail = loadClusterDetail(cluster.clusterId);
+            }
+            catch (error) {
+                status = `Cluster ${cluster.clusterId} changed; refreshing view`;
+                refreshAll(true);
+                return false;
+            }
             memberRows = buildMemberRows(clusterDetail, { includeClosedMembers: showClosed });
             selectedMemberThreadId = threadId;
             memberIndex = findSelectableIndex(memberRows, selectedMemberThreadId);
@@ -138,8 +199,26 @@ export async function startTui(params) {
             includeClosedClusters: showClosed,
         });
         selectedClusterId = preserveSelectedId(snapshot.clusters.map((cluster) => cluster.clusterId), previousClusterId);
+        rebuildClusterItems();
         if (selectedClusterId !== null) {
-            clusterDetail = loadClusterDetail(selectedClusterId);
+            try {
+                clusterDetail = loadClusterDetail(selectedClusterId);
+            }
+            catch {
+                snapshot = params.service.getTuiSnapshot({
+                    owner: currentRepository.owner,
+                    repo: currentRepository.repo,
+                    minSize,
+                    sort: sortMode,
+                    search,
+                    includeClosedClusters: showClosed,
+                });
+                rebuildClusterItems();
+                selectedClusterId = preserveSelectedId(snapshot.clusters.map((cluster) => cluster.clusterId), null);
+                clusterDetail = selectedClusterId !== null ? loadClusterDetail(selectedClusterId) : null;
+            }
+        }
+        if (selectedClusterId !== null && clusterDetail) {
             memberRows = buildMemberRows(clusterDetail, { includeClosedMembers: showClosed });
             selectedMemberThreadId = preserveSelectedId(memberRows.filter((row) => row.selectable).map((row) => row.threadId), previousMemberId);
             memberIndex = findSelectableIndex(memberRows, selectedMemberThreadId);
@@ -188,15 +267,7 @@ export async function startTui(params) {
             ? `#${snapshot.stats.latestClusterRunId} ${formatRelativeTime(snapshot.stats.latestClusterRunFinishedAt ?? null)}`
             : 'never';
         widgets.header.setContent(`{bold}${repoLabel}{/bold}  {cyan-fg}${snapshot?.stats.openPullRequestCount ?? 0} PR{/cyan-fg}  {green-fg}${snapshot?.stats.openIssueCount ?? 0} issues{/green-fg}  GH:${ghStatus}  Emb:${embedStatus}  Cl:${clusterStatus}  sort:${sortMode}  min:${minSize === 0 ? 'all' : `${minSize}+`}  layout:${wideLayout === 'columns' ? 'cols' : 'stack'}  closed:${showClosed ? 'shown' : 'hidden'}  filter:${search || 'none'}`);
-        const clusterItems = snapshot
-            ? snapshot.clusters.map((cluster) => {
-                const updated = formatClusterDateColumn(cluster.latestUpdatedAt);
-                const label = `${String(cluster.totalCount).padStart(3, ' ')}  C${String(cluster.clusterId).padStart(5, ' ')}  ${String(cluster.pullRequestCount).padStart(2, ' ')}P/${String(cluster.issueCount).padStart(2, ' ')}I  ${updated}  ${cluster.displayTitle}`;
-                return cluster.isClosed ? `{gray-fg}${escapeBlessedText(label)}{/gray-fg}` : escapeBlessedText(label);
-            })
-            : ['Pick a repository with p'];
-        widgets.clusters.setItems(clusterItems);
-        const clusterIndex = snapshot && selectedClusterId !== null ? Math.max(0, snapshot.clusters.findIndex((cluster) => cluster.clusterId === selectedClusterId)) : 0;
+        const clusterIndex = snapshot && selectedClusterId !== null ? Math.max(0, clusterIndexById.get(selectedClusterId) ?? -1) : 0;
         widgets.clusters.select(clusterIndex);
         widgets.members.setItems(memberRows.length > 0 ? memberRows.map((row) => row.label) : ['No members']);
         if (memberIndex >= 0) {
@@ -212,8 +283,8 @@ export async function startTui(params) {
         while (footerLines.length < FOOTER_LOG_LINES) {
             footerLines.unshift('');
         }
-        footerLines.push(`${status}  |  jobs:${activeJobs}  |  h/? help  g update  p repos  u author  / filter  s sort  f min  l layout  x closed`);
-        footerLines.push(`Tab focus  j/k move-or-scroll  PgUp/PgDn scroll  r refresh  o open  q quit`);
+        footerLines.push(`${status}  |  jobs:${activeJobs}  |  h/? help  # jump  g update  p repos  u author  / filter  s sort  f min  l layout  x closed`);
+        footerLines.push(`Tab focus  arrows move-or-scroll  PgUp/PgDn page  r refresh  o open  q quit`);
         widgets.footer.setContent(footerLines.join('\n'));
         widgets.screen.render();
     };
@@ -226,86 +297,148 @@ export async function startTui(params) {
         widgets.detail.scroll(offset);
         widgets.screen.render();
     };
-    const runSyncStep = async () => {
-        if (syncJobRunning) {
-            throw new Error('GitHub reconciliation already running');
-        }
-        syncJobRunning = true;
-        status = 'Running GitHub reconciliation';
-        pushActivity('[jobs] starting GitHub reconciliation');
-        render();
-        try {
-            const result = await params.service.syncRepository({
-                owner: currentRepository.owner,
-                repo: currentRepository.repo,
-                onProgress: pushActivity,
-            });
-            pushActivity(`[jobs] GitHub reconciliation complete threads=${result.threadsSynced} comments=${result.commentsSynced} closed=${result.threadsClosed}`);
-            refreshAll(true);
-        }
-        finally {
-            syncJobRunning = false;
-            status = 'Ready';
-            render();
-        }
+    const consumeStreamLines = (stream, onLine) => {
+        let buffer = '';
+        stream.setEncoding('utf8');
+        stream.on('data', (chunk) => {
+            buffer += chunk;
+            while (true) {
+                const newlineIndex = buffer.indexOf('\n');
+                if (newlineIndex === -1)
+                    break;
+                const line = buffer.slice(0, newlineIndex).replace(/\r$/, '').trimEnd();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line.length > 0)
+                    onLine(line);
+            }
+        });
+        stream.on('end', () => {
+            const line = buffer.replace(/\r$/, '').trim();
+            if (line.length > 0)
+                onLine(line);
+        });
     };
-    const runEmbedStep = async () => {
-        if (embedJobRunning) {
-            throw new Error('embed refresh already running');
-        }
-        embedJobRunning = true;
-        status = 'Running embed refresh';
-        pushActivity('[jobs] starting embed refresh');
-        render();
-        try {
-            const result = await params.service.embedRepository({
-                owner: currentRepository.owner,
-                repo: currentRepository.repo,
-                onProgress: pushActivity,
-            });
-            pushActivity(`[jobs] embed refresh complete embeddings=${result.embedded}`);
-            refreshAll(true);
-        }
-        finally {
-            embedJobRunning = false;
+    const finalizeBackgroundJob = (job) => {
+        void (async () => {
+            const result = await job.exitPromise;
+            if (activeJob === job) {
+                activeJob = null;
+            }
+            setActiveJobFlags(null);
+            if (job.terminatedByUser) {
+                pushActivity(`[jobs] update pipeline terminated for ${job.repo.owner}/${job.repo.repo}`);
+            }
+            else if (result.error) {
+                pushActivity(`[jobs] update pipeline failed for ${job.repo.owner}/${job.repo.repo}: ${result.error.message}`);
+            }
+            else if (result.code === 0) {
+                pushActivity(`[jobs] update pipeline complete for ${job.repo.owner}/${job.repo.repo}`);
+                try {
+                    const parsed = JSON.parse(result.stdout.trim());
+                    const summaryParts = [
+                        parsed.sync ? `sync:${parsed.sync.threadsSynced ?? 0} threads` : null,
+                        parsed.sync ? `closed:${parsed.sync.threadsClosed ?? 0}` : null,
+                        parsed.embed ? `embed:${parsed.embed.embedded ?? 0}` : null,
+                        parsed.cluster ? `cluster:${parsed.cluster.clusters ?? 0}` : null,
+                        parsed.cluster ? `edges:${parsed.cluster.edges ?? 0}` : null,
+                    ].filter((value) => value !== null);
+                    if (summaryParts.length > 0) {
+                        pushActivity(`[jobs] result ${summaryParts.join('  ')}`);
+                    }
+                }
+                catch {
+                    // Ignore malformed stdout; progress is already visible in the activity log.
+                }
+                if (currentRepository.owner === job.repo.owner && currentRepository.repo === job.repo.repo) {
+                    refreshAll(true);
+                }
+            }
+            else {
+                const exitSuffix = result.signal !== null ? `signal=${result.signal}` : `code=${result.code ?? 1}`;
+                pushActivity(`[jobs] update pipeline failed for ${job.repo.owner}/${job.repo.repo}: exited ${exitSuffix}`);
+            }
             status = 'Ready';
-            render();
-        }
+            if (!exitRequested) {
+                render();
+            }
+        })();
     };
-    const runClusterStep = async () => {
-        if (clusterJobRunning) {
-            throw new Error('cluster refresh already running');
-        }
-        clusterJobRunning = true;
-        status = 'Running cluster refresh';
-        pushActivity('[jobs] starting cluster refresh');
-        render();
-        try {
-            const result = params.service.clusterRepository({
-                owner: currentRepository.owner,
-                repo: currentRepository.repo,
-                onProgress: pushActivity,
-            });
-            pushActivity(`[jobs] cluster refresh complete clusters=${result.clusters} edges=${result.edges}`);
-            refreshAll(true);
+    const startBackgroundUpdatePipeline = (target, selection) => {
+        if (activeJob !== null) {
+            pushActivity('[jobs] another update pipeline is already running');
+            return false;
         }
-        finally {
-            clusterJobRunning = false;
-            status = 'Ready';
-            render();
+        if (!selection.sync && !selection.embed && !selection.cluster) {
+            pushActivity('[jobs] select at least one update step');
+            return false;
         }
+        const cliArgs = buildRefreshCliArgs(target, selection);
+        const launch = createCliLaunch(cliArgs);
+        const child = spawn(launch.command, launch.args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const job = {
+            child,
+            repo: target,
+            selection,
+            stdoutBuffer: '',
+            terminatedByUser: false,
+            exitPromise: new Promise((resolve) => {
+                let resolved = false;
+                const finish = (result) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    resolve(result);
+                };
+                child.on('error', (error) => {
+                    finish({ code: null, signal: null, stdout: job.stdoutBuffer, error });
+                });
+                child.on('close', (code, signal) => {
+                    finish({ code, signal, stdout: job.stdoutBuffer, error: null });
+                });
+            }),
+        };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            job.stdoutBuffer += chunk;
+        });
+        consumeStreamLines(child.stderr, (line) => pushActivity(line, { raw: true }));
+        activeJob = job;
+        setActiveJobFlags(selection);
+        status = `Running update pipeline for ${target.owner}/${target.repo}`;
+        pushActivity(`[jobs] starting update pipeline for ${target.owner}/${target.repo}: ${UPDATE_TASK_ORDER.filter((task) => selection[task]).join(' -> ')}`);
+        render();
+        finalizeBackgroundJob(job);
+        return true;
     };
-    const moveSelection = (delta) => {
+    const moveSelection = (delta, options) => {
         if (!snapshot)
             return;
+        const steps = Math.max(1, options?.steps ?? 1);
+        const wrap = options?.wrap ?? true;
         if (focusPane === 'clusters') {
             if (snapshot.clusters.length === 0)
                 return;
-            const currentIndex = Math.max(0, snapshot.clusters.findIndex((cluster) => cluster.clusterId === selectedClusterId));
-            const nextIndex = (currentIndex + delta + snapshot.clusters.length) % snapshot.clusters.length;
+            const currentIndex = Math.max(0, selectedClusterId === null ? -1 : (clusterIndexById.get(selectedClusterId) ?? -1));
+            let nextIndex = currentIndex + delta * steps;
+            if (wrap) {
+                nextIndex = ((nextIndex % snapshot.clusters.length) + snapshot.clusters.length) % snapshot.clusters.length;
+            }
+            else {
+                nextIndex = Math.max(0, Math.min(snapshot.clusters.length - 1, nextIndex));
+            }
             selectedClusterId = snapshot.clusters[nextIndex]?.clusterId ?? null;
             if (selectedClusterId !== null) {
-                clusterDetail = loadClusterDetail(selectedClusterId);
+                try {
+                    clusterDetail = loadClusterDetail(selectedClusterId);
+                }
+                catch {
+                    status = 'Cluster data changed; refreshing view';
+                    refreshAll(true);
+                    return;
+                }
                 memberRows = buildMemberRows(clusterDetail, { includeClosedMembers: showClosed });
                 selectedMemberThreadId = preserveSelectedId(memberRows.filter((row) => row.selectable).map((row) => row.threadId), null);
                 memberIndex = findSelectableIndex(memberRows, selectedMemberThreadId);
@@ -319,7 +452,15 @@ export async function startTui(params) {
         if (focusPane === 'members') {
             if (memberRows.length === 0)
                 return;
-            memberIndex = moveSelectableIndex(memberRows, memberIndex < 0 ? 0 : memberIndex, delta);
+            let nextIndex = memberIndex < 0 ? 0 : memberIndex;
+            for (let index = 0; index < steps; index += 1) {
+                const candidateIndex = moveSelectableIndex(memberRows, nextIndex, delta);
+                if (!wrap && candidateIndex === nextIndex) {
+                    break;
+                }
+                nextIndex = candidateIndex;
+            }
+            memberIndex = nextIndex;
             selectedMemberThreadId = selectedThreadIdFromRow(memberRows, memberIndex);
             loadSelectedThreadDetail(false);
             resetDetailScroll();
@@ -327,6 +468,17 @@ export async function startTui(params) {
             render();
         }
     };
+    const getFocusedListPageSize = () => {
+        const listHeight = focusPane === 'clusters' ? Number(widgets.clusters.height) : Number(widgets.members.height);
+        return Math.max(1, listHeight - 4);
+    };
+    const pageFocusedPane = (delta) => {
+        if (focusPane === 'detail') {
+            scrollDetail(delta * 12);
+            return;
+        }
+        moveSelection(delta, { steps: getFocusedListPageSize(), wrap: false });
+    };
     const promptFilter = () => {
         modalOpen = true;
         const prompt = blessed.prompt({
@@ -354,6 +506,56 @@ export async function startTui(params) {
             updateFocus('clusters');
         });
     };
+    const promptThreadJump = () => {
+        if (modalOpen)
+            return;
+        modalOpen = true;
+        const prompt = blessed.prompt({
+            parent: widgets.screen,
+            border: 'line',
+            height: 7,
+            width: '60%',
+            top: 'center',
+            left: 'center',
+            label: ' Jump To Issue/PR ',
+            tags: true,
+            keys: true,
+            vi: true,
+            style: {
+                border: { fg: '#fde74c' },
+                bg: '#101522',
+            },
+        });
+        prompt.input('Issue or PR number', '', (_error, value) => {
+            prompt.destroy();
+            modalOpen = false;
+            const parsed = Number((value ?? '').trim());
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                status = 'Enter a positive issue or PR number';
+                render();
+                return;
+            }
+            try {
+                const detail = params.service.getTuiThreadDetail({
+                    owner: currentRepository.owner,
+                    repo: currentRepository.repo,
+                    threadNumber: parsed,
+                    includeNeighbors: false,
+                });
+                const jumped = jumpToThread(detail.thread.id, detail.thread.clusterId ?? null);
+                if (jumped) {
+                    status = `Jumped to #${detail.thread.number} in cluster ${detail.thread.clusterId ?? '?'}`;
+                    updateFocus('members');
+                    return;
+                }
+                render();
+            }
+            catch (error) {
+                status = error instanceof Error ? error.message : `Thread #${parsed} was not found`;
+                render();
+            }
+        });
+    };
     const openSelectedThread = () => {
         const url = threadDetail?.thread.htmlUrl;
         if (!url) {
@@ -409,6 +611,76 @@ export async function startTui(params) {
             }
         })();
     };
+    const promptConfirm = async (label, message) => {
+        const box = blessed.box({
+            parent: widgets.screen,
+            border: 'line',
+            label: ` ${label} `,
+            tags: true,
+            top: 'center',
+            left: 'center',
+            width: '68%',
+            height: 9,
+            padding: {
+                left: 1,
+                right: 1,
+            },
+            style: {
+                border: { fg: '#fde74c' },
+                fg: 'white',
+                bg: '#101522',
+            },
+            content: `${message}\n\nPress y or Enter to confirm. Press n or Esc to cancel.`,
+        });
+        widgets.screen.render();
+        return await new Promise((resolve) => {
+            const finish = (value) => {
+                widgets.screen.off('keypress', handleKeypress);
+                box.destroy();
+                widgets.screen.render();
+                resolve(value);
+            };
+            const handleKeypress = (char, key) => {
+                if (key.name === 'enter' || char.toLowerCase() === 'y') {
+                    finish(true);
+                    return;
+                }
+                if (key.name === 'escape' || char.toLowerCase() === 'n' || key.name === 'q') {
+                    finish(false);
+                }
+            };
+            widgets.screen.on('keypress', handleKeypress);
+        });
+    };
+    const requestQuit = () => {
+        if (modalOpen)
+            return;
+        void (async () => {
+            if (activeJob === null) {
+                widgets.screen.destroy();
+                return;
+            }
+            modalOpen = true;
+            try {
+                const confirmed = await promptConfirm('Stop Update Pipeline', `A background update pipeline is still running for ${activeJob.repo.owner}/${activeJob.repo.repo}.\nQuitting now will send SIGTERM to that refresh process and wait for it to exit.`);
+                if (!confirmed) {
+                    render();
+                    return;
+                }
+                exitRequested = true;
+                status = 'Stopping background update pipeline';
+                pushActivity(`[jobs] stopping update pipeline for ${activeJob.repo.owner}/${activeJob.repo.repo}`);
+                render();
+                activeJob.terminatedByUser = true;
+                activeJob.child.kill('SIGTERM');
+                await activeJob.exitPromise;
+                widgets.screen.destroy();
+            }
+            finally {
+                modalOpen = false;
+            }
+        })();
+    };
     const promptUpdatePipeline = () => {
         if (modalOpen || hasActiveJobs()) {
             if (hasActiveJobs()) {
@@ -426,7 +698,7 @@ export async function startTui(params) {
                 }
                 const selectedTasks = UPDATE_TASK_ORDER.filter((task) => selection[task]).join(' -> ');
                 pushActivity(`[jobs] queued update pipeline: ${selectedTasks}`);
-                await runUpdatePipeline(selection);
+                startBackgroundUpdatePipeline(currentRepository, selection);
                 updateFocus('clusters');
             }
             finally {
@@ -434,29 +706,7 @@ export async function startTui(params) {
             }
         })();
     };
-    const hasActiveJobs = () => syncJobRunning || embedJobRunning || clusterJobRunning;
-    const runUpdatePipeline = async (selection) => {
-        if (hasActiveJobs()) {
-            pushActivity('[jobs] another update pipeline is already running');
-            return false;
-        }
-        try {
-            if (selection.sync) {
-                await runSyncStep();
-            }
-            if (selection.embed) {
-                await runEmbedStep();
-            }
-            if (selection.cluster) {
-                await runClusterStep();
-            }
-            return true;
-        }
-        catch (error) {
-            pushActivity(`[jobs] update pipeline failed: ${error instanceof Error ? error.message : String(error)}`);
-            return false;
-        }
-    };
+    const hasActiveJobs = () => activeJob !== null;
     const persistRepositoryPreference = () => {
         writeTuiRepositoryPreference(params.service.config, {
             owner: currentRepository.owner,
@@ -466,6 +716,33 @@ export async function startTui(params) {
             wideLayout,
         });
     };
+    const withLoadingOverlay = async (message, task) => {
+        const box = blessed.box({
+            parent: widgets.screen,
+            border: 'line',
+            label: ' Loading ',
+            width: '56%',
+            height: 7,
+            top: 'center',
+            left: 'center',
+            tags: true,
+            content: `${message}\n\nThis can take a few seconds on large repos.`,
+            style: {
+                border: { fg: '#5bc0eb' },
+                fg: 'white',
+                bg: '#101522',
+            },
+        });
+        widgets.screen.render();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        try {
+            return await task();
+        }
+        finally {
+            box.destroy();
+            widgets.screen.render();
+        }
+    };
     const switchRepository = (target, overrides) => {
         currentRepository = target;
         const preference = getTuiRepositoryPreference(params.service.config, target.owner, target.repo);
@@ -476,6 +753,9 @@ export async function startTui(params) {
         clearCaches();
         search = '';
         snapshot = null;
+        clusterItems = ['Pick a repository with p'];
+        clusterIndexById = new Map();
+        widgets.clusters.setItems(clusterItems);
         clusterDetail = null;
         threadDetail = null;
         selectedClusterId = null;
@@ -485,37 +765,14 @@ export async function startTui(params) {
         status = `Switched to ${target.owner}/${target.repo}`;
         refreshAll(false);
     };
-    const runRepositoryBootstrap = async (target) => {
+    const runRepositoryBootstrap = (target) => {
         if (hasActiveJobs()) {
             pushActivity('[repo] repository setup is blocked while jobs are already running');
             return false;
         }
-        status = `Bootstrapping ${target.owner}/${target.repo}`;
-        render();
-        try {
-            pushActivity(`[repo] starting initial update pipeline for ${target.owner}/${target.repo}`);
-            const previousRepository = currentRepository;
-            let ok = false;
-            try {
-                currentRepository = target;
-                ok = await runUpdatePipeline({ sync: true, embed: true, cluster: true });
-            }
-            finally {
-                currentRepository = previousRepository;
-            }
-            if (!ok) {
-                return false;
-            }
-            pushActivity(`[repo] initial setup complete for ${target.owner}/${target.repo}`);
-            switchRepository(target, { minClusterSize: 1 });
-            return true;
-        }
-        catch (error) {
-            pushActivity(`[repo] initial setup failed for ${target.owner}/${target.repo}: ${error instanceof Error ? error.message : String(error)}`);
-            status = 'Ready';
-            render();
-            return false;
-        }
+        switchRepository(target, { minClusterSize: 1 });
+        pushActivity(`[repo] opened ${target.owner}/${target.repo}; starting initial update pipeline in the background`);
+        return startBackgroundUpdatePipeline(target, { sync: true, embed: true, cluster: true });
     };
     const browseRepositories = () => {
         if (modalOpen)
@@ -533,7 +790,9 @@ export async function startTui(params) {
                     return;
                 }
                 if (choice.kind === 'existing') {
-                    switchRepository(choice.target);
+                    await withLoadingOverlay(`Opening ${choice.target.owner}/${choice.target.repo}...`, async () => {
+                        switchRepository(choice.target);
+                    });
                     pushActivity(`[repo] switched to ${choice.target.owner}/${choice.target.repo}`);
                     updateFocus('clusters');
                     return;
@@ -543,7 +802,7 @@ export async function startTui(params) {
                     render();
                     return;
                 }
-                await runRepositoryBootstrap(target);
+                runRepositoryBootstrap(target);
                 updateFocus('clusters');
             }
             finally {
@@ -562,7 +821,9 @@ export async function startTui(params) {
                 return false;
             }
             if (choice.kind === 'existing') {
-                switchRepository(choice.target);
+                await withLoadingOverlay(`Opening ${choice.target.owner}/${choice.target.repo}...`, async () => {
+                    switchRepository(choice.target);
+                });
                 pushActivity(`[repo] opened ${choice.target.owner}/${choice.target.repo}`);
                 updateFocus('clusters');
                 return true;
@@ -571,7 +832,7 @@ export async function startTui(params) {
             if (!target) {
                 return false;
             }
-            const ready = await runRepositoryBootstrap(target);
+            const ready = runRepositoryBootstrap(target);
             if (!ready) {
                 return false;
             }
@@ -583,24 +844,22 @@ export async function startTui(params) {
         }
     };
     widgets.screen.key(['q'], () => {
-        if (modalOpen)
-            return;
-        widgets.screen.destroy();
+        requestQuit();
     });
     widgets.screen.key(['C-c'], () => {
-        widgets.screen.destroy();
+        requestQuit();
     });
-    widgets.screen.key(['tab'], () => {
+    widgets.screen.key(['tab', 'right'], () => {
         if (modalOpen)
             return;
         updateFocus(cycleFocusPane(focusPane, 1));
     });
-    widgets.screen.key(['S-tab'], () => {
+    widgets.screen.key(['S-tab', 'left'], () => {
         if (modalOpen)
             return;
         updateFocus(cycleFocusPane(focusPane, -1));
     });
-    widgets.screen.key(['j', 'down'], () => {
+    widgets.screen.key(['down'], () => {
         if (modalOpen)
             return;
         if (focusPane === 'detail') {
@@ -609,7 +868,7 @@ export async function startTui(params) {
         }
         moveSelection(1);
     });
-    widgets.screen.key(['k', 'up'], () => {
+    widgets.screen.key(['up'], () => {
         if (modalOpen)
             return;
         if (focusPane === 'detail') {
@@ -621,12 +880,12 @@ export async function startTui(params) {
     widgets.screen.key(['pageup'], () => {
         if (modalOpen)
             return;
-        scrollDetail(-12);
+        pageFocusedPane(-1);
     });
     widgets.screen.key(['pagedown'], () => {
         if (modalOpen)
             return;
-        scrollDetail(12);
+        pageFocusedPane(1);
     });
     widgets.screen.key(['home'], () => {
         if (modalOpen)
@@ -693,6 +952,11 @@ export async function startTui(params) {
             return;
         promptFilter();
     });
+    widgets.screen.key(['#'], () => {
+        if (modalOpen)
+            return;
+        promptThreadJump();
+    });
     widgets.screen.key(['h', '?'], () => {
         if (modalOpen)
             return;
@@ -923,13 +1187,14 @@ export function buildHelpContent() {
         '',
         '{bold}Navigation{/bold}',
         'Tab / Shift-Tab  cycle focus across clusters, members, and detail',
-        'j / k             move selection, or scroll detail when detail is focused',
-        'Up / Down         same as j / k',
+        'Left / Right      cycle focus backward or forward across panes',
+        'Up / Down         move selection, or scroll detail when detail is focused',
         'Enter             clusters -> members, members -> detail',
-        'PgUp / PgDn       scroll detail or this help popup faster',
+        'PgUp / PgDn       page through the focused pane or this help popup faster',
         'Home / End        jump to the top or bottom of detail or help',
         '',
         '{bold}Views And Filters{/bold}',
+        '#                 jump directly to an issue or PR number',
         's                 cycle cluster sort mode',
         'f                 cycle minimum cluster size filter',
         'l                 toggle wide layout: columns vs. wide-left stacked-right',
@@ -938,20 +1203,20 @@ export function buildHelpContent() {
         'r                 refresh the current local view from SQLite',
         '',
         '{bold}Actions{/bold}',
-        'g                 open the staged update pipeline (GitHub, embeddings, clusters)',
+        'g                 start the staged update pipeline in the background (GitHub, embeddings, clusters)',
         'p                 open the repository browser / sync a new repository',
         'u                 show all open threads for the selected author',
         'o                 open the selected thread URL in your browser',
         '',
         '{bold}Help And Exit{/bold}',
         'h or ?            open this help popup',
-        'q                 quit the TUI (or close this popup)',
+        'q                 quit the TUI (or close this popup); warns if a background update is running',
         'Esc               close this popup',
         '',
         '{bold}Notes{/bold}',
         'Clusters show C<clusterId> so the cluster id is easy to copy into CLI or skill flows.',
         'The footer only shows the short command list. Open help to see the full list.',
-        'This popup scrolls. Use j/k, arrows, PgUp/PgDn, Home, and End if it does not fit.',
+        'This popup scrolls. Use arrows, PgUp/PgDn, Home, and End if it does not fit.',
     ].join('\n');
 }
 async function promptHelp(screen) {
@@ -992,7 +1257,7 @@ async function promptHelp(screen) {
         bottom: 1,
         left: 'center',
         tags: false,
-        content: 'Scroll with j/k, arrows, PgUp/PgDn, Home, End. Press Esc, q, h, ?, or Enter to close.',
+        content: 'Scroll with arrows, PgUp/PgDn, Home, End. Press Esc, q, h, ?, or Enter to close.',
         style: { fg: 'black', bg: '#5bc0eb' },
     });
     box.focus();
@@ -1063,7 +1328,7 @@ async function promptUpdatePipelineSelection(screen, stats) {
         height: 4,
         style: { fg: 'white', bg: '#101522' },
         content: 'Usually you want all three. Run order is fixed: GitHub sync/reconcile -> embeddings -> clusters.\n' +
-            'Toggle with space, move with j/k or arrows, Enter to start, Esc to cancel.',
+            'Toggle with space, move with arrows, Enter to start, Esc to cancel.',
     });
     box.focus();
     box.select(0);
@@ -1285,7 +1550,7 @@ async function runColdStartSetup(service, screen, target, log, footer) {
             repo: target.repo,
             onProgress: reporter,
         });
-        service.clusterRepository({
+        await service.clusterRepository({
             owner: target.owner,
             repo: target.repo,
             onProgress: reporter,