feat: fetch a per-platform engine and add a JetBrains IDE client

[anvanster]

Intent

The developer was driving CodeGraph 0.20.0 to release: a new JetBrains plugin plus a distribution change where all three clients (npm, VS Code, JetBrains) fetch a single per-platform engine from a GitHub release instead of bundling four binaries. Before rebuilding and publishing, they explicitly asked to fix two outstanding bugs found earlier: task #14, where adding bin/** to .vscodeignore dropped the static embedding model so CODEGRAPH_STATIC_MODEL pointed at a path that no longer ships, and task #15, an MCP crash loop where unknown or duplicated arguments made the engine exit 2 via clap before emitting telemetry, causing MCP clients to respawn forever (656k PostHog events from ~134 machines). They then instructed running the work through the no-mistakes gate and pushing to GitHub, noting the gh login had been switched to anvanster so publishing was unblocked, followed by a fresh rebuild of all four platform binaries to include the crash fixes. Standing constraints from their global instructions applied throughout: push only through the no-mistakes gate rather than directly to origin, never hand-edit auto-generated files like CHANGELOG.md, and no commits or pushes without an explicit request.

What Changed

• Engine distribution moved from bundling four platform binaries in every client to fetching one per-platform binary from a GitHub release: new fetch-engine download/verify path in the npm wrapper, engineDownload.ts in the VS Code extension, and EngineDownloader/EngineInstaller/CodeGraphServerResolver in the new JetBrains plugin, with publish-release-assets.sh and stamp-binary.sh publishing and provenance-stamping the assets and each client pinning the engine version per channel. Workspace version bumped to 0.20.0.
• Added a JetBrains IDE plugin (jetbrains/) as a thin LSP client - Symbols and Memories tool windows, graph panel, code vision, status bar widget, MCP registration for AI tooling, telemetry gate/reporter, crash breadcrumbs and a restart circuit breaker - and extended the VS Code extension with an activity bar view, CodeLens, hover, onboarding walkthrough and zero-file/first-index funnel recovery.
• Fixed the MCP crash loop where the wrapper passed a duplicate --mcp flag and the engine exited 2 through clap before reporting: the wrapper now de-duplicates its own flags, explains exit 2, and trips a persistent crash-loop breaker; CODEGRAPH_STATIC_MODEL is no longer pointed at the unbundled bin/ directory. Engine-side, the server now terminates on the LSP exit notification, initializes the workspace from rootUri/rootPath when workspaceFolders is absent, sweeps stale crash breadcrumbs, and stops discarding store errors.

Risk Assessment

⚠️ Medium: Every round-1 finding is correctly resolved and I found no new defects, but the branch remains a ~11k-line distribution rewrite whose principal failure mode — release assets that are unpublished, mistagged or stale — lives outside the diff and is guarded only by the (now-hardened) publish script's pin and manifest checks.

Testing

I exercised both bugs the release was blocked on at the surface an end user actually touches. For the MCP crash loop I staged the base-commit wrapper and the fixed wrapper over the real 0.20.0 engine and ran the exact invocation that was looping (codegraph-mcp --mcp): the old wrapper reproduces clap's "cannot be used multiple times" and exit 2, the fixed one completes the MCP handshake and lists 42 tools, and a genuinely bad flag now prints the assembled argument list and stops reporting after the third identical failure in a minute. For the static-model bug I drove codegraph_memory_store/codegraph_memory_search with --embedding-model static both ways: pointed at the VSIX bin/ directory that .vscodeignore removed, the vector engine fails to initialize and both tools return "Memory manager not initialized"; unset, the engine resolves the shared ~/.codegraph copy, reports "VectorEngine ready (jina-code-static-256, 256d, static)", and the stored memory comes back from search. The targeted automated suites (wrapper-args, fetch-engine, and the new server.spawnEnv vitest guard) all pass, and I mutation-tested the new guard by reintroducing the pre-fix default to confirm it fails, then reverted it. No screenshots: this round's changes are process-argument and spawn-environment behaviour with no rendered surface, so the reviewer-visible artifact is the CLI/JSON-RPC transcript. One gap worth knowing: the JetBrains mirror of the static-model rule reads correctly but has no runnable guard here, since its suite needs the IntelliJ SDK and network - that is the same gap already raised and closed for the VS Code side. Telemetry was disabled and a scratch HOME used throughout, so no events were sent and no state was written outside temp; the worktree is clean.

