preflight-mcp 0.1.2 → 0.1.4

package/dist/server.js

@@ -3,13 +3,18 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
 import { getConfig } from './config.js';
-import { bundleExists, checkForUpdates, clearBundleMulti, createBundle, findBundleByInputs, computeCreateInputFingerprint, findBundleStorageDir, getBundlePathsForId, getEffectiveStorageDir, listBundles, repairBundle, updateBundle, } from './bundle/service.js';
+import { assertBundleComplete, checkForUpdates, checkInProgressLock, clearBundleMulti, computeCreateInputFingerprint, createBundle, findBundleStorageDir, getBundlePathsForId, getEffectiveStorageDir, listBundles, repairBundle, updateBundle, } from './bundle/service.js';
+import { getProgressTracker } from './jobs/progressTracker.js';
 import { readManifest } from './bundle/manifest.js';
 import { safeJoin, toBundleFileUri } from './mcp/uris.js';
 import { wrapPreflightError } from './mcp/errorKinds.js';
-import { searchIndex, verifyClaimInIndex } from './search/sqliteFts.js';
+import { searchIndex } from './search/sqliteFts.js';
+import { logger } from './logging/logger.js';
 import { runSearchByTags } from './tools/searchByTags.js';
 import { cleanupOnStartup, cleanupOrphanBundles } from './bundle/cleanup.js';
