@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/source-resolver.js

@@ -1,21 +1,22 @@
 import { readdir } from "node:fs/promises";
 import { basename, dirname, join, resolve as resolvePath, sep } from "node:path";
-import { homedir } from "node:os";
 import fastGlob from "fast-glob";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
+import { resolveGradleUserHomePath } from "./gradle-paths.js";
 import { buildRemoteBinaryUrls, buildRemoteSourceUrls, groupToPath, hasExistingJar, isMutableMavenCoordinate, parseCoordinate, normalizedCoordinateValue } from "./maven-resolver.js";
 import { defaultDownloadPath, discardCachedDownload, resolveCachedDownload } from "./repo-downloader.js";
 import { normalizeJarPath } from "./path-resolver.js";
 import { composeArtifactId, contentDigestSignature, contentSignature, jarArtifactIdentity, DECOMPILE_SIGNATURE_QUALIFIER } from "./artifact-identity.js";
-import { hasAnyJarEntry, hasJavaSourceExtension } from "./source-jar-reader.js";
+import { hasAnyJarEntry, hasJavaSourceExtension, scanJarForJavaSources } from "./source-jar-reader.js";
 /**
  * Whether a jar contains java sources, with archive errors deliberately
  * propagating.
  *
  * This is the check for a jar that IS the subject of the request - the
- * `input.kind === "jar"` branch of `resolveSourceTarget` calling it on
- * `resolvedJarPath`. What propagates is the reader's refusal to OPEN the
- * archive: a truncated file, a non-zip file, an unreadable central directory,
+ * `input.kind === "jar"` branch of `resolveSourceTarget` runs it on
+ * `resolvedJarPath` as `scanSubjectJarForJavaSources`, the same walk that also
+ * collects Minecraft runtime signals. What propagates is the reader's refusal
+ * to OPEN the archive: a truncated file, a non-zip file, an unreadable central directory,
  * an I/O failure. On the subject jar that refusal is the verdict itself, and
  * swallowing it would downgrade "this archive could not be read" into "this
  * archive has no sources" - handing back a sibling `-sources.jar` as if the
@@ -73,6 +74,18 @@ async function candidateHasJavaSources(jarPath) {
         return false;
     }
 }
+/**
+ * `hasJavaSources` for the subject jar of a `kind: "jar"` request, returning the
+ * Minecraft runtime signals the same walk collected. Same contract on both counts
+ * that matter: an absent file answers "no sources" without opening anything, and
+ * an archive that cannot be opened propagates.
+ */
+async function scanSubjectJarForJavaSources(jarPath) {
+    if (!hasExistingJar(jarPath)) {
+        return { hasJavaSources: false };
+    }
+    return await scanJarForJavaSources(jarPath);
+}
 function resolveExactJarSourceCandidate(inputJarPath) {
     const directory = dirname(inputJarPath);
     const jarName = basename(inputJarPath);
@@ -331,16 +344,9 @@ async function firstReadableJarArchive(candidates) {
     }
     return undefined;
 }