Evidence: MCP crash loop: before/after transcript with the real 0.20.0 engine

client config: { "command": "codegraph-mcp", "args": ["--mcp"] } ----- BEFORE (wrapper at base commit 06bcc88) ----- error: the argument '--mcp' cannot be used multiple times Usage: codegraph-server-darwin-arm64 [OPTIONS] $? = 2 <- clap rejects the duplicate before any telemetry; the MCP client respawns into the identical failure, forever ----- AFTER (wrapper at 91cc406) ----- initialize -> {"name":"codegraph","version":"0.20.0"} tools/list -> 42 tools, e.g. codegraph_get_dependency_graph, codegraph_get_call_graph, codegraph_analyze_impact, codegraph_get_ai_context $? = 0 <- the wrapper drops the flags it owns, the engine starts and serves ----- AFTER: an argument the engine really does reject is now explained, and the loop is broken ----- attempt 3: error: unexpected argument '--not-a-real-flag' found codegraph-mcp: the engine rejected its arguments and exited 2. arguments: --mcp --not-a-real-flag This is a configuration problem, not a crash. Check the "args" in your MCP client config - the wrapper already supplies --mcp. codegraph-mcp: failed 3 times in under a minute with the same arguments. Not reporting further failures for this configuration.

CodeGraph 0.20.0 - task #15: MCP crash loop from a duplicated --mcp flag
engine: codegraph-server 0.20.0   client config: { "command": "codegraph-mcp", "args": ["--mcp"] }

----- BEFORE (wrapper at base commit 06bcc88) -----
error: the argument '--mcp' cannot be used multiple times

Usage: codegraph-server-darwin-arm64 [OPTIONS]

For more information, try '--help'.
$? = 2   <- clap rejects the duplicate before any telemetry; the MCP client respawns into the identical failure, forever

----- AFTER (wrapper at 91cc406) -----
initialize -> {"name":"codegraph","version":"0.20.0"}
tools/list -> 42 tools, e.g. codegraph_get_dependency_graph, codegraph_get_call_graph, codegraph_analyze_impact, codegraph_get_ai_context
$? = 0   <- the wrapper drops the flags it owns, the engine starts and serves

----- AFTER: an argument the engine really does reject is now explained, and the loop is broken -----
attempt 1:
  error: unexpected argument '--not-a-real-flag' found
  
  Usage: codegraph-server-darwin-arm64 --mcp
  
  For more information, try '--help'.
  
  codegraph-mcp: the engine rejected its arguments and exited 2.
    arguments: --mcp --not-a-real-flag
    This is a configuration problem, not a crash. Check the "args" in
    your MCP client config - the wrapper already supplies --mcp.
attempt 2:
  error: unexpected argument '--not-a-real-flag' found
  
  Usage: codegraph-server-darwin-arm64 --mcp
  
  For more information, try '--help'.
  
  codegraph-mcp: the engine rejected its arguments and exited 2.
    arguments: --mcp --not-a-real-flag
    This is a configuration problem, not a crash. Check the "args" in
    your MCP client config - the wrapper already supplies --mcp.
attempt 3:
  error: unexpected argument '--not-a-real-flag' found
  
  Usage: codegraph-server-darwin-arm64 --mcp
  
  For more information, try '--help'.
  
  codegraph-mcp: the engine rejected its arguments and exited 2.
    arguments: --mcp --not-a-real-flag
    This is a configuration problem, not a crash. Check the "args" in
    your MCP client config - the wrapper already supplies --mcp.
  codegraph-mcp: failed 3 times in under a minute with the same
    arguments. Not reporting further failures for this configuration.

Evidence: Static embedding model: memory tools broken vs working

