gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/mcp/resources.js

@@ -270,6 +270,7 @@ async function getContextResource(backend, repoName) {
     lines.push('  - query: Process-grouped code intelligence (execution flows related to a concept)');
     lines.push('  - context: 360-degree symbol view (categorized refs, process participation)');
     lines.push('  - impact: Blast radius analysis (what breaks if you change a symbol)');
+    lines.push('  - explain: Persisted taint findings — source→sink data flows with per-hop variables (requires analyze --pdg)');
     lines.push('  - detect_changes: Git-diff impact analysis (what do your changes affect)');
     lines.push('  - rename: Multi-file coordinated rename with confidence tags');
     lines.push('  - cypher: Raw graph queries');

package/dist/mcp/tools.d.ts

@@ -36,4 +36,13 @@ export interface ToolDefinition {
  */
 export declare const LIST_REPOS_DEFAULT_LIMIT = 50;
 export declare const LIST_REPOS_MAX_LIMIT = 200;
+/**
+ * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
+ * and capped per function at analyze time, but a large repo can still
+ * accumulate enough TAINTED rows to blow MCP/LLM token limits — the response
+ * is page-bounded like `list_repos`. Exported so the backend clamp
+ * (`local-backend.ts`) and the schema stay a single source of truth.
+ */
+export declare const EXPLAIN_DEFAULT_LIMIT = 50;
+export declare const EXPLAIN_MAX_LIMIT = 200;
 export declare const GITNEXUS_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -32,6 +32,15 @@ const DESTRUCTIVE_TOOL_ANNOTATIONS = {
  */
 export const LIST_REPOS_DEFAULT_LIMIT = 50;
 export const LIST_REPOS_MAX_LIMIT = 200;
+/**
+ * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
+ * and capped per function at analyze time, but a large repo can still
+ * accumulate enough TAINTED rows to blow MCP/LLM token limits — the response
+ * is page-bounded like `list_repos`. Exported so the backend clamp
+ * (`local-backend.ts`) and the schema stay a single source of truth.
+ */
+export const EXPLAIN_DEFAULT_LIMIT = 50;
+export const EXPLAIN_MAX_LIMIT = 200;
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
@@ -277,6 +286,29 @@ Returns: changed symbols, affected processes, and a risk summary.`,
             required: [],
         },
     },
+    {
+        name: 'check',
+        description: `Run read-only structural checks against the indexed graph.
+
+Currently detects directed cycles between File nodes connected by IMPORTS edges.
+Returns deterministic cycle paths and a cycle count suitable for CI automation.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cycles: {
+                    type: 'boolean',
+                    description: 'Detect circular file imports (default: true).',
+                    default: true,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'rename',
         description: `Multi-file coordinated rename using the knowledge graph + text search.
@@ -439,6 +471,49 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
             required: ['target', 'direction'],
         },
     },
+    {
+        name: 'explain',
+        description: `Explain persisted taint findings: intra-procedural source→sink data flows (TAINTED edges) recorded by \`gitnexus analyze --pdg\`.
+
+Each finding carries the sink category (command-injection, code-injection, path-traversal, sql-injection, xss), the source/sink lines, and the ordered hop path with the variable carried on each hop (decoded from the persisted path encoding).
+
+WHEN TO USE: Security review — "what taint findings exist in this repo / file / function?". Requires the repo to be indexed with \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no taint layer" note, not an error.
+
+ANCHORLESS (no "target"): enumerates all persisted findings for the repo — bounded ("limit", deterministic order), with "totalFindings" and a "truncated" flag.
+ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates, unknown names return not-found. Symbol anchoring is line-range granular (findings whose source block starts inside the symbol's span).
+
+CONTRACT CAVEATS (intra-procedural M3 scope — absent flows are NOT proof of safety):
+- Cross-function flows are not modeled (a flow through a helper function is invisible).
+- Closure/callback flows are invisible in both directions (e.g. arr.forEach(() => sink(y))).
+- Property/field flows are not tracked (obj.x = taint; sink(obj.y) has no chain).
+- Guard-style sanitizers (if (isValid(x))) and implicit/control-dependence flows are not modeled.
+- CommonJS aliasing is partially modeled (require('<literal>') joins resolve; dynamic requires do not).
+- Exception-path over-approximation can produce false-positive noise.
+
+Findings are deliberately NOT part of impact()'s traversal or the web schema — explain is the dedicated taint consumer. SANITIZES (kill) edges are queryable via cypher.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: {
+                    type: 'string',
+                    description: 'Optional anchor: a file path (e.g. "src/handlers/run.ts" — suffix match accepted) or a symbol/function name (resolved like context()). Omit to enumerate all findings for the repo.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: `Max findings returned (default: ${EXPLAIN_DEFAULT_LIMIT}, max: ${EXPLAIN_MAX_LIMIT}). "totalFindings" reports the full matched count; "truncated" is set when the page is smaller.`,
+                    default: EXPLAIN_DEFAULT_LIMIT,
+                    minimum: 1,
+                    maximum: EXPLAIN_MAX_LIMIT,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'route_map',
         description: `Show API route mappings: which components/hooks fetch which API endpoints, and which handler files serve them.
@@ -560,3 +635,37 @@ WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
         },
     },
 ];
+/**
+ * Per-repo tools that accept an optional `branch` scope (#2106). Single source
+ * of truth: the schema property is injected here so it cannot drift from the
+ * server-side default in `local-backend.ts` (`resolveRepo(repo, branch)`).
+ * `list_repos` and the `group_*` tools are intentionally excluded — they are
+ * not single-repo, single-branch operations.
+ */
+const BRANCH_SCOPED_TOOLS = new Set([
+    'query',
+    'cypher',
+    'context',
+    'detect_changes',
+    'explain',
+    'check',
+    'impact',
+    'rename',
+    'route_map',
+    'tool_map',
+    'shape_check',
+    'api_impact',
+]);
+for (const tool of GITNEXUS_TOOLS) {
+    if (!BRANCH_SCOPED_TOOLS.has(tool.name))
+        continue;
+    if (tool.inputSchema.properties.branch)
+        continue;
+    // Optional — `required` is left unchanged so omitting `branch` keeps today's
+    // default/primary-branch behavior. Ignored in group mode (repo starts "@").
+    tool.inputSchema.properties.branch = {
+        type: 'string',
+        description: 'Optional: scope to a specific branch index (multi-branch repos, #2106). ' +
+            'Omit for the default/primary branch. Ignored in group mode.',
+    };
+}

package/dist/server/analyze-launch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared analyze-worker launcher.
+ *
+ * Forks the analyze worker for an already-resolved repo directory and owns the
+ * lock + auto-retry + IPC machinery. Used by both the JSON `/api/analyze` route
+ * and the multipart `/api/analyze/upload` route. Dependency-injected (like
+ * createAnalyzeUploadHandler) so the seam is testable and api.ts stays smaller.
+ *
+ * NOTE: this module must live alongside analyze-worker.{ts,js} — the worker
+ * path is resolved relative to `import.meta.url`.
+ */
+import type { JobManager } from './analyze-job.js';
+export interface LaunchDeps {
+    jobManager: JobManager;
+    backend: {
+        init: () => Promise<unknown>;
+    };
+    acquireRepoLock: (key: string) => string | null;
+    releaseRepoLock: (key: string) => void;
+}
+export interface LaunchOptions {
+    force?: boolean;
+    embeddings?: boolean;
+    dropEmbeddings?: boolean;
+    registryName?: string;
+}
+export declare function createLaunchAnalysisWorker(deps: LaunchDeps): (job: {
+    id: string;
+}, targetPath: string, opts: LaunchOptions) => void;

package/dist/server/analyze-launch.js

@@ -0,0 +1,137 @@
+/**
+ * Shared analyze-worker launcher.
+ *
+ * Forks the analyze worker for an already-resolved repo directory and owns the
+ * lock + auto-retry + IPC machinery. Used by both the JSON `/api/analyze` route
+ * and the multipart `/api/analyze/upload` route. Dependency-injected (like
+ * createAnalyzeUploadHandler) so the seam is testable and api.ts stays smaller.
+ *
+ * NOTE: this module must live alongside analyze-worker.{ts,js} — the worker
+ * path is resolved relative to `import.meta.url`.
+ */
+import path from 'path';
+import { fork } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { createRequire } from 'node:module';
+import { getStoragePath } from '../storage/repo-manager.js';
+import { logger } from '../core/logger.js';
+const _require = createRequire(import.meta.url);
+const MAX_WORKER_RETRIES = 2;
+export function createLaunchAnalysisWorker(deps) {
+    const { jobManager, backend, acquireRepoLock, releaseRepoLock } = deps;
+    return function launchAnalysisWorker(job, targetPath, opts) {
+        // 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 ──────────────────────────────
+        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) => {
+                        logger.error({ err }, 'backend.init() failed after analyze:');
+                        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() || '';
+                    logger.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: !!opts.force,
+                    embeddings: !!opts.embeddings,
+                    dropEmbeddings: !!opts.dropEmbeddings,
+                    ...(opts.registryName ? { registryName: opts.registryName } : {}),
+                },
+            });
+        };
+        forkWorker();
+    };
+}