+import { startHttpServer } from './http/server.js';
+import { DependencyGraphInputSchema, generateDependencyGraph } from './evidence/dependencyGraph.js';
+import { TraceQueryInputSchema, TraceUpsertInputSchema, traceQuery, traceUpsert } from './trace/service.js';
 const CreateRepoInputSchema = z.union([
     z.object({
         kind: z.literal('github'),
@@ -24,10 +29,6 @@ const CreateRepoInputSchema = z.union([
         path: z.string().describe('Local directory path containing the repository files.'),
         ref: z.string().optional().describe('Optional label/ref for the local snapshot.'),
     }),
-    z.object({
-        kind: z.literal('deepwiki'),
-        url: z.string().url().describe('DeepWiki URL (https://deepwiki.com/owner/repo).'),
-    }),
 ]);
 const CreateBundleInputSchema = {
     repos: z.array(CreateRepoInputSchema).min(1).describe('Repositories to ingest into the bundle.'),
@@ -43,12 +44,6 @@ const UpdateBundleInputSchema = {
     checkOnly: z.boolean().optional().describe('If true, only check if updates are available without applying them.'),
     force: z.boolean().optional().describe('If true, force rebuild index even if no changes detected.'),
 };
-const UpdateAllBundlesInputSchema = {
-    bundleIds: z
-        .array(z.string())
-        .optional()
-        .describe('Optional bundle IDs to update. If omitted, updates all bundles in storage.'),
-};
 const SearchBundleInputSchema = {
     bundleId: z.string().describe('Bundle ID to search.'),
     query: z.string().describe('Search query. Prefix with fts: to use raw FTS syntax.'),
@@ -74,25 +69,6 @@ const SearchByTagsInputSchema = {
     scope: z.enum(['docs', 'code', 'all']).default('all').describe('Search scope.'),
     limit: z.number().int().min(1).max(200).default(50).describe('Max total hits across all bundles.'),
 };
-const VerifyClaimInputSchema = {
-    bundleId: z.string().describe('Bundle ID to verify against.'),
-    claim: z.string().describe('A claim to look for evidence for (best-effort).'),
-    scope: z.enum(['docs', 'code', 'all']).default('all').describe('Search scope.'),
-    limit: z.number().int().min(1).max(50).default(8).describe('Max number of evidence hits.'),
-    // Deprecated (kept for backward compatibility): this tool is strictly read-only.
-    ensureFresh: z
-        .boolean()
-        .optional()
-        .describe('DEPRECATED. This tool is strictly read-only and will not auto-update. Use preflight_update_bundle, then call verify again.'),
-    maxAgeHours: z
-        .number()
-        .optional()
-        .describe('DEPRECATED. Only used with ensureFresh (which is deprecated).'),
-    autoRepairIndex: z
-        .boolean()
-        .optional()
-        .describe('DEPRECATED. This tool is strictly read-only and will not auto-repair. Use preflight_repair_bundle, then call verify again.'),
-};
 const ListBundlesInputSchema = {
 // keep open for future filters
 };
@@ -106,22 +82,24 @@ const RepairBundleInputSchema = {
     rebuildGuides: z.boolean().optional().describe('If true, rebuild START_HERE.md and AGENTS.md when missing/empty.'),
     rebuildOverview: z.boolean().optional().describe('If true, rebuild OVERVIEW.md when missing/empty.'),
 };
-const BundleInfoInputSchema = {
-    bundleId: z.string().describe('Bundle ID to get info for.'),
-};
-const ReadFileInputSchema = {
-    bundleId: z.string().describe('Bundle ID.'),
-    file: z.string().default('OVERVIEW.md').describe('File path relative to bundle root. Common files: OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, or any repo file like repos/owner/repo/norm/README.md'),
+const GetTaskStatusInputSchema = {
+    taskId: z.string().optional().describe('Task ID to query (from BUNDLE_IN_PROGRESS error).'),
+    fingerprint: z.string().optional().describe('Fingerprint to query (computed from repos/libraries/topics).'),
+    repos: z.array(CreateRepoInputSchema).optional().describe('Repos to compute fingerprint from (alternative to fingerprint).'),
+    libraries: z.array(z.string()).optional().describe('Libraries for fingerprint computation.'),
+    topics: z.array(z.string()).optional().describe('Topics for fingerprint computation.'),
 };
 export async function startServer() {
     const cfg = getConfig();
     // Run orphan bundle cleanup on startup (non-blocking, best-effort)
-    cleanupOnStartup(cfg).catch(() => {
-        // Errors already logged, don't block server startup
+    cleanupOnStartup(cfg).catch((err) => {
+        logger.debug('Startup cleanup failed (non-critical)', err instanceof Error ? err : undefined);
     });
+    // Start built-in REST API (best-effort). This must not interfere with MCP stdio transport.
+    startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.1.2',
+        version: '0.1.4',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -280,13 +258,20 @@ export async function startServer() {
         };
     });
     server.registerTool('preflight_read_file', {
-        title: 'Read bundle file',
-        description: 'Read a file from bundle. Use when: "show overview", "read file", "查看概览", "项目概览", "看README", "查看文档". Common files: OVERVIEW.md, START_HERE.md, AGENTS.md.',
-        inputSchema: ReadFileInputSchema,
+        title: 'Read bundle file(s)',
+        description: 'Read file(s) from bundle. Two modes: ' +
+            '(1) Omit "file" param → returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs) in one call. ' +
+            '(2) Provide "file" param → returns that specific file. ' +
+            'Use when: "查看bundle", "show bundle", "read overview", "bundle概览", "项目信息".',
+        inputSchema: {
+            bundleId: z.string().describe('Bundle ID to read.'),
+            file: z.string().optional().describe('Specific file to read. If omitted, returns all key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs).'),
+        },
         outputSchema: {
             bundleId: z.string(),
-            file: z.string(),
-            content: z.string(),
+            file: z.string().optional(),
+            content: z.string().optional(),
+            files: z.record(z.string(), z.string().nullable()).optional(),
         },
         annotations: {
             readOnlyHint: true,
@@ -297,16 +282,66 @@ export async function startServer() {
             if (!storageDir) {
                 throw new Error(`Bundle not found: ${args.bundleId}`);
             }
-            const bundleRoot = getBundlePathsForId(storageDir, args.bundleId).rootDir;
-            const absPath = safeJoin(bundleRoot, args.file);
-            const content = await fs.readFile(absPath, 'utf8');
-            const out = {
-                bundleId: args.bundleId,
-                file: args.file,
-                content,
-            };
+            const paths = getBundlePathsForId(storageDir, args.bundleId);
+            const bundleRoot = paths.rootDir;
+            // Single file mode
+            if (args.file) {
+                const absPath = safeJoin(bundleRoot, args.file);
+                const content = await fs.readFile(absPath, 'utf8');
+                const out = { bundleId: args.bundleId, file: args.file, content };
+                return {
+                    content: [{ type: 'text', text: content }],
+                    structuredContent: out,
+                };
+            }
+            // Batch mode: read all key files
+            const keyFiles = ['OVERVIEW.md', 'START_HERE.md', 'AGENTS.md', 'manifest.json'];
+            const files = {};
+            for (const file of keyFiles) {
+                try {
+                    const absPath = safeJoin(bundleRoot, file);
+                    files[file] = await fs.readFile(absPath, 'utf8');
+                }
+                catch {
+                    files[file] = null;
+                }
+            }
+            // Try to find and read repo README files
+            try {
+                const manifest = await readManifest(paths.manifestPath);
+                for (const repo of manifest.repos ?? []) {
+                    if (!repo.id)
+                        continue;
+                    const [owner, repoName] = repo.id.split('/');
+                    if (!owner || !repoName)
+                        continue;
+                    const readmeNames = ['README.md', 'readme.md', 'Readme.md', 'README.MD'];
+                    for (const readmeName of readmeNames) {
+                        const readmePath = `repos/${owner}/${repoName}/norm/${readmeName}`;
+                        try {
+                            const absPath = safeJoin(bundleRoot, readmePath);
+                            files[readmePath] = await fs.readFile(absPath, 'utf8');
+                            break;
+                        }
+                        catch {
+                            // Try next
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore manifest read errors
+            }
+            // Build combined text output
+            const textParts = [];
+            for (const [filePath, content] of Object.entries(files)) {
+                if (content) {
+                    textParts.push(`=== ${filePath} ===\n${content}`);
+                }
+            }
+            const out = { bundleId: args.bundleId, files };
             return {
-                content: [{ type: 'text', text: content }],
+                content: [{ type: 'text', text: textParts.join('\n\n') || '(no files found)' }],
                 structuredContent: out,
             };
         }
@@ -342,131 +377,9 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
-    server.registerTool('preflight_bundle_info', {
-        title: 'Bundle info',
-        description: 'Get bundle details: repos, update time, stats. Use when: "bundle info", "show bundle details", "what\'s in this bundle", "bundle状态", "查看bundle详情", "仓库信息".',
-        inputSchema: BundleInfoInputSchema,
-        outputSchema: {
-            bundleId: z.string(),
-            createdAt: z.string(),
-            updatedAt: z.string(),
-            repos: z.array(z.object({
-                kind: z.enum(['github', 'local', 'deepwiki']),
-                id: z.string(),
-                source: z.enum(['git', 'archive', 'local', 'deepwiki']).optional(),
-                headSha: z.string().optional(),
-                fetchedAt: z.string().optional(),
-                notes: z.array(z.string()).optional(),
-            })),
-            libraries: z
-                .array(z.object({
-                kind: z.literal('context7'),
-                input: z.string(),
-                id: z.string().optional(),
-                fetchedAt: z.string(),
-                notes: z.array(z.string()).optional(),
-                files: z.array(z.string()).optional(),
-            }))
-                .optional(),
-            index: z.object({
-                backend: z.string(),
-                includeDocs: z.boolean(),
-                includeCode: z.boolean(),
-            }),
-            resources: z.object({
-                startHere: z.string(),
-                agents: z.string(),
-                overview: z.string(),
-                manifest: z.string(),
-            }),
-        },
-        annotations: {
-            readOnlyHint: true,
-        },
-    }, async (args) => {
-        try {
-            const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
-            if (!storageDir) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
-            }
-            const paths = getBundlePathsForId(storageDir, args.bundleId);
-            const manifest = await readManifest(paths.manifestPath);
-            const resources = {
-                startHere: toBundleFileUri({ bundleId: args.bundleId, relativePath: 'START_HERE.md' }),
-                agents: toBundleFileUri({ bundleId: args.bundleId, relativePath: 'AGENTS.md' }),
-                overview: toBundleFileUri({ bundleId: args.bundleId, relativePath: 'OVERVIEW.md' }),
-                manifest: toBundleFileUri({ bundleId: args.bundleId, relativePath: 'manifest.json' }),
-            };
-            const out = {
-                bundleId: manifest.bundleId,
-                createdAt: manifest.createdAt,
-                updatedAt: manifest.updatedAt,
-                repos: manifest.repos,
-                libraries: manifest.libraries,
-                index: manifest.index,
-                resources,
-            };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
-                structuredContent: out,
-            };
-        }
-        catch (err) {
-            throw wrapPreflightError(err);
-        }
-    });
-    server.registerTool('preflight_find_bundle', {
-        title: 'Find existing bundle',
-        description: 'Check whether a bundle already exists for the given inputs (no fetching, no changes). Use when: "does this repo already exist", "have I indexed this", "find bundle for", "这个项目是否已索引".',
-        inputSchema: {
-            repos: z.array(CreateRepoInputSchema).min(1),
-            libraries: z.array(z.string()).optional(),
-            topics: z.array(z.string()).optional(),
-        },
-        outputSchema: {
-            found: z.boolean(),
-            bundleId: z.string().optional(),
-            fingerprint: z.string(),
-        },
-        annotations: {
-            readOnlyHint: true,
-        },
-    }, async (args) => {
-        try {
-            const fingerprint = computeCreateInputFingerprint({
-                repos: args.repos,
-                libraries: args.libraries,
-                topics: args.topics,
-            });
-            const bundleId = await findBundleByInputs(cfg, {
-                repos: args.repos,
-                libraries: args.libraries,
-                topics: args.topics,
-            });
-            const out = {
-                found: !!bundleId,
-                bundleId: bundleId ?? undefined,
-                fingerprint,
-            };
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: out.found
-                            ? `FOUND ${out.bundleId} (fingerprint=${out.fingerprint})`
-                            : `NOT_FOUND (fingerprint=${out.fingerprint})`,
-                    },
-                ],
-                structuredContent: out,
-            };
-        }
-        catch (err) {
-            throw wrapPreflightError(err);
-        }
-    });
     server.registerTool('preflight_create_bundle', {
         title: 'Create bundle',
-        description: 'Create a new bundle from GitHub repos or DeepWiki (or update an existing one if ifExists=updateExisting). Use when: "index this repo", "create bundle for", "add repo to preflight", "索引这个仓库", "创建bundle", "添加GitHub项目", "学习这个项目".',
+        description: 'Create a new bundle from GitHub repos or local directories (or update an existing one if ifExists=updateExisting). Use when: "index this repo", "create bundle for", "add repo to preflight", "索引这个仓库", "创建bundle", "添加GitHub项目", "学习这个项目". NOTE: If the bundle contains code files, consider asking user if they want to generate dependency graph (preflight_evidence_dependency_graph) or establish trace links (preflight_trace_upsert).',
         inputSchema: CreateBundleInputSchema,
         outputSchema: {
             bundleId: z.string(),
@@ -479,9 +392,9 @@ export async function startServer() {
                 manifest: z.string(),
             }),
             repos: z.array(z.object({
-                kind: z.enum(['github', 'local', 'deepwiki']),
+                kind: z.enum(['github', 'local']),
                 id: z.string(),
-                source: z.enum(['git', 'archive', 'local', 'deepwiki']).optional(),
+                source: z.enum(['git', 'archive', 'local']).optional(),
                 headSha: z.string().optional(),
                 notes: z.array(z.string()).optional(),
             })),
@@ -524,6 +437,31 @@ export async function startServer() {
             };
         }
         catch (err) {
+            // Handle BUNDLE_IN_PROGRESS error specially - provide useful info instead of just error
+            if (err?.code === 'BUNDLE_IN_PROGRESS') {
+                const elapsedSec = err.startedAt
+                    ? Math.round((Date.now() - new Date(err.startedAt).getTime()) / 1000)
+                    : 0;
+                // Check current progress from tracker
+                const tracker = getProgressTracker();
+                const task = err.taskId ? tracker.getTask(err.taskId) : undefined;
+                const out = {
+                    status: 'in-progress',
+                    message: `Bundle creation already in progress. Use preflight_get_task_status to check progress.`,
+                    taskId: err.taskId,
+                    fingerprint: err.fingerprint,
+                    repos: err.repos,
+                    startedAt: err.startedAt,
+                    elapsedSeconds: elapsedSec,
+                    currentPhase: task?.phase,
+                    currentProgress: task?.progress,
+                    currentMessage: task?.message,
+                };
+                return {
+                    content: [{ type: 'text', text: `⚠️ Bundle creation in progress (${elapsedSec}s elapsed). ${task ? `Current: ${task.phase} (${task.progress}%) - ${task.message}` : 'Use preflight_get_task_status to check progress.'}` }],
+                    structuredContent: out,
+                };
+            }
             throw wrapPreflightError(err);
         }
     });
@@ -634,72 +572,42 @@ export async function startServer() {
                     structuredContent: out,
                 };
             }
-            const { summary, changed } = await updateBundle(cfg, args.bundleId, { force: args.force });
-            const resources = {
-                startHere: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'START_HERE.md' }),
-                agents: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'AGENTS.md' }),
-                overview: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'OVERVIEW.md' }),
-                manifest: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'manifest.json' }),
-            };
-            const out = {
-                changed: args.force ? true : changed,
-                ...summary,
-                resources,
-            };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
-                structuredContent: out,
-            };
-        }
-        catch (err) {
-            throw wrapPreflightError(err);
-        }
-    });
-    server.registerTool('preflight_update_all_bundles', {
-        title: 'Update all bundles',
-        description: 'Batch update all bundles at once. Use when: "update all bundles", "refresh everything", "sync all", "批量更新", "全部刷新", "更新所有bundle".',
-        inputSchema: UpdateAllBundlesInputSchema,
-        outputSchema: {
-            total: z.number().int(),
-            ok: z.number().int(),
-            results: z.array(z.object({
-                bundleId: z.string(),
-                changed: z.boolean().optional(),
-                updatedAt: z.string().optional(),
-                error: z.string().optional(),
-            })),
-        },
-        annotations: {
-            openWorldHint: true,
-        },
-    }, async (args) => {
-        const effectiveDir = await getEffectiveStorageDir(cfg);
-        const ids = args.bundleIds && args.bundleIds.length > 0
-            ? args.bundleIds
-            : await listBundles(effectiveDir);
-        const results = [];
-        for (const bundleId of ids) {
+            // Create task for progress tracking
+            const tracker = getProgressTracker();
+            const fingerprint = `update-${args.bundleId}`;
+            const taskId = tracker.startTask(fingerprint, [args.bundleId]);
             try {
-                const exists = await bundleExists(effectiveDir, bundleId);
-                if (!exists) {
-                    throw new Error(`Bundle not found: ${bundleId}`);
-                }
-                const { summary, changed } = await updateBundle(cfg, bundleId);
-                results.push({ bundleId, changed, updatedAt: summary.updatedAt });
+                const { summary, changed } = await updateBundle(cfg, args.bundleId, {
+                    force: args.force,
+                    onProgress: (phase, progress, message, total) => {
+                        tracker.updateProgress(taskId, phase, progress, message, total);
+                    },
+                });
+                tracker.completeTask(taskId, args.bundleId);
+                const resources = {
+                    startHere: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'START_HERE.md' }),
+                    agents: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'AGENTS.md' }),
+                    overview: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'OVERVIEW.md' }),
+                    manifest: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'manifest.json' }),
+                };
+                const out = {
+                    changed: args.force ? true : changed,
+                    ...summary,
+                    resources,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                    structuredContent: out,
+                };
             }
