@adhisang/minecraft-modding-mcp 7.0.0-rc.3 → 7.0.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.0.0] - 2026-09-13
+
+### Fixed
+
+- Several more ways a fault during the stdio supervisor's own fault-recovery work could leave a request permanently unanswered, or answered twice, are closed. A `validate-project` request could be left marked as still running forever if an internal recovery step for an earlier fault on that same request itself failed, blocking every later `validate-project` call for the rest of the session; that is now cleared first. If a client re-sent `initialize` to a worker that was already ready and the supervisor then faulted while recovering from that duplicate handshake, other requests still in flight on the worker being replaced were not answered and could hang for the rest of the session; they are now answered before the worker is replaced. And a request taken from the internal queue whose own reply step then failed in a narrow way could be left with no reply at all, or, in a different case, answered a second, spurious time; exactly one reply is now produced either way. Each of these requires an internal fault that is not known to occur in current Node.js and has not been observed in production.
+- Two remaining internal call sites that build an error's logged description now use the same safe string conversion already used elsewhere for this reason, so a thrown value whose own string conversion itself throws can no longer slip past them either. Cosmetic; there is no known way to trigger it.
+- Four more ways a fault on the stdio connection to the worker process could leave a request unanswered are closed. A write error to the worker other than a broken pipe used to be logged and otherwise ignored, leaving the connection pointed at a worker nothing could send to again, so every request already sent to it — and every request sent afterward — hung for the rest of the session; that fault now retires the broken worker and starts a replacement, answering the stranded request along the way. If that same fault lands while a still-starting successor worker is replaying the client's `initialize` handshake, the client's `initialize` call now fails immediately instead of waiting silently across every later restart attempt. A successful reply to `initialize` could also be lost outright if writing it to the client failed at the same moment as the fallback log message the supervisor writes about that failure; both are now recovered from together. And once `initialize` completes, a client may legally reuse its request id for a later call; if the worker then exited before answering that reused id, it used to be mistaken for the already-finished `initialize` and silently dropped instead of receiving its own reply.
+- A large request sent in line-delimited framing right after a `Content-Length`-framed one was wrongly rejected as an oversized header, because the 8 KiB header-size ceiling kept applying even once the reader had already moved on to line framing; such a request is now accepted up to the ordinary frame-size limit. Separately, when an oversized line arrived without its terminating newline yet, discarding it did not also consume the rest of that same line once the newline did arrive; the tail could then be re-read as if it were a fresh, legitimate request of its own. That tail is now discarded along with the rest of the line it belongs to.
+- Deleting a downloaded-jar entry with `manage-cache` could destroy a different jar than the one that was listed, when another resolve finished writing a fresh copy to the same cache slot in between; the delete now verifies it is still removing the jar it originally listed. A delete that could not actually remove a file — for example because the cache directory is read-only — is no longer reported as successful; it now returns a warning and the entry is not counted as deleted. Checking a cached download's size no longer treats a permission error the same as a missing file; previously that silently triggered a fresh download instead of surfacing the actionable error.
+- `find-class` now resolves the correct fully qualified name for a class nested two or more levels inside another class. It previously dropped every enclosing type past the first level, producing a name that does not exist among the compiled classes, so a follow-up call using that name — reading its members or source, for example — failed with a spurious not-found error. A class nested exactly one level deep was already correct and is unaffected.
+- An unrecognized failure opening the artifact index database — for example the database being locked or the disk being full — is now reported as the documented database-failure error instead of escaping unclassified. Previously only a failure already recognized as an I/O problem, a schema mismatch, or corruption was reported that way.
+- Loading a Yarn/Tiny mapping file from a Maven-hosted jar is now bounded the same way nested-jar and download extraction already are. A `.tiny` entry inside such a jar could previously be decompressed in full with no size limit, so a small, highly compressed entry could expand to multiple gigabytes and exhaust memory before mapping parsing ever started.
+
 ## [7.0.0-rc.3] - 2026-09-07
 
 ### Changed

package/dist/cache-registry.d.ts

@@ -42,6 +42,22 @@ type CacheEntryPage = {
  * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
  */
 export declare function pathContainsVersion(path: string, version: string): boolean;
+/**
+ * The identity `deleteEntries` captures for a downloads-cache jar at listing
+ * time, so a prune that only ever looked at the file once cannot destroy a
+ * concurrent resolve's freshly-written replacement at the same path.
+ *
+ * A missing, unreadable, or malformed sidecar answers with no identity to
+ * prove - {@link discardCachedDownload} already treats that as licence to
+ * evict unconditionally, the "cannot prove otherwise" rule this module's own
+ * sidecar-less entries already rely on elsewhere.
+ *
+ * Exported for direct testing, the same way {@link pathContainsVersion} is.
+ */
+export declare function readDownloadEntryIdentity(jarPath: string): Promise<{
+    url: string;
+    contentSha256: string;
+} | undefined>;
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;

package/dist/cache-registry.js

@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
 import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizeOptionalPathForHost } from "./path-converter.js";
-import { downloadSidecarPath, isDownloadSidecarPath } from "./repo-downloader.js";
+import { discardCachedDownload, downloadSidecarPath, isDownloadSidecarPath } from "./repo-downloader.js";
 import { openDatabase } from "./storage/db.js";
 import { getProcessWorkspaceContextCache } from "./workspace-context-cache.js";
 export const PUBLIC_CACHE_KINDS = [
@@ -528,6 +528,33 @@ async function downloadSidecarSizeBytes(downloadPath) {
         return 0;
     }
 }
