bambu-printer-mcp 1.1.28 → 1.1.29

package/src/index.ts

@@ -40,12 +40,13 @@ import {
 } from "./bambu-native.js";
 import { importFileViaBambuConnect } from "./bambu-connect.js";
 import { BlenderMcpBridge } from "./blender-mcp-bridge.js";
-import { hasAmsMappingInput, normalizeAmsMappingObject, normalizeBridgeAmsTrayValue } from "./ams-mapping.js";
+import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, hasAmsMappingInput, normalizeAmsMappingObject, normalizeBridgeAmsTrayValue } from "./ams-mapping.js";
 import { analyze3MFAmsRequirements, analyze3MFPlateObjects, analyzeCollarCharm3MF, extractBambuTemplateSettings, getCollarCharmRolePolicy, parse3MF } from './3mf_parser.js';
 import type { ThreeMFAmsRequirements } from "./types.js";
 import { BambuImplementation, assertDirectPrintSupported } from "./printers/bambu.js";
 import { inspectPrintFile } from "./safety/print-file.js";
 import { validatePrinterState } from "./safety/printer-state.js";
+import { isDualNozzleModel } from "./safety/limits.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName } from "./safety/artifact.js";
 import { detectProfilesRoot } from "./slicer/profile-flatten.js";
 
@@ -703,7 +704,7 @@ function resolveSlicerConfig(args: Record<string, unknown> | undefined): {
   slicerProfile: string;
 } {
   const slicerType = normalizeSlicerType(String(args?.slicer_type || DEFAULT_SLICER_TYPE));
-  const slicerPath = String(args?.slicer_path || process.env.SLICER_PATH || defaultSlicerPathFor(slicerType));
+  const slicerPath = slicerType === "orca-slicer-api" ? "" : String(args?.slicer_path || process.env.SLICER_PATH || defaultSlicerPathFor(slicerType));
   const slicerProfile = String(args?.slicer_profile || DEFAULT_SLICER_PROFILE);
   return { slicerType, slicerPath, slicerProfile };
 }
@@ -994,14 +995,9 @@ function stringifyBridgeJson(value: unknown): string | undefined {
   return JSON.stringify(value);
 }
 
