v0.13.0-beta.2

Beta for 0.13.0 on npm next (npm install -g engramgraph@next). latest stays 0.12.0 until this beta has been tested.

Replaces 0.13.0-beta.1 — please upgrade if you installed it.

Fixed in beta.2

• MCP: an unexpected error no longer loses its message. In beta.1 the MCP server's shared error handler called itself for any error other than "not in the graph" or "graph busy" and overflowed the stack; the caller read Right-hand side of 'instanceof' is not an object instead of the cause. It now answers isError with the original message.

Everything in beta.1 is still here: the five fixes from the 0.12.0 Windows 11 report, including exit codes that changed from 0 to 1 for a name the graph does not contain — read "Changed" in the CHANGELOG before upgrading a script.

Full details: CHANGELOG.md.

v0.13.0-beta.1

Beta for 0.13.0 on npm next (npm install -g engramgraph@next). latest stays 0.12.0 until this beta has been tested.

Fixes for the five problems in the 0.12.0 Windows 11 report (XSPEC-457).

⚠️ Exit codes changed — read before upgrading a script

These were 0 and are now 1 when the name is not in the graph: egr callers / callees (symbol), egr impact / implementers (spec id), egr implemented-by (path matching no module, or several), egr feedback (missing node), egr related (missing id). (none) with exit 0 now always means "it is in the graph and has no results". A write command's own lock failure now also ends in exit 1.

Fixed

• A running MCP server no longer blocks terminal egr commands — MCP opens the graph per query, read-only, and closes it.
• A write command checkpoints before exiting, so nothing is left for the next open to replay.
• egr doctor says whether this machine needs network, from where the ALGO extension would actually come from.
• egr callers X for an X the graph does not contain says so instead of printing (none).
• egr index --exclude <glob> (repeatable), and the summary reports what it kept out.

Full details: CHANGELOG.md.

v0.12.0

Moves latest from 0.11.0. Highlights:

• Two egr processes touching one graph no longer destroy it — query commands and the MCP server hold the graph read-only (XSPEC-374).
• The algorithm extension installs with the package on Windows x64, Linux x64 and macOS — god-nodes, communities, related work offline. (extension.ryugraph.io currently refuses connections, so on 0.11.0 these commands fail even with internet access.)
• C, Swift and Bash support; unsupported files are now reported instead of silently skipped.
• An existing graph no longer stops opening after the extension file moves.

Verified on Windows (hosted runner, no C++ toolchain, extension download host blocked) by .github/workflows/windows-release-verify.yml.

---

Release candidates rc.1–rc.5 shipped on npm next between 2026-08-11 and 2026-09-18; entries below marked (rc.N) arrived in that candidate. Verified on Windows by .github/workflows/windows-release-verify.yml — hosted Windows, no C++ toolchain, the ALGO download host blocked.

Two egr processes touching one graph did not refuse each other — they destroyed it.

Every command opened the graph for writing, even a pure query, because opening runs initSchema. The engine is single-writer, and writer-versus-writer is not a clean refusal: measured on a real graph, one process wins, the rest are refused, and the database is left answering Trying to create a vector with ANY type to everything afterwards. It is unrecoverable except by rebuilding, and the message says nothing about what happened.

This was reachable in ordinary use. An editor's MCP server holds the graph for as long as the editor is open; a post-commit hook or a shell-startup freshness check indexes in the background; you run egr in a terminal. Any two of those overlapping was enough.

Added

• C, Swift and Bash (rc.5) (XSPEC-414 R2–R4). Functions, structs/unions/enums, and #include-derived module relationships for C; functions, classes/structs/enums/protocols and extensions (attributed to the type they extend, including across files) for Swift; function definitions, calls and source/.-derived module relationships for Bash, with external commands (grep, echo, ...) never entering the graph. egr doctor now lists all three. .h routes to C++ when the same indexing run has a C++ source file alongside it, and to C otherwise (previously always C++).

