release: v1.108.193 - the size cap can be raised, and a withheld file cannot prove absence

Both reported by @dkiaulakis, measured on 1.108.188. Every line he
cited verified before the fix: 5 for 5.

The size cap was the one limit of three with no way to move it. Its
neighbours each had a resolver reading config; it had none, appeared
in none of the 79 JCODEMUNCH_* variables, was not among
index_folder()'s 11 parameters, and was passed from line 1490 as a
hardcoded constant. New security.get_max_file_size(), same shape as
its siblings. The default stays at 500KB - the ask was an escape
hatch, not a higher default.

The finding underneath the ask is the larger half. His sentence:
"Size is the one exclusion reason where the file is real, current,
and wanted."

Worse than reported. too_large is refused during discovery, so the
file never reaches files_accepted, and the 1.108.176 completeness
reconciliation balances perfectly because the refused file is outside
both numbers. Coverage reported complete: true over a corpus missing a
real, current, wanted source file. The contract was answering a
question about the walk while presenting the answer as being about the
tree.

Exclusions now split: excluded (the corpus being defined - binary,
gitignore, wrong_extension, never candidates, must still permit
absence) versus withheld (real source refused by our own limits -
too_large, file_limit, unreadable). Withheld makes complete false and
refuses absence, with a refusal that names the cause and the remedy
rather than the generic partial message.

Existing indexes will start reporting complete: false after a re-index
if they withheld anything. That is the contract reporting something
true it was previously hiding.

test_watcher_memory_cache.py corrected: it set a low cap by patching
DEFAULT_MAX_FILE_SIZE, which the resolver no longer consults, so the
patch silently did nothing and the fast path indexed an oversize file.
It now sets the config value. The failure proved the fast path honours
the new route end to end.

Tests: 6204 passed, 7 skipped (excl. the known 12 local-ONNX env
failures). New tests/test_v1_108_193.py (15).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.193] - 2026-07-27 - the size cap can be raised, and a withheld file cannot prove absence
+
+Both reported by @dkiaulakis, measured on 1.108.188. The ask was small. The
+finding underneath it was not.
+
+### Added
+
+- **`JCODEMUNCH_MAX_FILE_SIZE` / `max_file_size`.** The per-file size cap was
+  the one limit of three with no way to move it. Its neighbours
+  `DEFAULT_MAX_INDEX_FILES` and `DEFAULT_MAX_FOLDER_FILES` each had a resolver
+  reading config; the size cap had none, appeared in none of the 79
+  `JCODEMUNCH_*` variables, was not among `index_folder()`'s 11 parameters, and
+  was passed from `index_folder.py:1490` as a hardcoded constant. All five
+  points verified before the fix.
+
+  New `security.get_max_file_size()`, same shape as its siblings.
+  ⚠ **The default is unchanged at 500KB.** The ask was an escape hatch, not a
+  higher default, and 500KB still protects the common case from a parse worth
+  less than it costs.
+
+### Fixed
+
+- ⚠ **A file refused for size no longer lets the corpus call itself complete.**
+  His sentence, which is the actual finding: *"Size is the one exclusion reason
+  where the file is real, current, and wanted."*
+
+  Worse than reported. `too_large` is refused during **discovery**, so the file
+  never reaches `files_accepted`, and the 1.108.176 completeness reconciliation
+  balances perfectly because it compares what the walk accepted against what got
+  indexed — the refused file is outside **both** numbers. Coverage reported
+  `complete: true` over a corpus missing a real, current, wanted source file.
+  The contract was answering a question about the walk while presenting the
+  answer as being about the tree.
+
+  Exclusions now split in two:
+
+  - **excluded** — the corpus being defined. A `.png` is `binary`, a vendored
+    tree is `gitignore`, a lockfile is `wrong_extension`. Never candidates. A
+    search over this can still prove absence, and **must**, or no real
+    repository could prove anything.
+  - **withheld** — real source, current, wanted, refused by one of *our* limits:
+    `too_large`, `file_limit`, `unreadable`. Any of these makes `complete` false,
+    and a zero-result over such a corpus cannot prove absence.
+
+  The refusal names the cause and the remedy, separately from the generic
+  `partial` message, because they send a reader to different places: "the index
+  did not cover the whole tree" sends them to inspect their repo, while naming
+  `too_large` sends them to a setting.
+
+  ⚠ **Existing indexes will start reporting `complete: false` after a re-index
+  if they withheld anything, and affected absence claims degrade.** That is the
+  contract reporting something true it was previously hiding, not a regression.
+
+### Tests
+
+- New `tests/test_v1_108_193.py` (15), including the boundary that keeps the
+  signal useful: structural exclusions alone must still permit absence.
+- ⚠ `tests/test_watcher_memory_cache.py` corrected. It set a low cap by patching
+  `DEFAULT_MAX_FILE_SIZE`, which the resolver no longer consults, so the patch
+  silently did nothing and the watcher fast path indexed an oversize file. It
+  now sets the config value, which exercises the override a user actually has —
+  a stronger test than before, and the failure is what proved the fast path
+  honours the new route end to end.
+
+No tool-count, INDEX_VERSION or schema change.
+
 ## [1.108.192] - 2026-07-27 - #377 P3: one immutable snapshot, start to finish
 
 The two edges @mightydanp pinned adversarially on #377 after reviewing

