gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/mcp/resources.js

@@ -234,7 +234,7 @@ async function getReposResource(backend) {
     if (repos.length > 1) {
         lines.push('');
         lines.push('# Multiple repos indexed. Use repo parameter in tool calls:');
-        lines.push(`# query({query: "auth", repo: "${repos[0].name}"})`);
+        lines.push(`# query({search_query: "auth", repo: "${repos[0].name}"})`);
     }
     return lines.join('\n');
 }
@@ -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');
@@ -386,6 +387,12 @@ relationships:
   - MEMBER_OF: Symbol belongs to community
   - STEP_IN_PROCESS: Symbol is step N in process
 
+pdg_layers: "Recorded ONLY when indexed with 'gitnexus analyze --pdg'. Intra-procedural, basic-block granular; both endpoints are BasicBlock nodes. Prefer the pdg_query tool over raw Cypher."
+  - BasicBlock: "Basic-block node. Columns: id, filePath, startLine, endLine, text. id = 'BasicBlock:<filePath>:<fnStartLine>:<fnStartCol>:<blockIndex>'."
+  - CFG: "Control-flow edge BasicBlock->BasicBlock. Edge kind (seq/cond-true/cond-false/loop-back/...) is in reason."
+  - CDG: "Control-DEPENDENCE edge BasicBlock->BasicBlock — the source predicate gates the target's execution. Branch sense 'T'|'F' in reason. Query via pdg_query mode:'controls'."
+  - REACHING_DEF: "Data-dependence (def->use) edge BasicBlock->BasicBlock. Source-level variable name is in reason. Query via pdg_query mode:'flows'."
+
 relationship_table: "All relationships use a single CodeRelation table with a 'type' property. Properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)"
 
 example_queries:
@@ -403,6 +410,11 @@ example_queries:
     WHERE p.heuristicLabel = "LoginFlow"
     RETURN s.name, r.step
     ORDER BY r.step
+
+  guard_clauses (--pdg only; prefer pdg_query mode:'controls'): |
+    MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
+    WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
+    RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text
 `;
 }
 /**

package/dist/mcp/tools.d.ts

@@ -36,4 +36,16 @@ 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 PDG_QUERY_DEFAULT_LIMIT = 50;
+export declare const PDG_QUERY_MAX_LIMIT = 200;
+export declare const IMPACT_MAX_DEPTH = 32;
 export declare const GITNEXUS_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -32,6 +32,22 @@ 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;
+// pdg_query result-page bounds (#2086 M6). Mirror the EXPLAIN_* limits — the
+// no-rel-index path means every page must be anchored + LIMIT-bounded.
+export const PDG_QUERY_DEFAULT_LIMIT = 50;
+export const PDG_QUERY_MAX_LIMIT = 200;
+// Shared impact traversal depth cap. The MCP schema advertises this bound;
+// PDG direct backend callers also enforce it before running traversal.
+export const IMPACT_MAX_DEPTH = 32;
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
@@ -89,7 +105,14 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Natural language or keyword search query' },
+                // #2175: the legacy `query` key is still accepted by the handler
+                // (resolveAliasString in local-backend.ts), but is deliberately NOT named in the
+                // advertised property or its description — surfacing "query" in the schema an LLM
+                // reads would nudge it to send `query`, the exact argument Claude Code drops.
+                search_query: {
+                    type: 'string',
+                    description: 'Natural language or keyword search query.',
+                },
                 task_context: {
                     type: 'string',
                     description: 'What you are working on (e.g., "adding OAuth support"). Helps ranking.',
@@ -127,7 +150,7 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
                     description: 'Optional monorepo service root (relative path, "/" separators). In group mode (@repo), prefix-matches symbol file paths; ignored for a normal repo name. Empty string is rejected server-side.',
                 },
             },
-            required: ['query'],
+            required: ['search_query'],
         },
     },
     {
@@ -175,12 +198,20 @@ TIPS:
 - All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
 - Community = auto-detected functional area (Leiden algorithm). Properties: heuristicLabel, cohesion, symbolCount, keywords, description, enrichedBy
 - Process = execution flow trace from entry point to terminal. Properties: heuristicLabel, processType, stepCount, communities, entryPointId, terminalId
-- Use heuristicLabel (not label) for human-readable community/process names`,
+- Use heuristicLabel (not label) for human-readable community/process names
+- PDG layers (only when indexed with \`--pdg\`): BasicBlock nodes + CFG / CDG (control dependence, branch sense 'T'|'F' in reason) / REACHING_DEF (def→use, variable in reason) edges, all BasicBlock→BasicBlock. Prefer the \`pdg_query\` tool — it anchors + bounds these for you (raw \`[:CDG*]\`/\`[:REACHING_DEF*]\` path scans are unindexed and unbounded).`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Cypher query to execute' },
+                // #2175: the legacy `query` key is still accepted by the handler
+                // (resolveAliasString in local-backend.ts), but is deliberately NOT named in the
+                // advertised property or its description — surfacing "query" in the schema an LLM
+                // reads would nudge it to send `query`, the exact argument Claude Code drops.
+                statement: {
+                    type: 'string',
+                    description: 'Cypher statement to execute.',
+                },
                 params: {
                     type: 'object',
                     description: 'Optional query parameters for placeholders (e.g. $name) to execute via prepared statement binding.',
@@ -190,7 +221,7 @@ TIPS:
                     description: 'Repository name or path. Omit if only one repo is indexed.',
                 },
             },
