@codragraph/cli 1.6.2

package/dist/server/api.js

@@ -0,0 +1,1727 @@
+/**
+ * HTTP API Server
+ *
+ * REST API for browser-based clients to query the local .codragraph/ index.
+ * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
+ *
+ * Security: binds to localhost by default (use --host to override).
+ * CORS is restricted to localhost, private/LAN networks, and the deployed site.
+ */
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import fs from 'fs/promises';
+import { createRequire } from 'node:module';
+import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
+import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeLbug, withLbugDb, } from '../core/lbug/lbug-adapter.js';
+import { isWriteQuery } from '../core/lbug/pool-adapter.js';
+import { NODE_TABLES } from '../_shared/index.js';
+import { searchFTSFromLbug } from '../core/search/bm25-index.js';
+import { hybridSearch } from '../core/search/hybrid-search.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at server startup — crashes on unsupported Node ABI versions (#89)
+import { LocalBackend } from '../mcp/local/local-backend.js';
+import { mountMCPEndpoints } from './mcp-http.js';
+import { fork } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { JobManager } from './analyze-job.js';
+import { extractRepoName, getCloneDir, cloneOrPull } from './git-clone.js';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
+/**
+ * Determine whether an HTTP Origin header value is allowed by CORS policy.
+ *
+ * Permitted origins:
+ * - No origin (non-browser requests such as curl or server-to-server calls)
+ * - http://localhost:<port> — local development
+ * - http://127.0.0.1:<port> — loopback alias
+ * - RFC 1918 private/LAN networks (any port):
+ *     10.0.0.0/8      → 10.x.x.x
+ *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
+ *     192.168.0.0/16  → 192.168.x.x
+ * - https://codragraph.vercel.app — the deployed CodraGraph web UI
+ *
+ * @param origin - The value of the HTTP `Origin` request header, or `undefined`
+ *                 when the header is absent (non-browser request).
+ * @returns `true` if the origin is allowed, `false` otherwise.
+ */
+export const isAllowedOrigin = (origin) => {
+    if (origin === undefined) {
+        // Non-browser requests (curl, server-to-server) have no Origin header
+        return true;
+    }
+    if (origin.startsWith('http://localhost:') ||
+        origin === 'http://localhost' ||
+        origin.startsWith('http://127.0.0.1:') ||
+        origin === 'http://127.0.0.1' ||
+        origin.startsWith('http://[::1]:') ||
+        origin === 'http://[::1]' ||
+        origin === 'https://codragraph.vercel.app') {
+        return true;
+    }
+    // RFC 1918 private network ranges — allow any port on these hosts.
+    // We parse the hostname out of the origin URL and check against each range.
+    let hostname;
+    let protocol;
+    try {
+        const parsed = new URL(origin);
+        hostname = parsed.hostname;
+        protocol = parsed.protocol;
+    }
+    catch {
+        // Malformed origin — reject
+        return false;
+    }
+    // Only allow HTTP(S) origins — reject ftp://, file://, etc.
+    if (protocol !== 'http:' && protocol !== 'https:')
+        return false;
+    const octets = hostname.split('.').map(Number);
+    if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) {
+        return false;
+    }
+    const [a, b] = octets;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 172.16.0.0/12  →  172.16.x.x – 172.31.x.x
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+};
+export class ClientDisconnectedError extends Error {
+    constructor() {
+        super('Client disconnected during graph stream');
+        this.name = 'ClientDisconnectedError';
+    }
+}
+export const isIgnorableGraphQueryError = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.includes('does not exist') ||
+        message.includes('not found') ||
+        message.includes('No table named'));
+};
+const ensureStreamIsWritable = (res, signal) => {
+    if (signal?.aborted || res.destroyed || res.writableEnded) {
+        throw new ClientDisconnectedError();
+    }
+};
+const waitForDrain = async (res, signal) => {
+    ensureStreamIsWritable(res, signal);
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            res.off('drain', onDrain);
+            res.off('close', onClose);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new ClientDisconnectedError());
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new ClientDisconnectedError());
+        };
+        res.once('drain', onDrain);
+        res.once('close', onClose);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted || res.destroyed || res.writableEnded) {
+            onAbort();
+        }
+    });
+    ensureStreamIsWritable(res, signal);
+};
+const isClientDisconnectWriteError = (err) => {
+    if (!(err instanceof Error))
+        return false;
+    return (err.code === 'ERR_STREAM_DESTROYED' ||
+        err.code === 'EPIPE' ||
+        err.code === 'ECONNRESET' ||
+        err.message.includes('write after end'));
+};
+export const writeNdjsonRecord = async (res, record, signal) => {
+    ensureStreamIsWritable(res, signal);
+    try {
+        const canContinue = res.write(JSON.stringify(record) + '\n');
+        if (!canContinue) {
+            await waitForDrain(res, signal);
+        }
+    }
+    catch (err) {
+        if (isClientDisconnectWriteError(err)) {
+            throw new ClientDisconnectedError();
+        }
+        throw err;
+    }
+};
+const buildGraph = async (includeContent = false) => {
+    const nodes = [];
+    for (const table of NODE_TABLES) {
+        try {
+            const rows = await executeQuery(getNodeQuery(table, includeContent));
+            for (const row of rows) {
+                nodes.push(mapGraphNodeRow(table, row, includeContent));
+            }
+        }
+        catch (err) {
+            if (!isIgnorableGraphQueryError(err)) {
+                throw err;
+            }
+        }
+    }
+    const relationships = [];
+    const relRows = await executeQuery(GRAPH_RELATIONSHIP_QUERY);
+    for (const row of relRows) {
+        relationships.push(mapGraphRelationshipRow(row));
+    }
+    return { nodes, relationships };
+};
+const GRAPH_RELATIONSHIP_QUERY = `MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, ` +
+    `r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`;
+const quoteNodeTable = (table) => `\`${table.replace(/`/g, '``')}\``;
+const getNodeQuery = (table, includeContent) => {
+    const tableLabel = quoteNodeTable(table);
+    if (table === 'File') {
+        return includeContent
+            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`
+            : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
+    }
+    if (table === 'Folder') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
+    }
+    if (table === 'Community') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.cohesion AS cohesion, n.symbolCount AS symbolCount`;
+    }
+    if (table === 'Process') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
+    }
+    if (table === 'Route') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware`;
+    }
+    if (table === 'Tool') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
+    }
+    return includeContent
+        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`
+        : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
+};
+const mapGraphNodeRow = (table, row, includeContent) => ({
+    id: row.id ?? row[0],
+    label: table,
+    properties: {
+        name: row.name ?? row.label ?? row[1],
+        filePath: row.filePath ?? row[2],
+        startLine: row.startLine,
+        endLine: row.endLine,
+        content: includeContent ? row.content : undefined,
+        responseKeys: row.responseKeys,
+        errorKeys: row.errorKeys,
+        middleware: row.middleware,
+        heuristicLabel: row.heuristicLabel,
+        cohesion: row.cohesion,
+        symbolCount: row.symbolCount,
+        description: row.description,
+        processType: row.processType,
+        stepCount: row.stepCount,
+        communities: row.communities,
+        entryPointId: row.entryPointId,
+        terminalId: row.terminalId,
+    },
+});
+const mapGraphRelationshipRow = (row) => ({
+    id: `${row.sourceId}_${row.type}_${row.targetId}`,
+    type: row.type,
+    sourceId: row.sourceId,
+    targetId: row.targetId,
+    confidence: row.confidence,
+    reason: row.reason,
+    step: row.step,
+});
+export const streamGraphNdjson = async (res, includeContent = false, signal) => {
+    for (const table of NODE_TABLES) {
+        try {
+            await streamQuery(getNodeQuery(table, includeContent), async (row) => {
+                await writeNdjsonRecord(res, {
+                    type: 'node',
+                    data: mapGraphNodeRow(table, row, includeContent),
+                }, signal);
+            });
+        }
+        catch (err) {
+            if (!isIgnorableGraphQueryError(err)) {
+                throw err;
+            }
+        }
+    }
+    await streamQuery(GRAPH_RELATIONSHIP_QUERY, async (row) => {
+        await writeNdjsonRecord(res, {
+            type: 'relationship',
+            data: mapGraphRelationshipRow(row),
+        }, signal);
+    });
+};
+/**
+ * Mount an SSE progress endpoint for a JobManager.
+ * Handles: initial state, terminal events, heartbeat, event IDs, client disconnect.
+ */
+const mountSSEProgress = (app, routePath, jm) => {
+    app.get(routePath, (req, res) => {
+        const job = jm.getJob(req.params.jobId);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        let eventId = 0;
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        // Send current state immediately
+        eventId++;
+        res.write(`id: ${eventId}\ndata: ${JSON.stringify(job.progress)}\n\n`);
+        // If already terminal, send event and close
+        if (job.status === 'complete' || job.status === 'failed') {
+            eventId++;
+            res.write(`id: ${eventId}\nevent: ${job.status}\ndata: ${JSON.stringify({
+                repoName: job.repoName,
+                error: job.error,
+            })}\n\n`);
+            res.end();
+            return;
+        }
+        // Heartbeat to detect zombie connections
+        const heartbeat = setInterval(() => {
+            try {
+                res.write(':heartbeat\n\n');
+            }
+            catch {
+                clearInterval(heartbeat);
+                unsubscribe();
+            }
+        }, 30_000);
+        // Subscribe to progress updates
+        const unsubscribe = jm.onProgress(job.id, (progress) => {
+            try {
+                eventId++;
+                if (progress.phase === 'complete' || progress.phase === 'failed') {
+                    const eventJob = jm.getJob(req.params.jobId);
+                    res.write(`id: ${eventId}\nevent: ${progress.phase}\ndata: ${JSON.stringify({
+                        repoName: eventJob?.repoName,
+                        error: eventJob?.error,
+                    })}\n\n`);
+                    clearInterval(heartbeat);
+                    res.end();
+                    unsubscribe();
+                }
+                else {
+                    res.write(`id: ${eventId}\ndata: ${JSON.stringify(progress)}\n\n`);
+                }
+            }
+            catch {
+                clearInterval(heartbeat);
+                unsubscribe();
+            }
+        });
+        req.on('close', () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+        });
+    });
+};
+const statusFromError = (err) => {
+    const msg = String(err?.message ?? '');
+    if (msg.includes('No indexed repositories') || msg.includes('not found'))
+        return 404;
+    if (msg.includes('Multiple repositories'))
+        return 400;
+    return 500;
+};
+const requestedRepo = (req) => {
+    const fromQuery = typeof req.query.repo === 'string' ? req.query.repo : undefined;
+    if (fromQuery)
+        return fromQuery;
+    if (req.body && typeof req.body === 'object' && typeof req.body.repo === 'string') {
+        return req.body.repo;
+    }
+    return undefined;
+};
+export const createServer = async (port, host = '127.0.0.1') => {
+    const app = express();
+    app.disable('x-powered-by');
+    // CORS: allow localhost, private/LAN networks, and the deployed site.
+    // Non-browser requests (curl, server-to-server) have no origin and are allowed.
+    // Disallowed origins get the response without Access-Control-Allow-Origin,
+    // so the browser blocks it. We pass `false` instead of throwing an Error to
+    // avoid crashing into Express's default error handler (which returned 500).
+    app.use(cors({
+        origin: (origin, callback) => {
+            callback(null, isAllowedOrigin(origin));
+        },
+    }));
+    app.use(express.json({ limit: '10mb' }));
+    // Support Chromium Private Network Access (required since Chrome 130+).
+    // Without this header, Chrome/Edge/Brave/Arc block public->loopback requests
+    // which breaks bridge mode entirely.
+    app.use((_req, res, next) => {
+        res.setHeader('Access-Control-Allow-Private-Network', 'true');
+        next();
+    });
+    // Handle PNA preflight: Chromium sends Access-Control-Request-Private-Network
+    // on OPTIONS requests and expects the allow header in the response.
+    // Note: the actual Allow-Private-Network header is already set by the global
+    // middleware above, so we just need to call next() here.
+    app.options('*', (_req, res, next) => {
+        next();
+    });
+    // Initialize MCP backend (multi-repo, shared across all MCP sessions)
+    const backend = new LocalBackend();
+    await backend.init();
+    const cleanupMcp = mountMCPEndpoints(app, backend);
+    const jobManager = new JobManager();
+    // Shared repo lock — prevents concurrent analyze + embed on the same repo path,
+    // which would corrupt LadybugDB (analyze calls closeLbug + initLbug while embed has queries in flight).
+    const activeRepoPaths = new Set();
+    const acquireRepoLock = (repoPath) => {
+        if (activeRepoPaths.has(repoPath)) {
+            return `Another job is already active for this repository`;
+        }
+        activeRepoPaths.add(repoPath);
+        return null;
+    };
+    const releaseRepoLock = (repoPath) => {
+        activeRepoPaths.delete(repoPath);
+    };
+    /**
+     * Maximum time the hold-queue will wait for an active analysis job to complete.
+     * Must stay in sync with the frontend's `fetchRepoInfo({ awaitAnalysis: true })` timeout.
+     */
+    const HOLD_QUEUE_TIMEOUT_SECS = 300; // 5 minutes
+    // Helper: resolve a repo by name from the global registry, or default to first.
+    // Pass `req` to enable early exit if the client disconnects during the hold-queue wait.
+    const resolveRepo = async (repoName, isRetry = false, req) => {
+        const repos = await listRegisteredRepos();
+        let found = null;
+        // Normalize: if a full path is passed, extract just the basename.
+        // e.g. "C:\Users\LENOVO\.codragraph\repos\todo.txt-cli" -> "todo.txt-cli"
+        const normalizedName = repoName ? path.basename(repoName) : undefined;
+        if (normalizedName) {
+            found =
+                repos.find((r) => r.name === normalizedName) ||
+                    repos.find((r) => r.name.toLowerCase() === normalizedName.toLowerCase()) ||
+                    null;
+        }
+        else if (repos.length > 0) {
+            found = repos[0]; // default to first repo
+        }
+        // If not yet in the registry, check whether a background job is actively cloning or
+        // analyzing this repo. Hold the connection open (up to 5 minutes) until it completes.
+        // We only wait for in-progress jobs ('queued'|'cloning'|'analyzing') — a 'complete' job
+        // whose repo is still missing means the registry sync failed; the fallback below handles it.
+        if (!found && normalizedName) {
+            const lower = normalizedName.toLowerCase();
+            // Track client disconnect to cancel the wait early
+            let clientGone = false;
+            req?.on('close', () => {
+                clientGone = true;
+            });
+            for (const job of jobManager.listJobs()) {
+                const isMatch = job.repoName?.toLowerCase() === lower ||
+                    (job.repoUrl && path.basename(job.repoUrl).replace('.git', '').toLowerCase() === lower) ||
+                    (job.repoPath && path.basename(job.repoPath).toLowerCase() === lower);
+                if (isMatch && ['queued', 'cloning', 'analyzing'].includes(job.status)) {
+                    if (process.env.DEBUG) {
+                        console.log(`[debug] resolveRepo waiting for active job ${job.id} (${normalizedName})...`);
+                    }
+                    for (let wait = 0; wait < HOLD_QUEUE_TIMEOUT_SECS; wait++) {
+                        if (clientGone)
+                            return null; // client disconnected — stop polling
+                        const currentJob = jobManager.getJob(job.id);
+                        if (!currentJob || currentJob.status === 'failed')
+                            break;
+                        if (currentJob.status === 'complete') {
+                            await backend.init();
+                            const freshRepos = await listRegisteredRepos();
+                            return freshRepos.find((r) => r.name === normalizedName) || null;
+                        }
+                        await new Promise((r) => setTimeout(r, 1000));
+                    }
+                    // Timed out — signal to the caller with a specific message
+                    return { __timedOut: true, repoName: normalizedName };
+                }
+            }
+        }
+        // Emergency fallback: re-sync the registry to handle Windows file-system race conditions
+        // (e.g. registry file not yet flushed after clone completes).
+        if (!found && normalizedName && !isRetry) {
+            if (process.env.DEBUG) {
+                console.log(`[debug] resolveRepo 404 for "${normalizedName}". Triggering deep init...`);
+            }
+            await backend.init();
+            return await resolveRepo(normalizedName, true, req);
+        }
+        return found;
+    };
+    // SSE heartbeat — clients connect to detect server liveness instantly.
+    // When the server shuts down, the TCP connection drops and the client's
+    // EventSource fires onerror immediately (no polling delay).
+    app.get('/api/heartbeat', (_req, res) => {
+        // Use res.set() instead of res.writeHead() to preserve CORS headers from middleware
+        res.set({
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        res.flushHeaders();
+        // Send initial ping so the client knows it connected
+        res.write(':ok\n\n');
+        // Keep-alive ping every 15s to prevent proxy/firewall timeout
+        const interval = setInterval(() => res.write(':ping\n\n'), 15_000);
+        _req.on('close', () => clearInterval(interval));
+    });
+    // Server info: version and launch context (npx / global / local dev)
+    app.get('/api/info', (_req, res) => {
+        const execPath = process.env.npm_execpath ?? '';
+        const argv0 = process.argv[1] ?? '';
+        let launchContext;
+        if (execPath.includes('npx') ||
+            argv0.includes('_npx') ||
+            process.env.npm_config_prefix?.includes('_npx')) {
+            launchContext = 'npx';
+        }
+        else if (argv0.includes('node_modules')) {
+            launchContext = 'local';
+        }
+        else {
+            launchContext = 'global';
+        }
+        res.json({ version: pkg.version, launchContext, nodeVersion: process.version });
+    });
+    // List all registered repos
+    app.get('/api/repos', async (_req, res) => {
+        try {
+            const repos = await listRegisteredRepos();
+            res.json(repos.map((r) => ({
+                name: r.name,
+                path: r.path,
+                indexedAt: r.indexedAt,
+                lastCommit: r.lastCommit,
+                stats: r.stats,
+            })));
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to list repos' });
+        }
+    });
+    // Get repo info
+    app.get('/api/repo', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req), false, req);
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found. Run: codragraph analyze' });
+                return;
+            }
+            // Timed out waiting for an active analysis job
+            if (entry.__timedOut) {
+                res.status(503).json({
+                    error: `Repository analysis for "${entry.repoName}" is taking longer than expected. Please try again in a moment.`,
+                });
+                return;
+            }
+            const meta = await loadMeta(entry.storagePath);
+            res.json({
+                name: entry.name,
+                repoPath: entry.path,
+                indexedAt: meta?.indexedAt ?? entry.indexedAt,
+                stats: meta?.stats ?? entry.stats ?? {},
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to get repo info' });
+        }
+    });
+    // Delete a repo — removes index, clone dir (if any), and unregisters it
+    app.delete('/api/repo', async (req, res) => {
+        try {
+            const repoName = requestedRepo(req);
+            if (!repoName) {
+                res.status(400).json({ error: 'Missing repo name' });
+                return;
+            }
+            const entry = await resolveRepo(repoName);
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            // Acquire repo lock — prevents deleting while analyze/embed is in flight
+            const lockKey = getStoragePath(entry.path);
+            const lockErr = acquireRepoLock(lockKey);
+            if (lockErr) {
+                res.status(409).json({ error: lockErr });
+                return;
+            }
+            try {
+                // Close any open LadybugDB handle before deleting files
+                try {
+                    await closeLbug();
+                }
+                catch { }
+                // 1. Delete the .codragraph index/storage directory
+                const storagePath = getStoragePath(entry.path);
+                await fs.rm(storagePath, { recursive: true, force: true }).catch(() => { });
+                // 2. Delete the cloned repo dir if it lives under ~/.codragraph/repos/
+                const cloneDir = getCloneDir(entry.name);
+                try {
+                    const stat = await fs.stat(cloneDir);
+                    if (stat.isDirectory()) {
+                        await fs.rm(cloneDir, { recursive: true, force: true });
+                    }
+                }
+                catch {
+                    /* clone dir may not exist (local repos) */
+                }
+                // 3. Unregister from the global registry
+                const { unregisterRepo } = await import('../storage/repo-manager.js');
+                await unregisterRepo(entry.path);
+                // 4. Reinitialize backend to reflect the removal
+                await backend.init().catch(() => { });
+                res.json({ deleted: entry.name });
+            }
+            finally {
+                releaseRepoLock(lockKey);
+            }
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to delete repo' });
+        }
+    });
+    // ─── Phase 4: versioned graph (graphstore) ─────────────────────────
+    //
+    // Each route resolves the repo, then delegates to the same handler
+    // module the MCP server uses (mcp/local/graphstore-handler.ts) so
+    // there is a single source of truth for serialization.
+    app.get('/api/graphstore/log', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const { handleGraphstoreLog } = await import('../mcp/local/graphstore-handler.js');
+            const limitParam = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined;
+            const result = await handleGraphstoreLog({
+                storagePath: entry.storagePath,
+                from: typeof req.query.from === 'string' ? req.query.from : undefined,
+                limit: Number.isFinite(limitParam) ? limitParam : undefined,
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'graphstore log failed' });
+        }
+    });
+    app.get('/api/graphstore/branches', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const { handleGraphstoreBranches } = await import('../mcp/local/graphstore-handler.js');
+            const result = await handleGraphstoreBranches({ storagePath: entry.storagePath });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'graphstore branches failed' });
+        }
+    });
+    app.get('/api/graphstore/diff', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const from = typeof req.query.from === 'string' ? req.query.from : '';
+            const to = typeof req.query.to === 'string' ? req.query.to : '';
+            if (!from || !to) {
+                res
+                    .status(400)
+                    .json({ error: 'graphstore diff requires both `from` and `to` query params' });
+                return;
+            }
+            const { handleGraphstoreDiff } = await import('../mcp/local/graphstore-handler.js');
+            const result = await handleGraphstoreDiff({ storagePath: entry.storagePath, from, to });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'graphstore diff failed' });
+        }
+    });
+    // Higher-fidelity diff: classifies modifications + surfaces added /
+    // removed exported APIs and Processes. The dashboard's "what broke
+    // / what fixed" panel renders this.
+    app.get('/api/graphstore/semantic-diff', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const from = typeof req.query.from === 'string' ? req.query.from : '';
+            const to = typeof req.query.to === 'string' ? req.query.to : '';
+            if (!from || !to) {
+                res.status(400).json({
+                    error: 'graphstore semantic-diff requires both `from` and `to` query params',
+                });
+                return;
+            }
+            const { handleGraphstoreSemanticDiff } = await import('../mcp/local/graphstore-handler.js');
+            const result = await handleGraphstoreSemanticDiff({
+                storagePath: entry.storagePath,
+                from,
+                to,
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'graphstore semantic-diff failed' });
+        }
+    });
+    // ─── Phase 4 × Phase 3 moat: harness recipes ───────────────────────
+    //
+    // Lazy-imports the handler from codragraph-harness so the package
+    // stays optional at runtime — same pattern as harness_run /
+    // harness_swarm_run in local-backend.ts.
+    const importRecipeHandler = async (handlerName) => {
+        const moduleId = '@codragraph/harness/mcp/handler';
+        try {
+            const mod = (await import(/* @vite-ignore */ moduleId));
+            const fn = mod[handlerName];
+            if (typeof fn !== 'function') {
+                throw new Error(`codragraph-harness does not export ${handlerName}`);
+            }
+            return fn;
+        }
+        catch (err) {
+            throw new Error(`recipes endpoint requires codragraph-harness to be installed: ${err?.message ?? String(err)}`);
+        }
+    };
+    app.get('/api/recipes', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const limitParam = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined;
+            const handler = await importRecipeHandler('handleHarnessRecipesList');
+            const result = await handler({
+                recipe_store: path.join(entry.storagePath, 'recipes'),
+                task_family: typeof req.query.task_family === 'string' ? req.query.task_family : undefined,
+                snapshot_id: typeof req.query.snapshot_id === 'string' ? req.query.snapshot_id : undefined,
+                limit: Number.isFinite(limitParam) ? limitParam : undefined,
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'recipes list failed' });
+        }
+    });
+    app.get('/api/recipes/lookup', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const taskFamily = typeof req.query.task_family === 'string' ? req.query.task_family : '';
+            const snapshotId = typeof req.query.snapshot_id === 'string' ? req.query.snapshot_id : '';
+            if (!taskFamily || !snapshotId) {
+                res.status(400).json({
+                    error: 'recipes lookup requires `task_family` and `snapshot_id` query params',
+                });
+                return;
+            }
+            const handler = await importRecipeHandler('handleHarnessRecipesLookup');
+            const result = await handler({
+                recipe_store: path.join(entry.storagePath, 'recipes'),
+                task_family: taskFamily,
+                snapshot_id: snapshotId,
+                limit: typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined,
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'recipes lookup failed' });
+        }
+    });
+    // Read one recipe's full content (harness body, scores, provenance)
+    // by id. Powers the dashboard's recipe-detail drawer. Reads the file
+    // directly from the FsRecipeStore layout under
+    // `<storagePath>/recipes/by-id/<sanitized-id>.json` rather than going
+    // through the MCP handler — the listing endpoint already covers
+    // search and we want this route to be cheap and focused.
+    app.get('/api/recipes/by-id/:id', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const safeId = req.params.id.replace(/[^A-Za-z0-9._-]/g, '_');
+            const recipePath = path.join(entry.storagePath, 'recipes', 'by-id', `${safeId}.json`);
+            try {
+                const raw = await fs.readFile(recipePath, 'utf-8');
+                res.type('application/json').send(raw);
+            }
+            catch (err) {
+                if (err?.code === 'ENOENT') {
+                    res.status(404).json({ error: `recipe ${req.params.id} not found` });
+                    return;
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'recipe by-id failed' });
+        }
+    });
+    // ─── Cross-repo groups (multi-repo + monorepo bridges) ─────────────
+    //
+    // Groups bundle multiple registered repos under a single name and
+    // declare contract links between them (HTTP/gRPC/topic/lib). The
+    // dashboard's Projects tab consumes these to render: which repos a
+    // user's project is part of, what contracts cross between them, and
+    // which sibling clones are stale.
+    //
+    // Each route delegates to the same group service the MCP layer uses
+    // (LocalBackend.getGroupService) so there is one source of truth.
+    const getGroupSvc = () => backend.getGroupService();
+    app.get('/api/groups', async (_req, res) => {
+        try {
+            const result = (await getGroupSvc().groupList({}));
+            res.json({ groups: result.groups ?? [] });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'group list failed' });
+        }
+    });
+    // Reverse lookup: MUST be registered BEFORE `/api/groups/:name` so
+    // Express matches the literal `for-repo` segment first instead of
+    // treating it as a group name parameter.
+    app.get('/api/groups/for-repo', async (req, res) => {
+        try {
+            const repoName = typeof req.query.repo === 'string' ? req.query.repo : '';
+            if (!repoName) {
+                res.status(400).json({ error: 'repo query param is required' });
+                return;
+            }
+            const svc = getGroupSvc();
+            const list = (await svc.groupList({}));
+            const matches = [];
+            for (const groupName of list.groups ?? []) {
+                const details = (await svc.groupList({ name: groupName }));
+                if (!details.repos)
+                    continue;
+                for (const [groupPath, registryName] of Object.entries(details.repos)) {
+                    if (registryName === repoName) {
+                        matches.push({ group: groupName, groupPath });
+                    }
+                }
+            }
+            res.json({ repo: repoName, groups: matches });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'groups-for-repo failed' });
+        }
+    });
+    app.get('/api/groups/:name', async (req, res) => {
+        try {
+            const result = await getGroupSvc().groupList({ name: req.params.name });
+            if (result.error) {
+                res.status(404).json(result);
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'group details failed' });
+        }
+    });
+    app.get('/api/groups/:name/contracts', async (req, res) => {
+        try {
+            const params = { name: req.params.name };
+            if (typeof req.query.type === 'string')
+                params.type = req.query.type;
+            if (typeof req.query.repo === 'string')
+                params.repo = req.query.repo;
+            if (req.query.unmatchedOnly === 'true')
+                params.unmatchedOnly = true;
+            const result = await getGroupSvc().groupContracts(params);
+            const e = result.error;
+            if (e) {
+                res.status(e.toLowerCase().includes('not found') ? 404 : 400).json(result);
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'group contracts failed' });
+        }
+    });
+    app.get('/api/groups/:name/status', async (req, res) => {
+        try {
+            const yaml = await backend.readGroupStatusResource(req.params.name);
+            res.type('text/yaml').send(yaml);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'group status failed' });
+        }
+    });
+    // Get full graph
+    app.get('/api/graph', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const includeContent = req.query.includeContent === 'true';
+            const stream = req.query.stream === 'true';
+            // Guard: when a repo has no materialized lbug schema (fixture-
+            // seeded CAS-only repos), or the lbug WAL is corrupt/stale from
+            // a prior failed analyze, LadybugDB native will abort with
+            // UNREACHABLE_CODE or an ANY-vector exception. Detect both
+            // shapes — missing file (cheap fs.access) AND empty/4096-byte
+            // schema-only file (fs.stat) — and return an empty graph so
+            // the dashboard doesn't blow up. The Graph tab keeps working
+            // for repos that actually have a real lbug.
+            const isLbugMaterialized = await (async () => {
+                try {
+                    const stat = await fs.stat(lbugPath);
+                    // Schema-only lbug is exactly 4096 bytes (one page, no real
+                    // data). Real graphs are larger.
+                    return stat.isFile() && stat.size > 4096;
+                }
+                catch {
+                    return false;
+                }
+            })();
+            if (!isLbugMaterialized) {
+                if (stream) {
+                    res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
+                    res.flushHeaders();
+                    res.write(JSON.stringify({
+                        type: 'meta',
+                        repoName: entry.name,
+                        note: 'no lbug file — graph not yet materialized',
+                        nodeCount: 0,
+                        relationshipCount: 0,
+                    }) + '\n');
+                    res.end();
+                    return;
+                }
+                res.json({
+                    repoName: entry.name,
+                    repoPath: entry.path,
+                    nodes: [],
+                    relationships: [],
+                    stats: { nodes: 0, edges: 0 },
+                    note: 'no lbug file — graph not yet materialized',
+                });
+                return;
+            }
+            if (stream) {
+                const abortController = new AbortController();
+                let responseFinished = false;
+                const markFinished = () => {
+                    responseFinished = true;
+                };
+                const abortStreaming = () => {
+                    if (!responseFinished) {
+                        abortController.abort();
+                    }
+                };
+                res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.flushHeaders();
+                req.once('aborted', abortStreaming);
+                res.once('finish', markFinished);
+                res.once('close', abortStreaming);
+                try {
+                    await withLbugDb(lbugPath, async () => streamGraphNdjson(res, includeContent, abortController.signal));
+                    if (!abortController.signal.aborted && !res.writableEnded) {
+                        res.end();
+                    }
+                }
+                finally {
+                    req.off('aborted', abortStreaming);
+                    res.off('finish', markFinished);
+                    res.off('close', abortStreaming);
+                }
+                return;
+            }
+            const graph = await withLbugDb(lbugPath, async () => buildGraph(includeContent));
+            res.json(graph);
+        }
+        catch (err) {
+            if (err instanceof ClientDisconnectedError) {
+                return;
+            }
+            const message = err.message || 'Failed to build graph';
+            if (res.headersSent) {
+                try {
+                    res.write(JSON.stringify({ type: 'error', error: message }) + '\n');
+                }
+                catch {
+                    // Best-effort only after streaming has started.
+                }
+                res.end();
+                return;
+            }
+            res.status(500).json({ error: message });
+        }
+    });
+    // Execute Cypher query
+    app.post('/api/query', async (req, res) => {
+        try {
+            const cypher = req.body.cypher;
+            if (!cypher) {
+                res.status(400).json({ error: 'Missing "cypher" in request body' });
+                return;
+            }
+            if (isWriteQuery(cypher)) {
+                res.status(403).json({ error: 'Write queries are not allowed via the HTTP API' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const result = await withLbugDb(lbugPath, () => executeQuery(cypher));
+            res.json({ result });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Query failed' });
+        }
+    });
+    // Search (supports mode: 'hybrid' | 'semantic' | 'bm25', and optional enrichment)
+    app.post('/api/search', async (req, res) => {
+        try {
+            const query = (req.body.query ?? '').trim();
+            if (!query) {
+                res.status(400).json({ error: 'Missing "query" in request body' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const parsedLimit = Number(req.body.limit ?? 10);
+            const limit = Number.isFinite(parsedLimit)
+                ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
+                : 10;
+            const mode = req.body.mode ?? 'hybrid';
+            const enrich = req.body.enrich !== false; // default true
+            const results = await withLbugDb(lbugPath, async () => {
+                let searchResults;
+                if (mode === 'semantic') {
+                    const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
+                    if (!isEmbedderReady()) {
+                        return [];
+                    }
+                    const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
+                    searchResults = await semSearch(executeQuery, query, limit);
+                    // Normalize semantic results to HybridSearchResult shape
+                    searchResults = searchResults.map((r, i) => ({
+                        ...r,
+                        score: r.score ?? 1 - (r.distance ?? 0),
+                        rank: i + 1,
+                        sources: ['semantic'],
+                    }));
+                }
+                else if (mode === 'bm25') {
+                    searchResults = await searchFTSFromLbug(query, limit);
+                    searchResults = searchResults.map((r, i) => ({
+                        ...r,
+                        rank: i + 1,
+                        sources: ['bm25'],
+                    }));
+                }
+                else {
+                    // hybrid (default)
+                    const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
+                    if (isEmbedderReady()) {
+                        const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
+                        searchResults = await hybridSearch(query, limit, executeQuery, semSearch);
+                    }
+                    else {
+                        searchResults = await searchFTSFromLbug(query, limit);
+                    }
+                }
+                if (!enrich)
+                    return searchResults;
+                // Server-side enrichment: add connections, cluster, processes per result
+                // Uses parameterized queries to prevent Cypher injection via nodeId
+                const validLabel = (label) => NODE_TABLES.includes(label);
+                const enriched = await Promise.all(searchResults.slice(0, limit).map(async (r) => {
+                    const nodeId = r.nodeId || r.id || '';
+                    const nodeLabel = nodeId.split(':')[0];
+                    const enrichment = {};
+                    if (!nodeId || !validLabel(nodeLabel))
+                        return { ...r, ...enrichment };
+                    // Run connections, cluster, and process queries in parallel
+                    // Label is validated against NODE_TABLES (compile-time safe identifiers);
+                    // nodeId uses $nid parameter binding to prevent injection
+                    const [connRes, clusterRes, procRes] = await Promise.all([
+                        executePrepared(`
+              MATCH (n:${nodeLabel} {id: $nid})
+              OPTIONAL MATCH (n)-[r1:CodeRelation]->(dst)
+              OPTIONAL MATCH (src)-[r2:CodeRelation]->(n)
+              RETURN
+                collect(DISTINCT {name: dst.name, type: r1.type, confidence: r1.confidence}) AS outgoing,
+                collect(DISTINCT {name: src.name, type: r2.type, confidence: r2.confidence}) AS incoming
+              LIMIT 1
+            `, { nid: nodeId }).catch(() => []),
+                        executePrepared(`
+              MATCH (n:${nodeLabel} {id: $nid})
+              MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+              RETURN c.label AS label, c.description AS description
+              LIMIT 1
+            `, { nid: nodeId }).catch(() => []),
+                        executePrepared(`
+              MATCH (n:${nodeLabel} {id: $nid})
+              MATCH (n)-[rel:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+              RETURN p.id AS id, p.label AS label, rel.step AS step, p.stepCount AS stepCount
+              ORDER BY rel.step
+            `, { nid: nodeId }).catch(() => []),
+                    ]);
+                    if (connRes.length > 0) {
+                        const row = connRes[0];
+                        const outgoing = (Array.isArray(row) ? row[0] : row.outgoing || [])
+                            .filter((c) => c?.name)
+                            .slice(0, 5);
+                        const incoming = (Array.isArray(row) ? row[1] : row.incoming || [])
+                            .filter((c) => c?.name)
+                            .slice(0, 5);
+                        enrichment.connections = { outgoing, incoming };
+                    }
+                    if (clusterRes.length > 0) {
+                        const row = clusterRes[0];
+                        enrichment.cluster = Array.isArray(row) ? row[0] : row.label;
+                    }
+                    if (procRes.length > 0) {
+                        enrichment.processes = procRes
+                            .map((row) => ({
+                            id: Array.isArray(row) ? row[0] : row.id,
+                            label: Array.isArray(row) ? row[1] : row.label,
+                            step: Array.isArray(row) ? row[2] : row.step,
+                            stepCount: Array.isArray(row) ? row[3] : row.stepCount,
+                        }))
+                            .filter((p) => p.id && p.label);
+                    }
+                    return { ...r, ...enrichment };
+                }));
+                return enriched;
+            });
+            res.json({ results });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Search failed' });
+        }
+    });
+    // Read file — with path traversal guard
+    app.get('/api/file', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const filePath = req.query.path;
+            if (!filePath) {
+                res.status(400).json({ error: 'Missing path' });
+                return;
+            }
+            // Prevent path traversal — resolve and verify the path stays within the repo root
+            const repoRoot = path.resolve(entry.path);
+            const fullPath = path.resolve(repoRoot, filePath);
+            if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot) {
+                res.status(403).json({ error: 'Path traversal denied' });
+                return;
+            }
+            const raw = await fs.readFile(fullPath, 'utf-8');
+            // Optional line-range support: ?startLine=10&endLine=50
+            // Returns only the requested slice (0-indexed), plus metadata.
+            const startLine = req.query.startLine !== undefined ? Number(req.query.startLine) : undefined;
+            const endLine = req.query.endLine !== undefined ? Number(req.query.endLine) : undefined;
+            if (startLine !== undefined && Number.isFinite(startLine)) {
+                const lines = raw.split('\n');
+                const start = Math.max(0, startLine);
+                const end = endLine !== undefined && Number.isFinite(endLine)
+                    ? Math.min(lines.length, endLine + 1)
+                    : lines.length;
+                res.json({
+                    content: lines.slice(start, end).join('\n'),
+                    startLine: start,
+                    endLine: end - 1,
+                    totalLines: lines.length,
+                });
+            }
+            else {
+                res.json({ content: raw, totalLines: raw.split('\n').length });
+            }
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                res.status(404).json({ error: 'File not found' });
+            }
+            else {
+                res.status(500).json({ error: err.message || 'Failed to read file' });
+            }
+        }
+    });
+    // Grep — regex search across file contents in the indexed repo
+    // Uses filesystem-based search for memory efficiency (never loads all files into memory)
+    app.get('/api/grep', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const pattern = req.query.pattern;
+            if (!pattern) {
+                res.status(400).json({ error: 'Missing "pattern" query parameter' });
+                return;
+            }
+            // ReDoS protection: reject overly long or dangerous patterns
+            if (pattern.length > 200) {
+                res.status(400).json({ error: 'Pattern too long (max 200 characters)' });
+                return;
+            }
+            // Validate regex syntax
+            let regex;
+            try {
+                regex = new RegExp(pattern, 'gim');
+            }
+            catch {
+                res.status(400).json({ error: 'Invalid regex pattern' });
+                return;
+            }
+            const parsedLimit = Number(req.query.limit ?? 50);
+            const limit = Number.isFinite(parsedLimit)
+                ? Math.max(1, Math.min(200, Math.trunc(parsedLimit)))
+                : 50;
+            const results = [];
+            const repoRoot = path.resolve(entry.path);
+            // Get file paths from the graph (lightweight — no content loaded)
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const fileRows = await withLbugDb(lbugPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`));
+            // Search files on disk one at a time (constant memory)
+            for (const row of fileRows) {
+                if (results.length >= limit)
+                    break;
+                const filePath = row.filePath || '';
+                const fullPath = path.resolve(repoRoot, filePath);
+                // Path traversal guard
+                if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot)
+                    continue;
+                let content;
+                try {
+                    content = await fs.readFile(fullPath, 'utf-8');
+                }
+                catch {
+                    continue; // File may have been deleted since indexing
+                }
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    if (results.length >= limit)
+                        break;
+                    if (regex.test(lines[i])) {
+                        results.push({ filePath, line: i + 1, text: lines[i].trim().slice(0, 200) });
+                    }
+                    regex.lastIndex = 0;
+                }
+            }
+            res.json({ results });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Grep failed' });
+        }
+    });
+    // List all processes
+    app.get('/api/processes', async (req, res) => {
+        try {
+            const result = await backend.queryProcesses(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query processes' });
+        }
+    });
+    // Process detail
+    app.get('/api/process', async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryProcessDetail(name, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res
+                .status(statusFromError(err))
+                .json({ error: err.message || 'Failed to query process detail' });
+        }
+    });
+    // List all clusters
+    app.get('/api/clusters', async (req, res) => {
+        try {
+            const result = await backend.queryClusters(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query clusters' });
+        }
+    });
+    // Cluster detail
+    app.get('/api/cluster', async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryClusterDetail(name, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res
+                .status(statusFromError(err))
+                .json({ error: err.message || 'Failed to query cluster detail' });
+        }
+    });
+    // ── Analyze API ──────────────────────────────────────────────────────
+    // POST /api/analyze — start a new analysis job
+    app.post('/api/analyze', async (req, res) => {
+        try {
+            const { url: repoUrl, path: repoLocalPath, force, embeddings } = req.body;
+            // Input type validation
+            if (repoUrl !== undefined && typeof repoUrl !== 'string') {
+                res.status(400).json({ error: '"url" must be a string' });
+                return;
+            }
+            if (repoLocalPath !== undefined && typeof repoLocalPath !== 'string') {
+                res.status(400).json({ error: '"path" must be a string' });
+                return;
+            }
+            if (!repoUrl && !repoLocalPath) {
+                res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
+                return;
+            }
+            // Path validation: require absolute path, reject traversal (e.g. /tmp/../etc/passwd)
+            if (repoLocalPath) {
+                if (!path.isAbsolute(repoLocalPath)) {
+                    res.status(400).json({ error: '"path" must be an absolute path' });
+                    return;
+                }
+                if (path.normalize(repoLocalPath) !== path.resolve(repoLocalPath)) {
+                    res.status(400).json({ error: '"path" must not contain traversal sequences' });
+                    return;
+                }
+            }
+            const job = jobManager.createJob({ repoUrl, repoPath: repoLocalPath });
+            // If job was already running (dedup), just return its id
+            if (job.status !== 'queued') {
+                res.status(202).json({ jobId: job.id, status: job.status });
+                return;
+            }
+            // Mark as active synchronously to prevent race with concurrent requests
+            jobManager.updateJob(job.id, { status: 'cloning' });
+            // Start async work — don't await
+            (async () => {
+                let targetPath = repoLocalPath;
+                try {
+                    // Clone if URL provided
+                    if (repoUrl && !repoLocalPath) {
+                        const repoName = extractRepoName(repoUrl);
+                        targetPath = getCloneDir(repoName);
+                        jobManager.updateJob(job.id, {
+                            status: 'cloning',
+                            repoName,
+                            progress: { phase: 'cloning', percent: 0, message: `Cloning ${repoUrl}...` },
+                        });
+                        await cloneOrPull(repoUrl, targetPath, (progress) => {
+                            jobManager.updateJob(job.id, {
+                                progress: { phase: progress.phase, percent: 5, message: progress.message },
+                            });
+                        });
+                    }
+                    if (!targetPath) {
+                        throw new Error('No target path resolved');
+                    }
+                    // Acquire shared repo lock (keyed on storagePath to match embed handler)
+                    const analyzeLockKey = getStoragePath(targetPath);
+                    const lockErr = acquireRepoLock(analyzeLockKey);
+                    if (lockErr) {
+                        jobManager.updateJob(job.id, { status: 'failed', error: lockErr });
+                        return;
+                    }
+                    jobManager.updateJob(job.id, { repoPath: targetPath, status: 'analyzing' });
+                    // ── Worker fork with auto-retry ──────────────────────────────
+                    //
+                    // Forks a child process with 8GB heap. If the worker crashes
+                    // (OOM, native addon segfault, etc.), it retries up to
+                    // MAX_WORKER_RETRIES times with exponential backoff before
+                    // marking the job as permanently failed.
+                    //
+                    // In dev mode (tsx), registers the tsx ESM hook via a file://
+                    // URL so the child can compile TypeScript on-the-fly.
+                    const MAX_WORKER_RETRIES = 2;
+                    const callerPath = fileURLToPath(import.meta.url);
+                    const isDev = callerPath.endsWith('.ts');
+                    const workerFile = isDev ? 'analyze-worker.ts' : 'analyze-worker.js';
+                    const workerPath = path.join(path.dirname(callerPath), workerFile);
+                    const tsxHookArgs = isDev
+                        ? ['--import', pathToFileURL(_require.resolve('tsx/esm')).href]
+                        : [];
+                    const forkWorker = () => {
+                        const currentJob = jobManager.getJob(job.id);
+                        if (!currentJob || currentJob.status === 'complete' || currentJob.status === 'failed')
+                            return;
+                        const child = fork(workerPath, [], {
+                            execArgv: [...tsxHookArgs, '--max-old-space-size=8192'],
+                            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                        });
+                        // Capture stderr for crash diagnostics
+                        let stderrChunks = '';
+                        child.stderr?.on('data', (chunk) => {
+                            stderrChunks += chunk.toString();
+                            if (stderrChunks.length > 4096)
+                                stderrChunks = stderrChunks.slice(-4096);
+                        });
+                        child.on('message', (msg) => {
+                            if (msg.type === 'progress') {
+                                jobManager.updateJob(job.id, {
+                                    status: 'analyzing',
+                                    progress: { phase: msg.phase, percent: msg.percent, message: msg.message },
+                                });
+                            }
+                            else if (msg.type === 'complete') {
+                                releaseRepoLock(analyzeLockKey);
+                                // Reinitialize backend BEFORE marking complete — ensures the new
+                                // repo is queryable when the client receives the SSE complete event.
+                                backend
+                                    .init()
+                                    .then(() => {
+                                    jobManager.updateJob(job.id, {
+                                        status: 'complete',
+                                        repoName: msg.result.repoName,
+                                    });
+                                })
+                                    .catch((err) => {
+                                    console.error('backend.init() failed after analyze:', err);
+                                    jobManager.updateJob(job.id, {
+                                        status: 'failed',
+                                        error: 'Server failed to reload after analysis. Try again.',
+                                    });
+                                });
+                            }
+                            else if (msg.type === 'error') {
+                                releaseRepoLock(analyzeLockKey);
+                                jobManager.updateJob(job.id, {
+                                    status: 'failed',
+                                    error: msg.message,
+                                });
+                            }
+                        });
+                        child.on('error', (err) => {
+                            releaseRepoLock(analyzeLockKey);
+                            jobManager.updateJob(job.id, {
+                                status: 'failed',
+                                error: `Worker process error: ${err.message}`,
+                            });
+                        });
+                        child.on('exit', (code) => {
+                            const j = jobManager.getJob(job.id);
+                            if (!j || j.status === 'complete' || j.status === 'failed')
+                                return;
+                            // Worker crashed — attempt retry if under the limit
+                            if (j.retryCount < MAX_WORKER_RETRIES) {
+                                j.retryCount++;
+                                const delay = 1000 * Math.pow(2, j.retryCount - 1); // 1s, 2s
+                                const lastErr = stderrChunks.trim().split('\n').pop() || '';
+                                console.warn(`Analyze worker crashed (code ${code}), retry ${j.retryCount}/${MAX_WORKER_RETRIES} in ${delay}ms` +
+                                    (lastErr ? `: ${lastErr}` : ''));
+                                jobManager.updateJob(job.id, {
+                                    status: 'analyzing',
+                                    progress: {
+                                        phase: 'retrying',
+                                        percent: j.progress.percent,
+                                        message: `Worker crashed, retrying (${j.retryCount}/${MAX_WORKER_RETRIES})...`,
+                                    },
+                                });
+                                stderrChunks = '';
+                                setTimeout(forkWorker, delay);
+                            }
+                            else {
+                                // Exhausted retries — permanent failure
+                                releaseRepoLock(analyzeLockKey);
+                                jobManager.updateJob(job.id, {
+                                    status: 'failed',
+                                    error: `Worker crashed ${MAX_WORKER_RETRIES + 1} times (code ${code})${stderrChunks ? ': ' + stderrChunks.trim().split('\n').pop() : ''}`,
+                                });
+                            }
+                        });
+                        // Register child for cancellation + timeout tracking
+                        jobManager.registerChild(job.id, child);
+                        // Send start command to child
+                        child.send({
+                            type: 'start',
+                            repoPath: targetPath,
+                            options: { force: !!force, embeddings: !!embeddings },
+                        });
+                    };
+                    forkWorker();
+                }
+                catch (err) {
+                    if (targetPath)
+                        releaseRepoLock(getStoragePath(targetPath));
+                    jobManager.updateJob(job.id, {
+                        status: 'failed',
+                        error: err.message || 'Analysis failed',
+                    });
+                }
+            })();
+            res.status(202).json({ jobId: job.id, status: job.status });
+        }
+        catch (err) {
+            if (err.message?.includes('already in progress')) {
+                res.status(409).json({ error: err.message });
+            }
+            else {
+                res.status(500).json({ error: err.message || 'Failed to start analysis' });
+            }
+        }
+    });
+    // GET /api/analyze/:jobId — poll job status
+    app.get('/api/analyze/:jobId', (req, res) => {
+        const job = jobManager.getJob(req.params.jobId);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        res.json({
+            id: job.id,
+            status: job.status,
+            repoUrl: job.repoUrl,
+            repoPath: job.repoPath,
+            repoName: job.repoName,
+            progress: job.progress,
+            error: job.error,
+            startedAt: job.startedAt,
+            completedAt: job.completedAt,
+        });
+    });
+    // GET /api/analyze/:jobId/progress — SSE stream (shared helper)
+    mountSSEProgress(app, '/api/analyze/:jobId/progress', jobManager);
+    // DELETE /api/analyze/:jobId — cancel a running analysis job
+    app.delete('/api/analyze/:jobId', (req, res) => {
+        const job = jobManager.getJob(req.params.jobId);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        if (job.status === 'complete' || job.status === 'failed') {
+            res.status(400).json({ error: `Job already ${job.status}` });
+            return;
+        }
+        jobManager.cancelJob(req.params.jobId, 'Cancelled by user');
+        res.json({ id: job.id, status: 'failed', error: 'Cancelled by user' });
+    });
+    // ── Embedding endpoints ────────────────────────────────────────────
+    const embedJobManager = new JobManager();
+    // POST /api/embed — trigger server-side embedding generation
+    app.post('/api/embed', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            // Check shared repo lock — prevent concurrent analyze + embed on same repo
+            const repoLockPath = entry.storagePath;
+            const lockErr = acquireRepoLock(repoLockPath);
+            if (lockErr) {
+                res.status(409).json({ error: lockErr });
+                return;
+            }
+            const job = embedJobManager.createJob({ repoPath: entry.storagePath });
+            embedJobManager.updateJob(job.id, {
+                repoName: entry.name,
+                status: 'analyzing',
+                progress: { phase: 'analyzing', percent: 0, message: 'Starting embedding generation...' },
+            });
+            // 30-minute timeout for embedding jobs (same as analyze jobs)
+            const EMBED_TIMEOUT_MS = 30 * 60 * 1000;
+            const embedTimeout = setTimeout(() => {
+                const current = embedJobManager.getJob(job.id);
+                if (current && current.status !== 'complete' && current.status !== 'failed') {
+                    releaseRepoLock(repoLockPath);
+                    embedJobManager.updateJob(job.id, {
+                        status: 'failed',
+                        error: 'Embedding timed out (30 minute limit)',
+                    });
+                }
+            }, EMBED_TIMEOUT_MS);
+            // Run embedding pipeline asynchronously
+            (async () => {
+                try {
+                    const lbugPath = path.join(entry.storagePath, 'lbug');
+                    await withLbugDb(lbugPath, async () => {
+                        const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
+                        // Fetch existing content hashes for incremental embedding.
+                        // Delegated to lbug-adapter which owns the DB query logic and legacy-fallback handling.
+                        const { fetchExistingEmbeddingHashes } = await import('../core/lbug/lbug-adapter.js');
+                        const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
+                        if (existingEmbeddings && existingEmbeddings.size > 0) {
+                            console.log(`[embed] ${existingEmbeddings.size} nodes already embedded — incremental run with content-hash comparison`);
+                        }
+                        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
+                            embedJobManager.updateJob(job.id, {
+                                progress: {
+                                    phase: p.phase === 'ready' ? 'complete' : p.phase === 'error' ? 'failed' : p.phase,
+                                    percent: p.percent,
+                                    message: p.phase === 'loading-model'
+                                        ? 'Loading embedding model...'
+                                        : p.phase === 'embedding'
+                                            ? `Embedding nodes (${p.percent}%)...`
+                                            : p.phase === 'indexing'
+                                                ? 'Creating vector index...'
+                                                : p.phase === 'ready'
+                                                    ? 'Embeddings complete'
+                                                    : `${p.phase} (${p.percent}%)`,
+                                },
+                            });
+                        }, {}, // config: use defaults
+                        undefined, // skipNodeIds
+                        undefined, // context
+                        existingEmbeddings);
+                    });
+                    clearTimeout(embedTimeout);
+                    releaseRepoLock(repoLockPath);
+                    // Don't overwrite 'failed' if the job was cancelled while the pipeline was running
+                    const current = embedJobManager.getJob(job.id);
+                    if (!current || current.status !== 'failed') {
+                        embedJobManager.updateJob(job.id, { status: 'complete' });
+                    }
+                }
+                catch (err) {
+                    clearTimeout(embedTimeout);
+                    releaseRepoLock(repoLockPath);
+                    const current = embedJobManager.getJob(job.id);
+                    if (!current || current.status !== 'failed') {
+                        embedJobManager.updateJob(job.id, {
+                            status: 'failed',
+                            error: err.message || 'Embedding generation failed',
+                        });
+                    }
+                }
+            })();
+            res.status(202).json({ jobId: job.id, status: 'analyzing' });
+        }
+        catch (err) {
+            if (err.message?.includes('already in progress')) {
+                res.status(409).json({ error: err.message });
+            }
+            else {
+                res.status(500).json({ error: err.message || 'Failed to start embedding generation' });
+            }
+        }
+    });
+    // GET /api/embed/:jobId — poll embedding job status
+    app.get('/api/embed/:jobId', (req, res) => {
+        const job = embedJobManager.getJob(req.params.jobId);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        res.json({
+            id: job.id,
+            status: job.status,
+            repoName: job.repoName,
+            progress: job.progress,
+            error: job.error,
+            startedAt: job.startedAt,
+            completedAt: job.completedAt,
+        });
+    });
+    // GET /api/embed/:jobId/progress — SSE stream (shared helper)
+    mountSSEProgress(app, '/api/embed/:jobId/progress', embedJobManager);
+    // DELETE /api/embed/:jobId — cancel embedding job
+    app.delete('/api/embed/:jobId', (req, res) => {
+        const job = embedJobManager.getJob(req.params.jobId);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        if (job.status === 'complete' || job.status === 'failed') {
+            res.status(400).json({ error: `Job already ${job.status}` });
+            return;
+        }
+        embedJobManager.cancelJob(req.params.jobId, 'Cancelled by user');
+        res.json({ id: job.id, status: 'failed', error: 'Cancelled by user' });
+    });
+    // Global error handler — catch anything the route handlers miss
+    app.use((err, _req, res, _next) => {
+        console.error('Unhandled error:', err);
+        res.status(500).json({ error: 'Internal server error' });
+    });
+    // Wrap listen in a promise so errors (EADDRINUSE, EACCES, etc.) propagate
+    // to the caller instead of crashing with an unhandled 'error' event.
+    await new Promise((resolve, reject) => {
+        const server = app.listen(port, host, () => {
+            const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
+            console.log(`CodraGraph server running on http://${displayHost}:${port}`);
+            resolve();
+        });
+        server.on('error', (err) => reject(err));
+        // Graceful shutdown — close Express + LadybugDB cleanly
+        const shutdown = async () => {
+            console.log('\nShutting down...');
+            server.close();
+            jobManager.dispose();
+            embedJobManager.dispose();
+            await cleanupMcp();
+            await closeLbug();
+            await backend.disconnect();
+            process.exit(0);
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+};