+/**
+ * The identity `deleteEntries` captures for a downloads-cache jar at listing
+ * time, so a prune that only ever looked at the file once cannot destroy a
+ * concurrent resolve's freshly-written replacement at the same path.
+ *
+ * A missing, unreadable, or malformed sidecar answers with no identity to
+ * prove - {@link discardCachedDownload} already treats that as licence to
+ * evict unconditionally, the "cannot prove otherwise" rule this module's own
+ * sidecar-less entries already rely on elsewhere.
+ *
+ * Exported for direct testing, the same way {@link pathContainsVersion} is.
+ */
+export async function readDownloadEntryIdentity(jarPath) {
+    try {
+        const parsed = JSON.parse(await readFile(downloadSidecarPath(jarPath), "utf8"));
+        if (typeof parsed.url === "string" &&
+            typeof parsed.contentSha256 === "string" &&
+            parsed.contentSha256.length > 0) {
+            return { url: parsed.url, contentSha256: parsed.contentSha256 };
+        }
+    }
+    catch {
+        // Missing, unreadable, or malformed sidecar: nothing to identify these
+        // bytes with.
+    }
+    return undefined;
+}
 /**
  * Binary-remap cache entries are keyed by the final artifact id even when the
  * on-disk entry is a corrupt final directory or a leftover temp path.
@@ -682,7 +709,19 @@ export function createCacheRegistry(config) {
         async deleteEntries(input) {
             const entries = await collectEntries(input.cacheKinds, input.selector);
             const selectedBytes = entries.reduce((total, entry) => total + entry.sizeBytes, 0);
+            const warnings = [];
+            const failedEntries = [];
             if (input.executionMode === "apply") {
+                // Captured now, against the listing this call just made, rather than
+                // re-read right before each unlink below: the identity has to describe
+                // what THIS call selected, not whatever a concurrent resolve may have
+                // already replaced it with by the time the loop below reaches it.
+                const downloadIdentities = new Map();
+                for (const entry of entries) {
+                    if (entry.cacheKind === "downloads") {
+                        downloadIdentities.set(entry.path, await readDownloadEntryIdentity(entry.path));
+                    }
+                }
                 const db = openDb(config);
                 try {
                     for (const entry of entries) {
@@ -695,12 +734,40 @@ export function createCacheRegistry(config) {
                             continue;
                         }
                         if (entry.cacheKind === "downloads") {
-                            // The sidecar is part of this entry, so it goes with the jar —
-                            // outside the existsSync guard below, so a jar that vanished
-                            // out-of-band since the listing still takes its sidecar with it
-                            // instead of leaving an orphan behind. `force` makes a missing
-                            // sidecar a no-op.
-                            await rm(downloadSidecarPath(entry.path), { force: true });
+                            // Route through the same sidecar-identity check every other
+                            // eviction of this shared cache goes through, instead of an
+                            // unconditional unlink that cannot tell a poisoned jar from a
+                            // concurrent resolve's good one sitting at the same path. This
+                            // also retires the sidecar, so it goes with the jar exactly as
+                            // before - but only when the check above says the jar is still
+                            // the one this call listed. See discardCachedDownload's doc
+                            // comment in repo-downloader.ts for what the check does and does
+                            // not close.
+                            const expectedIdentity = downloadIdentities.get(entry.path);
+                            discardCachedDownload(entry.path, expectedIdentity);
+                            // discardCachedDownload swallows a genuine unlink failure
+                            // (EACCES, EBUSY, a locked file, ...) - documented there as an
+                            // accepted limitation for its own best-effort callers. That is
+                            // wrong for this explicit, user-facing delete/prune request:
+                            // verify the postcondition instead of trusting the call's
+                            // silence. The jar surviving is only a LEGITIMATE decline when
+                            // the identity recorded beside it now genuinely differs from
+                            // what this call captured at listing time - i.e. a concurrent
+                            // resolve's replacement is sitting there, exactly the case
+                            // discardCachedDownload itself declines for. A jar that is
+                            // still present with no such change (or no readable identity at
+                            // all) means the removal itself failed.
+                            if (existsSync(entry.path)) {
+                                const currentIdentity = await readDownloadEntryIdentity(entry.path);
+                                const declinedForConcurrentReplacement = expectedIdentity !== undefined &&
+                                    currentIdentity !== undefined &&
+                                    currentIdentity.contentSha256 !== expectedIdentity.contentSha256;
+                                if (!declinedForConcurrentReplacement) {
+                                    warnings.push(`Could not delete cached download (it may be locked or read-only): ${entry.path}`);
+                                    failedEntries.push(entry);
+                                }
+                            }
+                            continue;
                         }
                         if (existsSync(entry.path)) {
                             // Only binary-remap inventory can return directories as entries;
@@ -713,10 +780,11 @@ export function createCacheRegistry(config) {
                     db?.close();
                 }
             }
+            const failedBytes = failedEntries.reduce((total, entry) => total + entry.sizeBytes, 0);
             return {
-                deletedEntries: entries.length,
-                deletedBytes: selectedBytes,
-                warnings: []
+                deletedEntries: entries.length - failedEntries.length,
+                deletedBytes: selectedBytes - failedBytes,
+                warnings
             };
         },
         async pruneEntries(input) {

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

@@ -78,6 +78,15 @@ export declare class JsonRpcFrameReader {
     private awaitedBodyStart;
     private idleTimer;
     private fatal;
+    /**
+     * Set when an oversized, not-yet-terminated line/header-less run was just
+     * discarded with no newline in hand. The bytes that eventually complete
+     * that same logical line are not a delimiter the reader can trust as the
+     * start of a fresh frame, so every byte up to and including the next 0x0a —
+     * however many chunks it takes to arrive — is swallowed unread before
+     * normal parsing resumes. See `rejectOversizedIncompleteInput`.
+     */
+    private discardingOversizedLine;
     /**
      * @param options.maxFrameBytes Largest accepted frame; defaults to
      *   {@link loadMaxFrameBytes}.
@@ -128,6 +137,17 @@ export declare class JsonRpcFrameReader {
      * a caller that does not still gets a live pair rather than a stale one.
      */
     private armIdleTimer;
