@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/mixin/access-validators.js

@@ -183,6 +183,17 @@ export function validateParsedAccessTransformer(parsed, membersByClass, warnings
             invalidCount++;
             continue;
         }
+        if (entry.targetKind === "wildcard-all" || entry.targetKind === "wildcard-method") {
+            // A wildcard transforms all members (or all methods); it is valid as long as
+            // the owner class resolved, which it has by this point.
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: true } : {})
+            });
+            validCount++;
+            continue;
+        }
         if (entry.targetKind === "field") {
             const fieldNames = allFieldNames(members);
             const matchedField = members.fields.find((member) => member.name === entry.name);
@@ -215,8 +226,29 @@ export function validateParsedAccessTransformer(parsed, membersByClass, warnings
             continue;
         }
         const methodNames = allMethodNames(members);
-        const matchedMethod = members.methods.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor) ?? members.constructors.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor);
+        const sameNameMethods = [...members.methods, ...members.constructors].filter((member) => member.name === entry.name);
+        // Match by descriptor when one is supplied (AT method lines always carry one);
+        // fall back to a unique name match when it is absent.
+        const matchedMethod = entry.descriptor
+            ? sameNameMethods.find((member) => member.jvmDescriptor === entry.descriptor)
+            : sameNameMethods.length === 1
+                ? sameNameMethods[0]
+                : undefined;
         if (!matchedMethod) {
+            // Distinguish a true missing method from a descriptor mismatch so the user
+            // can see which overloads exist instead of a flat "not found".
+            if (entry.descriptor && sameNameMethods.length > 0) {
+                const available = [...new Set(sameNameMethods.map((member) => member.jvmDescriptor))];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Method "${entry.name}" exists in "${ownerFqn}" but no overload matches descriptor ${entry.descriptor} (available: ${available.join(", ")}).`,
+                    suggestions: available,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
             const suggestions = entry.name ? suggestSimilar(entry.name, methodNames) : [];
             validatedEntries.push({
                 ...entry,

package/dist/mixin/annotation-validators.js

@@ -6,8 +6,26 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             continue;
         const methodNames = allMethodNames(members);
         // Strip owner prefix and JVM descriptor from the method reference
-        const methodName = extractMethodName(inj.method);
-        if (!methodNames.includes(methodName)) {
+        const rawMethodName = extractMethodName(inj.method);
+        // Strip a trailing target-selector quantifier (e.g. "tick*", "tick+", "tick{2,3}")
+        const quantifier = /(?:\*|\+|\{\d+(?:,\d+)?\})$/.exec(rawMethodName)?.[0];
+        const methodName = quantifier
+            ? rawMethodName.slice(0, rawMethodName.length - quantifier.length)
+            : rawMethodName;
+        if (quantifier && methodName === "") {
+            // Bare wildcard selector (e.g. method = "*") matches everything; unverifiable.
+            resolvedMembers.push({
+                annotation: `@${inj.annotation}`,
+                name: rawMethodName,
+                line: inj.line,
+                status: "skipped"
+            });
+            continue;
+        }
+        const matched = (quantifier === "*" || quantifier === "+")
+            ? methodNames.some((n) => n.startsWith(methodName))
+            : methodNames.includes(methodName);
+        if (!matched) {
             const suggestions = suggestSimilar(methodName, methodNames);
             const descriptor = extractMethodDescriptor(inj.method);
             const descriptorHint = descriptor ? ` (descriptor: ${descriptor})` : "";
@@ -43,13 +61,59 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             });
         }
         else {
-            resolvedMembers.push({
-                annotation: `@${inj.annotation}`,
-                name: methodName,
-                line: inj.line,
-                resolvedTo: `${targetName}#${methodName}`,
-                status: "resolved"
-            });
+            // Name matched. If the reference carries a JVM descriptor, require an
+            // overload to match it; otherwise a wrong-signature target (e.g. tick(D)V
+            // when only tick(I)V exists) is silently reported as resolved.
+            const refDescriptor = quantifier ? undefined : extractMethodDescriptor(inj.method);
+            const sameNameMembers = [...members.constructors, ...members.methods].filter((member) => member.name === methodName);
+            if (refDescriptor &&
+                sameNameMembers.length > 0 &&
+                !sameNameMembers.some((member) => member.jvmDescriptor === refDescriptor)) {
+                const available = [...new Set(sameNameMembers.map((member) => member.jvmDescriptor))];
+                const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
+                const isSigFailed = signatureFailedTargets?.has(targetName);
+                // Only a healthy mapping lets us trust that the user-written descriptor is
+                // byte-equal to the runtime descriptor; otherwise downgrade to a warning.
+                const mappingDegraded = Boolean(isRemapFailed) || Boolean(isSigFailed) || healthReport?.overallHealthy === false;
+                const resolutionPath = isRemapFailed
+                    ? "member-remap-failed"
+                    : isSigFailed
+                        ? "source-signature-unavailable"
+                        : undefined;
+                const issueConfidence = mappingDegraded
+                    ? "uncertain"
+                    : confidence ?? "definite";
+                issues.push({
+                    severity: mappingDegraded ? "warning" : "error",
+                    kind: "descriptor-mismatch",
+                    annotation: `@${inj.annotation}`,
+                    target: `${targetName}#${inj.method}`,
+                    message: `Method "${methodName}" exists in "${targetName}" but no overload matches descriptor ${refDescriptor} (available: ${available.join(", ")}).${mappingDegraded ? " (mapping degraded; may be a remap artifact)" : ""}`,
+                    suggestions: available.length > 0 ? available : undefined,
+                    line: inj.line,
+                    confidence: issueConfidence,
+                    confidenceReason: mappingDegraded
+                        ? `Member remap/signature degraded; descriptor mismatch may be a tooling artifact, not a true signature error.`
+                        : confidenceReason,
+                    resolutionPath,
+                    falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+                });
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: methodName,
+                    line: inj.line,
+                    status: "not-found"
+                });
+            }
+            else {
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: methodName,
+                    line: inj.line,
+                    resolvedTo: `${targetName}#${methodName}`,
+                    status: "resolved"
+                });
+            }
         }
     }
 }