package/dist/server/analyze-upload.d.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/analyze/upload — analyze a browser folder upload.
+ *
+ * Securely ingests the multipart upload into a sandbox (upload-ingest.ts),
+ * promotes it to a persistent app-controlled directory, and analyzes it via
+ * the same job/worker machinery as a git clone — never returning a server
+ * path to the client. Factored as a dependency-injected handler so the job
+ * machinery (createJob + the worker launcher) can be mocked in unit tests.
+ */
+import type { Request, Response } from 'express';
+import { ingestUpload } from './upload-ingest.js';
+import type { AnalyzeJob } from './analyze-job.js';
+/** Minimal job shape the handler needs (a subset of the real AnalyzeJob). */
+export type UploadJobRef = Pick<AnalyzeJob, 'id' | 'status'>;
+export interface AnalyzeUploadDeps {
+    /** Create (or throw on busy) an analysis job for the given upload dir. */
+    createJob: (params: {
+        repoPath: string;
+    }) => UploadJobRef;
+    /** Launch the analyze worker against an already-resolved repo directory. */
+    launch: (job: UploadJobRef, targetPath: string, opts: {
+        registryName: string;
+    }) => void;
+    /**
+     * Mark a created job failed. The job occupies the single analysis slot from
+     * createJob onward, so ANY error before launch must release it — otherwise a
+     * leaked non-terminal job wedges all future analyses until restart.
+     */
+    failJob: (jobId: string, error: string) => void;
+    /** Injectable for tests (defaults to the real ingestUpload). */
+    ingest?: typeof ingestUpload;
+}
+export declare function createAnalyzeUploadHandler(deps: AnalyzeUploadDeps): (req: Request, res: Response) => Promise<void>;