CLAUDE.md

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.192"
+version = "1.108.193"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

pyproject.toml

@@ -23,6 +23,7 @@
     "JCODEMUNCH_USE_AI_SUMMARIES": "use_ai_summaries",
     "JCODEMUNCH_TRUSTED_FOLDERS": "trusted_folders",
     "JCODEMUNCH_TRUSTED_FOLDERS_WHITELIST_MODE": "trusted_folders_whitelist_mode",
+    "JCODEMUNCH_MAX_FILE_SIZE": "max_file_size",
     "JCODEMUNCH_MAX_FOLDER_FILES": "max_folder_files",
     "JCODEMUNCH_MAX_INDEX_FILES": "max_index_files",
     "JCODEMUNCH_STALENESS_DAYS": "staleness_days",
@@ -325,6 +326,7 @@ def apply_adaptive_languages(source_root: str, detected: set[str]) -> bool:
     "use_ai_summaries": "auto",
     "trusted_folders": [],
     "trusted_folders_whitelist_mode": True,
+    "max_file_size": 512000,
     "max_folder_files": 2000,
     "max_index_files": 10000,
     "staleness_days": 7,
@@ -480,6 +482,7 @@ def apply_adaptive_languages(source_root: str, detected: set[str]) -> bool:
     "use_ai_summaries": (bool, str),
     "trusted_folders": list,
     "trusted_folders_whitelist_mode": bool,
+    "max_file_size": int,
     "max_folder_files": int,
     "max_index_files": int,
     "staleness_days": int,
@@ -1921,6 +1924,13 @@ def generate_template() -> str:
   //   true = only trust folders in trusted_folders list (default, secure).
   //   false = trust all folders EXCEPT those in trusted_folders (blocklist mode).
 
+  // "max_file_size": 512000,
+  //   Per-file byte cap for indexing. A file larger than this is skipped with
+  //   reason `too_large`, and a search over a corpus that skipped one cannot
+  //   prove absence -- the file is real, current and wanted, it just never
+  //   entered the index. The default is deliberately conservative; raise it if
+  //   your repo has large legitimate source files, and re-index.
+
   // "max_folder_files": 2000,
   //   Maximum number of files to index when indexing a local folder.
   //   Prevents accidental massive indexing jobs. Monorepos often exceed this;

src/jcodemunch_mcp/config.py

@@ -145,6 +145,20 @@ def absence_refusal(record: Optional[dict]) -> Optional[str]:
             "the index did not cover the whole tree at scan time, so the target "
             "may sit in a file that never entered the corpus"
         )
+    _withheld = (record.get("coverage") or {}).get("withheld") or {}
+    if _withheld:
+        # v1.108.193. Named BEFORE the generic state rule, and separately from
+        # `partial`, because the cause is ours and the remedy is a setting.
+        # `partial` says the corpus has a gap; this says WE made it, by refusing
+        # a file that is real, current and wanted. A reader who is told "the
+        # index did not cover the whole tree" goes looking at their repo; a
+        # reader told a file was too large goes and raises the limit.
+        _detail = ", ".join(f"{n} {reason}" for reason, n in sorted(_withheld.items()))
+        return (
+            f"the index withheld files that belong to this corpus ({_detail}), so "
+            "the target may sit in a real, current file that our own limits kept "
+            "out; raise the relevant limit and re-index before claiming absence"
+        )
     _tree = record.get("working_tree") or {}
     if _tree.get("files_not_in_index"):
         # Named before the generic state rule (#377 item 5). Work OUTSIDE the

src/jcodemunch_mcp/handoff.py

@@ -95,6 +95,13 @@ def index_coverage_meta(index) -> Optional[dict]:
         out["dropped_after_discovery"] = cov["dropped_after_discovery"]
     if cov.get("unaccounted"):
         out["unaccounted"] = cov["unaccounted"]
+    # v1.108.193: surfaced separately from `excluded` because it answers a
+    # different question. `excluded` says what this corpus is not about; a
+    # binary or a gitignored tree was never a candidate. `withheld` says a real,
+    # current, wanted source file was refused by one of OUR limits, which is the
+    # one exclusion reason a reader must not read as "the file is not there".
+    if cov.get("withheld"):
+        out["withheld"] = cov["withheld"]
     return out
 
 

src/jcodemunch_mcp/retrieval/verdict.py