+    /**
+     * Whether the buffer, despite `mode` still sticking at "content-length"
+     * from an earlier frame, actually opens a line-mode frame — the same probe
+     * `readContentLengthMessage` uses to detect the mid-stream switch back to
+     * line framing (a JSON object/array opener can never begin a Content-Length
+     * header block). Used to keep the header-size ceiling scoped to buffers
+     * still being accumulated as a header block, so it never judges a line
+     * frame's bytes as an oversized header just because the switch hasn't been
+     * recognized yet.
+     */
+    private looksLikeLineFrame;
     private canCompleteFrame;
     private rejectOversizedIncompleteInput;
     /**

package/dist/json-rpc-framing.js

@@ -40,8 +40,10 @@ const clearIdleTimerHandle = (handle) => {
  *
  * Consequence worth stating, because it is load-bearing for the caller: an
  * EXTRA empty line after the terminator is body, not header. The body window
- * then opens on that empty line and is shifted by the two or three bytes the
- * peer did not count, so it no longer covers the same span as the JSON value.
+ * then opens on that empty line, shifted by however many bytes that line's own
+ * terminator took — one for a bare LF, two for CRLF — bytes the peer's
+ * declared length did not count, so the window no longer covers the same span
+ * as the JSON value.
  * All four extra-blank-line shapes behave alike here, which is the point: the
  * reading does not depend on which terminator style the peer chose.
  *
@@ -171,6 +173,15 @@ export class JsonRpcFrameReader {
     awaitedBodyStart = -1;
     idleTimer;
     fatal = false;
+    /**
+     * Set when an oversized, not-yet-terminated line/header-less run was just
+     * discarded with no newline in hand. The bytes that eventually complete
+     * that same logical line are not a delimiter the reader can trust as the
+     * start of a fresh frame, so every byte up to and including the next 0x0a —
+     * however many chunks it takes to arrive — is swallowed unread before
+     * normal parsing resumes. See `rejectOversizedIncompleteInput`.
+     */
+    discardingOversizedLine = false;
     /**
      * @param options.maxFrameBytes Largest accepted frame; defaults to
      *   {@link loadMaxFrameBytes}.
@@ -206,6 +217,7 @@ export class JsonRpcFrameReader {
         this.awaitedFrameEnd = -1;
         this.awaitedBodyStart = -1;
         this.fatal = false;
+        this.discardingOversizedLine = false;
     }
     clear() {
         this.clearIdleTimer();
@@ -216,6 +228,7 @@ export class JsonRpcFrameReader {
         this.awaitedFrameEnd = -1;
         this.awaitedBodyStart = -1;
         this.fatal = false;
+        this.discardingOversizedLine = false;
     }
     processChunk(chunk, handlers) {
         if (chunk.length === 0 || this.fatal) {
@@ -242,6 +255,24 @@ export class JsonRpcFrameReader {
         this.pendingBytes = 0;
         while (true) {
             try {
+                if (this.discardingOversizedLine) {
+                    // Swallow bytes up to and including the next newline WITHOUT
+                    // interpreting them as a frame — they are the tail of the line just
+                    // rejected as oversized, not a fresh start, even if they happen to
+                    // look like a well-formed message on their own. Only once that
+                    // terminator is found does this resynchronize on the byte position
+                    // the peer itself delimited.
+                    const newlineIndex = this.buffer.indexOf(0x0a);
+                    if (newlineIndex === -1) {
+                        // The discarded bytes carry no information, so there is nothing
+                        // to hold onto while waiting for the terminator.
+                        this.buffer = Buffer.alloc(0);
+                        return;
+                    }
+                    this.buffer = this.buffer.subarray(newlineIndex + 1);
+                    this.discardingOversizedLine = false;
+                    continue;
+                }
                 this.rejectOversizedIncompleteInput();
                 if (this.mode === "unknown") {
                     const detected = this.detectMode();
@@ -297,6 +328,7 @@ export class JsonRpcFrameReader {
                     this.buffer = Buffer.alloc(0);
                     this.pendingChunks = [];
                     this.pendingBytes = 0;
+                    this.discardingOversizedLine = false;
                     handlers.onError(error);
                     return;
                 }
@@ -361,6 +393,28 @@ export class JsonRpcFrameReader {
         handle = this.scheduleTimer(expire, this.incompleteFrameIdleMs);
         this.idleTimer = handle;
     }
+    /**
+     * Whether the buffer, despite `mode` still sticking at "content-length"
+     * from an earlier frame, actually opens a line-mode frame — the same probe
+     * `readContentLengthMessage` uses to detect the mid-stream switch back to
+     * line framing (a JSON object/array opener can never begin a Content-Length
+     * header block). Used to keep the header-size ceiling scoped to buffers
+     * still being accumulated as a header block, so it never judges a line
+     * frame's bytes as an oversized header just because the switch hasn't been
+     * recognized yet.
+     */
+    looksLikeLineFrame() {
+        let probeIndex = 0;
+        while (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x20 ||
+                this.buffer[probeIndex] === 0x09 ||
+                this.buffer[probeIndex] === 0x0d ||
+                this.buffer[probeIndex] === 0x0a)) {
+            probeIndex += 1;
+        }
+        return (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x7b /* '{' */ || this.buffer[probeIndex] === 0x5b /* '[' */));
+    }
     canCompleteFrame(chunk) {
         const bufferedBytes = this.buffer.length + this.pendingBytes;
         if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
@@ -373,8 +427,17 @@ export class JsonRpcFrameReader {
         return chunk.includes(0x0a) || bufferedBytes > this.maxFrameBytes;
     }
     rejectOversizedIncompleteInput() {
-        const headerBoundary = this.mode === "content-length" ? findHeaderBoundary(this.buffer) : undefined;
-        if (this.mode === "content-length" &&
+        // Sticky "content-length" mode only means a header block is being
+        // accumulated when the buffer doesn't already look like a line frame; a
+        // JSON object/array opener here is the same mid-stream switch
+        // `readContentLengthMessage` recognizes, just not yet reached. The header
+        // ceiling below must be scoped to actual header accumulation, or a large
+        // line-mode frame arriving right after a Content-Length frame gets judged
+        // as an oversized header before the switch is detected.
+        const isLineFrameAfterContentLength = this.mode === "content-length" && this.looksLikeLineFrame();
+        const inHeaderAccumulation = this.mode === "content-length" && !isLineFrameAfterContentLength;
+        const headerBoundary = inHeaderAccumulation ? findHeaderBoundary(this.buffer) : undefined;
+        if (inHeaderAccumulation &&
             !headerBoundary &&
             this.buffer.length > MAX_CONTENT_LENGTH_HEADER_BYTES) {
             // No header terminator anywhere in an over-limit header block: there is
@@ -387,15 +450,25 @@ export class JsonRpcFrameReader {
         if (this.buffer.length <= this.maxFrameBytes) {
             return;
         }
-        if (this.mode === "content-length" && headerBoundary) {
+        if (inHeaderAccumulation && headerBoundary) {
             return;
         }
-        if (this.mode !== "content-length" && this.buffer.includes(0x0a)) {
+        if (!inHeaderAccumulation && this.buffer.includes(0x0a)) {
             return;
         }
         const observedBytes = this.buffer.length;
-        const description = this.mode === "line" ? "Line-delimited JSON-RPC frame" : "Headerless JSON-RPC input";
+        const description = this.mode === "line" || isLineFrameAfterContentLength
+            ? "Line-delimited JSON-RPC frame"
+            : "Headerless JSON-RPC input";
         this.buffer = Buffer.alloc(0);
+        if (!inHeaderAccumulation) {
+            // The oversized run has no newline anywhere in it yet (the check above
+            // would otherwise have returned): remember to swallow bytes through the
+            // eventual terminator — wherever it arrives — before resuming normal
+            // parsing, so the discarded line's own tail is never re-read as a fresh
+            // frame (see `discardingOversizedLine` in `drainChunk`).
+            this.discardingOversizedLine = true;
+        }
         throw new Error(`${description} is ${observedBytes} bytes, exceeding the configured frame limit of ` +
             `${this.maxFrameBytes} bytes.`);
     }

package/dist/mapping/loaders/tiny-maven.d.ts

@@ -1,2 +1,11 @@
+import type { DirectionIndex, PairKey } from "../internal-types.js";
 import type { MappingLoaderDeps, MappingLoaderResult } from "./types.js";
+/**
+ * `maxEntryBytes` reuses the same ceiling as nested-jar extraction
+ * ({@link loadMaxNestedJarEntryBytes}): the downloaded jar is itself
+ * download-size-capped, but a single `.tiny`/`.tinyv2` entry inside it is
+ * decompressed in full before parsing, so an entry with a small compressed
+ * size and a huge inflated size (zip-bomb style) must still be bounded here.
+ */
+export declare function parseTinyFromJar(jarPath: string, maxEntryBytes?: number): Promise<Map<PairKey, DirectionIndex>>;
 export declare function loadTinyPairsFromMaven(deps: MappingLoaderDeps, version: string): Promise<MappingLoaderResult>;

package/dist/mapping/loaders/tiny-maven.js

@@ -1,4 +1,5 @@
 import { defaultDownloadPath, downloadToCache } from "../../repo-downloader.js";
+import { loadMaxNestedJarEntryBytes } from "../../source/nested-jars.js";
 import { collectMatchedJarEntriesAsUtf8 } from "../../source-jar-reader.js";
 import { mergeDirectionIndexes } from "../parsers/symbol-records.js";
 import { parseTinyMappingsInto } from "../parsers/tiny.js";
@@ -27,8 +28,15 @@ async function fetchYarnCoordinates(fetchFn, repoBase, version) {
         return [version];
     }
 }
-async function parseTinyFromJar(jarPath) {
-    const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
+/**
+ * `maxEntryBytes` reuses the same ceiling as nested-jar extraction
+ * ({@link loadMaxNestedJarEntryBytes}): the downloaded jar is itself
+ * download-size-capped, but a single `.tiny`/`.tinyv2` entry inside it is
+ * decompressed in full before parsing, so an entry with a small compressed
+ * size and a huge inflated size (zip-bomb style) must still be bounded here.
+ */
+export async function parseTinyFromJar(jarPath, maxEntryBytes = loadMaxNestedJarEntryBytes()) {
+    const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true, maxBytes: maxEntryBytes })).sort((left, right) => left.filePath.localeCompare(right.filePath));
     // Parsed straight into the shared accumulator: a parse-then-merge loop would
     // hold each entry's full index alongside the accumulated one. `ensurePairIndex`
     // + `addLookupEntries` union into what is already there, matching what

package/dist/repo-downloader.js

@@ -771,13 +771,24 @@ async function cachedBytesResult(url, destinationPath, sidecar, cacheStatus) {
  * a zip reader opens it - so it must satisfy neither an immutable hit nor a
  * stale-if-error fallback. Treating it as absent lets the next transfer replace
  * it instead of pinning it forever.
+ *
+ * That equivalence stops at "missing", the same line {@link describeFileIfPresent}
+ * draws: only {@link isMissingFileError} answers a cache miss. A present-but-
+ * unreadable entry (EACCES from a locked-down cache directory, EISDIR, EIO)
+ * propagates instead of collapsing to 0, because this is the first stat this
+ * module makes on the path - collapsing it here would let `resolveCachedDownload`
+ * read "no cached bytes" and fall through to a live transfer without ever
+ * reaching the read path that already reports this failure correctly.
  */
 function cachedByteCount(filePath) {
     try {
         return statSync(filePath).size;
     }
-    catch {
-        return 0;
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return 0;
+        }
+        throw error;
     }
 }
 /**

package/dist/source/class-source.js

@@ -9,6 +9,7 @@ import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, pro
 import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
 import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
+import { extractSymbolsFromSource } from "../symbols/symbol-extractor.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, inheritArtifactMapping, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
@@ -407,6 +408,50 @@ function projectDecompiledFallback(fallback, level) {
 // The class-like symbol kinds findClass returns. MUST stay in sync with the JS-side
 // isTypeSymbol checks below; pushed down to SQL so non-type rows are never fetched.
 const TYPE_SYMBOL_KINDS = ["class", "interface", "enum", "record"];
+/**
+ * Reconstruct the full nesting chain between a file's top-level type and a
+ * type declared two or more levels deeper inside it. The extractor stores
+ * only ONE qualifiedName per FILE (the top-level type), so naively
+ * concatenating `<topLevelFQN>.<symbolName>` is only correct for exactly one
+ * level of nesting — it silently drops every intermediate enclosing type.
+ *
+ * Walks the file's own type declarations from the top-level type downward,
+ * using brace-range containment to find which declaration directly encloses
+ * `targetLine` at each level, collecting each intermediate simple name.
+ *
+ * Returns the intermediate simple names (outermost first, target excluded)
+ * or undefined when the chain cannot be reconstructed — e.g. the file's
+ * content is unavailable — in which case the caller falls back to the
+ * single-level formula.
+ */
+function resolveNestedTypeChain(svc, artifactId, filePath, topSimpleName, targetLine) {
+    const fileRow = svc.filesRepo.getFileContent(artifactId, filePath);
+    if (!fileRow)
+        return undefined;
+    const lines = fileRow.content.split(/\r?\n/);
+    const fileSymbols = extractSymbolsFromSource(filePath, fileRow.content);
+    let currentBody = classSourceHelpers.computeBraceRange(lines, fileSymbols, topSimpleName);
+    if (!currentBody)
+        return undefined;
+    const chain = [];
+    // Bounded by the number of type symbols in the file; guards against ever
+    // looping on a malformed structure.
+    for (let step = 0; step <= fileSymbols.length; step += 1) {
+        const childRanges = classSourceHelpers.computeNestedTypeRanges(lines, fileSymbols, currentBody);
+        if (childRanges.some((range) => range.declarationLine === targetLine)) {
+            return chain;
+        }
+        const containingChild = childRanges.find((range) => range.declarationLine < targetLine && targetLine <= range.endLine);
+        if (!containingChild)
+            return undefined;
+        const childSymbol = fileSymbols.find((symbol) => symbol.line === containingChild.declarationLine);
+        if (!childSymbol)
+            return undefined;
+        chain.push(childSymbol.symbolName);
+        currentBody = containingChild;
+    }
+    return undefined;
+}
 export function findClass(svc, input) {
     const className = input.className.trim();
     if (!className) {
@@ -500,8 +545,18 @@ export function findClass(svc, input) {
         const enclosingQualifiedName = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
         const enclosingSimpleName = enclosingQualifiedName.split(".").at(-1) ?? enclosingQualifiedName;
         const nested = enclosingSimpleName !== row.symbolName;
+        let qualifiedName = nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName;
+        if (nested) {
+            // The formula above assumes exactly one level of nesting. When the type
+            // is nested two or more levels deep, reconstruct the real chain so the
+            // intermediate enclosing type(s) are not silently dropped.
+            const intermediateChain = resolveNestedTypeChain(svc, artifactId, row.filePath, enclosingSimpleName, row.line);
+            if (intermediateChain && intermediateChain.length > 0) {
+                qualifiedName = `${enclosingQualifiedName}.${[...intermediateChain, row.symbolName].join(".")}`;
+            }
+        }
         candidates.push({
-            qualifiedName: nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName,
+            qualifiedName,
             filePath: row.filePath,
             line: row.line,
             symbolKind: row.symbolKind,

package/dist/stdio-supervisor.js

@@ -1928,8 +1928,10 @@ export class StdioSupervisor {
                     message: detail
                 });
             });
+            const key = requestKey(entry.pending.id);
+            let released = false;
+            let attemptedRelease = false;
             this.runRecoveryStep("queue.dispatch_settle", () => {
-                const key = requestKey(entry.pending.id);
                 // Only THIS instance may be settled here. A fault before forwardRequest
                 // installed anything leaves the request re-queued by its own no-child
                 // fallback (a later drain owns it) or already answered by the
@@ -1937,17 +1939,51 @@ export class StdioSupervisor {
                 // different live request, which keeps its own guarantee.
                 if (this.pendingRequests.get(key) !== entry.pending)
                     return;
-                if (!this.releaseForwardedRequest(key, entry.pending))
-                    return;
-                this.writeSyntheticReply(entry.pending, {
-                    jsonrpc: "2.0",
-                    id: entry.pending.id,
-                    error: {
-                        code: -32603,
-                        message: `MCP supervisor failed to dispatch the queued request: ${detail}`
-                    }
-                });
+                attemptedRelease = true;
+                released = this.releaseForwardedRequest(key, entry.pending);
             });
+            if (attemptedRelease && !released) {
+                // releaseForwardedRequest deletes the entry and records its tombstone
+                // BEFORE it returns, so a throw part-way through (recordFinalityTombstone's
+                // only throw site today is the debug-log call during tombstone
+                // eviction) can still have taken the id away from its entry. `released`
+                // cannot tell "declined" apart from "threw after mutating", so the id
+                // is read back rather than assumed — mirrors
+                // answerFaultedWorkerResponse's worker_message.release_verify.
+                //
+                // Gated on `attemptedRelease`, not merely `!released`: the identity
+                // check above (`pendingRequests.get(key) !== entry.pending`) returns
+                // early, WITHOUT calling releaseForwardedRequest, whenever this entry
+                // was never installed into pendingRequests to begin with — which is
+                // exactly what happens when forwardRequest's no-child fallback re-queues
+                // this same entry (queue not full) or already answered it itself (queue
+                // full) before throwing later in that same fallback (e.g. from
+                // scheduleRestart). In either of those cases the id is either still
+                // waiting for a real dispatch that will answer it for real later, or
+                // already answered — and this verify step cannot distinguish "never
+                // installed" from "installed, then removed by a throwing release" using
+                // `pendingRequests.has(key)` alone. Running it anyway would record a
+                // spurious tombstone and send a synthetic reply for a request that gets
+                // (or already got) a real one, i.e. two replies for the same id.
+                this.runRecoveryStep("queue.dispatch_settle_verify", () => {
+                    if (entry.pending.method === "initialize" || this.pendingRequests.has(key))
+                        return;
+                    this.recordFinalityTombstone(key, entry.pending.mode);
+                    released = true;
+                });
+            }
+            if (released) {
+                this.runRecoveryStep("queue.dispatch_reply", () => {
+                    this.writeSyntheticReply(entry.pending, {
+                        jsonrpc: "2.0",
+                        id: entry.pending.id,
+                        error: {
+                            code: -32603,
+                            message: `MCP supervisor failed to dispatch the queued request: ${detail}`
+                        }
+                    });
+                });
+            }
             return false;
         }
     }
@@ -1966,7 +2002,7 @@ export class StdioSupervisor {
         }
         catch (error) {
             log("error", "supervisor.worker_spawn_throw", {
-                message: error instanceof Error ? error.message : String(error)
+                message: describeThrown(error)
             });
             this.handleStartupFailure(token, { code: null, signal: null });
             return;
@@ -2166,7 +2202,33 @@ export class StdioSupervisor {
             // cap allows. That successor arms a fresh startup watchdog and, on
             // ready, re-forwards the retained initialize (handleWorkerReady), so the
             // handshake gets a second chance instead of stalling.
+            //
+            // Replacing the generation does not by itself terminalize any OTHER
+            // request forwarded to the old child: when its `exit` eventually fires,
+            // `handleWorkerExit` finds `this.child` already pointing at the
+            // successor and takes its early-return branch, skipping
+            // failPendingRequestsOnWorkerExit entirely. So that call runs here
+            // first, mirroring the precedent at handleWorkerProcessError, and BEFORE
+            // recoverTimedOutWorker replaces the generation. It does not touch the
+            // retained `initialize` itself: failPendingRequestsOnWorkerExit carves
+            // out `this.initializeRequest`'s key, which is exactly the entry this
+            // lifecycle is about to continue on the successor.
+            //
+            // Split into two independent recovery steps, deliberately: these are two
+            // unrelated effects (terminalizing OTHER stranded requests, and replacing
+            // the generation so the retained initialize gets a second chance), and
+            // they must not share a fault boundary. Before failPendingRequestsOnWorkerExit
+            // existed here, recoverTimedOutWorker was the only statement in this step
+            // and ran unconditionally on any path that reached it. Running both in one
+            // `runRecoveryStep` would let a throw inside failPendingRequestsOnWorkerExit
+            // (e.g. its own timerClearer call faulting for some OTHER pending
+            // request's deadline timer) silently swallow the call to
+            // recoverTimedOutWorker that follows it in the same callback — silently
+            // skipping the one guarantee this whole branch exists to provide.
             if (pending.method === "initialize") {
+                this.runRecoveryStep("worker_message.initialize_recovery_fail_pending", () => {
+                    this.failPendingRequestsOnWorkerExit({ code: null, signal: null });
+                });
                 this.runRecoveryStep("worker_message.initialize_recovery", () => {
                     this.recoverTimedOutWorker();
                 });
@@ -2219,6 +2281,37 @@ export class StdioSupervisor {
             return;
         }
         log("warn", "supervisor.worker_stdin_error", { message: error.message });
+        // This event fires only on child.stdin, which exists only once the child
+        // has actually been spawned, but that does NOT collapse to a single
+        // "always post-ready" case: handleWorkerReady's legacy-era replay of a
+        // retained `initialize` (era === "legacy" with `this.initializeRequest`
+        // set) forwards it to a freshly spawned successor WITHOUT calling
+        // adoptActiveChild first — adoptActiveChild only runs once that
+        // initialize's response actually comes back, or on the no-replay early
+        // return. So a live child can have `child.stdin` while `this.childReady`
+        // is still false, mirroring the fork handleWorkerProcessError already
+        // makes on `wasReady`. Treating that window as post-ready would run
+        // failPendingRequestsOnWorkerExit, which deliberately carves the retained
+        // initialize's pending entry OUT of what it fails (so a later id reuse of
+        // the completed initialize is not wrongly caught) — leaving the client's
+        // `initialize` answered by nothing and re-replayed against every
+        // successor forever if the stdin fault persists. Before this recovery
+        // existed at all, a broken stdin left `this.child` pointing at a worker
+        // nothing could ever write to again: scheduleRestart's own `this.child`
+        // guard made every later restart attempt a permanent no-op, and any
+        // request already forwarded to this child had nothing left that would
+        // ever answer it.
+        const wasReady = this.childReady;
+        this.invalidateCurrentChild(child);
+        this.beginTreeTermination(child);
+        if (!wasReady) {
+            this.handleStartupFailure(this.attemptToken, { code: null, signal: null });
+        }
+        else {
+            this.consecutiveImmediateStandDowns = 0;
+            this.failPendingRequestsOnWorkerExit({ code: null, signal: null });
+            this.scheduleRestart(true);
+        }
     }
     /**
      * Reassembles the worker's stderr into lines (the ready marker may be split
@@ -2379,13 +2472,17 @@ export class StdioSupervisor {
         if (this.isInitializationResponse(message)) {
             const id = getTrackedRequestId(message);
             let initializeMode;
+            let initializeKey;
+            let initializePending;
             if (id !== undefined) {
-                const key = requestKey(id);
-                initializeMode = this.pendingRequests.get(key)?.mode;
-                this.pendingRequests.delete(key);
+                initializeKey = requestKey(id);
+                initializePending = this.pendingRequests.get(initializeKey);
+                initializeMode = initializePending?.mode;
             }
             initializeMode ??= this.modeForMessage(this.initializeRequest);
             if ("error" in message) {
+                if (initializeKey !== undefined)
+                    this.pendingRequests.delete(initializeKey);
                 if (!this.replayingInitialization && id !== undefined) {
                     this.writeSyntheticReply({ id, era: this.era, mode: initializeMode }, buildLegacyJsonRpcError(id));
                     const retainedIndex = this.queuedNotifications.findIndex((entry) => isRequest(entry) && requestKey(entry.id) === requestKey(id));
@@ -2401,6 +2498,8 @@ export class StdioSupervisor {
                 return;
             }
             if (this.replayingInitialization) {
+                if (initializeKey !== undefined)
+                    this.pendingRequests.delete(initializeKey);
                 this.replayingInitialization = false;
                 if (this.initializedNotification) {
                     this.writeToWorker(child, this.initializedNotification);
@@ -2409,9 +2508,22 @@ export class StdioSupervisor {
                 this.flushQueue();
                 return;
             }
+            // Mark the entry as settling and remove it BEFORE writeToClient, so a
+            // throw there (or in the diagnostic write reporting that throw) still
+            // leaves `settlingWorkerResponse` for `answerUndeliveredWorkerResponse`
+            // to answer this id from later — mirrors the non-initialize response
+            // path below, which does the same for every other successful reply.
+            // Without this, the entry was gone and no marker recorded it, so a
+            // faulted client write here permanently lost the reply to `initialize`.
+            if (initializeKey !== undefined && initializePending) {
+                this.settlingWorkerResponse = { key: initializeKey, snapshot: initializePending };
+            }
+            if (initializeKey !== undefined)
+                this.pendingRequests.delete(initializeKey);
             this.clientInitialized = true;
             this.adoptActiveChild();
             this.writeToClient(message, initializeMode);
+            this.settlingWorkerResponse = undefined;
             this.flushQueue();
             return;
         }
@@ -2446,13 +2558,19 @@ export class StdioSupervisor {
                     // branch above, never here.
                     this.settlingWorkerResponse = { key, snapshot: pending };
                 }
-                if (pending?.deadlineTimer)
-                    this.timerClearer(pending.deadlineTimer);
+                // These two clears run BEFORE timerClearer: a validate-project id must
+                // not stay "running" if the timer clear below throws. answerUndelivered-
+                // WorkerResponse (which later answers this id via settlingWorkerResponse
+                // on a writeToClient/drainQueue fault) never touches these two fields,
+                // so leaving them ordered after a throwing call would strand the
+                // barrier and every validate-project admitted behind it, permanently.
                 if (pending?.toolName === "validate-project") {
                     this.runningValidateKey = undefined;
                     if (this.validateBarrierKey === key)
                         this.validateBarrierKey = undefined;
                 }
+                if (pending?.deadlineTimer)
+                    this.timerClearer(pending.deadlineTimer);
             }
         }
         this.writeToClient(message, responseMode);
@@ -2558,7 +2676,12 @@ export class StdioSupervisor {
         // count to N and falsely escalate retryRecommendation to "report-bug".
         const pendingToolNames = [];
         for (const [key, pending] of this.pendingRequests.entries()) {
-            if (key === preservedInitializeKey)
+            // Identity, not just id: a client may legally reuse `initialize`'s id
+            // for a later request once initialize has completed. `initializeRequest`
+            // (and so `preservedInitializeKey`) is retained past that point, so a
+            // bare key match would treat the REUSED entry as the still-pending
+            // initialize and skip it here — leaving it answered by nothing.
+            if (key === preservedInitializeKey && pending.method === "initialize")
                 continue;
             pendingToolNames.push(pending.toolName);
         }
@@ -2566,23 +2689,59 @@ export class StdioSupervisor {
         for (const [toolName, updated] of updatedByTool) {
             this.recentRestarts.set(toolName, updated);
         }
+        // Each entry's cleanup and its reply run as two SEPARATE recovery steps,
+        // not one bundled try around the whole loop body. Fault containment must
+        // be per-entry, not just per-function: a throw from `this.timerClearer`
+        // (or anything else in the cleanup half) for entry N must not abort the
+        // `for` loop, or every entry after N in Map iteration order is left
+        // completely unprocessed — not answered, and not cleared from
+        // runningValidateKey/validateBarrierKey either. Since the old worker's
+        // own `exit`/`error` handling short-circuits once `this.child` already
+        // points at a successor generation, a request stranded that way here is
+        // stranded permanently, and a stranded validate-project holding the
+        // barrier keys would jam every later validate-project request behind it
+        // forever. Splitting into two steps also means a fault in ONE entry's
+        // cleanup cannot suppress that SAME entry's own reply.
         for (const [key, pending] of [...this.pendingRequests.entries()]) {
-            if (key === preservedInitializeKey)
+            // See the identical guard above: a bare key match would also wrongly
+            // skip a request that legally reused the completed initialize's id.
+            if (key === preservedInitializeKey && pending.method === "initialize")
                 continue;
-            if (pending.deadlineTimer)
-                this.timerClearer(pending.deadlineTimer);
-            if (this.runningValidateKey === key)
-                this.runningValidateKey = undefined;
-            if (this.validateBarrierKey === key)
-                this.validateBarrierKey = undefined;
-            // Forwarded entries stay in pendingRequests until writeSyntheticReply
-            // settles them (the FORWARDED pending is what entitles the id to a
-            // finality tombstone). Cancelled entries are already gone — the
-            // cancellation settled them terminally at admission.
-            const toolName = pending.toolName ?? "unknown";
-            const pruned = prunedByTool.get(toolName) ?? [];
-            const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
-            this.writeSyntheticReply(pending, reply);
+            this.runRecoveryStep("worker_exit.fail_pending_cleanup", () => {
+                if (this.runningValidateKey === key)
+                    this.runningValidateKey = undefined;
+                if (this.validateBarrierKey === key)
+                    this.validateBarrierKey = undefined;
+                // Nil the field immediately after clearing, matching the convention
+                // releaseForwardedRequest already uses. writeSyntheticReply (below,
+                // in the SEPARATE fail_pending_reply step) also does
+                // `if (pending.deadlineTimer) this.timerClearer(...)` before it
+                // deletes the entry from pendingRequests. If this step cleared the
+                // timer but left the field set, that second check would still be
+                // true and writeSyntheticReply would attempt a REDUNDANT second
+                // clear of the SAME already-cleared timer. A timerClearer that
+                // faults on a repeat invocation for the same timer would then throw
+                // BEFORE writeSyntheticReply's delete/tombstone — unlike a fault
+                // strictly after deletion (which only loses that one reply), this
+                // would leave the entry live in pendingRequests forever, with
+                // nothing left to remove or answer it. Nilling here makes
+                // writeSyntheticReply's own check false, so it never attempts that
+                // second clear at all.
+                if (pending.deadlineTimer) {
+                    this.timerClearer(pending.deadlineTimer);
+                    pending.deadlineTimer = undefined;
+                }
+            });
+            this.runRecoveryStep("worker_exit.fail_pending_reply", () => {
+                // Forwarded entries stay in pendingRequests until writeSyntheticReply
+                // settles them (the FORWARDED pending is what entitles the id to a
+                // finality tombstone). Cancelled entries are already gone — the
+                // cancellation settled them terminally at admission.
+                const toolName = pending.toolName ?? "unknown";
+                const pruned = prunedByTool.get(toolName) ?? [];
+                const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
+                this.writeSyntheticReply(pending, reply);
+            });
         }
     }
     /**
@@ -2688,7 +2847,7 @@ export class StdioSupervisor {
         }
         catch (error) {
             this.eventWriter("warn", "supervisor.client_write_error", {
-                message: error instanceof Error ? error.message : String(error)
+                message: describeThrown(error)
             });
         }
     }

package/dist/storage/db.js

@@ -135,7 +135,11 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
                     path: config.sqlitePath,
                     reason: errorMessage
                 });
-                throw caughtError;
+                throw createError({
+                    code: ERROR_CODES.DB_FAILURE,
+                    message: `Failed to open SQLite database at ${config.sqlitePath}: ${errorMessage}`,
+                    details: { sqlitePath: config.sqlitePath, reason: caughtError?.code }
+                });
             }
             // The rebuild runs INSIDE the handler for the failure it is recovering
             // from, so it needs a guard of its own: without one a throw from here left

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "7.0.0-rc.3",
+  "version": "7.0.0",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "packageManager": "pnpm@10.30.1",