release: stage v4.3.1 "Proof" (patch) — version bumps + CHANGELOG + release notes

All surfaces aligned to 4.3.1: package.json, server.json (x2), README banner +
install snippet + test badge (1128 -> 1144) + a v4.3.1 what's-new note,
docs/install.html, CHANGELOG [4.3.1] entry, docs/release-notes-4.3.1.md.

v4.3.1 bundles the two execution-swarm-audit fix commits (c8df2cd, 4c46d09) +
the earlier #90/5-bugs/docs: honest cost-digest + bench phrasing, the
incremental cross-file edge rebuild, the mtime-keyed refs cache (328ms -> ~1ms
on the reindex hot path), the MCP serverInfo version fix, doctor kill-switch
warning, gen clean error, and the 5 robustness fixes. No new features.

Ship-hygiene: tsc clean; full suite 1144/1144; e2e from the built dist confirms
the cost digest carries the "not a bill saving" caveat and bench prints
"5x LARGER" honestly; npm pack -> engramx-4.3.1.tgz, 55 files, 0 dev files;
version consistent across package.json / server.json / built CLI / MCP
serverInfo; leak-scan clean.

Gated to Nick (the publish ritual): tag v4.3.1 + push + gh release + npm publish
(2FA) + mcp-publisher republish.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: NickCirv

CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
+## [4.3.1] — 2026-06-06 — "Proof" (patch)
+
+**Why:** a two-pass execution-swarm audit (agents that *ran* engram end-to-end, not just read it)
+plus a perf self-audit hardened the 4.3.0 release. All fixes, no new features, no change to the
+honest claim. 1144 tests.
+
+### Fixed
+- **Honesty — `engram cost` digest:** the weekly digest (built for Substack/LinkedIn/Telegram) printed
+  an unqualified `Total tokens saved: … (100% reduction, ~$3.60)`. It now carries the full
+  "structural reduction, **not a bill saving** — net over prompt caching ≈ 0; USD is illustrative
+  list-price only" caveat. The cost module predated the honesty pass.
+- **Honesty — `bench`/`stats` ratio:** a packet *larger* than the relevant files printed as
+  "0.2x smaller packet" (a sub-1 ratio shown as a win). New `packetRatioPhrase()` centralises honest
+  wording across the CLI, bench, and HTTP server: "5x LARGER — engram passes through".
+- **Graph drift — incremental reindex:** single-file `reindex` / `watch` / the reindex-hook (fires on
+  every edit) deleted + re-extracted a file but never rebuilt the name-resolved cross-file `calls`
+  relation, so ranking/callers/callees drifted until the next full `init`. Now rebuilt on both the
+  index and prune paths.
+- **Perf:** that rebuild re-parsed every file on disk (~330ms on a 1k-node graph) on the hot path. An
+  mtime-keyed per-file refs cache (`file_refs_cache`) makes a single-file reindex re-parse only the
+  changed file — measured **328ms → ~1ms** warm, identical edges (equivalence-tested).
+- **MCP server:** `serverInfo.version` was hardcoded to `0.2.1` (clients/registry saw the wrong
+  version); now reads the real package version (4.3.1).
+- **`engram doctor`:** reported a green "hook active" even with the `.engram/hook-disabled` kill switch
+  set; now warns "installed but DISABLED".
+- **`engram gen --task <bad>`:** threw a raw stacktrace; now prints the clear "unknown task" message and
+  exits 1.
+- **Robustness:** grep-family Bash parser no longer mis-intercepts output-mode flags placed after the
+  pattern (`rg sym -l`/`-c`/`-A 3`); `missingHookEvents` no longer throws on a hand-edited
+  `settings.json`; Windows drive-letter paths survive `measure`'s recall set; recall bench guards
+  `trials === 0` (no `NaN%`).
+
 ## [4.3.0] — 2026-06-05 — "Proof"
 
 **Why "Proof":** this release makes engram's saving real and *provable*. `engram measure` shows the

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner-v3.png" alt="engramx — the universal context spine for AI coding tools (v4.3 'Proof')" width="100%">
+  <img src="assets/banner-v3.png" alt="engramx — the universal context spine for AI coding tools (v4.3.1 'Proof')" width="100%">
 </p>
 
 <p align="center">
@@ -58,7 +58,7 @@
   <a href="https://open-vsx.org/extension/nickcirv/engram-vscode"><img src="https://img.shields.io/open-vsx/v/nickcirv/engram-vscode?color=blue&label=OpenVSX" alt="OpenVSX engram-vscode"></a>
   <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