-            required: ['query'],
+            required: ['statement'],
         },
     },
     {
@@ -277,6 +308,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.
@@ -317,11 +371,17 @@ Each edit is tagged with confidence:
         description: `Analyze the blast radius of changing a code symbol.
 Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
 
+MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/EXTENDS/IMPLEMENTS) — inter-procedural, the established comparator/default behavior. "pdg" requires an index built with \`gitnexus analyze --pdg\` and returns one unified PDG-facing result: statement-level control/data dependence from the persisted PDG plus inter-procedural symbol reach. The explicit interprocedural surface is interproceduralByDepth/pdgInterprocedural; byDepth remains the compatibility symbol bucket. pdg remains incompatible with crossDepth and @group targets; relationTypes/minConfidence filter the inter-symbol reach.
+
+STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
+
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:1 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:1, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar.
+
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
 
 Output includes:
-- risk: LOW / MEDIUM / HIGH / CRITICAL
+- risk: LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN
 - summary: direct callers, processes affected, modules affected
 - affected_processes: which execution flows break and at which step
 - affected_modules: which functional areas are hit (direct vs indirect)
@@ -357,6 +417,17 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     type: 'string',
                     description: 'upstream (what depends on this) or downstream (what this depends on)',
                 },
+                mode: {
+                    type: 'string',
+                    enum: ['callgraph', 'pdg'],
+                    default: 'callgraph',
+                    description: "Blast-radius engine. 'callgraph' (default) = inter-procedural symbol→symbol traversal (established comparator). 'pdg' = unified PDG-facing impact: intra-procedural statement-level affectedStatements from the persisted control/data dependence layer plus inter-procedural symbols in interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket; requires `gitnexus analyze --pdg`. PDG symbol reach is labeled as a PDG evidence bridge, not pure statement-level dependence, and successful PDG results are UNKNOWN-risk. PDG is incompatible with crossDepth and @group targets; relationTypes/minConfidence filter the inter-symbol reach.",
+                },
+                line: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: "1-based source line — PDG statement anchor (mode:'pdg'). Seeds affectedStatements on the statement at this line; inter-procedural symbols are still returned in interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket.",
+                },
                 file_path: {
                     type: 'string',
                     description: 'File path hint to disambiguate common names',
@@ -370,7 +441,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'Max relationship depth (default: 3, server clamps to 1–32)',
                     default: 3,
                     minimum: 1,
-                    maximum: 32,
+                    maximum: IMPACT_MAX_DEPTH,
                 },
                 crossDepth: {
                     type: 'number',
@@ -439,6 +510,99 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
             required: ['target', 'direction'],
         },
     },
+    {
+        name: 'explain',
+        description: `Explain persisted taint findings recorded by \`gitnexus analyze --pdg\`: intra-procedural source→sink data flows (TAINTED edges, statement-level hops) AND cross-function flows (TAINT_PATH edges, function-level hops, marked \`interprocedural: true\`).
+
+Each finding carries the sink category (command-injection, code-injection, path-traversal, sql-injection, xss) and the ordered hop path. Intra-procedural findings carry source/sink lines and the variable on each hop; interprocedural findings carry the source and sink FUNCTION names and the chain of functions the taint crossed (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 for intra-procedural findings; cross-function findings match when the symbol is the source OR sink function.
+
+CONTRACT CAVEATS (absent flows are NOT proof of safety):
+- Cross-function flows ARE modeled (#2084 M4): a source flowing through helper functions into a sink is found, via summary composition over the call graph (context-insensitive — return/call-site merging is accepted).
+- Cross-function matching is by callee NAME (context-insensitive): when one caller invokes two distinct same-named callees, a flow into one over-attributes to both — a cross-function finding does not prove the taint reached every same-named function (sound over-report, never a missed flow).
+- Closure/callback flows are invisible in both directions (e.g. arr.forEach(() => sink(y))) — the largest false-negative class.
+- 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: 'pdg_query',
+        description: `Query the persisted Program Dependence Graph recorded by \`gitnexus analyze --pdg\` — control dependence (CDG) and data dependence (REACHING_DEF) at basic-block granularity. The control/data analog of \`explain\` (which is the taint consumer).
+
+MODES:
+- \`controls\` — "under what condition does X run?". Returns, for the anchored function, each control-dependence edge: the controlling predicate block, the dependent block, and the branch sense ('T' = the predicate's true/taken arm, 'F' = its false/fall-through arm). An edge into an early return/throw block is flagged \`guard: true\` (subsumes the #559 guard heuristic); the branch sense of a guard depends on its predicate — \`if (!ok) return;\` rides the 'T' arm — so don't filter guards by a fixed label.
+- \`flows\` — "where does variable Y flow?". Returns REACHING_DEF def→use edges for the anchored function; pass \`variable\` to filter to one binding.
+
+WHEN TO USE: comprehension ("what guards this statement?"), data-flow tracing within a function, guard-clause discovery. Requires \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no PDG layer" note, not an error.
+
+ANCHORING (required): \`target\` is a file path or a symbol/function name (resolved like context()). PDG queries are ALWAYS anchored — there is no whole-repo enumeration (an unanchored basic-block path scan is unbounded; LadybugDB has no rel-property index). A symbol target is line-range granular; an ambiguous name returns ranked candidates, unknown returns not-found.
+
+CONTRACT CAVEATS:
+- CDG labels are binary 'T'/'F' in M5/M6; per-case \`switch\` arm conditions are not yet distinguished (every case dispatch is 'T').
+- Granularity is basic-block, reconstructed to the function via the BasicBlock id + line span (no Function→BasicBlock edge); deeply same-line-packed functions may anchor coarsely.
+- Control/data dependence is intra-procedural (per function). Cross-function flow is taint's domain (\`explain\`).
+- These edges are deliberately NOT part of impact()'s traversal — \`pdg_query\` is the dedicated consumer; raw edges are also queryable via \`cypher\`.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['controls', 'flows'],
+                    description: "'controls' = control dependence (CDG: what condition gates X); 'flows' = data dependence (REACHING_DEF: where variable Y flows).",
+                },
+                target: {
+                    type: 'string',
+                    description: 'Required anchor: a file path (e.g. "src/handlers/run.ts" — suffix match accepted) or a symbol/function name (resolved like context()).',
+                },
+                variable: {
+                    type: 'string',
+                    description: 'Optional (flows mode only): restrict REACHING_DEF results to this source-level variable name.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: `Max edges returned (default: ${PDG_QUERY_DEFAULT_LIMIT}, max: ${PDG_QUERY_MAX_LIMIT}). "total" reports the full matched count; "truncated" is set when the page is smaller.`,
+                    default: PDG_QUERY_DEFAULT_LIMIT,
+                    minimum: 1,
+                    maximum: PDG_QUERY_MAX_LIMIT,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: ['mode', 'target'],
+        },
+    },
     {
         name: 'route_map',
         description: `Show API route mappings: which components/hooks fetch which API endpoints, and which handler files serve them.
@@ -559,6 +723,45 @@ WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
             required: ['name'],
         },
     },