engine: codegraph-server 0.20.0 | VS Code setting codegraph.embeddingModel = "static" ----- BEFORE: CODEGRAPH_STATIC_MODEL=<extensionPath>/bin/jina-code-static-256 (that directory is gone - bin/** is excluded from the VSIX) ----- codegraph_memory_store -> Error: Failed to store memory: Other("Memory manager not initialized") codegraph_memory_search -> Error: Memory search failed: Other("Memory manager not initialized") engine log: VectorEngine initialization failed: Model("read config.json: No such file or directory (os error 2)") ----- AFTER (91cc406): CODEGRAPH_STATIC_MODEL left unset unless the user names a directory ----- codegraph_memory_store -> {"id":"571bc1c9-b488-4001-be72-2295fd0ec3ba","status":"stored", ...} codegraph_memory_search -> {"results":[{"content":"parse_config reads the JSON configuration file","kind":"convention","score":0.375554 ... engine log: VectorEngine ready (jina-code-static-256 (256d, static), 256d, static)

CodeGraph 0.20.0 - task #14: .vscodeignore bin/** dropped the static embedding model
engine: codegraph-server 0.20.0  |  VS Code setting codegraph.embeddingModel = "static"
user surface exercised: the codegraph_memory_* tools, which are backed by the static vector engine

----- BEFORE: extension exports CODEGRAPH_STATIC_MODEL=<extensionPath>/bin/jina-code-static-256 -----
        (that directory is gone - bin/** is excluded from the VSIX)
  codegraph_memory_store  -> Error: Failed to store memory: Other("Memory manager not initialized")
  codegraph_memory_search -> Error: Memory search failed: Other("Memory manager not initialized")
  engine log: VectorEngine initialization failed: Model("read config.json: No such file or directory (os error 2)")

----- AFTER (91cc406): extension leaves CODEGRAPH_STATIC_MODEL unset unless the user names a directory -----
        (engine resolves ~/.codegraph/static_models/jina-code-static-256, where the npm postinstall puts it)
  codegraph_memory_store  -> {"id":"571bc1c9-b488-4001-be72-2295fd0ec3ba","status":"stored","warning":"Workspace has only 2 nodes — it may not be indexed yet. Run codegraph_reindex_workspace for full code intelligence (typically 
  codegraph_memory_search -> {"results":[{"content":"parse_config reads the JSON configuration file","created_at":"2026-08-09T02:42:26.141019+00:00","id":"571bc1c9-b488-4001-be72-2295fd0ec3ba","kind":"convention","score":0.375554
  engine log: VectorEngine ready (jina-code-static-256 (256d, static), 256d, static)

Evidence: Mutation check: the new guard fails when the regression is reintroduced

Mutation check: reintroduce the pre-fix default (<extensionPath>/bin/jina-code-static-256) in vscode/src/server.ts ❯ src/server.spawnEnv.test.ts (5 tests | 2 failed) × does not point CODEGRAPH_STATIC_MODEL at a bundled path the VSIX no longer ships × leaves an inherited CODEGRAPH_STATIC_MODEL alone rather than clearing it AssertionError: expected '/ext/bin/jina-code-static-256' to be undefined (reverted afterwards; git status --porcelain clean, guard back to 5 passed)

Mutation check: reintroduce the pre-fix default (<extensionPath>/bin/jina-code-static-256) in vscode/src/server.ts


 RUN  v4.1.2 /Users/anvanster/.no-mistakes/worktrees/b8216ba13cd2/01KZJ46XN25EFMSEHDM538ZDM4/vscode

 ❯ src/server.spawnEnv.test.ts (5 tests | 2 failed) 4ms
     × does not point CODEGRAPH_STATIC_MODEL at a bundled path the VSIX no longer ships 2ms
     × leaves an inherited CODEGRAPH_STATIC_MODEL alone rather than clearing it 1ms

⎯⎯⎯⎯⎯⎯⎯ Failed Tests 2 ⎯⎯⎯⎯⎯⎯⎯

 FAIL  src/server.spawnEnv.test.ts > engineSpawnEnv > does not point CODEGRAPH_STATIC_MODEL at a bundled path the VSIX no longer ships
AssertionError: expected '/ext/bin/jina-code-static-256' to be undefined

- Expected:
undefined

+ Received:
"/ext/bin/jina-code-static-256"

 ❯ src/server.spawnEnv.test.ts:33:44
     31|         const env = engineSpawnEnv(config({ embeddingModel: 'static' }…
     32|
     33|         expect(env.CODEGRAPH_STATIC_MODEL).toBeUndefined();
       |                                            ^
     34|     });
     35|

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/2]⎯

 FAIL  src/server.spawnEnv.test.ts > engineSpawnEnv > leaves an inherited CODEGRAPH_STATIC_MODEL alone rather than clearing it
AssertionError: expected '/ext/bin/jina-code-static-256' to be '/from/the/users/shell' // Object.is equality

Expected: "/from/the/users/shell"
Received: "/ext/bin/jina-code-static-256"

 ❯ src/server.spawnEnv.test.ts:59:44
     57|         });
     58|
     59|         expect(env.CODEGRAPH_STATIC_MODEL).toBe('/from/the/users/shell…
       |                                            ^
     60|     });

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (19m19s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 5 issues found → auto-fixed ✅

• ⚠️ scripts/publish-release-assets.sh:130 - set -euo pipefail is active, so a grep that finds nothing inside a command substitution aborts the script before its own diagnostic runs. Line 70 (pin="$(grep -m1 'ENGINE_VERSION = "' ... | sed ...)") and line 130 (recorded="$(grep -F " $bin" "$MANIFEST" 2>/dev/null | ... )") are both plain assignments in statement position, so a failed grep propagates through pipefail and terminates the run. The ${pin:-<not found>} and NOT STAMPED messages, and the whole guidance block below them, are unreachable in exactly the cases they were written for. Since every channel now depends on this release existing, the operator gets a bare exit 1 instead of the instructions telling them what to stamp or rebuild. Fix: pin="$(... || true)" (or || pin='') on both, matching the fallbacks already coded.
• ⚠️ mcp-package/test/wrapper-args.test.js:28 - LOOP_STATE is computed from the real os.homedir() and the test unlinks it three times (lines 116, 129, 140) plus lets the wrapper write to it. Running npm test therefore destroys any genuine crash-loop state in ~/.codegraph/mcp-failures.json, and the breaker assertion silently depends on the developer's real home being writable — recordFailure returns 1 on a write failure, so on a read-only or sandboxed HOME the "breaker engages within three identical failures" check fails for an unrelated reason. Every other resource in this test is already isolated in mkdtempSync. Fix: point HOME (and USERPROFILE for Windows) at a temp dir in the spawnSync env and compute LOOP_STATE from that same dir.
• ℹ️ scripts/package-npm.sh:46 - The pre-pack gate runs only node test/fetch-engine.test.js. package.json now defines "test": "node test/fetch-engine.test.js && node test/wrapper-args.test.js", and wrapper-args.test.js is the regression guard for the duplicated---mcp collision that produced 656k crash events — the exact defect this release fixes. Packaging can currently succeed with that guard failing. Fix: run npm test here, or add the second file to the same subshell.
• ℹ️ mcp-package/bin/postinstall.js:68 - Both comments state that codegraph-mcp resolves the engine "from its own bin directory and nowhere else", and the user-facing failure advice only names the bin path. findBinary() (bin/codegraph-mcp.js:171) now honours CODEGRAPH_SERVER_PATH — that was made to work in this same branch. The air-gapped/offline failure messages omit the one mechanism just fixed for that case, so a user hitting the retry path is steered away from the supported option. Fix: mention CODEGRAPH_SERVER_PATH=<engine> alongside the bin path in both messages and drop the stale "nowhere else" claim.
• ℹ️ jetbrains/src/main/kotlin/ai/codegraph/jetbrains/telemetry/TelemetryReporter.kt:164 - dispose() calls sender.awaitTermination(2, SECONDS) on a project-level service, which IntelliJ disposes on the EDT during project close. With TIMEOUT_MS = 5_000 on both connect and read, an in-flight POST to an unreachable PostHog endpoint blocks project close for the full 2 seconds. The comment immediately above already establishes that the thread is a daemon and cannot keep the IDE alive, which is the reason the wait is not needed. Fix: sender.shutdownNow() without the await.

🔧 Fix: harden release scripts, isolate wrapper test, unblock EDT dispose
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found → auto-fixed ✅

• ⚠️ vscode/src/extension.ts:380 - The VS Code half of the static-model fix (vscode/src/extension.ts:380 - only set CODEGRAPH_STATIC_MODEL when the user names a directory) has no executable regression guard. vscode/vitest.config.ts documents that the private @vsforge test harness the extension suite depends on is permanently lost, and vscode/package.json still declares file:../vsforge/packages/@vsforge/* dependencies that do not exist in the repo, so npm install and therefore vitest cannot run here at all. The equivalent JetBrains change needs the IntelliJ SDK and network. I verified the user-visible outcome end-to-end at the engine boundary instead (both env conditions, real engine), and the change itself by reading the diff, but nothing will catch a future regression in the client-side wiring. Worth a decision on whether to rebuild a minimal vscode mock for this path.
• node mcp-client-sim.js <pkg> 3 against the base-commit wrapper + real codegraph-server 0.20.0 - reproduced the exit-2 --mcp cannot be used multiple times respawn loop
• node mcp-client-sim.js <pkg> 1 against the target-commit wrapper - MCP initialize returns serverInfo codegraph 0.20.0, exit 0
• node bin/codegraph-mcp.js --mcp --bogus x4 with the real engine - exit-2 explanation, argument echo, and crash-loop breaker at the 3rd failure; inspected ~/.codegraph/mcp-failures.json
• node static-model-probe.js with CODEGRAPH_STATIC_MODEL=<extensionPath>/bin/jina-code-static-256 - engine logs VectorEngine initialization failed: read config.json: No such file or directory, codegraph_memory_search returns Memory manager not initialized
• node static-model-probe.js with CODEGRAPH_STATIC_MODEL unset - engine resolves ~/.codegraph/static_models/jina-code-static-256, logs VectorEngine ready, memory search responds
• node test/wrapper-args.test.js in mcp-package (9 checks)
• node test/fetch-engine.test.js in mcp-package (28 checks)
• Checked engine version pins: Cargo.toml 0.20.0 vs mcp-package/bin/fetch-engine.js and jetbrains/.../CodeGraphServerResolver.kt - all match
• git status --porcelain - worktree left clean, no transient artifacts

🔧 Fix: add regression guard for static model spawn env
✅ Re-checked - no issues remain.

• node mcp-package/test/wrapper-args.test.js - 9 assertions on flag de-duplication, exit-2 diagnostics and the crash-loop breaker
• node mcp-package/test/fetch-engine.test.js - engine asset/platform resolution for the unbundled distribution
• npx vitest run src/server.spawnEnv.test.ts (in vscode/) - the new engineSpawnEnv guard, 5 tests
• Mutation check: reintroduced the pre-fix <extensionPath>/bin/jina-code-static-256 default in vscode/src/server.ts, confirmed 2 of the 5 guard tests fail, then reverted (worktree verified clean via git status --porcelain)
• Manual end-to-end MCP repro: staged the base-commit (06bcc88) wrapper and the fixed (91cc406) wrapper side by side over the real codegraph-server 0.20.0 binary and ran the previously-looping invocation codegraph-mcp --mcp with a JSON-RPC initialize + tools/list on stdin
• Manual crash-loop breaker check: three consecutive codegraph-mcp --not-a-real-flag spawns, observing the exit-2 explanation each time and the breaker message on the third
• Manual static-model repro: ran the engine in MCP mode with --embedding-model static and exercised codegraph_memory_store / codegraph_memory_search, once with CODEGRAPH_STATIC_MODEL pointed at the no-longer-shipped VSIX bin/ directory and once with it unset

⚠️ **Document** - 1 info

• ℹ️ docs/troubleshooting.md:55 - Placement judgment call left for the author: the MCP crash-loop fix introduces user-visible state and output that no user document names - the persistent failure counter at ~/.codegraph/mcp-failures.json, the "engine rejected its arguments and exited 2" message, and the new mcp.crashloop telemetry event. The wrapper-owned-flags half is now covered in mcp-package/README.md (the owner of npm wrapper usage), which should stop users hitting it at all. The remaining state file and diagnostics would fit a "MCP server keeps restarting" section in docs/troubleshooting.md, but that document is currently scoped entirely to VS Code indexing, so widening it is a scope decision rather than a stale fact.

⚠️ **Lint** - 3 issues (1 warning, 2 infos)

• ⚠️ vscode/package.json:1 - npm run lint in vscode/ fails outright: eslint 8.57.1 finds no configuration file, and no .eslintrc*/eslint.config.* has ever existed in the repo (confirmed at both 06bcc88 and 91cc406). This change adds or rewrites ~13 TypeScript files (engineDownload.ts, funnel.ts, codeLensProvider.ts, server.ts, extension.ts, telemetry/*), none of which have been linted. Authoring a config is a judgment call, not a mechanical fix, so it is left for the author: a flat config with @typescript-eslint (already a devDependency) would be the minimum. tsc --noEmit passes, so this is a lint-coverage gap, not a type error.
• ℹ️ crates/codegraph-go/src/visitor.rs:1 - cargo fmt --all -- --check reports drift in ~60 files across the parser crates (codegraph-go, -c, -swift, -perl, -memory, -harness and others), roughly 250 hunks. None of them are touched by this change, and every Rust file that is touched is already rustfmt-clean. Running cargo fmt --all would be mechanical and safe but would bury the 0.20.0 release diff in unrelated churn, so it is left as a follow-up for a standalone style commit.
• ℹ️ crates/codegraph-server/src/domain/unused_code.rs:17 - clippy reports 22 pre-existing warnings in codegraph-server (the whole find_unused_code module is dead code; BODY_PREFIX_MAX_CHARS is an unused import in 13 parser crates; two map_or/redundant-closure nits in mcp/server.rs). git blame puts all of them before the base commit, and none sit on a line this change touched, so they are reported rather than fixed here.

✅ **Push** - passed

✅ No issues found.

[github-actions]

🔍 CodeGraph PR Review

105 files changed (+11192/−546, 363 functions) · Risk: 🔴 high

Blast radius

548 direct callers affected (455 breaking) across CodeGraph/crates/codegraph-dockerfile, CodeGraph/crates/codegraph-fortran, CodeGraph/crates/codegraph-kotlin, CodeGraph/crates/codegraph-toml, CodeGraph/crates/codegraph-verilog

⚠️ Test gaps (256 functions, 0 coverage)

• start_file_watcher (crates/codegraph-server/src/backend.rs) — body_changed
• shutdown (crates/codegraph-server/src/backend.rs) — body_changed
• handle_memory_invalidate (crates/codegraph-server/src/backend.rs) — body_changed
• handle_memory_update (crates/codegraph-server/src/backend.rs) — body_changed
• handle_get_curated_context (crates/codegraph-server/src/backend.rs) — body_changed
• handle_memory_store (crates/codegraph-server/src/backend.rs) — body_changed
• handle_memory_search (crates/codegraph-server/src/backend.rs) — body_changed
• handle_memory_stats (crates/codegraph-server/src/backend.rs) — body_changed
• handle_mine_git_history_for_file (crates/codegraph-server/src/backend.rs) — body_changed
• memory_manager (crates/codegraph-server/src/backend.rs) — signature_changed
• …and 246 more

Suggested reviewers

Andrey Vasilevsky (442 lines), anvanster (3 lines)

_{Suggested commit: feat(codegraph-dockerfile): <describe the change> · 183 tests cover the changes
🤖 Generated by CodeGraph}