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

package/dist/stdio-supervisor.js

@@ -1,9 +1,11 @@
 import { spawn } from "node:child_process";
 import process from "node:process";
-import { encodeJsonRpcMessage, JsonRpcFrameReader } from "./json-rpc-framing.js";
+import { encodeJsonRpcMessage, isJsonRpcFramingFatalError, JsonRpcFrameReader } from "./json-rpc-framing.js";
 import { log } from "./logger.js";
 import { buildSuggestedCall } from "./build-suggested-call.js";
-import { getToolSchema } from "./tool-schema-registry.js";
+import { getToolSchema, registeredToolCount } from "./tool-schema-registry.js";
+import { buildEraConflictRejection, buildInvalidInitializeRejection, buildMethodNotFoundRejection, buildMissingMetaRejection, buildUnsupportedProtocolVersionRejection, classifyEraSignal, extractModernRequestContext, isCompleteInitializeRequest, stripModernEraClaimInPlace, MODERN_PROTOCOL_VERSION, PROTOCOL_VERSION_META_KEY } from "./era-classifier.js";
+import { decorateSyntheticReply } from "./synthetic-decorator.js";
 const DEFAULT_CLIENT_MODE = "line";
 const WORKER_MODE_ENV = "MCP_STDIO_WORKER_MODE";
 const WORKER_READY_MARKER = "__MCP_STDIO_WORKER_READY__";
@@ -21,7 +23,38 @@ const MIN_VALIDATE_PROJECT_TIMEOUT_MS = 10_000;
 const MAX_VALIDATE_PROJECT_TIMEOUT_MS = 600_000;
 const MAX_WORKER_STARTUP_WATCHDOG_MS = 30_000;
 const MAX_SUPERVISOR_QUEUE = 2;
+/**
+ * Hard ceiling on retained response-finality tombstones (see
+ * syntheticTombstones). Retention is normally bounded per worker generation,
+ * but a client can synthesize terminal outcomes (queue overflow, cancellation)
+ * for unlimited fresh ids INSIDE one healthy generation, so the map also
+ * evicts in insertion order once it reaches this size. Losing the oldest
+ * tombstone can at worst let a very old late worker answer through, which is
+ * strictly preferable to unbounded supervisor memory.
+ */
+const MAX_SYNTHETIC_TOMBSTONES = 1024;
+/**
+ * Methods the supervisor answers `-32601 Method not found` at admission in
+ * every NON-legacy state. `subscriptions/listen` is auto-provided by the SDK
+ * stdio entry with zero registration, so the worker would otherwise ACCEPT it
+ * and answer with an id-less acknowledgment notification, never settling the
+ * request id (see docs/tool-reference.md, "Absent modern surfaces"). The
+ * legacy era needs no entry: nothing registers the method there, so the
+ * worker's own registry answers -32601.
+ */
+const MODERN_UNSUPPORTED_METHODS = new Set(["subscriptions/listen"]);
 const DEFAULT_TREE_CLEANUP_TIMEOUT_MS = 5_000;
