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

package/dist/source/artifact-resolver.js

@@ -1,4 +1,5 @@
 import fastGlob from "fast-glob";
+import { DECOMPILE_SIGNATURE_QUALIFIER, jarArtifactIdentity } from "../artifact-identity.js";
 import { buildArtifactAlias } from "../config.js";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
@@ -7,9 +8,8 @@ import { log } from "../logger.js";
 import { applyMappingPipeline } from "../mapping-pipeline-service.js";
 import { parseCoordinate } from "../maven-resolver.js";
 import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
-import { artifactSignatureFromFile } from "../path-resolver.js";
 import { detectFabricLikeInputNamespace, listJavaEntries } from "../source-jar-reader.js";
-import { artifactIdForJar, resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
+import { resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
 import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
@@ -562,8 +562,10 @@ export async function probeMinecraftArtifact(svc, input) {
             });
         }
         const selectedSourceJarPath = versionSourceDiscovery.selectedSourceJarPath;
-        const sourceSignature = artifactSignatureFromFile(selectedSourceJarPath).signature;
-        const artifactId = artifactIdForJar("jar", selectedSourceJarPath, sourceSignature);
+        // The same helper `resolveSourceTarget`'s jar branch uses, so the id this
+        // probe publishes and the id a full resolve mints for the same jar are
+        // derived and composed by one piece of code.
+        const { artifactId } = await jarArtifactIdentity(selectedSourceJarPath);
         warnings.push(`Resolved source-backed artifact from Loom cache candidate: ${selectedSourceJarPath}.`);
         if (versionSourceDiscovery.selectedHasMinecraftNamespace === false) {
             warnings.push(`Source coverage does not include net.minecraft for ${selectedSourceJarPath}; class lookups may fall back to the binary artifact.`);
@@ -577,8 +579,14 @@ export async function probeMinecraftArtifact(svc, input) {
             ...(warnings.length > 0 ? { warnings } : {})
         };
     }
