preflight-mcp 0.1.3 → 0.1.4

package/README.md

@@ -15,8 +15,12 @@ Each bundle contains:
 
 ## Features
 
-- **12 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
-- **De-duplication**: prevent repeated indexing of the same normalized inputs
+- **13 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
+- **Progress tracking**: Real-time progress reporting for long-running operations (create/update bundles)
+- **Bundle integrity check**: Prevents operations on incomplete bundles with helpful error messages
+- **De-duplication with in-progress lock**: Prevent duplicate bundle creation even during MCP timeouts
+- **Global dependency graph**: Generate project-wide import relationship graphs
+- **Batch file reading**: Read all key bundle files in a single call
 - **Resilient GitHub fetching**: configurable git clone timeout + GitHub archive (zipball) fallback
 - **Offline repair**: rebuild missing/empty derived artifacts (index/guides/overview) without re-fetching
 - **Static facts extraction** via `analysis/FACTS.json` (non-LLM)
@@ -117,7 +121,7 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (12 total)
+## Tools (13 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
@@ -146,8 +150,10 @@ Input (example):
 **Note**: If the bundle contains code files, consider using `preflight_evidence_dependency_graph` for dependency analysis or `preflight_trace_upsert` for trace links.
 
 ### `preflight_read_file`
-Read a file from bundle (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, or any repo file).
-- Triggers: "查看概览", "项目概览", "看README", "bundle详情", "bundle状态", "仓库信息"
+Read file(s) from bundle. Two modes:
+- **Batch mode** (omit `file`): Returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs) in one call
+- **Single file mode** (provide `file`): Returns that specific file
+- Triggers: "查看bundle", "bundle概览", "项目信息", "show bundle"
 - Use `file: "manifest.json"` to get bundle metadata (repos, timestamps, tags, etc.)
 
 ### `preflight_delete_bundle`
@@ -189,10 +195,12 @@ Optional parameters:
 - `limit`: Max total hits across all bundles
 
 ### `preflight_evidence_dependency_graph`
-Generate an evidence-based dependency graph for a target file/symbol (imports + callers).
+Generate an evidence-based dependency graph. Two modes:
+- **Target mode** (provide `target.file`): Analyze a specific file's imports and callers
+- **Global mode** (omit `target`): Generate project-wide import graph of all code files
 - Deterministic output with source ranges for edges.
 - Uses Tree-sitter parsing when `PREFLIGHT_AST_ENGINE=wasm`; falls back to regex extraction otherwise.
-- Emits `imports` edges (file → module) and, when resolvable, `imports_resolved` edges (file → internal file).
+- Emits `imports` edges (file → module) and `imports_resolved` edges (file → internal file).
 
 ### `preflight_trace_upsert`
 Upsert traceability links (commit↔ticket, symbol↔test, code↔doc, etc.) for a bundle.
@@ -210,6 +218,12 @@ Parameters:
 
 Note: This is also automatically executed on server startup (background, non-blocking).
 
+### `preflight_get_task_status`
+Check status of bundle creation/update tasks (progress tracking).
+- Triggers: "check progress", "what is the status", "查看任务状态", "下载进度"
+- Query by `taskId` (from error), `fingerprint`, or `repos`
+- Shows: phase, progress percentage, message, elapsed time
+
 ## Resources
 
 ### `preflight://bundles`

package/dist/bundle/github.js

