@akira-tl/forgerelay 0.4.4 → 0.4.6

package/dist/lsp/runtime/manager.js

@@ -1,5 +1,5 @@
 import { realpath } from "node:fs/promises";
-import { resolve } from "node:path";
+import { resolve, sep } from "node:path";
 import { CodeIntelligenceError, LanguageService, languageServiceKey, } from "../code-intelligence.js";
 import { LanguageServerConfigurationError, resolveLanguageProject, } from "../language-server-config.js";
 const LANGUAGE_SERVICE_IDLE_MS = 10 * 60 * 1_000;
@@ -8,17 +8,25 @@ const MAX_LANGUAGE_SERVICES = 16;
 const LANGUAGE_SERVICE_START_TIMEOUT_MS = 15_000;
 const LANGUAGE_REQUEST_TIMEOUT_MS = 10_000;
 const LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS = 2_000;
+const MAX_CONCURRENT_SEMANTIC_REQUESTS = 4;
+const MAX_QUEUED_SEMANTIC_REQUESTS = 16;
 const MAX_DIAGNOSTIC_DOCUMENTS = 128;
 const MAX_DIAGNOSTICS_PER_DOCUMENT = 1000;
+const LANGUAGE_SERVICE_CRASH_COOLDOWN_MS = 5_000;
 export class CodeIntelligenceManager {
     config;
     services = new Map();
     serviceCreations = new Map();
+    invalidatedServiceKeys = new Set();
+    crashStates = new Map();
+    retiredWorkspaceRoots = new Set();
     serviceCreationQueue = Promise.resolve();
     cleanupTimer;
     policy;
+    crashCooldownMs;
     constructor(config, options = {}) {
         this.config = config;
+        this.crashCooldownMs = positiveInteger(options.crashCooldownMs, LANGUAGE_SERVICE_CRASH_COOLDOWN_MS, "crashCooldownMs");
         this.policy = {
             idleMs: positiveInteger(options.idleMs, LANGUAGE_SERVICE_IDLE_MS, "idleMs"),
             cleanupIntervalMs: positiveInteger(options.cleanupIntervalMs, LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS, "cleanupIntervalMs"),
@@ -26,6 +34,8 @@ export class CodeIntelligenceManager {
             startTimeoutMs: positiveInteger(options.startTimeoutMs, LANGUAGE_SERVICE_START_TIMEOUT_MS, "startTimeoutMs"),
             requestTimeoutMs: positiveInteger(options.requestTimeoutMs, LANGUAGE_REQUEST_TIMEOUT_MS, "requestTimeoutMs"),
             shutdownTimeoutMs: positiveInteger(options.shutdownTimeoutMs, LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs"),
+            maxConcurrentSemanticRequests: positiveInteger(options.maxConcurrentSemanticRequests, MAX_CONCURRENT_SEMANTIC_REQUESTS, "maxConcurrentSemanticRequests"),
+            maxQueuedSemanticRequests: positiveInteger(options.maxQueuedSemanticRequests, MAX_QUEUED_SEMANTIC_REQUESTS, "maxQueuedSemanticRequests"),
             maxDiagnosticDocuments: positiveInteger(options.maxDiagnosticDocuments, MAX_DIAGNOSTIC_DOCUMENTS, "maxDiagnosticDocuments"),
             maxDiagnosticsPerDocument: positiveInteger(options.maxDiagnosticsPerDocument, MAX_DIAGNOSTICS_PER_DOCUMENT, "maxDiagnosticsPerDocument"),
         };
@@ -34,11 +44,12 @@ export class CodeIntelligenceManager {
         }, this.policy.cleanupIntervalMs);
         this.cleanupTimer.unref();
     }
-    async run(workspaceRoot, input) {
+    async run(workspaceRoot, input, options = {}) {
         let project;
         let canonicalWorkspaceRoot;
         try {
             canonicalWorkspaceRoot = await realpath(resolve(workspaceRoot));
+            this.assertWorkspaceRootAvailable(canonicalWorkspaceRoot);
             project = await resolveLanguageProject({
                 workspaceRoot: canonicalWorkspaceRoot,
                 sourcePath: input.path,
@@ -51,26 +62,42 @@ export class CodeIntelligenceManager {
             }
             throw error;
         }
-        const service = await this.acquireService(canonicalWorkspaceRoot, project);
-        try {
-            switch (input.operation) {
-                case "definition":
-                    return await service.definition(input);
-                case "hover":
-                    return await service.hover(input);
-                case "references":
-                    return await service.references(input);
-                case "documentSymbols":
-                    return await service.documentSymbols(input);
-                case "workspaceSymbols":
-                    return await service.workspaceSymbols(input);
-                case "diagnostics":
-                    return await service.diagnostics(input);
+        await this.invalidateChangedServices(project);
+        const identity = languageServiceKey(project);
+        this.assertNotCoolingDown(identity, project);
+        let lastCrash;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            this.assertWorkspaceRootAvailable(canonicalWorkspaceRoot);
+            const service = await this.acquireService(canonicalWorkspaceRoot, project);
+            let crashed = false;
+            try {
+                const result = await this.executeOperation(service, input, options.signal);
+                this.crashStates.delete(identity);
+                return result;
+            }
+            catch (error) {
+                if (!(error instanceof CodeIntelligenceError) || error.code !== "code.server_crashed") {
+                    throw error;
+                }
+                crashed = true;
+                lastCrash = error;
+            }
+            finally {
+                await this.releaseService(service);
+            }
+            if (crashed) {
+                await this.discardService(service);
+                const failures = (this.crashStates.get(identity)?.failures ?? 0) + 1;
+                if (attempt === 0) {
+                    this.crashStates.set(identity, { failures, cooldownUntil: 0 });
+                    continue;
+                }
+                const cooldownUntil = Date.now() + this.crashCooldownMs;
+                this.crashStates.set(identity, { failures, cooldownUntil });
+                throw new CodeIntelligenceError("code.language_service_cooldown", `Language server ${project.definition.id} crashed repeatedly; retry after ${this.crashCooldownMs}ms. Last error: ${lastCrash.message}`);
             }
         }
-        finally {
-            service.release();
-        }
+        throw lastCrash ?? new CodeIntelligenceError("code.server_crashed", `Language server ${project.definition.id} failed without a recoverable result.`);
     }
     async shutdown() {
         clearInterval(this.cleanupTimer);
@@ -78,11 +105,150 @@ export class CodeIntelligenceManager {
         this.serviceCreations.clear();
         const services = [...this.services.values()];
         this.services.clear();
+        this.invalidatedServiceKeys.clear();
+        this.crashStates.clear();
+        this.retiredWorkspaceRoots.clear();
         await Promise.allSettled(services.map((service) => service.shutdown()));
     }
     get size() {
         return this.services.size;
     }
+    stats() {
+        const services = [...this.services.values()];
+        const now = Date.now();
+        return services.reduce((stats, service) => {
+            const serviceStats = service.runtimeStats;
+            stats.servicesActive += service.isIdle ? 0 : 1;
+            stats.servicesIdle += service.isIdle ? 1 : 0;
+            stats.processesRunning += serviceStats.processRunning ? 1 : 0;
+            stats.operationsInFlight += serviceStats.operationInFlight;
+            stats.semanticRequestsActive += serviceStats.semanticRequestsActive;
+            stats.semanticRequestsQueued += serviceStats.semanticRequestsQueued;
+            stats.openDocuments += serviceStats.openDocuments;
+            stats.diagnosticSnapshots += serviceStats.diagnosticSnapshots;
+            stats.diagnosticsRetained += serviceStats.diagnosticsRetained;
+            stats.stderrBytes += serviceStats.stderrBytes;
+            return stats;
+        }, {
+            servicesTotal: services.length,
+            servicesActive: 0,
+            servicesIdle: 0,
+            processesRunning: 0,
+            operationsInFlight: 0,
+            semanticRequestsActive: 0,
+            semanticRequestsQueued: 0,
+            openDocuments: 0,
+            diagnosticSnapshots: 0,
+            diagnosticsRetained: 0,
+            stderrBytes: 0,
+            pendingCreations: this.serviceCreations.size,
+            crashCooldowns: [...this.crashStates.values()].filter((state) => state.cooldownUntil > now).length,
+            invalidatedServices: this.invalidatedServiceKeys.size,
+            retiredWorkspaceRoots: this.retiredWorkspaceRoots.size,
+        });
+    }
+    async retireWorkspaceRoot(workspaceRoot) {
+        const canonicalRoot = await realpath(resolve(workspaceRoot));
+        this.retiredWorkspaceRoots.add(canonicalRoot);
+        await Promise.allSettled(this.serviceCreations.values());
+        const matching = [...this.services.entries()].filter(([, service]) => resolve(service.workspaceRoot) === canonicalRoot);
+        const active = matching.filter(([, service]) => !service.isIdle);
+        if (active.length > 0) {
+            this.retiredWorkspaceRoots.delete(canonicalRoot);
+            throw new CodeIntelligenceError("code.language_service_busy", `Cannot finalize Workspace ${canonicalRoot} while ${active.length} Language service request(s) are still active.`);
+        }
+        let releasedServices = 0;
+        for (const [key, service] of matching) {
+            if (this.services.get(key) === service)
+                this.services.delete(key);
+            this.invalidatedServiceKeys.delete(key);
+            this.crashStates.delete(key);
+            await service.shutdown();
+            releasedServices += 1;
+        }
+        this.clearIdentityStateForWorkspaceRoot(canonicalRoot);
+        return { root: canonicalRoot, releasedServices };
+    }
+    restoreWorkspaceRoot(root) {
+        this.retiredWorkspaceRoots.delete(resolve(root));
+    }
+    assertWorkspaceRootAvailable(workspaceRoot) {
+        if (!this.retiredWorkspaceRoots.has(resolve(workspaceRoot)))
+            return;
+        throw new CodeIntelligenceError("code.language_service_unavailable", "Code intelligence is unavailable because this managed-worktree Workspace is being finalized.");
+    }
+    clearIdentityStateForWorkspaceRoot(workspaceRoot) {
+        for (const key of [...this.crashStates.keys()]) {
+            if (identityBelongsToWorkspaceRoot(key, workspaceRoot))
+                this.crashStates.delete(key);
+        }
+        for (const key of [...this.invalidatedServiceKeys]) {
+            if (identityBelongsToWorkspaceRoot(key, workspaceRoot))
+                this.invalidatedServiceKeys.delete(key);
+        }
+    }
+    async executeOperation(service, input, signal) {
+        switch (input.operation) {
+            case "definition":
+                return service.definition(input, signal);
+            case "hover":
+                return service.hover(input, signal);
+            case "references":
+                return service.references(input, signal);
+            case "documentSymbols":
+                return service.documentSymbols(input, signal);
+            case "workspaceSymbols":
+                return service.workspaceSymbols(input, signal);
+            case "diagnostics":
+                return service.diagnostics(input, signal);
+        }
+    }
+    assertNotCoolingDown(identity, project) {
+        const state = this.crashStates.get(identity);
+        if (!state?.cooldownUntil)
+            return;
+        const remaining = state.cooldownUntil - Date.now();
+        if (remaining <= 0) {
+            this.crashStates.delete(identity);
+            return;
+        }
+        throw new CodeIntelligenceError("code.language_service_cooldown", `Language server ${project.definition.id} is cooling down after repeated crashes; retry in ${remaining}ms.`);
+    }
+    async invalidateChangedServices(project) {
+        const root = resolve(project.projectRoot);
+        const invalidated = [];
+        for (const [key, service] of this.services) {
+            if (resolve(service.project.projectRoot) === root &&
+                service.project.definition.id === project.definition.id &&
+                service.project.definition.fingerprint !== project.definition.fingerprint) {
+                this.invalidatedServiceKeys.add(key);
+                this.crashStates.delete(key);
+                if (service.isIdle)
+                    invalidated.push([key, service]);
+            }
+        }
+        for (const [key, service] of invalidated) {
+            if (this.services.get(key) === service)
+                this.services.delete(key);
+            this.invalidatedServiceKeys.delete(key);
+            await service.shutdown();
+        }
+    }
+    async releaseService(service) {
+        service.release();
+        if (!this.invalidatedServiceKeys.has(service.key) || !service.isIdle)
+            return;
+        if (this.services.get(service.key) === service)
+            this.services.delete(service.key);
+        this.invalidatedServiceKeys.delete(service.key);
+        await service.shutdown();
+    }
+    async discardService(service) {
+        if (this.services.get(service.key) === service)
+            this.services.delete(service.key);
+        this.invalidatedServiceKeys.delete(service.key);
+        await service.shutdown();
+    }
     async acquireService(workspaceRoot, project) {
         const key = languageServiceKey(project);
         const existing = this.services.get(key);
@@ -133,7 +299,7 @@ export class CodeIntelligenceManager {
         }
     }
     async closeIdle(now = Date.now()) {
-        const stale = [...this.services.entries()].filter(([, service]) => service.inFlight === 0 && now - service.lastUsedAt >= this.policy.idleMs);
+        const stale = [...this.services.entries()].filter(([, service]) => service.isIdle && now - service.lastUsedAt >= this.policy.idleMs);
         for (const [key, service] of stale) {
             this.services.delete(key);
             await service.shutdown();
@@ -143,7 +309,7 @@ export class CodeIntelligenceManager {
         if (this.services.size < this.policy.maxServices)
             return;
         const idle = [...this.services.entries()]
-            .filter(([, service]) => service.inFlight === 0)
+            .filter(([, service]) => service.isIdle)
             .sort((left, right) => left[1].lastUsedAt - right[1].lastUsedAt);
         const candidate = idle[0];
         if (!candidate) {
@@ -153,6 +319,21 @@ export class CodeIntelligenceManager {
         await candidate[1].shutdown();
     }
 }
+function identityBelongsToWorkspaceRoot(identity, workspaceRoot) {
+    try {
+        const parsed = JSON.parse(identity);
+        const projectRoot = Array.isArray(parsed) && typeof parsed[0] === "string"
+            ? resolve(parsed[0])
+            : undefined;
+        if (!projectRoot)
+            return false;
+        const root = resolve(workspaceRoot);
+        return projectRoot === root || projectRoot.startsWith(`${root}${sep}`);
+    }
+    catch {
+        return false;
+    }
+}
 function positiveInteger(value, fallback, label) {
     const resolvedValue = value ?? fallback;
     if (!Number.isInteger(resolvedValue) || resolvedValue < 1) {

package/dist/lsp/runtime/semantic-requests.js

@@ -0,0 +1,116 @@
+import { CancellationTokenSource } from "vscode-jsonrpc";
+import { CodeIntelligenceError } from "../code-intelligence-error.js";
+export class SemanticRequestCoordinator {
+    options;
+    active = 0;
+    queue = [];
+    constructor(options) {
+        this.options = options;
+    }
+    async run(label, signal, operation) {
+        const startedAt = Date.now();
+        await this.acquire(label, signal, startedAt);
+        const source = new CancellationTokenSource();
+        let settledForCaller = false;
+        let timeout;
+        let onAbort;
+        const cancellation = new Promise((_resolve, reject) => {
+            const rejectOnce = (error) => {
+                if (settledForCaller)
+                    return;
+                settledForCaller = true;
+                try {
+                    source.cancel();
+                }
+                catch {
+                    // The Language-server connection may already have closed or crashed.
+                }
+                reject(error);
+            };
+            const remaining = Math.max(1, this.options.deadlineMs - (Date.now() - startedAt));
+            timeout = setTimeout(() => rejectOnce(new CodeIntelligenceError("code.request_timeout", `${label} exceeded the ${this.options.deadlineMs}ms semantic request deadline.`)), remaining);
+            timeout.unref();
+            if (signal) {
+                onAbort = () => rejectOnce(new CodeIntelligenceError("code.request_cancelled", `${label} was cancelled by the Host.`));
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            }
+        });
+        const underlying = operation(source.token);
+        underlying.finally(() => {
+            source.dispose();
+            this.release();
+        }).catch(() => undefined);
+        try {
+            const value = await Promise.race([underlying, cancellation]);
+            settledForCaller = true;
+            return value;
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+            if (signal && onAbort)
+                signal.removeEventListener("abort", onAbort);
+        }
+    }
+    get activeCount() {
+        return this.active;
+    }
+    get queuedCount() {
+        return this.queue.length;
+    }
+    async acquire(label, signal, startedAt) {
+        if (signal?.aborted) {
+            throw new CodeIntelligenceError("code.request_cancelled", `${label} was cancelled by the Host.`);
+        }
+        if (this.active < this.options.maxConcurrent) {
+            this.active += 1;
+            return;
+        }
+        if (this.queue.length >= this.options.maxQueued) {
+            throw new CodeIntelligenceError("code.request_capacity", `Semantic request queue capacity reached (${this.options.maxQueued}) for this Language service.`);
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal };
+            const remaining = Math.max(1, this.options.deadlineMs - (Date.now() - startedAt));
+            const remove = () => {
+                const index = this.queue.indexOf(waiter);
+                if (index >= 0)
+                    this.queue.splice(index, 1);
+            };
+            waiter.timer = setTimeout(() => {
+                remove();
+                reject(new CodeIntelligenceError("code.request_timeout", `${label} exceeded the ${this.options.deadlineMs}ms semantic request deadline while queued.`));
+            }, remaining);
+            waiter.timer.unref();
+            if (signal) {
+                waiter.onAbort = () => {
+                    remove();
+                    if (waiter.timer)
+                        clearTimeout(waiter.timer);
+                    reject(new CodeIntelligenceError("code.request_cancelled", `${label} was cancelled by the Host.`));
+                };
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            this.queue.push(waiter);
+        });
+    }
+    release() {
+        this.active = Math.max(0, this.active - 1);
+        while (this.queue.length > 0 && this.active < this.options.maxConcurrent) {
+            const waiter = this.queue.shift();
+            if (waiter.timer)
+                clearTimeout(waiter.timer);
+            if (waiter.signal && waiter.onAbort)
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            if (waiter.signal?.aborted) {
+                waiter.reject(new CodeIntelligenceError("code.request_cancelled", "Semantic request was cancelled by the Host."));
+                continue;
+            }
+            this.active += 1;
+            waiter.resolve();
+        }
+    }
+}

package/dist/lsp/test-support/server-fixture.js

@@ -51,9 +51,14 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
     };
     t.after(async () => {
         await close();
-        await rm(root, { recursive: true, force: true });
+        await rm(root, {
+            recursive: true,
+            force: true,
+            maxRetries: 8,
+            retryDelay: 100,
+        });
     });
-    return { client, project, close };
+    return { client, project, codeIntelligence, close };
 }
 export async function callOpen(client, path, conversationScopeId) {
     return client.callTool({

package/dist/server.js

@@ -755,10 +755,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
         codeIntelligence: {
             available: true,
-            run: async (input, context) => {
+            run: async (input, context, options) => {
                 try {
                     return {
-                        value: await codeIntelligence.run(context.workspaceRoot, input),
+                        value: await codeIntelligence.run(context.workspaceRoot, input, { signal: options.signal }),
                     };
                 }
                 catch (error) {
@@ -1254,7 +1254,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }) => {
+    }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         let changedPaths = [];
         return runToolWithHooks(hooks, {
@@ -1289,7 +1289,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         });
                         return result;
                     }
-                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace), { nativeFile: file });
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace), { nativeFile: file, signal: extra.signal });
                     changedPaths = execution.changedPaths ?? [];
                     const result = {
                         content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
@@ -1389,7 +1389,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         throw new Error(`Cannot close this worktree-backed workspace while logical workspace processes are still running or awaiting completion delivery: ${busyWorkspaceIds.join(", ")}.`);
                     }
                     const startedAt = performance.now();
-                    const closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                    const retirement = await codeIntelligence.retireWorkspaceRoot(workspace.root);
+                    let closed;
+                    try {
+                        closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                    }
+                    finally {
+                        codeIntelligence.restoreWorkspaceRoot(retirement.root);
+                    }
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
                     const result = [
                         `Closed managed-worktree-backed workspace ${workspaceId}.`,
@@ -2161,6 +2168,7 @@ export function createServer(config = loadConfig(), options = {}) {
     const logRuntimeResources = () => {
         const memory = process.memoryUsage();
         const processStats = processSessions.stats();
+        const codeStats = codeIntelligence.stats();
         logEvent(config.logging, "debug", "runtime_resources", {
             rssBytes: memory.rss,
             heapUsedBytes: memory.heapUsed,
@@ -2173,7 +2181,20 @@ export function createServer(config = loadConfig(), options = {}) {
             processesCompleted: processStats.completed,
             cachedWorkspaces: workspaces.cachedWorkspaceCount,
             reviewStates: reviewCheckpoints.stateCount,
-            languageServices: codeIntelligence.size,
+            languageServices: codeStats.servicesTotal,
+            languageServicesActive: codeStats.servicesActive,
+            languageProcessesRunning: codeStats.processesRunning,
+            languageOperationsInFlight: codeStats.operationsInFlight,
+            languageRequestsActive: codeStats.semanticRequestsActive,
+            languageRequestsQueued: codeStats.semanticRequestsQueued,
+            languageOpenDocuments: codeStats.openDocuments,
+            languageDiagnosticSnapshots: codeStats.diagnosticSnapshots,
+            languageDiagnosticsRetained: codeStats.diagnosticsRetained,
+            languageStderrBytes: codeStats.stderrBytes,
+            languagePendingCreations: codeStats.pendingCreations,
+            languageCrashCooldowns: codeStats.crashCooldowns,
+            languageInvalidatedServices: codeStats.invalidatedServices,
+            languageRetiredWorkspaceRoots: codeStats.retiredWorkspaceRoots,
         });
     };
     const transportCleanupTimer = setInterval(() => {

package/docs/configuration.md

@@ -154,7 +154,7 @@ force a Host to invalidate its cached schema.
 ### LSP code intelligence
 
 ForgeRelay advertises `code.intelligence` through the Capability Gateway; it does
-not add language-specific top-level MCP tools. ForgeRelay 0.4.4 supports
+not add language-specific top-level MCP tools. ForgeRelay 0.4 LSP v1 supports
 `definition`, `hover`, `references`, `documentSymbols`, `workspaceSymbols`, and
 `diagnostics`.
 Position-based operations accept the same workspace-relative source position. Hover
@@ -173,7 +173,28 @@ snapshot. Push and pull use one normalized result shape with `provider`,
 filesystem document version. Bounded collection results report `returned`, `truncated`,
 and the real `total` when the complete Language-server response makes it known. Language Servers are external
 dependencies: ForgeRelay may discover an executable already installed on the
-machine, but it never downloads or installs one automatically.
+machine, but it never downloads or installs one automatically. Built-in discovery
+knows `typescript-language-server`, `pyright-langserver`, `rust-analyzer`, `gopls`,
+and `clangd`. See `examples/language-servers.json` for copyable explicit TypeScript
+and Pyright definitions.
+
+ForgeRelay 0.4.5 hardens this shared Language-service runtime. Semantic requests
+have one internal bounded deadline, Host cancellation propagates to LSP cancellation,
+and each service has finite concurrent and queued request budgets rather than
+Agent-configurable timeouts. An unexpected server crash is retried at most once;
+repeated crashes enter a short cooldown. Effective server-definition fingerprints
+invalidate only the affected project/service on the next resolution without adding
+a recursive filesystem watcher.
+
+Language services are keyed by physical Language project identity, so logical
+workspaces over the same checkout reuse one process. Truly idle services are
+reclaimed after a bounded TTL and the global service cap evicts the least-recently-
+used safe idle service. A server request that ignores cancellation still counts as
+active until the underlying JSON-RPC request settles. Managed-worktree finalization
+releases services rooted in that worktree before removal and refuses finalization
+while semantic work is active. Debug `runtime_resources` telemetry includes only
+aggregate Language-service/process/request/document/diagnostic/stderr counts; it
+does not log source contents or source paths.
 
 Effective Language-server definitions resolve in this order:
 
@@ -225,6 +246,11 @@ not recursively scan the Workspace.
 
 Code-intelligence input positions are 1-based line and 1-based Unicode code-point
 column values. The Workspace filesystem is the only v1 document source of truth.
+
+For contributor/release interoperability checks, run `npm run lsp:interop`. The
+command tests each supported real Language server that is already on `PATH` through
+ForgeRelay built-in discovery and stdio LSP, reports a clear skip when an executable
+is absent, and never installs external dependencies.
 Definition results may point outside the Workspace and are then marked
 `external: true`; this is informational only and does not expand allowed roots or
 file-tool authority.

package/docs/roadmap.md

@@ -240,6 +240,13 @@ and verify publication before work begins on the next boundary:
 - **0.4.6** — optional real-server interoperability, cross-platform checks, fresh Host
   acceptance, documentation, and final LSP v1 closure.
 
+The shipping 0.4 LSP v1 contract keeps the canonical nine Core MCP tools unchanged
+and exposes semantic operations only through `code.intelligence`. Deterministic
+fake-LSP coverage remains the primary cross-platform protocol/lifecycle gate, while
+`npm run lsp:interop` exercises `typescript-language-server`, Pyright,
+`rust-analyzer`, `gopls`, and `clangd` only when those external executables are
+already present and otherwise reports explicit skips without installing them.
+
 ## 0.5 — First-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions.

package/docs/versioning.md

@@ -85,6 +85,18 @@ Run the full local release gate with:
 npm run release:verify
 ```
 
+`release:verify` checks the current development runtime and then runs a focused
+`release:parity` gate in an isolated Node 22.19.0 sandbox. The parity sandbox
+performs its own `npm ci` so native addons use the same Node ABI as cloud CI,
+then reruns the LSP/release tests most sensitive to event-loop timing, process
+lifecycle, path canonicalization, executable discovery, and cleanup behavior.
+It also tests that a command which exists on `PATH` but fails its `--version`
+preflight is treated as unavailable rather than as an installed Language server.
+
+Cloud verification and the publication job are both pinned to Node 22.19.0, the
+minimum supported Node release, so local parity and the release runners use the
+same runtime instead of drifting across separate Node 22/24 variants.
+
 Validate a specific tag with:
 
 ```bash
@@ -158,8 +170,9 @@ npm publishing token.
 3. Run the appropriate `release:patch`, `release:minor`, or `release:major`
    command.
 4. Review the generated version and changelog diff.
-5. Run `npm run release:verify` locally. This full local gate is a release-time
-   operation; ordinary development pushes do not need to run the full release gate.
+5. Run `npm run release:verify` locally. This full local gate includes the isolated
+   Node 22.19.0 parity sandbox and is a release-time operation; ordinary development
+   pushes do not need to run the full release gate.
 6. Commit the release-ready code and metadata and push `main`.
 7. Create the exact version tag, for example:
 

package/examples/language-servers.json

@@ -0,0 +1,30 @@
+{
+  "typescript": {
+    "command": "typescript-language-server",
+    "args": ["--stdio"],
+    "env": {},
+    "languages": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
+    "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+    "languageIdByExtension": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact",
+      ".mjs": "javascript",
+      ".cjs": "javascript"
+    },
+    "projectMarkers": ["tsconfig.json", "jsconfig.json", "package.json"]
+  },
+  "pyright": {
+    "command": "pyright-langserver",
+    "args": ["--stdio"],
+    "env": {},
+    "languages": ["python"],
+    "extensions": [".py", ".pyi"],
+    "languageIdByExtension": {
+      ".py": "python",
+      ".pyi": "python"
+    },
+    "projectMarkers": ["pyrightconfig.json", "pyproject.toml", "setup.cfg", "setup.py"]
+  }
+}