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

package/dist/error-mapping.js

@@ -32,6 +32,122 @@ export function extractDidYouMean(details) {
     }
     return cleaned.slice(0, MAX_DID_YOU_MEAN_ENTRIES);
 }
+// A shell jar bundles a handful of inner jars, not hundreds; the cap only
+// bounds a pathological inventory, it is not an expected truncation point.
+const MAX_NESTED_JAR_ENTRIES = 64;
+// Per-entry length ceiling, in UTF-8 bytes. Real entries are jar-relative paths
+// like "META-INF/jars/fabric-screen-handler-api-v1-2.0.5.jar" (~52 bytes); the
+// zip format itself allows a 65535-byte name, so an entry name is attacker-sized
+// unless bounded here. 256 bytes is ~5x the longest realistic entry and still
+// leaves any genuine name intact.
+const MAX_NESTED_JAR_ENTRY_BYTES = 256;
+// Total ceiling for the published list, in UTF-8 bytes. A full fabric-api-style
+// inventory (64 entries at ~52 bytes) is ~3.3 KiB, so 8 KiB carries every real
+// inventory whole while bounding the worst case this field can add to an error
+// payload — which matters because nothing else in this project bounds an
+// outbound response (MCP_MAX_FRAME_BYTES governs inbound decoding only).
+const MAX_NESTED_JARS_TOTAL_BYTES = 8 * 1024;
+/**
+ * Validates and extracts a `nestedJars` inventory from error details.
+ * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
+ * shell jar, but `context` is primitive-only, so without this the inventory
+ * never left the process.
+ *
+ * Two distinct dispositions, deliberately not conflated:
+ *  - MALFORMED (a non-string or empty-string element, anywhere in the array):
+ *    the whole array is dropped, matching {@link extractDidYouMean}. The scan
+ *    deliberately continues past the caps so a malformed element beyond them is
+ *    still found — the upstream array is a real jar's own entry list, bounded by
+ *    the archive, so the full scan is not an exposure.
+ *  - OVERSIZED (an entry longer than {@link MAX_NESTED_JAR_ENTRY_BYTES}, an
+ *    entry past the count cap, or one that would push the list past the total
+ *    byte budget): that ENTRY alone is excluded and `nestedJarsTruncated` is
+ *    set. An implausible name is not evidence that the rest of the inventory is
+ *    untrustworthy, so it must not drop the array.
+ *
+ * An empty inventory is dropped as before: the producing site omits the key
+ * entirely in that case, so an empty array carries no information a caller could
+ * act on. If the caps leave nothing publishable, both keys are omitted rather
+ * than publishing a truncation flag with no list beside it.
+ */
+export function extractNestedJarsField(details) {
+    const raw = details?.nestedJars;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return {};
+    }
+    const cleaned = [];
+    let truncated = false;
+    let totalBytes = 0;
+    let budgetExhausted = false;
+    for (const entry of raw) {
+        if (typeof entry !== "string" || !entry) {
+            return {};
+        }
+        if (budgetExhausted || cleaned.length >= MAX_NESTED_JAR_ENTRIES) {
+            truncated = true;
+            continue;
+        }
+        const entryBytes = Buffer.byteLength(entry, "utf8");
+        if (entryBytes > MAX_NESTED_JAR_ENTRY_BYTES) {
+            truncated = true;
+            continue;
+        }
+        if (totalBytes + entryBytes > MAX_NESTED_JARS_TOTAL_BYTES) {
+            // Keep the published list a prefix of the surviving entries: once the
+            // budget is spent, stop admitting rather than cherry-picking short names
+            // from the tail.
+            truncated = true;
+            budgetExhausted = true;
+            continue;
+        }
+        totalBytes += entryBytes;
+        cleaned.push(entry);
+    }
+    if (cleaned.length === 0) {
+        return {};
+    }
+    return { nestedJars: cleaned, ...(truncated ? { nestedJarsTruncated: true } : {}) };
+}
+/**
+ * Inventory-only view of {@link extractNestedJarsField}.
+ *
+ * NOT for an emission site. All three - the tool envelope, the batch entry, the
+ * error resource - publish the field pair, because dropping the flag makes a
+ * shortened inventory indistinguishable from a complete one. This remains for
+ * callers that want the list alone (tests pinning the validation and capping
+ * rules), and a new publisher should reach for the field-returning form.
+ */
+export function extractNestedJars(details) {
+    return extractNestedJarsField(details).nestedJars;
+}
+const ISSUE_ORIGIN_VALUES = new Set([
+    "code_issue",
+    "tool_issue",
+    "environment"
+]);
+/**
+ * Per-throw-site {@link IssueOrigin} override carried on an AppError's
+ * `details.issueOrigin`.
+ *
+ * The default classification is keyed purely on the error CODE, which is right
+ * for codes whose every throw site shares one origin. A few codes do not:
+ * `ERR_CONTEXT_UNRESOLVED` covers both a caller naming a version no artifact
+ * carries (genuinely `code_issue`) and the tool resolving an artifact with no
+ * binary jar behind the caller's back (`tool_issue`). Publishing the latter as
+ * caller-fixable sends an agent into a retry loop over input it cannot repair.
+ *
+ * This override is deliberately opt-in and per-error: `issueOriginForErrorCode`
+ * and its default sets stay untouched, so the exhaustive classification map in
+ * tests/runtime/error-mapping.test.ts keeps forcing a conscious decision for
+ * every new code. The key is not in `CONTEXT_ALLOWLIST`, so it cannot leak into
+ * the public `context` blob.
+ */
+export function extractIssueOriginOverride(details) {
+    const raw = details?.issueOrigin;
+    return typeof raw === "string" && ISSUE_ORIGIN_VALUES.has(raw)
+        ? raw
+        : undefined;
+}
 export function statusForErrorCode(code) {
     if (code === ERROR_CODES.BATCH_ABORTED) {
         return 412;
@@ -200,6 +316,51 @@ export function issueOriginForErrorCode(code) {
     }
     return "tool_issue";
 }
+/**
+ * The single source of truth for a ProblemDetails classification pair, and the
+ * ONLY supported way to compute one for an error the server caught. Every site
+ * that turns a caught error into a published envelope spreads this result — the
+ * tool envelope (`mapErrorToProblem`), batch entries, the batch-aborted
+ * sentinel, and the `mc://` resource read — so one failure always publishes the
+ * same `{ retryClass, issueOrigin }` no matter which access path the caller
+ * used.
+ *
+ * KNOWN EXCEPTION — the synthetic supervisor replies in `src/stdio-supervisor.ts`
+ * (`buildSupervisorQueueLimitReply`, `buildValidateProjectTimeoutReply`) write
+ * the pair as literals and never import this builder. They are not emission
+ * sites for a caught error at all: the supervisor answers a request the worker
+ * never got to run, so there is no source `AppError` whose `details` could carry
+ * an override and nothing to pass as the required `details` argument. Their
+ * literals are `transient` / `tool_issue`, which is exactly what this function
+ * returns for `ERR_LIMIT_EXCEEDED` and `ERR_TOOL_TIMEOUT` today — but that is a
+ * duplicated value held in agreement by hand, not a second call into this
+ * classifier. Reclassifying either code here must be mirrored there.
+ *
+ * It exists because that pair used to be assembled by hand at each site. The
+ * `issueOrigin` half has a per-throw-site override (see
+ * {@link extractIssueOriginOverride}), and honouring it was copy-pasted into
+ * some sites and forgotten in others — which is exactly how one identical
+ * AppError came to publish `tool_issue` through a tool call and `code_issue`
+ * through a resource read. Composing the pair here removes the opportunity:
+ * emission modules import this function and no longer reach the component
+ * classifiers at all.
+ *
+ * `details` is REQUIRED, deliberately without a default. A site that genuinely
+ * has no AppError behind it (a ZodError, a sanitized non-AppError, the
+ * batch-aborted sentinel) must pass `undefined` explicitly, so skipping the
+ * override can only ever be a written-down decision rather than an omission.
+ *
+ * Only `issueOrigin` is overridable per throw site. `retryClass` stays purely
+ * code-derived: it is a documented wire contract, and changing the value an
+ * existing code publishes is a Breaking change, so a `retryClass` override seam
+ * was deliberately deferred rather than added alongside this one.
+ */
+export function problemClassification(code, details) {
+    return {
+        retryClass: retryClassForErrorCode(code),
+        issueOrigin: extractIssueOriginOverride(details) ?? issueOriginForErrorCode(code)
+    };
+}
 // Non-sensitive AppError.details fields that are safe to echo to callers as
 // machine-readable repair context. Filesystem paths and free-form text are
 // intentionally excluded.
@@ -220,7 +381,14 @@ const CONTEXT_ALLOWLIST = new Set([
     "maxMembers",
     "candidateCount",
     "candidatesSeen",
-    "ambiguous"
+    "ambiguous",
+    // Why a repository cascade gave up, as the failing leg's own error code (e.g.
+    // "ERR_LIMIT_EXCEEDED"). The terminal ERR_REPO_FETCH_FAILED says only that
+    // repositories were unstable, which is wrong for a configuration-driven
+    // refusal; the underlying code is the machine-readable half of that
+    // correction, beside the human-readable `nextAction` hint. A bare code string
+    // - no url, no path, no message - which is why it can travel here at all.
+    "repoFailureCode"
 ]);
 /**
  * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
@@ -282,6 +450,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         const fieldErrors = extractFieldErrors(caughtError.details);
         const context = extractAllowlistedContext(caughtError.details);
         const didYouMean = extractDidYouMean(caughtError.details);
+        const nestedJarsField = extractNestedJarsField(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -289,12 +458,12 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
             status: statusForErrorCode(caughtError.code),
             code: caughtError.code,
             instance,
-            retryClass: retryClassForErrorCode(caughtError.code),
-            issueOrigin: issueOriginForErrorCode(caughtError.code),
+            ...problemClassification(caughtError.code, caughtError.details),
             ...(fieldErrors ? { fieldErrors } : {}),
             ...(baseHints ? { hints: baseHints } : {}),
             ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {}),
             ...(didYouMean ? { didYouMean } : {}),
+            ...nestedJarsField,
             ...(context ? { context } : {})
         };
     }
@@ -314,8 +483,9 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         status: 500,
         code: ERROR_CODES.INTERNAL,
         instance,
-        retryClass: retryClassForErrorCode(ERROR_CODES.INTERNAL),
-        issueOrigin: issueOriginForErrorCode(ERROR_CODES.INTERNAL),
+        // No AppError behind this envelope: the throw was sanitized away, so there
+        // is no per-site override to honour.
+        ...problemClassification(ERROR_CODES.INTERNAL, undefined),
         ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
     };
 }
@@ -327,8 +497,8 @@ export function buildBatchAbortedProblem(instance) {
         status: 412,
         code: ERROR_CODES.BATCH_ABORTED,
         instance,
-        retryClass: retryClassForErrorCode(ERROR_CODES.BATCH_ABORTED),
-        issueOrigin: issueOriginForErrorCode(ERROR_CODES.BATCH_ABORTED)
+        // Synthesized sentinel, not a caught AppError: no per-site override exists.
+        ...problemClassification(ERROR_CODES.BATCH_ABORTED, undefined)
     };
 }
 //# sourceMappingURL=error-mapping.js.map

package/dist/index.js

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

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

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

package/dist/json-rpc-framing.js

@@ -1,13 +1,34 @@
+import { clearTimeout as clearNodeTimeout, setTimeout as setNodeTimeout } from "node:timers";
 import { parseJSONRPCMessage } from "@modelcontextprotocol/server";
 const DEFAULT_MAX_FRAME_BYTES = 64 * 1024 * 1024;
 const MIN_MAX_FRAME_BYTES = 1024 * 1024;
 const MAX_CONTENT_LENGTH_HEADER_BYTES = 8 * 1024;
+const DEFAULT_INCOMPLETE_FRAME_IDLE_MS = 30_000;
+const scheduleIdleTimer = (callback, delayMs) => {
+    const timer = setNodeTimeout(callback, delayMs);
+    // The budget must never be the reason a process stays alive: a reader parked
+    // on an incomplete body would otherwise hold the event loop open for the
+    // whole budget after every other handle had closed.
+    timer.unref();
+    return timer;
+};
+const clearIdleTimerHandle = (handle) => {
+    clearNodeTimeout(handle);
+};
+/**
+ * The FIRST header terminator in the buffer, whichever style it is.
+ *
+ * Preferring a CRLFCRLF found anywhere over an earlier LFLF mis-framed every
+ * LF-framed peer whose JSON body happened to contain a raw `\r\n\r\n` — legal
+ * inter-token whitespace — because the header block was then cut at a boundary
+ * inside the body, losing that frame and the next.
+ */
 function findHeaderBoundary(buffer) {
     const crlfBoundary = buffer.indexOf("\r\n\r\n");
-    if (crlfBoundary !== -1) {
+    const lfBoundary = buffer.indexOf("\n\n");
+    if (crlfBoundary !== -1 && (lfBoundary === -1 || crlfBoundary < lfBoundary)) {
         return { index: crlfBoundary, delimiterBytes: 4 };
     }
-    const lfBoundary = buffer.indexOf("\n\n");
     if (lfBoundary !== -1) {
         return { index: lfBoundary, delimiterBytes: 2 };
     }
@@ -46,10 +67,15 @@ function asError(value) {
  *  - an oversized Content-Length whose declared body has NOT fully arrived
  *    (waiting on it is what let a single unanswerable header wedge the
  *    transport for the process lifetime),
+ *  - an UNDER-limit Content-Length whose declared body stops arriving for the
+ *    incomplete-frame idle budget — the same wedge, below the size check,
  *  - a Content-Length body that is not valid JSON — under-declaration,
  *    over-declaration and an honestly-framed bad body are indistinguishable,
  *    and the first two have already desynchronized the stream,
- *  - duplicate Content-Length headers — the body length is ambiguous,
+ *  - a header block that declared a body length and then contradicted it
+ *    (duplicate Content-Length headers, a non-numeric value alongside a
+ *    numeric one, junk after a good declaration) — bytes the peer counted as
+ *    body would otherwise be re-read as frames,
  *  - a Content-Length header block that never terminates within the header
  *    limit — there is no delimiter left to resynchronize on.
  */
@@ -87,14 +113,34 @@ export function encodeJsonRpcMessage(message, mode) {
 }
 export class JsonRpcFrameReader {
     maxFrameBytes;
+    incompleteFrameIdleMs;
+    scheduleTimer;
+    clearTimer;
     mode = "unknown";
     buffer = Buffer.alloc(0);
     pendingChunks = [];
     pendingBytes = 0;
     awaitedFrameEnd = -1;
+    awaitedBodyStart = -1;
+    idleTimer;
     fatal = false;
+    /**
+     * @param options.maxFrameBytes Largest accepted frame; defaults to
+     *   {@link loadMaxFrameBytes}.
+     * @param options.incompleteFrameIdleMs How long a declared Content-Length
+     *   body may stop arriving before the session is terminated. This is IDLE
+     *   time, not total time: every arriving byte clears and re-arms it, so a
+     *   legitimately slow or very large body is never cut off. Defaults to
+     *   30 000 ms; a non-positive or non-finite value disables the budget.
+     * @param options.timerScheduler Schedules the idle budget; defaults to an
+     *   `unref()`'d `setTimeout`. Injectable so tests can drive it directly.
+     * @param options.timerClearer Cancels a handle from `timerScheduler`.
+     */
     constructor(options = {}) {
         this.maxFrameBytes = options.maxFrameBytes ?? loadMaxFrameBytes();
+        this.incompleteFrameIdleMs = options.incompleteFrameIdleMs ?? DEFAULT_INCOMPLETE_FRAME_IDLE_MS;
+        this.scheduleTimer = options.timerScheduler ?? scheduleIdleTimer;
+        this.clearTimer = options.timerClearer ?? clearIdleTimerHandle;
     }
     get currentMode() {
         return this.mode;
@@ -108,22 +154,37 @@ export class JsonRpcFrameReader {
         return this.fatal;
     }
     reset() {
+        this.clearIdleTimer();
         this.mode = "unknown";
         this.awaitedFrameEnd = -1;
+        this.awaitedBodyStart = -1;
         this.fatal = false;
     }
     clear() {
+        this.clearIdleTimer();
         this.mode = "unknown";
         this.buffer = Buffer.alloc(0);
         this.pendingChunks = [];
         this.pendingBytes = 0;
         this.awaitedFrameEnd = -1;
+        this.awaitedBodyStart = -1;
         this.fatal = false;
     }
     processChunk(chunk, handlers) {
         if (chunk.length === 0 || this.fatal) {
             return;
         }
+        // Bytes arrived, so any pending idle budget is stale; it is re-armed below
+        // only if this chunk leaves a declared body still incomplete.
+        this.clearIdleTimer();
+        try {
+            this.drainChunk(chunk, handlers);
+        }
+        finally {
+            this.armIdleTimer(handlers);
+        }
+    }
+    drainChunk(chunk, handlers) {
         this.pendingChunks.push(chunk);
         this.pendingBytes += chunk.length;
         if (!this.canCompleteFrame(chunk)) {
@@ -153,15 +214,34 @@ export class JsonRpcFrameReader {
                     }
                     return;
                 }
-                handlers.onFrame({
-                    message,
-                    mode: this.mode
-                });
+                try {
+                    handlers.onFrame({
+                        message,
+                        mode: this.mode
+                    });
+                }
+                catch (handlerError) {
+                    // The frame HANDLER threw, not the framer. This frame's bytes are
+                    // already consumed and the framing state describes the stream
+                    // correctly, so it must survive untouched: sharing the framing
+                    // try/catch turned a handler bug into a silent framing change (the
+                    // compat transport picks its response framing from `currentMode`,
+                    // so a reset here downgraded later replies to line framing) and left
+                    // the offending request unanswered with no distinguishing signal.
+                    // The failure is still surfaced through `onError` — the path every
+                    // transport already handles — but as a plain Error, so a handler can
+                    // never forge the framing-fatal signal that tears a session down.
+                    const handlerFault = asError(handlerError);
+                    handlers.onError(new Error(`JSON-RPC frame handler failed: ${handlerFault.message}`, {
+                        cause: handlerFault
+                    }));
+                }
             }
             catch (caughtError) {
                 const error = asError(caughtError);
                 this.mode = "unknown";
                 this.awaitedFrameEnd = -1;
+                this.awaitedBodyStart = -1;
                 if (error instanceof JsonRpcFramingFatalError) {
                     // Terminal: drop everything buffered and refuse all further input so
                     // no byte after the violation can be mistaken for a frame. The
@@ -177,6 +257,63 @@ export class JsonRpcFrameReader {
             }
         }
     }
+    clearIdleTimer() {
+        if (this.idleTimer === undefined) {
+            return;
+        }
+        const handle = this.idleTimer;
+        this.idleTimer = undefined;
+        this.clearTimer(handle);
+    }
+    /**
+     * Puts an incomplete declared body on an idle clock.
+     *
+     * A Content-Length UNDER the frame limit whose body never arrives was the
+     * one wedge the size check could not see: `readContentLengthMessage` armed
+     * `awaitedFrameEnd`, `canCompleteFrame` then refused to look at anything
+     * until that many bytes existed, and every later frame piled up behind a
+     * body that was never coming. The budget is idle time — the caller clears it
+     * on every arriving chunk and this re-arms it — so only a stream that has
+     * gone silent mid-body is terminated.
+     *
+     * `onError` belongs to a `processChunk` call, so the timer fires through the
+     * handlers of the MOST RECENT call rather than the one that armed it. Every
+     * caller in this repository passes a stable handler pair on every chunk, and
+     * a caller that does not still gets a live pair rather than a stale one.
+     */
+    armIdleTimer(handlers) {
+        if (this.fatal || this.awaitedFrameEnd < 0 || this.awaitedBodyStart < 0) {
+            return;
+        }
+        if (!Number.isFinite(this.incompleteFrameIdleMs) || this.incompleteFrameIdleMs <= 0) {
+            return;
+        }
+        let handle;
+        const expire = () => {
+            if (this.idleTimer === handle) {
+                this.idleTimer = undefined;
+            }
+            if (this.fatal || this.awaitedFrameEnd < 0 || this.awaitedBodyStart < 0) {
+                // Cleared, completed or already terminated between scheduling and now.
+                return;
+            }
+            const declaredBytes = this.awaitedFrameEnd - this.awaitedBodyStart;
+            const arrivedBytes = Math.max(0, this.buffer.length + this.pendingBytes - this.awaitedBodyStart);
+            this.fatal = true;
+            this.mode = "unknown";
+            this.buffer = Buffer.alloc(0);
+            this.pendingChunks = [];
+            this.pendingBytes = 0;
+            this.awaitedFrameEnd = -1;
+            this.awaitedBodyStart = -1;
+            handlers.onError(new JsonRpcFramingFatalError(`Content-Length declared ${declaredBytes} body bytes but only ${arrivedBytes} arrived ` +
+                `within the ${this.incompleteFrameIdleMs} ms incomplete-frame idle budget; the reader ` +
+                "cannot resynchronize without trusting bytes that may never be sent, so the stdio " +
+                "session is terminated."));
+        };
+        handle = this.scheduleTimer(expire, this.incompleteFrameIdleMs);
+        this.idleTimer = handle;
+    }
     canCompleteFrame(chunk) {
         const bufferedBytes = this.buffer.length + this.pendingBytes;
         if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
@@ -237,6 +374,7 @@ export class JsonRpcFrameReader {
         if (BigInt(this.buffer.length) >= frameEnd) {
             this.buffer = this.buffer.subarray(Number(frameEnd));
             this.awaitedFrameEnd = -1;
+            this.awaitedBodyStart = -1;
             this.mode = "unknown";
             throw new Error(reason);
         }
@@ -311,6 +449,7 @@ export class JsonRpcFrameReader {
     }
     readContentLengthMessage() {
         this.awaitedFrameEnd = -1;
+        this.awaitedBodyStart = -1;
         // Skip blank separator lines between frames so the mid-stream mode check
         // below sees the first byte of the next frame.
         while (this.buffer.length > 0) {
@@ -356,36 +495,61 @@ export class JsonRpcFrameReader {
             .split(/\r?\n/)
             .map((line) => line.trim())
             .filter((line) => line.length > 0);
+        // The WHOLE block is inspected before anything is thrown. Throwing on the
+        // first bad line consumed only the header block, which left the body bytes
+        // an EARLIER Content-Length had already declared sitting in the buffer to
+        // be re-read as line frames — so `Content-Length: 5x` followed by
+        // `Content-Length: 44`, or a good declaration followed by junk, let the
+        // peer decide where the reader thought the frame ended.
         let contentLength;
+        let declaredValue;
+        let contentLengthLines = 0;
+        let headerFault;
         for (const headerLine of headerLines) {
             const separatorIndex = headerLine.indexOf(":");
             if (separatorIndex === -1) {
-                this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
-                throw new Error(`Malformed header line: ${headerLine}`);
+                headerFault ??= `Malformed header line: ${headerLine}`;
+                continue;
             }
             const headerName = headerLine.slice(0, separatorIndex).trim().toLowerCase();
             const headerValue = headerLine.slice(separatorIndex + 1).trim();
-            if (headerName === "content-length") {
-                if (contentLength !== undefined) {
-                    // Two declarations, no way to tell which delimits the body: the
-                    // classic frame-smuggling shape. Last-wins would hand an attacker
-                    // the choice of where the reader thinks this frame ends.
-                    throw new JsonRpcFramingFatalError(`Duplicate Content-Length header (${contentLength.toString()} then ${headerValue}): the ` +
-                        "declared body length is ambiguous, so the reader cannot determine where this frame " +
-                        "ends; the stdio session is terminated.");
-                }
-                if (!/^[0-9]+$/.test(headerValue)) {
-                    this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
-                    throw new Error(`Invalid Content-Length header value: ${headerValue}`);
-                }
-                contentLength = BigInt(headerValue);
+            if (headerName !== "content-length") {
+                continue;
+            }
+            contentLengthLines += 1;
+            if (contentLengthLines > 1) {
+                // Two declarations, no way to tell which delimits the body: the
+                // classic frame-smuggling shape. Last-wins would hand an attacker
+                // the choice of where the reader thinks this frame ends.
+                headerFault ??=
+                    `Duplicate Content-Length header (${declaredValue ?? ""} then ${headerValue})`;
+                continue;
+            }
+            declaredValue = headerValue;
+            if (!/^[0-9]+$/.test(headerValue)) {
+                headerFault ??= `Invalid Content-Length header value: ${headerValue}`;
+                continue;
             }
+            contentLength = BigInt(headerValue);
+        }
+        const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
+        if (headerFault !== undefined) {
+            this.buffer = this.buffer.subarray(messageStart);
+            if (contentLength !== undefined || contentLengthLines > 1) {
+                // The block named a body length somewhere and then contradicted it, so
+                // bytes the peer counted as body may already be buffered. Consuming
+                // only the header block would re-dispatch them as frames.
+                throw new JsonRpcFramingFatalError(`${headerFault}: the declared body length is ambiguous, so the reader cannot determine ` +
+                    "where this frame ends; the stdio session is terminated.");
+            }
+            // No usable length was ever declared, so the delimited header block is
+            // all there is to consume and the recovery is provable.
+            throw new Error(headerFault);
         }
         if (contentLength === undefined) {
-            this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+            this.buffer = this.buffer.subarray(messageStart);
             throw new Error("Missing Content-Length header.");
         }
-        const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
         if (contentLength > BigInt(this.maxFrameBytes)) {
             this.rejectDeclaredBody(messageStart, contentLength, `Content-Length ${contentLength.toString()} exceeds the configured frame limit of ` +
                 `${this.maxFrameBytes} bytes.`);
@@ -397,6 +561,7 @@ export class JsonRpcFrameReader {
         const frameEnd = messageStart + Number(contentLength);
         if (this.buffer.length < frameEnd) {
             this.awaitedFrameEnd = frameEnd;
+            this.awaitedBodyStart = messageStart;
             return undefined;
         }
         const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");