@adhisang/minecraft-modding-mcp 7.0.0-rc.1 → 7.0.0-rc.2

package/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.0.0-rc.2] - 2026-09-04
+
+### Added
+
+- Artifact downloads are now capped at 512 MiB per transfer, configurable with `MCP_MAX_DOWNLOAD_BYTES`. The ceiling is checked against the declared `Content-Length` before the body is read and again against the bytes actually received, so a chunked or mis-declared response is caught too. A breach fails with `ERR_LIMIT_EXCEEDED`, is not retried, and its partial file is removed on a best-effort basis; a cached copy is never served in its place. When every repository trips the cap, the final `ERR_REPO_FETCH_FAILED` says so: `hints` tells you to raise `MCP_MAX_DOWNLOAD_BYTES`, and `context.repoFailureCode` is `"ERR_LIMIT_EXCEEDED"`. Previously only a 15-second timeout bounded a transfer, so a fast link serving a very large body could fill the disk. The cap is per transfer and is unrelated to total cache size.
+- Nested-jar extraction is now capped at 64 MiB per inner jar, configurable with `MCP_MAX_NESTED_JAR_ENTRY_BYTES`. The ceiling is checked against the entry's declared uncompressed size before extraction and against the bytes actually streamed. A breach fails that one entry with `ERR_LIMIT_EXCEEDED`; the shell jar's other inner jars still resolve. Previously inner jars were read whole into memory with no size check, so a highly compressible entry could expand far beyond the archive carrying it.
+- The `nestedJars` error field is now bounded in bytes as well as entry count, and says when it has been shortened. Entries longer than 256 bytes are dropped individually, the list stops at 8 KiB in total, and `nestedJarsTruncated: true` accompanies a shortened list wherever one is emitted. Previously a truncated inventory was indistinguishable from a complete one.
+- `resolve-artifact` now reports the `binary-jar-no-classes` quality flag for a binary jar that opens cleanly but contains no `.class` entry. Such jars are legitimate — `net.fabricmc:yarn` and `intermediary` `v2` carry only `mappings/mappings.tiny`, and a resource-only Fabric mod carries only `fabric.mod.json` and assets — so the flag describes the artifact and never refuses it. It is set for `coordinate`, `jar` and `version` targets alike. Known limit: a class-free jar that is not a Jar-in-Jar shell still fails during indexing with `ERR_DECOMPILER_FAILED` before any response exists, so the flag does not reach a caller in exactly that case.
+
+### Changed
+
+- **Wire contract change.** `context.jarHash` is renamed to `context.jarSignature` on `get-class-members` and `batch-class-members`. The value never was a hash of the jar's bytes: it is a signature over the jar's resolved path, modification time and size, useful for spotting that a jar changed between two responses but not as a content identity or cache key. The value and its derivation are unchanged. Callers reading `context.jarHash` must read `context.jarSignature` instead.
+- **Wire contract change.** An artifact named only by an opaque handle no longer draws the blame for carrying no binary jar. `get-class-members`, `batch-class-members` and `inspect-minecraft`'s `class-members` task now apply one rule: a caller-named jar target (`target: { kind: "jar", ... }`) is the only shape that reports `issueOrigin: "code_issue"`; every other shape, an `artifactId` or `resolved-id` handle from an earlier resolve included, reports `"tool_issue"`. Previously `get-class-members` reported `"code_issue"` for `target: { kind: "artifact", artifactId }`, even though a handle tells its holder nothing about whether the artifact has a binary jar and `resolve-artifact` does not accept one. `retryClass` is unchanged and still `"input"` here. The error now points at `manage-cache action="inspect"` with `selector: { artifactId }` and `include: ["cacheEntries"]`, which reports the artifact's stored jar as `meta.binaryJarPath` inside `cacheEntries`. Clients that branch on `issueOrigin` should read it per response rather than assume a fixed value per error code.
+- **A dependency's `artifactId` is now derived from the jar's bytes when the jar is served from `~/.m2` or the Gradle dependency cache**, not from its modification time and size. This applies to the routes that reach a jar through a Maven coordinate, `target.kind="dependency"` and `target.kind="coordinate"`; a jar named directly by path (`target.kind="jar"`) is unchanged and still takes its identity from that path with the file's modification time and size. 7.0.0-rc.1's content-derived `artifactId` covered only the remote-download path, so on the local path a `touch`, a cache eviction and re-fetch of identical bytes, or a filesystem restore still minted a new `artifactId`. Each already-cached local dependency gets a new `artifactId` and re-indexes once on its first resolve after upgrading, including a fresh decompile for binary-only dependencies.
+
+### Fixed
+
+- `search-class-source`, `get-artifact-file`, `list-artifact-files` and `index-artifact` now accept a top-level `projectPath` parameter, matching `find-class`, and advertise it in their `tools/list` `inputSchema`. Previously a `target.kind="workspace"` or unversioned `target.kind="dependency"` call to these four tools was rejected with an error asking for `projectPath`, but their schemas had no such field, so the error's own advice could not be followed.
+- A dependency resolve no longer warns that its requested mapping "is not enforced" when a source-backed jar actually supplied it. The warning used to fire whenever a non-obfuscated mapping was requested for a dependency, contradicting the same response's `mappingApplied` and `qualityFlags` when the mapping had genuinely succeeded. It now fires only when the binary remap was actually skipped, that is, when `qualityFlags` includes `dependency-mapping-unverified`.
+- A dependency's own coordinate version is no longer read as a signal about Minecraft's obfuscation state. A version that parses as a modern Minecraft version — any `26.x` or later, as `org.jetbrains:annotations:26.0.2` does — made a `mapping: "mojang"` request on a binary-only dependency return `mappingApplied: "mojang"` with no quality flag and no warning, claiming a remap that was never performed. Such a dependency now reports `mappingApplied: "obfuscated"` with the `dependency-mapping-unverified` flag and warning, on `resolve-artifact`, `get-class-source` and `get-class-members` alike. The obfuscation check now applies only to targets that genuinely name a Minecraft version — a `target.kind="version"`, or a `coordinate` target naming the Minecraft runtime itself such as `net.minecraft:client:26.1`; a `target.kind="dependency"` request is never treated as one — so vanilla resolution is unaffected.
+- `get-class-members` and `batch-class-members` now report `context.minecraftVersion: "unknown"` for a dependency artifact instead of a plausible-but-wrong value. The version used to be guessed from the jar's path, which for a jar served out of the Gradle cache yielded the cache-layout constant `2.1` and under `~/.m2` the dependency's own release number, and a fallback then substituted the dependency's coordinate version. The workspace's Minecraft version is not substituted either: `"unknown"` reports what the tool genuinely knows. Vanilla artifacts are unaffected.
+- `get-class-members`, `batch-class-members`, `find-class` and `get-class-source` now recognize a dependency artifact however it was reached. Previously only a `target.kind="dependency"` request marked the artifact as a dependency; the same jar reached by its Maven coordinate or reused by its `artifactId` was treated as vanilla, so `context.minecraftVersion` again reported the Gradle cache-layout constant `2.1` or the dependency's own release number, and a class-not-found miss drew a false hint to retry with `mapping="mojang"`. A dependency named by a Maven coordinate is now detected on every route, and `net.minecraft` alone no longer marks an artifact as Minecraft: the artifact name is read too, so `net.minecraft:launchwrapper:1.12` is a dependency, as is a group that merely ends in `net.minecraft` or an artifact whose name merely contains `minecraft-client`. A jar named by bare path (`target.kind="jar"`) under the Gradle dependency cache or the local Maven repository, wherever `MCP_LOCAL_M2` puts it, reports `"unknown"` unless the part of the path below the store's root names the Minecraft runtime; directories above the store are never consulted. Minecraft's own jars are unaffected. Remaining limit: a third-party jar whose own file name starts with `minecraft-`, such as `minecraft-client-helper`, still reports its own release number when named by a bare jar path; reach it with a `dependency` or `coordinate` target instead.
+- `batch-class-members` and `inspect-minecraft`'s `class-members` task no longer blame the caller when the artifact they themselves resolved from the request's target carries no binary jar. Both collapse the request to a single artifact before reading members, and the failure was reported as `issueOrigin: "code_issue"` — once per entry on a batch — pointing at an input that could not have chosen otherwise. It is now `"tool_issue"`, matching `get-class-members`. A caller who named a jar themselves (`target: { kind: "jar", ... }`) still gets `"code_issue"`. This closes the gap 7.0.0-rc.1 recorded as outstanding for `batch-class-members`.
+- A binary jar that `resolve-artifact` reports is now also persisted when the resolve was served from the warm cache. Previously that path skipped the write, so a binary companion that appeared in `~/.m2` or the Gradle cache after the artifact was first recorded, or the mojang-remapped jar reconciled for a `binary-remap:obf->mojang` artifact, reached the `resolve-artifact` response but not the stored artifact, and `get-class-members` on the returned `artifactId` then failed with `ERR_CONTEXT_UNRESOLVED` saying the artifact has no binary jar. Affected artifacts repair themselves on their next resolve; no re-index or cache clear is needed. A resolve that reaches no jar never clears a previously stored one.
+- Cached artifact bytes that a concurrent resolve or cache prune deleted are now re-downloaded instead of failing the call with a raw `ENOENT`. Both a cache hit and a `304` revalidation treat vanished bytes as a cache miss and transfer again — unconditionally in the 304 case, carrying no validator from any source, caller-supplied `requestHeaders` included. A 304 revalidation no longer overwrites a fresher freshness record that a concurrent resolve left beside replaced `-SNAPSHOT` bytes: that record's digest, `etag` and `lastModified` are reported as they stand and no extra transfer is made. A cached entry that is present but unreadable — a permission error, a directory where a jar should be — is now reported instead of being treated as a miss, which had put that URL on the network on every call while hiding the actionable error. When that failed every repository, the final `ERR_REPO_FETCH_FAILED` names the offending cache path and its errno (`EACCES`, `EISDIR`, `EPERM`, `EIO`) in `hints` and says to remove or repair it.
+- Evicting a poisoned download no longer destroys a concurrent resolve's good jar, and an eviction that cannot delete no longer leaves an entry the cache re-adopts forever. A response that is not a readable archive is dropped from the download cache, but the deletion named only the path, so when another resolve of the same URL had meanwhile finished a real jar into the same slot, that jar was deleted on the strength of a check run against different bytes. The eviction now compares the digest of the body it is rejecting with the identity record beside the file and leaves the file alone when they differ; this narrows the window rather than closing it, since another process can still replace the file between the comparison and the deletion. An entry no record can identify is still deleted, so a cache poisoned by an earlier version still heals itself. Separately, when the deletion itself fails — a read-only cache directory, say — the file is now truncated to zero bytes, which the cache treats exactly like a missing one, so the next transfer replaces it; previously whatever survived was served back and rejected again on every later resolve.
+- `Retry-After` is now honoured in the RFC 9110 HTTP-date form. That form used to parse as `NaN` and fall through to a roughly 200-millisecond backoff, hammering a server that had just asked for a long pause. The numeric form is now read strictly, so `Retry-After: 12abc` is malformed rather than 12 seconds. Both forms stay capped at 30 seconds, a date already in the past behaves like `Retry-After: 0`, and only the space and horizontal tab RFC 9110 permits are stripped: a value padded with a newline, a form feed or a non-breaking space stays malformed instead of being repaired into a pause. The delta is measured against the local clock rather than the response's `Date` header.
+- A caller-supplied Maven coordinate can no longer reach a jar outside the configured local repository. Every segment of `group:artifact:version[:classifier]` becomes a path component, and none was validated: an `artifactId` or `version` carrying `../` walked out of the repository root, and a `groupId` of `.`, `..` or `.a` landed at the filesystem root. Each segment is now trimmed and checked against one rule — 1 to 200 characters from `[A-Za-z0-9._+-]`, no leading `.`, no `..` — with `version` and `classifier` additionally admitting a space, because `net.fabricmc:yarn:1.14 Pre-Release 1+build.10:v2` is a real coordinate. A rejected coordinate fails with `ERR_COORDINATE_PARSE_FAILED` naming the offending segment in `details.component`, including when a mandatory segment is blank; `g : a : 1.0` now resolves instead of failing on its padding. The `dependency` target route applies the same rule to `target.group` and `target.name` before it probes the Gradle cache (its old blocklist admitted `group="D:"` with `name="."`, which listed a directory outside the cache root into `candidatesSeen`), trims `target.version`, and names `target.group` or `target.name` in its field error instead of just `target`. Scope: the reachable impact was reading a file that is both named `<artifact>-<version>[-classifier][-sources].jar` and openable as a zip; no write location was ever reachable, since every cache and artifact write derives its filename from a sha256.
+- One corrupt `-sources.jar` in `~/.m2` no longer aborts artifact resolution. A truncated or non-zip sources jar among the resolution candidates used to surface as a generic `ERR_ARTIFACT_RESOLUTION_FAILED`, with the Gradle cache, the remote sources repositories, the local-binary decompile branch and the remote binary fallbacks never tried. An unopenable candidate is now treated as "no sources here" and resolution moves on, as the binary side already did. A jar the caller named directly still reports the open failure rather than laundering it into "no sources".
+- A sources jar found in `~/.m2` or the Gradle module cache now picks its binary companion by opening the candidates, and looks in both stores. Previously each store took the first companion that merely existed, so a truncated or half-copied jar in one cache shadowed a good copy in the other, and the unusable path was what got recorded on the artifact, so every later `get-class-members` on that `artifactId` went to the broken file. Candidates are now tried in preference order, the sources jar's own store first, and the first one that opens wins. A companion that opens but holds no `.class` entry carries the `binary-jar-no-classes` quality flag here too.
+- `validate-access-widener` and `validate-access-transformer` no longer answer `ERR_CONTEXT_UNRESOLVED` because of a directory name above the Gradle cache. A runtime jar's loader was read from its whole path, so a Fabric workspace checked out under a folder called `forge`, `moddev-notes` or `srg-test` was taken for a Forge or NeoForge runtime and refused. The loader is now read only from the part of the path a build tool wrote — everything below the deepest dot-directory (`.gradle`, `.m2`), Gradle's `caches` root or a project `build` directory, or the file name alone when the path enters none of them. A NeoForge-patched jar inside a Loom cache is still reported as NeoForge.
+- A stdio peer that sends a `Content-Length` header and then stops sending the body no longer silences the connection. 7.0.0-rc.0 closed this only for a declared length above the frame limit; a smaller declared length followed by no body still parked the reader forever, with every later request stuck behind it. After 30 seconds with no further bytes the session now ends with a diagnostic naming the declared and received byte counts. The budget measures silence, not total transfer time: every arriving byte re-arms it, so a slow or very large body is never cut off.
+- A header block whose lines contradict each other — a second `Content-Length` line even when the first value was unusable, or a malformed line alongside a good one — is now rejected outright and ends the session. Previously the reader stopped at the first bad line and consumed only the header block, so the body bytes an earlier declaration had claimed were re-read as separate messages and the peer effectively chose where the frame ended. A block that never declares a usable length is still reported as an ordinary parse error and recovered from.
+- Peers that frame `Content-Length` headers with bare LF line endings are no longer mis-read when the JSON body contains a `\r\n\r\n` pair, which is legal JSON whitespace. A CRLF terminator anywhere in the buffer used to win over an earlier LF one, cutting the header block inside the body and losing that message and the next. The first terminator now wins, whichever style it is.
+- A fault while handling an already-decoded frame no longer changes how later replies are framed. Such a throw used to reset the detected framing mode, so every later response was silently downgraded to line framing while the faulting request went unanswered. The fault is now reported through the ordinary parse-error channel with the framing state left as it was, and it can no longer tear the session down.
+- A running `validate-project` no longer loses its timeout when a client reuses its JSON-RPC id. The deadline was matched by id alone, so a queued duplicate with the same id was timed out in its place while the real `validate-project` kept running with no deadline and still holding the dispatch barrier; whenever the worker never answered, everything queued behind it waited forever. A deadline now belongs to the exact request it was armed for, and a request that does not hold the barrier cannot release it.
+- An internal failure while handing a request to the MCP worker no longer leaves that request half-registered. The supervisor answers such a fault with a JSON-RPC `-32603` "failed to admit the request" error, but the entry it had already installed stayed live: for `validate-project` the abandoned deadline later fired a second reply for the same id, and the dispatch barrier stayed raised until it did. The `-32603` is now the only reply for that id — the entry, its deadline and any barrier it held are released before the error is written — and queued work resumes immediately. An `initialize` that faults at this point keeps its own handshake recovery and is not rolled back here.
+- A `tools/call` whose `arguments` are nested thousands of levels deep — a few KB on the wire — is now answered instead of vanishing. The argument redaction that runs at admission had no depth bound, so such a frame overflowed the stack and the request got no reply on an id the client then waited on forever. The walk now stops at 32 levels and reports anything deeper as `"<max-depth>"` in the diagnostic copies (`meta.timeout.redactedToolArgs`, `meta.restart.redactedToolArgs`, marked by `redactedToolArgsModified`); no real tool schema nests near that deep. Any request the supervisor cannot admit, for any reason, is now answered with JSON-RPC `-32603` rather than dropped.
+- A worker or JVM that writes one very long stderr line with no newline no longer makes the server's memory grow until that worker is next restarted. The pending line is capped at 64 KiB: the part already held is passed through as one truncated line with a `supervisor.worker_stderr_line_truncated` warning, the rest of that line is discarded, and normal line handling resumes at the next newline, so worker startup is still detected.
+- `compare-versions` no longer reports every class as both added and removed when only one of the two versions has usable Mojang mappings. Each side used to be lifted independently, so a pair where one side stayed obfuscated compared two different namespaces and returned `unchanged: 0` beside two full class lists. The diff now falls back to the jars' own class names on both sides, the `obfuscated` namespace the result already reported, and the warning announcing that fallback lists `version` alongside `packageFilter` in its `affectedFields`. One case the fallback cannot repair: when the two versions straddle Minecraft's move to unobfuscated names and the obfuscated side's mappings cannot be loaded, the jars' own names are still two different schemes, so `warnings` now says outright that the added and removed lists are not meaningful and `unchanged` will be near zero.
+- A mapping file that leaves a namespace column empty on a class row no longer files that class's fields and methods under the previous class. The previous name was left standing for that namespace, so every member row that followed was indexed under the wrong owner and a lookup could be answered with a member the owner does not declare. Such a row now clears the namespace instead.
+- `MCP_LOOM_TINY_MAX_INDEX_ENTRIES` now accepts only plain ASCII digits. A value such as `1e9`, `2_000_000`, `10M` or `1.9` used to be read from its leading digits as 1, 2, 10 or 1, small enough to truncate every real Loom mapping load; such a value now falls back to the heap-derived budget. A plain integer such as `250000` is still honoured, and may still be deliberately small.
+- `find-mapping` and `resolve-method-mapping-exact` now return the mapping loader's own warnings in `warnings` whenever a mapping was loaded, `mapping_unavailable` included, as `get-class-api-matrix` and `check-symbol-exists` already did. The notice that a Loom mapping index stopped at its entry budget — the one signal that the answer may be incomplete — was being dropped on exactly the two tools most likely to hit it, and a `mapping_unavailable` answer replaced those warnings with its own single "no mapping path is available" sentence; both now appear together. On a version with no Mojang mappings these two tools now also surface the pre-existing `does not expose client mappings URL` notice.
+- `resolve-method-mapping-exact` now says when a `not_found` was caused by an `owner` with no package. An unqualified owner cannot be projected into the target namespace and can never match, but the response explained the miss only as an inherited or relocated member. The message now names the owner and asks for the fully-qualified one.
+- A version-manifest or version-detail fetch that fails at the transport layer — DNS, a refused connection, a TLS handshake — now fails with `ERR_REPO_FETCH_FAILED` instead of `ERR_INTERNAL`, so a network fault no longer reads as a server bug. The underlying message travels in `details.cause`; the timeout mapping is unchanged.
+- `MCP_SQLITE_CACHE_KB` and `MCP_SQLITE_MMAP_SIZE` now also tune the artifact index that `manage-cache` opens. It used to open the same database on the built-in defaults — 8000 KiB page cache, 256 MiB memory map — whatever the two variables said.
+- A failure while rebuilding a corrupted artifact index now fails with `ERR_DB_FAILURE` and closes the half-opened database handle, instead of escaping as a raw filesystem error from a read-only directory or a full disk. `details.reason` is `"rebuild_failed"` and the underlying message is carried in the error message.
+
+### Documentation
+
+- `docs/tool-reference.md` no longer tells a caller to work around a parameter that now exists. Its "Essential Conventions" entry named `find-class` as the only flat-`artifactId` tool accepting a top-level `projectPath` and directed callers of the other four to resolve the artifact first, contradicting the "Common Pitfalls" entry in the same document. Both now state that all five tools accept a top-level `projectPath` for a target that cannot supply workspace context from its own fields; resolve-first stays documented in "Common Pitfalls" as the optional alternative it still is.
+- `docs/tool-reference.md` now documents the `context` block `get-class-members` and `batch-class-members` return. `jarSignature` is described as a signature over the jar's resolved path, modification time and size — good for spotting that the jar behind two responses is no longer the same file in the same state, usable neither as a content identity nor as a cache key. `minecraftVersion`, `mappingType`, `mappingNamespace` and `generatedAt` are described alongside it, including that `minecraftVersion` is `"unknown"` for a dependency artifact and for a jar inside a dependency store whose store-relative path does not name the Minecraft runtime, while a jar outside any such store is read from the first version-shaped token in its path.
+- **Correction to 7.0.0-rc.0.** That release's "Ending the session no longer leaves a worker process behind" entry says the signal path and the supervisor-fault path both "exit non-zero once the worker group is collected or a bounded watchdog expires". That is wrong about the signal path: `SIGHUP`, `SIGINT` and `SIGTERM` run the ordinary cooperative shutdown and the process exits with code 0 once the detached worker group is collected, exactly as when stdin closes. Only an uncaught supervisor fault (`supervisor.fatal`) and a client framing violation (`supervisor.client_framing_fatal`) set exit code 1 on a running session, which is what lets a launcher tell a crash from a clean stop. No code changed; the published 7.0.0-rc.0 entry is left as it stands.
+
 ## [7.0.0-rc.1] - 2026-08-28
 
 ### Added