-function resolveGradleUserHome() {
-    const configured = process.env.GRADLE_USER_HOME?.trim();
-    if (configured) {
-        return configured;
-    }
-    return resolvePath(homedir(), ".gradle");
-}
 async function resolveGradleCacheCoordinateCandidate(coordinate) {
     const parsed = parseCoordinate(coordinate);
-    const baseDir = resolvePath(resolveGradleUserHome(), "caches", "modules-2", "files-2.1", parsed.groupId, parsed.artifactId, parsed.version);
+    const baseDir = resolvePath(resolveGradleUserHomePath(), "caches", "modules-2", "files-2.1", parsed.groupId, parsed.artifactId, parsed.version);
     const base = `${parsed.artifactId}-${parsed.version}`;
     const classifierSuffix = parsed.classifier ? `-${parsed.classifier}` : "";
     const preferredSourceNames = [
@@ -526,7 +532,9 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
         const adjacentSourceCandidates = await listAdjacentJarSourceCandidates(resolvedJarPath);
         const maybeAdjacentSourceCandidates = adjacentSourceCandidates.length > 0 ? adjacentSourceCandidates : undefined;
         const preferBinaryOnly = options.preferBinaryOnly ?? false;
-        if (await hasJavaSources(resolvedJarPath)) {
+        const subjectScan = await scanSubjectJarForJavaSources(resolvedJarPath);
+        options.onSubjectJarScanned?.(subjectScan);
+        if (subjectScan.hasJavaSources) {
             const siblingBinaryJarPath = resolveSiblingBinaryJarCandidate(resolvedJarPath);
             const binaryJarPath = siblingBinaryJarPath ??
                 (basename(resolvedJarPath).endsWith("-sources.jar") ? undefined : resolvedJarPath);

package/dist/source-service.d.ts

@@ -671,6 +671,11 @@ export declare class SourceService {
     listVersions(input?: ListVersionsInput): Promise<ListVersionsOutput>;
     getRegistryData(input: GetRegistryDataInput): Promise<GetRegistryDataOutput>;
     compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
+    /**
+     * Thin passthrough so entry tools (migration-overview) can diff a version
+     * pair's `libraries` without reaching into VersionService directly.
+     */
+    getVersionLibraries(version: string): Promise<string[]>;
     decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
     /**
      * Member-level view of a third-party mod jar class, read from bytecode

package/dist/source-service.js

@@ -123,6 +123,13 @@ export class SourceService {
     async compareVersions(input) {
         return this.versionDiffService.compareVersions(input);
     }
+    /**
+     * Thin passthrough so entry tools (migration-overview) can diff a version
+     * pair's `libraries` without reaching into VersionService directly.
+     */
+    async getVersionLibraries(version) {
+        return this.versionService.getVersionLibraries(version);
+    }
     async decompileModJar(input) {
         return this.modDecompileService.decompileModJar(input);
     }

package/dist/stdio-supervisor.d.ts

@@ -204,6 +204,15 @@ export declare class StdioSupervisor {
     private readonly unresolvedTreeTokens;
     private readonly restartBackoff;
     private readonly terminalChildren;
+    /**
+     * Workers started by the DEFAULT spawner on POSIX, which spawns them
+     * detached — so each one leads its own process group and `-pid` names
+     * exactly that group. Only these are group-signalled after an unexpected
+     * exit: a child handed in by an injected spawner carries no such guarantee,
+     * and its pid may not be a group id this supervisor owns.
+     */
+    private readonly processGroupLeaders;
+    private readonly spawnsProcessGroupLeaders;
     /**
      * Monotonic worker-generation counter (incremented per successful spawn).
      * Recorded into finality tombstones so retention can be bounded per
@@ -310,7 +319,8 @@ export declare class StdioSupervisor {
      * 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.
+     * suffix gated until the initialization response. A RE-initialize (the era
+     * is already legacy) has no prefix at all: nothing queued may overtake it.
      */
     private initializePredecessorCount;
     private clientInitialized;
@@ -739,6 +749,30 @@ export declare class StdioSupervisor {
     private adoptActiveChild;
     private invalidateCurrentChild;
     private detachCurrentChild;
+    /**
+     * Signals the process group of a worker that exited UNEXPECTEDLY, so the
+     * descendants it leaves behind (a Java grandchild above all) are not
+     * orphaned.
+     *
+     * PID reuse: this runs from the worker's `exit` event, after the worker
+     * itself was reaped, so its pid is free again. The kernel still refuses to
+     * hand that number out as a new pid or pgid while ANY member of the old
+     * group is alive — so while there is something left to reap, `-pid` names
+     * exactly that group. The residual race (the group already empty AND the
+     * number reused by a new group leader in between) is accepted as negligible.
+     * pidfd-based group signalling would close it but needs Linux 6.9+.
+     *
+     * Fire-and-forget by design: it is not recorded as an in-flight cleanup, so
+     * it never occupies a live-generation slot or delays the replacement.
+     *
+     * Windows: `taskkill /T` walks the tree from its root, and the root has
+     * already exited here, so there is nothing it can find. Descendants of a
+     * crashed worker are not reaped on Windows (known limitation).
+     *
+     * Logged `result`: "signalled" (the group had members and was signalled),
+     * "group-empty" (ESRCH — nothing was left), or "failed".
+     */
+    private reapExitedWorkerGroup;
     private recoverTimedOutWorker;
     private beginTreeTermination;
     private finishTreeTermination;

package/dist/stdio-supervisor.js

@@ -670,6 +670,15 @@ export class StdioSupervisor {
     unresolvedTreeTokens = new Set();
     restartBackoff = new RestartBackoffState();
     terminalChildren = new WeakSet();
+    /**
+     * Workers started by the DEFAULT spawner on POSIX, which spawns them
+     * detached — so each one leads its own process group and `-pid` names
+     * exactly that group. Only these are group-signalled after an unexpected
+     * exit: a child handed in by an injected spawner carries no such guarantee,
+     * and its pid may not be a group id this supervisor owns.
+     */
+    processGroupLeaders = new WeakSet();
+    spawnsProcessGroupLeaders;
     /**
      * Monotonic worker-generation counter (incremented per successful spawn).
      * Recorded into finality tombstones so retention can be bounded per
@@ -776,7 +785,8 @@ export class StdioSupervisor {
      * 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.
+     * suffix gated until the initialization response. A RE-initialize (the era
+     * is already legacy) has no prefix at all: nothing queued may overtake it.
      */
     initializePredecessorCount = 0;
     clientInitialized = false;
@@ -818,6 +828,7 @@ export class StdioSupervisor {
         this.monotonicNow = options.monotonicNow ?? (() => performance.now());
         this.timerScheduler = options.timerScheduler ?? ((callback, delayMs) => setTimeout(callback, delayMs));
         this.timerClearer = options.timerClearer ?? ((timer) => clearTimeout(timer));
+        this.spawnsProcessGroupLeaders = options.workerSpawner === undefined && process.platform !== "win32";
         this.workerSpawner = options.workerSpawner ?? (() => spawn(process.execPath, [...process.execArgv, this.entryFile], {
             env: {
                 ...process.env,
@@ -1246,6 +1257,7 @@ export class StdioSupervisor {
                 this.writeToClient(buildInvalidInitializeRejection(message.id), this.modeForMessage(message));
                 return;
             }
+            const eraBeforeInitialize = this.era;
             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
@@ -1270,7 +1282,13 @@ export class StdioSupervisor {
                 this.forwardRequest(message, this.createPendingRequest(message));
             }
             else {
-                this.initializePredecessorCount = this.queuedRequests.length;
+                // Only an INITIAL initialize owns a releasable prefix: while the era
+                // was unselected the sole request that can have queued is an
+                // era-neutral discover. Once legacy is locked ordinary requests queue
+                // too, and letting them overtake a RE-sent initialize would hand them
+                // to an un-handshaken replacement worker.
+                this.initializePredecessorCount =
+                    eraBeforeInitialize === "unselected" ? this.queuedRequests.length : 0;
                 const existing = this.queuedNotifications.findIndex((entry) => isRequest(entry) && entry.method === "initialize");
                 if (existing >= 0)
                     this.queuedNotifications.splice(existing, 1);
@@ -2009,6 +2027,8 @@ export class StdioSupervisor {
         }
         this.child = child;
         this.liveChildren.add(child);
+        if (this.spawnsProcessGroupLeaders)
+            this.processGroupLeaders.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
@@ -2407,6 +2427,10 @@ export class StdioSupervisor {
         const wasReady = this.childReady;
         const readyAt = this.childReadyAt;
         this.detachCurrentChild();
+        // The worker ended on its own (crash, OOM, an external kill of the worker
+        // alone): no supervisor-initiated termination ran, so any descendant it
+        // forked is still alive in its process group with no other owner.
+        this.reapExitedWorkerGroup(child, childPid);
         if (this.shuttingDown) {
             return;
         }
@@ -2925,6 +2949,57 @@ export class StdioSupervisor {
             child.stdin.removeAllListeners("error");
         }
     }
+    /**
+     * Signals the process group of a worker that exited UNEXPECTEDLY, so the
+     * descendants it leaves behind (a Java grandchild above all) are not
+     * orphaned.
+     *
+     * PID reuse: this runs from the worker's `exit` event, after the worker
+     * itself was reaped, so its pid is free again. The kernel still refuses to
+     * hand that number out as a new pid or pgid while ANY member of the old
+     * group is alive — so while there is something left to reap, `-pid` names
+     * exactly that group. The residual race (the group already empty AND the
+     * number reused by a new group leader in between) is accepted as negligible.
+     * pidfd-based group signalling would close it but needs Linux 6.9+.
+     *
+     * Fire-and-forget by design: it is not recorded as an in-flight cleanup, so
+     * it never occupies a live-generation slot or delays the replacement.
+     *
+     * Windows: `taskkill /T` walks the tree from its root, and the root has
+     * already exited here, so there is nothing it can find. Descendants of a
+     * crashed worker are not reaped on Windows (known limitation).
+     *
+     * Logged `result`: "signalled" (the group had members and was signalled),
+     * "group-empty" (ESRCH — nothing was left), or "failed".
+     */
+    reapExitedWorkerGroup(child, pid) {
+        if (pid === undefined)
+            return;
+        const report = (result) => {
+            this.eventWriter(result === "failed" ? "warn" : "info", "supervisor.worker_exit_group_cleanup", {
+                pid,
+                result
+            });
+        };
+        if (process.platform === "win32") {
+            debugSupervisor("worker_exit_group_unreachable", { pid });
+            return;
+        }
+        if (!this.processGroupLeaders.has(child))
+            return;
+        let groupEmpty = false;
+        const signalled = terminatePosixProcessGroup(pid, (target, signal) => {
+            try {
+                process.kill(target, signal);
+            }
+            catch (error) {
+                if (error?.code === "ESRCH")
+                    groupEmpty = true;
+                throw error;
+            }
+        });
+        report(!signalled ? "failed" : groupEmpty ? "group-empty" : "signalled");
+    }
     recoverTimedOutWorker() {
         const child = this.child;
         if (!child) {

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 {};

package/dist/storage/db.js

@@ -1,22 +1,131 @@
-import { existsSync, renameSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { mkdirSync } from "node:fs";
-import Database from "./sqlite.js";
+import { randomUUID } from "node:crypto";
+import Database, { isRawSqliteCorruptionError } from "./sqlite.js";
 import { runMigrations } from "./migrations.js";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { log } from "../logger.js";
+// Re-exported for callers that already import the predicate from this module
+// (it now lives in ./sqlite.js so the Database wrapper can call it directly
+// without a module cycle back to this file).
+export { isRawSqliteCorruptionError };
 const DEFAULT_SQLITE_CACHE_KB = 8_000;
 const DEFAULT_SQLITE_MMAP_SIZE = 268_435_456;
+// Per-request escalation files created by the runtime-corruption recovery
+// path (see attachRuntimeCorruptionObserver / convertRuntimeSqliteCorruption
+// below): a SQLite error surfaced while serving a tool call - not at open
+// time - means quick_check already passed for this file, so the NEXT open
+// must pay for the full integrity_check instead of trusting quick_check
+// again.
+//
+// Each request is its OWN immutable, uniquely-named file (exclusive-create,
+// never overwritten), rather than one shared marker whose content gets
+// replaced. That is what makes two requests race-free even across processes
+// sharing one cache directory: an open lists whatever request files exist at
+// its OWN decision point and remembers those exact names; after honoring
+// them, it deletes only those names. A request file created by someone else
+// AFTER that decision (a concurrent process, or a second corruption event)
+// is simply a name that open never saw, so it can never be swept up by a
+// clear meant for a different, earlier decision - it waits for the NEXT
+// open. (An earlier single shared marker file, `<sqlitePath>.integrity-check-
+// requested`, was never released, so there is no old name to keep reading
+// for compatibility; it is dropped outright rather than special-cased.)
+const INTEGRITY_CHECK_REQUEST_INFIX = ".integrity-check-requested.";
 function ensureParentDirectory(path) {
     mkdirSync(dirname(path), { recursive: true });
 }
-function runIntegrityCheck(db) {
-    const result = db.prepare("PRAGMA integrity_check").get();
-    if (!result || result.integrity_check !== "ok") {
+function integrityCheckRequestFileName(sqlitePath, token) {
+    return `${basename(sqlitePath)}${INTEGRITY_CHECK_REQUEST_INFIX}${token}`;
+}
+function integrityCheckRequestFileNamePrefix(sqlitePath) {
+    return `${basename(sqlitePath)}${INTEGRITY_CHECK_REQUEST_INFIX}`;
+}
+/**
+ * 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 function requestFullIntegrityCheck(sqlitePath, logger = buildDefaultLogger()) {
+    const token = `${Date.now()}-${process.pid}-${randomUUID()}`;
+    const requestPath = join(dirname(sqlitePath), integrityCheckRequestFileName(sqlitePath, token));
+    try {
+        ensureParentDirectory(sqlitePath);
+        writeFileSync(requestPath, "", { flag: "wx" });
+        return true;
+    }
+    catch (writeError) {
+        logger.warn("Failed to request a full SQLite integrity check", {
+            sqlitePath,
+            reason: writeError instanceof Error ? writeError.message : String(writeError)
+        });
+        return false;
+    }
+}
+/**
+ * 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 function listIntegrityCheckRequestFiles(sqlitePath) {
+    const dir = dirname(sqlitePath);
+    const prefix = integrityCheckRequestFileNamePrefix(sqlitePath);
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.startsWith(prefix))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function clearIntegrityCheckRequestFiles(requestFiles, logger = buildDefaultLogger()) {
+    for (const requestFile of requestFiles) {
+        try {
+            unlinkSync(requestFile);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                continue;
+            }
+            logger.warn("Failed to clear a SQLite full-integrity-check request file", {
+                requestFile,
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+}
+function runIntegrityCheck(db, logger, mode = "quick") {
+    const resultKey = mode === "full" ? "integrity_check" : "quick_check";
+    const startedAt = Date.now();
+    const result = db.prepare(`PRAGMA ${resultKey}`).get();
+    const durationMs = Date.now() - startedAt;
+    logger.info("SQLite consistency check completed", { durationMs, check: resultKey });
+    if (!result || result[resultKey] !== "ok") {
         throw createError({
             code: ERROR_CODES.DB_FAILURE,
             message: "SQLite integrity check failed.",
-            details: { reason: "integrity_check_failed", integrityCheck: result }
+            details: { reason: "integrity_check_failed", check: resultKey, checkResult: result }
         });
     }
 }
@@ -60,21 +169,59 @@ function isSchemaVersionMismatchError(error) {
     return (error.details?.reason === "schema_version_unsupported" ||
         error.details?.reason === "schema_version_invalid");
 }
-const SQLITE_CORRUPT_ERRCODE = 11;
-const SQLITE_NOTADB_ERRCODE = 26;
 function isCorruptionError(error) {
     if (isAppError(error)) {
         return (error.code === ERROR_CODES.DB_FAILURE && error.details?.reason === "integrity_check_failed");
     }
-    const sqliteError = error;
-    if (sqliteError?.code === "SQLITE_CORRUPT" || sqliteError?.code === "SQLITE_NOTADB") {
-        return true;
-    }
-    if (typeof sqliteError?.errcode !== "number") {
-        return false;
+    return isRawSqliteCorruptionError(error);
+}
+/**
+ * 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 function attachRuntimeCorruptionObserver(db, sqlitePath, logger = buildDefaultLogger()) {
+    db.setCorruptionObserver(() => {
+        requestFullIntegrityCheck(sqlitePath, logger);
+    });
+}
+/**
+ * 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 function convertRuntimeSqliteCorruption(error, sqlitePath, logger = buildDefaultLogger()) {
+    if (!isRawSqliteCorruptionError(error)) {
+        return error;
     }
-    const primaryErrcode = sqliteError.errcode & 0xff;
-    return primaryErrcode === SQLITE_CORRUPT_ERRCODE || primaryErrcode === SQLITE_NOTADB_ERRCODE;
+    const scheduled = requestFullIntegrityCheck(sqlitePath, logger);
+    const nextAction = scheduled
+        ? "Restart the MCP server so the cache database is fully checked and rebuilt if necessary, then retry the request."
+        : `The automatic full check could not be scheduled. Stop every MCP server process that uses this cache, delete the cache database at ${sqlitePath} together with its -wal and -shm files, then restart; the cache is rebuilt on the next start.`;
+    return createError({
+        code: ERROR_CODES.DB_FAILURE,
+        message: "A SQLite consistency error occurred while serving this request.",
+        details: {
+            sqlitePath,
+            reason: "runtime_corruption",
+            nextAction
+        }
+    });
 }
 function buildDefaultLogger() {
     return {
@@ -100,12 +247,21 @@ function buildDefaultLogger() {
 }
 export function openDatabase(config, logger = buildDefaultLogger()) {
     let db;
+    const pendingRequestFiles = listIntegrityCheckRequestFiles(config.sqlitePath);
     try {
         ensureParentDirectory(config.sqlitePath);
         db = new Database(config.sqlitePath);
         applyPragmas(db, config);
         const schemaVersion = runMigrations(db);
-        runIntegrityCheck(db);
+        runIntegrityCheck(db, logger, pendingRequestFiles.length > 0 ? "full" : "quick");
+        if (pendingRequestFiles.length > 0) {
+            clearIntegrityCheckRequestFiles(pendingRequestFiles, logger);
+        }
+        // Only attach the runtime-corruption observer once the open itself
+        // (migrations + consistency check) has fully succeeded: open-time
+        // failures must keep going through the backup/rebuild path below, not
+        // silently re-request a check that is about to happen anyway.
+        attachRuntimeCorruptionObserver(db, config.sqlitePath, logger);
         return { db, schemaVersion };
     }
     catch (caughtError) {
@@ -152,12 +308,17 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
                 const backupPath = backupCorruptedDb(config.sqlitePath);
                 logger.warn("SQLite database integrity check failed. Recreated database after backup", {
                     sqlitePath: config.sqlitePath,
-                    backupPath
+                    backupPath,
+                    reason: errorMessage
                 });
                 rebuilt = new Database(config.sqlitePath);
                 applyPragmas(rebuilt, config);
                 const schemaVersion = runMigrations(rebuilt);
-                runIntegrityCheck(rebuilt);
+                runIntegrityCheck(rebuilt, logger);
+                if (pendingRequestFiles.length > 0) {
+                    clearIntegrityCheckRequestFiles(pendingRequestFiles, logger);
+                }
+                attachRuntimeCorruptionObserver(rebuilt, config.sqlitePath, logger);
                 return { db: rebuilt, schemaVersion };
             }
             catch (rebuildError) {

package/dist/storage/files-repo.d.ts

@@ -19,6 +19,13 @@ export interface SearchFilesOptions {
     cursor?: string;
     mode?: "mixed" | "text" | "path";
     fetchLimitOverride?: number;
+    /**
+     * Literal file_path prefix (e.g. `net/minecraft/`) that narrows the candidate
+     * queries through an escaped, ASCII case-insensitive `LIKE prefix%`. That match
+     * set is a superset of a case-sensitive startsWith, so callers keep their own
+     * exact scope check on the returned candidates.
+     */
+    pathPrefix?: string;
 }
 export interface SearchFilesResult {
     filePath: string;