Merge origin/main into fix-issue1727-1729

Author: Widthdom

DEVELOPER_GUIDE.md

@@ -224,6 +224,14 @@ Do not add mutable static caches, shared `StringBuilder` instances, reused `Matc
 
 `status --check` keeps the DB/worktree checksum comparison in `IndexFreshnessChecker`, but the user-facing age hint threshold is resolved in `QueryCommandRunner`: CLI `--stale-after <duration>` wins over `CDIDX_STALE_AFTER`, which wins over `.cdidxrc.json`'s `stale_after`, then the 24-hour default. Supported duration suffixes are `m`, `h`, and `d`. JSON output includes `stale_after_seconds` and `index_age_seconds` only for `--check`, so clients can confirm which threshold was applied without inferring it from text.
 
+### Workspace version pinning
+
+On startup, `cdidx` walks up from the current directory looking for `.cdidx-version`. The first non-empty line is treated as the required CLI version for that workspace. A mismatch prints a warning and continues by default; `--strict-version` or `CDIDX_STRICT_VERSION=1` turns the mismatch into exit code `64` (`EX_USAGE`). This check is advisory and does not rewrite the file. Use it to keep teams on the same binary when index contracts or query behavior differ between releases.
+
+### Release freshness and upgrade checks
+
+`cdidx --check-updates` and `cdidx status --check-updates` query the GitHub latest-release endpoint through `UpdateChecker`, using the same 24-hour cache and `CDIDX_DISABLE_UPDATE_CHECK=1` opt-out as the `--version` hint. `cdidx upgrade --check-only` reuses that check. `cdidx upgrade` is intentionally a thin wrapper around the signed release installer: it downloads `install.sh`, verifies the current binary directory is writable, sets `CDIDX_INSTALL_DIR` to that directory, and runs the installer for the latest release.
+
 ### Degradation reason codes
 
 Readiness degradation reason codes are centralized in `DegradationReasonCodes`. Add new codes there with human text, a recommended action, and an alternative action before emitting them from readers, CLI, or MCP payloads.

README.md

@@ -118,7 +118,20 @@ file completion.
 | Drift checks | `cdidx diff <db1> <db2>` compares schema, file, symbol, and reference deltas with stable exit codes: `0` identical, `1` drift, `2` schema mismatch, `3` unreadable DB. |
 | Extensibility and feedback | Post-extraction hooks from `~/.config/cdidx/hooks/*.dll` or `CDIDX_HOOKS_DIR` can enrich symbols and references. `cdidx suggestions` lists, inspects, and exports local suggestion history, with fuzzy MCP suggestion deduplication controlled by CLI, env, or `.cdidxrc.json`. |
 | Language coverage | 78 detected languages, with symbol and graph support where available. |
-| Updates | `cdidx --version` checks GitHub releases at most once per day and appends a newer-release hint when one is available. Set `CDIDX_DISABLE_UPDATE_CHECK=1` to suppress the check. |
+| Updates | `cdidx --version` checks GitHub releases at most once per day and appends a newer-release hint when one is available. Use `cdidx --check-updates` or `cdidx status --check-updates` for an explicit freshness check, and `cdidx upgrade` to reinstall the latest GitHub release via `install.sh`. Set `CDIDX_DISABLE_UPDATE_CHECK=1` to suppress checks. |
+
+### Upgrade and uninstall
+
+`cdidx upgrade --check-only` reports whether a newer GitHub release is available. `cdidx upgrade` downloads the current `install.sh`, refuses unwritable install directories, and reruns the installer with `CDIDX_INSTALL_DIR` pointed at the current binary directory.
+
+Direct `install.sh` installs can be removed with:
+
+```bash
+bash ./install.sh --uninstall
+bash ./install.sh --uninstall --purge-cache
+```
+
+The uninstaller removes files placed next to the `cdidx` binary and can optionally remove `~/.cache/cdidx`. It does not remove project `.cdidx/` directories, shell profile PATH edits, shell completion scripts, Homebrew installs, or .NET global-tool installs.
 
 The documented `status --json` trust contract covers these fields:
 

changelog.d/unreleased/1700.fixed.md

@@ -0,0 +1,15 @@
+---
+category: fixed
+issues:
+  - 1700
+affected:
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+---
+
+## English
+
+- **Out-of-range query numeric flags now fail closed (#1700)** — numeric options such as `--depth 999999999` return usage errors instead of being silently coerced or clamped.
+
+## 日本語
+
+- **範囲外の query 数値フラグを fail-closed にしました (#1700)** — `--depth 999999999` のような数値 option は silent な補正や clamp ではなく usage error を返します。

changelog.d/unreleased/1705-1801.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 1705
+  - 1801
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+---
+
+## English
+
+- **Unknown query flags now fail closed (#1705, #1801)** — query commands reject unknown dash-prefixed tokens unless the user explicitly passes them after `--`.
+
+## 日本語
+
+- **未知の query flag を fail-closed にしました (#1705, #1801)** — query command は、ユーザーが明示的に `--` の後ろへ置いた場合を除き、未知の dash 始まり token を拒否します。

changelog.d/unreleased/1732.added.md

@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 1732
+affected:
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - src/CodeIndex/Mcp/McpToolDefinitions.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+---
+
+## English
+
+- **Added MCP `countOnly` probing for large result sets (#1732)** — `search`, `references`, `callers`, `callees`, and `impact_analysis` can now return count metadata plus a small top-file histogram without row payloads.
+
+## 日本語
+
+- **大きな結果セット向けに MCP `countOnly` プローブを追加しました (#1732)** — `search`、`references`、`callers`、`callees`、`impact_analysis` が、行 payload を返さずに件数 metadata と小さな top-file histogram を返せるようになりました。

changelog.d/unreleased/1744.added.md

@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 1744
+affected:
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - README.md
+---
+
+## English
+
+- **Added `cdidx upgrade` for release self-upgrades (#1744)** — `upgrade` checks GitHub release freshness, supports `--check-only`, refuses unwritable install directories, and reruns the signed `install.sh` installer for the latest release.
+
+## 日本語
+
+- **リリース自己更新用の `cdidx upgrade` を追加しました (#1744)** — `upgrade` は GitHub release の鮮度を確認し、`--check-only` をサポートし、書き込み不能なインストール先を拒否したうえで最新リリース向けに署名済み `install.sh` を再実行します。

changelog.d/unreleased/1745.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 1745
+affected:
+  - src/CodeIndex/Mcp/McpServer.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+---
+
+## English
+
+- **MCP tool responses now have a server-wide byte ceiling (#1745)** — oversized responses fail with structured `response_too_large` metadata instead of being serialized and written unbounded.
+
+## 日本語
+
+- **MCP ツール応答にサーバー全体の byte 上限を追加しました (#1745)** — 過大な応答は無制限に直列化・書き込みされず、構造化された `response_too_large` metadata を持つエラーになります。

changelog.d/unreleased/1748.added.md

@@ -0,0 +1,18 @@
+---
+category: added
+issues:
+  - 1748
+affected:
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/UpdateChecker.cs
+  - README.md
+---
+
+## English
+
+- **Added explicit update checks (#1748)** — `cdidx --check-updates` and `cdidx status --check-updates` now use the cached GitHub latest-release check so operators can ask for version freshness without running an upgrade.
+
+## 日本語
+
+- **明示的な更新確認を追加しました (#1748)** — `cdidx --check-updates` と `cdidx status --check-updates` がキャッシュ付き GitHub latest-release 確認を使うようになり、upgrade せずにバージョン鮮度を確認できます。

changelog.d/unreleased/1750.added.md

@@ -0,0 +1,16 @@
+---
+category: added
+issues:
+  - 1750
+affected:
+  - install.sh
+  - README.md
+---
+
+## English
+
+- **Added installer uninstall mode (#1750)** — `install.sh --uninstall` removes files installed next to the `cdidx` binary and `--purge-cache` can also remove the per-user cdidx cache, while documenting what remains manual.
+
+## 日本語
+
+- **インストーラーに uninstall モードを追加しました (#1750)** — `install.sh --uninstall` は `cdidx` バイナリ横に配置されたファイルを削除し、`--purge-cache` ではユーザー単位の cdidx キャッシュも削除できます。手動で残るものも明示します。

changelog.d/unreleased/1752.added.md

@@ -0,0 +1,16 @@
+---
+category: added
+issues:
+  - 1752
+affected:
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Added workspace version pin warnings (#1752)** — `.cdidx-version` now warns when the running CLI version differs from the workspace pin, and `--strict-version` / `CDIDX_STRICT_VERSION=1` can turn the mismatch into exit code 64.
+
+## 日本語
+
+- **ワークスペースのバージョン固定警告を追加しました (#1752)** — `.cdidx-version` と実行中 CLI のバージョンが異なる場合に警告し、`--strict-version` / `CDIDX_STRICT_VERSION=1` で不一致を exit code 64 にできます。