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

package/dist/stdio-supervisor.js

@@ -181,6 +181,33 @@ export async function settleTreeCleanupWithin(operation, timeoutMs, onTimeout =
         operation.then(finish, () => finish(false));
     });
 }
+/**
+ * Describes a thrown value without being able to throw while doing it.
+ *
+ * The recovery paths in this file start by turning the thrown value into a
+ * string for the client's error message. Written inline as
+ * `error instanceof Error ? error.message : String(error)`, that conversion
+ * runs BEFORE any guard the recovery installs — and it is not safe: `String`
+ * calls `toString`, which a thrown object may define to throw, and `.message`
+ * may be an accessor that throws (an `Error` subclass, or any object passed
+ * through `Object.defineProperty`). A throw there escaped the recovery
+ * entirely and reached the frame reader, which drops the frame as a parse
+ * error: the request the recovery existed to answer was lost, with no reply,
+ * no deadline and its queue still parked.
+ *
+ * Every step is inside the guard, `instanceof` included — a Proxy can throw
+ * from its `getPrototypeOf` trap — and the fallback is a constant, so this
+ * function has no throwing path of its own.
+ */
+function describeThrown(error) {
+    try {
+        const described = error instanceof Error ? error.message : error;
+        return typeof described === "string" ? described : String(described);
+    }
+    catch {
+        return "<error description unavailable>";
+    }
+}
 function isRequest(message) {
     return "method" in message && "id" in message;
 }
