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

package/dist/stdio-supervisor.js

@@ -1928,8 +1928,10 @@ export class StdioSupervisor {
                     message: detail
                 });
             });
+            const key = requestKey(entry.pending.id);
+            let released = false;
+            let attemptedRelease = false;
             this.runRecoveryStep("queue.dispatch_settle", () => {
-                const key = requestKey(entry.pending.id);
                 // 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
@@ -1937,17 +1939,51 @@ export class StdioSupervisor {
                 // different live request, which keeps its own guarantee.
                 if (this.pendingRequests.get(key) !== entry.pending)
                     return;
-                if (!this.releaseForwardedRequest(key, entry.pending))
-                    return;
-                this.writeSyntheticReply(entry.pending, {
-                    jsonrpc: "2.0",
-                    id: entry.pending.id,
-                    error: {
-                        code: -32603,
-                        message: `MCP supervisor failed to dispatch the queued request: ${detail}`
-                    }
-                });
+                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;
         }
     }
@@ -1966,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;
@@ -2166,7 +2202,33 @@ export class StdioSupervisor {
             // 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();
                 });
@@ -2219,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
@@ -2379,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));
@@ -2401,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);
@@ -2409,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;
         }
@@ -2446,13 +2558,19 @@ export class StdioSupervisor {
                     // branch above, never here.
                     this.settlingWorkerResponse = { key, snapshot: pending };
                 }
-                if (pending?.deadlineTimer)
-                    this.timerClearer(pending.deadlineTimer);
+                // 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);
@@ -2558,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);
         }
@@ -2566,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);
+            });
         }
     }
     /**
@@ -2688,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)
             });
         }
     }

package/dist/storage/db.d.ts

@@ -1,5 +1,6 @@
-import Database from "./sqlite.js";
+import Database, { isRawSqliteCorruptionError } from "./sqlite.js";
 import type { Config } from "../types.js";
+export { isRawSqliteCorruptionError };
 type SqliteDatabase = InstanceType<typeof Database>;
 type Logger = {
     warn: (message: string, details?: Record<string, unknown>) => void;
@@ -11,5 +12,64 @@ export interface InitializedDatabase {
     schemaVersion: number;
 }
 type DatabaseConfig = Pick<Config, "sqlitePath"> & Partial<Pick<Config, "sqliteCacheKb" | "sqliteMmapSize">>;
+/**
+ * Best-effort request that the NEXT `openDatabase` for `sqlitePath` run the
+ * full `PRAGMA integrity_check` instead of the default `quick_check`. Creates
+ * a new, uniquely-named request file (see the block comment above) with
+ * exclusive-create so it can never collide with or overwrite another
+ * pending request. Never throws: a failure to write the file only means the
+ * escalation is missed, which is logged rather than allowed to mask the
+ * caller's real error. Returns whether the file was actually written, so a
+ * caller that cannot schedule the follow-up check can say so instead of
+ * promising one.
+ */
+export declare function requestFullIntegrityCheck(sqlitePath: string, logger?: Logger): boolean;
+/**
+ * Lists the full paths of every currently pending full-integrity-check
+ * request file for `sqlitePath`. Best-effort: a missing or unreadable
+ * directory is treated as "no requests pending" rather than as an error,
+ * since the fallback (a quick_check) is always safe to run.
+ */
+export declare function listIntegrityCheckRequestFiles(sqlitePath: string): string[];
+/**
+ * Deletes EXACTLY the given request file paths - the ones an earlier
+ * `listIntegrityCheckRequestFiles` call returned, never a fresh listing - so
+ * a request file created after that decision point is never deleted by a
+ * clear that only ever meant to honor the requests it actually acted on.
+ * Best-effort per file: ENOENT (already gone) is ignored, anything else is
+ * logged, not thrown.
+ *
+ * Exported so a unit test can exercise the race guard directly:
+ * `openDatabase` lists-then-clears synchronously with no `await` in between,
+ * so there is no way to interleave a concurrent request file appearing
+ * between "decide" and "clear" from outside that call.
+ */
+export declare function clearIntegrityCheckRequestFiles(requestFiles: string[], logger?: Logger): void;
+/**
+ * Wires a Database instance's corruption observer (see sqlite.ts) so that a
+ * raw corruption error thrown by ANY later statement on this handle - no
+ * matter what catches and wraps it further up the call stack, including a
+ * tool-specific error wrapper that never reaches runTool's own catch block -
+ * still schedules the next open's full integrity_check. Exported so a unit
+ * test can attach the same wiring to a Database instance opened directly
+ * (bypassing openDatabase's own open-time check, which would otherwise catch
+ * a test's injected corruption before a "successfully opened" handle ever
+ * existed to query against).
+ */
+export declare function attachRuntimeCorruptionObserver(db: SqliteDatabase, sqlitePath: string, logger?: Logger): void;
+/**
+ * runTool catch-path helper: when `caughtError` is a raw SQLite corruption
+ * error observed while serving a tool call (not at open time - open-time
+ * corruption is already an AppError by the time it reaches here), this
+ * requests a full integrity check on the next open and returns a typed
+ * ERR_DB_FAILURE the caller should report instead of the raw error. Any other
+ * error is returned unchanged so non-corruption failures are unaffected.
+ *
+ * The marker request here is redundant with the Database corruption observer
+ * (attachRuntimeCorruptionObserver) for an UNWRAPPED raw error, since that
+ * observer already fired deeper in the call stack; it is kept because
+ * `convertRuntimeSqliteCorruption` is the only place with reliable access to
+ * whether scheduling succeeded, which decides which `nextAction` to publish.
+ */
+export declare function convertRuntimeSqliteCorruption(error: unknown, sqlitePath: string, logger?: Logger): unknown;
 export declare function openDatabase(config: DatabaseConfig, logger?: Logger): InitializedDatabase;
-export {};