-    const binarySignature = artifactSignatureFromFile(versionJar.jarPath).signature;
-    const artifactId = artifactIdForJar("jar", versionJar.jarPath, `${binarySignature}:decompile`);
+    // "Lightweight" describes what this probe SKIPS: it neither decompiles nor
+    // rebuilds the index. It does read the version jar's bytes, because that is
+    // what the jar route derives an id from, so the first probe of a given jar in
+    // a process pays for one hash of it; the digest memo in
+    // `src/artifact-identity.ts` covers the ones after that.
+    const { artifactId } = await jarArtifactIdentity(versionJar.jarPath, {
+        signatureQualifier: DECOMPILE_SIGNATURE_QUALIFIER
+    });
     return {
         artifactId,
         mappingApplied: effectiveMapping,

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/source-resolver.d.ts

@@ -48,7 +48,6 @@ export declare function localM2CoordinateCandidatePaths(localM2Path: string, par
  */
 export declare const BINARY_JAR_NO_CLASSES_FLAG = "binary-jar-no-classes";
 export type { MappingVariant } from "./types.js";
-export declare function artifactIdForJar(inputKind: string, artifactPath: string, signature: string, suffix?: string, mappingVariant?: MappingVariant): string;
 export interface ResolveSourceTargetOptions {
     allowDecompile: boolean;
     preferBinaryOnly?: boolean;

package/dist/source-resolver.js

@@ -1,78 +1,13 @@
-import { statSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { basename, dirname, join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import fastGlob from "fast-glob";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { buildRemoteBinaryUrls, buildRemoteSourceUrls, groupToPath, hasExistingJar, isMutableMavenCoordinate, parseCoordinate, normalizedCoordinateValue } from "./maven-resolver.js";
-import { defaultDownloadPath, digestFile, discardCachedDownload, resolveCachedDownload } from "./repo-downloader.js";
-import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
-import { stableArtifactId } from "./config.js";
+import { defaultDownloadPath, discardCachedDownload, resolveCachedDownload } from "./repo-downloader.js";
+import { normalizeJarPath } from "./path-resolver.js";
+import { composeArtifactId, contentDigestSignature, contentSignature, jarArtifactIdentity, DECOMPILE_SIGNATURE_QUALIFIER } from "./artifact-identity.js";
 import { hasAnyJarEntry, hasJavaSourceExtension } from "./source-jar-reader.js";
-function readStatsSignature(filePath) {
-    const stats = artifactSignatureFromFile(filePath);
-    return stats.signature;
-}
-/**
- * Digests already derived from a local jar, each pinned to the stat that
- * produced it.
- *
- * Keyed by the symlink-resolved path, so a jar reached through two names is
- * hashed once. The entry is only ever *reused*, never trusted on its own: a
- * mismatched mtime or size discards it, so the map cannot serve a digest for
- * bytes that have since been replaced.
- *
- * Bounded, like the helper caches in `src/source/artifact-resolver.ts`: this map
- * is module-level and lives as long as the process, and a long-running server
- * walks this cascade once per target-driven tool call, so an unbounded map grows
- * with every distinct jar path the server has ever seen. Eviction costs at most
- * one re-hash, which is exactly what a cache miss already costs.
- */
-const contentSignatureCache = new Map();
-const MAX_CONTENT_SIGNATURE_CACHE = 512;
-/** Insert, dropping the oldest key first when the bound is reached. */
-function rememberContentSignature(resolvedPath, entry) {
-    if (!contentSignatureCache.has(resolvedPath) && contentSignatureCache.size >= MAX_CONTENT_SIGNATURE_CACHE) {
-        const oldestKey = contentSignatureCache.keys().next().value;
-        if (oldestKey) {
-            contentSignatureCache.delete(oldestKey);
-        }
-    }
-    contentSignatureCache.set(resolvedPath, entry);
-}
-/**
- * The identity of a jar sitting on local disk: a sha256 of its bytes.
- *
- * `~/.m2` and the Gradle module cache move a file's mtime for reasons that have
- * nothing to do with its contents - an eviction followed by a re-fetch of
- * byte-identical bytes, a filesystem restore, a plain `touch`. An `mtimeMs:size`
- * signature turns every one of those into a fresh artifactId and a fresh
- * decompile, which is exactly the instability the download cache's
- * content-addressed identity removed from the remote half of this cascade.
- *
- * Hashing is not free and this cascade is re-walked on every target-driven tool
- * call, so the digest is memoized against the stat that produced it. The stat is
- * taken *before* the digest on purpose: bytes replaced mid-hash are recorded
- * against a stat they no longer have, so the entry is rejected on the next call
- * and re-derived - a wasted hash, never a wrong identity.
- */
-async function contentSignature(jarPath) {
-    // The same normalization `artifactSignatureFromFile` applied, kept so this
-    // path still refuses a vanished or non-jar file the way it always has.
-    const resolvedPath = normalizeJarPath(jarPath);
-    const stats = statSync(resolvedPath);
-    const cached = contentSignatureCache.get(resolvedPath);
-    if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
-        return cached.sha256;
-    }
-    const { contentSha256 } = await digestFile(resolvedPath);
-    rememberContentSignature(resolvedPath, {
-        mtimeMs: stats.mtimeMs,
-        size: stats.size,
-        sha256: contentSha256
-    });
-    return contentSha256;
-}
 /**
  * Whether a jar contains java sources, with archive errors deliberately
  * propagating.
@@ -445,28 +380,20 @@ async function resolveGradleCacheCoordinateCandidate(coordinate) {
 function resolveRemoteBinaryCandidate(coordinate, repos) {
     return buildRemoteBinaryUrls(repos, coordinate);
 }
-export function artifactIdForJar(inputKind, artifactPath, signature, suffix, mappingVariant = "pass") {
-    const parts = [inputKind, artifactPath, signature, suffix ?? "source"];
-    if (mappingVariant === "mojang-remapped") {
-        parts.push("mojang-remapped");
-    }
-    return stableArtifactId(parts);
-}
-function artifactIdForCoordinate(coordinate, source, signature, mappingVariant = "pass") {
-    const parts = ["coord", coordinate, source, signature];
-    if (mappingVariant === "mojang-remapped") {
-        parts.push("mojang-remapped");
-    }
-    return stableArtifactId(parts);
-}
 function resolvedAtNow() {
     return new Date().toISOString();
 }
 /** Shared shape for every artifact the coordinate cascade can return. */
 function coordinateArtifact(spec) {
     return {
-        artifactId: artifactIdForCoordinate(spec.coordinate, spec.idSource, spec.signature, spec.mappingVariant ?? "pass"),
-        artifactSignature: spec.signature,
+        artifactId: composeArtifactId({
+            space: "coordinate",
+            coordinate: spec.coordinate,
+            idSource: spec.idSource,
+            signature: spec.signature,
+            mappingVariant: spec.mappingVariant
+        }),
+        artifactSignature: spec.signature.value,
         origin: spec.origin,
         sourceJarPath: spec.sourceJarPath,
         binaryJarPath: spec.binaryJarPath,
@@ -595,7 +522,6 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
     };
     if (input.kind === "jar") {
         const resolvedJarPath = normalizeJarPath(input.value);
-        const binarySignature = readStatsSignature(resolvedJarPath);
         const exactSourceJarPath = resolveExactJarSourceCandidate(resolvedJarPath);
         const adjacentSourceCandidates = await listAdjacentJarSourceCandidates(resolvedJarPath);
         const maybeAdjacentSourceCandidates = adjacentSourceCandidates.length > 0 ? adjacentSourceCandidates : undefined;
@@ -604,9 +530,10 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             const siblingBinaryJarPath = resolveSiblingBinaryJarCandidate(resolvedJarPath);
             const binaryJarPath = siblingBinaryJarPath ??
                 (basename(resolvedJarPath).endsWith("-sources.jar") ? undefined : resolvedJarPath);
+            const identity = await jarArtifactIdentity(resolvedJarPath);
             return {
-                artifactId: artifactIdForJar("jar", resolvedJarPath, binarySignature),
-                artifactSignature: binarySignature,
+                artifactId: identity.artifactId,
+                artifactSignature: identity.signature,
                 origin: "local-jar",
                 binaryJarPath,
                 sourceJarPath: resolvedJarPath,
@@ -616,10 +543,10 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             };
         }
         if (!preferBinaryOnly && await candidateHasJavaSources(exactSourceJarPath)) {
-            const sourceSignature = readStatsSignature(exactSourceJarPath);
+            const identity = await jarArtifactIdentity(exactSourceJarPath);
             return {
-                artifactId: artifactIdForJar("jar", exactSourceJarPath, sourceSignature),
-                artifactSignature: sourceSignature,
+                artifactId: identity.artifactId,
+                artifactSignature: identity.signature,
                 origin: "local-jar",
                 binaryJarPath: resolvedJarPath,
                 sourceJarPath: exactSourceJarPath,
@@ -648,9 +575,13 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
         // no `.java` entries.
         const subjectArchive = await inspectSubjectJarArchive(resolvedJarPath);
         const subjectQualityFlags = subjectArchive ? binaryJarQualityFlags(subjectArchive) : [];
+        const identity = await jarArtifactIdentity(resolvedJarPath, {
+            signatureQualifier: DECOMPILE_SIGNATURE_QUALIFIER,
+            mappingVariant: options.mappingVariant
+        });
         return {
-            artifactId: artifactIdForJar("jar", resolvedJarPath, `${binarySignature}:decompile`, undefined, options.mappingVariant ?? "pass"),
-            artifactSignature: `${binarySignature}:decompile`,
+            artifactId: identity.artifactId,
+            artifactSignature: identity.signature,
             origin: "decompiled",
             binaryJarPath: resolvedJarPath,
             adjacentSourceCandidates: maybeAdjacentSourceCandidates,
@@ -843,7 +774,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             // Identity follows the bytes. The HTTP validators that used to form this
             // signature rotate whenever a CDN or repository migration happens, even
             // when the jar is byte-identical.
-            const signature = download.contentSha256;
+            const signature = contentDigestSignature(download.contentSha256);
             return coordinateArtifact({
                 coordinate,
                 idSource: "remote-repo",
@@ -983,7 +914,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             }
             // A file in the URL-keyed download cache is identified by its bytes, not
             // by a stat signature that a re-download would change for free.
-            const signature = downloaded.contentSha256;
+            const signature = contentDigestSignature(downloaded.contentSha256);
             return coordinateArtifact({
                 coordinate,
                 idSource: "decompiled",

package/dist/stdio-supervisor.d.ts

@@ -238,6 +238,22 @@ export declare class StdioSupervisor {
      */
     private readonly syntheticTombstones;
     private child;
+    /**
+     * The one response `handleWorkerMessage` is part-way through settling.
+     *
+     * It removes a response's pending entry BEFORE writing the reply, so between
+     * those two statements the id is owed a response that NOTHING records: the
+     * entry is gone, no deadline is armed for anything but validate-project, and
+     * the worker considers the request answered. A fault in that window used to
+     * be indistinguishable from an id already settled, and the request stayed
+     * unanswered for the life of an otherwise healthy session.
+     *
+     * Set the moment the entry is deleted and cleared the moment the write
+     * returns, so it is defined only inside that window and only ever names one
+     * request. `answerFaultedWorkerResponse` is the sole reader, and it consumes
+     * the marker rather than merely reading it.
+     */
+    private settlingWorkerResponse;
     private childReady;
     /**
      * Monotonic timestamp of the current generation's adoption, or undefined
@@ -338,17 +354,47 @@ export declare class StdioSupervisor {
      */
     private readonly handleFatalError;
     /**
-     * Admission entry point, wrapped so a fault can never make a request vanish.
+     * Admission entry point, wrapped so a fault cannot silently drop a request.
      *
      * Anything thrown while classifying, queueing or forwarding a client frame
      * propagates out of the frame reader's `onFrame`, where the reader swallows
      * it as a parse error — the request then gets NO reply and the client waits
      * on that id forever (and on a modern-era request the one-way era lock has
-     * already happened). Answering the id with -32603 keeps the
-     * exactly-one-response guarantee; id-less frames (notifications, malformed
-     * ids) have nothing to answer and are only logged.
+     * already happened). The catch below answers the id with -32603 instead.
+     *
+     * The reply is conditional, and on exactly one thing: that nothing this
+     * admission installed is still live at the id. A surviving instance is
+     * already tracked and will be settled by an ordinary path, so answering
+     * alongside it would make two terminal replies for one request; the catch
+     * reports and stands down in that case rather than answering. Id-less frames
+     * (notifications, malformed ids) have nothing to answer and are only logged.
      */
     private handleClientMessage;
+    /**
+     * Runs one step of a fault-recovery path so that it cannot throw.
+     *
+     * The two frame-reader callers — the admission catch in handleClientMessage
+     * and the worker-frame catch in handleWorkerData — execute inside a
+     * {@link JsonRpcFrameReader}'s `onFrame`, where the reader deliberately
+     * converts an escaping throw into a plain parse error: the frame is then
+     * silently dropped, which for a recovery path means the request it was
+     * rescuing is lost after all. `dispatchQueuedRequest` is the third caller,
+     * and its exposure is wider rather than narrower: a drain is reached from
+     * those two `onFrame` paths, but also from timer callbacks
+     * (handleValidateProjectDeadline) and from process-event handlers
+     * (handleWorkerExit), where nothing above it is prepared to contain a throw
+     * at all.
+     *
+     * Reporting goes through `log` rather than the injected `eventWriter` so
+     * that an INJECTED writer — the collaborator most likely to have thrown — is
+     * not also the reporter. That NARROWS the failure; it does not remove it.
+     * `eventWriter` defaults to `log` (see the constructor), so in the default
+     * configuration, where nothing is injected, the reporter IS the writer that
+     * just faulted. The report therefore carries its own try/catch whose handler
+     * does nothing: past this point there is no reporting channel left, and a
+     * throw here would drop the frame this method exists to save.
+     */
+    private runRecoveryStep;
     /**
      * Every request INSTANCE live at `key` right now: the forwarded entry plus any
      * queued ones. Captured before admission runs so a rollback can tell the state
@@ -374,6 +420,20 @@ export declare class StdioSupervisor {
      * Returns whether anything was rolled back.
      */
     private rollbackFailedAdmission;
+    /**
+     * Removes every QUEUED instance at `key` that is absent from `preexisting`.
+     *
+     * Split out of rollbackFailedAdmission so the admission catch's finality
+     * check can repeat the removal without re-entering the method that may just
+     * have thrown. Returns whether anything was removed; calling it twice is
+     * harmless, because the second call finds nothing.
+     */
+    private dropQueuedInstances;
+    /**
+     * Whether any request instance live at `key` is absent from `preexisting` —
+     * that is, whether the admission being rolled back still owns its id.
+     */
+    private hasInstanceOutside;
     private routeClientMessage;
     /**
      * Era-aware notification dispatch. notifications/cancelled stays
@@ -499,8 +559,94 @@ export declare class StdioSupervisor {
      */
     private handleValidateProjectDeadline;
     private drainQueue;
+    /**
+     * Forwards one queued entry, containing a fault in the forward itself.
+     *
+     * `forwardRequest` installs the pending entry and takes the validate
+     * slot/barrier BEFORE it writes to the worker's stdin, so a throw from the
+     * encode or the write leaves the request holding an id it never reached the
+     * worker on. Unguarded, that request is unreachable: it has been shifted out
+     * of the queue, so no later drain can dispatch it, and no worker will answer
+     * an id it never saw — and only validate-project arms a deadline, so nothing
+     * else settles it either. The one containing guard above this
+     * (`runRecoveryStep` around the recovery drain) contains the exception
+     * without recovering the request, and stops the drain on top of that,
+     * leaving everything behind it parked as well.
+     *
+     * Both are repaired here: the entry is released — which records the finality
+     * tombstone, so a worker that did somehow see the bytes cannot answer over
+     * the reply below — terminally answered, and the drain carries on to the
+     * next entry. Containment is per-entry because the fault this catches is
+     * per-message: an encode failure on one payload, or a stdin `write` that
+     * throws. A stdin that is merely destroyed never reaches this catch at all —
+     * `forwardRequest` tests for that first and takes its own no-child fallback,
+     * which does not throw.
+     *
+     * The `initialize` carve-out in `releaseForwardedRequest` is honoured: if it
+     * declines, nothing is answered here and the handshake lifecycle keeps the
+     * entry. Admission parks `initialize` in `queuedNotifications` rather than in
+     * `queuedRequests`, so the ordinary path never puts one in front of this
+     * drain; `forwardRequest`'s own no-child fallback is the one way an
+     * initialize can end up queued, and the carve-out is what covers it.
+     *
+     * Returns whether the entry reached the worker.
+     */
+    private dispatchQueuedRequest;
     private spawnWorker;
     private handleWorkerData;
+    /**
+     * Rescues the request a faulted worker frame was answering.
+     *
+     * `handleWorkerMessage` runs inside the worker reader's `onFrame`, where a
+     * throw becomes a parse error and the frame is simply dropped. For a
+     * RESPONSE frame that left the pending entry live with no reply and nothing
+     * left to settle it — deadlines are armed for validate-project only, so any
+     * other tool had no rescue at all and the client waited on that id for the
+     * life of the session. The id is released and answered here instead.
+     *
+     * The queue drain is the OTHER half, and it is why the answering half lives
+     * in its own method: `handleWorkerMessage` deletes a response's pending
+     * entry before the `writeToClient` that can throw, and its `drainQueue()` is
+     * the last statement of all. So the commonest fault arrives here with the
+     * entry already gone AND the queue undrained, and every early return in the
+     * answering path is a case where the drain is the only rescue left.
+     *
+     * What this recovery is worth, stated exactly. It answers the id when this
+     * supervisor is the one entitled to (see `answerFaultedWorkerResponse`), and
+     * every id it answers is tombstoned, so the worker's own answer for that id
+     * cannot become a second reply. It does NOT make one-response-per-id a
+     * property of the whole file: an id whose entry could not be released is
+     * deliberately left unanswered here rather than answered twice, the
+     * `initialize` carve-out is settled by the handshake lifecycle instead, and
+     * tombstone retention is capped at {@link MAX_SYNTHETIC_TOMBSTONES} — past
+     * 1024 live tombstones in one worker generation the oldest is evicted, and a
+     * very old worker's late answer for an evicted id would pass through.
+     *
+     * What this deliberately does NOT do: tear the session down or touch framing
+     * state. One frame the supervisor could not handle is not evidence that the
+     * worker's stream desynchronized (that is `supervisor.worker_framing_fatal`,
+     * reported by the reader itself), and the reader's own state already
+     * describes the stream correctly. The one exception is an in-flight
+     * `initialize`, whose generation cannot finish its handshake once its answer
+     * has been lost — see `answerFaultedWorkerResponse`.
+     */
+    private recoverFaultedWorkerMessage;
+    /**
+     * Terminally answers the client request a faulted worker RESPONSE frame was
+     * carrying the answer for, if this supervisor is still the one entitled to
+     * answer it. Returns without replying otherwise; the caller's drain runs
+     * either way.
+     */
+    private answerFaultedWorkerResponse;
+    /**
+     * Answers a request whose pending entry `handleWorkerMessage` had already
+     * removed when it faulted, and which therefore never reached the client.
+     *
+     * Consumed once: the marker is cleared before the reply is attempted, so a
+     * fault in the reply cannot leave a stale claim on the id for a later,
+     * unrelated fault to act on.
+     */
+    private answerUndeliveredWorkerResponse;
     private handleWorkerStdinError;
     /**
      * Reassembles the worker's stderr into lines (the ready marker may be split