-  <img src="https://img.shields.io/badge/tests-1128%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1144%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/per--file%20reduction-53--89%25-orange" alt="53-89% per-file structural reduction">
   <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
   <img src="https://img.shields.io/badge/LLM%20cost-$0-green" alt="Zero LLM cost">
@@ -86,8 +86,8 @@ mkdir -p /tmp/engram-demo && cd /tmp/engram-demo && \
   echo "export const buggy = () => null;" > src.ts && \
   git add -A && git commit -q -m "feat: add buggy helper returning null causing form crashes" && \
   git revert --no-edit HEAD > /dev/null && \
-  npx --yes engramx@4.3.0 init . && \
-  npx --yes engramx@4.3.0 mistakes
+  npx --yes engramx@4.3.1 init . && \
+  npx --yes engramx@4.3.1 mistakes
 ```
 
 You should see, within 30 seconds, the **bi-temporal pre-mortem** engram auto-captured from your revert:
@@ -121,7 +121,9 @@ Works in 8 IDEs and counting — Claude Code, Cursor, Cline, Continue.dev, Aider
 
 > **v4.3 "Proof" shipped 2026-06-05 — engram's saving is now real *and provable*.** Run **`engram measure`** in your own repo to see the honest structural context-token reduction on **your** code — every disclosure computed live: it's a ceiling, here's the recall, here's the intercept rate, "structural tokens, not your bill." Run **`npm run bench:recall`** for the reproducible proof that engram surfaces the files a change actually touches (recall@10 33% on engram's own repo, decomposed honestly: candidate generation reaches 43%, the PageRank ranker adds +3.2pp over random-within-candidate; 10.4% blind chance).
 >
-> New this release: a **never-worse gate** on Grep (engram passes through whenever its packet isn't actually smaller — sized to your grep's exact `cwd`/`path`/`glob` scope), **Bash-grep interception** (the shell-only IDEs — Aider, Codex CLI, Cline — now get the call-site packet too), a **sub-agent context broker** (a tight ~100-token ranked slice into each spawned Claude Code sub-agent — the one regime prompt caching can't help), and a **compaction ledger** (a "previously read" list injected at `/compact` so the agent doesn't re-explore). Every number is a measured fact or a labelled bet — **no cost claims**; a *structural* context reduction, not a bill saving (engram's net over prompt caching ≈ 0). 1128 tests. See [CHANGELOG.md](CHANGELOG.md), `docs/COMPARISON.md` (vs the other local code-graph tools — ranking isn't unique, the *combination* is), and `docs/FRONTIER.md`.
+> New this release: a **never-worse gate** on Grep (engram passes through whenever its packet isn't actually smaller — sized to your grep's exact `cwd`/`path`/`glob` scope), **Bash-grep interception** (the shell-only IDEs — Aider, Codex CLI, Cline — now get the call-site packet too), a **sub-agent context broker** (a tight ~100-token ranked slice into each spawned Claude Code sub-agent — the one regime prompt caching can't help), and a **compaction ledger** (a "previously read" list injected at `/compact` so the agent doesn't re-explore). Every number is a measured fact or a labelled bet — **no cost claims**; a *structural* context reduction, not a bill saving (engram's net over prompt caching ≈ 0). 1144 tests. See [CHANGELOG.md](CHANGELOG.md), `docs/COMPARISON.md` (vs the other local code-graph tools — ranking isn't unique, the *combination* is), and `docs/FRONTIER.md`.
+>
+> **v4.3.1 (patch) — 2026-06-06:** a two-swarm execution audit hardened the release. Fixes: the `engram cost` digest no longer prints an unqualified dollar/"% saved" figure (it now carries the structural-not-a-bill-saving caveat); `bench`/`stats` state "Nx LARGER — passes through" instead of a backwards "0.2x smaller" on tiny repos; the incremental reindex now rebuilds cross-file `calls` edges (no graph drift between full re-indexes) **and** does so in ~1ms via an mtime-keyed refs cache instead of re-parsing every file on each edit; the MCP server reports its real version; `doctor` flags a disabled kill-switch; `gen --task <bad>` errors cleanly. No new features, no behaviour change to the honest claim.
 
 <details>
 <summary><strong>Earlier release notes (v4.2 "Loop", June 3)</strong></summary>

docs/install.html

@@ -1173,7 +1173,7 @@ <h3 class="step-title">Pull the binary from npm</h3>
           </div>
           <div class="terminal-body">
 <pre id="step-01"><span class="prompt">$</span><span class="cmd">npm install -g engramx</span>
-<span class="out-dim">↳</span> <span class="out-info">added engramx@4.2.0 in 4s</span></pre>
+<span class="out-dim">↳</span> <span class="out-info">added engramx@4.3.1 in 4s</span></pre>
           </div>
         </div>
       </article>

docs/release-notes-4.3.1.md

@@ -0,0 +1,24 @@
+# engramx v4.3.1 — "Proof" (patch)
+
+A two-pass **execution-swarm audit** — agents that actually *ran* engram end-to-end (hooks, CLI, MCP server, the graph, packaging) rather than just reading it — plus a perf self-audit, hardened the 4.3.0 release. **All fixes, no new features, no change to the honest claim.** 1144 tests.
+
+## Fixed
+
+### Honesty (the project's core discipline)
+- **`engram cost` digest** printed an unqualified `Total tokens saved: … (100% reduction, ~$3.60)` — in output literally designed to be pasted to Substack/LinkedIn/Telegram. It now carries the full *"structural reduction, **not a bill saving** — net over prompt caching ≈ 0; USD is illustrative list-price only"* caveat. (The cost module predated the honesty pass.)
+- **`bench`/`stats`** printed "0.2x smaller packet" when the packet was actually **5× larger** than the relevant files. A new shared `packetRatioPhrase()` states it honestly across CLI, bench, and the HTTP server: *"5x LARGER — engram passes through."*
+
+### Graph correctness + performance
+- **Incremental reindex drift:** single-file `reindex` / `watch` / the reindex-hook (fires on every edit) re-extracted a file but never rebuilt the name-resolved cross-file `calls` relation, so ranking / callers / callees silently drifted until the next full `init`. Now rebuilt on both the index and prune paths.
+- **Hot-path perf:** that rebuild re-parsed *every* file on disk (~330 ms on a 1k-node graph) on the per-edit hook path. An mtime-keyed per-file refs cache makes a single-file reindex re-parse only the changed file — **328 ms → ~1 ms** warm, with byte-identical edges (equivalence-tested).
+
+### Robustness
+- **MCP server** reported `serverInfo.version: "0.2.1"` (clients + the MCP registry saw the wrong version); now reads the real package version.
+- **`engram doctor`** reported a green "hook active" even with the `.engram/hook-disabled` kill switch set; now warns "installed but DISABLED."
+- **`engram gen --task <bad>`** threw a raw stacktrace; now prints the clear "unknown task" message and exits 1.
+- Grep-family Bash parser no longer mis-intercepts output-mode flags after the pattern (`rg sym -l` / `-c` / `-A 3`); `missingHookEvents` no longer throws on a hand-edited `settings.json`; Windows drive-letter paths survive `measure`'s recall set; the recall bench guards `trials === 0` (no `NaN%`).
+
+## Verified (no fix needed)
+Hook interception layer clean; all v4.3 headline features (sub-agent broker, compaction ledger, mistakes memory, grep never-worse, PageRank ranking) work E2E; security held against every injection / SQL / DoS / auth attack; npm tarball ships 55 files / 0 dev files; 4 parallel reindexes leave the graph intact; docs carry no surviving cost over-claim; public `engramx@4.3.0` smoke from npm passes.
+
+**Upgrade:** `npm i -g engramx@4.3.1` (or `npx engramx@4.3.1`). No migration; the refs cache builds itself on the next `init`/reindex.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "mcpName": "io.github.NickCirv/engram",
   "description": "The context spine for AI coding agents. 9 built-in providers + mcpConfig plugin contract (wrap any MCP server in 10 lines), generic MCP-client aggregator (stdio), pre-mortem mistake-guard, bi-temporal mistake memory, Anthropic Auto-Memory bridge, SSE streaming context packets, dual-emit AGENTS.md+CLAUDE.md. Up to ~89% per-file structural context reduction (codebase-dependent; reproducible bench included). Local SQLite, zero cloud.",
   "repository": {

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/NickCirv/engram",
     "source": "github"
   },
-  "version": "4.3.0",
+  "version": "4.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "engramx",
-      "version": "4.3.0",
+      "version": "4.3.1",
       "transport": {
         "type": "stdio"
       },