-            catch (err) {
-                results.push({ bundleId, error: wrapPreflightError(err).message });
+            catch (updateErr) {
+                tracker.failTask(taskId, updateErr instanceof Error ? updateErr.message : String(updateErr));
+                throw updateErr;
             }
         }
-        const out = {
-            total: ids.length,
-            ok: results.filter((r) => !r.error).length,
-            results,
-        };
-        return {
-            content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
-            structuredContent: out,
-        };
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
     });
     server.registerTool('preflight_search_by_tags', {
         title: 'Search by tags',
@@ -749,7 +657,7 @@ export async function startServer() {
             },
             searchIndexForBundleId: (bundleId, query, scope, limit) => {
                 const paths = getBundlePathsForId(effectiveDir, bundleId);
-                return searchIndex(paths.searchDbPath, query, scope, limit);
+                return searchIndex(paths.searchDbPath, query, scope, limit, paths.rootDir);
             },
             toUri: (bundleId, p) => toBundleFileUri({ bundleId, relativePath: p }),
         });
@@ -801,6 +709,8 @@ export async function startServer() {
         },
     }, async (args) => {
         try {
+            // Check bundle completeness before any operation
+            await assertBundleComplete(cfg, args.bundleId);
             // Resolve bundle location across storageDirs (more robust than a single effectiveDir).
             const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
             if (!storageDir) {
@@ -815,7 +725,7 @@ export async function startServer() {
                     'Call preflight_repair_bundle explicitly, then call preflight_search_bundle again.');
             }
             const paths = getBundlePathsForId(storageDir, args.bundleId);
-            const rawHits = searchIndex(paths.searchDbPath, args.query, args.scope, args.limit);
+            const rawHits = searchIndex(paths.searchDbPath, args.query, args.scope, args.limit, paths.rootDir);
             const hits = rawHits.map((h) => ({
                 ...h,
                 uri: toBundleFileUri({ bundleId: args.bundleId, relativePath: h.path }),
@@ -835,98 +745,93 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
-    server.registerTool('preflight_verify_claim', {
-        title: 'Verify claim',
-        description: 'Verify a claim with evidence classification and confidence scoring (strictly read-only). If you need to update or repair, call preflight_update_bundle or preflight_repair_bundle explicitly, then verify again. Returns supporting/contradicting/related evidence. Use when: "verify this claim", "is this true", "find evidence for", "check if", "验证说法", "找证据", "这个对吗", "有没有依据".',
-        inputSchema: VerifyClaimInputSchema,
+    server.registerTool('preflight_evidence_dependency_graph', {
+        title: 'Evidence: dependency graph (callers + imports)',
+        description: 'Generate an evidence-based dependency graph. Two modes: ' +
+            '(1) TARGET MODE: provide target.file to analyze a specific file\'s imports and callers. ' +
+            '(2) GLOBAL MODE: omit target to generate a project-wide import graph of all code files. ' +
+            'For target mode, file path must be bundle-relative: repos/{owner}/{repo}/norm/{path}. ' +
+            'Use preflight_search_bundle to find file paths, or check OVERVIEW.md.',
+        inputSchema: DependencyGraphInputSchema,
+        outputSchema: {
+            meta: z.any(),
+            facts: z.any(),
+            signals: z.any(),
+        },
+        annotations: {
+            readOnlyHint: true,
+        },
+    }, async (args) => {
+        try {
+            // Check bundle completeness before generating dependency graph
+            await assertBundleComplete(cfg, args.bundleId);
+            const out = await generateDependencyGraph(cfg, args);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                structuredContent: out,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
+    server.registerTool('preflight_trace_upsert', {
+        title: 'Trace: upsert links',
+        description: 'Upsert traceability links (commit↔ticket, symbol↔test, code↔doc, etc.) for a bundle. Stores trace edges in a per-bundle SQLite database.',
+        inputSchema: TraceUpsertInputSchema,
         outputSchema: {
             bundleId: z.string(),
-            claim: z.string(),
-            scope: z.enum(['docs', 'code', 'all']),
-            found: z.boolean(),
-            confidence: z.number().describe('Confidence score 0-1'),
-            confidenceLabel: z.enum(['high', 'medium', 'low', 'none']),
-            summary: z.string().describe('Human-readable summary of verification'),
-            supporting: z.array(z.object({
-                kind: z.enum(['doc', 'code']),
-                repo: z.string(),
-                path: z.string(),
-                lineNo: z.number(),
-                snippet: z.string(),
-                uri: z.string(),
-                evidenceType: z.enum(['supporting', 'contradicting', 'related']),
-                relevanceScore: z.number(),
-            })).describe('Evidence supporting the claim'),
-            contradicting: z.array(z.object({
-                kind: z.enum(['doc', 'code']),
-                repo: z.string(),
-                path: z.string(),
-                lineNo: z.number(),
-                snippet: z.string(),
-                uri: z.string(),
-                evidenceType: z.enum(['supporting', 'contradicting', 'related']),
-                relevanceScore: z.number(),
-            })).describe('Evidence contradicting the claim'),
-            related: z.array(z.object({
-                kind: z.enum(['doc', 'code']),
-                repo: z.string(),
-                path: z.string(),
-                lineNo: z.number(),
-                snippet: z.string(),
-                uri: z.string(),
-                evidenceType: z.enum(['supporting', 'contradicting', 'related']),
-                relevanceScore: z.number(),
-            })).describe('Related but inconclusive evidence'),
-            autoUpdated: z
-                .boolean()
-                .optional()
-                .describe('DEPRECATED. This tool is strictly read-only and will not auto-update.'),
-            autoRepaired: z
-                .boolean()
-                .optional()
-                .describe('DEPRECATED. This tool is strictly read-only and will not auto-repair.'),
-            repairActions: z
-                .array(z.string())
-                .optional()
-                .describe('DEPRECATED. This tool is strictly read-only and will not auto-repair.'),
+            upserted: z.number().int(),
+            ids: z.array(z.string()),
+        },
+        annotations: {
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            // Check bundle completeness before trace upsert
+            await assertBundleComplete(cfg, args.bundleId);
+            const out = await traceUpsert(cfg, args);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                structuredContent: out,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
+    server.registerTool('preflight_trace_query', {
+        title: 'Trace: query links',
+        description: 'Query traceability links. Provide bundleId for fast queries; if omitted, scans across bundles (capped). This tool is read-only.',
+        inputSchema: TraceQueryInputSchema,
+        outputSchema: {
+            bundleId: z.string().optional(),
+            scannedBundles: z.number().int().optional(),
+            truncated: z.boolean().optional(),
+            edges: z.array(z.object({
+                id: z.string(),
+                source: z.object({ type: z.string(), id: z.string() }),
+                target: z.object({ type: z.string(), id: z.string() }),
+                type: z.string(),
+                confidence: z.number(),
+                method: z.enum(['exact', 'heuristic']),
+                sources: z.array(z.any()),
+                createdAt: z.string(),
+                updatedAt: z.string(),
+                bundleId: z.string().optional(),
+            })),
         },
         annotations: {
             readOnlyHint: true,
         },
     }, async (args) => {
         try {
-            // Resolve bundle location across storageDirs (more robust than a single effectiveDir).
-            const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
-            if (!storageDir) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
-            }
-            if (args.ensureFresh) {
-                throw new Error('ensureFresh is deprecated and not supported in this tool. This tool is strictly read-only. ' +
-                    'Call preflight_update_bundle explicitly, then call preflight_verify_claim again.');
-            }
-            if (args.autoRepairIndex) {
-                throw new Error('autoRepairIndex is deprecated and not supported in this tool. This tool is strictly read-only. ' +
-                    'Call preflight_repair_bundle explicitly, then call preflight_verify_claim again.');
+            // Check bundle completeness if bundleId is provided
+            if (args.bundleId) {
+                await assertBundleComplete(cfg, args.bundleId);
             }
-            const paths = getBundlePathsForId(storageDir, args.bundleId);
-            const verification = verifyClaimInIndex(paths.searchDbPath, args.claim, args.scope, args.limit);
-            // Add URIs to evidence hits
-            const addUri = (hit) => ({
-                ...hit,
-                uri: toBundleFileUri({ bundleId: args.bundleId, relativePath: hit.path }),
-            });
-            const out = {
-                bundleId: args.bundleId,
-                claim: args.claim,
-                scope: args.scope,
-                found: verification.found,
-                confidence: verification.confidence,
-                confidenceLabel: verification.confidenceLabel,
-                summary: verification.summary,
-                supporting: verification.supporting.map(addUri),
-                contradicting: verification.contradicting.map(addUri),
-                related: verification.related.map(addUri),
-            };
+            const out = await traceQuery(cfg, args);
             return {
                 content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
                 structuredContent: out,
@@ -974,6 +879,115 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
+    // Get task status - for checking progress of in-progress bundle creations
+    server.registerTool('preflight_get_task_status', {
+        title: 'Get task status',
+        description: 'Check status of bundle creation tasks (especially in-progress ones). Use when: "check bundle creation progress", "what is the status", "查看任务状态", "下载进度". Can query by taskId (from error), fingerprint, or repos.',
+        inputSchema: GetTaskStatusInputSchema,
+        outputSchema: {
+            found: z.boolean(),
+            task: z.object({
+                taskId: z.string(),
+                fingerprint: z.string(),
+                phase: z.string(),
+                progress: z.number(),
+                total: z.number().optional(),
+                message: z.string(),
+                startedAt: z.string(),
+                updatedAt: z.string(),
+                repos: z.array(z.string()),
+                bundleId: z.string().optional(),
+                error: z.string().optional(),
+            }).optional(),
+            inProgressLock: z.object({
+                bundleId: z.string(),
+                status: z.string(),
+                startedAt: z.string().optional(),
+                taskId: z.string().optional(),
+                repos: z.array(z.string()).optional(),
+                elapsedSeconds: z.number().optional(),
+            }).optional(),
+            activeTasks: z.array(z.object({
+                taskId: z.string(),
+                fingerprint: z.string(),
+                phase: z.string(),
+                progress: z.number(),
+                message: z.string(),
+                repos: z.array(z.string()),
+                startedAt: z.string(),
+            })).optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+        },
+    }, async (args) => {
+        try {
+            const tracker = getProgressTracker();
+            let result = { found: false };
+            // Compute fingerprint if repos provided
+            let fingerprint = args.fingerprint;
+            if (!fingerprint && args.repos?.length) {
+                fingerprint = computeCreateInputFingerprint({
+                    repos: args.repos,
+                    libraries: args.libraries,
+                    topics: args.topics,
+                });
+            }
+            // Query by taskId
+            if (args.taskId) {
+                const task = tracker.getTask(args.taskId);
+                if (task) {
+                    result = { found: true, task };
+                }
+            }
+            // Query by fingerprint
+            else if (fingerprint) {
+                const task = tracker.getTaskByFingerprint(fingerprint);
+                if (task) {
+                    result = { found: true, task };
+                }
+                // Also check persistent in-progress lock
+                const lock = await checkInProgressLock(cfg, fingerprint);
+                if (lock) {
+                    const elapsedSeconds = lock.startedAt
+                        ? Math.round((Date.now() - new Date(lock.startedAt).getTime()) / 1000)
+                        : undefined;
+                    result.inProgressLock = {
+                        bundleId: lock.bundleId,
+                        status: lock.status ?? 'unknown',
+                        startedAt: lock.startedAt,
+                        taskId: lock.taskId,
+                        repos: lock.repos,
+                        elapsedSeconds,
+                    };
+                    result.found = true;
+                }
+            }
+            // If no specific query, return all active tasks
+            else {
+                const activeTasks = tracker.listActiveTasks();
+                if (activeTasks.length > 0) {
+                    result = { found: true, activeTasks };
+                }
+            }
+            const summary = result.found
+                ? result.task
+                    ? `Task ${result.task.taskId}: ${result.task.phase} (${result.task.progress}%) - ${result.task.message}`
+                    : result.activeTasks
+                        ? `${result.activeTasks.length} active task(s)`
+                        : result.inProgressLock
+                            ? `In-progress lock found (started ${result.inProgressLock.elapsedSeconds}s ago)`
+                            : 'Status found'
+                : 'No matching task found';
+            return {
+                content: [{ type: 'text', text: summary }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
     // Provide backward-compatible parsing of the same URI via resources/read for clients that bypass templates.
     // This is a safety net: if a client gives us a fully-specified URI, we can still serve it.
     server.registerResource('bundle-file-compat', 'preflight://bundle-file', {