@@ -13,8 +13,26 @@ export function parseOwnerRepo(input) {
 export function toCloneUrl(ref) {
     return `https://github.com/${ref.owner}/${ref.repo}.git`;
 }
+/**
+ * Parse git clone progress from stderr.
+ * Git outputs progress like:
+ * - "Receiving objects:  45% (1234/2741)"
+ * - "Resolving deltas:  60% (100/167)"
+ */
+function parseGitProgress(line) {
+    // Match patterns like "Receiving objects:  45% (1234/2741)"
+    const match = line.match(/(Receiving objects|Resolving deltas|Counting objects|Compressing objects):\s+(\d+)%/);
+    if (match) {
+        return {
+            phase: match[1],
+            percent: parseInt(match[2], 10),
+        };
+    }
+    return null;
+}
 async function runGit(args, opts) {
     const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
+    const onProgress = opts?.onProgress;
     return new Promise((resolve, reject) => {
         const child = spawn('git', args, {
             cwd: opts?.cwd,
@@ -65,7 +83,19 @@ async function runGit(args, opts) {
             stdout += data.toString('utf8');
         });
         child.stderr?.on('data', (data) => {
-            stderr += data.toString('utf8');
+            const chunk = data.toString('utf8');
+            stderr += chunk;
+            // Parse and report progress
+            if (onProgress) {
+                // Git progress can come in chunks, split by lines
+                const lines = chunk.split(/[\r\n]+/);
+                for (const line of lines) {
+                    const progress = parseGitProgress(line);
+                    if (progress) {
+                        onProgress(progress.phase, progress.percent, `${progress.phase}: ${progress.percent}%`);
+                    }
+                }
+            }
         });
         child.on('error', (err) => {
             cleanup();
@@ -125,14 +155,15 @@ export async function shallowClone(cloneUrl, destDir, opts) {
     await fs.mkdir(path.dirname(destDir), { recursive: true });
     // Clean dest if exists.
     await fs.rm(destDir, { recursive: true, force: true });
-    const args = ['-c', 'core.autocrlf=false', 'clone', '--depth', '1', '--no-tags', '--single-branch'];
+    // Use --progress to force progress output even when not attached to a terminal
+    const args = ['-c', 'core.autocrlf=false', 'clone', '--depth', '1', '--no-tags', '--single-branch', '--progress'];
     if (opts?.ref) {
         // Validate ref before using it in git command
         validateGitRef(opts.ref);
         args.push('--branch', opts.ref);
     }
     args.push(cloneUrl, destDir);
-    await runGit(args, { timeoutMs: opts?.timeoutMs ?? 15 * 60_000 });
+    await runGit(args, { timeoutMs: opts?.timeoutMs ?? 15 * 60_000, onProgress: opts?.onProgress });
 }
 export async function getLocalHeadSha(repoDir) {
     const { stdout } = await runGit(['-C', repoDir, 'rev-parse', 'HEAD']);

package/dist/bundle/githubArchive.js

@@ -36,7 +36,7 @@ async function fetchJson(url, headers, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
         clearTimeout(timeoutId);
     }
 }
-async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS) {
+async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS, onProgress) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -44,12 +44,51 @@ async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLO
         if (!res.ok) {
             throw new Error(`Download error ${res.status}: ${res.statusText}`);
         }
-        // Use streaming if possible; otherwise fallback to arrayBuffer.
+        // Get content length for progress reporting
+        const contentLengthHeader = res.headers.get('content-length');
+        const totalBytes = contentLengthHeader ? parseInt(contentLengthHeader, 10) : undefined;
+        await ensureDir(path.dirname(destPath));
+        // Use streaming to report progress
         const anyRes = res;
         const body = anyRes.body;
-        await ensureDir(path.dirname(destPath));
+        if (body && typeof body[Symbol.asyncIterator] === 'function') {
+            // Async iterator for progress tracking
+            const fsModule = await import('node:fs');
+            const ws = fsModule.createWriteStream(destPath);
+            let downloadedBytes = 0;
+            let lastReportTime = Date.now();
+            const reportIntervalMs = 500; // Report at most every 500ms
+            try {
+                for await (const chunk of body) {
+                    ws.write(chunk);
+                    downloadedBytes += chunk.length;
+                    // Throttle progress reports
+                    const now = Date.now();
+                    if (onProgress && (now - lastReportTime > reportIntervalMs)) {
+                        lastReportTime = now;
+                        const percent = totalBytes ? Math.round((downloadedBytes / totalBytes) * 100) : 0;
+                        const msg = totalBytes
+                            ? `Downloaded ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)} (${percent}%)`
+                            : `Downloaded ${formatBytes(downloadedBytes)}`;
+                        onProgress(downloadedBytes, totalBytes, msg);
+                    }
+                }
+            }
+            finally {
+                ws.end();
+                await new Promise((resolve) => ws.on('finish', () => resolve()));
+            }
+            // Final progress report
+            if (onProgress) {
+                const msg = totalBytes
+                    ? `Downloaded ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)} (100%)`
+                    : `Downloaded ${formatBytes(downloadedBytes)}`;
+                onProgress(downloadedBytes, totalBytes, msg);
+            }
+            return;
+        }
         if (body && typeof body.pipe === 'function') {
-            // Node.js stream
+            // Node.js stream (fallback without progress)
             const ws = (await import('node:fs')).createWriteStream(destPath);
             await new Promise((resolve, reject) => {
                 body.pipe(ws);
@@ -59,14 +98,27 @@ async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLO
             });
             return;
         }
-        // Web stream or no stream support.
+        // Web stream or no stream support (fallback without progress)
         const buf = Buffer.from(await res.arrayBuffer());
         await fs.writeFile(destPath, buf);
+        if (onProgress) {
+            onProgress(buf.length, buf.length, `Downloaded ${formatBytes(buf.length)}`);
+        }
     }
     finally {
         clearTimeout(timeoutId);
     }
 }
+/** Format bytes for display */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
 async function extractZip(zipPath, destDir) {
     await ensureDir(destDir);
     const zip = new AdmZip(zipPath);
@@ -91,7 +143,7 @@ export async function downloadAndExtractGitHubArchive(params) {
     // Use the API zipball endpoint so ref can be branch/tag/SHA (including slashes via URL-encoding).
     const zipballUrl = `https://api.github.com/repos/${params.owner}/${params.repo}/zipball/${encodeURIComponent(refUsed)}`;
     await ensureDir(params.destDir);
-    await downloadToFile(zipballUrl, headers, zipPath);
+    await downloadToFile(zipballUrl, headers, zipPath, DEFAULT_DOWNLOAD_TIMEOUT_MS, params.onProgress);
     const extractDir = path.join(params.destDir, `extracted-${Date.now()}`);
     await extractZip(zipPath, extractDir);
     const repoRoot = await findSingleTopLevelDir(extractDir);

package/dist/bundle/service.js

@@ -14,6 +14,7 @@ import { ingestContext7Libraries } from './context7.js';
 import { analyzeBundleStatic } from './analysis.js';
 import { autoDetectTags, generateDisplayName, generateDescription } from './tagging.js';
 import { bundleCreationLimiter } from '../core/concurrency-limiter.js';
+import { getProgressTracker, calcPercent } from '../jobs/progressTracker.js';
 const DEDUP_INDEX_FILE = '.preflight-dedup-index.json';
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
@@ -90,7 +91,7 @@ async function writeDedupIndex(storageDir, idx) {
         throw err;
     }
 }
-async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpdatedAt) {
+async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpdatedAt, status = 'complete') {
     for (const storageDir of cfg.storageDirs) {
         try {
             const parentAvailable = await isParentAvailable(storageDir);
@@ -98,7 +99,7 @@ async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpda
                 continue;
             await ensureDir(storageDir);
             const idx = await readDedupIndex(storageDir);
-            idx.byFingerprint[fingerprint] = { bundleId, bundleUpdatedAt };
+            idx.byFingerprint[fingerprint] = { bundleId, bundleUpdatedAt, status };
             idx.updatedAt = nowIso();
             await writeDedupIndex(storageDir, idx);
         }
@@ -107,6 +108,97 @@ async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpda
         }
     }
 }
+/**
+ * Set in-progress lock for a fingerprint. Returns false if already locked (not timed out).
+ */
+async function setInProgressLock(cfg, fingerprint, taskId, repos) {
+    const now = nowIso();
+    const nowMs = Date.now();
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            await ensureDir(storageDir);
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            // Check if there's an existing in-progress lock
+            if (existing?.status === 'in-progress' && existing.startedAt) {
+                const startedMs = new Date(existing.startedAt).getTime();
+                const elapsed = nowMs - startedMs;
+                // If lock hasn't timed out, return the existing entry
+                if (elapsed < cfg.inProgressLockTimeoutMs) {
+                    return { locked: false, existingEntry: existing };
+                }
+                // Lock timed out - will be overwritten
+                logger.warn(`In-progress lock timed out for fingerprint ${fingerprint.slice(0, 8)}...`);
+            }
+            // Set new in-progress lock
+            idx.byFingerprint[fingerprint] = {
+                bundleId: '', // Will be set on completion
+                bundleUpdatedAt: now,
+                status: 'in-progress',
+                startedAt: now,
+                taskId,
+                repos,
+            };
+            idx.updatedAt = now;
+            await writeDedupIndex(storageDir, idx);
+            return { locked: true };
+        }
+        catch (err) {
+            logger.debug(`Failed to set in-progress lock in ${storageDir}`, err instanceof Error ? err : undefined);
+        }
+    }
+    // If we couldn't write to any storage, assume we can proceed (best-effort)
+    return { locked: true };
+}
+/**
+ * Clear in-progress lock (on failure or completion with status='complete').
+ */
+async function clearInProgressLock(cfg, fingerprint) {
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            // Only clear if it's in-progress
+            if (existing?.status === 'in-progress') {
+                delete idx.byFingerprint[fingerprint];
+                idx.updatedAt = nowIso();
+                await writeDedupIndex(storageDir, idx);
+            }
+        }
+        catch (err) {
+            logger.debug(`Failed to clear in-progress lock in ${storageDir}`, err instanceof Error ? err : undefined);
+        }
+    }
+}
+/**
+ * Check if a fingerprint has an in-progress lock (not timed out).
+ */
+export async function checkInProgressLock(cfg, fingerprint) {
+    const nowMs = Date.now();
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            if (existing?.status === 'in-progress' && existing.startedAt) {
+                const startedMs = new Date(existing.startedAt).getTime();
+                const elapsed = nowMs - startedMs;
+                if (elapsed < cfg.inProgressLockTimeoutMs) {
+                    return existing;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
 async function readBundleSummary(cfg, bundleId) {
     const storageDir = (await findBundleStorageDir(cfg.storageDirs, bundleId)) ?? (await getEffectiveStorageDir(cfg));
     const paths = getBundlePaths(storageDir, bundleId);
@@ -137,6 +229,9 @@ async function findExistingBundleByFingerprint(cfg, fingerprint) {
                 continue;
             const idx = await readDedupIndex(storageDir);
             const hit = idx.byFingerprint[fingerprint];
+            // Skip in-progress entries - they don't have a completed bundle yet
+            if (hit?.status === 'in-progress')
+                continue;
             if (hit?.bundleId && (await bundleExistsMulti(cfg.storageDirs, hit.bundleId))) {
                 return hit.bundleId;
             }
@@ -321,6 +416,33 @@ async function validateBundleCompleteness(bundleRoot) {
         missingComponents,
     };
 }
+/**
+ * Assert that a bundle is complete and ready for operations.
+ * Throws an error with helpful guidance if the bundle is incomplete.
+ * Should be called at the entry point of tools that require a complete bundle
+ * (e.g., dependency graph, trace links, search).
+ */
+export async function assertBundleComplete(cfg, bundleId) {
+    const storageDir = await findBundleStorageDir(cfg.storageDirs, bundleId);
+    if (!storageDir) {
+        throw new Error(`Bundle not found: ${bundleId}`);
+    }
+    const bundleRoot = getBundlePaths(storageDir, bundleId).rootDir;
+    const { isValid, missingComponents } = await validateBundleCompleteness(bundleRoot);
+    if (!isValid) {
+        const issues = missingComponents.join('\n  - ');
+        throw new Error(`Bundle is incomplete and cannot be used for this operation.\n\n` +
+            `Bundle ID: ${bundleId}\n` +
+            `Missing components:\n  - ${issues}\n\n` +
+            `This usually happens when:\n` +
+            `1. Bundle creation was interrupted (timeout, network error, etc.)\n` +
+            `2. Bundle download is still in progress\n\n` +
+            `Suggested actions:\n` +
+            `- Use preflight_update_bundle with force:true to re-download the repository\n` +
+            `- Or use preflight_delete_bundle and preflight_create_bundle to start fresh\n` +
+            `- Check preflight_get_task_status if creation might still be in progress`);
+    }
+}
 /**
  * Detect primary language from ingested files
  */
@@ -628,7 +750,14 @@ async function cloneAndIngestGitHubRepo(params) {
     let fetchedAt = nowIso();
     let refUsed = params.ref;
     try {
-        await shallowClone(cloneUrl, tmpCheckoutGit, { ref: params.ref, timeoutMs: params.cfg.gitCloneTimeoutMs });
+        params.onProgress?.('cloning', 0, `Cloning ${repoId}...`);
+        await shallowClone(cloneUrl, tmpCheckoutGit, {
+            ref: params.ref,
+            timeoutMs: params.cfg.gitCloneTimeoutMs,
+            onProgress: (phase, percent, msg) => {
+                params.onProgress?.('cloning', percent, `${repoId}: ${msg}`);
+            },
+        });
         headSha = await getLocalHeadSha(tmpCheckoutGit);
     }
     catch (err) {
@@ -636,12 +765,17 @@ async function cloneAndIngestGitHubRepo(params) {
         source = 'archive';
         const msg = err instanceof Error ? err.message : String(err);
         notes.push(`git clone failed; used GitHub archive fallback: ${msg}`);
+        params.onProgress?.('downloading', 0, `Downloading ${repoId} archive...`);
         const archive = await downloadAndExtractGitHubArchive({
             cfg: params.cfg,
             owner: params.owner,
             repo: params.repo,
             ref: params.ref,
             destDir: tmpArchiveDir,
+            onProgress: (downloaded, total, msg) => {
+                const percent = total ? Math.round((downloaded / total) * 100) : 0;
+                params.onProgress?.('downloading', percent, `${repoId}: ${msg}`);
+            },
         });
         repoRootForIngest = archive.repoRoot;
         fetchedAt = archive.fetchedAt;
@@ -721,6 +855,15 @@ export async function createBundle(cfg, input, options) {
 }
 async function createBundleInternal(cfg, input, options) {
     const fingerprint = computeCreateInputFingerprint(input);
+    const repoIds = input.repos.map((r) => r.repo);
+    const onProgress = options?.onProgress;
+    const tracker = getProgressTracker();
+    // Helper to report progress
+    const reportProgress = (phase, progress, message, total) => {
+        if (onProgress) {
+            onProgress(phase, progress, message, total);
+        }
+    };
     const ifExists = options?.ifExists ?? 'error';
     if (ifExists !== 'createNew') {
         const existing = await findExistingBundleByFingerprint(cfg, fingerprint);
@@ -735,6 +878,28 @@ async function createBundleInternal(cfg, input, options) {
             throw new Error(`Bundle already exists for these inputs: ${existing}`);
         }
     }
+    // Start tracking this task
+    const taskId = tracker.startTask(fingerprint, repoIds);
+    reportProgress('starting', 0, `Starting bundle creation for ${repoIds.join(', ')}`);
+    // Try to acquire in-progress lock
+    const lockResult = await setInProgressLock(cfg, fingerprint, taskId, repoIds);
+    if (!lockResult.locked) {
+        // Another task is already creating this bundle
+        const entry = lockResult.existingEntry;
+        const elapsedSec = entry.startedAt
+            ? Math.round((Date.now() - new Date(entry.startedAt).getTime()) / 1000)
+            : 0;
+        const msg = `Bundle creation already in progress (taskId: ${entry.taskId}, started ${elapsedSec}s ago). ` +
+            `Use preflight_get_task_status to check progress.`;
+        // Throw a special error that can be caught and handled
+        const err = new Error(msg);
+        err.code = 'BUNDLE_IN_PROGRESS';
+        err.taskId = entry.taskId;
+        err.fingerprint = fingerprint;
+        err.repos = entry.repos;
+        err.startedAt = entry.startedAt;
+        throw err;
+    }
     const bundleId = crypto.randomUUID();
     const createdAt = nowIso();
     // Use effective storage dir (falls back if primary unavailable)
@@ -749,9 +914,15 @@ async function createBundleInternal(cfg, input, options) {
     const reposSummary = [];
     try {
         // All operations happen in tmpPaths (temporary directory)
+        const totalRepos = input.repos.length;
+        let repoIndex = 0;
         for (const repoInput of input.repos) {
+            repoIndex++;
+            const repoProgress = Math.round((repoIndex - 1) / totalRepos * 40); // 0-40% for repo fetching
             if (repoInput.kind === 'github') {
                 const { owner, repo } = parseOwnerRepo(repoInput.repo);
+                reportProgress('cloning', repoProgress, `[${repoIndex}/${totalRepos}] Fetching ${owner}/${repo}...`);
+                tracker.updateProgress(taskId, 'cloning', repoProgress, `Fetching ${owner}/${repo}...`);
                 const { headSha, files, skipped, notes, source } = await cloneAndIngestGitHubRepo({
                     cfg,
                     bundleId,
@@ -759,6 +930,12 @@ async function createBundleInternal(cfg, input, options) {
                     owner,
                     repo,
                     ref: repoInput.ref,
+                    onProgress: (phase, percent, msg) => {
+                        // Map clone/download progress to overall progress (0-40% range per repo)
+                        const overallProgress = repoProgress + Math.round(percent * 0.4 / totalRepos);
+                        reportProgress(phase, overallProgress, `[${repoIndex}/${totalRepos}] ${msg}`);
+                        tracker.updateProgress(taskId, phase, overallProgress, msg);
+                    },
                 });
                 allIngestedFiles.push(...files);
                 reposSummary.push({
@@ -772,6 +949,8 @@ async function createBundleInternal(cfg, input, options) {
             else {
                 // Local repository
                 const { owner, repo } = parseOwnerRepo(repoInput.repo);
+                reportProgress('ingesting', repoProgress, `[${repoIndex}/${totalRepos}] Ingesting local ${owner}/${repo}...`);
+                tracker.updateProgress(taskId, 'ingesting', repoProgress, `Ingesting local ${owner}/${repo}...`);
                 const { files, skipped } = await ingestLocalRepo({
                     cfg,
                     bundleId,
@@ -801,6 +980,8 @@ async function createBundleInternal(cfg, input, options) {
             librariesSummary = libIngest.libraries;
         }
         // Build index.
+        reportProgress('indexing', 50, `Building search index (${allIngestedFiles.length} files)...`);
+        tracker.updateProgress(taskId, 'indexing', 50, `Building search index (${allIngestedFiles.length} files)...`);
         await rebuildIndex(tmpPaths.searchDbPath, allIngestedFiles, {
             includeDocs: true,
             includeCode: true,
@@ -859,6 +1040,8 @@ async function createBundleInternal(cfg, input, options) {
             libraries: librariesSummary,
         });
         // Generate static facts (FACTS.json) FIRST. This is intentionally non-LLM and safe to keep inside bundles.
+        reportProgress('analyzing', 70, 'Analyzing code structure...');
+        tracker.updateProgress(taskId, 'analyzing', 70, 'Analyzing code structure...');
         await generateFactsBestEffort({
             bundleId,
             bundleRoot: tmpPaths.rootDir,
@@ -866,6 +1049,8 @@ async function createBundleInternal(cfg, input, options) {
             mode: cfg.analysisMode,
         });
         // Overview (S2: factual-only with evidence pointers) - generated AFTER FACTS.json
+        reportProgress('generating', 80, 'Generating overview...');
+        tracker.updateProgress(taskId, 'generating', 80, 'Generating overview...');
         const perRepoOverviews = reposSummary
             .filter((r) => r.kind === 'github' || r.kind === 'local')
             .map((r) => {
@@ -889,6 +1074,8 @@ async function createBundleInternal(cfg, input, options) {
         }
         // ATOMIC OPERATION: Move from temp to final location
         // This is atomic on most filesystems - bundle becomes visible only when complete
+        reportProgress('finalizing', 90, 'Finalizing bundle...');
+        tracker.updateProgress(taskId, 'finalizing', 90, 'Finalizing bundle...');
         logger.info(`Moving bundle ${bundleId} from temp to final location (atomic)`);
         await ensureDir(effectiveStorageDir);
         try {
@@ -915,7 +1102,10 @@ async function createBundleInternal(cfg, input, options) {
             await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
         }
         // Update de-duplication index (best-effort). This is intentionally after atomic move.
-        await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, createdAt);
+        await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, createdAt, 'complete');
+        // Mark task complete
+        reportProgress('complete', 100, `Bundle created: ${bundleId}`);
+        tracker.completeTask(taskId, bundleId);
         const summary = {
             bundleId,
             createdAt,
@@ -929,8 +1119,15 @@ async function createBundleInternal(cfg, input, options) {
         // Clean up temp directory on failure
         logger.error(`Bundle creation failed, cleaning up temp: ${bundleId}`, err instanceof Error ? err : undefined);
         await rmIfExists(tmpPaths.rootDir);
-        // Enhance error message
+        // Clear in-progress lock on failure
+        await clearInProgressLock(cfg, fingerprint);
+        // Mark task failed
         const errorMsg = err instanceof Error ? err.message : String(err);
+        tracker.failTask(taskId, errorMsg);
+        // Re-throw with enhanced message (unless it's already our BUNDLE_IN_PROGRESS error)
+        if (err?.code === 'BUNDLE_IN_PROGRESS') {
+            throw err;
+        }
         throw new Error(`Failed to create bundle: ${errorMsg}`);
     }
     finally {
@@ -1198,15 +1395,27 @@ export async function updateBundle(cfg, bundleId, options) {
     const paths = getBundlePaths(effectiveStorageDir, bundleId);
     const manifest = await readManifest(paths.manifestPath);
     const updatedAt = nowIso();
+    const onProgress = options?.onProgress;
+    // Report progress helper
+    const reportProgress = (phase, progress, message, total) => {
+        if (onProgress) {
+            onProgress(phase, progress, message, total);
+        }
+    };
+    reportProgress('starting', 0, `Updating bundle ${bundleId}...`);
     let changed = false;
     const allIngestedFiles = [];
     const reposSummary = [];
+    const totalRepos = manifest.inputs.repos.length;
+    let repoIndex = 0;
     // Rebuild everything obvious for now (simple + deterministic).
     for (const repoInput of manifest.inputs.repos) {
+        repoIndex++;
         if (repoInput.kind === 'github') {
             const { owner, repo } = parseOwnerRepo(repoInput.repo);
             const repoId = `${owner}/${repo}`;
             const cloneUrl = toCloneUrl({ owner, repo });
+            reportProgress('cloning', calcPercent(repoIndex - 1, totalRepos), `Checking ${repoId}...`, totalRepos);
             let remoteSha;
             try {
                 remoteSha = await getRemoteHeadSha(cloneUrl);
@@ -1218,6 +1427,7 @@ export async function updateBundle(cfg, bundleId, options) {
             if (remoteSha && prev?.headSha && remoteSha !== prev.headSha) {
                 changed = true;
             }
+            reportProgress('downloading', calcPercent(repoIndex - 1, totalRepos), `Fetching ${repoId}...`, totalRepos);
             const { headSha, files, skipped, notes, source } = await cloneAndIngestGitHubRepo({
                 cfg,
                 bundleId,
@@ -1225,6 +1435,9 @@ export async function updateBundle(cfg, bundleId, options) {
                 owner,
                 repo,
                 ref: repoInput.ref,
+                onProgress: (phase, progress, message) => {
+                    reportProgress(phase, progress, message);
+                },
             });
             if (prev?.headSha && headSha && headSha !== prev.headSha) {
                 changed = true;
@@ -1257,6 +1470,7 @@ export async function updateBundle(cfg, bundleId, options) {
     // Context7 libraries (best-effort).
     let librariesSummary;
     if (manifest.inputs.libraries?.length) {
+        reportProgress('downloading', 80, 'Fetching Context7 libraries...');
         await rmIfExists(paths.librariesDir);
         await ensureDir(paths.librariesDir);
         const libIngest = await ingestContext7Libraries({
@@ -1269,6 +1483,7 @@ export async function updateBundle(cfg, bundleId, options) {
         librariesSummary = libIngest.libraries;
     }
     // Rebuild index.
+    reportProgress('indexing', 85, `Rebuilding search index (${allIngestedFiles.length} files)...`);
     await rebuildIndex(paths.searchDbPath, allIngestedFiles, {
         includeDocs: manifest.index.includeDocs,
         includeCode: manifest.index.includeCode,
@@ -1294,6 +1509,7 @@ export async function updateBundle(cfg, bundleId, options) {
     };
     await writeManifest(paths.manifestPath, newManifest);
     // Regenerate guides + overview.
+    reportProgress('generating', 90, 'Regenerating guides and overview...');
     await writeAgentsMd(paths.agentsPath);
     await writeStartHereMd({
         targetPath: paths.startHerePath,
@@ -1316,6 +1532,7 @@ export async function updateBundle(cfg, bundleId, options) {
     });
     await writeOverviewFile(paths.overviewPath, overviewMd);
     // Refresh static facts (FACTS.json) after update.
+    reportProgress('analyzing', 95, 'Analyzing bundle...');
     await generateFactsBestEffort({
         bundleId,
         bundleRoot: paths.rootDir,
@@ -1323,11 +1540,13 @@ export async function updateBundle(cfg, bundleId, options) {
         mode: cfg.analysisMode,
     });
     // Mirror to backup storage directories (non-blocking on failures)
+    reportProgress('finalizing', 98, 'Finalizing update...');
     if (cfg.storageDirs.length > 1) {
         await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
     }
     // Keep the de-duplication index fresh (best-effort).
     await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, updatedAt);
+    reportProgress('complete', 100, `Bundle updated: ${bundleId}`);
     const summary = {
         bundleId,
         createdAt: manifest.createdAt,

package/dist/config.js

@@ -88,5 +88,6 @@ export function getConfig() {
         defaultMaxAgeHours: envNumber('PREFLIGHT_DEFAULT_MAX_AGE_HOURS', 24),
         maxSearchLimit: envNumber('PREFLIGHT_MAX_SEARCH_LIMIT', 200),
         defaultSearchLimit: envNumber('PREFLIGHT_DEFAULT_SEARCH_LIMIT', 30),
+        inProgressLockTimeoutMs: envNumber('PREFLIGHT_IN_PROGRESS_LOCK_TIMEOUT_MS', 30 * 60_000),
     };
 }