gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/mcp/server.d.ts

@@ -12,11 +12,14 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { LocalBackend } from './local/local-backend.js';
+import { McpRepositoryPolicy } from './repository-policy.js';
 /**
  * Create a configured MCP Server with all handlers registered.
  * Transport-agnostic — caller connects the desired transport.
  */
-export declare function createMCPServer(backend: LocalBackend): Server;
+export declare function createMCPServer(backend: LocalBackend, options?: {
+    repositoryPolicy?: McpRepositoryPolicy;
+}): Server;
 /** Conventional 128 + signal-number exit codes for graceful termination. */
 export declare const SHUTDOWN_EXIT_CODES: {
     readonly SIGINT: 130;
@@ -34,5 +37,5 @@ type SignalRegistrar = (event: 'SIGINT' | 'SIGTERM', listener: (...args: unknown
  * mapping can be unit-tested without touching the real process.
  */
 export declare function installSignalShutdown(shutdown: (exitCode?: number) => unknown, on?: SignalRegistrar): void;
-export declare function startMCPServer(backend: LocalBackend): Promise<void>;
+export declare function startMCPServer(backend: LocalBackend, repositoryPolicy?: McpRepositoryPolicy): Promise<void>;
 export {};

package/dist/mcp/server.js

@@ -17,6 +17,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 import { GITNEXUS_TOOLS } from './tools.js';
 import { installGlobalStdoutSentinel } from './stdio-context.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+import { assertMcpReadOnlyResource, assertMcpReadOnlyToolCall, filterMcpReadOnlyResourceContent, MCP_READ_ONLY_TOOLS, readOnlyResourceTemplateAllowed, resolveMcpReadOnlyMode, toolForReadOnlyMcp, } from './read-only-policy.js';
+import { createMcpRepositoryPolicy, McpRepositoryPolicy, mcpRepositoryPolicyConfigured, } from './repository-policy.js';
+import { applyMcpMaxTokens, resolveMcpMaxTokens, withoutMcpBudgetArg } from './output-budget.js';
 /**
  * Next-step hints appended to tool responses.
  *
@@ -60,7 +63,13 @@ function getNextStepHint(toolName, args) {
  * Create a configured MCP Server with all handlers registered.
  * Transport-agnostic — caller connects the desired transport.
  */
-export function createMCPServer(backend) {
+export function createMCPServer(backend, options = {}) {
+    const readOnly = resolveMcpReadOnlyMode();
+    if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
+        throw new Error('Configured MCP repository policy must be validated before server creation.');
+    }
+    const repositoryPolicy = options.repositoryPolicy ?? McpRepositoryPolicy.unrestricted();
+    const scopedBackend = repositoryPolicy.scopeBackend(backend);
     const require = createRequire(import.meta.url);
     const pkgVersion = require('../../package.json').version;
     const server = new Server({
@@ -87,7 +96,8 @@ export function createMCPServer(backend) {
     });
     // Handle list resource templates request (for dynamic resources)
     server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
-        const templates = getResourceTemplates();
+        const templates = getResourceTemplates().filter((template) => readOnlyResourceTemplateAllowed(template.uriTemplate, readOnly) &&
+            repositoryPolicy.resourceTemplateAllowed(template.uriTemplate));
         return {
             resourceTemplates: templates.map((t) => ({
                 uriTemplate: t.uriTemplate,
@@ -101,7 +111,9 @@ export function createMCPServer(backend) {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
         try {
-            const content = await readResource(uri, backend);
+            assertMcpReadOnlyResource(uri, readOnly);
+            repositoryPolicy.assertResourceUri(uri);
+            const content = filterMcpReadOnlyResourceContent(await readResource(uri, scopedBackend), readOnly);
             return {
                 contents: [
                     {
@@ -126,7 +138,10 @@ export function createMCPServer(backend) {
     });
     // Handle list tools request
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: GITNEXUS_TOOLS.map((tool) => ({
+        tools: GITNEXUS_TOOLS.filter((tool) => (!readOnly || MCP_READ_ONLY_TOOLS.has(tool.name)) &&
+            repositoryPolicy.toolAllowed(tool.name))
+            .map((tool) => toolForReadOnlyMcp(repositoryPolicy.toolForMcp(tool), readOnly))
+            .map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -136,15 +151,19 @@ export function createMCPServer(backend) {
     // Handle tool calls — append next-step hints to guide agent workflow
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        let maxTokens;
         try {
-            const result = await backend.callTool(name, args);
+            const typedArgs = args;
+            assertMcpReadOnlyToolCall(name, typedArgs, readOnly);
+            maxTokens = resolveMcpMaxTokens(name, typedArgs);
+            const result = await scopedBackend.callTool(name, withoutMcpBudgetArg(typedArgs));
             const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
             const hint = getNextStepHint(name, args);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: resultText + hint,
+                        text: applyMcpMaxTokens(resultText + hint, maxTokens),
                     },
                 ],
             };
@@ -155,7 +174,7 @@ export function createMCPServer(backend) {
                 content: [
                     {
                         type: 'text',
-                        text: `Error: ${message}`,
+                        text: applyMcpMaxTokens(`Error: ${message}`, maxTokens),
                     },
                 ],
                 isError: true,
@@ -265,8 +284,9 @@ export function installSignalShutdown(shutdown, on = (event, listener) => {
     on('SIGINT', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGINT));
     on('SIGTERM', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGTERM));
 }
-export async function startMCPServer(backend) {
-    const server = createMCPServer(backend);
+export async function startMCPServer(backend, repositoryPolicy) {
+    const validatedRepositoryPolicy = repositoryPolicy ?? (await createMcpRepositoryPolicy(backend));
+    const server = createMCPServer(backend, { repositoryPolicy: validatedRepositoryPolicy });
     // Idempotent global sentinel install. cli/mcp.ts calls this first thing
     // (before warnMissingOptionalGrammars / backend.init can emit to stdout);
     // calling again here is a safety net for direct callers of startMCPServer

package/dist/mcp/tools.d.ts

@@ -24,14 +24,6 @@ export interface ToolDefinition {
             minLength?: number;
         }>;
         required: string[];
-        /**
-         * JSON-Schema `anyOf` for cross-property constraints `required` cannot express
-         * — e.g. "at least one of route/file". Forwarded verbatim to clients by the
-         * server's ListTools handler, so MCP clients see the constraint.
-         */
-        anyOf?: Array<{
-            required: string[];
-        }>;
     };
 }
 /**

package/dist/mcp/tools.js

@@ -141,6 +141,11 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
                     description: 'Include full symbol source code (default: false)',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>" (member path keys from group.yaml). Omit when only one indexed repo exists.',
@@ -253,6 +258,10 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)',
                 },
                 file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                file: {
+                    type: 'string',
+                    description: 'Compatibility alias for file_path; values must agree when both are present',
+                },
                 kind: {
                     type: 'string',
                     description: "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
@@ -262,6 +271,11 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'Include full symbol source code (default: false)',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". Omit if only one repo is indexed.',
@@ -379,7 +393,7 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 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.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — 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:2, 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.
@@ -413,6 +427,14 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
             type: 'object',
             properties: {
                 target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+                name: {
+                    type: 'string',
+                    description: 'Compatibility alias for target; all supplied target aliases must agree',
+                },
+                symbol: {
+                    type: 'string',
+                    description: 'Compatibility alias for target; all supplied target aliases must agree',
+                },
                 target_uid: {
                     type: 'string',
                     description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup, skips target resolution)',
@@ -503,6 +525,11 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'When true, returns target, summary, risk, byDepthCounts, affected_processes, and affected_modules — omits byDepth. Single-repo only; ignored in group mode (@groupName). Use for hub symbols to get actionable signal without output explosion.',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 timeoutMs: {
                     type: 'number',
                     description: 'Wall-clock budget in milliseconds for the Phase-1 local impact leg (default 30000)',
@@ -516,7 +543,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     maximum: 3600000,
                 },
             },
-            required: ['target', 'direction'],
+            required: ['direction'],
         },
     },
     {
@@ -699,9 +726,6 @@ Response shape is keyed on how many routes match, not on the data: exactly one m
                 repo: { type: 'string', description: 'Repository name or path.' },
             },
             required: [],
-            // Exactly one lookup key is needed, but either works (route wins if both
-            // are passed) — so the structural constraint is "at least one of route/file".
-            anyOf: [{ required: ['route'] }, { required: ['file'] }],
         },
     },
     {
@@ -804,6 +828,76 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
             required: [],
         },
     },
+    {
+        name: 'move_entries',
+        description: `List Move/Aptos entry points (compiler-sourced).
+
+WHEN TO USE: To enumerate a Move package's external surface - \`entry\` functions (transaction entry points) and \`#[view]\` functions (read-only queries). Filter by module, kind, or attribute.
+
+Returns: { entries: [{ name, qualifiedName, filePath, isEntry, isView, visibility, acquires, attributes, returnType }], count }.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: {
+                    type: 'string',
+                    description: 'Filter to one module (qualified name, e.g. 0xa::coin).',
+                },
+                kind: {
+                    type: 'string',
+                    enum: ['entry', 'view', 'inline', 'native'],
+                    description: 'Restrict to a single entry kind. Omit for entry+view.',
+                },
+                attribute: {
+                    type: 'string',
+                    description: 'Only functions carrying this attribute (e.g. "view").',
+                },
+                repo: { type: 'string', description: 'Repository name or path.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'move_resources',
+        description: `List Move/Aptos resources (structs/enums with the \`key\` ability) and their accessors.
+
+WHEN TO USE: To audit on-chain storage — which resources exist and which functions read/write/acquire them (from READS_RESOURCE / WRITES_RESOURCE / ACQUIRES edges).
+
+Returns: { resources: [{ name, qualifiedName, filePath, abilities, fieldList, accessors: [{ caller, reason, isEntry, isView }] }], count }.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: { type: 'string', description: 'Filter to one module (qualified name).' },
+                repo: { type: 'string', description: 'Repository name or path.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'move_impact',
+        description: `Blast radius for a Move/Aptos symbol over Move edges (CALLS / READS_RESOURCE / WRITES_RESOURCE / ACQUIRES / USES_TYPE).
+
+WHEN TO USE: BEFORE editing a Move function or resource/type. Reports callers, resource-access dependents, and signature type users. Restricts the generic impact traversal to Move semantic edges.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: {
+                    type: 'string',
+                    description: 'Move symbol (qualified name preferred, e.g. 0xa::coin::transfer).',
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['upstream', 'downstream'],
+                    description: 'upstream = who depends on the target (default); downstream = what the target depends on.',
+                },
+                maxDepth: { type: 'number', description: 'Traversal depth (default 3).' },
+                repo: { type: 'string', description: 'Repository name or path.' },
+            },
+            required: ['target'],
+        },
+    },
 ];
 /**
  * Per-repo tools that accept an optional `branch` scope (#2106). Single source
@@ -827,6 +921,9 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'shape_check',
     'api_impact',
     'trace',
+    'move_entries',
+    'move_resources',
+    'move_impact',
 ]);
 for (const tool of GITNEXUS_TOOLS) {
     if (!BRANCH_SCOPED_TOOLS.has(tool.name))

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

@@ -30,6 +30,7 @@ export interface AnalyzeJob {
 export declare class JobManager {
     private jobs;
     private children;
+    private abortControllers;
     private timeouts;
     private emitter;
     private cleanupTimer;
@@ -45,6 +46,8 @@ export declare class JobManager {
     updateJob(id: string, update: Partial<Pick<AnalyzeJob, 'status' | 'progress' | 'error' | 'repoPath' | 'repoName' | 'completedAt'>>): void;
     /** Register a child process for a job — enables cancellation and timeout. */
     registerChild(jobId: string, child: ChildProcess): void;
+    /** Register cancellable in-process work for a job. */
+    registerAbortController(jobId: string, controller: AbortController): void;
     /** Cancel a running job — sends SIGTERM to child process. */
     cancelJob(jobId: string, reason?: string): boolean;
     /** Subscribe to progress events for a job. Returns unsubscribe function. */

package/dist/server/analyze-job.js

@@ -16,6 +16,7 @@ const JOB_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 export class JobManager {
     jobs = new Map();
     children = new Map();
+    abortControllers = new Map();
     timeouts = new Map();
     emitter = new EventEmitter();
     cleanupTimer;
@@ -72,6 +73,7 @@ export class JobManager {
         Object.assign(job, update);
         if (this.isTerminal(job.status)) {
             job.completedAt = job.completedAt ?? Date.now();
+            this.abortControllers.delete(id);
         }
         // Emit exactly one event per updateJob call to prevent SSE double-write
         if (update.status === 'complete' || update.status === 'failed') {
@@ -107,6 +109,15 @@ export class JobManager {
             }
         });
     }
+    /** Register cancellable in-process work for a job. */
+    registerAbortController(jobId, controller) {
+        const job = this.jobs.get(jobId);
+        if (!job || this.isTerminal(job.status)) {
+            controller.abort();
+            return;
+        }
+        this.abortControllers.set(jobId, controller);
+    }
     /** Cancel a running job — sends SIGTERM to child process. */
     cancelJob(jobId, reason) {
         const job = this.jobs.get(jobId);
@@ -116,6 +127,8 @@ export class JobManager {
         if (child) {
             child.kill('SIGTERM');
         }
+        this.abortControllers.get(jobId)?.abort();
+        this.abortControllers.delete(jobId);
         this.updateJob(jobId, {
             status: 'failed',
             error: reason || 'Analysis cancelled',
@@ -134,6 +147,9 @@ export class JobManager {
             child.kill('SIGTERM');
         }
         this.children.clear();
+        for (const controller of this.abortControllers.values())
+            controller.abort();
+        this.abortControllers.clear();
         // Clear all timeouts
         for (const timer of this.timeouts.values()) {
             clearTimeout(timer);
@@ -150,6 +166,7 @@ export class JobManager {
         for (const [id, job] of this.jobs) {
             if (this.isTerminal(job.status) && job.completedAt && now - job.completedAt > JOB_TTL_MS) {
                 this.jobs.delete(id);
+                this.abortControllers.delete(id);
             }
         }
     }

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

@@ -17,6 +17,12 @@ export interface LaunchDeps {
     };
     acquireRepoLock: (key: string) => string | null;
     releaseRepoLock: (key: string) => void;
+    /**
+     * Drops the server's cached LadybugDB handle (closeLbug). The worker
+     * process rewrites the repo's DB files on disk, so a connection opened
+     * before the rewrite keeps reading the pre-rewrite state until evicted.
+     */
+    closeDbHandle: () => Promise<void>;
 }
 export interface LaunchOptions {
     force?: boolean;

package/dist/server/analyze-launch.js

@@ -10,16 +10,83 @@
  * path is resolved relative to `import.meta.url`.
  */
 import path from 'path';
+import { existsSync, statSync } from 'node:fs';
 import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
-import { getStoragePath } from '../storage/repo-manager.js';
+import { canonicalizePath, getStoragePath, INDEX_METADATA_FILE, listRegisteredRepos, registryPathEquals, } from '../storage/repo-manager.js';
 import { logger } from '../core/logger.js';
 const _require = createRequire(import.meta.url);
 const MAX_WORKER_RETRIES = 2;
+/**
+ * The worker reports `complete` over IPC before its on-disk finalization
+ * (LadybugDB checkpoint + native handle release + metadata write) is visible
+ * at `getStoragePath(targetPath)` — observed up to ~6.5s behind the IPC
+ * message. Opening the database inside that window is what the pre-IPC
+ * ordering was meant to prevent and is actively dangerous: reads fail with
+ * binder errors or return an empty graph, the open can quarantine the
+ * in-flight WAL, and the native layer racing the rewrite has crashed the
+ * whole server (SIGSEGV-class exit, no output) on slow CI runners.
+ */
+const FINALIZE_SETTLE_TIMEOUT_MS = 60_000;
+const FINALIZE_SETTLE_POLL_MS = 200;
+/**
+ * Resolve once the analyzed repo's index is settled at `storagePath`: the
+ * LadybugDB file and metadata both exist AND were (re)written by THIS job
+ * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
+ * the previous index in place while it works), and no transient WAL/shadow/
+ * checkpoint sidecars remain (the worker's native close has finished).
+ *
+ * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
+ * than failing a job whose analysis genuinely succeeded — e.g. a no-op
+ * non-force analyze legitimately rewrites nothing.
+ */
+/**
+ * Look up the analyzed repo's registered storage path. The request's
+ * user-provided path is used only as a comparison key; the filesystem probes
+ * below run against the registry's own `storagePath` — the server-owned
+ * record readers resolve through, and not a user-controlled value
+ * (CodeQL js/path-injection).
+ */
+const registeredStoragePath = async (targetPath) => {
+    const target = canonicalizePath(path.resolve(targetPath));
+    const entries = await listRegisteredRepos();
+    const entry = entries.find((e) => registryPathEquals(canonicalizePath(e.path), target));
+    return entry?.storagePath ?? null;
+};
+const waitForSettledIndex = async (targetPath, jobStartMs) => {
+    const settled = (storagePath) => {
+        try {
+            const lbugStat = statSync(path.join(storagePath, 'lbug'));
+            const metaStat = statSync(path.join(storagePath, INDEX_METADATA_FILE));
+            return (lbugStat.mtimeMs >= jobStartMs &&
+                metaStat.mtimeMs >= jobStartMs &&
+                ['lbug.wal', 'lbug.shadow', 'lbug.wal.checkpoint'].every((f) => !existsSync(path.join(storagePath, f))));
+        }
+        catch {
+            return false; // not written yet
+        }
+    };
+    const deadline = Date.now() + FINALIZE_SETTLE_TIMEOUT_MS;
+    for (;;) {
+        // Re-resolved each round: the worker registers the repo as part of the
+        // finalization this gate is waiting out.
+        const storagePath = await registeredStoragePath(targetPath);
+        if (storagePath && settled(storagePath))
+            return;
+        if (Date.now() > deadline) {
+            logger.warn({ targetPath }, 'analyze finalization not visible after timeout; completing job anyway');
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, FINALIZE_SETTLE_POLL_MS));
+    }
+};
 export function createLaunchAnalysisWorker(deps) {
-    const { jobManager, backend, acquireRepoLock, releaseRepoLock } = deps;
+    const { jobManager, backend, acquireRepoLock, releaseRepoLock, closeDbHandle } = deps;
     return function launchAnalysisWorker(job, targetPath, opts) {
+        // For waitForSettledIndex: files (re)written by this job have mtimes at or
+        // after this instant. Taken before the fork so no worker write predates it.
+        const jobStartMs = Date.now();
         // Acquire shared repo lock (keyed on storagePath to match embed handler)
         const analyzeLockKey = getStoragePath(targetPath);
         const lockErr = acquireRepoLock(analyzeLockKey);
@@ -67,10 +134,17 @@ export function createLaunchAnalysisWorker(deps) {
                 }
                 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()
+                    // Before marking complete: (1) wait for the worker's on-disk
+                    // finalization to settle (see waitForSettledIndex), (2) evict the
+                    // cached DB handle — same invalidation DELETE /api/repo performs, a
+                    // handle opened before the rewrite reads pre-rewrite state — and
+                    // only then (3) reinitialize the backend. This makes the ordering
+                    // comment below true in practice: the repo is actually queryable
+                    // when the client receives the SSE complete event.
+                    waitForSettledIndex(targetPath, jobStartMs)
+                        .then(() => closeDbHandle())
+                        .catch(() => { }) // best-effort: eviction failure must not fail the job
+                        .then(() => backend.init())
                         .then(() => {
                         jobManager.updateJob(job.id, { status: 'complete', repoName: msg.result.repoName });
                     })
@@ -84,6 +158,8 @@ export function createLaunchAnalysisWorker(deps) {
                 }
                 else if (msg.type === 'error') {
                     releaseRepoLock(analyzeLockKey);
+                    // A failed (force) analyze may still have rewritten DB files first.
+                    void closeDbHandle().catch(() => { });
                     jobManager.updateJob(job.id, { status: 'failed', error: msg.message });
                 }
             });

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

@@ -14,6 +14,7 @@
  */
 import type { AnalyzeOptions } from '../core/run-analyze.js';
 import type { WorkerMessage } from './analyze-worker.js';
+import type { AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
 export interface WorkerAnalysisDeps {
     runFullAnalysis: typeof import('../core/run-analyze.js').runFullAnalysis;
     assertAnalysisFinalized: typeof import('../storage/repo-manager.js').assertAnalysisFinalized;
@@ -32,7 +33,7 @@ export interface WorkerAnalysisDeps {
  * already claimed the terminal slot — and never throws; the caller schedules
  * `process.exit` after this resolves.
  */
-export declare function runWorkerAnalysis(repoPath: string, options: AnalyzeOptions, deps: WorkerAnalysisDeps): Promise<void>;
+export declare function runWorkerAnalysis(repoPath: string, options: AnalyzeOptions, deps: WorkerAnalysisDeps, runnerIdentityAtBootstrap?: AnalyzerRunnerIdentity): Promise<void>;
 /**
  * Create the single-use terminal-outcome claim shared by the worker's message
  * handler and its SIGTERM handler. The first call returns `true`; every later

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

@@ -5,9 +5,12 @@ import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
  * already claimed the terminal slot — and never throws; the caller schedules
  * `process.exit` after this resolves.
  */
-export async function runWorkerAnalysis(repoPath, options, deps) {
+export async function runWorkerAnalysis(repoPath, options, deps, runnerIdentityAtBootstrap) {
     let terminal;
     try {
+        const bootstrapArgs = runnerIdentityAtBootstrap
+            ? [runnerIdentityAtBootstrap]
+            : [];
         const result = await deps.runFullAnalysis(repoPath, 
         // This worker force-exits right after reporting, so skip the native close
         // (it can double-free in LadybugDB's ClientContext destructor after --pdg
@@ -15,7 +18,7 @@ export async function runWorkerAnalysis(repoPath, options, deps) {
         { ...options, skipNativeCloseOnExit: true }, {
             onProgress: (phase, percent, message) => deps.send({ type: 'progress', phase, percent, message }),
             onLog: (message) => deps.send({ type: 'progress', phase: 'log', percent: -1, message }),
-        });
+        }, ...bootstrapArgs);
         // P2 (#2264): a half-finalized repo — meta.json written but the global
         // registry entry missing (e.g. a prior collision-aborted run, or a wiped
         // registry) — must NOT be reported as a successful analysis. Mirror the CLI's

package/dist/server/analyze-worker.js

@@ -10,10 +10,7 @@
  *   Child -> Parent: { type: 'complete', result: AnalyzeResult }
  *   Child -> Parent: { type: 'error', message: string }
  */
-import { runFullAnalysis } from '../core/run-analyze.js';
 import { runWorkerAnalysis, createTerminalClaim } from './analyze-worker-core.js';
-import { assertAnalysisFinalized } from '../storage/repo-manager.js';
-import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
 function send(msg) {
     // No try/catch: if the IPC channel is gone, process.send throws
     // (ERR_IPC_CHANNEL_CLOSED) and that failure must NOT be swallowed. Every caller
@@ -26,6 +23,7 @@ function send(msg) {
 // terminal send, so a cancel near the finish line can't also report success and a
 // late SIGTERM can't flip an already-reported job (#2264 P3).
 const claimTerminal = createTerminalClaim();
+let boundedCheckpointBeforeExit = null;
 // Catch uncaught exceptions and unhandled rejections — report them to the parent
 // over IPC (the same channel the analysis path uses), then exit. The report runs
 // in `try` and the exit in `finally` so a throw from send() on a closed channel
@@ -61,6 +59,10 @@ process.on('SIGTERM', () => {
     if (claimTerminal()) {
         send({ type: 'error', message: 'Analysis cancelled (worker received SIGTERM)' });
     }
+    if (!boundedCheckpointBeforeExit) {
+        process.exit(0);
+        return;
+    }
     void boundedCheckpointBeforeExit({
         exitCode: 0,
         onFlushError: (err) => {
@@ -76,16 +78,37 @@ process.on('message', async (msg) => {
         return;
     started = true;
     try {
+        // Capture the complete build/dependency receipt before evaluating the
+        // analyzer graph or loading LadybugDB. A replacement racing this boundary
+        // is compared against this receipt again immediately before metadata commit.
+        const identityModule = await import('../core/analyzer-identity.js');
+        const prepared = await identityModule.captureAnalyzerIdentityBeforeLoad(import.meta.url, async () => {
+            const [analysisModule, repoManager, shutdownHelpers] = await Promise.all([
+                import('../core/run-analyze.js'),
+                import('../storage/repo-manager.js'),
+                import('../core/lbug/shutdown-helpers.js'),
+            ]);
+            return { analysisModule, repoManager, shutdownHelpers };
+        });
+        boundedCheckpointBeforeExit = prepared.loaded.shutdownHelpers.boundedCheckpointBeforeExit;
         // The run → finalize → report contract lives in the side-effect-free
         // analyze-worker-core seam (unit-testable without this entry module's
         // process.on side effects). It reports exactly one terminal message and
         // never throws.
         await runWorkerAnalysis(msg.repoPath, msg.options, {
-            runFullAnalysis,
-            assertAnalysisFinalized,
+            runFullAnalysis: prepared.loaded.analysisModule.runFullAnalysis,
+            assertAnalysisFinalized: prepared.loaded.repoManager.assertAnalysisFinalized,
             send,
             claimTerminal,
-        });
+        }, prepared.runnerIdentity);
+    }
+    catch (error) {
+        if (claimTerminal()) {
+            send({
+                type: 'error',
+                message: error instanceof Error ? error.message : 'Analysis worker bootstrap failed',
+            });
+        }
     }
     finally {
         // LadybugDB's native module prevents clean exit — force it (same reason the