@@ -677,6 +704,22 @@ export class StdioSupervisor {
      */
     syntheticTombstones = new Map();
     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.
+     */
+    settlingWorkerResponse;
     childReady = false;
     /**
      * Monotonic timestamp of the current generation's adoption, or undefined
@@ -887,15 +930,20 @@ export class StdioSupervisor {
         });
     };
     /**
-     * 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.
      */
     handleClientMessage(message) {
         const admittedId = isRequest(message) ? getTrackedRequestId(message) : undefined;
@@ -906,47 +954,173 @@ export class StdioSupervisor {
             this.routeClientMessage(message);
         }
         catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            this.eventWriter("error", "supervisor.admission_failed", {
-                id: "id" in message ? message.id : undefined,
-                method: "method" in message ? message.method : undefined,
-                message: detail
+            // `describeThrown`, not an inline conversion: this line runs BEFORE
+            // every guard below, so a thrown value whose `toString` or `.message`
+            // throws would escape the recovery here and cost the request its reply.
+            const detail = describeThrown(error);
+            // EVERY step below is individually guarded, because this whole block runs
+            // inside the frame reader's `onFrame`: a throw escaping here is reported
+            // as a parse error and the request is dropped — the exact loss this
+            // handler exists to prevent, reintroduced by its own recovery. Guarding
+            // per step rather than as a block is what keeps a faulting event writer
+            // from costing the client its terminal reply, and a faulting reply from
+            // costing the queue its drain.
+            //
+            // The two writers are separate channels, not one: in the DEFAULT
+            // configuration `eventWriter` is `log`, which writes to stderr, while a
+            // reply with no injected `clientWriter` goes to stdout. A failure of one
+            // is therefore no evidence about the other, in either direction — which
+            // is the reason each step carries its own guard rather than the block
+            // carrying one.
+            this.runRecoveryStep("admission.event", () => {
+                this.eventWriter("error", "supervisor.admission_failed", {
+                    id: "id" in message ? message.id : undefined,
+                    method: "method" in message ? message.method : undefined,
+                    message: detail
+                });
             });
             // Admission installs state before it can fault (see rollbackFailedAdmission),
             // and the -32603 below is terminal for the id — so anything half-installed
             // has to go before the reply, or it will answer the id a second time.
-            const rolledBack = admittedId !== undefined &&
-                preexisting !== undefined &&
-                this.rollbackFailedAdmission(requestKey(admittedId), preexisting);
+            let rolledBack = false;
+            this.runRecoveryStep("admission.rollback", () => {
+                rolledBack =
+                    admittedId !== undefined &&
+                        preexisting !== undefined &&
+                        this.rollbackFailedAdmission(requestKey(admittedId), preexisting);
+            });
+            // A rollback that FAULTED may have removed part of the state and left
+            // the rest, and it reports neither — so the step above proves only that
+            // it did not throw, never that the id is clear. Redo the removal through
+            // the primitives themselves rather than through the method that may just
+            // have thrown (a fallback that re-enters the failed step is not a
+            // fallback), then read the id back. Both halves are idempotent: after a
+            // rollback that succeeded they find nothing and change nothing.
+            let admissionInstanceSurvives = false;
+            if (admittedId !== undefined && preexisting !== undefined) {
+                const admittedKey = requestKey(admittedId);
+                const scope = preexisting;
+                this.runRecoveryStep("admission.rollback_finality", () => {
+                    try {
+                        if (this.dropQueuedInstances(admittedKey, scope))
+                            rolledBack = true;
+                        const live = this.pendingRequests.get(admittedKey);
+                        if (live && !scope.has(live) && this.releaseForwardedRequest(admittedKey, live)) {
+                            rolledBack = true;
+                        }
+                    }
+                    finally {
+                        // In a `finally` because the removal above may itself throw, and a
+                        // removal that threw part-way through is exactly the case the read
+                        // back has to cover. Should the read ITSELF throw, the step's guard
+                        // contains it and the flag stays false, so the reply goes out: a
+                        // request answered is the failure this handler exists to prevent,
+                        // and it is the safer of the two directions to fail in.
+                        admissionInstanceSurvives = this.hasInstanceOutside(admittedKey, scope);
+                    }
+                });
+            }
             if (!isRequest(message))
                 return;
             const id = getTrackedRequestId(message);
             if (id === undefined)
                 return;
-            this.writeToClient({
-                jsonrpc: "2.0",
-                id,
-                error: {
-                    code: -32603,
-                    message: `MCP supervisor failed to admit the request: ${detail}`
-                }
-            }, this.modeForMessage(message));
-            if (rolledBack) {
-                // The released entry may have been the last occupant of a dispatch
-                // barrier, and its cleared deadline was the timer that used to (much
-                // later) unblock the queue behind it. Drain now instead. A second fault
-                // must not escape: the client is already answered, and an escaping throw
-                // reaches the frame reader, which swallows it as a parse error.
-                try {
-                    this.drainQueue();
-                }
-                catch (drainError) {
-                    this.eventWriter("error", "supervisor.admission_failed", {
+            if (admissionInstanceSurvives) {
+                // Nothing could take the id away from this admission's own instance,
+                // and that instance still owns it: it is tracked, so the worker's
+                // answer, the worker-exit terminalization or an armed validate-project
+                // deadline will settle it. Adding -32603 on top would be the second
+                // terminal reply for one request, which is the one thing this handler
+                // may never do. It is reported and left alone instead.
+                //
+                // Known limitation: a non-validate tool arms no deadline, so if the
+                // fault also kept the request from reaching the worker, the id waits
+                // for the worker's exit. That is the accepted cost of not adding a
+                // universal per-request deadline; a blanket one would cut off the long
+                // calls this server legitimately makes.
+                this.runRecoveryStep("admission.rollback_incomplete", () => {
+                    this.eventWriter("error", "supervisor.admission_rollback_incomplete", {
                         id,
-                        method: message.method,
-                        message: drainError instanceof Error ? drainError.message : String(drainError)
+                        method: message.method
                     });
-                }
+                });
+            }
+            else {
+                this.runRecoveryStep("admission.reply", () => {
+                    this.writeToClient({
+                        jsonrpc: "2.0",
+                        id,
+                        error: {
+                            code: -32603,
+                            message: `MCP supervisor failed to admit the request: ${detail}`
+                        }
+                    }, this.modeForMessage(message));
+                });
+            }
+            if (rolledBack) {
+                // Something WAS removed — which is true on the stand-down branch too,
+                // where a queued instance went but a forwarded one survived. The
+                // released entry may have been the last occupant of a dispatch
+                // barrier, and its cleared deadline was the timer that used to (much
+                // later) unblock the queue behind it. Drain now instead — whether or
+                // not the reply above got out, since a client channel that refused the
+                // reply is no reason to leave the queue parked. A second fault must not
+                // escape either: an escaping throw reaches the frame reader, which
+                // swallows it as a parse error.
+                this.runRecoveryStep("admission.drain", () => {
+                    try {
+                        this.drainQueue();
+                    }
+                    catch (drainError) {
+                        this.eventWriter("error", "supervisor.admission_failed", {
+                            id,
+                            method: message.method,
+                            message: describeThrown(drainError)
+                        });
+                    }
+                });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    runRecoveryStep(step, run) {
+        try {
+            run();
+        }
+        catch (error) {
+            try {
+                // describeThrown cannot throw, so the outer try/catch here guards only
+                // the `log` call itself.
+                log("error", "supervisor.recovery_step_failed", {
+                    step,
+                    message: describeThrown(error)
+                });
+            }
+            catch {
+                // Deliberately empty — see above. Nothing is left to report through.
             }
         }
     }
@@ -985,7 +1159,23 @@ export class StdioSupervisor {
      * Returns whether anything was rolled back.
      */
     rollbackFailedAdmission(key, preexisting) {
-        let rolledBack = false;
+        let rolledBack = this.dropQueuedInstances(key, preexisting);
+        const pending = this.pendingRequests.get(key);
+        if (pending && !preexisting.has(pending) && this.releaseForwardedRequest(key, pending)) {
+            rolledBack = true;
+        }
+        return rolledBack;
+    }
+    /**
+     * 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.
+     */
+    dropQueuedInstances(key, preexisting) {
+        let removed = false;
         for (let index = this.queuedRequests.length - 1; index >= 0; index -= 1) {
             const entry = this.queuedRequests[index];
             if (requestKey(entry.pending.id) !== key || preexisting.has(entry.pending))
@@ -1003,13 +1193,20 @@ export class StdioSupervisor {
             if (this.validateBarrierKey === key && this.runningValidateKey !== key) {
                 this.validateBarrierKey = undefined;
             }
-            rolledBack = true;
+            removed = true;
         }
-        const pending = this.pendingRequests.get(key);
-        if (pending && !preexisting.has(pending) && this.releaseForwardedRequest(key, pending)) {
-            rolledBack = true;
+        return removed;
+    }
+    /**
+     * Whether any request instance live at `key` is absent from `preexisting` —
+     * that is, whether the admission being rolled back still owns its id.
+     */
+    hasInstanceOutside(key, preexisting) {
+        for (const instance of this.liveInstancesAt(key)) {
+            if (!preexisting.has(instance))
+                return true;
         }
-        return rolledBack;
+        return false;
     }
     routeClientMessage(message) {
         debugSupervisor("client_message", {
@@ -1416,6 +1613,18 @@ export class StdioSupervisor {
             else {
                 if (pending.deadlineTimer)
                     this.timerClearer(pending.deadlineTimer);
+                // Unlike the admission-time queue-limit site, this one runs AFTER
+                // admission may have raised the validate barrier for this very
+                // request, and the terminal reply below is the last event the id will
+                // ever produce — so the barrier has to come down here or nothing
+                // behind it would ever dispatch again. Same guard as every other
+                // release: the barrier may be held by a DIFFERENT, RUNNING request
+                // that reuses this id, and releasing that one would admit concurrent
+                // work alongside a live validate-project.
+                const abandonedKey = requestKey(pending.id);
+                if (this.validateBarrierKey === abandonedKey && this.runningValidateKey !== abandonedKey) {
+                    this.validateBarrierKey = undefined;
+                }
                 this.writeSyntheticReply(pending, buildSupervisorQueueLimitReply(pending.id, pending.method ?? message.method));
             }
             this.scheduleRestart();
@@ -1457,8 +1666,12 @@ export class StdioSupervisor {
             const [{ pending }] = this.queuedRequests.splice(queuedIndex, 1);
             if (pending.deadlineTimer)
                 this.timerClearer(pending.deadlineTimer);
-            if (this.validateBarrierKey === key)
+            // A queued entry never owns runningValidateKey. The barrier may be held
+            // by a DIFFERENT, RUNNING request that reuses this id; releasing it here
+            // would admit concurrent work alongside a live validate-project.
+            if (this.validateBarrierKey === key && this.runningValidateKey !== key) {
                 this.validateBarrierKey = undefined;
+            }
             this.drainQueue();
             return;
         }
@@ -1651,8 +1864,13 @@ export class StdioSupervisor {
                     return;
                 }
                 this.queuedRequests.shift();
-                this.forwardRequest(next.message, next.pending);
-                return;
+                // Return only when the dispatch actually happened: a validate-project
+                // runs alone, but one that never reached the worker was settled
+                // instead and released the barrier with it, so the queue behind it is
+                // free to move in the same pass.
+                if (this.dispatchQueuedRequest(next))
+                    return;
+                continue;
             }
             if (this.validateBarrierKey && this.validateBarrierKey !== nextKey) {
                 const barrierIndex = this.queuedRequests.findIndex((entry) => requestKey(entry.pending.id) === this.validateBarrierKey);
@@ -1660,7 +1878,113 @@ export class StdioSupervisor {
                     return;
             }
             this.queuedRequests.shift();
-            this.forwardRequest(next.message, next.pending);
+            this.dispatchQueuedRequest(next);
+        }
+    }
+    /**
+     * 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.
+     */
+    dispatchQueuedRequest(entry) {
+        try {
+            this.forwardRequest(entry.message, entry.pending);
+            return true;
+        }
+        catch (error) {
+            const detail = describeThrown(error);
+            this.runRecoveryStep("queue.dispatch", () => {
+                this.eventWriter("error", "supervisor.queued_dispatch_failed", {
+                    id: entry.pending.id,
+                    method: entry.pending.method,
+                    toolName: entry.pending.toolName,
+                    message: detail
+                });
+            });
+            const key = requestKey(entry.pending.id);
+            let released = false;
+            let attemptedRelease = false;
+            this.runRecoveryStep("queue.dispatch_settle", () => {
+                // Only THIS instance may be settled here. A fault before forwardRequest
+                // installed anything leaves the request re-queued by its own no-child
+                // fallback (a later drain owns it) or already answered by the
+                // queue-limit rejection; either way the id may meanwhile belong to a
+                // different live request, which keeps its own guarantee.
+                if (this.pendingRequests.get(key) !== entry.pending)
+                    return;
+                attemptedRelease = true;
+                released = this.releaseForwardedRequest(key, entry.pending);
+            });
+            if (attemptedRelease && !released) {
+                // releaseForwardedRequest deletes the entry and records its tombstone
+                // BEFORE it returns, so a throw part-way through (recordFinalityTombstone's
+                // only throw site today is the debug-log call during tombstone
+                // eviction) can still have taken the id away from its entry. `released`
+                // cannot tell "declined" apart from "threw after mutating", so the id
+                // is read back rather than assumed — mirrors
+                // answerFaultedWorkerResponse's worker_message.release_verify.
+                //
+                // Gated on `attemptedRelease`, not merely `!released`: the identity
+                // check above (`pendingRequests.get(key) !== entry.pending`) returns
+                // early, WITHOUT calling releaseForwardedRequest, whenever this entry
+                // was never installed into pendingRequests to begin with — which is
+                // exactly what happens when forwardRequest's no-child fallback re-queues
+                // this same entry (queue not full) or already answered it itself (queue
+                // full) before throwing later in that same fallback (e.g. from
+                // scheduleRestart). In either of those cases the id is either still
+                // waiting for a real dispatch that will answer it for real later, or
+                // already answered — and this verify step cannot distinguish "never
+                // installed" from "installed, then removed by a throwing release" using
+                // `pendingRequests.has(key)` alone. Running it anyway would record a
+                // spurious tombstone and send a synthetic reply for a request that gets
+                // (or already got) a real one, i.e. two replies for the same id.
+                this.runRecoveryStep("queue.dispatch_settle_verify", () => {
+                    if (entry.pending.method === "initialize" || this.pendingRequests.has(key))
+                        return;
+                    this.recordFinalityTombstone(key, entry.pending.mode);
+                    released = true;
+                });
+            }
+            if (released) {
+                this.runRecoveryStep("queue.dispatch_reply", () => {
+                    this.writeSyntheticReply(entry.pending, {
+                        jsonrpc: "2.0",
+                        id: entry.pending.id,
+                        error: {
+                            code: -32603,
+                            message: `MCP supervisor failed to dispatch the queued request: ${detail}`
+                        }
+                    });
+                });
+            }
+            return false;
         }
     }
     spawnWorker() {
@@ -1678,7 +2002,7 @@ export class StdioSupervisor {
         }
         catch (error) {
             log("error", "supervisor.worker_spawn_throw", {
-                message: error instanceof Error ? error.message : String(error)
+                message: describeThrown(error)
             });
             this.handleStartupFailure(token, { code: null, signal: null });
             return;
@@ -1723,7 +2047,15 @@ export class StdioSupervisor {
             return;
         reader.processChunk(chunk, {
             onFrame: ({ message }) => {
-                this.handleWorkerMessage(child, message);
+                try {
+                    this.handleWorkerMessage(child, message);
+                }
+                catch (error) {
+                    // Mirror of the client side's admission safety net (see
+                    // handleClientMessage): an unguarded throw here escapes into the
+                    // reader, which reports it as a parse error and drops the frame.
+                    this.recoverFaultedWorkerMessage(message, error);
+                }
             },
             onError: (error) => {
                 if (isJsonRpcFramingFatalError(error)) {
@@ -1741,6 +2073,207 @@ export class StdioSupervisor {
             }
         });
     }
+    /**
+     * 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`.
+     */
+    recoverFaultedWorkerMessage(message, error) {
+        // `describeThrown`, not an inline conversion: this line runs BEFORE every
+        // guard below, so a thrown value whose `toString` or `.message` throws
+        // would escape into the reader and drop the frame this method exists to
+        // rescue.
+        const detail = describeThrown(error);
+        this.runRecoveryStep("worker_message.event", () => {
+            this.eventWriter("error", "supervisor.worker_message_failed", {
+                id: "id" in message ? message.id : undefined,
+                method: "method" in message ? message.method : undefined,
+                message: detail
+            });
+        });
+        this.answerFaultedWorkerResponse(message, detail);
+        // Unconditional, and outside every early return above. Running it when the
+        // ordinary tail-drain would not have is bounded rather than free-handed:
+        // drainQueue returns at once unless the current child is ready with a live
+        // stdin, and dispatches nothing at all while a validate-project is running.
+        //
+        // The guard here contains a drain fault; it does not recover one. What
+        // recovers the request a faulting dispatch stranded is
+        // `dispatchQueuedRequest`, one level down — a request shifted out of the
+        // queue and installed at its id has left every path that could re-reach
+        // it, so containment alone would strand it exactly as badly as the throw
+        // this method exists to answer for.
+        this.runRecoveryStep("worker_message.drain", () => {
+            this.drainQueue();
+        });
+    }
+    /**
+     * 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.
+     */
+    answerFaultedWorkerResponse(message, detail) {
+        if (!isResponse(message))
+            return;
+        const id = getTrackedRequestId(message);
+        if (id === undefined)
+            return;
+        const key = requestKey(id);
+        const pending = this.pendingRequests.get(key);
+        if (!pending) {
+            // No entry at the id — which is NOT proof the id was answered.
+            // handleWorkerMessage deletes a response's pending entry BEFORE it writes
+            // the reply, so a write that faults arrives here with the entry already
+            // gone and the client still owed a response. That window is the only
+            // thing `settlingWorkerResponse` records, and it is the only case in
+            // which an id with no entry may be answered here; anything else is an id
+            // this supervisor already settled, or one it never tracked.
+            this.answerUndeliveredWorkerResponse(key, detail);
+            return;
+        }
+        let released = false;
+        this.runRecoveryStep("worker_message.release", () => {
+            // releaseForwardedRequest declines an in-flight `initialize` by design:
+            // that entry belongs to the handshake lifecycle.
+            released = this.releaseForwardedRequest(key, pending);
+        });
+        if (!released) {
+            // `released` is false for three different reasons: the `initialize`
+            // carve-out declined, the release threw before it removed anything, or
+            // the release threw AFTER removing the entry. Only the first two leave
+            // the entry owning its id, and the flag cannot tell them apart — the
+            // step is guarded, so any throw leaves it false, and
+            // releaseForwardedRequest deletes the entry and records its tombstone
+            // before it returns. An entry that no longer owns its id has nothing
+            // left that could ever answer it, so the id is read back rather than
+            // assumed.
+            this.runRecoveryStep("worker_message.release_verify", () => {
+                if (pending.method === "initialize" || this.pendingRequests.has(key))
+                    return;
+                // Re-recording is idempotent (see recordFinalityTombstone), and covers
+                // a release that threw before it got this far.
+                this.recordFinalityTombstone(key, pending.mode);
+                released = true;
+            });
+        }
+        if (!released) {
+            // Still live and still owning its id. The `initialize` carve-out leaves
+            // the entry to the handshake lifecycle — but that lifecycle's recovery
+            // paths are not all armed here. The startup watchdog in particular is
+            // cleared by adoptActiveChild, so a client whose `initialize` reached an
+            // ALREADY-READY worker has no watchdog behind it, and a worker that stays
+            // alive triggers neither the exit nor the replay path. What is certain in
+            // every one of those lifecycles is that THIS generation can no longer
+            // finish the handshake: the frame that was lost was its answer. So the
+            // generation is replaced: the current child is invalidated and
+            // terminated, and a successor is spawned — now, or once the live-child
+            // cap allows. That successor arms a fresh startup watchdog and, on
+            // ready, re-forwards the retained initialize (handleWorkerReady), so the
+            // handshake gets a second chance instead of stalling.
+            //
+            // Replacing the generation does not by itself terminalize any OTHER
+            // request forwarded to the old child: when its `exit` eventually fires,
+            // `handleWorkerExit` finds `this.child` already pointing at the
+            // successor and takes its early-return branch, skipping
+            // failPendingRequestsOnWorkerExit entirely. So that call runs here
+            // first, mirroring the precedent at handleWorkerProcessError, and BEFORE
+            // recoverTimedOutWorker replaces the generation. It does not touch the
+            // retained `initialize` itself: failPendingRequestsOnWorkerExit carves
+            // out `this.initializeRequest`'s key, which is exactly the entry this
+            // lifecycle is about to continue on the successor.
+            //
+            // Split into two independent recovery steps, deliberately: these are two
+            // unrelated effects (terminalizing OTHER stranded requests, and replacing
+            // the generation so the retained initialize gets a second chance), and
+            // they must not share a fault boundary. Before failPendingRequestsOnWorkerExit
+            // existed here, recoverTimedOutWorker was the only statement in this step
+            // and ran unconditionally on any path that reached it. Running both in one
+            // `runRecoveryStep` would let a throw inside failPendingRequestsOnWorkerExit
+            // (e.g. its own timerClearer call faulting for some OTHER pending
+            // request's deadline timer) silently swallow the call to
+            // recoverTimedOutWorker that follows it in the same callback — silently
+            // skipping the one guarantee this whole branch exists to provide.
+            if (pending.method === "initialize") {
+                this.runRecoveryStep("worker_message.initialize_recovery_fail_pending", () => {
+                    this.failPendingRequestsOnWorkerExit({ code: null, signal: null });
+                });
+                this.runRecoveryStep("worker_message.initialize_recovery", () => {
+                    this.recoverTimedOutWorker();
+                });
+            }
+            return;
+        }
+        this.runRecoveryStep("worker_message.reply", () => {
+            this.writeSyntheticReply(pending, {
+                jsonrpc: "2.0",
+                id,
+                error: {
+                    code: -32603,
+                    message: `MCP supervisor failed to process the worker response: ${detail}`
+                }
+            });
+        });
+    }
+    /**
+     * 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.
+     */
+    answerUndeliveredWorkerResponse(key, detail) {
+        const settling = this.settlingWorkerResponse;
+        this.settlingWorkerResponse = undefined;
+        if (!settling || settling.key !== key)
+            return;
+        this.runRecoveryStep("worker_message.undelivered_reply", () => {
+            // The entry is already gone, so writeSyntheticReply will not settle or
+            // tombstone anything; the tombstone is recorded here so the worker
+            // repeating its answer cannot become a second reply.
+            this.recordFinalityTombstone(key, settling.snapshot.mode);
+            this.writeSyntheticReply(settling.snapshot, {
+                jsonrpc: "2.0",
+                id: settling.snapshot.id,
+                error: {
+                    code: -32603,
+                    message: `MCP supervisor failed to deliver the worker response: ${detail}`
+                }
+            });
+        });
+    }
     handleWorkerStdinError(child, error) {
         if (child !== this.child)
             return;
@@ -1748,6 +2281,37 @@ export class StdioSupervisor {
             return;
         }
         log("warn", "supervisor.worker_stdin_error", { message: error.message });
+        // This event fires only on child.stdin, which exists only once the child
+        // has actually been spawned, but that does NOT collapse to a single
+        // "always post-ready" case: handleWorkerReady's legacy-era replay of a
+        // retained `initialize` (era === "legacy" with `this.initializeRequest`
+        // set) forwards it to a freshly spawned successor WITHOUT calling
+        // adoptActiveChild first — adoptActiveChild only runs once that
+        // initialize's response actually comes back, or on the no-replay early
+        // return. So a live child can have `child.stdin` while `this.childReady`
+        // is still false, mirroring the fork handleWorkerProcessError already
+        // makes on `wasReady`. Treating that window as post-ready would run
+        // failPendingRequestsOnWorkerExit, which deliberately carves the retained
+        // initialize's pending entry OUT of what it fails (so a later id reuse of
+        // the completed initialize is not wrongly caught) — leaving the client's
+        // `initialize` answered by nothing and re-replayed against every
+        // successor forever if the stdin fault persists. Before this recovery
+        // existed at all, a broken stdin left `this.child` pointing at a worker
+        // nothing could ever write to again: scheduleRestart's own `this.child`
+        // guard made every later restart attempt a permanent no-op, and any
+        // request already forwarded to this child had nothing left that would
+        // ever answer it.
+        const wasReady = this.childReady;
+        this.invalidateCurrentChild(child);
+        this.beginTreeTermination(child);
+        if (!wasReady) {
+            this.handleStartupFailure(this.attemptToken, { code: null, signal: null });
+        }
+        else {
+            this.consecutiveImmediateStandDowns = 0;
+            this.failPendingRequestsOnWorkerExit({ code: null, signal: null });
+            this.scheduleRestart(true);
+        }
     }
     /**
      * Reassembles the worker's stderr into lines (the ready marker may be split
@@ -1908,13 +2472,17 @@ export class StdioSupervisor {
         if (this.isInitializationResponse(message)) {
             const id = getTrackedRequestId(message);
             let initializeMode;
+            let initializeKey;
+            let initializePending;
             if (id !== undefined) {
-                const key = requestKey(id);
-                initializeMode = this.pendingRequests.get(key)?.mode;
-                this.pendingRequests.delete(key);
+                initializeKey = requestKey(id);
+                initializePending = this.pendingRequests.get(initializeKey);
+                initializeMode = initializePending?.mode;
             }
             initializeMode ??= this.modeForMessage(this.initializeRequest);
             if ("error" in message) {
+                if (initializeKey !== undefined)
+                    this.pendingRequests.delete(initializeKey);
                 if (!this.replayingInitialization && id !== undefined) {
                     this.writeSyntheticReply({ id, era: this.era, mode: initializeMode }, buildLegacyJsonRpcError(id));
                     const retainedIndex = this.queuedNotifications.findIndex((entry) => isRequest(entry) && requestKey(entry.id) === requestKey(id));
@@ -1930,6 +2498,8 @@ export class StdioSupervisor {
                 return;
             }
             if (this.replayingInitialization) {
+                if (initializeKey !== undefined)
+                    this.pendingRequests.delete(initializeKey);
                 this.replayingInitialization = false;
                 if (this.initializedNotification) {
                     this.writeToWorker(child, this.initializedNotification);
@@ -1938,9 +2508,22 @@ export class StdioSupervisor {
                 this.flushQueue();
                 return;
             }
+            // Mark the entry as settling and remove it BEFORE writeToClient, so a
+            // throw there (or in the diagnostic write reporting that throw) still
+            // leaves `settlingWorkerResponse` for `answerUndeliveredWorkerResponse`
+            // to answer this id from later — mirrors the non-initialize response
+            // path below, which does the same for every other successful reply.
+            // Without this, the entry was gone and no marker recorded it, so a
+            // faulted client write here permanently lost the reply to `initialize`.
+            if (initializeKey !== undefined && initializePending) {
+                this.settlingWorkerResponse = { key: initializeKey, snapshot: initializePending };
+            }
+            if (initializeKey !== undefined)
+                this.pendingRequests.delete(initializeKey);
             this.clientInitialized = true;
             this.adoptActiveChild();
             this.writeToClient(message, initializeMode);
+            this.settlingWorkerResponse = undefined;
             this.flushQueue();
             return;
         }
@@ -1967,16 +2550,34 @@ export class StdioSupervisor {
                 const pending = this.pendingRequests.get(key);
                 responseMode = pending?.mode;
                 this.pendingRequests.delete(key);
-                if (pending?.deadlineTimer)
-                    this.timerClearer(pending.deadlineTimer);
+                if (pending && pending.method !== "initialize") {
+                    // The entry is gone and the client has not been answered yet. From
+                    // here until writeToClient returns, this marker is the only record
+                    // that the id is still owed a response (see settlingWorkerResponse).
+                    // An in-flight initialize is excluded: it is settled by the handshake
+                    // branch above, never here.
+                    this.settlingWorkerResponse = { key, snapshot: pending };
+                }
+                // These two clears run BEFORE timerClearer: a validate-project id must
+                // not stay "running" if the timer clear below throws. answerUndelivered-
+                // WorkerResponse (which later answers this id via settlingWorkerResponse
+                // on a writeToClient/drainQueue fault) never touches these two fields,
+                // so leaving them ordered after a throwing call would strand the
+                // barrier and every validate-project admitted behind it, permanently.
                 if (pending?.toolName === "validate-project") {
                     this.runningValidateKey = undefined;
                     if (this.validateBarrierKey === key)
                         this.validateBarrierKey = undefined;
                 }
+                if (pending?.deadlineTimer)
+                    this.timerClearer(pending.deadlineTimer);
             }
         }
         this.writeToClient(message, responseMode);
+        // Past this point the reply has been handed to the client channel, so the
+        // id is no longer owed one by the recovery. A fault in the drain below is
+        // the drain's own problem, not an undelivered response.
+        this.settlingWorkerResponse = undefined;
         this.drainQueue();
     }
     applyStageUpdate(params) {
@@ -2075,7 +2676,12 @@ export class StdioSupervisor {
         // count to N and falsely escalate retryRecommendation to "report-bug".
         const pendingToolNames = [];
         for (const [key, pending] of this.pendingRequests.entries()) {
-            if (key === preservedInitializeKey)
+            // Identity, not just id: a client may legally reuse `initialize`'s id
+            // for a later request once initialize has completed. `initializeRequest`
+            // (and so `preservedInitializeKey`) is retained past that point, so a
+            // bare key match would treat the REUSED entry as the still-pending
+            // initialize and skip it here — leaving it answered by nothing.
+            if (key === preservedInitializeKey && pending.method === "initialize")
                 continue;
             pendingToolNames.push(pending.toolName);
         }
@@ -2083,23 +2689,59 @@ export class StdioSupervisor {
         for (const [toolName, updated] of updatedByTool) {
             this.recentRestarts.set(toolName, updated);
         }
+        // Each entry's cleanup and its reply run as two SEPARATE recovery steps,
+        // not one bundled try around the whole loop body. Fault containment must
+        // be per-entry, not just per-function: a throw from `this.timerClearer`
+        // (or anything else in the cleanup half) for entry N must not abort the
+        // `for` loop, or every entry after N in Map iteration order is left
+        // completely unprocessed — not answered, and not cleared from
+        // runningValidateKey/validateBarrierKey either. Since the old worker's
+        // own `exit`/`error` handling short-circuits once `this.child` already
+        // points at a successor generation, a request stranded that way here is
+        // stranded permanently, and a stranded validate-project holding the
+        // barrier keys would jam every later validate-project request behind it
+        // forever. Splitting into two steps also means a fault in ONE entry's
+        // cleanup cannot suppress that SAME entry's own reply.
         for (const [key, pending] of [...this.pendingRequests.entries()]) {
-            if (key === preservedInitializeKey)
+            // See the identical guard above: a bare key match would also wrongly
+            // skip a request that legally reused the completed initialize's id.
+            if (key === preservedInitializeKey && pending.method === "initialize")
                 continue;
-            if (pending.deadlineTimer)
-                this.timerClearer(pending.deadlineTimer);
-            if (this.runningValidateKey === key)
-                this.runningValidateKey = undefined;
-            if (this.validateBarrierKey === key)
-                this.validateBarrierKey = undefined;
-            // Forwarded entries stay in pendingRequests until writeSyntheticReply
-            // settles them (the FORWARDED pending is what entitles the id to a
-            // finality tombstone). Cancelled entries are already gone — the
-            // cancellation settled them terminally at admission.
-            const toolName = pending.toolName ?? "unknown";
-            const pruned = prunedByTool.get(toolName) ?? [];
-            const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
-            this.writeSyntheticReply(pending, reply);
+            this.runRecoveryStep("worker_exit.fail_pending_cleanup", () => {
+                if (this.runningValidateKey === key)
+                    this.runningValidateKey = undefined;
+                if (this.validateBarrierKey === key)
+                    this.validateBarrierKey = undefined;
+                // Nil the field immediately after clearing, matching the convention
+                // releaseForwardedRequest already uses. writeSyntheticReply (below,
+                // in the SEPARATE fail_pending_reply step) also does
+                // `if (pending.deadlineTimer) this.timerClearer(...)` before it
+                // deletes the entry from pendingRequests. If this step cleared the
+                // timer but left the field set, that second check would still be
+                // true and writeSyntheticReply would attempt a REDUNDANT second
+                // clear of the SAME already-cleared timer. A timerClearer that
+                // faults on a repeat invocation for the same timer would then throw
+                // BEFORE writeSyntheticReply's delete/tombstone — unlike a fault
+                // strictly after deletion (which only loses that one reply), this
+                // would leave the entry live in pendingRequests forever, with
+                // nothing left to remove or answer it. Nilling here makes
+                // writeSyntheticReply's own check false, so it never attempts that
+                // second clear at all.
+                if (pending.deadlineTimer) {
+                    this.timerClearer(pending.deadlineTimer);
+                    pending.deadlineTimer = undefined;
+                }
+            });
+            this.runRecoveryStep("worker_exit.fail_pending_reply", () => {
+                // Forwarded entries stay in pendingRequests until writeSyntheticReply
+                // settles them (the FORWARDED pending is what entitles the id to a
+                // finality tombstone). Cancelled entries are already gone — the
+                // cancellation settled them terminally at admission.
+                const toolName = pending.toolName ?? "unknown";
+                const pruned = prunedByTool.get(toolName) ?? [];
+                const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
+                this.writeSyntheticReply(pending, reply);
+            });
         }
     }
     /**
@@ -2205,7 +2847,7 @@ export class StdioSupervisor {
         }
         catch (error) {
             this.eventWriter("warn", "supervisor.client_write_error", {
-                message: error instanceof Error ? error.message : String(error)
+                message: describeThrown(error)
             });
         }
     }