@akira-tl/forgerelay 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.4.6] - 2026-08-11
+
+### Added
+
+- Added published `npm run lsp:interop` acceptance for `typescript-language-server`, Pyright, `rust-analyzer`, `gopls`, and `clangd`: detected executables run through built-in discovery and real stdio LSP, while missing external servers are reported as explicit skips without automatic installation.
+- Extended the real 7677 HTTP/OAuth/MCP acceptance path to execute all six `code.intelligence` v1 operations, normalized results, a stable error path, and Language-service `shutdown -> exit` behavior while keeping exactly nine Core MCP tools.
+
+### Changed
+
+- Cloud release CI now runs optional real-server interoperability after the normal deterministic fake-LSP test/build gate on Linux, macOS, and Windows. Executable preflight now distinguishes a runnable Language server from PATH shims/proxies that exist but fail to launch, so incomplete rustup components are skipped rather than misreported as installed servers.
+- Local `release:verify` now includes an isolated Node 22.19.0 parity sandbox with its own `npm ci` and focused LSP/release regression suite; cloud CI and publication use the same Node 22.19.0 runtime to reduce local/cloud drift, while Windows test cleanup retries transient locked-directory removal.
+- Completed the 0.4 LSP v1 user, configuration, roadmap, contributor, and explicit Language-server example documentation, and hardened cross-platform/concurrency acceptance timing exposed during final release validation.
+
 ## [0.4.5] - 2026-08-11
 
 ### Added

package/README.md

@@ -112,6 +112,22 @@ reports a semantic capability but the Host still shows an older tool snapshot,
 refresh or reconnect the integration rather than assuming the capability is
 missing from ForgeRelay.
 