package/dist/mixin/parsed-validator.js

@@ -27,6 +27,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     resolutionPath: "target-mapping-failed",
                     falsePositiveRisk: healthReport?.overallHealthy === false ? "high" : "medium"
                 });
+                addSkippedMembers(parsed, resolvedMembers);
             }
             else if (symbolExistsButSignatureFailed?.has(target.className)) {
                 // Symbol exists in mapping graph but getSignature failed — tool limitation, not code issue
@@ -209,7 +210,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version) {
                         assignSuggested(issue, "get-class-source", {
                             className: issue.target,
-                            target: { type: "resolve", kind: "version", value: version },
+                            target: { kind: "version", value: version },
                             ...(mapping ? { mapping } : {}),
                             mode: "metadata",
                             ...classSourceContext
@@ -236,7 +237,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version) {
                         assignSuggested(issue, "get-class-source", {
                             className,
-                            target: { type: "resolve", kind: "version", value: version },
+                            target: { kind: "version", value: version },
                             ...(mapping ? { mapping } : {}),
                             mode: "metadata",
                             ...classSourceContext

package/dist/mixin-parser.js

@@ -5,13 +5,15 @@
 /* ------------------------------------------------------------------ */
 /*  Regex patterns                                                     */
 /* ------------------------------------------------------------------ */
-const CLASS_DECL_RE = /(?:public\s+)?(?:abstract\s+)?(?:class|interface)\s+(\w+)/;
+const CLASS_DECL_RE = /^\s*(?:@[\w$.]+(?:\([^)]*\))?\s+)*(?:public\s+|final\s+|abstract\s+|sealed\s+)*\b(?:class|interface)\s+(\w+)/;
 // import statements for FQCN resolution
 const IMPORT_RE = /^\s*import\s+([\w.]+)\s*;/;
 // @Mixin(Foo.class)  or  @Mixin({Foo.class, Bar.class})  or  @Mixin(value = Foo.class)
 // Also handles  @Mixin(value = {Foo.class, Bar.class}, priority = 900)
 const MIXIN_ANNOTATION_START_RE = /^\s*@Mixin\s*\(/;
-const MIXIN_TARGET_RE = /(\w[\w.]*?)\.class/g;
+// `$` is a legal Java identifier character (e.g. generated classes like My$Class);
+// without it the capture would start mid-name and yield a wrong target.
+const MIXIN_TARGET_RE = /([\w$][\w.$]*?)\.class/g;
 const MIXIN_PRIORITY_RE = /priority\s*=\s*(\d+)/;
 // String-form targets: @Mixin(targets = "pkg.Class") or @Mixin(targets = {"pkg.A", "pkg.B"})
 const MIXIN_TARGETS_STRING_RE = /targets\s*=\s*(?:\{([^}]+)\}|"([^"]+)")/;
@@ -55,15 +57,100 @@ function collectMultilineAnnotation(lines, startIndex) {
     }
     return { text, endIndex: lines.length - 1 };
 }
+/**
+ * Blank out `/* *\/` block comments and `//` line comments (outside string literals)
+ * while preserving line count and line numbers, so the annotation scans never match
+ * inside commented-out code.
+ */
+function stripComments(source) {
+    let out = "";
+    let inBlock = false;
+    let inString = false;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        const next = source[i + 1];
+        if (inBlock) {
+            if (ch === "*" && next === "/") {
+                out += "  ";
+                i++;
+                inBlock = false;
+            }
+            else {
+                out += ch === "\n" ? "\n" : " ";
+            }
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (ch === "\\" && next !== undefined) {
+                out += next;
+                i++;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            out += "  ";
+            i++;
+            inBlock = true;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < source.length && source[i] !== "\n") {
+                i++;
+            }
+            i--;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
 /**
  * Skip past annotations (including multi-line ones) starting at `startIndex`.
  * Returns the index of the first non-annotation line.
  * Lines with inline annotation + declaration (e.g. `@Nullable private int x;`)
  * are treated as declaration lines (not skipped).
  */
+function isUpperCaseLetter(ch) {
+    return ch !== ch.toLowerCase() && ch === ch.toUpperCase();
+}
 function skipAnnotations(lines, startIndex) {
     let idx = startIndex;
-    while (idx < lines.length && /^\s*@/.test(lines[idx])) {
+    while (idx < lines.length) {
+        const current = lines[idx];
+        // Skip blank lines and comment-only lines that sit between an annotation and the
+        // member declaration; otherwise the declaration line is missed and the member dropped.
+        if (/^\s*$/.test(current) || /^\s*\/\//.test(current)) {
+            idx++;
+            continue;
+        }
+        if (/^\s*\/\*/.test(current)) {
+            if (current.includes("*/")) {
+                const afterComment = current.slice(current.indexOf("*/") + 2).trim();
+                if (afterComment === "") {
+                    idx++;
+                    continue;
+                }
+                break; // declaration text follows an inline block comment
+            }
+            idx++;
+            while (idx < lines.length && !lines[idx].includes("*/")) {
+                idx++;
+            }
+            idx++; // move past the closing "*/" line
+            continue;
+        }
+        if (!/^\s*@/.test(current)) {
+            break;
+        }
         if (lines[idx].includes("(")) {
             // Check if parentheses are unbalanced (multi-line annotation) — always skip
             let depth = 0;
@@ -106,18 +193,33 @@ const INLINE_ANNOTATION_RE = /\s*@[\w$.]+(?:\([^)]*\))?\s*/g;
 function stripInlineAnnotations(line) {
     return line.replace(INLINE_ANNOTATION_RE, " ").trim();
 }
+/**
+ * JavaBeans `Introspector.decapitalize`, which SpongePowered Mixin's AccessorInfo
+ * uses for inflection: leave the name unchanged when its first two characters are
+ * both upper case (getURL -> URL, getNBT -> NBT), otherwise lower-case the first
+ * character (getId -> id, getHealth -> health).
+ */
+function decapitalize(name) {
+    if (name.length === 0) {
+        return name;
+    }
+    if (name.length > 1 && isUpperCaseLetter(name.charAt(1)) && isUpperCaseLetter(name.charAt(0))) {
+        return name;
+    }
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
 function inferAccessorTarget(methodName) {
     const getterMatch = GETTER_PREFIX_RE.exec(methodName);
     if (getterMatch) {
-        return getterMatch[1].charAt(0).toLowerCase() + getterMatch[1].slice(1);
+        return decapitalize(getterMatch[1]);
     }
     const setterMatch = SETTER_PREFIX_RE.exec(methodName);
     if (setterMatch) {
-        return setterMatch[1].charAt(0).toLowerCase() + setterMatch[1].slice(1);
+        return decapitalize(setterMatch[1]);
     }
     const invokerMatch = INVOKER_PREFIX_RE.exec(methodName);
     if (invokerMatch) {
-        return invokerMatch[1].charAt(0).toLowerCase() + invokerMatch[1].slice(1);
+        return decapitalize(invokerMatch[1]);
     }
     return methodName;
 }
@@ -125,7 +227,7 @@ function inferAccessorTarget(methodName) {
 /*  Main parser                                                        */
 /* ------------------------------------------------------------------ */
 export function parseMixinSource(source) {
-    const lines = source.split(/\r?\n/);
+    const lines = stripComments(source).split(/\r?\n/);
     const parseWarnings = [];
     const targets = [];
     const injections = [];
@@ -279,6 +381,16 @@ export function parseMixinSource(source) {
                 }
                 i = endIndex;
             }
+            // Try same-line declaration first (e.g. `@Accessor("x") int getX();`)
+            const inlineDecl = stripInlineAnnotations(line);
+            const inlineMethodMatch = inlineDecl.includes("(") ? METHOD_DECL_RE.exec(inlineDecl) : null;
+            if (inlineMethodMatch) {
+                const methodName = inlineMethodMatch[2];
+                const targetName = explicitTarget ?? inferAccessorTarget(methodName);
+                accessors.push({ annotation, name: methodName, targetName, line: lineNum });
+                i++;
+                continue;
+            }
             // Find the method declaration following the annotation (skip multi-line annotations)
             let methodLine = i + 1;
             methodLine = skipAnnotations(lines, methodLine);

package/dist/mod-decompile-service.d.ts

@@ -43,8 +43,10 @@ export type GetModClassSourceOutput = {
 export declare class ModDecompileService {
     private readonly config;
     private readonly decompileCache;
+    private readonly inflightDecompiles;
     constructor(config: Config);
     decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
     getModClassSource(input: GetModClassSourceInput): Promise<GetModClassSourceOutput>;
     private ensureDecompiled;
+    private decompileAndCache;
 }

package/dist/mod-decompile-service.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, join, resolve as resolvePath } from "node:path";
 import { createError, ERROR_CODES } from "./errors.js";
@@ -6,10 +7,12 @@ import { log } from "./logger.js";
 import { decompileBinaryJar } from "./decompiler/vineflower.js";
 import { resolveVineflowerJar } from "./vineflower-resolver.js";
 import { analyzeModJar } from "./mod-analyzer.js";
-import { validateAndNormalizeJarPath } from "./path-resolver.js";
+import { buildJarSignature, validateAndNormalizeJarPath } from "./path-resolver.js";
+import { sliceToMaxCharsSafe } from "./text-truncate.js";
 const DECOMPILE_TIMEOUT_MS = 300_000;
 function modDecompileCacheKey(jarPath) {
-    return createHash("sha256").update(jarPath).digest("hex");
+    const stats = statSync(jarPath);
+    return createHash("sha256").update(`${jarPath}|${buildJarSignature(stats)}`).digest("hex");
 }
 function classNameToFilePath(className) {
     return className.replaceAll(".", "/") + ".java";
@@ -27,6 +30,7 @@ export class ModDecompileService {
     config;
     // Cache: jarPath hash → decompiled output dir + file list
     decompileCache = new Map();
+    inflightDecompiles = new Map();
     constructor(config) {
         this.config = config;
     }
@@ -122,7 +126,7 @@ export class ModDecompileService {
         }
         // Apply maxChars truncation
         if (input.maxChars != null && input.maxChars > 0 && content.length > input.maxChars) {
-            content = content.slice(0, input.maxChars);
+            content = sliceToMaxCharsSafe(content, input.maxChars);
             charsTruncated = true;
             truncated = true;
         }
@@ -154,6 +158,20 @@ export class ModDecompileService {
             this.decompileCache.set(cacheKey, cached);
             return cached;
         }
+        const existingDecompile = this.inflightDecompiles.get(cacheKey);
+        if (existingDecompile) {
+            return existingDecompile;
+        }
+        const decompilePromise = this.decompileAndCache(jarPath, cacheKey, warnings);
+        this.inflightDecompiles.set(cacheKey, decompilePromise);
+        try {
+            return await decompilePromise;
+        }
+        finally {
+            this.inflightDecompiles.delete(cacheKey);
+        }
+    }
+    async decompileAndCache(jarPath, cacheKey, warnings) {
         log("info", "mod-decompile.start", { jarPath });
         const startedAt = Date.now();
         // Analyze mod metadata

package/dist/mod-remap-service.d.ts

@@ -1,9 +1,18 @@
+import { resolveTinyMappingFile } from "./mapping-service.js";
+import { resolveMojangTinyFile } from "./mojang-tiny-mapping-service.js";
+import { remapJar } from "./tiny-remapper-service.js";
+import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
 import type { Config } from "./types.js";
 export interface ModRemapInput {
     inputJar: string;
     outputJar?: string;
     mcVersion?: string;
     targetMapping: "yarn" | "mojang";
+    /**
+     * Skip the remap cache and force re-resolution of the newest yarn build
+     * (bypasses both the output-jar cache hit and the yarn metadata TTL).
+     */
+    forceRemap?: boolean;
 }
 export interface ModRemapResult {
     outputJar: string;
@@ -14,4 +23,14 @@ export interface ModRemapResult {
     durationMs: number;
     warnings: string[];
 }
-export declare function remapModJar(input: ModRemapInput, config: Config): Promise<ModRemapResult>;
+/**
+ * Injectable external dependencies, used by tests to drive the remap pipeline
+ * without spawning Java or downloading mapping jars. Production callers omit it.
+ */
+export interface RemapModJarDeps {
+    remapJar?: typeof remapJar;
+    resolveTinyMappingFile?: typeof resolveTinyMappingFile;
+    resolveMojangTinyFile?: typeof resolveMojangTinyFile;
+    resolveTinyRemapperJar?: typeof resolveTinyRemapperJar;
+}
+export declare function remapModJar(input: ModRemapInput, config: Config, deps?: RemapModJarDeps): Promise<ModRemapResult>;

package/dist/mod-remap-service.js

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
@@ -11,6 +11,13 @@ import { normalizePathForHost } from "./path-converter.js";
 import { detectFabricLikeInputNamespace } from "./source-jar-reader.js";
 import { remapJar } from "./tiny-remapper-service.js";
 import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
+// Bumped whenever the remap pipeline changes in a way that makes previously
+// cached output jars wrong. The v1 pipeline mis-mapped intermediary jars to
+// mojang using an obfuscated<->mojang tiny (no intermediary namespace), so any
+// cached mojang output is invalid and must not be reused. v3 adds the resolved
+// mapping identity (yarn build coordinate) to the cache key so a newer yarn
+// build no longer serves the stale jar; the bump invalidates v2 outputs once.
+const REMAP_PIPELINE_VERSION = "v3";
 function normalizeTargetNamespace(target) {
     return target === "yarn" ? "yarn" : "mojang";
 }
@@ -58,14 +65,18 @@ function copyJarToDestination(sourceJar, destinationJar) {
     mkdirSync(dirname(destinationJar), { recursive: true });
     copyFileSync(sourceJar, destinationJar);
 }
-function buildCacheKey(inputJar, fromNamespace, targetNamespace, mcVersion) {
+function buildCacheKey(inputJar, fromNamespace, targetNamespace, mcVersion, mappingIdentity) {
     const stat = statSync(inputJar, { throwIfNoEntry: false });
     const signature = stat ? `${stat.mtimeMs}:${stat.size}` : "unknown";
     return createHash("sha256")
-        .update(`${inputJar}|${signature}|${fromNamespace}|${targetNamespace}|${mcVersion}`)
+        .update(`${REMAP_PIPELINE_VERSION}|${inputJar}|${signature}|${fromNamespace}|${targetNamespace}|${mcVersion}|${mappingIdentity}`)
         .digest("hex");
 }
-export async function remapModJar(input, config) {
+export async function remapModJar(input, config, deps = {}) {
+    const remapJarFn = deps.remapJar ?? remapJar;
+    const resolveTinyMappingFileFn = deps.resolveTinyMappingFile ?? resolveTinyMappingFile;
+    const resolveMojangTinyFileFn = deps.resolveMojangTinyFile ?? resolveMojangTinyFile;
+    const resolveTinyRemapperJarFn = deps.resolveTinyRemapperJar ?? resolveTinyRemapperJar;
     const startedAt = Date.now();
     const warnings = [];
     // 1. Normalize input JAR path
@@ -111,12 +122,33 @@ export async function remapModJar(input, config) {
         });
     }
     const outputJar = resolveOutputJarPath(input, normalizedInput, analysis.modId, analysis.modVersion);
-    // 4. Check cache after mapping context is known
-    const cacheKey = buildCacheKey(normalizedInput, fromNamespace, resolvedTargetNamespace, mcVersion);
+    // 4. Resolve the mapping identity BEFORE the cache key so the key reflects
+    // which mappings produced the jar. Yarn builds are mutable (Fabric publishes
+    // new builds per MC version), so the resolved yarn coordinate is the identity;
+    // mojang is immutable per release so its version-keyed path string suffices.
+    // The yarn resolution is TTL-fenced (see resolveTinyMappingFile), so on the
+    // common warm path this is zero-network and stays off the cache-hit fast path.
+    let mappingIdentity;
+    let resolvedYarnTiny;
+    if (fromNamespace === resolvedTargetNamespace) {
+        // No remap will run (input already in target namespace); the output is a
+        // copy of the input, so no mapping identity is involved.
+        mappingIdentity = `copy:${resolvedTargetNamespace}`;
+    }
+    else if (resolvedTargetNamespace === "yarn") {
+        resolvedYarnTiny = await resolveTinyMappingFileFn(mcVersion, "yarn", config.cacheDir, undefined, {
+            forceRefresh: input.forceRemap
+        });
+        mappingIdentity = resolvedYarnTiny.coordinate ?? resolvedYarnTiny.path;
+    }
+    else {
+        mappingIdentity = `${mcVersion}-mojang-merged.tiny`;
+    }
+    const cacheKey = buildCacheKey(normalizedInput, fromNamespace, resolvedTargetNamespace, mcVersion, mappingIdentity);
     const cacheDir = join(config.cacheDir, "remapped-mods");
     mkdirSync(cacheDir, { recursive: true });
     const cachedOutput = join(cacheDir, `${cacheKey}.jar`);
-    if (existsSync(cachedOutput)) {
+    if (!input.forceRemap && existsSync(cachedOutput)) {
         const cacheHitOutputJar = input.outputJar
             ? outputJar
             : cachedOutput;
@@ -161,57 +193,81 @@ export async function remapModJar(input, config) {
         });
     }
     // 5. Resolve tiny-remapper
-    const tinyRemapperJar = await resolveTinyRemapperJar(config.cacheDir, config.tinyRemapperJarPath);
-    // 6. Resolve mapping file and remap
-    let mappingsFile;
-    let toNamespace;
+    const tinyRemapperJar = await resolveTinyRemapperJarFn(config.cacheDir, config.tinyRemapperJarPath);
+    const passes = [];
     if (resolvedTargetNamespace === "yarn") {
-        mappingsFile = await resolveTinyMappingFile(mcVersion, "yarn", config.cacheDir);
-        toNamespace = "named";
+        // The Fabric yarn v2 tiny declares both intermediary and named, so a single
+        // intermediary -> named pass is sufficient.
+        // Reuse the coordinate resolved for the cache key (already TTL-fenced).
+        const yarnTiny = resolvedYarnTiny ?? await resolveTinyMappingFileFn(mcVersion, "yarn", config.cacheDir, undefined, {
+            forceRefresh: input.forceRemap
+        });
+        passes.push({ mappingsFile: yarnTiny.path, fromNamespace, toNamespace: "named" });
     }
     else {
-        const mojangTiny = await resolveMojangTinyFile(mcVersion, config);
-        mappingsFile = mojangTiny.path;
-        toNamespace = "mojang";
+        // Mojang target. The merged mojang tiny only bridges obfuscated <-> mojang,
+        // but a Fabric/Quilt jar is intermediary-named, so a direct intermediary ->
+        // mojang remap finds no matching keys and silently no-ops. Remap in two passes:
+        //   pass 1: intermediary -> official (= obfuscated) via the Fabric intermediary v2 tiny
+        //   pass 2: obfuscated    -> mojang                via the merged mojang tiny
+        const mojangTiny = await resolveMojangTinyFileFn(mcVersion, config);
         warnings.push(...mojangTiny.warnings);
+        if (fromNamespace === "intermediary") {
+            const intermediaryTiny = await resolveTinyMappingFileFn(mcVersion, "intermediary", config.cacheDir);
+            passes.push({ mappingsFile: intermediaryTiny.path, fromNamespace: "intermediary", toNamespace: "official" });
+            passes.push({ mappingsFile: mojangTiny.path, fromNamespace: "obfuscated", toNamespace: "mojang" });
+        }
+        else {
+            // Defensive: an already-obfuscated input maps directly. (mojang -> mojang is
+            // handled earlier by the copy short-circuit, so this is not normally reached.)
+            passes.push({ mappingsFile: mojangTiny.path, fromNamespace: "obfuscated", toNamespace: "mojang" });
+        }
     }
     mkdirSync(dirname(outputJar), { recursive: true });
-    // 8. Use temporary directory for intermediate work
-    const tempDir = join(tmpdir(), `mcp-remap-${cacheKey.slice(0, 12)}`);
-    mkdirSync(tempDir, { recursive: true });
+    // 7. Use a temporary directory for intermediate work
+    const tempDir = mkdtempSync(join(tmpdir(), `mcp-remap-${cacheKey.slice(0, 12)}-`));
     try {
-        const tempOutput = join(tempDir, "remapped.jar");
-        try {
-            await remapJar(tinyRemapperJar, {
-                inputJar: normalizedInput,
-                outputJar: tempOutput,
-                mappingsFile,
-                fromNamespace,
-                toNamespace,
-                timeoutMs: config.remapTimeoutMs,
-                maxMemoryMb: config.remapMaxMemoryMb
-            });
-        }
-        catch (caughtError) {
-            if (isAppError(caughtError)) {
-                throw createError({
-                    code: caughtError.code,
-                    message: caughtError.message,
-                    details: {
-                        ...(caughtError.details ?? {}),
-                        fromMapping: fromNamespace,
-                        targetMapping: input.targetMapping,
-                        resolvedTargetNamespace
-                    }
+        let passInput = normalizedInput;
+        let tempOutput = "";
+        for (let passIndex = 0; passIndex < passes.length; passIndex += 1) {
+            const pass = passes[passIndex];
+            tempOutput = join(tempDir, `pass-${passIndex}.jar`);
+            try {
+                await remapJarFn(tinyRemapperJar, {
+                    inputJar: passInput,
+                    outputJar: tempOutput,
+                    mappingsFile: pass.mappingsFile,
+                    fromNamespace: pass.fromNamespace,
+                    toNamespace: pass.toNamespace,
+                    timeoutMs: config.remapTimeoutMs,
+                    maxMemoryMb: config.remapMaxMemoryMb
                 });
             }
-            throw caughtError;
+            catch (caughtError) {
+                if (isAppError(caughtError)) {
+                    throw createError({
+                        code: caughtError.code,
+                        message: caughtError.message,
+                        details: {
+                            ...(caughtError.details ?? {}),
+                            fromMapping: fromNamespace,
+                            targetMapping: input.targetMapping,
+                            resolvedTargetNamespace,
+                            pass: `${pass.fromNamespace}->${pass.toNamespace}`
+                        }
+                    });
+                }
+                throw caughtError;
+            }
+            passInput = tempOutput;
         }
         // Copy to final destination and cache
         copyFileSync(tempOutput, outputJar);
         if (outputJar !== cachedOutput) {
             mkdirSync(dirname(cachedOutput), { recursive: true });
-            copyFileSync(tempOutput, cachedOutput);
+            const tempCachedOutput = `${cachedOutput}.${randomBytes(4).toString("hex")}.tmp`;
+            copyFileSync(tempOutput, tempCachedOutput);
+            renameSync(tempCachedOutput, cachedOutput);
         }
         const durationMs = Date.now() - startedAt;
         log("info", "remap.pipeline.done", {