v3.8.6

Added

• CodeBuddy AI platform support (#423) — CodeBuddy joins Claude Code / Codex
  as a first-class agent: detection, init / setup / uninstall, MCP wiring
  at ~/.codebuddy/mcp.json, dedicated rules injection, and the same path-jail
  protection as .claude / .codex (~/.codebuddy in IDE_CONFIG_DIRS, the
  broad-root guard, and the home/agent-dir checks). Thanks @studyzy.
• Structure-first cold reads (structure_first, #361) — an opt-in bias (off
  by default; env LEAN_CTX_STRUCTURE_FIRST) for auto to prefer map on a
  cold read of a medium-sized source file. It is the one read saving that
  survives a phase-isolated harness (no warm-session re-read to amortise a full
  read) and is capability-safe: the active-diagnostic / edit-fail / small-file
  guards still force full.
• gain now reports net-of-injection bill impact (#361) — lean-ctx gain
  (and gain --json) surface the observed proxy turns, the total injected
  overhead (per-turn tax × turns) and net_tokens_saved (which can go negative
  and says so), so the meter reconciles to the provider bill instead of a
  tool-local ratio. The proxy persists its request count to make this honest.
• Faithful benchmark arm config (#361) — bench/agent-task/r2/ ships a
  zero-injection, capability-safe lean-ctx arm (rules_injection=off, minimal
  tool profile, structure_first, proxy on with cache-aware pruning) plus the pi
  extension config and proxy env wiring, so an independent benchmark runs
  lean-ctx "installed = running as designed".

Changed

• Suspect files are never compressed away on a fix task (#361) — when the
  task text explicitly names a file (e.g. "fix the sort in versioncmp.c"), auto
  now forces full for that file ahead of any compression-favouring intent, so
  the agent always gets the body it needs to localise and edit the defect.
• The proxy protects build/test fidelity and foreign tools (#361) — a
  generic/foreign shell tool_result that looks like a build failure or test run
  is preserved verbatim at the wire (compiler errors, panics and test summaries
  kept intact), and vendor-prefixed tools (forge_read, pi.shell, …) are now
  classified by name segment so a foreign source read is protected and a foreign
  shell log is compressed. Request-body compression is deterministic, keeping the
  provider prompt-cache prefix byte-stable.
• The pi extension can route shell through ctx_shell (#361) — a new
  routeShell opt-in (env LEAN_CTX_PI_ROUTE_SHELL, implied by replace mode)
  suppresses the native bash builtin so build/test/log output is compressed and
  metered (lossless for signal), while the read/list/search builtins stay
  available alongside ctx_*.

Fixed

• [archive] could exhaust host RAM and force a reboot (#417) — archived
  tool outputs (.txt + .meta.json + SQLite FTS) were written on every large
  call, but the configured max_disk_mb / max_age_hours limits were never
  enforced: archive::cleanup() had no production caller and the FTS cap deleted
  only DB rows, orphaning the (much larger) .txt blobs. The store therefore
  grew unbounded on disk and starved the host of RAM via the page cache.
  cleanup() now enforces both the age TTL and the on-disk size budget, prunes
  the content files and FTS index together (no more orphans), runs at MCP start
  and periodically off the hot path, and lean-ctx cache prune reclaims the
  archive too.
• doctor reported the proxy as broken on Windows (#416) — proxy autostart
  has no backend on Windows, so doctor treated its absence as a hard failure
  (a permanent 27/28). The proxy check is now platform-aware: a reachable proxy
  is green, an unreachable proxy on a platform without autostart is a warning
  (run lean-ctx proxy start), and "running but autostart not installed" is a
  warning rather than a failure on macOS/Linux.
• setup reported compression settings it never saved (#415) — the wizard
  printed "✓ Compression: …" before writing and swallowed the write error, so a
  failed save still looked successful. Success (and the rules-prompt injection)
  is now reported only after the config is actually persisted. doctor also
  displayed "power" for an unpinned install; it now correctly reports
  "lean (default)".
• A data dir split across two trees could not be merged (#414) — when both a
  legacy (~/.lean-ctx) and an XDG tree held a stats.json, the old migration
  bailed and doctor pointed at lean-ctx setup instead of doctor --fix.
  doctor --fix now consolidates every non-canonical data tree into the
  canonical one (newer file wins, never clobbering a newer copy) before the XDG
  split, the hint points to the right command, and $XDG_DATA_HOME/lean-ctx is
  included in split detection.
• JetBrains plugin now ships as a downloadable GitHub Release asset (#418) —
  the plugin .zip is built and attached to every release. It was missing from
  v3.8.5 because the plugin's Release Asset job only ran on release events,
  which a GITHUB_TOKEN-created release never triggers. The plugin version is now
  single-sourced in gradle.properties and mirrors the engine release via
  -Pversion=<tag>, so it can no longer drift (it had been stuck at 3.8.3).
• The wake-up briefing listed dead and foreign agents (#419) — ctx_overview
  read the raw AgentRegistry, so it showed peers from crashed or exited MCP
  processes (and from other projects). It now prunes stale entries
  (cleanup_stale) and scopes the list to the current project root, matching
  what ctx_agent list and the dashboard already do.
• ctx_read map/signatures served pre-rebuild output (#420) — lean-ctx graph build --force and lean-ctx index build-full only dropped the in-process graph
  cache, but a running daemon kept serving stale map/signatures from its
  long-lived SessionCache in another process. Both commands now also flush the
  daemon's read cache over IPC (never auto-starting one), so derivations
  re-derive on the next read.
• ctx_multi_read ignored auto mode (#421) — batch reads forced
  auto→full, so every file came back fully expanded regardless of the active
  profile. ctx_multi_read now honours auto like a single ctx_read, resolving
  the optimal mode per file. Tool descriptions, schemas and the injected rules
  (bumped to v12) now steer agents to omit mode (= auto) and reserve full
  for the read immediately before an edit.
• ctx_semantic_search was hidden in the default profile (#422) — the
  meaning-based search tool was categorised under Memory and absent from the
  lean core set, so it never appeared in the default ("lean") gate. It is now a
  Core tool and part of the advertised core surface; the setup/doctor tool counts
  are derived dynamically instead of a hard-coded "13".
• A cold read could cost more tokens than the raw file (#361) — an
  independent benchmark measured ctx_read auto-mode payloads up to +21.6%
  larger than the source on a small codebase: on a tiny file the one-line
  framing header (file ref + deps/exports summary) is net overhead that only
  amortises across re-reads, and the CLI one-shot path used a divergent resolver
  that lacked the small-file guard. ctx_read now enforces a hard anti-inflation
  invariant — a read never returns more tokens than the raw file. When
  framing would exceed the bare content (auto-resolved or full reads) the file
  is shipped verbatim, so a read is break-even at worst and a win whenever a
  compressed mode or cached re-read applies; an explicitly requested view
  (map/signatures/lines:) is always honoured untouched. The same guarantee
  now covers the additive one-shot CLI path, which also routes through the
  unified auto-mode resolver. Re-reads are unaffected (the cache keys on path and
  re-derives the file ref). Follow-up: map mode no longer repeats exports the
  API: section already lists with full signatures — the same symbols were
  emitted twice (once as a bare exports: line, once in API:). A shared
  exports_not_in_signatures helper now drives the MCP, CLI and benchmark map
  renderers, so every export is shown exactly once (re-exports/const aliases the
  API can't capture still surface) and the scorecard measures the deduped output
  agents actually receive.
• A knowledge store could grow to 2× its fact cap on import (#417) —
  remember() hard-caps a project's facts at max_facts, but the bulk
  import_facts() path still used the old max_facts * 2 guard, so a
  merge/import could inflate a store to twice its budget before any eviction
  fired (observed live as a doctor capacity CRIT, e.g. facts 232/200). The
  import path now runs the memory lifecycle as soon as it exceeds max_facts,
  draining the excess by importance (archived, not lost). The eviction invariant
  now holds on every write path (remember, import, persist-merge).
• Knowledge stores for deleted projects accumulated forever (#615) — a store
  at knowledge/<hash>/ is keyed to a project_root; when that root is deleted
  (a removed git worktree, a thrown-away project) the store can never be written
  again, so its eviction cap can never self-heal and it lingers as pure disk
  bloat (one such store surfaced live as a permanent doctor capacity CRIT).
  lean-ctx doctor now reports orphaned stores and the reclaimable size,
  lean-ctx cache prune reclaims them (alongside BM25/graph/archive), and
  doctor --fix prunes them as part of a repair. Detection is conservative — a
  store with an empty (legacy/global) root or a still-existing root is never
  touched, and only the explicit prune commands delete (never the background
  lifecycle), so a temporarily-unmounted drive can't trigger data loss.
• auto_update_mcp = false was ignored by the hooks-layer MCP writers (#281)
  — the hooks integration still registered and rewrote MCP server entries even
  when auto_update_mcp was disabled, contradicting the setting's contract. The
  hooks-layer writers now honour the flag on every path, so a user who opts out
  of automatic MCP registration is respected (the proxy/daemon paths already
  did).

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: v3.8.6...v3.8.6