-function nativeAmsMapping2(mapping: number[] | undefined): string | undefined {
+function nativeAmsMapping2(mapping: number[] | undefined, dualNozzle = false): string | undefined {
   if (!mapping || mapping.length === 0) return undefined;
-  return JSON.stringify(mapping.map((value) => {
-    if (value < 0 || value === 255) return { ams_id: 255, slot_id: 255 };
-    if (value === 254) return { ams_id: 254, slot_id: 254 };
-    if (value >= 128) return { ams_id: 128, slot_id: value - 128 };
-    return { ams_id: Math.floor(value / 4), slot_id: value % 4 };
-  }));
+  return JSON.stringify(mapping.map((value) => bridgeAmsMapping2Entry(value, dualNozzle)));
 }
 
 function redactPrintParams(params: Record<string, unknown>): Record<string, unknown> {
@@ -1357,6 +1353,9 @@ class BambuPrinterMCPServer {
   ): ReturnType<typeof resolveSlicerConfig> {
     const config = resolveSlicerConfig(args);
     if (args?.slicer_path !== undefined) {
+      if (config.slicerType === "orca-slicer-api") {
+        throw new Error(`${toolName}: remote slicing uses trusted SLICER_API_URL and BAMBU_PROFILES_ROOT configuration; slicer_path is unsupported.`);
+      }
       const resolvedSlicerPath = this.resolveExecutableSelectorArg(
         args.slicer_path,
         toolName,
@@ -1397,10 +1396,10 @@ class BambuPrinterMCPServer {
 
     console.error(`3MF has no gcode - auto-slicing with ${slicerType} for ${printModel}`);
     const autoSliceOptions: BambuSliceOptions = {
-      uptodate: true,
-      ensureOnBed: true,
-      minSave: true,
-      skipModifiedGcodes: true,
+      ...(slicerType === "orca-slicer-api" ? {} : {
+        uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+      }),
+      ...(slicerType === "orca-slicer-api" ? { slicePlate: Number(args.plate_index ?? 0) + 1 } : {}),
       bedType: bedType ? resolveBambuStudioCliBedType(bedType) : undefined,
       nozzleType: resolveNozzleType(args?.nozzle_type),
       nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
@@ -1426,9 +1425,10 @@ class BambuPrinterMCPServer {
   ): Promise<{ useAMS: boolean; finalAmsMapping?: number[]; finalAmsSlots?: number[] }> {
     const parsed3MFData = await parse3MF(threeMFPath);
     let parsedAmsMapping: number[] | undefined;
+    const trayOptions = { dualNozzle: isDualNozzleModel(printModel) };
 
     if (parsed3MFData.slicerConfig?.ams_mapping) {
-      const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping as Record<string, unknown>);
+      const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping as Record<string, unknown>, "ams_mapping", trayOptions);
       if (slots.length > 0) {
         parsedAmsMapping = slots;
       }
@@ -1444,10 +1444,10 @@ class BambuPrinterMCPServer {
       let userMappingOverride: number[] | undefined;
       if (Array.isArray(args.ams_mapping)) {
         userMappingOverride = args.ams_mapping.map((v: unknown, i: number) =>
-          normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`)
+          normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`, trayOptions)
         );
       } else if (args.ams_mapping && typeof args.ams_mapping === 'object') {
-        userMappingOverride = normalizeAmsMappingObject(args.ams_mapping as Record<string, unknown>);
+        userMappingOverride = normalizeAmsMappingObject(args.ams_mapping as Record<string, unknown>, "ams_mapping", trayOptions);
       }
       if (userMappingOverride && userMappingOverride.length > 0) {
         finalAmsMapping = userMappingOverride;
@@ -1458,7 +1458,7 @@ class BambuPrinterMCPServer {
 
     if (!hasUserAmsMapping && hasUserAmsSlots) {
       const userSlots = args.ams_slots.map((slot: unknown, i: number) =>
-        normalizeBridgeAmsTrayValue(slot, `ams_slots[${i}]`)
+        normalizeBridgeAmsTrayValue(slot, `ams_slots[${i}]`, trayOptions)
       );
       finalAmsSlots = userSlots;
       finalAmsMapping = undefined;
@@ -1487,8 +1487,8 @@ class BambuPrinterMCPServer {
     }
 
     if (args?.use_ams === false) {
-      finalAmsMapping = undefined;
-      finalAmsSlots = undefined;
+      if (!hasUserAmsMapping) finalAmsMapping = undefined;
+      if (!hasUserAmsSlots) finalAmsSlots = undefined;
       useAMS = false;
     }
     if ((!finalAmsMapping || finalAmsMapping.length === 0) && (!finalAmsSlots || finalAmsSlots.length === 0)) {
@@ -1589,8 +1589,16 @@ class BambuPrinterMCPServer {
         inspection.usedFilamentPositions.forEach((position, index) => { mapping![position] = finalAmsSlots[index]; });
       }
       if (!useAMS) {
-        mapping = Array(inspection.materials.length).fill(-1);
-        inspection.usedFilamentPositions.forEach(position => { mapping![position] = 254; });
+        mapping ??= Array(inspection.materials.length).fill(-1);
+        const dualNozzle = isDualNozzleModel(printModel);
+        for (const position of inspection.usedFilamentPositions) {
+          if (mapping[position] === undefined || mapping[position] < 0) {
+            mapping[position] = externalTrayForNozzle(inspection.filamentNozzleIndices?.[position], dualNozzle);
+          }
+          if (mapping[position] !== 254 && !(dualNozzle && mapping[position] === 255)) {
+            throw new Error("use_ams:false requires an external-spool mapping for every used filament.");
+          }
+        }
       }
       const requirements = { ...inspection, amsMapping: mapping, useAMS };
       const initialStatus = await this.bambu.getSafetyStatus(devIp, devId, password || bambuToken);
@@ -1599,7 +1607,7 @@ class BambuPrinterMCPServer {
       const confirmedStatus = await this.bambu.getSafetyStatus(devIp, devId, password || bambuToken);
       validatePrinterState(confirmedStatus, requirements);
       this.bambu.assertBedClearance(confirmedStatus, bedClearance);
-      const amsMapping = stringifyBridgeJson(mapping);
+      const amsMapping = stringifyBridgeJson(mapping?.map(value => bridgeAmsMappingValue(value, isDualNozzleModel(printModel))));
       const remoteFileName = uniquePrintName(threeMFPath);
       const params: Record<string, unknown> = {
         dev_id: devId,
@@ -1616,7 +1624,7 @@ class BambuPrinterMCPServer {
         ftp_file_md5: String(args?.ftp_file_md5 || ""),
         nozzle_mapping: stringifyBridgeJson(args?.nozzle_mapping) || "",
         ams_mapping: amsMapping || "",
-        ams_mapping2: stringifyBridgeJson(args?.ams_mapping2) || "",
+        ams_mapping2: nativeAmsMapping2(mapping, isDualNozzleModel(printModel)) || "",
         ams_mapping_info: stringifyBridgeJson(args?.ams_mapping_info) || "",
         nozzles_info: stringifyBridgeJson(args?.nozzles_info) || "",
         connection_type: connectionType,
@@ -1657,7 +1665,7 @@ class BambuPrinterMCPServer {
           host: devIp, serial: devId, token: password || bambuToken, filePath: snapshot,
           projectName: String(params.task_name), presetName, remoteName: remoteFileName,
           plateIndex, bedType: printBedType, useAMS,
-          amsMapping, amsMapping2: nativeAmsMapping2(mapping),
+          amsMapping, amsMapping2: nativeAmsMapping2(mapping, isDualNozzleModel(printModel)),
           bedLeveling: params.task_bed_leveling as boolean,
           flowCalibration: params.task_flow_cali as boolean,
           vibrationCalibration: params.task_vibration_cali as boolean,
@@ -1916,10 +1924,9 @@ class BambuPrinterMCPServer {
       );
     }
     const autoSliceOptions: BambuSliceOptions = {
-      uptodate: true,
-      ensureOnBed: true,
-      minSave: true,
-      skipModifiedGcodes: true,
+      ...(slicerType === "orca-slicer-api" ? {} : {
+        uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+      }),
       bedType,
     };
 
@@ -2470,7 +2477,7 @@ class BambuPrinterMCPServer {
                 rotate_y: { type: "number", description: "Rotate the model around the Y-axis by this many degrees before slicing. Useful for reorienting prints for better layer adhesion." },
                 min_save: { type: "boolean", description: "Write a smaller output 3MF by omitting non-essential metadata. Reduces file size for faster FTP upload to the printer." },
                 skip_modified_gcodes: { type: "boolean", description: "Strip custom start/end gcodes embedded in the 3MF. Recommended for downloaded 3MFs since custom gcodes from other users' profiles may be unsafe for your printer." },
-                slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates (default). Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." }
+                slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates for local slicers; remote slicing defaults to plate 1 and rejects 0. Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." }
               },
               required: ["stl_path", "bambu_model"]
             }
@@ -2573,8 +2580,8 @@ class BambuPrinterMCPServer {
                 nozzle_diameter: { type: "string", description: "Nozzle diameter in mm for auto-slicing (default: 0.4)." },
                 nozzle_diameters: { type: "array", minItems: 1, maxItems: 2, items: { type: "number", enum: [0.2, 0.4, 0.6, 0.8] }, description: "Complete per-nozzle diameters for pre-sliced jobs, e.g. [0.4, 0.6]. Omit to verify file metadata against every reported nozzle; cannot combine with nozzle_diameter." },
                 use_ams: { type: "boolean", description: "Whether to use the AMS; defaults to auto-detect from the 3MF mapping." },
-                ams_mapping: { type: "array", description: "AMS slot mapping array used by both local MCP printing and FULU PrintParams.", items: { type: "number" } },
-                ams_slots: { type: "array", description: "Per-used-filament AMS slot list, matching the local LAN print path.", items: { type: "number" } },
+                ams_mapping: { type: "array", description: "AMS slot mapping array used by both local MCP printing and FULU PrintParams. Same tray values as print_3mf: 254 = external spool; on dual-nozzle printers 254 = left/deputy nozzle external and 255 = right/main nozzle external.", items: { type: "number" } },
+                ams_slots: { type: "array", description: "Per-used-filament AMS slot list, matching the local LAN print path (254/255 external spool rules as in print_3mf).", items: { type: "number" } },
                 ams_mapping_bridge: { type: "string", description: "Raw JSON string override for FULU PrintParams ams_mapping when the automatic array is not enough." },
                 ams_mapping2: { type: "string", description: "Raw JSON string for FULU PrintParams ams_mapping2, matching OrcaSlicer-bambulab's v1 AMS mapping field." },
                 ams_mapping_info: { type: "string", description: "Raw JSON string for FULU PrintParams ams_mapping_info, matching OrcaSlicer-bambulab's detailed AMS mapping field." },
@@ -3002,12 +3009,12 @@ class BambuPrinterMCPServer {
                 use_ams: { type: "boolean", description: "Whether to use the AMS (default: auto-detect from 3MF)" },
                 ams_mapping: {
                   type: "array",
-                  description: "Project-level AMS mapping array. Position = project filament index, value = absolute AMS tray (0-3=AMS 0, 4-7=AMS 1, 8-11=AMS 2, 128+=AMS-HT, 254=external, -1=unused). Prefer ams_slots unless you know the project-level layout.",
+                  description: "Project-level AMS mapping array. Position = project filament index, value = absolute AMS tray (0-3=AMS 0, 4-7=AMS 1, 8-11=AMS 2, 128+=AMS-HT, 254=external, -1=unused). On dual-nozzle printers (H2D, H2D Pro, H2C, X2D) 254 is the LEFT/deputy nozzle external spool and 255 the RIGHT/main nozzle external spool, matching Bambu Studio's virtual tray ids; the gcode header's filament_map (1=left, 2=right) says which nozzle each filament was sliced for. Prefer ams_slots unless you know the project-level layout.",
                   items: { type: "number" }
                 },
                 ams_slots: {
                   type: "array",
-                  description: "Preferred AMS input: one absolute tray index per USED filament in plate order, e.g. [1] for a single-filament print pulling from AMS 0 slot 1. Expanded to project-level ams_mapping automatically from the 3MF's plate_N.json and gcode header.",
+                  description: "Preferred AMS input: one absolute tray index per USED filament in plate order, e.g. [1] for a single-filament print pulling from AMS 0 slot 1. Use 254 for the external spool (on dual-nozzle printers: 254 = left/deputy nozzle external, 255 = right/main nozzle external). Expanded to project-level ams_mapping automatically from the 3MF's plate_N.json and gcode header.",
                   items: { type: "number" }
                 },
                 auto_match_ams: {
@@ -4098,10 +4105,9 @@ class BambuPrinterMCPServer {
               }
               console.error(`3MF has no gcode — auto-slicing with ${slicerType} for ${printModel}`);
               const autoSliceOptions: BambuSliceOptions = {
-                uptodate: true,
-                ensureOnBed: true,
-                minSave: true,
-                skipModifiedGcodes: true,
+                ...(slicerType === "orca-slicer-api" ? { slicePlate: plateIndex + 1 } : {
+                  uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+                }),
                 bedType: printBedType,
                 nozzleType: resolveNozzleType(args?.nozzle_type),
                 nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
@@ -4133,9 +4139,10 @@ class BambuPrinterMCPServer {
 
             const parsed3MFData = await parse3MF(threeMFPath);
             const isH2Print = H2_BAMBU_MODELS.has(printModel);
+            const trayOptions = { dualNozzle: isDualNozzleModel(printModel) };
             let parsedAmsMapping: number[] | undefined;
             if (!isH2Print && parsed3MFData.slicerConfig?.ams_mapping) {
-              const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping as Record<string, unknown>);
+              const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping as Record<string, unknown>, "ams_mapping", trayOptions);
               if (slots.length > 0) {
                 parsedAmsMapping = slots;
               }
@@ -4151,10 +4158,10 @@ class BambuPrinterMCPServer {
               let userMappingOverride: number[] | undefined;
               if (Array.isArray(args.ams_mapping)) {
                 userMappingOverride = args.ams_mapping.map((v: unknown, i: number) =>
-                  normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`)
+                  normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`, trayOptions)
                 );
               } else if (args.ams_mapping && typeof args.ams_mapping === 'object') {
-                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping as Record<string, unknown>);
+                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping as Record<string, unknown>, "ams_mapping", trayOptions);
               }
               if (userMappingOverride && userMappingOverride.length > 0) {
                 finalAmsMapping = userMappingOverride;
@@ -4208,8 +4215,8 @@ class BambuPrinterMCPServer {
             }
 
             if (args?.use_ams === false) {
-              finalAmsMapping = undefined;
-              finalAmsSlots = undefined;
+              if (!hasUserAmsMapping) finalAmsMapping = undefined;
+              if (!hasUserAmsSlots) finalAmsSlots = undefined;
               useAMS = false;
             }
             if ((!finalAmsMapping || finalAmsMapping.length === 0) && (!finalAmsSlots || finalAmsSlots.length === 0)) {

package/src/printers/bambu.ts

@@ -7,7 +7,8 @@ import os from "node:os";
 import { Readable } from "node:stream";
 import { readSafe3mfArchive } from "../safety/archive.js";
 import { inspectPrintFile, type PrintFileInspection } from "../safety/print-file.js";
-import { normalizeModel, validateTemperature } from "../safety/limits.js";
+import { isDualNozzleModel, normalizeModel, validateTemperature } from "../safety/limits.js";
+import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, describeAmsTrayRange } from "../ams-mapping.js";
 import { describeHmsKey, hiddenHmsKeys, hiddenHmsNotices, reportedHmsKey, validatePrinterState, manualHeatingRequirements, type PrinterStateRequirements } from "../safety/printer-state.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName, normalizedRemotePath, cancelPendingPrinterOperations } from "../safety/artifact.js";
 import { Client as FTPClient } from "basic-ftp";
@@ -747,15 +748,20 @@ export class BambuImplementation {
     // `plate_N.json.filament_ids` -- and expand to a full project-level
     // array here. `amsMapping` is the raw escape hatch (takes precedence
     // when both are supplied).
+    // Dual-nozzle printers address two external spools: 254 feeds the left/deputy
+    // nozzle and 255 the right/main nozzle (Bambu Studio VIRTUAL_TRAY_DEPUTY_ID /
+    // VIRTUAL_TRAY_MAIN_ID). Single-nozzle printers keep 254 as the only external tray.
+    const dualNozzle = isDualNozzleModel(model);
+    const externalTrays = dualNozzle ? [254, 255] : [254];
     const validateTrayValue = (v: unknown, label: string): void => {
       if (
         !Number.isInteger(v) ||
         (v as number) < -1 ||
         ((v as number) > 15 && (v as number) < 128) ||
-        (v as number) > 254
+        (v as number) > (dualNozzle ? 255 : 254)
       ) {
         throw new Error(
-          `${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${v}`
+          `${label} values must be integers in ${describeAmsTrayRange({ dualNozzle })}; got ${v}`
         );
       }
     };
@@ -794,7 +800,7 @@ export class BambuImplementation {
       );
       baseMapping = Array<number>(projectLen).fill(-1);
       positions.forEach((pos, i) => {
-        baseMapping[pos] = options.useAMS === false ? 254 : i;
+        baseMapping[pos] = options.useAMS === false ? externalTrayForNozzle(inspection.filamentNozzleIndices?.[pos], dualNozzle) : i;
       });
     }
 
@@ -805,12 +811,7 @@ export class BambuImplementation {
       amsMapping = Array.from({ length: projLen }, (_, i) =>
         i < baseMapping.length ? baseMapping[i] : -1
       );
-      amsMapping2 = amsMapping.map((v) => {
-        if (v < 0 || v === 255) return { ams_id: 255, slot_id: 255 };
-        if (v === 254) return { ams_id: 254, slot_id: 254 };
-        if (v >= 128) return { ams_id: 128, slot_id: v - 128 };
-        return { ams_id: Math.floor(v / 4), slot_id: v % 4 };
-      });
+      amsMapping2 = amsMapping.map((v) => bridgeAmsMapping2Entry(v, dualNozzle));
     } else {
       amsMapping = Array.from({ length: Math.max(5, baseMapping.length, projectMetadata.projectFilamentCount) }, (_, i) =>
         i < baseMapping.length ? baseMapping[i] : -1
@@ -822,8 +823,8 @@ export class BambuImplementation {
       if (baseMapping[position] === undefined || baseMapping[position] < 0) {
         throw new Error(`Missing physical filament mapping for project filament ${position}.`);
       }
-      if (options.useAMS === false && baseMapping[position] !== 254) {
-        throw new Error("External-spool printing requires external spool mapping (254).");
+      if (options.useAMS === false && !externalTrays.includes(baseMapping[position])) {
+        throw new Error(`External-spool printing requires external spool mapping (${externalTrays.join(" or ")}).`);
       }
     }
     const legacyContainer = options.filePath.toLowerCase().endsWith(".gcode.3mf") && !usesH2ProjectFile && !isA1;
@@ -898,7 +899,7 @@ export class BambuImplementation {
           project_id: submissionId,
           subtask_id: submissionId,
           task_id: submissionId,
-          ams_mapping: amsMapping,
+          ams_mapping: amsMapping.map(value => bridgeAmsMappingValue(value, dualNozzle)),
           ams_mapping2: amsMapping2,
         },
       };

package/src/safety/limits.ts

@@ -31,6 +31,15 @@ export const MACHINE_LIMITS: Readonly<Record<string, {nozzle: number; bed: numbe
   x2d: {nozzle:300,bed:120,chamber:65,volume:[256,256,260]},
 };
 
+/** Printers with two physical nozzles. Bambu Studio numbers the right/main nozzle 0
+ * (MAIN_EXTRUDER_ID) and the left/deputy nozzle 1 (DEPUTY_EXTRUDER_ID), and reports one
+ * virtual external-spool slot per nozzle: 255 (VIRTUAL_TRAY_MAIN_ID) and 254
+ * (VIRTUAL_TRAY_DEPUTY_ID). The single-nozzle H2S is deliberately absent. */
+export const DUAL_NOZZLE_MODELS: ReadonlySet<string> = new Set(['h2d','h2dpro','h2c','x2d']);
+export function isDualNozzleModel(model: unknown): boolean {
+  const normalized = normalizeModel(model);
+  return normalized !== undefined && DUAL_NOZZLE_MODELS.has(normalized);
+}
 export function normalizeModel(value: unknown): string | undefined {
   if (typeof value !== 'string') return undefined;
   let model = value.trim().toLowerCase().replace(/^bambu\s*(?:lab\s*)?/, '').replace(/[\s_-]/g, '');

package/src/safety/print-file.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 
 export interface PrintFileInspection {
   model: string;
@@ -16,6 +16,8 @@ export interface PrintFileInspection {
   selectsAms: boolean;
   nozzleTypes?: string[];
   nozzleFlows?: string[];
+  /** Physical nozzle index for each declared filament, composed from the selected plate headers. */
+  filamentNozzleIndices?: number[];
 }
 type Metadata = Record<string, unknown>;
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
@@ -140,6 +142,7 @@ function validateBounds(headers: Metadata[], model: string, plate: Metadata): vo
 export async function inspectPrintFile(filePath: string, options: {model:string; nozzleDiameters?:number[]; plateIndex?:number; bedType?:string}): Promise<PrintFileInspection> {
   const model=normalizeModel(options.model);
   if(!model) return fail(`unknown or missing printer model '${options.model}'`);
+  const dualNozzle=isDualNozzleModel(model);
   const plateIndex=options.plateIndex ?? 0;
   if(!Number.isInteger(plateIndex)||plateIndex<0) return fail('selected plate index must be a nonnegative integer');
   if(/\.md5$/i.test(filePath)) return fail('a checksum file is not a printable artifact');
@@ -237,6 +240,22 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
   const materials=consistent(metadataValues(metadata,['filament_type']),value=>{
     const values=list(value);return values.length && values.every(v=>!!normalizeMaterial(v))?values.map(v=>normalizeMaterial(v)!):undefined;
   },'filament material');
+  // GCode.cpp uses 1-based filament_map logical extruders and then indexes
+  // physical_extruder_map to select the physical nozzle. Only this selected
+  // plate's headers establish that binding; unsliced project defaults do not.
+  const headerMap=(key:string,count:number,low:number,high:number):number[]|undefined=>{
+    const values=metadataValues(headers,[key]);
+    if(!values.length) return undefined;
+    return consistent(values,value=>{
+      const entries=list(value);
+      return entries.length===count && entries.every(v=>NUMBER.test(v) && Number.isInteger(Number(v)) && Number(v)>=low && Number(v)<=high)
+        ? entries.map(Number):undefined;
+    },key.replace(/_/g,' '));
+  };
+  const physicalExtruderMap=headerMap('physical_extruder_map',nozzleDiameters.length,0,dualNozzle?Math.min(nozzleDiameters.length,2)-1:nozzleDiameters.length-1);
+  if(physicalExtruderMap && new Set(physicalExtruderMap).size!==physicalExtruderMap.length) fail('physical extruder map must be a complete permutation');
+  const filamentMap=headerMap('filament_map',materials.length,1,nozzleDiameters.length);
+  const filamentNozzleIndices=filamentMap && physicalExtruderMap ? filamentMap.map(logical=>physicalExtruderMap[logical-1]):undefined;
   const bedValues=metadataValues([...metadata,plate],['curr_bed_type','bed_type']);
   const bedType=bedValues.length?consistent(bedValues,normalizeBed,'bed type'):undefined;
   if(options.bedType && (!bedType || normalizeBed(options.bedType)!==bedType)) return fail('selected bed type cannot be verified or contradicts the sliced file; re-slice with the intended bed');
@@ -278,7 +297,10 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
     try {
       if(isLayerMarker(lines[index]) || /^\s*;\s*MACHINE_START_GCODE_END\s*$/i.test(lines[index])) closeStartupWindow();
       let line=stripComments(lines[index]);if(!line||line==='%') continue;
-      // The official H2C template emits this literal separator without a semicolon.
+      // Accept only the exact vendor banners in their documented model/scope.
+      // X2D emits its filament-change banner throughout a print; H2C's record
+      // separator stays inside its explicitly bounded startup block.
+      if(line==='======== X2D filament_change gcode ==========' && model==='x2d') continue;
       if(line==='========== record data ==========' && h2cStartup(index)) continue;
       line=line.replace(/^N\d+\s*/i,'').replace(/\*\d+\s*$/,'');
       if(/[{}\[\]#]/.test(line)) fail('unresolved dynamic command syntax');
@@ -355,17 +377,23 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
           heat('bed',args.get('D')!,undefined,true);continue;
         }
         const vendorWait=code==='M109' && ['a1','a1mini'].includes(model);
-        for(const key of args.keys()) if(!'SRTA'.includes(key) && !(key==='H' && vendorWait)) fail(`unsupported ${code} temperature parameter ${key}`);
+        // Bambu Studio addresses a physical nozzle on dual-nozzle machines with N<index>
+        // (X2D `M104 T1 S25 N0` multi-extruder pre-cooling and wipe-tower reheats).
+        // N selects a nozzle, never a target, so it is accepted only on those models,
+        // only for nozzle heaters, and only within the declared nozzle count.
+        const nozzleIndex=['M104','M109'].includes(code) && dualNozzle;
+        for(const key of args.keys()) if(!'SRTA'.includes(key) && !(key==='H' && vendorWait) && !(key==='N' && nozzleIndex)) fail(`unsupported ${code} temperature parameter ${key}`);
+        if(args.has('N') && (!Number.isInteger(args.get('N')) || args.get('N')!<0 || args.get('N')!>=Math.min(nozzleDiameters.length,2))) fail(`unsupported ${code} nozzle index N`);
         if(args.has('H') && (!Number.isFinite(args.get('H')) || args.get('H')!<0 || args.get('H')!>300)) fail(`unsupported ${code} wait parameter H`);
         if(!args.has('S')&&!args.has('R')) fail(`missing ${code} temperature target`);
         const component= ['M104','M109'].includes(code)?'nozzle': ['M140','M190'].includes(code)?'bed':'chamber';
         // Heater T is a physical nozzle, unlike standalone remapped T filament selection.
         // Without a verified per-filament nozzle map, apply all possible materials.
         if(args.has('T') && (!Number.isInteger(args.get('T')) || args.get('T')!<0 || args.get('T')!>=nozzleDiameters.length)) fail('physical heater target has no declared nozzle');
-        const position= args.has('T') ? undefined : active;
+        const position= args.has('T') || args.has('N') ? undefined : active;
         const commonFlush=code==='M109' && args.size===1 && args.get('S')===290 && model==='x1e' && !depositionStarted && !commonFlushUsed && boundedX1ePurge(lines,index);
         if(commonFlush) commonFlushUsed=true;
-        for(const key of ['S','R']) if(args.has(key)) heat(component,args.get(key)!,position,args.has('T') || args.has('A'),commonFlush);
+        for(const key of ['S','R']) if(args.has(key)) heat(component,args.get(key)!,position,args.has('T') || args.has('N') || args.has('A'),commonFlush);
       } else if(code==='M620' || code==='M621') {
         const args=parameters(argumentsText,model==='x2d'?'MAB':model==='h2c'?'MAN':'MA');
         if(args.has('N') && (code!=='M620' || !h2cStartup(index) || args.size!==1 || !Number.isNaN(args.get('N')!))) fail('unsupported H2C startup hotend-remap flag');
@@ -464,5 +492,5 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
   }
   if(!commandCount) return fail('selected G-code contains no printable commands');
   if(!used.size) materials.forEach((_,index)=>used.add(index));
-  return {model,nozzleDiameters,materials,usedFilamentPositions:[...used].sort((a,b)=>a-b),plateInternalPath,sha256,maxNozzleTemperature,maxBedTemperature,maxChamberTemperature,bedType,selectsAms,nozzleTypes,nozzleFlows};
+  return {model,nozzleDiameters,materials,usedFilamentPositions:[...used].sort((a,b)=>a-b),plateInternalPath,sha256,maxNozzleTemperature,maxBedTemperature,maxChamberTemperature,bedType,selectsAms,nozzleTypes,nozzleFlows,filamentNozzleIndices};
 }

package/src/safety/printer-state.ts

@@ -1,6 +1,6 @@
 import { HIDDEN_HMS } from "./hidden-hms.js";
 import { BambuClient, GetVersionCommand, PushAllCommand } from "bambu-node";
-import { normalizeMaterial, normalizeModel } from "./limits.js";
+import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
 
 const MAX_REPORT_AGE_MS = 15_000;
 const MODEL_IDS: Record<string, string> = {
@@ -103,6 +103,8 @@ export interface PrinterStateRequirements {
   nozzleDiameters: number[];
   materials?: string[];
   usedFilamentPositions?: number[];
+  /** Verified physical nozzle index for each project filament, composed from the inspected plate mappings. */
+  filamentNozzleIndices?: number[];
   amsMapping?: number[];
   useAMS?: boolean;
   requireIdle?: boolean;
@@ -280,13 +282,20 @@ function trayRange(value: unknown, label: string): number | undefined {
   if (number === undefined || number <= 0) throw new Error(`Reported filament ${label} temperature is malformed.`);
   return number;
 }
-function externalTray(raw: Record<string,any>): Record<string,any> | undefined {
+/** Dual-nozzle printers report one virtual external slot per nozzle, numbered as Bambu
+ * Studio does (VIRTUAL_TRAY_MAIN_ID 255 = right/main nozzle, VIRTUAL_TRAY_DEPUTY_ID 254 =
+ * left/deputy nozzle), so the requested tray selects its slot. Single-nozzle printers keep
+ * requiring exactly one slot 254 report, then the legacy vt_tray field. */
+function externalTray(raw: Record<string,any>, trayIndex: number, model: string): Record<string,any> | undefined {
   const slots = raw.vir_slot;
+  const dualNozzle = isDualNozzleModel(model);
   if (Array.isArray(slots)) {
-    const selected = slots.filter((slot:any) => Number(slot?.id) === 254);
-    if (slots.length === 1 && selected.length === 1) return selected[0];
+    const selected = slots.filter((slot:any) => Number(slot?.id) === trayIndex);
+    if (selected.length === 1 && (dualNozzle || slots.length === 1)) return selected[0];
+    if (dualNozzle && selected.length === 0 && slots.length > 0) throw new Error(`External spool ${trayIndex} is not in the fresh per-nozzle report; cannot verify the selected material.`);
     if (slots.length > 0) throw new Error("External spool report is ambiguous for this nozzle; cannot verify the selected material.");
   }
+  if (dualNozzle) throw new Error(`Dual-nozzle external spool ${trayIndex} requires a fresh per-nozzle vir_slot report; legacy vt_tray cannot verify the selected nozzle.`);
   return object(raw.vt_tray) ? raw.vt_tray : undefined;
 }
 function mappedTray(raw: Record<string,any>, index: number): Record<string,any> {
@@ -332,7 +341,7 @@ export function validatePrinterState(status: any, requirements: PrinterStateRequ
     }
   }
   const nozzles = requirements.nozzleDiameters.length ? reportedNozzles(raw) : [];
-  if (requirements.nozzleDiameters.length && ["h2d","h2dpro","h2c","x2d"].includes(model) &&
+  if (requirements.nozzleDiameters.length && isDualNozzleModel(model) &&
       !Array.isArray(raw.device?.nozzle?.info) && !Array.isArray(raw.nozzle_diameter)) {
     throw new Error("A scalar legacy nozzle report is ambiguous for this multi-nozzle printer; fresh per-nozzle configuration is required.");
   }
@@ -360,13 +369,27 @@ export function validatePrinterState(status: any, requirements: PrinterStateRequ
   if (requirements.verifyMaterials !== false && (requirements.materials !== undefined || requirements.nozzleDiameters.length)) {
     const materials = requirements.materials ?? [];
     const positions = requirements.usedFilamentPositions ?? materials.map((_, index) => index);
+    // 255 is the right/main nozzle external spool only on dual-nozzle printers.
+    const dualNozzle = isDualNozzleModel(model);
+    const maxTray = dualNozzle ? 255 : 254;
     if (!positions.length) throw new Error("A declared material is required for each used filament or external spool.");
     for (const position of positions) {
       const material = normalizeMaterial(materials[position]);
       if (!Number.isInteger(position) || position < 0 || !material) throw new Error(`A known declared material is required for filament position ${position}.`);
-      const trayIndex = requirements.useAMS ? requirements.amsMapping?.[position] : 254;
-      if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > 254) throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
-      const tray = trayIndex === 254 ? externalTray(raw) : mappedTray(raw,trayIndex);
+      const physicalNozzle = requirements.filamentNozzleIndices?.[position];
+      const externalForNozzle = physicalNozzle === 0 ? 255 : physicalNozzle === 1 ? 254 : undefined;
+      const trayIndex = requirements.useAMS || requirements.amsMapping !== undefined
+        ? requirements.amsMapping?.[position] : dualNozzle ? externalForNozzle : 254;
+      if (!requirements.useAMS && dualNozzle && requirements.amsMapping === undefined && externalForNozzle === undefined) {
+        throw new Error(`External spool for filament position ${position} is ambiguous; re-slice with complete filament_map and physical_extruder_map nozzle bindings or provide a verified sliced plate.`);
+      }
+      if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > maxTray) throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
+      if (!requirements.useAMS && trayIndex < 254) throw new Error("External-spool printing requires an external spool mapping; AMS trays require use_ams:true.");
+      if (dualNozzle && trayIndex >= 254) {
+        if (externalForNozzle === undefined) throw new Error(`External spool ${trayIndex} needs a verified physical nozzle binding for filament position ${position}; re-slice with complete filament_map and physical_extruder_map metadata.`);
+        if (trayIndex !== externalForNozzle) throw new Error(`External spool ${trayIndex} does not feed physical nozzle ${physicalNozzle} for filament position ${position}; use spool ${externalForNozzle}.`);
+      }
+      const tray = trayIndex >= 254 ? externalTray(raw,trayIndex,model) : mappedTray(raw,trayIndex);
       const reportedType = typeof tray?.tray_type === "string" ? tray.tray_type.trim() : "";
       if (reportedType && normalizeMaterial(reportedType) !== material) throw new Error(`Reported material ${reportedType} in slot ${trayIndex} contradicts declared ${materials[position]}.`);
       const nozzleMin = trayRange(tray?.nozzle_temp_min,"minimum");
@@ -384,7 +407,7 @@ export function manualHeatingRequirements(status: any, model: string, nozzleDiam
   if (!normalized) throw new Error("A known printer model is required for manual nozzle heating.");
   const raw = status?.raw;
   if (!object(raw)) throw new Error("A fresh printer report is required for manual nozzle heating.");
-  if (["h2d","h2dpro","h2c","x2d"].includes(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
+  if (isDualNozzleModel(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
     throw new Error("Manual heating cannot verify the active nozzle and loaded material on this multi-nozzle printer. Use a checked sliced print instead.");
   }
   const requirements: PrinterStateRequirements = {