package/README.md

@@ -174,6 +174,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 - `validate-project` has a supervisor-owned end-to-end deadline of 120 seconds, including queue time. Set `MCP_VALIDATE_PROJECT_TIMEOUT_MS` to an ASCII-decimal value from `10000` through `600000` to override it. A timeout returns `ERR_TOOL_TIMEOUT`; a running timeout restarts the isolated worker before queued calls resume, while a queue timeout leaves the current worker untouched.
+- Artifact downloads are capped at 512 MiB (`536870912` bytes) each. Set `MCP_MAX_DOWNLOAD_BYTES` to an ASCII-decimal byte count to override it; values below 1 MiB are raised to 1 MiB, and anything else — non-numeric, malformed, or too large to be an exact integer — falls back to the default. The cap is checked twice: against `Content-Length` before any body is read (a header that is not a plain byte count is treated as absent rather than as a breach), and against the bytes actually received, so a chunked or mis-declared response is caught too. A download that exceeds it fails with `ERR_LIMIT_EXCEEDED` and is not retried; the partial file is deleted on a best-effort basis, so a file the server cannot remove may survive the refusal. A cached copy is never served in its place — a cap is a configuration verdict, not a passing outage, and standing a stale artifact in for it would hide the ceiling instead of reporting it. When every repository trips the cap, the terminal `ERR_REPO_FETCH_FAILED` reports it where a caller can actually read it: `hints` carries the sentence naming `MCP_MAX_DOWNLOAD_BYTES` and the byte count to clear, and `context.repoFailureCode` is `ERR_LIMIT_EXCEEDED`.
+- Nested (Jar-in-Jar) entries are capped at 64 MiB (`67108864` bytes) of uncompressed data each. Set `MCP_MAX_NESTED_JAR_ENTRY_BYTES` to override it, on the same rules as the download cap: ASCII decimal digits, values below 1 MiB raised to 1 MiB, anything else falling back to the default. The size is checked against the entry's declared uncompressed size before the read starts and again against the bytes actually streamed. A breach fails that one inner jar with `ERR_LIMIT_EXCEEDED`; the shell jar's other inner jars still resolve.
 - Queued calls resume only after the replacement worker completes initialization replay. If replacement startup or replay fails, queued tool calls terminate with `ERR_WORKER_RESTART` instead of waiting indefinitely. If unresolved process-tree cleanup fills the supervisor's two live-generation slots, new requests fail with the existing restart envelope and unavailable notifications are warning-dropped until cleanup or reconnect. On POSIX, an already-gone process group counts as cleaned up rather than leaving a stale cleanup token.
 - If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
 - `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.

package/dist/cache-registry.d.ts

@@ -45,6 +45,16 @@ export declare function pathContainsVersion(path: string, version: string): bool
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;
+    /**
+     * SQLite page-cache and memory-map tuning for the artifact index, as
+     * MCP_SQLITE_CACHE_KB and MCP_SQLITE_MMAP_SIZE resolve them. Optional because
+     * a caller with no opinion should get the same defaults `applyPragmas` gives
+     * every other reader of the index - but a caller that HAS one is the whole
+     * point: without these the registry opened the index on the built-in defaults,
+     * so the two variables tuned every consumer except manage-cache.
+     */
+    sqliteCacheKb?: number;
+    sqliteMmapSize?: number;
     pathRuntimeInfo?: PathRuntimeInfo;
     workspaceContextCache?: WorkspaceContextCache;
 };

package/dist/cache-registry.js

@@ -227,7 +227,11 @@ function openDb(config) {
     if (!existsSync(config.sqlitePath)) {
         return undefined;
     }
-    return openDatabase(config).db;
+    return openDatabase({
+        sqlitePath: config.sqlitePath,
+        sqliteCacheKb: config.sqliteCacheKb,
+        sqliteMmapSize: config.sqliteMmapSize
+    }).db;
 }
 function candidatePathsForEntry(entry) {
     const paths = new Set();

package/dist/entry-tools/batch-class-members-service.js

@@ -48,6 +48,14 @@ export class BatchClassMembersService {
                 }
                 const raw = (await this.deps.getClassMembers({
                     artifactId: sharedArtifact.artifactId,
+                    // This artifactId is OURS, not the caller's: the shared target was
+                    // resolved above and every entry is dispatched by the result. Without
+                    // saying so, get-class-members reads the bare presence of an
+                    // artifactId as the caller having named the artifact, and reports a
+                    // missing binary jar as their mistake - once per entry - though
+                    // `target` here cannot name an artifact at all. Only a jar the caller
+                    // named themselves is genuinely their choice.
+                    artifactSelectedBy: input.target.kind === "jar" ? "caller" : "tool",
                     className: entry.className,
                     access: entry.access,
                     includeSynthetic: entry.includeSynthetic,

package/dist/entry-tools/inspect-minecraft/handlers/class-members.js

@@ -1,5 +1,17 @@
 import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createSummarySubject, createTruncationMeta } from "../../response-contract.js";
 import { buildClassSubject, resolveClassArtifactReference, invalidTaskSubjectError } from "../internal.js";
+function artifactSelectedByFor(ref) {
+    if (!ref) {
+        return "tool";
+    }
+    // A `resolved-id` reference is NOT a caller choice, despite being written by
+    // the caller. The id is an opaque handle some earlier resolve produced: it
+    // says nothing about whether the artifact carries a binary jar, and it cannot
+    // be re-resolved into one that does. Only `target: { kind: "jar", ... }`
+    // names a jar the caller actually picked and can pick differently, which is
+    // the same line `get-class-members` draws for its own `artifact` target.
+    return ref.type === "resolve-target" && ref.target.kind === "jar" ? "caller" : "tool";
+}
 export async function handleClassMembers(deps, subject, detail, include, limit) {
     if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
         invalidTaskSubjectError("class-members", subject);
@@ -9,6 +21,15 @@ export async function handleClassMembers(deps, subject, detail, include, limit)
     const members = await deps.getClassMembers({
         className: classSubject.className,
         artifactId: artifact.artifactId || undefined,
+        // The artifactId above is one WE produced - resolveClassArtifactReference
+        // collapses every subject shape to one, including the workspace
+        // auto-resolution that happens with no artifact reference at all. Only the
+        // caller's own reference says whether they picked the artifact, and only a
+        // jar target does: it names an exact jar they can name differently.
+        // Anything else (a resolved-id handle, a version/coordinate target, or an
+        // omitted reference) leaves the artifact effectively ours, so a missing
+        // binary jar is not their input to fix.
+        artifactSelectedBy: artifactSelectedByFor(classSubject.artifact),
         mapping: classSubject.mapping,
         scope: classSubject.scope,
         projectPath: classSubject.projectPath,

package/dist/entry-tools/inspect-minecraft/internal.d.ts

@@ -424,6 +424,10 @@ export type InspectMinecraftDeps = {
         strictVersion?: boolean;
         maxMembers?: number;
         includeDescriptors?: boolean;
+        /** Who chose the artifact: see `GetClassMembersInput.artifactSelectedBy`.
+         * This tool always collapses its subject to an artifactId before calling,
+         * so without it every failure would be attributed to the caller. */
+        artifactSelectedBy?: "caller" | "tool";
     }) => Promise<GetClassMembersOutput>;
     searchClassSource: (input: {
         artifactId: string;

package/dist/error-mapping.d.ts

@@ -65,6 +65,15 @@ export type ProblemDetails = {
      * dedicated typed field: `context` is primitive-only and can never carry it.
      */
     nestedJars?: string[];
+    /**
+     * True when `nestedJars` is a SHORTENED view of the shell's inventory —
+     * entries were dropped by the count cap, the per-entry length cap, or the
+     * total-bytes cap. Without it a caller cannot tell a complete inventory from
+     * a trimmed one and may conclude a class is bundled nowhere. Additive and
+     * omitted entirely when the published list is complete, matching the
+     * `candidatesTruncated` precedent.
+     */
+    nestedJarsTruncated?: boolean;
     failedStage?: string;
     context?: Record<string, string | number | boolean>;
 };
@@ -75,14 +84,47 @@ export type ProblemDetails = {
  * whole rather than partially published.
  */
 export declare function extractDidYouMean(details: unknown): DidYouMeanCandidate[] | undefined;
+/**
+ * The `nestedJars` pair as published: the inventory plus the additive flag that
+ * says whether it is complete. Both keys are omitted when there is nothing to
+ * publish, so the object spreads directly into a ProblemDetails.
+ */
+export type NestedJarsField = {
+    nestedJars?: string[];
+    nestedJarsTruncated?: boolean;
+};
 /**
  * Validates and extracts a `nestedJars` inventory from error details.
  * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
  * shell jar, but `context` is primitive-only, so without this the inventory
- * never left the process. Malformed payloads are dropped whole rather than
- * partially published, matching {@link extractDidYouMean}. An empty inventory
- * is dropped too: the producing site omits the key entirely in that case, so an
- * empty array carries no information a caller could act on.
+ * never left the process.
+ *
+ * Two distinct dispositions, deliberately not conflated:
+ *  - MALFORMED (a non-string or empty-string element, anywhere in the array):
+ *    the whole array is dropped, matching {@link extractDidYouMean}. The scan
+ *    deliberately continues past the caps so a malformed element beyond them is
+ *    still found — the upstream array is a real jar's own entry list, bounded by
+ *    the archive, so the full scan is not an exposure.
+ *  - OVERSIZED (an entry longer than {@link MAX_NESTED_JAR_ENTRY_BYTES}, an
+ *    entry past the count cap, or one that would push the list past the total
+ *    byte budget): that ENTRY alone is excluded and `nestedJarsTruncated` is
+ *    set. An implausible name is not evidence that the rest of the inventory is
+ *    untrustworthy, so it must not drop the array.
+ *
+ * An empty inventory is dropped as before: the producing site omits the key
+ * entirely in that case, so an empty array carries no information a caller could
+ * act on. If the caps leave nothing publishable, both keys are omitted rather
+ * than publishing a truncation flag with no list beside it.
+ */
+export declare function extractNestedJarsField(details: unknown): NestedJarsField;
+/**
+ * Inventory-only view of {@link extractNestedJarsField}.
+ *
+ * NOT for an emission site. All three - the tool envelope, the batch entry, the
+ * error resource - publish the field pair, because dropping the flag makes a
+ * shortened inventory indistinguishable from a complete one. This remains for
+ * callers that want the list alone (tests pinning the validation and capping
+ * rules), and a new publisher should reach for the field-returning form.
  */
 export declare function extractNestedJars(details: unknown): string[] | undefined;
 /**

package/dist/error-mapping.js

@@ -35,28 +35,90 @@ export function extractDidYouMean(details) {
 // A shell jar bundles a handful of inner jars, not hundreds; the cap only
 // bounds a pathological inventory, it is not an expected truncation point.
 const MAX_NESTED_JAR_ENTRIES = 64;
+// Per-entry length ceiling, in UTF-8 bytes. Real entries are jar-relative paths
+// like "META-INF/jars/fabric-screen-handler-api-v1-2.0.5.jar" (~52 bytes); the
+// zip format itself allows a 65535-byte name, so an entry name is attacker-sized
+// unless bounded here. 256 bytes is ~5x the longest realistic entry and still
+// leaves any genuine name intact.
+const MAX_NESTED_JAR_ENTRY_BYTES = 256;
+// Total ceiling for the published list, in UTF-8 bytes. A full fabric-api-style
+// inventory (64 entries at ~52 bytes) is ~3.3 KiB, so 8 KiB carries every real
+// inventory whole while bounding the worst case this field can add to an error
+// payload — which matters because nothing else in this project bounds an
+// outbound response (MCP_MAX_FRAME_BYTES governs inbound decoding only).
+const MAX_NESTED_JARS_TOTAL_BYTES = 8 * 1024;
 /**
  * Validates and extracts a `nestedJars` inventory from error details.
  * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
  * shell jar, but `context` is primitive-only, so without this the inventory
- * never left the process. Malformed payloads are dropped whole rather than
- * partially published, matching {@link extractDidYouMean}. An empty inventory
- * is dropped too: the producing site omits the key entirely in that case, so an
- * empty array carries no information a caller could act on.
+ * never left the process.
+ *
+ * Two distinct dispositions, deliberately not conflated:
+ *  - MALFORMED (a non-string or empty-string element, anywhere in the array):
+ *    the whole array is dropped, matching {@link extractDidYouMean}. The scan
+ *    deliberately continues past the caps so a malformed element beyond them is
+ *    still found — the upstream array is a real jar's own entry list, bounded by
+ *    the archive, so the full scan is not an exposure.
+ *  - OVERSIZED (an entry longer than {@link MAX_NESTED_JAR_ENTRY_BYTES}, an
+ *    entry past the count cap, or one that would push the list past the total
+ *    byte budget): that ENTRY alone is excluded and `nestedJarsTruncated` is
+ *    set. An implausible name is not evidence that the rest of the inventory is
+ *    untrustworthy, so it must not drop the array.
+ *
+ * An empty inventory is dropped as before: the producing site omits the key
+ * entirely in that case, so an empty array carries no information a caller could
+ * act on. If the caps leave nothing publishable, both keys are omitted rather
+ * than publishing a truncation flag with no list beside it.
  */
-export function extractNestedJars(details) {
+export function extractNestedJarsField(details) {
     const raw = details?.nestedJars;
     if (!Array.isArray(raw) || raw.length === 0) {
-        return undefined;
+        return {};
     }
     const cleaned = [];
+    let truncated = false;
+    let totalBytes = 0;
+    let budgetExhausted = false;
     for (const entry of raw) {
         if (typeof entry !== "string" || !entry) {
-            return undefined;
+            return {};
+        }
+        if (budgetExhausted || cleaned.length >= MAX_NESTED_JAR_ENTRIES) {
+            truncated = true;
+            continue;
+        }
+        const entryBytes = Buffer.byteLength(entry, "utf8");
+        if (entryBytes > MAX_NESTED_JAR_ENTRY_BYTES) {
+            truncated = true;
+            continue;
         }
+        if (totalBytes + entryBytes > MAX_NESTED_JARS_TOTAL_BYTES) {
+            // Keep the published list a prefix of the surviving entries: once the
+            // budget is spent, stop admitting rather than cherry-picking short names
+            // from the tail.
+            truncated = true;
+            budgetExhausted = true;
+            continue;
+        }
+        totalBytes += entryBytes;
         cleaned.push(entry);
     }
-    return cleaned.slice(0, MAX_NESTED_JAR_ENTRIES);
+    if (cleaned.length === 0) {
+        return {};
+    }
+    return { nestedJars: cleaned, ...(truncated ? { nestedJarsTruncated: true } : {}) };
+}
+/**
+ * Inventory-only view of {@link extractNestedJarsField}.
+ *
+ * NOT for an emission site. All three - the tool envelope, the batch entry, the
+ * error resource - publish the field pair, because dropping the flag makes a
+ * shortened inventory indistinguishable from a complete one. This remains for
+ * callers that want the list alone (tests pinning the validation and capping
+ * rules), and a new publisher should reach for the field-returning form.
+ */
+export function extractNestedJars(details) {
+    return extractNestedJarsField(details).nestedJars;
 }
 const ISSUE_ORIGIN_VALUES = new Set([
     "code_issue",
@@ -319,7 +381,14 @@ const CONTEXT_ALLOWLIST = new Set([
     "maxMembers",
     "candidateCount",
     "candidatesSeen",
-    "ambiguous"
+    "ambiguous",
+    // Why a repository cascade gave up, as the failing leg's own error code (e.g.
+    // "ERR_LIMIT_EXCEEDED"). The terminal ERR_REPO_FETCH_FAILED says only that
+    // repositories were unstable, which is wrong for a configuration-driven
+    // refusal; the underlying code is the machine-readable half of that
+    // correction, beside the human-readable `nextAction` hint. A bare code string
+    // - no url, no path, no message - which is why it can travel here at all.
+    "repoFailureCode"
 ]);
 /**
  * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
@@ -381,7 +450,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         const fieldErrors = extractFieldErrors(caughtError.details);
         const context = extractAllowlistedContext(caughtError.details);
         const didYouMean = extractDidYouMean(caughtError.details);
-        const nestedJars = extractNestedJars(caughtError.details);
+        const nestedJarsField = extractNestedJarsField(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -394,7 +463,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
             ...(baseHints ? { hints: baseHints } : {}),
             ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {}),
             ...(didYouMean ? { didYouMean } : {}),
-            ...(nestedJars ? { nestedJars } : {}),
+            ...nestedJarsField,
             ...(context ? { context } : {})
         };
     }

package/dist/index.js

@@ -175,7 +175,9 @@ const validateProjectService = new ValidateProjectService({
 const manageCacheService = new ManageCacheService({
     registry: createCacheRegistry({
         cacheDir: config.cacheDir,
-        sqlitePath: config.sqlitePath
+        sqlitePath: config.sqlitePath,
+        sqliteCacheKb: config.sqliteCacheKb,
+        sqliteMmapSize: config.sqliteMmapSize
     })
 });
 const verifyMixinTargetService = new VerifyMixinTargetService({

package/dist/json-rpc-framing.d.ts

@@ -5,6 +5,14 @@ export type ParsedJsonRpcFrame = {
     message: JSONRPCMessage;
     mode: ConcreteFramingMode;
 };
+/**
+ * The opaque handle a {@link JsonRpcFrameReader}'s idle-budget timer is
+ * identified by. Only the reader's own scheduler/clearer pair interprets it,
+ * so a test can substitute a plain object for a real timer.
+ */
+export type FrameIdleTimerHandle = unknown;
+export type FrameIdleTimerScheduler = (callback: () => void, delayMs: number) => FrameIdleTimerHandle;
+export type FrameIdleTimerClearer = (handle: FrameIdleTimerHandle) => void;
 /**
  * A framing violation the reader cannot provably recover from.
  *
@@ -32,10 +40,15 @@ export type ParsedJsonRpcFrame = {
  *  - an oversized Content-Length whose declared body has NOT fully arrived
  *    (waiting on it is what let a single unanswerable header wedge the
  *    transport for the process lifetime),
+ *  - an UNDER-limit Content-Length whose declared body stops arriving for the
+ *    incomplete-frame idle budget — the same wedge, below the size check,
  *  - a Content-Length body that is not valid JSON — under-declaration,
  *    over-declaration and an honestly-framed bad body are indistinguishable,
  *    and the first two have already desynchronized the stream,
- *  - duplicate Content-Length headers — the body length is ambiguous,
+ *  - a header block that declared a body length and then contradicted it
+ *    (duplicate Content-Length headers, a non-numeric value alongside a
+ *    numeric one, junk after a good declaration) — bytes the peer counted as
+ *    body would otherwise be re-read as frames,
  *  - a Content-Length header block that never terminates within the header
  *    limit — there is no delimiter left to resynchronize on.
  */
@@ -54,14 +67,34 @@ export declare function loadMaxFrameBytes(value?: string | undefined): number;
 export declare function encodeJsonRpcMessage(message: JSONRPCMessage, mode: ConcreteFramingMode): Buffer;
 export declare class JsonRpcFrameReader {
     private readonly maxFrameBytes;
+    private readonly incompleteFrameIdleMs;
+    private readonly scheduleTimer;
+    private readonly clearTimer;
     private mode;
     private buffer;
     private pendingChunks;
     private pendingBytes;
     private awaitedFrameEnd;
+    private awaitedBodyStart;
+    private idleTimer;
     private fatal;
+    /**
+     * @param options.maxFrameBytes Largest accepted frame; defaults to
+     *   {@link loadMaxFrameBytes}.
+     * @param options.incompleteFrameIdleMs How long a declared Content-Length
+     *   body may stop arriving before the session is terminated. This is IDLE
+     *   time, not total time: every arriving byte clears and re-arms it, so a
+     *   legitimately slow or very large body is never cut off. Defaults to
+     *   30 000 ms; a non-positive or non-finite value disables the budget.
+     * @param options.timerScheduler Schedules the idle budget; defaults to an
+     *   `unref()`'d `setTimeout`. Injectable so tests can drive it directly.
+     * @param options.timerClearer Cancels a handle from `timerScheduler`.
+     */
     constructor(options?: {
         maxFrameBytes?: number;
+        incompleteFrameIdleMs?: number;
+        timerScheduler?: FrameIdleTimerScheduler;
+        timerClearer?: FrameIdleTimerClearer;
     });
     get currentMode(): FramingMode;
     /**
@@ -76,6 +109,25 @@ export declare class JsonRpcFrameReader {
         onFrame: (frame: ParsedJsonRpcFrame) => void;
         onError: (error: Error) => void;
     }): void;
+    private drainChunk;
+    private clearIdleTimer;
+    /**
+     * Puts an incomplete declared body on an idle clock.
+     *
+     * A Content-Length UNDER the frame limit whose body never arrives was the
+     * one wedge the size check could not see: `readContentLengthMessage` armed
+     * `awaitedFrameEnd`, `canCompleteFrame` then refused to look at anything
+     * until that many bytes existed, and every later frame piled up behind a
+     * body that was never coming. The budget is idle time — the caller clears it
+     * on every arriving chunk and this re-arms it — so only a stream that has
+     * gone silent mid-body is terminated.
+     *
+     * `onError` belongs to a `processChunk` call, so the timer fires through the
+     * handlers of the MOST RECENT call rather than the one that armed it. Every
+     * caller in this repository passes a stable handler pair on every chunk, and
+     * a caller that does not still gets a live pair rather than a stale one.
+     */
+    private armIdleTimer;
     private canCompleteFrame;
     private rejectOversizedIncompleteInput;
     /**