+    {
+        name: 'trace',
+        description: `Find the shortest directed path between two symbols over call and class-member edges.
+
+WHEN TO USE: Debugging "how does A reach B?" — answers in one call what would take 3-8 manual context/impact hops. Shows the exact chain with file:line positions plus a per-hop edge type and confidence.
+
+Traverses CALLS edges plus HAS_METHOD (class → member) edges, so a trace can descend from a class into its methods. Each hop's edge type is reported in edges[], so call hops and containment hops remain distinguishable.
+
+Returns: ordered hops with file:line, and an aligned edges[] of edge type + confidence. When no path exists, reports the furthest reachable node so you know where the chain breaks (and truncated: true if a traversal cap was hit first).`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'string', description: 'Source symbol name' },
+                from_uid: { type: 'string', description: 'Source symbol UID (zero-ambiguity)' },
+                from_file: { type: 'string', description: 'Source file path hint for disambiguation' },
+                to: { type: 'string', description: 'Target symbol name' },
+                to_uid: { type: 'string', description: 'Target symbol UID (zero-ambiguity)' },
+                to_file: { type: 'string', description: 'Target file path hint for disambiguation' },
+                maxDepth: {
+                    type: 'number',
+                    description: 'Maximum path length in hops (default: 10)',
+                    default: 10,
+                    minimum: 1,
+                    maximum: 30,
+                },
+                includeTests: {
+                    type: 'boolean',
+                    description: 'Include test-file symbols in traversal (default: false)',
+                    default: false,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
 ];
 /**
  * Per-repo tools that accept an optional `branch` scope (#2106). Single source
@@ -572,12 +775,16 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'cypher',
     'context',
     'detect_changes',
+    'explain',
+    'pdg_query',
+    'check',
     'impact',
     'rename',
     'route_map',
     'tool_map',
     'shape_check',
     'api_impact',
+    'trace',
 ]);
 for (const tool of GITNEXUS_TOOLS) {
     if (!BRANCH_SCOPED_TOOLS.has(tool.name))

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>;