• egr index follows an extension-less shebang script (rc.5) (#!/bin/bash, #!/usr/bin/env sh, XSPEC-414 R4) and indexes it as Bash, instead of counting it as an unsupported file.

• A new IMPORTS (Module → Module) relationship (rc.5), resolved from C's #include and Bash's source/. against the files in the same indexing run; egr index's summary and --json output report the count.

• The algorithm extension installs with the package (rc.4). god-nodes, communities and related need ryugraph's ALGO extension, which until now was downloaded from extension.ryugraph.io on first use — so on a network that cannot reach it they did not work at all. It now ships prebuilt as @asiaostrich/engramgraph-algo-<platform>, an optional dependency npm installs only on the matching platform, and loads from there with no network and nothing written to your home directory. Platforms: Windows x64, Linux x64, macOS arm64 and x64. Linux arm64 is not included: ryugraph's own linux-arm64 engine file is currently an x86-64 binary (predictable-labs/ryugraph#48), so there is nothing correct to build against. Everywhere else, the download still works as before.

• egr index names what it skipped (rc.4). Files with an extension no grammar handles are counted and reported by extension in the summary and in --json (unindexedCode), instead of silently lowering the file count.

• egr index says what to do next (rc.4) when most calls did not resolve (points at --scip) and when documents were found but none were recognised as specs or none are implemented in code (states the naming rule and the // implements comment).

Fixed

• An existing graph could stop opening at all after the extension file moved (rc.4). Loading the extension writes its absolute path into the graph's write-ahead log, which is replayed on every open; egr exits without a checkpoint, so the record stayed. After a Node version switch, a reinstall, or a cleared ~/.ryu, every command on that graph — including ones that never use the extension — failed with Failed to load library. 0.11.0's download path had the same defect. egr now checkpoints right after loading. A graph already in that state opens again once the file is back at the path in the error.
• MCP index_code parsed files with no grammar as JavaScript (rc.4), producing plausible and wrong nodes. They are now skipped and reported.
• Git-branch isolation followed the caller's GIT_DIR (rc.4) instead of the directory it was given, whenever one was set in the environment — as it is inside every git hook.
• --help and the CLI docs state that the skip list is fixed and .gitignore is not read (rc.4); the help text is generated from the list itself.

Changed

• Query commands open read-only — callers, callees, implementers, implemented-by, impact, top, blindspots, signatures. (god-nodes, communities and related were on this list in rc.2 and are not: they load the algorithm extension and build a projected graph first, and both are writes. Corrected in rc.3; this entry was not.) A read-only open can be refused; refusal is all it can do. Measured: five concurrent read-only opens all succeed and the graph is intact; a writer and a reader refuse each other cleanly with the graph intact; only writer-versus-writer corrupts.
• The MCP stdio server holds the graph read-only. Held for writing, it made every terminal egr command fail for as long as the editor was open. Verified end-to-end: with the server running, top, implementers, blindspots and a full egr index all work.
• index_code, index_docs and ingest_feedback over MCP now refuse by name and point at the CLI equivalent, rather than failing at a lower layer with a lock error an assistant cannot act on.
• Read-only openGraph neither creates nor migrates. Both are writes. A missing graph now says so and names egr index, instead of silently producing an empty one.

v0.12.0-rc.5

Release candidate for 0.12.0 on npm next. latest stays 0.11.0 until the Windows verification passes.

Added in rc.5

• C, Swift and Bash (rc.5) (XSPEC-414 R2–R4). Functions, structs/unions/enums, and #include-derived module relationships for C; functions, classes/structs/enums/protocols and extensions (attributed to the type they extend, including across files) for Swift; function definitions, calls and source/.-derived module relationships for Bash, with external commands (grep, echo, ...) never entering the graph. egr doctor now lists all three. .h routes to C++ when the same indexing run has a C++ source file alongside it, and to C otherwise (previously always C++).
• egr index follows an extension-less shebang script (rc.5) (#!/bin/bash, #!/usr/bin/env sh, XSPEC-414 R4) and indexes it as Bash, instead of counting it as an unsupported file.
• A new IMPORTS (Module → Module) relationship (rc.5), resolved from C's #include and Bash's source/. against the files in the same indexing run; egr index's summary and --json output report the count.

Known limitations: bin/ is in the fixed skip list, so shebang scripts placed there are not indexed; Bash calls made at a script's top level (outside any function) are not attributed; Swift initializers all share the name init. Coverage measurements: docs/CROSS-FILE-COVERAGE.md.

Everything since 0.11.0 (including rc.4's offline algorithm extension): CHANGELOG.md

v0.12.0-rc.4

Release candidate for 0.12.0 on npm next. latest stays 0.11.0 until the Windows verification passes.

Network note: as of 2026-09-17 extension.ryugraph.io is not accepting connections, so on 0.11.0 the algorithm commands fail even with internet access. rc.4 installs the extension with the package on Windows x64, Linux x64 and macOS.

Added

• The algorithm extension installs with the package (rc.4). god-nodes, communities and related need ryugraph's ALGO extension, which until now was downloaded from extension.ryugraph.io on first use — so on a network that cannot reach it they did not work at all. It now ships prebuilt as @asiaostrich/engramgraph-algo-<platform>, an optional dependency npm installs only on the matching platform, and loads from there with no network and nothing written to your home directory. Platforms: Windows x64, Linux x64, macOS arm64 and x64. Linux arm64 is not included: ryugraph's own linux-arm64 engine file is currently an x86-64 binary (predictable-labs/ryugraph#48), so there is nothing correct to build against. Everywhere else, the download still works as before.
• egr index names what it skipped (rc.4). Files with an extension no grammar handles are counted and reported by extension in the summary and in --json (unindexedCode), instead of silently lowering the file count.
• egr index says what to do next (rc.4) when most calls did not resolve (points at --scip) and when documents were found but none were recognised as specs or none are implemented in code (states the naming rule and the // implements comment).

Fixed

• An existing graph could stop opening at all after the extension file moved (rc.4). Loading the extension writes its absolute path into the graph's write-ahead log, which is replayed on every open; egr exits without a checkpoint, so the record stayed. After a Node version switch, a reinstall, or a cleared ~/.ryu, every command on that graph — including ones that never use the extension — failed with Failed to load library. 0.11.0's download path had the same defect. egr now checkpoints right after loading. A graph already in that state opens again once the file is back at the path in the error.
• MCP index_code parsed files with no grammar as JavaScript (rc.4), producing plausible and wrong nodes. They are now skipped and reported.
• Git-branch isolation followed the caller's GIT_DIR (rc.4) instead of the directory it was given, whenever one was set in the environment — as it is inside every git hook.
• --help and the CLI docs state that the skip list is fixed and .gitignore is not read (rc.4); the help text is generated from the list itself.

Full changelog for the 0.12.0 cycle: CHANGELOG.md

v0.12.0-rc.3 — read-only list had three writers in it

Supersedes 0.12.0-rc.2, which shipped a read-only command list with three
writing commands in it.

god-nodes, communities and related install the algo extension and build a
projected graph before they can rank anything — both are writes. related is
also an MCP tool, and the stdio server is read-only by design, so an assistant
calling it received a lock error from the engine.

It passed its tests because related returns early on an unknown seed id, and
every case written for it used one. The write path was never exercised.

Fixed, and the class with it: every entry in the read-only set is now executed
against a real read-only connection on a populated graph, with its keys taken
from the set itself. A writing command added there fails the suite.

Still the same thing to verify on Windows: run egr index . with Claude Code
open, then query. Two writers used to corrupt the graph; queries now open
read-only and coexist.

v0.12.0-rc.2 — queries open read-only (concurrent use no longer corrupts the graph)

[0.12.0] — 2026-08-11

Two egr processes touching one graph did not refuse each other — they destroyed it.

Every command opened the graph for writing, even a pure query, because opening runs initSchema. The engine is single-writer, and writer-versus-writer is not a clean refusal: measured on a real graph, one process wins, the rest are refused, and the database is left answering Trying to create a vector with ANY type to everything afterwards. It is unrecoverable except by rebuilding, and the message says nothing about what happened.

This was reachable in ordinary use. An editor's MCP server holds the graph for as long as the editor is open; a post-commit hook or a shell-startup freshness check indexes in the background; you run egr in a terminal. Any two of those overlapping was enough.

Changed

• Query commands open read-only — callers, callees, implementers, implemented-by, impact, top, god-nodes, communities, related, blindspots, signatures. A read-only open can be refused; refusal is all it can do. Measured: five concurrent read-only opens all succeed and the graph is intact; a writer and a reader refuse each other cleanly with the graph intact; only writer-versus-writer corrupts.
• The MCP stdio server holds the graph read-only. Held for writing, it made every terminal egr command fail for as long as the editor was open. Verified end-to-end: with the server running, top, implementers, blindspots and a full egr index all work.
• index_code, index_docs and ingest_feedback over MCP now refuse by name and point at the CLI equivalent, rather than failing at a lower layer with a lock error an assistant cannot act on.
• Read-only openGraph neither creates nor migrates. Both are writes. A missing graph now says so and names egr index, instead of silently producing an empty one.

v0.12.0-rc.1 — queries open read-only (concurrent use no longer corrupts the graph)

[0.12.0] — 2026-08-11

Two egr processes touching one graph did not refuse each other — they destroyed it.

Every command opened the graph for writing, even a pure query, because opening runs initSchema. The engine is single-writer, and writer-versus-writer is not a clean refusal: measured on a real graph, one process wins, the rest are refused, and the database is left answering Trying to create a vector with ANY type to everything afterwards. It is unrecoverable except by rebuilding, and the message says nothing about what happened.

This was reachable in ordinary use. An editor's MCP server holds the graph for as long as the editor is open; a post-commit hook or a shell-startup freshness check indexes in the background; you run egr in a terminal. Any two of those overlapping was enough.

Changed

• Query commands open read-only — callers, callees, implementers, implemented-by, impact, top, god-nodes, communities, related, blindspots, signatures. A read-only open can be refused; refusal is all it can do. Measured: five concurrent read-only opens all succeed and the graph is intact; a writer and a reader refuse each other cleanly with the graph intact; only writer-versus-writer corrupts.
• The MCP stdio server holds the graph read-only. Held for writing, it made every terminal egr command fail for as long as the editor was open. Verified end-to-end: with the server running, top, implementers, blindspots and a full egr index all work.
• index_code, index_docs and ingest_feedback over MCP now refuse by name and point at the CLI equivalent, rather than failing at a lower layer with a lock error an assistant cannot act on.
• Read-only openGraph neither creates nor migrates. Both are writes. A missing graph now says so and names egr index, instead of silently producing an empty one.

v0.11.0 — an agent can now ask what is missing

[0.11.0] — 2026-08-11

An agent could be told the answer might be incomplete, and had no way to ask what was missing.

indexHealth.possiblyIncomplete has been attached to MCP query results since 0.8.0, but the three commands that answer the follow-up question — blindspots, signatures, doctor — existed only in the CLI. So an assistant receiving that flag could relay it to a human and stop. Surfacing health to a machine consumer is pointless if the next question has no tool.

Added

• blindspots (MCP) — files that parsed partially or failed, from the parse-health manifest. The natural follow-up to indexHealth.possiblyIncomplete. Carries manifestPresent, because blindspots: [] alone cannot distinguish "nothing wrong" from "nothing was ever measured".
• signatures (MCP) — the same files grouped by root cause rather than listed one by one; turns "584 files" into "1 problem".
• doctor (MCP) — which languages are available and why any are not, what was compiled on this machine, which commands need network. Does not open the graph, so it still answers when indexing itself is what is broken.

Started without a manifestPath, blindspots and signatures return an explicit error saying so — not an empty success. A tool that cannot see must not return the same shape as a tool that looked and found nothing.

v0.10.1 — both fixes are for damage 0.10.0 did

[0.10.1] — 2026-08-11

Both fixes here are for damage 0.10.0 did, and both were found by the person it was released for.

Fixed

• egr was unusable on Windows for anyone with an existing graph. 0.10.0 adds a column to three tables, so the first open migrates — and the migration backed up the database file while the engine still held it open, failing with EBUSY: resource busy or locked, read and leaving zero-byte backups. backup.ts had already switched to openSync for Windows share flags after an earlier EBUSY … copyfile report; that was necessary and insufficient, because share flags decide who may open a file and do not defeat a byte-range lock the engine holds. The migration now closes the connection before copying and reopens afterwards. If the backup fails for any other reason, the message names the database, the pending columns, the cause, and two ways out — instead of five words.

• The warning built to prevent noise emitted thirty-one lines of it. The unresolved-prefix warning fired against a skills library whose files are named topic-first (language-options.md, bdd-workflow.md, testing-pyramid.md) — none meant to be a spec, and the specs it exists to find were already indexed correctly. Artifact id conventions are near-universally upper case; topic naming is lower case. Matching the prefix case-sensitively took that repository from 31 warnings to 2, both of them real. Samples are de-duplicated (one run reported the same filename three times, being three directories deep), and at most three clusters are reported.

  Trade-off on the record: a project naming specs Spec-Login.md now gets no hint. Under-reporting is the right failure — one missed hint costs a search, thirty-one spurious ones cost the reader's attention permanently, including for the warning that would have mattered.