package/dist/server/analyze-upload.js

@@ -0,0 +1,123 @@
+/**
+ * POST /api/analyze/upload — analyze a browser folder upload.
+ *
+ * Securely ingests the multipart upload into a sandbox (upload-ingest.ts),
+ * promotes it to a persistent app-controlled directory, and analyzes it via
+ * the same job/worker machinery as a git clone — never returning a server
+ * path to the client. Factored as a dependency-injected handler so the job
+ * machinery (createJob + the worker launcher) can be mocked in unit tests.
+ */
+import path from 'path';
+import fsp from 'fs/promises';
+import { ingestUpload } from './upload-ingest.js';
+import { UPLOAD_ROOT, getUploadDir, deriveUploadName } from './upload-paths.js';
+import { BadRequestError } from './validation.js';
+/** Cap on collision-suffix attempts when allocating an upload dir name. */
+const MAX_NAME_COLLISION_TRIES = 100;
+/**
+ * Find an available upload directory name, appending `-2`, `-3`, … on
+ * collision with an existing upload. Bounded to avoid an unbounded scan.
+ */
+async function pickAvailableName(base) {
+    for (let i = 0; i < MAX_NAME_COLLISION_TRIES; i++) {
+        const name = i === 0 ? base : `${base}-${i + 1}`;
+        let dir;
+        try {
+            dir = getUploadDir(name);
+        }
+        catch {
+            continue;
+        }
+        try {
+            await fsp.access(dir);
+            // exists → try the next suffix
+        }
+        catch {
+            return name; // ENOENT → available
+        }
+    }
+    throw new BadRequestError(`Could not allocate an upload directory after ${MAX_NAME_COLLISION_TRIES} attempts`, 409);
+}
+export function createAnalyzeUploadHandler(deps) {
+    const ingest = deps.ingest ?? ingestUpload;
+    return async function handleAnalyzeUploadRequest(req, res) {
+        let stageRoot;
+        let promotedDir;
+        let createdJobId;
+        let launched = false;
+        try {
+            const result = await ingest(req);
+            stageRoot = result.stageRoot;
+            const baseName = deriveUploadName(result.topLevelName);
+            if (!baseName) {
+                throw new BadRequestError('Uploaded folder has no usable name');
+            }
+            // webkitRelativePath prefixes every entry with the picked folder, so the
+            // real repo root is stageRoot/<topLevelName>. Validate it is a directory
+            // BEFORE taking the single analysis slot — a malformed (non-folder)
+            // upload must not be able to occupy the slot.
+            const innerRoot = path.join(result.stageRoot, result.topLevelName);
+            let innerIsDir = false;
+            try {
+                innerIsDir = (await fsp.stat(innerRoot)).isDirectory();
+            }
+            catch {
+                innerIsDir = false;
+            }
+            if (!innerIsDir) {
+                throw new BadRequestError('Upload must be a folder');
+            }
+            const finalName = await pickAvailableName(baseName);
+            const finalDir = getUploadDir(finalName);
+            // createJob occupies the single analysis slot (throws 'already in
+            // progress' → 409). From here on, ANY error before launch MUST release
+            // the slot via failJob in the catch, or the server wedges all analyses.
+            let job;
+            try {
+                job = deps.createJob({ repoPath: finalDir });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : '';
+                if (msg.includes('already in progress')) {
+                    throw new BadRequestError(msg, 409);
+                }
+                throw err;
+            }
+            createdJobId = job.id;
+            // Promote staging → persistent upload dir. Both live under UPLOAD_ROOT's
+            // filesystem, so this rename stays atomic (no EXDEV).
+            await fsp.mkdir(UPLOAD_ROOT, { recursive: true });
+            await fsp.rename(innerRoot, finalDir);
+            promotedDir = finalDir;
+            const oldStage = stageRoot;
+            stageRoot = undefined;
+            await fsp.rm(oldStage, { recursive: true, force: true }).catch(() => { });
+            // Drop any crafted index the upload may have carried (a `.gitnexus`
+            // segment passes containment); the worker will build a fresh one.
+            await fsp
+                .rm(path.join(finalDir, '.gitnexus'), { recursive: true, force: true })
+                .catch(() => { });
+            deps.launch(job, finalDir, { registryName: finalName });
+            launched = true;
+            res.status(202).json({ jobId: job.id, status: job.status });
+        }
+        catch (err) {
+            // Release the single analysis slot if a job was created but never
+            // launched — otherwise the leaked queued job blocks all future analyses.
+            if (createdJobId && !launched) {
+                deps.failJob(createdJobId, err instanceof Error ? err.message : 'Upload failed');
+            }
+            if (stageRoot) {
+                await fsp.rm(stageRoot, { recursive: true, force: true }).catch(() => { });
+            }
+            if (promotedDir && !launched) {
+                await fsp.rm(promotedDir, { recursive: true, force: true }).catch(() => { });
+            }
+            if (err instanceof BadRequestError) {
+                res.status(err.status).json({ error: err.message });
+                return;
+            }
+            res.status(500).json({ error: 'Upload failed' });
+        }
+    };
+}