@@ -357,6 +357,42 @@ def get_extra_ignore_patterns(
 DEFAULT_MAX_FOLDER_FILES = 2_000
 MAX_FOLDER_FILES_ENV_VAR = "JCODEMUNCH_MAX_FOLDER_FILES"
 
+# The size cap was the only one of these three with no way to move it
+# (reported by @dkiaulakis, v1.108.193). Its two neighbours each had a
+# resolver reading config; this one was passed as a hardcoded constant from
+# index_folder.py and appeared in none of the 79 JCODEMUNCH_* variables.
+#
+# The default is NOT raised. 500KB stays, because it protects the common case
+# from a parse that costs more than the file is worth. What changes is that a
+# caller who knows their own corpus can move it, the same way they can already
+# move both file-count limits three lines up.
+MAX_FILE_SIZE_ENV_VAR = "JCODEMUNCH_MAX_FILE_SIZE"
+
+
+def get_max_file_size(max_size: Optional[int] = None) -> int:
+    """Resolve the per-file byte cap from arg or config.
+
+    Parity with ``get_max_index_files`` / ``get_max_folder_files``, which is the
+    whole point: the size cap was the one limit of the three that could not be
+    moved by any route (v1.108.193).
+
+    Args:
+        max_size: Explicit override. Must be a positive integer when provided.
+
+    Returns:
+        Positive byte limit. Falls back to the default if config is unset or
+        invalid, matching the siblings rather than failing the index.
+    """
+    if max_size is not None:
+        if max_size <= 0:
+            raise ValueError("max_size must be a positive integer")
+        return max_size
+
+    value = _config.get("max_file_size", DEFAULT_MAX_FILE_SIZE)
+    if isinstance(value, int) and value > 0:
+        return value
+    return DEFAULT_MAX_FILE_SIZE
+
 
 def get_max_index_files(max_files: Optional[int] = None) -> int:
     """Resolve the maximum indexed file count from arg or config.

src/jcodemunch_mcp/security.py

@@ -29,6 +29,7 @@
     is_secret_file,
     is_binary_file,
     DEFAULT_MAX_FILE_SIZE,
+    get_max_file_size,
     get_max_folder_files,
     get_extra_ignore_patterns,
     get_skip_directories,
@@ -87,6 +88,25 @@ def _attach_cap_report(result: dict, cap: Optional[dict]) -> None:
         f"JCODEMUNCH_MAX_FOLDER_FILES) and re-index, or narrow the path."
     )
 
+#: Skip reasons where the file is REAL, CURRENT and WANTED, and we refused it
+#: anyway (v1.108.193, reported by @dkiaulakis). Every other reason describes a
+#: file that was never a candidate for this corpus: a `.png` is `binary`, a
+#: vendored tree is `gitignore`, a `.lock` is `wrong_extension`. Excluding
+#: those is the corpus being defined, and a search over it can still prove
+#: absence.
+#:
+#: These are different in kind. The file is source, it is current, an agent
+#: asked about it by name, and it is missing because of OUR limit rather than
+#: the caller's intent. A zero-result over a corpus that withheld one cannot
+#: prove absence: "I never learned that file" and "that file does not exist"
+#: are exactly the two things this whole contract exists to keep apart.
+WITHHELD_SKIP_REASONS = frozenset({
+    "too_large",     # over max_file_size, which until v1.108.193 could not be raised
+    "file_limit",    # over max_folder_files / max_index_files
+    "unreadable",    # a permission or IO failure, NOT a statement about the file
+})
+
+
 def _coverage_report(
     skip_counts: dict, files_indexed: int, no_symbols_count: int,
     files_accepted: Optional[int] = None,
@@ -148,7 +168,16 @@ def _coverage_report(
     unaccounted = int(files_accepted) - int(files_indexed) - sum(drops.values())
     if unaccounted > 0:
         report["unaccounted"] = unaccounted
-    report["complete"] = (int(files_indexed) == int(files_accepted)) and not drops
+    # v1.108.193: withheld files never reach `files_accepted` (they are refused
+    # during discovery), so the reconciliation below balances perfectly while a
+    # real, wanted source file sits outside the corpus. Counting them keeps
+    # `complete` honest about the tree rather than only about the walk.
+    withheld = {k: v for k, v in skips.items() if k in WITHHELD_SKIP_REASONS}
+    if withheld:
+        report["withheld"] = withheld
+    report["complete"] = (
+        int(files_indexed) == int(files_accepted) and not drops and not withheld
+    )
     return report
 
 
@@ -1487,7 +1516,7 @@ def _run_deferred_summarize(
             _fast_filter_cfg = _build_index_filters(
                 root=folder_path.resolve(),
                 follow_symlinks=follow_symlinks,
-                max_size=DEFAULT_MAX_FILE_SIZE,
+                max_size=get_max_file_size(),
                 extra_spec=_fast_extra_spec,
                 forced_paths=set(),
                 skip_dirs_regex=_build_skip_dirs_regex(),