+/**
+ * How long a fatal-error teardown may run before the process is ended anyway.
+ *
+ * Registering `uncaughtException`/`unhandledRejection` handlers suppresses
+ * node's default abort, so the non-zero exit has to be performed explicitly.
+ * Cleanup gets this long to reap the worker's process group first; a teardown
+ * that stalls past it must not be allowed to keep a crashed supervisor alive.
+ */
+const FATAL_SHUTDOWN_WATCHDOG_MS = 10_000;
+const DEFAULT_CLEANUP_TOKEN_RETRY_BASE_MS = 1_000;
+const DEFAULT_CLEANUP_TOKEN_RETRY_CAP_MS = 30_000;
 export function loadValidateProjectTimeoutMs(value = process.env.MCP_VALIDATE_PROJECT_TIMEOUT_MS) {
     if (!/^[0-9]+$/.test(value ?? "")) {
         return DEFAULT_VALIDATE_PROJECT_TIMEOUT_MS;
@@ -43,6 +76,22 @@ export function computeRestartBackoffMs(retryIndex) {
     }
     return Math.min(100 * (2 ** Math.floor(retryIndex)), MAX_WORKER_STARTUP_WATCHDOG_MS);
 }
+/**
+ * How long an adopted worker must stay ready before a CLEAN voluntary
+ * stand-down counts as the end of a generation that actually served.
+ *
+ * A worker stands down on stdin EOF. On a host that hands every spawned child
+ * a stdin which closes immediately, that EOF arrives while the worker is still
+ * starting: it writes its ready marker, is adopted (which clears the restart
+ * backoff), and exits 0 in the same breath. Answering that with the 100 ms
+ * restart floor respawns a ~125 MB process ten times a second forever, so a
+ * stand-down inside this window escalates the backoff instead.
+ *
+ * A CRASH is deliberately not covered: it may be transient and keeps the
+ * prompt replacement the restart suites pin, whereas a clean stand-down means
+ * the host closed the pipe and will close the replacement's stdin the same way.
+ */
+export const MIN_HEALTHY_WORKER_READY_MS = 1_000;
 export function terminatePosixProcessGroup(pid, kill = process.kill) {
     try {
         kill(-pid, "SIGKILL");
@@ -76,6 +125,20 @@ export class RestartBackoffState {
     reset() {
         this.retryIndex = 0;
     }
+    /**
+     * Raise the escalation level without reserving a restart.
+     *
+     * Adoption resets the index, so a generation that was adopted and then died
+     * without ever serving arrives here with the level already cleared. This
+     * restores the level that the repeated failure has earned, which is what
+     * stops a self-cancelling adopt/reset cycle from pinning every restart to
+     * the 100 ms floor.
+     */
+    escalateTo(level) {
+        if (!Number.isFinite(level) || level <= 0)
+            return;
+        this.retryIndex = Math.max(this.retryIndex, Math.floor(level));
+    }
 }
 export function retryPosixTreeToken(pid, kill = process.kill) {
     return terminatePosixProcessGroup(pid, kill);
@@ -109,6 +172,9 @@ function isNotification(message) {
 function isResponse(message) {
     return !("method" in message) && "id" in message;
 }
+function isToolArgumentsRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function getTrackedRequestId(message) {
     return typeof message.id === "string" || typeof message.id === "number"
         ? message.id
@@ -117,6 +183,49 @@ function getTrackedRequestId(message) {
 function requestKey(id) {
     return `${typeof id}:${String(id)}`;
 }
+/**
+ * Frozen premigration reply for a tools/call whose name is not registered
+ * (typo OR flag-disabled tool — indistinguishable, exactly as the v1 SDK
+ * answered): a SUCCESSFUL CallToolResult with isError:true and one text
+ * content entry embedding the v1 error string. The v2 SDK throws a raw
+ * -32602 instead, so the supervisor synthesizes this envelope for
+ * LEGACY-era registry misses (see handleClientMessage) to keep the legacy
+ * wire byte-identical to the premigration baseline
+ * (tests/fixtures/premigration/error-code-inventory.json, disabled-tool
+ * row). The modern era keeps the raw -32602 (sanctioned: tool absence is a
+ * params problem on 2026-07-28, mirroring the SDK's own not-found mapping).
+ */
+export function buildUnknownToolNotFoundReply(id, toolName) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [{ type: "text", text: `MCP error -32602: Tool ${toolName} not found` }],
+            isError: true
+        }
+    };
+}
+function buildLegacyMalformedToolArgumentsReply(id, argumentsValue) {
+    const received = argumentsValue === null
+        ? "null"
+        : Array.isArray(argumentsValue)
+            ? "array"
+            : typeof argumentsValue;
+    const message = JSON.stringify([
+        {
+            code: "invalid_type",
+            expected: "object",
+            received,
+            path: ["params", "arguments"],
+            message: `Expected object, received ${received}`
+        }
+    ], null, 2);
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32603, message }
+    };
+}
 export function buildLegacyJsonRpcError(id) {
     return {
         jsonrpc: "2.0",
@@ -489,6 +598,8 @@ export class StdioSupervisor {
     clientWriter;
     treeTokenRetrier;
     treeCleanupTimeoutMs;
+    cleanupTokenRetryBaseMs;
+    cleanupTokenRetryCapMs;
     eventWriter;
     monotonicNow;
     timerScheduler;
@@ -507,10 +618,59 @@ export class StdioSupervisor {
     unresolvedTreeTokens = new Set();
     restartBackoff = new RestartBackoffState();
     terminalChildren = new WeakSet();
+    /**
+     * Monotonic worker-generation counter (incremented per successful spawn).
+     * Recorded into finality tombstones so retention can be bounded per
+     * generation; hand-injected children in tests that bypass spawnWorker run
+     * as generation 0.
+     */
+    workerGeneration = 0;
+    /**
+     * Response-finality tombstones: request key → {originating worker
+     * generation, originating framing mode}, recorded by writeSyntheticReply
+     * the moment a synthetic response is written. While a tombstone exists, any
+     * worker RESPONSE for that id is discarded (with a logged
+     * `supervisor.late_response_discarded` event) instead of being forwarded —
+     * the synthesized response was terminal, and exactly one response per id
+     * must reach the client. A tombstone is cleared when its id is re-forwarded
+     * to a worker (forwardRequest), because a client may legally retry with the
+     * same id; finality is per request INSTANCE, not per id forever.
+     *
+     * `mode` is retained deliberately even though discard writes nothing today:
+     * a tombstoned id keeps its originating framing mode until discard, so any
+     * future terminal write for that id — should the discard policy ever gain
+     * one — answers in the originating framing.
+     *
+     * Retention bound: entries with generation ≤ G are dropped when the
+     * generation-G child emits "close" (process ended AND its stdio streams
+     * closed — Node's guarantee for that event). This is safe: worker frames
+     * only enter handleWorkerMessage from the CURRENT child, the supervisor
+     * only forwards ids with live pending entries, and forwarding clears the
+     * id's tombstone — so once every generation that could have seen a
+     * tombstoned id is gone with streams closed, no current child can ever
+     * deliver a frame for it. Also cleared wholesale on shutdown.
+     */
+    syntheticTombstones = new Map();
     child;
     childReady = false;
+    /**
+     * Monotonic timestamp of the current generation's adoption, or undefined
+     * while no generation is adopted. Read once at exit to tell a generation
+     * that served from one that stood down the moment it came up.
+     */
+    childReadyAt;
+    /**
+     * Consecutive adopted generations that stood down CLEANLY before they had
+     * been ready for MIN_HEALTHY_WORKER_READY_MS. Any other outcome — a crash, a
+     * signal, a generation that served — clears it.
+     */
+    consecutiveImmediateStandDowns = 0;
     shuttingDown = false;
     restartTimer;
+    cleanupRetryTimer;
+    cleanupRetryIndex = 0;
+    cleanupRetryAttempts = new Map();
+    cleanupRetriesInFlight = new Map();
     startupWatchdog;
     validateBarrierKey;
     runningValidateKey;
@@ -519,12 +679,58 @@ export class StdioSupervisor {
     currentRetryReservation;
     retryPaused = false;
     workerStderrBuffer = "";
-    clientMode = DEFAULT_CLIENT_MODE;
+    /**
+     * Framing mode of the most recently detected inbound client frame. NOT used
+     * for request-correlated writes (those use the originating request's
+     * captured mode); this is only the documented fallback for client-bound
+     * writes that correlate to no request id (worker-originated notifications
+     * and server->client requests forwarded at handleWorkerMessage, and
+     * untracked-id responses with no finality tombstone — tombstoned ids are
+     * discarded, never forwarded).
+     */
+    lastInboundClientMode = DEFAULT_CLIENT_MODE;
+    /**
+     * Per-frame framing mode of every inbound client message, keyed by message
+     * object identity. Lets admission (createPendingRequest), queued-message
+     * flushes, and initialize replay recover the ORIGINATING frame's mode long
+     * after the frame was parsed.
+     */
+    inboundFrameModes = new WeakMap();
     initializeRequest;
     initializedNotification;
+    /**
+     * Number of queued requests that arrived before an initial initialize while
+     * the worker was unavailable. Only era-neutral modern discovers can occupy
+     * this prefix; readiness forwards it before initialize, then keeps the queue
+     * suffix gated until the initialization response.
+     */
+    initializePredecessorCount = 0;
     clientInitialized = false;
     replayingInitialization = false;
     initializeSentToWorker = false;
+    /**
+     * Process-lifetime era state. The supervisor is the SOLE era gatekeeper:
+     * classification happens at admission (handleClientMessage), in stdin
+     * order. The first valid NON-discover era signal locks the era (initialize
+     * → legacy; shallow-valid modern `_meta` request → modern); the lock is
+     * one-way and survives worker restarts.
+     */
+    era = "unselected";
+    /**
+     * Whether `start()` attached this instance to the real process stdio. Only
+     * then may a teardown touch process-wide state (the framing-fatal exit
+     * code); white-box suites construct supervisors without starting them and
+     * must never have their own runner's exit status rewritten.
+     */
+    ownsProcessStdio = false;
+    /**
+     * Whether a fatal fault has already armed the explicit process exit. A
+     * second fault must not stack another watchdog or cut the first teardown
+     * short.
+     */
+    fatalExitScheduled = false;
+    /** Memoized teardown; see shutdown(). */
+    shutdownRun;
     constructor(options) {
         this.entryFile = options.entryFile;
         this.validateProjectTimeoutMs = options.validateProjectTimeoutMs ?? loadValidateProjectTimeoutMs();
@@ -532,6 +738,8 @@ export class StdioSupervisor {
         this.clientWriter = options.clientWriter;
         this.treeTokenRetrier = options.treeTokenRetrier;
         this.treeCleanupTimeoutMs = options.treeCleanupTimeoutMs ?? DEFAULT_TREE_CLEANUP_TIMEOUT_MS;
+        this.cleanupTokenRetryBaseMs = Math.max(1, Math.floor(options.cleanupTokenRetryBaseMs ?? DEFAULT_CLEANUP_TOKEN_RETRY_BASE_MS));
+        this.cleanupTokenRetryCapMs = Math.max(this.cleanupTokenRetryBaseMs, Math.floor(options.cleanupTokenRetryCapMs ?? DEFAULT_CLEANUP_TOKEN_RETRY_CAP_MS));
         this.eventWriter = options.eventWriter ?? log;
         this.monotonicNow = options.monotonicNow ?? (() => performance.now());
         this.timerScheduler = options.timerScheduler ?? ((callback, delayMs) => setTimeout(callback, delayMs));
@@ -547,6 +755,7 @@ export class StdioSupervisor {
         this.treeTerminator = options.treeTerminator;
     }
     async start() {
+        this.ownsProcessStdio = true;
         process.stdin.on("data", this.handleClientData);
         process.stdin.on("error", this.handleClientError);
         process.stdin.on("end", this.handleClientClosed);
@@ -554,19 +763,51 @@ export class StdioSupervisor {
         process.stdin.resume();
         process.on("SIGINT", this.handleTerminateSignal);
         process.on("SIGTERM", this.handleTerminateSignal);
+        // SIGHUP is what a terminating launcher or a vanishing session sends.
+        // Left to the OS default it kills this process where it stands, and the
+        // detached worker process group survives with nobody left to reap it.
+        process.on("SIGHUP", this.handleTerminateSignal);
+        // The supervisor OWNS this process's fatal handlers: it is the only party
+        // that can reach shutdown() and terminate the worker's process group.
+        // Node's default handler prints a stack and leaves the worker orphaned.
+        process.on("uncaughtException", this.handleFatalError);
+        process.on("unhandledRejection", this.handleFatalError);
         this.spawnWorker();
     }
     handleClientData = (chunk) => {
         this.clientReader.processChunk(chunk, {
             onFrame: ({ message, mode }) => {
-                this.clientMode = mode;
+                this.inboundFrameModes.set(message, mode);
+                this.lastInboundClientMode = mode;
                 this.handleClientMessage(message);
             },
             onError: (error) => {
+                if (isJsonRpcFramingFatalError(error)) {
+                    // The client stream can no longer be framed. Every later byte would
+                    // be guesswork, so the session ends with this diagnostic rather than
+                    // leaving a live process that silently answers nothing (the wedge
+                    // this repair removes).
+                    this.eventWriter("error", "supervisor.client_framing_fatal", {
+                        message: error.message
+                    });
+                    if (this.ownsProcessStdio) {
+                        // A client protocol violation ended the session — distinguishable
+                        // by a launcher from the code 0 of an ordinary stdin close. Set the
+                        // code rather than calling process.exit(), so the shutdown finishes
+                        // and the diagnostic is flushed.
+                        process.exitCode = 1;
+                    }
+                    void this.shutdown();
+                    return;
+                }
                 log("warn", "supervisor.client_parse_error", { message: error.message });
             }
         });
     };
+    /** The captured per-frame mode of an inbound client message, if known. */
+    modeForMessage(message) {
+        return message === undefined ? undefined : this.inboundFrameModes.get(message);
+    }
     handleClientError = (error) => {
         log("warn", "supervisor.client_stream_error", { message: error.message });
     };
@@ -576,6 +817,44 @@ export class StdioSupervisor {
     handleTerminateSignal = () => {
         void this.shutdown();
     };
+    /**
+     * Terminal fault in the supervisor process. Reported through the injected
+     * event writer, then routed into the ordinary shutdown so the detached
+     * worker group is reaped rather than orphaned by a crash.
+     */
+    handleFatalError = (reason) => {
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        this.eventWriter("error", "supervisor.fatal", {
+            message: error.message,
+            stack: error.stack
+        });
+        // Always the SAME teardown promise, so a second fault arriving mid-shutdown
+        // waits for the worker group to be reaped instead of racing it to the exit.
+        const teardown = this.shutdown();
+        if (!this.ownsProcessStdio) {
+            // Embedded or white-box supervisor: the host owns this process's fate.
+            void teardown.catch(() => undefined);
+            return;
+        }
+        process.exitCode = 1;
+        if (this.fatalExitScheduled)
+            return;
+        this.fatalExitScheduled = true;
+        // Registering fatal handlers suppressed node's default abort, so the exit
+        // is no longer implied by the crash — it has to be performed. Cleanup
+        // first, bounded, then leave with the non-zero status regardless of what
+        // is still holding the event loop.
+        const watchdog = setTimeout(() => {
+            this.eventWriter("error", "supervisor.fatal_exit_forced", {
+                timeoutMs: FATAL_SHUTDOWN_WATCHDOG_MS
+            });
+            process.exit(1);
+        }, FATAL_SHUTDOWN_WATCHDOG_MS);
+        void teardown.catch(() => undefined).then(() => {
+            clearTimeout(watchdog);
+            process.exit(1);
+        });
+    };
     handleClientMessage(message) {
         debugSupervisor("client_message", {
             hasMethod: "method" in message,
@@ -583,45 +862,62 @@ export class StdioSupervisor {
             id: "id" in message ? message.id : undefined,
             childReady: this.childReady
         });
-        if (isRequest(message) && message.method === "initialize") {
-            this.initializeRequest = message;
-            this.clientInitialized = false;
-        }
-        else if (isNotification(message) && message.method === "notifications/initialized") {
-            this.initializedNotification = message;
-        }
         if (isNotification(message)) {
-            if (message.method === "notifications/cancelled") {
-                this.handleCancellation(message);
-                return;
-            }
-            if (!this.childReady) {
-                if (!shouldRetainUnavailableNotification(message.method)) {
-                    this.eventWriter("warn", "supervisor.notification_dropped", {
-                        method: message.method,
-                        reason: this.liveCapOccupancy() >= 2 ? "live-cap-blocked" : "worker-unavailable"
-                    });
-                }
-                return;
-            }
-            if (this.child && !this.child.stdin.destroyed) {
-                this.writeToWorker(this.child, message);
-            }
+            this.handleClientNotification(message);
             return;
         }
         if (!isRequest(message)) {
             return;
         }
         if (message.method === "initialize") {
+            // initialize is the legacy era signal regardless of any _meta envelope
+            // it carries: the envelope is ignored for era classification here.
+            if (this.era === "modern") {
+                // One-way era lock: a rejected initialize is NEVER captured into the
+                // replay cache.
+                this.writeToClient(buildEraConflictRejection(message.id, "modern"), this.modeForMessage(message));
+                return;
+            }
+            if (!isCompleteInitializeRequest(message)) {
+                // The legacy lock is ONE-WAY and lasts the process lifetime, so it may
+                // only be committed on a frame that is actually a valid era opening.
+                // Generic JSON-RPC parsing is not that check: `params: {}` reaches
+                // here as a well-formed request and used to burn the lock, after which
+                // the worker rejected the handshake, the supervisor replaced that with
+                // a -32603 telling the client to RETRY, and the retry — or any modern
+                // request — could never succeed in this process again. Rejecting here
+                // leaves the era UNSELECTED, which makes that advice true.
+                this.eventWriter("warn", "supervisor.invalid_initialize_rejected", {
+                    id: message.id
+                });
+                this.writeToClient(buildInvalidInitializeRejection(message.id), this.modeForMessage(message));
+                return;
+            }
+            this.era = "legacy";
+            // The SDK's opening classifier treats an initialize that carries a
+            // valid modern era claim as MODERN, diverging from this admission rule
+            // ("initialize is the legacy era signal; the envelope is ignored") and
+            // failing the handshake on the worker. Strip the era-claim keys before
+            // the frame is cached, queued, or forwarded (in place: the framing-mode
+            // registry is keyed by this exact frame object).
+            stripModernEraClaimInPlace(message.params);
             if (!this.child && this.liveCapOccupancy() >= 2) {
+                // Capture-ordering fix: the cap-blocked rejection happens BEFORE
+                // capture, so a rejected initialize can never enter (or corrupt) the
+                // replay cache. clearInitialInitializationState() still discards any
+                // NOT-yet-completed earlier handshake, exactly as before.
                 this.clearInitialInitializationState();
-                this.writeToClient(buildLegacyJsonRpcError(message.id));
+                this.writeSyntheticReply({ id: message.id, era: this.era, mode: this.modeForMessage(message) }, buildLegacyJsonRpcError(message.id));
                 return;
             }
+            this.initializeRequest = message;
+            this.clientInitialized = false;
             if (this.childReady) {
+                this.initializePredecessorCount = 0;
                 this.forwardRequest(message, this.createPendingRequest(message));
             }
             else {
+                this.initializePredecessorCount = this.queuedRequests.length;
                 const existing = this.queuedNotifications.findIndex((entry) => isRequest(entry) && entry.method === "initialize");
                 if (existing >= 0)
                     this.queuedNotifications.splice(existing, 1);
@@ -629,19 +925,78 @@ export class StdioSupervisor {
             }
             return;
         }
-        const pending = this.createPendingRequest(message);
+        const eraSignal = this.admitEraRequest(message);
+        if (!eraSignal) {
+            return;
+        }
+        if (this.era !== "legacy" && MODERN_UNSUPPORTED_METHODS.has(message.method)) {
+            // Admission-time method rejection, AFTER the envelope check and the era
+            // lock admitEraRequest already applied, so the documented ordering holds:
+            // a claim-less listen in a non-legacy state fails -32602 first, a
+            // modern-signal listen still locks modern, and only then is the method
+            // itself rejected. Rejected pre-queue: no pendingRequests entry is
+            // created, so an unanswerable request can never occupy a dispatch
+            // barrier or a queue slot.
+            this.eventWriter("info", "supervisor.unsupported_method_rejected", {
+                id: message.id,
+                method: message.method,
+                era: this.era
+            });
+            this.writeToClient(buildMethodNotFoundRejection(message.id), this.modeForMessage(message));
+            return;
+        }
+        const pending = this.createPendingRequest(message, eraSignal);
         if (!this.child && this.liveCapOccupancy() >= 2) {
             const { reply } = buildWorkerRestartReply(pending, { code: null, signal: null }, this.monotonicNow(), [], { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
-            this.writeToClient(reply);
+            this.writeSyntheticReply(pending, reply);
             return;
         }
         const isValidate = pending.toolName === "validate-project";
         const dispatchImmediately = this.canDispatchImmediately(pending);
         if (!dispatchImmediately && this.queuedRequests.length >= MAX_SUPERVISOR_QUEUE) {
-            this.writeToClient(buildSupervisorQueueLimitReply(pending.id, pending.method ?? message.method));
+            this.writeSyntheticReply(pending, buildSupervisorQueueLimitReply(pending.id, pending.method ?? message.method));
             this.drainQueue();
             return;
         }
+        if (this.era === "legacy" &&
+            message.method === "tools/call" &&
+            isToolArgumentsRecord(message.params) &&
+            Object.prototype.hasOwnProperty.call(message.params, "arguments")) {
+            const argumentsValue = message.params.arguments;
+            if (argumentsValue !== undefined && !isToolArgumentsRecord(argumentsValue)) {
+                this.writeSyntheticReply(pending, buildLegacyMalformedToolArgumentsReply(pending.id, argumentsValue));
+                return;
+            }
+        }
+        if (this.era === "legacy" &&
+            message.method === "tools/call" &&
+            typeof pending.toolName === "string" &&
+            registeredToolCount() > 0 &&
+            getToolSchema(pending.toolName) === undefined) {
+            // LEGACY-era registry miss (typo or flag-disabled tool): answer the
+            // frozen premigration isError envelope. The registry is authoritative
+            // in production (src/cli.ts imports ./index.js before the supervisor
+            // starts, under the same env flags the worker inherits); the
+            // populated-registry gate keeps white-box suites that construct the
+            // supervisor without the app import on today's forwarding behavior.
+            // Semantics: DEGRADED states answer first — the cap-blocked restart
+            // and queue-overflow branches above take precedence exactly as before
+            // the intercept existed — while in the normal state the miss is
+            // answered immediately, pre-queue: it never enters pendingRequests or
+            // queuedRequests, so writeSyntheticReply's forwarded-only entitlement
+            // records no finality tombstone, and — unlike v1, which forwarded the
+            // call — it consumes no queue slot and skips the worker round-trip
+            // (identical per-request reply bytes, different queue occupancy and
+            // latency). Modern-era misses pass through to the worker's raw -32602
+            // (sanctioned modern contract); the unselected state never reaches
+            // here (rule-5 rejection in admitEraRequest).
+            this.eventWriter("info", "supervisor.unknown_tool_intercepted", {
+                id: pending.id,
+                toolName: pending.toolName
+            });
+            this.writeSyntheticReply(pending, buildUnknownToolNotFoundReply(pending.id, pending.toolName));
+            return;
+        }
         if (isValidate) {
             pending.timeoutPhase = "queue";
             const elapsedAtAdmission = Math.max(0, this.monotonicNow() - pending.startedAt);
@@ -657,12 +1012,219 @@ export class StdioSupervisor {
         }
         this.queuedRequests.push({ message, pending });
     }
-    createPendingRequest(message) {
+    /**
+     * Era-aware notification dispatch. notifications/cancelled stays
+     * supervisor-side in ALL eras/states; notifications/initialized is captured
+     * and forwarded only within a legacy flow; every other notification is
+     * gated by the era rules before reaching the original forwarding path.
+     * Dropped variants emit NO response and never affect subsequent traffic.
+     */
+    handleClientNotification(message) {
+        if (message.method === "notifications/cancelled") {
+            this.handleCancellation(message);
+            return;
+        }
+        if (message.method === "notifications/initialized") {
+            if (this.era !== "legacy") {
+                // A stray initialized outside a legacy flow is dropped and NEVER
+                // captured: forwarding (or later replaying) it would pin a worker
+                // connection legacy.
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: this.era === "modern" ? "era-conflict" : "era-unselected"
+                });
+                return;
+            }
+            if (this.initializeRequest === undefined) {
+                // Legacy era but NO handshake in progress (e.g. after a cap-rejected
+                // initialize): capturing here could later replay the stray frame
+                // around an uninitialized worker. Drop, never capture.
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: "no-active-handshake"
+                });
+                return;
+            }
+            this.initializedNotification = message;
+        }
+        else if (this.era === "unselected") {
+            if (this.childReady) {
+                // Consumed at the supervisor: forwarding any notification before an
+                // era is selected would pin the worker connection legacy. The
+                // worker-unavailable branch below keeps its original drop reasons.
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: "era-unselected"
+                });
+                return;
+            }
+        }
+        else {
+            const signal = classifyEraSignal(message.params);
+            if (this.era === "legacy" && signal.classification === "modern-signal") {
+                // Only shallow-VALID modern signals conflict with the legacy lock;
+                // claim-less and claim-shaped-invalid notifications forward as today
+                // (the legacy era stays maximally permissive).
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: "era-conflict"
+                });
+                return;
+            }
+            if (this.era === "modern" && signal.classification !== "modern-signal") {
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: "missing-meta"
+                });
+                return;
+            }
+        }
+        if (!this.childReady) {
+            if (!shouldRetainUnavailableNotification(message.method)) {
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: this.liveCapOccupancy() >= 2 ? "live-cap-blocked" : "worker-unavailable"
+                });
+            }
+            return;
+        }
+        if (this.child && !this.child.stdin.destroyed) {
+            this.writeToWorker(this.child, message);
+        }
+    }
+    /**
+     * Era rules for non-initialize requests, applied at admission in stdin
+     * order. Returns undefined when the request was terminally rejected here (a
+     * supervisor-produced response was written; nothing may be forwarded or
+     * queued). On admission it returns the admission-time era signal, which the
+     * caller hands to createPendingRequest so snapshot capture uses the same
+     * result as the gating decision (extractModernRequestContext re-checks the
+     * same immutable params graph defensively — a pure re-evaluation, not a
+     * second authority); the caller then proceeds through the original era-less
+     * admission path unchanged.
+     */
+    admitEraRequest(message) {
+        const signal = classifyEraSignal(message.params);
+        const mode = this.modeForMessage(message);
+        const id = message.id;
+        if (message.method === "server/discover") {
+            // server/discover is ERA-NEUTRAL: it forwards under the legacy lock
+            // (the legacy-pinned worker answers -32601) and a modern-signal
+            // discover forwards WITHOUT locking; only signal-less discovers in
+            // non-legacy states are rejected.
+            if (this.era === "legacy") {
+                return signal;
+            }
+            if (signal.classification === "modern-signal") {
+                if (this.rejectUnsupportedProtocolVersion(message, signal, mode)) {
+                    return undefined;
+                }
+                return signal;
+            }
+            this.writeToClient(buildMissingMetaRejection(id, signal, this.era === "modern" ? "modern" : "unselected"), mode);
+            return undefined;
+        }
+        if (signal.classification === "modern-signal") {
+            if (this.era === "legacy") {
+                this.writeToClient(buildEraConflictRejection(id, "legacy"), mode);
+                return undefined;
+            }
+            if (this.era === "unselected") {
+                this.lockModernEra();
+            }
+            if (this.rejectUnsupportedProtocolVersion(message, signal, mode)) {
+                return undefined;
+            }
+            return signal;
+        }
+        if (this.era === "legacy") {
+            // Legacy-locked behavior is otherwise UNCHANGED: claim-less AND
+            // claim-shaped-invalid traffic forwards exactly as before the era gate.
+            return signal;
+        }
+        this.writeToClient(buildMissingMetaRejection(id, signal, this.era === "modern" ? "modern" : "unselected"), mode);
+        return undefined;
+    }
+    /**
+     * Deep validation of a shallow-valid modern claim's protocolVersion VALUE,
+     * applied to EVERY modern request at admission. Returns whether the request
+     * was terminally answered here.
+     *
+     * The version check used to be delegated entirely to the worker, and the SDK
+     * only performs it while the connection is still OPENING: once an instance
+     * is pinned, `processMessage` delivers straight to it without re-reading the
+     * envelope. So the contract ("any unsupported version string answers -32022
+     * with data.supported/data.requested") held for exactly one request per
+     * process — and whether it held at all depended on which method the client
+     * happened to send first, since the era-neutral `server/discover` does not
+     * pin. Every later request with `"1999-12-31"` was SERVED, tool handlers
+     * included.
+     *
+     * Ordering is deliberate and matches the SDK's own listen path: the envelope
+     * shape is checked first (era gating above), the era lock is committed
+     * BEFORE this check — an unsupported version still locks modern, exactly as
+     * documented — and only then is the value judged, ahead of any method-level
+     * rejection. The reply is built from the SDK's own
+     * UnsupportedProtocolVersionError, so it stays byte-identical to the answer
+     * the worker gives on the still-opening path.
+     */
+    rejectUnsupportedProtocolVersion(message, signal, mode) {
+        if (signal.classification !== "modern-signal") {
+            return false;
+        }
+        const meta = message.params._meta;
+        const requested = meta[PROTOCOL_VERSION_META_KEY];
+        if (requested === MODERN_PROTOCOL_VERSION) {
+            return false;
+        }
+        this.eventWriter("warn", "supervisor.unsupported_protocol_version", {
+            id: message.id,
+            method: message.method,
+            requested
+        });
+        this.writeToClient(buildUnsupportedProtocolVersionRejection(message.id, requested), mode);
+        return true;
+    }
+    /**
+     * One-way modern lock. Purges the cached legacy lifecycle state so no
+     * initialize/notifications/initialized can ever reach a worker in a
+     * modern-locked process — across ALL later worker generations.
+     */
+    lockModernEra() {
+        this.era = "modern";
+        this.initializeRequest = undefined;
+        this.initializedNotification = undefined;
+        this.initializePredecessorCount = 0;
+        this.clientInitialized = false;
+        this.replayingInitialization = false;
+        this.initializeSentToWorker = false;
+    }
+    /**
+     * `eraSignal` is the ADMISSION-time classification handed back by
+     * admitEraRequest — the initialize/replay/flush call sites omit it (an
+     * initialize snapshot is always era "legacy" with no modern context, even
+     * when the initialize carries a _meta envelope). Context is captured only
+     * for shallow-valid modern signals; this.era already reflects any lock
+     * admitEraRequest applied, so it IS the era at admission on every path.
+     */
+    createPendingRequest(message, eraSignal) {
         const pending = {
             id: message.id,
             method: message.method,
-            startedAt: this.monotonicNow()
+            startedAt: this.monotonicNow(),
+            mode: this.modeForMessage(message),
+            era: this.era
         };
+        if (eraSignal?.classification === "modern-signal") {
+            const context = extractModernRequestContext(message.params);
+            if (context) {
+                pending.protocolVersion = context.protocolVersion;
+                pending.clientCapabilities = context.clientCapabilities;
+                if ("clientInfo" in context) {
+                    pending.clientInfo = context.clientInfo;
+                }
+            }
+        }
         if (message.method === "tools/call") {
             const params = (message.params ?? {});
             if (typeof params.name === "string")
@@ -694,11 +1256,15 @@ export class StdioSupervisor {
             else {
                 if (pending.deadlineTimer)
                     this.timerClearer(pending.deadlineTimer);
-                this.writeToClient(buildSupervisorQueueLimitReply(pending.id, pending.method ?? message.method));
+                this.writeSyntheticReply(pending, buildSupervisorQueueLimitReply(pending.id, pending.method ?? message.method));
             }
             this.scheduleRestart();
             return;
         }
+        // The id goes live on a worker: a finality tombstone from an EARLIER
+        // request instance that reused this id no longer applies (a client may
+        // legally retry with the same id after a synthetic terminal reply).
+        this.syntheticTombstones.delete(requestKey(pending.id));
         this.pendingRequests.set(requestKey(pending.id), pending);
         if (pending.toolName === "validate-project") {
             pending.timeoutPhase = "running";
@@ -725,6 +1291,9 @@ export class StdioSupervisor {
         const key = requestKey(targetId);
         const queuedIndex = this.queuedRequests.findIndex((entry) => requestKey(entry.pending.id) === key);
         if (queuedIndex >= 0) {
+            if (queuedIndex < this.initializePredecessorCount) {
+                this.initializePredecessorCount -= 1;
+            }
             const [{ pending }] = this.queuedRequests.splice(queuedIndex, 1);
             if (pending.deadlineTimer)
                 this.timerClearer(pending.deadlineTimer);
@@ -734,13 +1303,100 @@ export class StdioSupervisor {
             return;
         }
         const pending = this.pendingRequests.get(key);
-        if (pending?.toolName === "validate-project") {
-            pending.clientCancelled = true;
+        const released = pending !== undefined && this.releaseCancelledRequest(key, pending);
+        if (this.shouldForwardCancellation(message, pending !== undefined)) {
+            const child = this.child;
+            if (child && !child.stdin.destroyed) {
+                this.writeToWorker(child, message);
+            }
         }
-        const child = this.child;
-        if (child && !child.stdin.destroyed) {
-            this.writeToWorker(child, message);
+        if (released) {
+            // The released entry may have been the last occupant of a dispatch
+            // barrier, so queued work can move immediately.
+            this.drainQueue();
+        }
+    }
+    /**
+     * Terminal release of a FORWARDED request the client cancelled.
+     *
+     * MCP cancellation semantics forbid a response for a cancelled id, so the
+     * supervisor stops waiting on the worker the moment the cancellation is
+     * admitted — and a worker is under no obligation to ever answer a cancelled
+     * request. Keeping the entry in `pendingRequests` as a suppression marker
+     * (the pre-repair behavior) therefore stranded EVERY dispatch barrier the
+     * map gates — canDispatchImmediately's empty-map requirement, drainQueue's
+     * validate release — for the life of the process whenever the worker never
+     * answered, and let a client grow the map without bound by pairing fresh
+     * ids with cancellations.
+     *
+     * Suppression is instead recorded as an ordinary response-finality
+     * tombstone, which already carries exactly the needed semantics: a late
+     * worker answer for the id is discarded with a logged event, and
+     * re-forwarding the id (a legal retry) clears it. The result is one
+     * mechanism for "this request instance is over" rather than two.
+     *
+     * Carve-out: an in-flight `initialize` is NOT released. Its pending entry is
+     * owned by the legacy handshake lifecycle (replay correlation,
+     * isInitializationResponse, the preserved-key rule in
+     * failPendingRequestsOnWorkerExit), which has its own recovery paths
+     * (startup watchdog, worker exit, clearInitialInitializationState) and never
+     * consulted the cancellation marker anyway — so handshake behavior is
+     * unchanged, byte for byte.
+     *
+     * Returns whether an entry was actually released.
+     */
+    releaseCancelledRequest(key, pending) {
+        if (pending.method === "initialize") {
+            return false;
+        }
+        if (pending.deadlineTimer)
+            this.timerClearer(pending.deadlineTimer);
+        pending.deadlineTimer = undefined;
+        this.pendingRequests.delete(key);
+        if (this.runningValidateKey === key)
+            this.runningValidateKey = undefined;
+        if (this.validateBarrierKey === key)
+            this.validateBarrierKey = undefined;
+        this.recordFinalityTombstone(key, pending.mode);
+        this.eventWriter("info", "supervisor.request_cancelled", {
+            id: pending.id,
+            method: pending.method,
+            toolName: pending.toolName
+        });
+        return true;
+    }
+    /**
+     * Era gating for a cancellation notification. Extracted from
+     * handleCancellation so supervisor-side bookkeeping (releasing the cancelled
+     * request) stays independent of whether the frame may reach the worker — a
+     * DROPPED cancellation still cancels, exactly as documented.
+     */
+    shouldForwardCancellation(message, hasPendingTarget) {
+        const cancellationSignal = classifyEraSignal(message.params).classification;
+        if (this.era === "unselected") {
+            if (!hasPendingTarget || cancellationSignal === "claim-shaped-invalid") {
+                // Unknown cancellations could be the worker connection's first frame;
+                // claim-shaped-invalid notifications are not protocol-valid. Drop both.
+                // A known active claim-less target is different: that pending request
+                // proves this current worker already received a modern discover.
+                return false;
+            }
+        }
+        if (this.era === "modern") {
+            const activeClaimlessCancellation = cancellationSignal === "claim-less" && hasPendingTarget;
+            if (cancellationSignal !== "modern-signal" && !activeClaimlessCancellation) {
+                // A claim-less cancellation is safe only while its target is pending:
+                // that proves this current worker already received a modern request.
+                // Unknown claim-less and claim-shaped-invalid cancellations remain
+                // dropped so they can never legacy-pin a fresh worker generation.
+                this.eventWriter("warn", "supervisor.notification_dropped", {
+                    method: message.method,
+                    reason: "missing-meta"
+                });
+                return false;
+            }
         }
+        return true;
     }
     handleValidateProjectDeadline(key) {
         const queuedIndex = this.queuedRequests.findIndex((entry) => requestKey(entry.pending.id) === key);
@@ -751,34 +1407,35 @@ export class StdioSupervisor {
             pending.deadlineTimer = undefined;
             if (this.validateBarrierKey === key)
                 this.validateBarrierKey = undefined;
-            if (!pending.clientCancelled) {
-                this.writeToClient(buildValidateProjectTimeoutReply({
-                    request: pending,
-                    phase: "queue",
-                    deadlineMs: this.validateProjectTimeoutMs,
-                    now: this.monotonicNow(),
-                    workerRestartInitiated: false
-                }));
-            }
+            // A cancelled queued entry was spliced out of queuedRequests (and its
+            // timer cleared) at cancellation, so anything still here is live.
+            this.writeSyntheticReply(pending, buildValidateProjectTimeoutReply({
+                request: pending,
+                phase: "queue",
+                deadlineMs: this.validateProjectTimeoutMs,
+                now: this.monotonicNow(),
+                workerRestartInitiated: false
+            }));
             this.drainQueue();
             return;
         }
         const pending = this.pendingRequests.get(key);
         if (!pending || pending.toolName !== "validate-project")
             return;
-        this.pendingRequests.delete(key);
         pending.deadlineTimer = undefined;
         this.runningValidateKey = undefined;
         this.validateBarrierKey = undefined;
-        if (!pending.clientCancelled) {
-            this.writeToClient(buildValidateProjectTimeoutReply({
-                request: pending,
-                phase: "running",
-                deadlineMs: this.validateProjectTimeoutMs,
-                now: this.monotonicNow(),
-                workerRestartInitiated: true
-            }));
-        }
+        // The entry stays in pendingRequests until writeSyntheticReply settles it:
+        // the FORWARDED pending is what entitles the id to a finality tombstone.
+        // A cancelled request never reaches here: releaseCancelledRequest already
+        // settled it and cleared this timer.
+        this.writeSyntheticReply(pending, buildValidateProjectTimeoutReply({
+            request: pending,
+            phase: "running",
+            deadlineMs: this.validateProjectTimeoutMs,
+            now: this.monotonicNow(),
+            workerRestartInitiated: true
+        }));
         this.recoverTimedOutWorker();
     }
     drainQueue() {
@@ -832,7 +1489,12 @@ export class StdioSupervisor {
         this.child = child;
         this.liveChildren.add(child);
         this.workerReaders.set(child, new JsonRpcFrameReader());
+        const generation = ++this.workerGeneration;
+        // "close" fires only once the process has ended AND its stdio streams are
+        // closed — the tombstone retention bound (see syntheticTombstones).
+        child.once("close", () => this.purgeTombstonesThroughGeneration(generation));
         this.childReady = false;
+        this.childReadyAt = undefined;
         this.initializeSentToWorker = false;
         this.workerStderrBuffer = "";
         this.clearStartupWatchdog();
@@ -866,6 +1528,17 @@ export class StdioSupervisor {
                 this.handleWorkerMessage(child, message);
             },
             onError: (error) => {
+                if (isJsonRpcFramingFatalError(error)) {
+                    // The worker's own output stream desynchronized: its reader is dead,
+                    // so this generation can never be read again. Recover the way any
+                    // other unusable worker is recovered — terminate it and restart.
+                    this.eventWriter("error", "supervisor.worker_framing_fatal", {
+                        pid: child.pid,
+                        message: error.message
+                    });
+                    this.handleWorkerProcessError(child, error);
+                    return;
+                }
                 log("warn", "supervisor.worker_parse_error", { message: error.message });
             }
         });
@@ -904,6 +1577,9 @@ export class StdioSupervisor {
             this.handleStartupFailure(this.attemptToken, { code: null, signal: null });
         }
         else {
+            // A stream/process fault is never a clean stand-down, so it breaks any
+            // run of them.
+            this.consecutiveImmediateStandDowns = 0;
             this.failPendingRequestsOnWorkerExit({ code: null, signal: null });
             this.scheduleRestart(true);
         }
@@ -920,6 +1596,7 @@ export class StdioSupervisor {
             this.staleChildren.delete(child);
             if (cleanup.status === "pending" || cleanup.status === "unresolved") {
                 this.unresolvedTreeTokens.add(cleanup.pid);
+                this.scheduleCleanupTokenRetry();
             }
             else {
                 this.cleanupStates.delete(child);
@@ -938,6 +1615,7 @@ export class StdioSupervisor {
         }
         const childPid = this.child?.pid;
         const wasReady = this.childReady;
+        const readyAt = this.childReadyAt;
         this.detachCurrentChild();
         if (this.shuttingDown) {
             return;
@@ -952,9 +1630,40 @@ export class StdioSupervisor {
             this.handleStartupFailure(this.attemptToken, { code, signal });
             return;
         }
+        this.accountForReadyGenerationExit(childPid, readyAt, code, signal);
         this.failPendingRequestsOnWorkerExit({ code, signal });
         this.scheduleRestart(true);
     }
+    /**
+     * Decide whether the generation that just ended counts as a start that
+     * succeeded.
+     *
+     * A worker stands down on stdin EOF, and it replays an EOF that arrived
+     * while it was still starting. On a host that closes a spawned child's stdin
+     * immediately, every generation therefore signals ready, is adopted — which
+     * clears the restart backoff — and exits 0 in the same breath. Left at the
+     * 100 ms floor that is an unbounded hot respawn loop, so a clean stand-down
+     * inside the healthy window re-escalates the backoff the adoption cleared.
+     *
+     * Only a CLEAN exit qualifies: a non-zero code or a signal is a crash, which
+     * may be transient and keeps its prompt replacement.
+     */
+    accountForReadyGenerationExit(pid, readyAt, code, signal) {
+        const readyMs = readyAt === undefined ? 0 : this.monotonicNow() - readyAt;
+        const stoodDownImmediately = code === 0 && signal === null && readyMs < MIN_HEALTHY_WORKER_READY_MS;
+        if (!stoodDownImmediately) {
+            this.consecutiveImmediateStandDowns = 0;
+            return;
+        }
+        this.consecutiveImmediateStandDowns += 1;
+        this.restartBackoff.escalateTo(this.consecutiveImmediateStandDowns);
+        this.eventWriter("warn", "supervisor.worker_stood_down_immediately", {
+            pid,
+            readyMs,
+            consecutive: this.consecutiveImmediateStandDowns,
+            healthyReadyMs: MIN_HEALTHY_WORKER_READY_MS
+        });
+    }
     handleWorkerMessage(child, message) {
         if (child !== this.child)
             return;
@@ -972,12 +1681,16 @@ export class StdioSupervisor {
         }
         if (this.isInitializationResponse(message)) {
             const id = getTrackedRequestId(message);
+            let initializeMode;
             if (id !== undefined) {
-                this.pendingRequests.delete(requestKey(id));
+                const key = requestKey(id);
+                initializeMode = this.pendingRequests.get(key)?.mode;
+                this.pendingRequests.delete(key);
             }
+            initializeMode ??= this.modeForMessage(this.initializeRequest);
             if ("error" in message) {
                 if (!this.replayingInitialization && id !== undefined) {
-                    this.writeToClient(buildLegacyJsonRpcError(id));
+                    this.writeSyntheticReply({ id, era: this.era, mode: initializeMode }, buildLegacyJsonRpcError(id));
                     const retainedIndex = this.queuedNotifications.findIndex((entry) => isRequest(entry) && requestKey(entry.id) === requestKey(id));
                     if (retainedIndex >= 0)
                         this.queuedNotifications.splice(retainedIndex, 1);
@@ -1001,15 +1714,32 @@ export class StdioSupervisor {
             }
             this.clientInitialized = true;
             this.adoptActiveChild();
-            this.writeToClient(message);
+            this.writeToClient(message, initializeMode);
             this.flushQueue();
             return;
         }
+        // Worker messages that correlate to no tracked request (server-originated
+        // notifications/requests, untracked-id responses with no tombstone) fall
+        // back to the last-detected inbound mode in writeToClient. A response for
+        // a TOMBSTONED id is different: the supervisor already synthesized the
+        // terminal response for that request instance, so the late answer is
+        // discarded — exactly one response per id.
+        let responseMode;
         if (isResponse(message)) {
             const id = getTrackedRequestId(message);
             if (id !== undefined) {
                 const key = requestKey(id);
+                const tombstone = this.syntheticTombstones.get(key);
+                if (tombstone) {
+                    this.eventWriter("warn", "supervisor.late_response_discarded", {
+                        id,
+                        tombstoneGeneration: tombstone.generation,
+                        currentGeneration: this.workerGeneration
+                    });
+                    return;
+                }
                 const pending = this.pendingRequests.get(key);
+                responseMode = pending?.mode;
                 this.pendingRequests.delete(key);
                 if (pending?.deadlineTimer)
                     this.timerClearer(pending.deadlineTimer);
@@ -1017,14 +1747,10 @@ export class StdioSupervisor {
                     this.runningValidateKey = undefined;
                     if (this.validateBarrierKey === key)
                         this.validateBarrierKey = undefined;
-                    if (pending.clientCancelled) {
-                        this.drainQueue();
-                        return;
-                    }
                 }
             }
         }
-        this.writeToClient(message);
+        this.writeToClient(message, responseMode);
         this.drainQueue();
     }
     applyStageUpdate(params) {
@@ -1061,11 +1787,20 @@ export class StdioSupervisor {
             hasInitializeRequest: this.initializeRequest !== undefined,
             clientInitialized: this.clientInitialized
         });
-        if (!this.initializeRequest) {
+        // Era-gated replay: initialize replay fires ONLY in the legacy era. The
+        // modern lock purges the cached lifecycle, so the era check is
+        // belt-and-braces — no initialize may ever reach a modern-locked worker.
+        if (this.era !== "legacy" || !this.initializeRequest) {
             this.adoptActiveChild();
             this.flushQueue();
             return;
         }
+        while (this.initializePredecessorCount > 0 && this.queuedRequests.length > 0) {
+            const predecessor = this.queuedRequests.shift();
+            this.initializePredecessorCount -= 1;
+            this.forwardRequest(predecessor.message, predecessor.pending);
+        }
+        this.initializePredecessorCount = 0;
         this.replayingInitialization = this.clientInitialized;
         this.forwardRequest(this.initializeRequest, this.createPendingRequest(this.initializeRequest));
     }
@@ -1125,34 +1860,121 @@ export class StdioSupervisor {
         for (const [key, pending] of [...this.pendingRequests.entries()]) {
             if (key === preservedInitializeKey)
                 continue;
-            this.pendingRequests.delete(key);
             if (pending.deadlineTimer)
                 this.timerClearer(pending.deadlineTimer);
             if (this.runningValidateKey === key)
                 this.runningValidateKey = undefined;
             if (this.validateBarrierKey === key)
                 this.validateBarrierKey = undefined;
-            if (pending.clientCancelled)
-                continue;
+            // 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.writeToClient(reply);
+            this.writeSyntheticReply(pending, reply);
+        }
+    }
+    /**
+     * The single terminal-synthesis writer: EVERY supervisor-synthesized
+     * response (queue-limit, validate-project timeout, worker-restart in all
+     * variants incl. the structured-restart toggle, startup-failure
+     * terminalization, initialize-failure -32603) routes through here.
+     * Responsibilities, in order:
+     *  1. settle the pending entry,
+     *  2. record the finality tombstone (id + originating worker generation +
+     *     framing mode) so a late worker response for the id is discarded —
+     *     ONLY when the id was actually FORWARDED to a worker (i.e. the entry
+     *     in pendingRequests at the id IS the snapshot instance being
+     *     answered; an id-colliding DIFFERENT live entry is left untouched).
+     *     Never-forwarded
+     *     rejections (queue-limit at admission and at the forward fallback,
+     *     queue-phase validate timeout, cap-blocked replies, startup-failure
+     *     terminalization of queued work, the retained-initialize error) record
+     *     NO tombstone: no worker ever saw those ids, so no worker can answer
+     *     them, and tombstoning them would let a client grow the map without
+     *     bound inside a healthy generation,
+     *  3. apply modern-era decoration — `snapshot.era` is the ONLY
+     *     captured-context field read; raw error envelopes and non-modern eras
+     *     pass through byte-identical — and
+     *  4. write in the ORIGINATING request's framing.
+     * Admission-time era rejections (era_conflict/missing_meta/-32601) do NOT
+     * route through here: they reject before any forwarding could happen, so
+     * no worker can ever answer those ids. The initialize-error synthesis also
+     * records no tombstone: isInitializationResponse settles its pending entry
+     * before synthesizing, the answering generation is terminated, and the
+     * replay cache is cleared — no late-response channel remains.
+     */
+    writeSyntheticReply(snapshot, reply) {
+        const key = requestKey(snapshot.id);
+        const pending = this.pendingRequests.get(key);
+        // Settle ONLY the exact forwarded instance this synthesis answers. A
+        // never-forwarded snapshot (queue-limit, cap-blocked, intercept, queued
+        // terminalization, ad-hoc literals) whose id collides with a DIFFERENT
+        // live forwarded request must not delete or tombstone that live entry:
+        // the tombstone would discard the worker's real answer and strand the
+        // validate barrier (id reuse is a client-side JSON-RPC violation, but
+        // the live request keeps its exactly-one-response guarantee).
+        if (pending && pending === snapshot) {
+            if (pending.deadlineTimer)
+                this.timerClearer(pending.deadlineTimer);
+            this.pendingRequests.delete(key);
+            this.recordFinalityTombstone(key, snapshot.mode);
+        }
+        this.writeToClient(decorateSyntheticReply(reply, snapshot.era), snapshot.mode);
+    }
+    /**
+     * Records a response-finality tombstone for a request instance the
+     * supervisor has terminally settled (synthesized reply or client
+     * cancellation). Insertion-order eviction at MAX_SYNTHETIC_TOMBSTONES keeps
+     * the map bounded even inside one healthy worker generation, where the
+     * per-generation purge cannot fire.
+     */
+    recordFinalityTombstone(key, mode) {
+        // Re-set moves an existing key to the end of the insertion order, so the
+        // eviction victim is always the least recently recorded tombstone.
+        this.syntheticTombstones.delete(key);
+        this.syntheticTombstones.set(key, { generation: this.workerGeneration, mode });
+        while (this.syntheticTombstones.size > MAX_SYNTHETIC_TOMBSTONES) {
+            const oldest = this.syntheticTombstones.keys().next();
+            if (oldest.done)
+                break;
+            this.syntheticTombstones.delete(oldest.value);
+            debugSupervisor("tombstone_evicted", { key: oldest.value, cap: MAX_SYNTHETIC_TOMBSTONES });
+        }
+    }
+    /**
+     * Retention bound for finality tombstones: generation `generation` is gone
+     * with streams closed, so every tombstone recorded at or before it is
+     * unreachable (see syntheticTombstones doc) and may be dropped.
+     */
+    purgeTombstonesThroughGeneration(generation) {
+        for (const [key, tombstone] of this.syntheticTombstones) {
+            if (tombstone.generation <= generation) {
+                this.syntheticTombstones.delete(key);
+            }
         }
     }
-    writeToClient(message) {
+    /**
+     * Writes one client-bound message. `mode` is the ORIGINATING REQUEST's
+     * captured framing; callers omit it only for writes that correlate to no
+     * request id, which fall back to the last-detected inbound mode.
+     */
+    writeToClient(message, mode) {
+        const effectiveMode = mode ?? this.lastInboundClientMode;
         debugSupervisor("write_to_client", {
             hasMethod: "method" in message,
             method: "method" in message ? message.method : undefined,
             id: "id" in message ? message.id : undefined,
-            clientMode: this.clientMode
+            clientMode: effectiveMode
         });
         try {
             if (this.clientWriter) {
                 this.clientWriter(message);
                 return;
             }
-            const frame = encodeJsonRpcMessage(message, this.clientMode);
+            const frame = encodeJsonRpcMessage(message, effectiveMode);
             process.stdout.write(frame);
         }
         catch (error) {
@@ -1164,14 +1986,33 @@ export class StdioSupervisor {
     clearInitialInitializationState() {
         if (this.clientInitialized)
             return;
+        if (this.initializeRequest) {
+            // A preserved not-yet-answered initialize map entry (kept across worker
+            // exit for replay correlation) is orphaned once the cached handshake is
+            // discarded: no replay can ever answer it, and leaving it would block
+            // validate-project dispatch forever and resurface at the next worker
+            // exit as a duplicate reply. Drop it without a tombstone — its
+            // generation is gone, so no late answer can arrive.
+            const staleKey = requestKey(this.initializeRequest.id);
+            const stale = this.pendingRequests.get(staleKey);
+            if (stale?.method === "initialize") {
+                if (stale.deadlineTimer)
+                    this.timerClearer(stale.deadlineTimer);
+                this.pendingRequests.delete(staleKey);
+            }
+        }
         this.initializeRequest = undefined;
         this.initializedNotification = undefined;
+        this.initializePredecessorCount = 0;
         this.replayingInitialization = false;
         this.initializeSentToWorker = false;
     }
     liveCapOccupancy() {
         return this.liveChildren.size + this.unresolvedTreeTokens.size;
     }
+    get unresolvedTreeTokenCount() {
+        return this.unresolvedTreeTokens.size;
+    }
     clearStartupWatchdog() {
         if (this.startupWatchdog) {
             this.timerClearer(this.startupWatchdog);
@@ -1181,6 +2022,7 @@ export class StdioSupervisor {
     adoptActiveChild() {
         this.clearStartupWatchdog();
         this.childReady = true;
+        this.childReadyAt ??= this.monotonicNow();
         this.restartBackoff.reset();
         this.currentRetryEpoch = undefined;
         this.currentRetryReservation = undefined;
@@ -1192,6 +2034,7 @@ export class StdioSupervisor {
         this.clearStartupWatchdog();
         this.child = undefined;
         this.childReady = false;
+        this.childReadyAt = undefined;
         this.replayingInitialization = false;
         this.initializeSentToWorker = false;
         this.staleChildren.add(child);
@@ -1205,6 +2048,7 @@ export class StdioSupervisor {
         this.clearStartupWatchdog();
         this.child = undefined;
         this.childReady = false;
+        this.childReadyAt = undefined;
         this.replayingInitialization = false;
         this.initializeSentToWorker = false;
         if (child) {
@@ -1328,15 +2172,64 @@ export class StdioSupervisor {
             return;
         if (success) {
             this.unresolvedTreeTokens.delete(cleanup.pid);
+            this.cleanupRetryAttempts.delete(cleanup.pid);
             this.cleanupStates.delete(child);
+            this.stopCleanupTokenRetryIfIdle();
         }
         else {
             this.unresolvedTreeTokens.add(cleanup.pid);
+            this.scheduleCleanupTokenRetry();
         }
         this.resumePausedRestart();
         this.drainQueue();
     }
-    async retryUnresolvedTreeToken(pid) {
+    scheduleCleanupTokenRetry() {
+        if (this.shuttingDown || this.cleanupRetryTimer || this.unresolvedTreeTokens.size === 0)
+            return;
+        const delayMs = Math.min(this.cleanupTokenRetryBaseMs * (2 ** this.cleanupRetryIndex), this.cleanupTokenRetryCapMs);
+        this.cleanupRetryIndex += 1;
+        this.cleanupRetryTimer = this.timerScheduler(() => {
+            this.cleanupRetryTimer = undefined;
+            void this.runCleanupTokenRetries();
+        }, delayMs);
+        this.cleanupRetryTimer.unref();
+    }
+    async runCleanupTokenRetries() {
+        await Promise.all([...this.unresolvedTreeTokens].map((pid) => this.retryUnresolvedTreeToken(pid)));
+        if (this.unresolvedTreeTokens.size === 0) {
+            this.cleanupRetryIndex = 0;
+            return;
+        }
+        this.scheduleCleanupTokenRetry();
+    }
+    stopCleanupTokenRetryIfIdle() {
+        if (this.unresolvedTreeTokens.size > 0)
+            return;
+        if (this.cleanupRetryTimer) {
+            this.timerClearer(this.cleanupRetryTimer);
+            this.cleanupRetryTimer = undefined;
+        }
+        this.cleanupRetryIndex = 0;
+        this.cleanupRetryAttempts.clear();
+    }
+    retryUnresolvedTreeToken(pid) {
+        const existing = this.cleanupRetriesInFlight.get(pid);
+        if (existing)
+            return existing;
+        const retry = this.performUnresolvedTreeTokenRetry(pid);
+        this.cleanupRetriesInFlight.set(pid, retry);
+        return retry.finally(() => {
+            if (this.cleanupRetriesInFlight.get(pid) === retry) {
+                this.cleanupRetriesInFlight.delete(pid);
+            }
+        });
+    }
+    async performUnresolvedTreeTokenRetry(pid) {
+        if (!this.unresolvedTreeTokens.has(pid))
+            return;
+        const attempt = (this.cleanupRetryAttempts.get(pid) ?? 0) + 1;
+        this.cleanupRetryAttempts.set(pid, attempt);
+        this.eventWriter("warn", "supervisor.cleanup_token.retry", { pid, attempt });
         let success = false;
         if (this.treeTokenRetrier) {
             success = await settleTreeCleanupWithin(Promise.resolve().then(() => this.treeTokenRetrier(pid)), this.treeCleanupTimeoutMs);
@@ -1374,14 +2267,23 @@ export class StdioSupervisor {
                 catch { /* best effort */ }
             });
         }
-        if (!success)
+        if (!success || !this.unresolvedTreeTokens.has(pid))
             return;
         this.unresolvedTreeTokens.delete(pid);
+        this.cleanupRetryAttempts.delete(pid);
         for (const [child, cleanup] of this.cleanupStates) {
             if (cleanup.pid === pid && cleanup.parentExited) {
                 this.cleanupStates.delete(child);
             }
         }
+        this.eventWriter("info", "supervisor.cleanup_token.recovered", {
+            pid,
+            attempt,
+            unresolvedTreeTokens: this.unresolvedTreeTokens.size
+        });
+        this.stopCleanupTokenRetryIfIdle();
+        this.resumePausedRestart();
+        this.drainQueue();
     }
     handleStartupFailure(token, exit) {
         if (token !== this.attemptToken && this.child !== undefined)
@@ -1399,12 +2301,16 @@ export class StdioSupervisor {
             const { reply } = buildWorkerRestartReply(pending, exit, now, [], {
                 structuredRestartDisabled: STRUCTURED_RESTART_DISABLED
             });
-            this.writeToClient(reply);
+            this.writeSyntheticReply(pending, reply);
         }
         const retainedInitialize = this.queuedNotifications.find((message) => isRequest(message) && message.method === "initialize");
         this.queuedNotifications.splice(0, this.queuedNotifications.length);
         if (retainedInitialize && isRequest(retainedInitialize)) {
-            this.writeToClient(buildLegacyJsonRpcError(retainedInitialize.id));
+            this.writeSyntheticReply({
+                id: retainedInitialize.id,
+                era: this.era,
+                mode: this.modeForMessage(retainedInitialize)
+            }, buildLegacyJsonRpcError(retainedInitialize.id));
         }
         this.clearInitialInitializationState();
         this.validateBarrierKey = undefined;
@@ -1419,6 +2325,13 @@ export class StdioSupervisor {
         this.currentRetryEpoch = reservation.epoch;
         if (this.liveCapOccupancy() >= 2) {
             this.retryPaused = true;
+            this.eventWriter("warn", "supervisor.live_cap.saturated", {
+                occupancy: this.liveCapOccupancy(),
+                cap: 2,
+                liveChildren: this.liveChildren.size,
+                unresolvedTreeTokens: this.unresolvedTreeTokens.size,
+                reason: "restart-blocked"
+            });
             return;
         }
         this.armRestartReservation(reservation);
@@ -1458,11 +2371,25 @@ export class StdioSupervisor {
             return;
         this.armRestartReservation(reservation);
     }
-    async shutdown() {
+    /**
+     * Idempotent teardown. Every caller receives the SAME promise, so a caller
+     * that needs to know when cleanup is really finished — the fatal handler,
+     * which then ends the process — cannot be handed an already-resolved promise
+     * while another teardown is still collecting the worker's process group.
+     */
+    shutdown() {
+        this.shutdownRun ??= this.runShutdown();
+        return this.shutdownRun;
+    }
+    async runShutdown() {
         if (this.shuttingDown) {
             return;
         }
         this.shuttingDown = true;
+        if (this.cleanupRetryTimer) {
+            this.timerClearer(this.cleanupRetryTimer);
+            this.cleanupRetryTimer = undefined;
+        }
         if (this.restartTimer) {
             this.timerClearer(this.restartTimer);
             this.restartTimer = undefined;
@@ -1481,17 +2408,41 @@ export class StdioSupervisor {
         }
         this.pendingRequests.clear();
         this.queuedRequests.splice(0, this.queuedRequests.length);
+        this.syntheticTombstones.clear();
         process.stdin.off("data", this.handleClientData);
         process.stdin.off("error", this.handleClientError);
         process.stdin.off("end", this.handleClientClosed);
         process.stdin.off("close", this.handleClientClosed);
+        // Symmetric with start()'s resume(). Without this a shutdown triggered
+        // while stdin is still OPEN (a framing-fatal teardown, a signal) leaves the
+        // stdin handle referenced and the process alive with nothing left to serve;
+        // the ordinary shutdown path never noticed because stdin had already ended.
+        // pause() stops the flow, unref() releases the event-loop reference (absent
+        // on a file-backed stdin, hence the guard).
+        process.stdin.pause();
+        const unrefStdin = process.stdin.unref;
+        if (typeof unrefStdin === "function") {
+            unrefStdin.call(process.stdin);
+        }
         process.off("SIGINT", this.handleTerminateSignal);
         process.off("SIGTERM", this.handleTerminateSignal);
+        process.off("SIGHUP", this.handleTerminateSignal);
         this.detachCurrentChild();
         for (const child of this.liveChildren) {
             this.beginTreeTermination(child);
         }
-        await Promise.all([...this.unresolvedTreeTokens].map((pid) => this.retryUnresolvedTreeToken(pid)));
+        try {
+            await Promise.all([...this.unresolvedTreeTokens].map((pid) => this.retryUnresolvedTreeToken(pid)));
+        }
+        finally {
+            // Deregistered only once the teardown TAIL is done. Dropping them before
+            // the await left a rejection raised while the worker group was still
+            // being collected with nowhere to go: node's default handler is
+            // suppressed for the lifetime of a registration, and this one had
+            // already been withdrawn.
+            process.off("uncaughtException", this.handleFatalError);
+            process.off("unhandledRejection", this.handleFatalError);
+        }
     }
 }
 export const STDIO_WORKER_MODE_ENV = WORKER_MODE_ENV;