package/dist/server/analyze-worker-ipc.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON-safe projection of `AnalyzeResult` for the analyze-worker → parent IPC
+ * boundary (#2112 boundary audit; #2135).
+ *
+ * The forked analyze worker (`analyze-worker.ts`) reports completion to the
+ * parent over `child_process` IPC, which uses Node's DEFAULT `'json'`
+ * serialization — `api.ts` forks the worker with no `serialization:` option, so
+ * the channel runs `JSON.stringify`/`JSON.parse`, NOT V8 structured clone.
+ *
+ * `AnalyzeResult.pipelineResult` is populated on every successful analysis
+ * (`run-analyze.ts`) and carries `pipelineResult.graph` — the live
+ * `KnowledgeGraph` closure object. Sending the raw result across this channel is
+ * wrong three ways:
+ *   1. Waste — the graph's `nodes`/`relationships` getters force-materialize the
+ *      ENTIRE graph into two arrays, then JSON-stringify them, on every analyze.
+ *      On a large repo (the #2112 scenario) that is a multi-hundred-MB
+ *      stringify+parse whose result is immediately discarded.
+ *   2. Silent corruption — the graph's methods are own function properties;
+ *      `JSON.stringify` drops them with no error, so a `pipelineResult.graph`
+ *      that survived the wire is a data-only husk whose `forEachNode(...)` throws
+ *      "is not a function" far from the cause.
+ *   3. Conditional crash — a BigInt or circular reference anywhere in the
+ *      payload makes `process.send` throw `TypeError` synchronously; the throw is
+ *      caught in the worker and re-sent as `{type:'error'}`, turning a
+ *      SUCCESSFUL analysis (DB already written) into a reported FAILURE. This is
+ *      the #2112 failure family on the server path, and — unlike the parse-worker
+ *      result boundary — it has no clone-safety net.
+ *
+ * The parent (`api.ts`) reads only `result.repoName`; `pipelineResult`'s real
+ * consumers (CLI skill generation) call `runFullAnalysis` in-process and never
+ * cross this fork. So the worker sends an explicit allowlist of the scalar
+ * fields, JSON-safe by construction.
+ */
+import type { AnalyzeResult } from '../core/run-analyze.js';
+/**
+ * The JSON-safe subset of `AnalyzeResult` that crosses the analyze-worker IPC
+ * boundary. A `Pick` allowlist — NOT `Omit<…, 'pipelineResult'>`. With `Pick`
+ * the allowlist IS the type, so the projection is exhaustive by construction:
+ * `projectAnalyzeResultForIpc`'s return literal must name exactly these keys
+ * (omitting one is a compile error), and a new field added to `AnalyzeResult`
+ * is simply absent from the wire until it is *deliberately* added here. `Omit`
+ * couldn't give that guarantee — it kept every other field, including OPTIONAL
+ * ones (e.g. `isPrimaryBranch?`), so an optional non-serializable field could be
+ * advertised by the type yet silently dropped by the runtime allowlist.
+ *
+ * `isPrimaryBranch` is intentionally excluded: the parent (`api.ts`) reads only
+ * `repoName`, and nothing consumes `isPrimaryBranch` across this fork (its CLI
+ * consumer calls `runFullAnalysis` in-process). Add a field here only when a
+ * server-side IPC consumer actually needs it — and only if it is JSON-safe.
+ */
+export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped'>;
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export declare function projectAnalyzeResultForIpc(result: AnalyzeResult): AnalyzeResultIpc;

package/dist/server/analyze-worker-ipc.js

@@ -0,0 +1,16 @@
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export function projectAnalyzeResultForIpc(result) {
+    return {
+        repoName: result.repoName,
+        repoPath: result.repoPath,
+        stats: result.stats,
+        alreadyUpToDate: result.alreadyUpToDate,
+        ftsRepairedOnly: result.ftsRepairedOnly,
+        ftsSkipped: result.ftsSkipped,
+    };
+}

package/dist/server/analyze-worker.d.ts

@@ -10,4 +10,20 @@
  *   Child -> Parent: { type: 'complete', result: AnalyzeResult }
  *   Child -> Parent: { type: 'error', message: string }
  */
-export {};
+import { type AnalyzeResultIpc } from './analyze-worker-ipc.js';
+export interface ProgressMessage {
+    type: 'progress';
+    phase: string;
+    percent: number;
+    message: string;
+}
+export interface CompleteMessage {
+    type: 'complete';
+    result: AnalyzeResultIpc;
+}
+export interface ErrorMessage {
+    type: 'error';
+    message: string;
+}
+/** Child → parent IPC messages. Shared with the parent-side launcher. */
+export type WorkerMessage = ProgressMessage | CompleteMessage | ErrorMessage;

package/dist/server/analyze-worker.js

@@ -11,6 +11,7 @@
  *   Child -> Parent: { type: 'error', message: string }
  */
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 function send(msg) {
     process.send?.(msg);
@@ -48,7 +49,12 @@ process.on('message', async (msg) => {
                 send({ type: 'progress', phase: 'log', percent: -1, message });
             },
         });
-        send({ type: 'complete', result });
+        // Send a JSON-safe projection, NOT the raw result: the IPC channel is
+        // default-JSON serialization and `result.pipelineResult` carries the live
+        // KnowledgeGraph (wasteful to materialize, silently corrupted by JSON, and
+        // a BigInt/circular value would throw and mis-report this success as a
+        // failure). See analyze-worker-ipc.ts.
+        send({ type: 'complete', result: projectAnalyzeResultForIpc(result) });
     }
     catch (err) {
         send({ type: 'error', message: err?.message || 'Analysis failed' });