+## LSP code intelligence
+
+ForgeRelay 0.4 LSP v1 exposes semantic code navigation through the
+`code.intelligence` Capability without adding language-specific top-level MCP tools.
+The v1 operations are definition, hover/type information, references, document
+symbols, workspace symbols, and diagnostics. Results use ForgeRelay-owned normalized
+locations, ranges, symbols, hover content, and diagnostic shapes rather than raw LSP
+wire unions.
+
+Language servers remain external dependencies. ForgeRelay can discover
+`typescript-language-server`, `pyright-langserver`, `rust-analyzer`, `gopls`, and
+`clangd` when they already exist on `PATH`, or use structured project/global
+configuration, but it never installs a server automatically. See
+[Configuration Reference](docs/configuration.md#lsp-code-intelligence) and
+[`examples/language-servers.json`](examples/language-servers.json).
+
 ## Worktrees without the usual cleanup mess
 
 A new managed worktree gets its own `forgerelay/*` branch instead of a detached
@@ -247,13 +263,13 @@ forgerelay doctor
 
 ## Where ForgeRelay is going
 
-The next additions are focused on making the local execution layer more useful,
-not on turning ForgeRelay into another all-in-one agent framework:
+With LSP code intelligence established in the 0.4 line, the next additions remain
+focused on making the local execution layer more useful, not on turning ForgeRelay
+into another all-in-one agent framework:
 
-1. LSP-backed code intelligence;
-2. first-class MCP subagent delegation;
-3. stronger worktree verification and recovery;
-4. checkpoint/rewind and retention improvements.
+1. first-class MCP subagent delegation;
+2. stronger worktree verification and recovery;
+3. checkpoint/rewind and retention improvements.
 
 ForgeRelay does not plan to add its own shell sandbox, long-term memory system,
 or plugin marketplace. Conversation, planning, web access, and other host-native
@@ -277,10 +293,13 @@ npm run release:verify
 ```
 
 Daily branch pushes do not run cloud CI. When preparing a release, run the full
-local release verification first. Pushing a matching `vX.Y.Z` tag to
-`Akira-TL/forgerelay` is the only cloud CI and publish trigger: GitHub Actions
-runs the reusable multi-platform CI, then publishes `@akira-tl/forgerelay` and
-creates the matching GitHub Release only after CI succeeds.
+local release verification first. `release:verify` includes a focused parity pass
+in an isolated Node 22.19.0 environment with its own `npm ci`, matching the cloud
+CI runtime for native addons and high-risk LSP lifecycle tests. Pushing a matching
+`vX.Y.Z` tag to `Akira-TL/forgerelay` is the only cloud CI and publish trigger:
+GitHub Actions runs the reusable multi-platform CI, then publishes
+`@akira-tl/forgerelay` and creates the matching GitHub Release only after CI
+succeeds.
 
 See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
 Trusted Publishing setup.

package/capabilities/code-intelligence/GUIDE.md

@@ -4,7 +4,7 @@ Use the `code.intelligence` Capability for read-only semantic code navigation ba
 
 ForgeRelay does not install Language servers. It discovers supported executables when available and accepts explicit definitions from the global ForgeRelay config or `<workspace>/.forgerelay/language-servers.json`. Project definitions override global definitions, and global definitions override built-in discovery. An explicit definition may disable discovery with `enabled: false`.
 
-ForgeRelay 0.4.4 adds `diagnostics` alongside `definition`, `hover`, `references`, `documentSymbols`, and `workspaceSymbols`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. `documentSymbols` needs only `path` and an optional bounded `limit`. `workspaceSymbols` uses `path` to select the Language project/service and accepts a `query` plus optional `limit`; it does not merge multiple nested Language services. `diagnostics` uses `path` plus an optional bounded `limit`. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
+ForgeRelay 0.4 LSP v1 exposes `definition`, `hover`, `references`, `documentSymbols`, `workspaceSymbols`, and `diagnostics`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. `documentSymbols` needs only `path` and an optional bounded `limit`. `workspaceSymbols` uses `path` to select the Language project/service and accepts a `query` plus optional `limit`; it does not merge multiple nested Language services. `diagnostics` uses `path` plus an optional bounded `limit`. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
 
 Code-intelligence results use ForgeRelay-owned shapes rather than raw LSP wire types. Definition returns normalized locations. Hover returns one `contents` string, an optional legacy `language`, and an optional ForgeRelay-normalized `range`; plaintext, Markdown `MarkupContent`, and supported legacy `MarkedString` payloads are normalized before reaching the Agent. References uses the same normalized location shape, defaults to `limit: 100`, and accepts limits up to 1000. Its result reports `returned`, `truncated`, and `total` when the complete Language-server response makes the total known.
 
@@ -21,3 +21,5 @@ Semantic Language-server requests use an internal bounded deadline; the Agent co
 An unexpected Language-server process exit fails its pending JSON-RPC work immediately instead of waiting for the semantic deadline. ForgeRelay discards that service and retries the current semantic operation at most once. A second consecutive crash for the same Language project/server-definition fingerprint enters a short cooldown before another process may be started; a successful retry clears the crash state. Effective server definitions are fingerprinted, so a changed project/global/built-in definition selects a new service identity on the next code-intelligence resolution and retires only an idle service with the same project root/server id but the old fingerprint. ForgeRelay does not add a recursive config watcher.
 
 Language services are shared by physical Language project identity rather than logical Workspace id, so multiple conversations over the same checkout do not multiply server processes. Idle services are reclaimed after a bounded TTL, and the global service cap evicts the least-recently-used truly idle service; a request that has returned to the Host but whose server ignored cancellation still counts as active until the underlying LSP request settles. Managed-worktree finalization releases idle Language services rooted in that worktree before removing it and refuses finalization while semantic work is still active. Debug runtime telemetry reports only aggregate service/process/request/document/diagnostic/stderr counts and never source contents.
+
+The built-in discovery candidates are `typescript-language-server`, `pyright-langserver`, `rust-analyzer`, `gopls`, and `clangd`. Contributors can run `npm run lsp:interop` to exercise any of those executables that are already present on `PATH`; each detected server is tested through built-in discovery and real stdio LSP, while absent servers are reported as explicit skips. The interoperability check never downloads or installs a Language server.

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

@@ -51,7 +51,12 @@ 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, codeIntelligence, close };
 }

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.5 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,10 @@ 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,
@@ -243,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"]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -40,6 +40,8 @@
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
     "debug:accept": "node scripts/debug/accept.mjs",
+    "lsp:interop": "node scripts/lsp-interop.mjs",
+    "release:parity": "node scripts/release-parity.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
     "test": "tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
@@ -50,7 +52,7 @@
     "release:patch": "node scripts/release-version.mjs next patch",
     "release:minor": "node scripts/release-version.mjs next minor",
     "release:major": "node scripts/release-version.mjs next major",
-    "release:verify": "npm run release:check && npm run typecheck && npm test && npm run build"
+    "release:verify": "npm run release:check && npm run typecheck && npm test && npm run build && npm run lsp:interop && npm run release:parity"
   },
   "keywords": [
     "mcp",

package/scripts/debug/accept.mjs

@@ -20,6 +20,11 @@ import {
   debugRoot,
   repoRoot,
 } from "./runtime.mjs";
+import {
+  assertCodeIntelligenceShutdown as assertCodeIntelligenceAcceptanceShutdown,
+  exerciseCodeIntelligence as exerciseCodeIntelligenceAcceptance,
+  setupCodeIntelligenceProject as setupCodeIntelligenceAcceptanceProject,
+} from "./code-intelligence-accept.mjs";
 
 const packageJson = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
 const acceptanceRoot = resolve(debugRoot, "acceptance");
@@ -27,6 +32,8 @@ const stateDir = resolve(acceptanceRoot, "state");
 const worktreeRoot = resolve(acceptanceRoot, "worktrees");
 const hookLog = resolve(acceptanceRoot, "hooks.jsonl");
 const checkoutWorkspace = resolve(acceptanceRoot, "workspace");
+const codeIntelligenceLog = resolve(acceptanceRoot, "code-intelligence-lsp.jsonl");
+const fakeLanguageServer = resolve(repoRoot, "src", "lsp", "test-fixtures", "fake-lsp-server.mjs");
 const gitProject = resolve(acceptanceRoot, "git-project");
 const releaseProject = resolve(acceptanceRoot, "release-project");
 const releaseRemote = resolve(acceptanceRoot, "release-remote.git");
@@ -38,6 +45,11 @@ await assertDebugPortFree();
 rmSync(acceptanceRoot, { recursive: true, force: true });
 mkdirSync(acceptanceRoot, { recursive: true });
 setupGitProject(checkoutWorkspace);
+setupCodeIntelligenceAcceptanceProject({
+  root: checkoutWorkspace,
+  fakeLanguageServer,
+  logPath: codeIntelligenceLog,
+});
 
 const { env } = createDebugEnvironment({
   ownerToken,
@@ -64,6 +76,7 @@ const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"
   env,
   stdio: ["ignore", "inherit", "inherit"],
 });
+let acceptanceCompleted = false;
 
 try {
   const health = await waitForHealth(server);
@@ -349,6 +362,13 @@ try {
     (variant) => variant.properties.operation.const === "workspaceSymbols",
   );
   assert.ok(workspaceSymbolsSchema.required.includes("query"));
+  exerciseCodeIntelligenceAcceptance({
+    callTool,
+    accessToken: oauth.accessToken,
+    sessionId,
+    workspaceId,
+    pass,
+  });
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
       workspaceId,
@@ -569,9 +589,7 @@ try {
     headers: mcpHeaders(oauth.accessToken, sessionId),
   });
   assert.ok([200, 202, 204].includes(deleteSession.status));
-
-  console.log("\nForgeRelay 7677 acceptance passed.");
-  console.log(`Artifacts: ${acceptanceRoot}`);
+  acceptanceCompleted = true;
 } catch (error) {
   console.error("\nForgeRelay 7677 acceptance failed.");
   throw error;
@@ -580,6 +598,12 @@ try {
   await stopServer(server);
 }
 
+if (acceptanceCompleted) {
+  assertCodeIntelligenceAcceptanceShutdown({ logPath: codeIntelligenceLog, pass });
+  console.log("\nForgeRelay 7677 acceptance passed.");
+  console.log(`Artifacts: ${acceptanceRoot}`);
+}
+
 function authorizeDebugClient(metadata) {
   const redirectUri = `${debugBaseUrl}/debug/callback`;
   const registration = jsonRequest(metadata.registration_endpoint, {

package/scripts/debug/code-intelligence-accept.mjs

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function setupCodeIntelligenceProject({ root, fakeLanguageServer, logPath }) {
+  mkdirSync(join(root, ".forgerelay"), { recursive: true });
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "tsconfig.json"), "{}\n", "utf8");
+  writeFileSync(
+    join(root, "src", "main.ts"),
+    [
+      "const value = target();",
+      "class Widget {",
+      "  runMethod() {}",
+      "  stopMethod() {}",
+      "}",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  writeFileSync(join(root, "src", "target.ts"), "export const target = () => 1;\n", "utf8");
+  writeFileSync(
+    join(root, ".forgerelay", "language-servers.json"),
+    `${JSON.stringify({
+      "debug-fake": {
+        command: process.execPath,
+        args: [fakeLanguageServer],
+        env: {
+          FORGERELAY_FAKE_LSP_LOG: logPath,
+          FORGERELAY_FAKE_LSP_HOVER_TEXT: "**debug target**: `() => void`",
+          FORGERELAY_FAKE_LSP_REFERENCE_COUNT: "2",
+          FORGERELAY_FAKE_LSP_DIAGNOSTICS_MODE: "pull",
+          FORGERELAY_FAKE_LSP_DIAGNOSTIC_COUNT: "2",
+        },
+        languages: ["typescript"],
+        extensions: [".ts"],
+        projectMarkers: ["tsconfig.json"],
+      },
+    }, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+export function exerciseCodeIntelligence({ callTool, accessToken, sessionId, workspaceId, pass }) {
+  const run = (id, argumentsValue) => callTool(accessToken, sessionId, id, "capability", {
+    workspaceId,
+    name: "code.intelligence",
+    action: "run",
+    arguments: argumentsValue,
+  });
+
+  const definition = run(90, {
+    operation: "definition",
+    path: "src/main.ts",
+    line: 1,
+    column: 15,
+  });
+  assert.equal(definition.isError, undefined);
+  const definitionResult = definition.structuredContent.result;
+  assert.equal(definitionResult.operation, "definition");
+  assert.equal(definitionResult.selectedServer, "debug-fake");
+  assert.deepEqual(definitionResult.locations, [{
+    path: "src/target.ts",
+    external: false,
+    range: {
+      start: { line: 1, column: 8 },
+      end: { line: 1, column: 14 },
+    },
+  }]);
+
+  const hover = run(91, {
+    operation: "hover",
+    path: "src/main.ts",
+    line: 1,
+    column: 15,
+  });
+  assert.equal(hover.isError, undefined);
+  assert.equal(hover.structuredContent.result.operation, "hover");
+  assert.equal(hover.structuredContent.result.contents, "**debug target**: `() => void`");
+  assert.deepEqual(hover.structuredContent.result.range, {
+    start: { line: 1, column: 15 },
+    end: { line: 1, column: 21 },
+  });
+
+  const references = run(92, {
+    operation: "references",
+    path: "src/main.ts",
+    line: 1,
+    column: 15,
+  });
+  assert.equal(references.isError, undefined);
+  assert.equal(references.structuredContent.result.operation, "references");
+  assert.equal(references.structuredContent.result.returned, 2);
+  assert.equal(references.structuredContent.result.total, 2);
+  assert.equal(references.structuredContent.result.truncated, false);
+  assert.ok(references.structuredContent.result.locations.every((location) =>
+    location.path === "src/target.ts" && location.external === false
+  ));
+
+  const documentSymbols = run(93, {
+    operation: "documentSymbols",
+    path: "src/main.ts",
+  });
+  assert.equal(documentSymbols.isError, undefined);
+  const documentSymbolsResult = documentSymbols.structuredContent.result;
+  assert.equal(documentSymbolsResult.operation, "documentSymbols");
+  assert.equal(documentSymbolsResult.hierarchical, true);
+  assert.equal(documentSymbolsResult.returned, 3);
+  assert.equal(documentSymbolsResult.symbols[0].name, "Widget");
+  assert.deepEqual(
+    documentSymbolsResult.symbols[0].children.map((symbol) => symbol.name),
+    ["run", "stop"],
+  );
+
+  const workspaceSymbols = run(94, {
+    operation: "workspaceSymbols",
+    path: "src/main.ts",
+    query: "Target",
+  });
+  assert.equal(workspaceSymbols.isError, undefined);
+  const workspaceSymbolsResult = workspaceSymbols.structuredContent.result;
+  assert.equal(workspaceSymbolsResult.operation, "workspaceSymbols");
+  assert.equal(workspaceSymbolsResult.returned, 1);
+  assert.equal(workspaceSymbolsResult.symbols[0].name, "Target");
+  assert.equal(workspaceSymbolsResult.symbols[0].location.path, "src/target.ts");
+  assert.equal(workspaceSymbolsResult.symbols[0].location.external, false);
+
+  const diagnostics = run(95, {
+    operation: "diagnostics",
+    path: "src/main.ts",
+  });
+  assert.equal(diagnostics.isError, undefined);
+  const diagnosticsResult = diagnostics.structuredContent.result;
+  assert.equal(diagnosticsResult.operation, "diagnostics");
+  assert.equal(diagnosticsResult.provider, "pull");
+  assert.equal(diagnosticsResult.returned, 2);
+  assert.equal(diagnosticsResult.total, 2);
+  assert.equal(diagnosticsResult.freshness.state, "fresh");
+  assert.deepEqual(
+    diagnosticsResult.diagnostics.map((diagnostic) => diagnostic.message),
+    ["pulled diagnostic 1", "pulled diagnostic 2"],
+  );
+
+  const invalidPosition = run(96, {
+    operation: "definition",
+    path: "src/main.ts",
+    line: 99,
+    column: 1,
+  });
+  assert.equal(invalidPosition.isError, true);
+  assert.equal(invalidPosition.structuredContent.error.code, "code.invalid_position");
+  pass(
+    "code intelligence execution",
+    "definition + hover + references + document/workspace symbols + diagnostics + stable error over OAuth/MCP",
+  );
+}
+
+export function assertCodeIntelligenceShutdown({ logPath, pass }) {
+  const events = readFileSync(logPath, "utf8")
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  const shutdownIndex = events.findIndex((event) => event.method === "shutdown");
+  const exitIndex = events.findIndex((event, index) => index > shutdownIndex && event.method === "exit");
+  assert.ok(shutdownIndex >= 0, "code-intelligence Language server did not receive shutdown");
+  assert.ok(exitIndex > shutdownIndex, "code-intelligence Language server did not receive exit after shutdown");
+  pass("code intelligence shutdown", "Language service received shutdown -> exit during ForgeRelay server shutdown");
+}

package/scripts/lsp-interop-support.mjs

@@ -0,0 +1,49 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export function findExecutable(
+  command,
+  env = process.env,
+  platform = process.platform,
+) {
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const pathEntries = pathValue.split(delimiter).filter(Boolean);
+  const extensions = platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+    : [""];
+  const accessMode = platform === "win32" ? constants.F_OK : constants.X_OK;
+
+  for (const directory of pathEntries) {
+    for (const extension of extensions) {
+      const candidate = join(directory, platform === "win32" ? `${command}${extension}` : command);
+      try {
+        accessSync(candidate, accessMode);
+        return candidate;
+      } catch {
+        // Continue searching PATH without invoking or installing anything.
+      }
+    }
+  }
+  return undefined;
+}
+
+export function probeExecutable(
+  executable,
+  env = process.env,
+  platform = process.platform,
+) {
+  const result = spawnSync(executable, ["--version"], {
+    encoding: "utf8",
+    env,
+    windowsHide: true,
+    timeout: 5_000,
+    ...(platform === "win32" ? { shell: true } : {}),
+  });
+  if (result.status === 0) return { available: true };
+  const reason = result.error?.message ?? result.stderr?.trim() ?? result.stdout?.trim() ?? `exit ${result.status ?? "unknown"}`;
+  return {
+    available: false,
+    reason: reason.replace(/\s+/g, " ").slice(0, 240),
+  };
+}

package/scripts/lsp-interop-support.test.mjs

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import test from "node:test";
+import { findExecutable, probeExecutable } from "./lsp-interop-support.mjs";
+
+const root = mkdtempSync(join(tmpdir(), "forgerelay-lsp-preflight-test-"));
+
+try {
+  const env = { ...process.env, PATH: root };
+  if (process.platform === "win32") {
+    env.PATHEXT = ".CMD";
+    writeFileSync(join(root, "working.cmd"), "@echo off\r\nif \"%1\"==\"--version\" echo fake-lsp 1.0.0 & exit /b 0\r\n", "utf8");
+    writeFileSync(join(root, "broken.cmd"), "@echo off\r\necho error: Unknown binary 1>&2\r\nexit /b 1\r\n", "utf8");
+  } else {
+    writeFileSync(join(root, "working"), "#!/bin/sh\necho fake-lsp 1.0.0\nexit 0\n", "utf8");
+    writeFileSync(join(root, "broken"), "#!/bin/sh\necho 'error: Unknown binary' >&2\nexit 1\n", "utf8");
+    chmodSync(join(root, "working"), 0o755);
+    chmodSync(join(root, "broken"), 0o755);
+  }
+
+  test("interop preflight distinguishes runnable executables from PATH proxies that fail", () => {
+    const working = findExecutable("working", env);
+    const broken = findExecutable("broken", env);
+    assert.ok(working);
+    assert.ok(broken);
+    assert.deepEqual(probeExecutable(working, env), { available: true });
+    const unavailable = probeExecutable(broken, env);
+    assert.equal(unavailable.available, false);
+    assert.match(unavailable.reason, /Unknown binary|exit 1/i);
+  });
+
+  test("interop preflight treats a missing command as unavailable without installation", () => {
+    assert.equal(findExecutable("missing-language-server", env), undefined);
+    assert.equal(env.PATH.split(delimiter).length, 1);
+  });
+} finally {
+  process.on("exit", () => rmSync(root, { recursive: true, force: true }));
+}

package/scripts/lsp-interop.mjs

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CodeIntelligenceManager } from "../dist/lsp/runtime/manager.js";
+import { findExecutable, probeExecutable } from "./lsp-interop-support.mjs";
+
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const interopRoot = resolve(repoRoot, ".forgerelay-debug", "lsp-interop");
+const fixtures = [
+  {
+    id: "typescript",
+    command: "typescript-language-server",
+    sourcePath: "src/main.ts",
+    hover: { line: 1, column: 14 },
+    setup(root) {
+      write(root, "tsconfig.json", `${JSON.stringify({ compilerOptions: { strict: true } }, null, 2)}\n`);
+      write(root, "src/main.ts", [
+        "export class Widget {",
+        "  run(): number { return 1; }",
+        "  stop(): number { return 0; }",
+        "}",
+        "",
+      ].join("\n"));
+    },
+  },
+  {
+    id: "pyright",
+    command: "pyright-langserver",
+    sourcePath: "main.py",
+    hover: { line: 1, column: 7 },
+    setup(root) {
+      write(root, "pyrightconfig.json", "{}\n");
+      write(root, "main.py", [
+        "class Widget:",
+        "    def run(self) -> int:",
+        "        return 1",
+        "",
+      ].join("\n"));
+    },
+  },
+  {
+    id: "rust-analyzer",
+    command: "rust-analyzer",
+    sourcePath: "src/lib.rs",
+    hover: { line: 1, column: 12 },
+    setup(root) {
+      write(root, "Cargo.toml", [
+        "[package]",
+        'name = "forgerelay-interop"',
+        'version = "0.1.0"',
+        'edition = "2021"',
+        "",
+        "[lib]",
+        'path = "src/lib.rs"',
+        "",
+      ].join("\n"));
+      write(root, "src/lib.rs", [
+        "pub struct Widget;",
+        "impl Widget {",
+        "    pub fn run(&self) -> i32 { 1 }",
+        "}",
+        "",
+      ].join("\n"));
+    },
+  },
+  {
+    id: "gopls",
+    command: "gopls",
+    sourcePath: "main.go",
+    hover: { line: 3, column: 6 },
+    setup(root) {
+      write(root, "go.mod", "module example.com/forgerelay-interop\n\ngo 1.22\n");
+      write(root, "main.go", [
+        "package interop",
+        "",
+        "type Widget struct{}",
+        "",
+        "func (Widget) Run() int { return 1 }",
+        "",
+      ].join("\n"));
+    },
+  },
+  {
+    id: "clangd",
+    command: "clangd",
+    sourcePath: "main.cpp",
+    hover: { line: 1, column: 7 },
+    setup(root) {
+      write(root, "compile_flags.txt", "-std=c++17\n");
+      write(root, "main.cpp", [
+        "class Widget {",
+        " public:",
+        "  int run() const { return 1; }",
+        "};",
+        "",
+      ].join("\n"));
+    },
+  },
+];
+
+rmSync(interopRoot, { recursive: true, force: true });
+
+let passed = 0;
+let skipped = 0;
+const failures = [];
+
+for (const fixture of fixtures) {
+  const executable = findExecutable(fixture.command);
+  if (!executable) {
+    skipped += 1;
+    console.log(`SKIP ${fixture.id}: ${fixture.command} not found on PATH; ForgeRelay does not install Language servers.`);
+    continue;
+  }
+  const preflight = probeExecutable(executable);
+  if (!preflight.available) {
+    skipped += 1;
+    console.log(`SKIP ${fixture.id}: ${executable} is present but not runnable: ${preflight.reason}`);
+    continue;
+  }
+
+  const root = join(interopRoot, fixture.id);
+  fixture.setup(root);
+  const manager = new CodeIntelligenceManager(
+    { languageServers: {} },
+    {
+      startTimeoutMs: 30_000,
+      requestTimeoutMs: 30_000,
+      shutdownTimeoutMs: 5_000,
+      idleMs: 60_000,
+      cleanupIntervalMs: 60_000,
+    },
+  );
+
+  try {
+    const symbols = await manager.run(root, {
+      operation: "documentSymbols",
+      path: fixture.sourcePath,
+      limit: 20,
+    });
+    assert.equal(symbols.operation, "documentSymbols");
+    assert.equal(symbols.selectedServer, fixture.id);
+    assert.ok(symbols.returned > 0, `${fixture.id} returned no document symbols`);
+
+    const hover = await manager.run(root, {
+      operation: "hover",
+      path: fixture.sourcePath,
+      line: fixture.hover.line,
+      column: fixture.hover.column,
+    });
+    assert.equal(hover.operation, "hover");
+    assert.equal(hover.selectedServer, fixture.id);
+
+    passed += 1;
+    console.log(
+      `PASS ${fixture.id}: ${executable} -> documentSymbols(${symbols.returned}) + hover via built-in discovery and stdio LSP.`,
+    );
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    failures.push(`${fixture.id}: ${message}`);
+    console.error(`FAIL ${fixture.id}: ${message}`);
+  } finally {
+    await manager.shutdown();
+    assert.equal(manager.stats().servicesTotal, 0, `${fixture.id} retained a Language service after shutdown`);
+  }
+}
+
+console.log(`LSP interoperability summary: ${passed} passed, ${skipped} skipped, ${failures.length} failed.`);
+if (failures.length > 0) {
+  console.error(`Interop artifacts retained at ${interopRoot}`);
+  process.exitCode = 1;
+} else {
+  rmSync(interopRoot, { recursive: true, force: true });
+}
+
+function write(root, relativePath, content) {
+  const path = join(root, relativePath);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}

package/scripts/release-parity.mjs

@@ -0,0 +1,85 @@
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const minimumNode = "22.19.0";
+const npmVersion = "11";
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const debugRoot = join(repoRoot, ".forgerelay-debug");
+const sandbox = mkdtempSync(join(ensureDirectory(debugRoot), "release-parity-node22-"));
+const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+const highRiskTests = [
+  "scripts/lsp-interop-support.test.mjs",
+  "src/lsp/language-server-config.test.ts",
+  "src/lsp/runtime/semantic-requests.test.ts",
+  "src/lsp/operations/request-hardening.server.test.ts",
+  "src/lsp/operations/recovery.server.test.ts",
+  "src/lsp/operations/lifecycle.server.test.ts",
+];
+
+try {
+  copy("package.json");
+  copy("package-lock.json");
+  copy("tsconfig.json");
+  copy("src");
+  copy("scripts");
+  copy("capabilities");
+
+  run(
+    ["--yes", "-p", `node@${minimumNode}`, "-p", `npm@${npmVersion}`, "--", "npm", "ci", "--no-audit", "--no-fund"],
+    `Node ${minimumNode} isolated npm ci`,
+    sandbox,
+  );
+
+  run(
+    [
+      "--yes",
+      `node@${minimumNode}`,
+      "--import",
+      "tsx",
+      "--test",
+      "--test-concurrency=1",
+      ...highRiskTests,
+    ],
+    `Node ${minimumNode} high-risk parity tests`,
+    sandbox,
+  );
+
+  console.log(`Release parity passed in an isolated Node ${minimumNode} sandbox.`);
+} finally {
+  rmSync(sandbox, {
+    recursive: true,
+    force: true,
+    maxRetries: 8,
+    retryDelay: 100,
+  });
+}
+
+function ensureDirectory(path) {
+  mkdirSync(path, { recursive: true });
+  return `${path}/`;
+}
+
+function copy(relativePath) {
+  cpSync(join(repoRoot, relativePath), join(sandbox, relativePath), {
+    recursive: true,
+    force: true,
+  });
+}
+
+function run(args, label, cwd) {
+  console.log(`\n== ${label} ==`);
+  const result = spawnSync(npx, args, {
+    cwd,
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    console.error(`${label} failed with exit ${result.status ?? "unknown"}.`);
+    process.exitCode = result.status ?? 1;
+    throw new Error(`${label} failed.`);
+  }
+}