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

package/dist/path-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactSignature } from "./types.js";
+import type { JarStatStamp } from "./types.js";
 export interface ResolvedJarInfo {
     originalPath: string;
     resolvedPath: string;
@@ -9,7 +9,18 @@ export declare function buildJarSignature(stats: {
     mtimeMs: number;
     size: number;
 }): string;
-export declare function artifactSignatureFromFile(jarPath: string): ArtifactSignature;
+/**
+ * Read a jar's stat stamp: it stats the file, it does not read a byte of it.
+ *
+ * The name says stat because a stat is all this is. Artifact identity is
+ * derived and composed in `src/artifact-identity.ts`; nothing this returns is
+ * an artifactId, and nothing keys an artifact by it.
+ *
+ * Its one production caller is the `jarSignature` field in
+ * `src/minecraft-explorer-service.ts`, which publishes this stat-based value to
+ * callers of `get-project-context`.
+ */
+export declare function readJarStatStamp(jarPath: string): JarStatStamp;
 export declare function isSecureJarEntryPath(entryPath: string): boolean;
 /**
  * Validate and normalize a user-supplied jar path input.

package/dist/path-resolver.js

@@ -72,7 +72,18 @@ export function resolveJarPathWithSymlinkCheck(jarPath) {
 export function buildJarSignature(stats) {
     return `${Math.trunc(stats.mtimeMs)}:${stats.size}`;
 }
-export function artifactSignatureFromFile(jarPath) {
+/**
+ * Read a jar's stat stamp: it stats the file, it does not read a byte of it.
+ *
+ * The name says stat because a stat is all this is. Artifact identity is
+ * derived and composed in `src/artifact-identity.ts`; nothing this returns is
+ * an artifactId, and nothing keys an artifact by it.
+ *
+ * Its one production caller is the `jarSignature` field in
+ * `src/minecraft-explorer-service.ts`, which publishes this stat-based value to
+ * callers of `get-project-context`.
+ */
+export function readJarStatStamp(jarPath) {
     const resolvedPath = resolveJarPathWithSymlinkCheck(jarPath).resolvedPath;
     const stats = statSync(resolvedPath);
     return {

package/dist/repo-downloader.d.ts

@@ -11,13 +11,16 @@
  * That claim is scoped to this entry point, not to the `downloads/` directory.
  * Callers that reach for raw {@link downloadToCache} - the version service's
  * Mojang jars, the mapping service's mapping archives - park files under the
- * same root, write no sidecar, and keep their own identity on purpose: a Mojang
- * artifact already carries an upstream SHA-1 contract, and a version jar keeps
- * an `mtimeMs:size` signature. They are a different cache layer, not a
- * migration this module is waiting on. Artifacts on local disk outside the
- * cache entirely (`~/.m2`, the Gradle module cache) are identified by their
- * bytes as well - see `contentSignature` in `source-resolver.ts`, which reuses
- * {@link digestFile} to get there.
+ * same root and write no sidecar: a Mojang artifact already carries an upstream
+ * SHA-1 contract. They are a different cache layer, not a migration this module
+ * is waiting on.
+ *
+ * Every artifactId `src/artifact-identity.ts` composes, in both of its id
+ * spaces, is built on a sha256 of the bytes of the file it names - see
+ * `contentSignature` there, which reuses {@link digestFile} to get it. That
+ * covers artifacts on local disk outside the cache entirely (`~/.m2`, the
+ * Gradle module cache) and a jar or a Minecraft version the caller names
+ * directly.
  */
 export interface DownloadResult {
     ok: boolean;
@@ -109,6 +112,15 @@ export interface CachedDownloadFailure {
  * for a fresh download.
  */
 export type CachedDownloadResult = CachedDownloadSuccess | CachedDownloadFailure;
+/**
+ * Drop every remembered rejection.
+ *
+ * The records are process-local and expire on their own, so this exists for a
+ * caller that wants the next resolve to ask the repositories again without
+ * waiting out {@link REMEMBERED_REJECTION_TTL_MS} - a test isolating itself from
+ * the record another test left behind, above all.
+ */
+export declare function clearRememberedRejections(): void;
 /** The persisted identity and freshness record for one cached download. */
 export interface DownloadSidecar {
     version: number;

package/dist/repo-downloader.js

@@ -40,6 +40,96 @@ const DEFINITIVE_REJECTION_STATUS_CODES = new Set([403, 404, 410]);
 function isDefinitiveRejection(statusCode) {
     return statusCode !== undefined && DEFINITIVE_REJECTION_STATUS_CODES.has(statusCode);
 }
+/**
+ * How long a definitive rejection is remembered, and how many such records are
+ * kept at once.
+ *
+ * Nothing about a FAILED download is recorded anywhere else: only bytes land in
+ * the download cache, so a coordinate whose sources jar does not exist re-issues
+ * the same request to every configured repository on every resolve. That is what
+ * makes a repeated `target`-addressed resolve expensive - the artifact index it
+ * built is reused, but the repository sweep that preceded it is paid again - and
+ * a caller whose first call timed out pays the identical sweep on its retry.
+ *
+ * Only {@link DEFINITIVE_REJECTION_STATUS_CODES} are eligible, because those are
+ * the statuses this module already treats as an answer about the artifact rather
+ * than about the repository's health; the doc comment there is the reasoning.
+ * A 5xx, a 429, a 401, a timeout and a thrown network error are all ineligible,
+ * so a passing fault costs one extra request on the next call rather than
+ * locking the artifact out of reach.
+ *
+ * The window bounds even the eligible ones. Records live in memory only, so the
+ * whole set dies with the process, and an artifact published after its rejection
+ * was recorded is reachable again once the record expires.
+ */
+const REMEMBERED_REJECTION_TTL_MS = 5 * 60_000;
+const REMEMBERED_REJECTION_MAX_ENTRIES = 1024;
+/**
+ * Definitive rejections, keyed by the cache slot AND the url that was refused.
+ *
+ * The slot is in the key because it names the cache directory: two configs
+ * pointed at different cache directories are different caches and must not
+ * inherit each other's verdicts. The url is in the key as well because
+ * `destinationPath` is the caller's to choose, so nothing here may assume the
+ * slot was derived from the url it is being asked about.
+ */
+const rememberedRejections = new Map();
+function rememberedRejectionKey(url, destinationPath) {
+    return `${destinationPath}\u0000${url}`;
+}
+/** The unexpired rejection recorded for this url in this slot, if there is one. */
+function readRememberedRejection(url, destinationPath, now) {
+    const key = rememberedRejectionKey(url, destinationPath);
+    const remembered = rememberedRejections.get(key);
+    if (remembered === undefined) {
+        return undefined;
+    }
+    if (remembered.expiresAt <= now) {
+        rememberedRejections.delete(key);
+        return undefined;
+    }
+    // A copy, so a caller that mutates what it was handed cannot edit the record
+    // every later call is answered from.
+    return { ...remembered.result };
+}
+function rememberRejection(url, destinationPath, result, now) {
+    const key = rememberedRejectionKey(url, destinationPath);
+    // Delete before set, so re-recording a key moves it to the back of the Map's
+    // insertion order - which is the order the eviction below reads as recency.
+    rememberedRejections.delete(key);
+    rememberedRejections.set(key, {
+        expiresAt: now + REMEMBERED_REJECTION_TTL_MS,
+        result: { ...result }
+    });
+    if (rememberedRejections.size <= REMEMBERED_REJECTION_MAX_ENTRIES) {
+        return;
+    }
+    // Over the cap. Expired records first - they answer nothing anyway - and then
+    // oldest-recorded first until the set fits. Deleting during iteration is
+    // defined for a Map: the iterator skips what has already been removed.
+    for (const [candidate, entry] of rememberedRejections) {
+        if (entry.expiresAt <= now) {
+            rememberedRejections.delete(candidate);
+        }
+    }
+    for (const candidate of rememberedRejections.keys()) {
+        if (rememberedRejections.size <= REMEMBERED_REJECTION_MAX_ENTRIES) {
+            break;
+        }
+        rememberedRejections.delete(candidate);
+    }
+}
+/**
+ * Drop every remembered rejection.
+ *
+ * The records are process-local and expire on their own, so this exists for a
+ * caller that wants the next resolve to ask the repositories again without
+ * waiting out {@link REMEMBERED_REJECTION_TTL_MS} - a test isolating itself from
+ * the record another test left behind, above all.
+ */
+export function clearRememberedRejections() {
+    rememberedRejections.clear();
+}
 /** Location of the sidecar describing `destinationPath`. Destination-adjacent. */
 export function downloadSidecarPath(destinationPath) {
     return `${destinationPath}${DOWNLOAD_SIDECAR_SUFFIX}`;
@@ -737,6 +827,17 @@ export async function resolveCachedDownload(url, destinationPath, options) {
         // cache miss, so fall through to the transfer below - failing here would
         // hand the caller's repository loop an ENOENT as its reason to fail over.
     }
+    if (freshness === "immutable") {
+        // A repository's definitive answer about this url, still inside its window.
+        // Below the cached-bytes hit above on purpose: bytes we hold outrank a
+        // remembered refusal, and the 404 leg further down deliberately keeps the
+        // bytes it found. Only immutable urls are ever recorded, so this can never
+        // answer for a -SNAPSHOT.
+        const remembered = readRememberedRejection(url, destinationPath, Date.now());
+        if (remembered !== undefined) {
+            return remembered;
+        }
+    }
     const conditionalHeaders = freshness === "revalidate" ? conditionalHeadersFor(sidecar) : undefined;
     /**
      * Run the transfer, carrying the cached copy's validators only when asked.
@@ -920,13 +1021,21 @@ export async function resolveCachedDownload(url, destinationPath, options) {
             // this module's call - and the record goes back with them, so a later
             // revalidation that finds the artifact restored still has its validators.
             restoreRetiredSidecar();
-            return {
+            const rejection = {
                 ok: false,
                 statusCode: downloaded.statusCode,
                 etag: downloaded.etag,
                 lastModified: downloaded.lastModified,
                 contentLength: downloaded.contentLength
             };
+            // Remember it, so the next resolve of this url inside the window answers
+            // from here instead of re-issuing the request. Immutable urls only: a
+            // -SNAPSHOT is republished under the same name, so its 404 can be a
+            // publish in progress rather than an answer that will hold.
+            if (freshness === "immutable") {
+                rememberRejection(url, destinationPath, rejection, Date.now());
+            }
+            return rejection;
         }
         // The same stale-if-error reuse, for a repository that answered rather than
         // failed to: a 5xx, a 429, an authentication hiccup. Nothing here says the

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-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