v2.8.3

## [2.8.3] - 2026-08-16

### Security

- `qmd update` no longer runs a project-local `.qmd/index.yml`'s `update:`
  commands without approval (#886). That file arrives with a `git clone` and is
  adopted automatically for any command run inside the tree, so cloning a
  repository and running `qmd update` executed shell commands chosen by whoever
  wrote it. On a terminal QMD now lists the commands and asks; with nobody to
  ask it skips them and keeps indexing. Approvals are recorded per config file
  and per command set in `<config dir>/trusted.json`, so editing a command — or
  a `git pull` that rewrites one — asks again. New `qmd trust`,
  `qmd trust list` and `qmd trust revoke` manage approvals, and
  `QMD_TRUST_UPDATE_HOOKS=1` opts unattended runs back in. Commands in your own
  `~/.config/qmd/*.yml`, including anything `qmd collection update-cmd` writes,
  are unaffected.

- The same project-local trust gate now covers collection `path` values that
  resolve outside the project and non-default `models.embed` / `models.rerank`
  / `models.generate` URIs (#889). In-project paths still index unattended;
  out-of-project directories are skipped until `qmd trust`, and custom model
  URIs are not loaded or downloaded. `QMD_TRUST_LOCAL_CONFIG=1` opts unattended
  runs back in (and `QMD_TRUST_UPDATE_HOOKS=1` still does). `qmd collection
  add` records trust as it writes, the same way `update-cmd` does.

- Indexing no longer follows file symlinks or glob `../` / absolute patterns
  out of the collection directory. `fast-glob` already skipped symlinked
  directories, but a file symlink (or a mask like `../**/*.md`) still resolved
  via `realpath` and ingested the target. `qmd://` filesystem resolution uses
  the same containment check, so `qmd://collection/../../../etc/passwd` no
  longer produces a path outside the collection.

- `qmd mcp --http` now validates the `Origin` and `Host` headers on every
  request and answers `403` when they name anything but a loopback address
  (#881). Binding to localhost is no defence against the user's own browser:
  a page can re-point its hostname at `127.0.0.1` (DNS rebinding) and read
  the indexed corpus through `POST /query` or `POST /mcp`. Requests with no
  `Origin` (curl, MCP clients, editors) are unaffected. Extend the allowlists
  with `QMD_ALLOWED_ORIGINS` / `QMD_ALLOWED_HOSTS`, or set
  `QMD_ALLOWED_ORIGINS=*` behind your own authenticating proxy. A wildcard
  bind (`--host 0.0.0.0`) skips the host check and warns at startup.

### Changed

- Dependencies: `node-llama-cpp` 3.18.1 → **3.20.0** (llama.cpp b8390 → b10361, 2026-08-11). Also safe patch/minors: `picomatch` 4.0.4 → 4.0.5, `web-tree-sitter` 0.26.8 → 0.26.12, `tsx` 4.21.0 → 4.23.12, `vitest` 3.2.4 → 3.2.7. No zod/vitest major; `@modelcontextprotocol/server` stays 2.0.0 (no 2.x patch). `flake.nix` FOD hashes are not updated here.
- `generate` and query expansion now await `LlamaContextSequence.dispose()` before disposing the parent context. node-llama-cpp 3.20 made sequence dispose async; the library's context-onDispose path does not wait.

- MCP server now speaks protocol revision **2026-07-28** via the official
  TypeScript SDK 2.x (`@modelcontextprotocol/server`). HTTP is sessionless
  (no `Mcp-Session-Id`, no initialize handshake, no idle-session TTL / #816
  reaper). Clients send version and capabilities in `_meta`; `server/discover`
  is implemented; Streamable HTTP POST requires `Mcp-Method` / `Mcp-Name`
  (mismatch → `-32020`); `tools/list` is deterministic and carries `ttlMs` /
  `cacheScope`. 2025-era stdio clients still work (`serveStdio` dual-speak);
  2025-era HTTP `initialize` is answered per-request without minting a
  session. Existing tools (`query` / `get` / `multi_get` / `status`), stdio
  EOF shutdown, and named-index daemon PIDs are unchanged. No release.

- `qmd pull` (and implicit model downloads in `embed`/`query`) no longer print
  node-llama-cpp's download progress bar. The bar redraws every few kilobytes
  and flooded agent transcripts with thousands of tokens (#776). Pass
  `qmd pull --progress` to show it on an interactive terminal.
- `--full-path` no longer degrades silently when a result cannot be resolved on
  disk (#785). A fallback there means the file moved or was deleted since the
  last index, so `search`, `query`, `get` and `multi-get` now print a notice to
  stderr naming how many results fell back and suggesting `qmd update`; stdout
  stays machine-readable.
- `search`/`query` now decide per result whether to show the docid under
  `--full-path`, matching `multi-get` and `get`: a result that resolved shows
  its on-disk path and no docid, one that did not keeps its `qmd://` URI *and*
  its docid, so it is still addressable. Previously the docid was dropped for
  every row whenever the flag was set, leaving unresolved rows with neither a
  usable path nor an identifier.
- `search --format csv` always emits the `docid` column, empty for rows that
  resolved to an on-disk path. Under `--full-path` the header previously
  dropped the column entirely — which also disagreed with the empty-result
  header, always printed with `docid`. Column positions are now stable across
  runs and formats.

### Fixed

- Concurrent first-open of a cold index no longer fails with
  `table documents_fts already exists` on Bun/macOS. FTS5
  `CREATE VIRTUAL TABLE IF NOT EXISTS` is not atomic across WAL
  connections: two processes can both see a missing table on their
  schema snapshot and the loser throws. Table create and legacy-schema
  repair now use the same `BEGIN IMMEDIATE` + double-check as the FTS
  sync triggers, and treat a concurrent "already exists" as success
  when the table is present.

- Nix flake `qmd-node-modules` FOD hashes updated for x86_64-linux and
  aarch64-darwin after the MCP SDK 2.0 bump. `nix build` / Nix GHA was
  failing with a fixed-output hash mismatch.

- CJK FTS rebuild no longer skips leftover `fts5(name, body, content='documents')`
  tables when `fts_cjk_normalized_version` is already stamped, and schema
  repair now checks live FTS columns (`PRAGMA table_info`) as well as
  `sqlite_master.sql`. The MCP HTTP test helper still seeds that legacy
  table; `startMcpHttpServer` / `createStore` on it must not throw
  `no such column: T.name` (#792 regression).

- `qmd collection add --glob` is no longer silently ignored. parseArgs ran
  with `strict: false`, so OpenClaw's `--glob memory.md` (and any other
  `--glob`) fell through, the default `**/*.md` was used, and a second
  collection on the same path collided as a duplicate instead of indexing
  the requested mask (#536). `--glob` is now an alias for `--mask`.

- The `bin/qmd` trampoline now execs `process.execPath` instead of
  re-resolving `node` from PATH. Native addons (`better-sqlite3`) are
  compiled for the Node that installed qmd; a version manager (nvm, fnm,
  mise) selecting a different major in the working directory used to spawn
  that other binary and fail with `NODE_MODULE_VERSION` / `ERR_DLOPEN_FAILED`
  (#577 leftover; #319). `bun bin/qmd` still resolves `node` from PATH so
  Node-ABI addons are not loaded into bun.

- `qmd update` / `qmd collection add` no longer swallow unreadable files
  silently (#460). `readFileSync` failures (ETIMEDOUT on APFS compressed
  files, EAGAIN, EACCES, …) still skip the file so the rest of the collection
  indexes, but the CLI now warns with the path and error code and reports
  the skip count. The SDK `update()` result includes `skipped`.

- The architecture diagram no longer draws Vec expansions into BM25 search
  (#680). `lex` expansions are FTS-only; `vec` and `hyde` expansions are
  vector-only. The original query still goes to both backends.

- `qmd bench` no longer runs to a wall of 0.00 when the fixture collection is
  missing or empty (#716). It errors up front with the same "Collection not
  found" / index hint as `qmd search -c`, and if every backend still scores
  zero it warns on stderr to check `qmd ls`.

- `qmd cleanup` now reclaims the content and FTS space left behind after a
  wrong-directory `qmd update`. Deactivating files (the next update in the
  right directory) only tombstoned the `documents` rows; cleanup deleted those
  rows and vacuumed, but never dropped the unreferenced `content` hashes and
  never ran FTS5 `optimize`, so `documents_fts_data` kept the old bodies
  (#550). Cleanup now deletes inactive docs, then orphaned content, then
  compact FTS, then vacuum. `--dry-run` reports the content hashes too.

- Concurrent `query` calls with `rerank: true` on a cold MCP server no longer
  race `ensureRerankContexts()`. Embed already serialized context creation;
  rerank did not, so two overlapping first queries both saw an empty pool,
  both created ranking contexts, and the inactivity timer disposed the loser
  (`Object is disposed`, #682). Callers now await the in-flight create.

- Embedding-context pool size no longer assumes every GGUF costs 150 MB of
  VRAM (the nomic-embed figure). Larger models such as Qwen3-Embedding-0.6B
  are ~1190 MB per 2048-token context; opening 8 of those exhausted an 8 GB
  card so `qmd query` failed with `Failed to create any rerank context` even
  though the reranker itself was fine. The pool is now sized from the weight
  file, and 1 GB is reserved for the reranker (#799). Default
  embeddinggemma/nomic throughput is unchanged. `QMD_EMBED_PARALLELISM` still
  overrides.

- Multi-collection `-c A -c B` (and SDK/MCP `collections: [A, B]`) no longer
  searches globally then post-filters. A large unrelated collection could fill
  the FTS/ANN top-k so the requested collections vanished, yielding false-empty
  results even though each collection matched on its own. `searchFTS` /
  `searchVec` now search each requested collection, then merge by score
  (#775). Single-collection exact-scan (#791, #803) is unchanged.

- Query expansion no longer consumes caller `intent`, and a cached expansion
  whose sub-queries all miss is dropped instead of replaying forever (#818).
  Intent still steers reranking and snippet/chunk selection; it just no longer
  enters the expansion prompt or cache key, where the model copied meta-language
  ("so I can compare spend settings") into lex/vec terms that matched nothing.

- Files whose names differ only in the characters the legacy slug collapsed to
  `-` (spaces, underscores) no longer evict each other from the index (#717).
  The handalized-path migration now skips any row whose path is still owned by
  a file in the current scan, so it only adopts genuinely stale pre-2.6 rows.
  `qmd get` and `qmd ls <prefix>` also match `_` and `%` in paths literally
  instead of as SQL `LIKE` wildcards, so `qmd get 2026_06_16.md` no longer
  returns a sibling `2026-06-16.md`.

- CLI `multi-get` and SDK/MCP `multi_get` now share one comma-list resolver.
  Collection-prefixed paths (`qmd/docs/SYNTAX.md`) work in both transports,
  unanchored `LIKE '%name'` no longer silently fetches a different document
  for a filename fragment (`NTAX.md` ≠ `SYNTAX.md`), and ambiguous names
  across collections error with the candidate list instead of `LIMIT 1` (#759).

- The Nix flake wrapper now seeds the same pre-import env as `bin/qmd`.
  Nix installs exec `bun src/cli/qmd.ts` directly, so they previously skipped
  the launcher: `qmd mcp` could leak llama/ggml native logs onto JSON-RPC
  stdio, and Darwin CLI exits dumped a ggml Metal residency-set stack trace
  after an otherwise successful query. The wrapper now quiets those logs for
  `mcp` and sets `GGML_METAL_NO_RESIDENCY=1` on Darwin unless
  `QMD_METAL_KEEP_RESIDENCY=1` (#723).

- Rerank context creation no longer swallows the real failure. A VRAM OOM or
  corrupt model previously produced only `Reranker unavailable — skipping
  reranking` (and a dead identical retry whose comment claimed it disabled
  flash attention, which ranking contexts never supported). The warning now
  includes the underlying message so the two cases are distinguishable (#782).

- The Nix flake package now ships `skills/` next to `src/` in `$out/lib/qmd/`.
  `findPackageRoot()` walks up from the wrapped `src/cli/qmd.ts` looking for a
  sibling `skills/` directory; without it, `qmd skill show` and `qmd skills list`
  always failed with "QMD skill not found" on Nix-installed binaries (#722).

- `/release` step 1 no longer points at a missing script. `skills/release/scripts/release-context.sh`
  now exists: it silently installs git hooks and prints version info, working-tree
  status, commits and files since the last tag, `[Unreleased]`, and the previous
  changelog entry. The skill's process list also drops the duplicate step 7 and
  checks dependency updates before cutting the release (#796).

- `store.searchVec()` (and SDK `searchVector()`) now embed the query with the
  store's pinned embed model instead of the global `QMD_EMBED_MODEL`. A store
  created with a non-default `models.embed` previously failed with
  `Dimension mismatch ... Expected N ... received M` and loaded the wrong
  (often much larger) model at query time. Hybrid/precomputed/session search
  paths were unaffected and stay unchanged (#690).

- `qmd collection add --mask "a.md,*.txt"` now indexes the union of each
  pattern. The comma-separated form was documented and commonly guessed, but
  the joined string was passed to fast-glob as one literal glob, so it
  matched zero files with no error. Brace form `{a.md,*.txt}` is unchanged.
  The same split applies on `qmd update` for stored comma-list masks (#557).

- NixOS / immutable-root installs no longer crash `qmd embed` with EACCES
  when node-llama-cpp tries to compile llama.cpp into a read-only
  `node_modules`. The flake wrapper puts Nix's glibc and libstdc++ on
  `LD_LIBRARY_PATH` so prebuilt binaries can `dlopen` them, and
  `getLlama()` uses `build: "never"` when the llama directory is not
  writable (#574).

- CJK FTS rebuild no longer raises "database is busy" when flushing insert
  batches. The streaming `.iterate()` cursor stayed open across
  `BEGIN` on the same connection; the scan now uses keyset-paginated
  `LIMIT` batches so each SELECT finalizes before the insert transaction
  starts (#797).

- Quoted FTS phrases containing dotted tokens (e.g. `"1.0.21"`) now match the
  indexed document. The porter unicode61 tokenizer stores dotted strings as
  adjacent parts, but phrase sanitization stripped the dots into a single
  token (`1021`) that could never hit. Dotted tokens inside quotes are split
  into adjacent phrase terms, matching the bare-term rewrite from #563 (#757).

- `scripts/build.mjs` no longer passes `shell: true` to `spawnSync` on Windows.
  With the default Node install path (`C:\Program Files\nodejs\node.exe`),
  `cmd.exe` split the unquoted `process.execPath` at the space, the `tsc`
  spawn failed, and `prepare` could still report success with no `dist/` —
  leaving `bin/qmd` at "not built". The helper always receives a real binary
  path plus an args array, so no shell is needed. A spawn error now prints
  the missing binary path instead of failing silently. (#681)

- Case-sensitive collections no longer collapse distinct document identities that
  differ only by path casing. The implicit `COLLATE NOCASE` legacy migration was
  unsafe for filesystems that contain both `README.md` and `readme.md`; case-only
  legacy migrations must now be explicit and operator-reviewed (#801).

- `cleanupOrphanedVectors` now runs its orphan count and both DELETEs in a
  single immediate transaction. An interruption between the two DELETEs
  (crash, `SQLITE_BUSY`) could desync `vectors_vec` from `content_vectors`,
  leaving stale metadata rows that make a later reactivation of the same
  content hash look already-embedded — so `qmd embed` skips it and the
  document becomes silently unsearchable by vector, with no orphan left to
  clean up (#766).

- `qmd embed` no longer splits a UTF-16 surrogate pair (emoji, etc.) across a
  chunk boundary. A chunk ending or starting mid-pair produced an unpaired
  surrogate in the chunk text, which some remote embedding APIs reject as
  invalid JSON — permanently failing that chunk on every retry, since the
  boundary calculation is deterministic. This covers both the character-based
  chunker and `chunkDocumentByTokens`'s recursive re-splitting for
  astral-plane-dense content, which could previously drive the char budget
  low enough to reproduce the same split (#777).

- `insertContext` looks up `store_collections` by name. #754 retargeted the
  query from the dropped `collections` table but left `WHERE id = ?`, and
  `store_collections` has `name TEXT PRIMARY KEY` with no `id` column — the
  call threw `no such column: id`. Matches `deleteContext` /
  `updateStoreContext` (#853).

- `qmd collection add` with no path argument now errors with usage instead of
  silently indexing the current working directory (#684). Pass `.` to index
  CWD, matching the documented examples.

- `qmd status` reports orphaned embedding chunks, `qmd update` hints when they
  exceed 10% of vectors, and `qmd cleanup --dry-run` previews what would be
  removed. Incremental update still does not auto-prune vectors (a transient
  empty mount would otherwise force a full re-embed) (#768).

- `qmd --index <name> mcp --http --daemon` now scopes PID/log files per index
  (`mcp-<name>.pid`) and passes the resolved database path to the child, so a
  named-index daemon no longer collides with the default `mcp.pid` or opens
  the default store (#772).

- Opening a store no longer throws `SQLiteError: no such column: T.name` when
  `documents_fts` is still the legacy `fts5(name, body, content='documents')`
  schema. `CREATE VIRTUAL TABLE IF NOT EXISTS` left that table in place, and
  the CJK FTS rebuild's `DELETE FROM documents_fts` compiled against
  `documents.name`, which does not exist (#792).

- Rerank cache keys now include the resolved `models.rerank` URI, so swapping
  the configured reranker no longer serves the previous model's cached scores
  (#764).

- `vsearch -c <collection>` no longer returns empty results for small
  collections crowded out of the global ANN candidate pool. `searchVec` now
  exact-scans the collection's vectors with `vec_distance_cosine` when the
  set is within 20k rows (ANN + post-filter cannot see collections that never
  enter global top-k, and sqlite-vec caps `k` at 4096 so a larger multiplier
  alone is not enough). Larger collections still use capped ANN over-fetch
  (#791, #803).

- `multi-get --format files` now emits the docid as its own CSV field
  (`#docid,path,...`) instead of prepending it into the path field with a
  space (`#docid path,...`), matching `search --format files` and keeping
  naive comma-splitting usable (#760).

- `qmd embed` now takes an exclusive process lock (`.qmd-embed.lock` next to
  the index DB) so concurrent invocations no longer race on `vectors_vec`
  and fail with `UNIQUE constraint failed: vectors_vec.hash_seq`. A second
  embed exits early with `Another embed process is already running. Skipping.`
  Stale locks from crashed processes are recovered via PID identity checks
  (#825).

- windows prepare fix #778 keeps dist build #824

- `qmd mcp` (stdio) now shuts down gracefully when stdin reaches EOF instead
  of orphaning to PID 1 when the parent MCP client dies (#751): the server
  closes its transport, gives in-flight request handlers a bounded window to
  settle, closes the store (which disposes its llama.cpp instance), and lets
  the process drain via `process.exitCode` (no forced `process.exit()`, which
  has caused exit-time native crashes before).

- `qmd --version` no longer reports an unrelated repository's commit (#787).
  The commit was discovered at runtime with `git -C <installDir> rev-parse`,
  and `git -C` walks *up*, so any install nested inside another checkout
  reported that checkout's HEAD — a global npm install under a git-managed
  prefix such as Homebrew's `/opt/homebrew` claimed Homebrew's commit as
  qmd's. Identical tarballs reported different "commits" depending only on
  where they were installed, which is why one issue can collect three distinct
  hashes for the same published build. `scripts/build.mjs` now stamps the
  commit it built from into `dist/cli/build-info.json` (suffixed `-dirty` when
  built from a modified tree), and the runtime prefers that. Source checkouts
  still resolve their own HEAD, but only after confirming the enclosing
  repository is qmd's; anything else reports no commit rather than a
  misleading one. The lookup also no longer interpolates the install path into
  a shell string, so a path containing a space stops silently dropping the
  commit, and `--version` from a build runs no subprocess at all.

- `qmd doctor` no longer false-positives `.etag` HTTP sidecars (written by
  `qmd pull` next to each download) as invalid GGUF models. The model-cache
  check now only inspects real `.gguf` files, so a sidecar that happens to
  sort before the blob no longer poisons the report. #812

- `qmd mcp stop` and `qmd mcp --http --daemon` now verify that a pidfile PID still belongs to a qmd process before signalling it or refusing to start. Recycled PIDs (common after reboot) are treated as stale: the pidfile is unlinked instead of SIGTERM'ing an unrelated process or blocking daemon start with a false "Already running" error (#806).

- `qmd collection add` now rejects missing paths and regular files before
  creating collection configuration or index state. The error reports both the
  received and resolved path so malformed shell arguments can be corrected.

- Claude Code plugin: scope the plugin `source` to `./skills` so installs
  copy just the skills (~50 KB) instead of the entire repository. Previously a
  canonical install materialized ~230 MB / 9,000+ items into
  `~/.claude/plugins/cache/` — including a full npm dependency install
  triggered by the repo-root `package.json`. Both skills (`qmd` and `release`)
  still ship, unchanged. (#790)

- Claude Code plugin: releases now bump the plugin version in
  `.claude-plugin/marketplace.json` in lockstep with `package.json`. The
  plugin cache is keyed on this version, and it had been stuck at `0.1.0`
  since February — so installed plugins never received skill updates
  (users who installed in February are still being served that snapshot
  today, despite the qmd skill nearly tripling in size since). Also bumps
  the plugin to `2.6.3` as a one-time catch-up so existing installs pick
  up the current skill on their next `claude plugin update`. (#789)

### Changed

- `--full-path` no longer degrades silently when a result cannot be resolved on
  disk (#785). A fallback there means the file moved or was deleted since the
  last index, so `search`, `query`, `get` and `multi-get` now print a notice to
  stderr naming how many results fell back and suggesting `qmd update`; stdout
  stays machine-readable.
- `search`/`query` now decide per result whether to show the docid under
  `--full-path`, matching `multi-get` and `get`: a result that resolved shows
  its on-disk path and no docid, one that did not keeps its `qmd://` URI *and*
  its docid, so it is still addressable. Previously the docid was dropped for
  every row whenever the flag was set, leaving unresolved rows with neither a
  usable path nor an identifier.
- `search --format csv` always emits the `docid` column, empty for rows that
  resolved to an on-disk path. Under `--full-path` the header previously
  dropped the column entirely — which also disagreed with the empty-result
  header, always printed with `docid`. Column positions are now stable across
  runs and formats.