bambu-printer-mcp 1.1.27 → 1.1.29

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+)$/;
@@ -57,6 +59,11 @@ function stripComments(line: string): string {
 /** A deliberately narrow parameter lexer for commands affecting heat/material selection.
  * Unknown nonthermal vendor commands do not require a global G-code allowlist.
  */
+/** True when the parameter is present, finite and within [low, high]. */
+function inRange(args: Map<string,number>, key: string, low: number, high: number): boolean {
+  const value=args.get(key);
+  return value!==undefined && Number.isFinite(value) && value>=low && value<=high;
+}
 function parameters(text: string, flags = ''): Map<string,number> {
   const result=new Map<string,number>();let rest=text.trim();
   while(rest) {
@@ -135,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');
@@ -232,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');
@@ -273,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');
@@ -292,6 +319,26 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
       if(!command) fail(`unsupported G-code command syntax '${line.slice(0,100)}'`);
       const [base,subcode]=command![2].split('.');
       const code=command![1].toUpperCase()+String(Number(base))+(subcode===undefined?'':'.'+subcode);const argumentsText=line.slice(command![0].length).trim();commandCount++;
+      if(code==='M9711') {
+        // Official X2D and H2D time-lapse capture (Bambu Studio and OrcaSlicer
+        // templates), emitted on every layer: M is the time-lapse mode and E the
+        // physical extruder, not a second command; T is a duration, not a heater.
+        // It sets no temperature. Positions stay inside the machine volume.
+        const invalid=()=>fail('unsupported M9711 time-lapse parameters');
+        if(!['x2d','h2d'].includes(model)) invalid();
+        let args:Map<string,number>;
+        try {args=parameters(argumentsText);} catch {return invalid();}
+        const [width,depth,height]=MACHINE_LIMITS[model].volume;
+        const position=['X','Y','U','V'].filter(key=>args.has(key)).join('');
+        const limit:Record<string,number>={X:width,U:width,Y:depth,V:depth};
+        if([...args.keys()].some(key=>!'MEXYUVZSCOT'.includes(key)) ||
+           // X2D and H2D have two physical extruders, whatever the file declares.
+           ![0,1].includes(args.get('M')!) || !Number.isInteger(args.get('E')) || !inRange(args,'E',0,Math.min(nozzleDiameters.length,2)-1) ||
+           args.get('S')!==11 || args.get('C')!==10 || args.get('O')!==0 || !inRange(args,'T',0,600000) ||
+           !inRange(args,'Z',0,height) ||
+           !['','XY','UV'].includes(position) || [...position].some(key=>!inRange(args,key,0,limit[key]))) invalid();
+        continue;
+      }
       if(!['M117','M118','M1002','M1006','M900','M970','M983.1','G383'].includes(code) && /[GM]\s*\d/i.test(argumentsText)) fail('multiple commands on one line are unsupported');
       // Coordinated extrusion closes the startup-only allowance even when the
       // source omits layer comments. Retraction also closes it conservatively.
@@ -330,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');
@@ -409,7 +462,18 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
         const args=parameters(argumentsText);
         if(!args.has('S') || !args.has('L') || !args.has('T') || !Number.isInteger(args.get('T')) || args.get('T')!<0 || args.get('T')!>=nozzleDiameters.length) fail('unsupported M620.17 nozzle/material temperature mapping');
         for(const key of args.keys()) if(!'SLT'.includes(key)) fail(`unsupported M620.17 parameter ${key}`);
-        heat('nozzle',args.get('S')!,requirePosition(args.get('L')!));
+        if(args.get('L')===-1 && model==='x2d') {
+          // OrcaSlicer's X2D start G-code preheats a nozzle with no assigned
+          // filament (L-1) for toolhead-offset calibration; Bambu Studio writes
+          // L0 there. No project filament is selected, so check the target
+          // against the hardware limit and every declared material, like other
+          // heater commands without a verified filament. That is never looser
+          // than an accepted L<position> form. Material left in the nozzle from
+          // an earlier job is live state that no file can declare. T names one
+          // of the two physical nozzles, whatever the file declares.
+          if(args.get('T')!>1) fail('unsupported M620.17 nozzle/material temperature mapping');
+          heat('nozzle',args.get('S')!,undefined,true);
+        } else heat('nozzle',args.get('S')!,requirePosition(args.get('L')!));
       } else if((/^M620\./.test(code) && !['M620.3','M620.6','M620.11'].includes(code)) || /^M621\./.test(code)) {
         fail(`unsupported thermal-affecting filament command ${code}`);
       } else if(code==='M145') {
@@ -428,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,12 +1,13 @@
+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> = {
   O1C: "H2C", O1C2: "H2C", O1D: "H2D", O1E: "H2D Pro", O1S: "H2S", N6: "X2D",
   N2S: "A1", A1M: "A1 Mini", C11: "P1P", C12: "P1S", C13: "X1E", "BL-P001": "X1C", "BL-P002": "X1",
 };
-const SERIAL_MODELS: Record<string, string> = {
+export const SERIAL_MODELS: Record<string, string> = {
   "093": "H2S", "094": "H2D", "31B": "H2C", "239": "H2D Pro", "20P": "X2D",
   "00M": "X1C", "00W": "X1", "03W": "X1E", "01S": "P1P", "01P": "P1S", "22E": "P2S", "039": "A1", "030": "A1 Mini",
 };
@@ -102,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;
@@ -183,24 +186,95 @@ function reportedNozzles(raw: Record<string,any>): ReportedNozzle[] {
   return output;
 }
 
-function validateErrors(raw: Record<string,any>, requireIdle: boolean) {
+const hiddenHmsSets = new Map(Object.entries(HIDDEN_HMS).map(([prefix, codes]) => [prefix, new Set(codes)]));
+
+type HmsEntry = { attr: number; code: number; severity: number; hex: string };
+function hmsCode(entry: any): HmsEntry | undefined {
+  const code = finiteNumber(entry?.code);
+  const attr = finiteNumber(entry?.attr);
+  const valid = (value: number | undefined): value is number => value !== undefined && Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+  if (!valid(code) || !valid(attr)) return undefined;
+  // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+  return { attr, code, severity: Math.floor(code / 65536), hex: (attr.toString(16).padStart(8, "0") + code.toString(16).padStart(8, "0")).toUpperCase() };
+}
+
+const hmsLabel = (hex: string) => `HMS ${hex.slice(0, 4)}-${hex.slice(4, 8)}-${hex.slice(8, 12)}-${hex.slice(12)}`;
+const hmsKey = (entry: HmsEntry) => `hms:${entry.attr}:${entry.code}`;
+
+/** The one key format for a reported entry, shared by the gate and clear_hms_errors. */
+export function reportedHmsKey(entry: unknown): string {
+  const parsed = hmsCode(entry);
+  return parsed ? hmsKey(parsed) : `hms:${(entry as any)?.attr}:${(entry as any)?.code}`;
+}
+
+/** Bambu's display form of a cleared-code key such as "hms:83887616:131184"; other keys unchanged. */
+export function describeHmsKey(key: string): string {
+  const match = /^hms:(\d+):(\d+)$/.exec(key);
+  const entry = match ? hmsCode({ attr: Number(match[1]), code: Number(match[2]) }) : undefined;
+  return entry ? hmsLabel(entry.hex) : key;
+}
+
+/**
+ * A serious or common entry that Bambu lists for this serial prefix with empty
+ * text: Bambu Studio, Bambu Handy and the printer screen never show it, and
+ * the printer keeps printing with it (an X2D raises 0500-0600-0002-0070 at
+ * every boot). Bambu Studio selects the table by serial prefix, so this does
+ * too, but only when that prefix belongs to the verified model: a sparse report
+ * without a serial must not let a misconfigured serial pick another model's
+ * table. Fatal, invalid-level and unlisted entries never qualify.
+ */
+function isHiddenNotice(serial: string, model: string, entry: HmsEntry): boolean {
+  if (entry.severity !== 2 && entry.severity !== 3) return false;
+  const prefix = serial.trim().toUpperCase().slice(0, 3);
+  const normalized = normalizeModel(model);
+  if (!normalized || normalizeModel(SERIAL_MODELS[prefix] ?? "") !== normalized) return false;
+  return hiddenHmsSets.get(prefix)?.has(entry.hex) === true;
+}
+
+function hiddenHmsEntries(raw: unknown, serial: string, model: string): HmsEntry[] {
+  if (!object(raw)) return [];
+  const identity = observedIdentity(raw, serial);
+  if (!identity.observedSerial || identity.model !== normalizeModel(model)) return [];
+  const entries = Array.isArray(raw.hms) ? raw.hms : [];
+  const seen = new Set<string>();
+  return entries.map(hmsCode).filter((entry): entry is HmsEntry =>
+    !!entry && isHiddenNotice(identity.observedSerial, model, entry) && !seen.has(entry.hex) && !!seen.add(entry.hex));
+}
+
+/** Labels of reported entries that pass only because Bambu hides them for this printer. */
+export function hiddenHmsNotices(raw: unknown, serial: string, model: string): string[] {
+  return hiddenHmsEntries(raw, serial, model).map(entry => hmsLabel(entry.hex));
+}
+
+/** Cleared-code keys of reported hidden entries; clearing never removes them, so they are not re-acknowledged. */
+export function hiddenHmsKeys(raw: unknown, serial: string, model: string): string[] {
+  return hiddenHmsEntries(raw, serial, model).map(hmsKey);
+}
+
+const loggedHiddenNotices = new Set<string>();
+/** Name each hidden entry a check passed once per printer on stderr, so headless runs still record it. */
+function logHiddenNotices(raw: Record<string, any>, serial: string, model: string): void {
+  for (const entry of hiddenHmsEntries(raw, serial, model)) {
+    const key = `${serial}:${entry.hex}`;
+    if (loggedHiddenNotices.has(key)) continue;
+    loggedHiddenNotices.add(key);
+    console.error(`Printer ${serial} reports ${hmsLabel(entry.hex)}, which Bambu lists for it without text and never shows as a fault; it does not block operations.`);
+  }
+}
+
+function validateErrors(raw: Record<string,any>, requireIdle: boolean, serial: string, model: string) {
   const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
   if (requireIdle && !["IDLE","FINISH"].includes(state)) throw new Error(`Printer state ${state} is not safely idle.`);
   if (!requireIdle && !["IDLE","FINISH","RUNNING","PAUSE"].includes(state)) throw new Error(`Printer state ${state} is unknown or failed.`);
   if (finiteNumber(raw.print_error) !== 0) throw new Error("Printer reports a print error or did not report its error state.");
   if (!Array.isArray(raw.hms)) throw new Error("Printer HMS error state is missing or malformed.");
-  for (const entry of raw.hms) {
-    const code = finiteNumber(entry?.code);
-    const attr = finiteNumber(entry?.attr);
-    // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+  for (const reported of raw.hms) {
+    const entry = hmsCode(reported);
     // Unknown severities fail closed; attr identifies the module and is not a severity bitmask.
-    if (code === undefined || attr === undefined || !Number.isInteger(code) || !Number.isInteger(attr) || code < 0 || code > 0xffffffff || attr < 0 || attr > 0xffffffff || Math.floor(code / 65536) !== 4) {
-      const hex = (value: number) => value.toString(16).toUpperCase().padStart(8, "0");
-      const label = code !== undefined && attr !== undefined && Number.isInteger(code) && Number.isInteger(attr) && code >= 0 && attr >= 0
-        ? ` (HMS ${hex(attr).slice(0, 4)}-${hex(attr).slice(4)}-${hex(code).slice(0, 4)}-${hex(code).slice(4)})` : "";
-      throw new Error(`Printer reports actionable or unknown HMS errors${label}; inspect and resolve them before proceeding.`);
-    }
+    if (entry && (entry.severity === 4 || isHiddenNotice(serial, model, entry))) continue;
+    throw new Error(`Printer reports actionable or unknown HMS errors${entry ? ` (${hmsLabel(entry.hex)})` : ""}; inspect and resolve them before proceeding.`);
   }
+  logHiddenNotices(raw, serial, model);
 }
 function trayRange(value: unknown, label: string): number | undefined {
   if (value === undefined || value === null || value === "" || value === "0" || value === 0) return undefined;
@@ -208,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> {
@@ -248,7 +329,7 @@ export function validatePrinterState(status: any, requirements: PrinterStateRequ
   const identity = observedIdentity(raw, String(status.serial ?? ""));
   const model = normalizeModel(requirements.model);
   if (!model || !identity.model || model !== identity.model) throw new Error(`Printer model identity mismatch: requested ${requirements.model}, observed ${identity.model ?? "unknown"}.`);
-  validateErrors(raw, requirements.requireIdle !== false);
+  validateErrors(raw, requirements.requireIdle !== false, identity.observedSerial ?? "", model);
   if (requirements.requireLoadedFilament && (raw.ams?.tray_now !== undefined || Array.isArray(raw.ams?.ams))) {
     const current = finiteNumber(raw.ams?.tray_now);
     if (current === 255) throw new Error("The nozzle is explicitly reported unloaded. Load the declared filament before starting or resuming this G-code job.");
@@ -260,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.");
   }
@@ -288,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");
@@ -312,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 = {

package/src/slicer/profile-flatten.ts

@@ -335,6 +335,37 @@ function enforceMatchingNozzles(arr: unknown[]): void {
   }
 }
 
+/**
+ * BambuStudio picks each per-variant machine, process, and filament value
+ * (e.g. filament_max_volumetric_speed) by "<extruder_type> <nozzle_volume_type>"
+ * among the variants each extruder declares in extruder_variant_list. A flow
+ * type the preset doesn't declare has no values to pick, so refuse it instead
+ * of labelling a job for a nozzle it wasn't sliced for.
+ */
+function assertNozzleVariantDeclared(
+  flat: Record<string, unknown>,
+  volumeType: string,
+  machineLeaf: string
+): void {
+  const strings = (key: string): string[] =>
+    Array.isArray(flat[key]) ? (flat[key] as unknown[]).map(String) : [];
+  const extruderTypes = strings("extruder_type");
+  const declaredLists = strings("extruder_variant_list");
+  const count = (flat["nozzle_volume_type"] as unknown[]).length;
+  for (let i = 0; i < count; i++) {
+    const extruderType = extruderTypes[i] ?? extruderTypes[0];
+    const declared = (declaredLists[i] ?? declaredLists[0] ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+    const matches = (variant: string) =>
+      extruderType ? variant === `${extruderType} ${volumeType}` : variant.endsWith(` ${volumeType}`);
+    // Presets without variant declarations only have Standard values.
+    if (declared.length === 0 ? volumeType === "Standard" : declared.some(matches)) continue;
+    throw new Error(
+      `Slicing for a ${volumeType} nozzle is refused: "${machineLeaf}" declares no ${volumeType} variant ` +
+        `for extruder ${i + 1} (declared: ${declared.join(", ") || "none"}).`
+    );
+  }
+}
+
 /** Best-effort extruder count for fallback nozzle_volume_type sizing. */
 /** BambuStudio's built-in filament_colour default. */
 export const DEFAULT_FILAMENT_COLOUR = "#00AE42";
@@ -687,6 +718,7 @@ export async function flattenForCli(opts: FlattenOptions): Promise<FlattenedProf
 
   // CLI-specific post-processing on machine profile only.
   deriveNozzleVolumeType(machineFlat, opts.nozzleVolumeType);
+  if (opts.nozzleVolumeType) assertNozzleVariantDeclared(machineFlat, opts.nozzleVolumeType, opts.machineLeaf);
   applyMachineModelBedMetadata(machineFlat, machineIndex);
   // A standalone custom machine can accompany process/filament profiles that
   // need BBL resolution; do not impose bundled model config on that machine.

package/src/slicer/remote-slicer.ts

@@ -0,0 +1,216 @@
+/** AFKFelix/orca-slicer-api contract at a9a28f0a7b0c6f51b9be158509e9e9677532b868. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { inspectPrintFile } from '../safety/print-file.js';
+import { normalizeMaterial, normalizeModel } from '../safety/limits.js';
+import type { BambuSliceOptions } from '../stl/stl-manipulator.js';
+
+const MAX_BYTES = 100_000_000;
+const SUPPORTED_OPTIONS = new Set([
+  'arrange', 'orient', 'loadFilaments', 'filamentColours', 'bedType',
+  'nozzleType', 'nozzleVolumeType', 'slicePlate',
+]);
+
+function configuration(): { base: string; headers: Record<string, string>; mode: string; timeout: number } {
+  let url: URL;
+  try { url = new URL(process.env.SLICER_API_URL ?? ''); }
+  catch { throw new Error('Remote slicing requires a valid trusted SLICER_API_URL.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('SLICER_API_URL must use HTTP(S) without embedded credentials, query or fragment.');
+  }
+  const mode = process.env.SLICER_API_MODE || 'sync';
+  if (!['sync', 'async'].includes(mode)) throw new Error('SLICER_API_MODE must be sync or async.');
+  const timeout = Number(process.env.SLICER_API_TIMEOUT_MS ?? 600000);
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) {
+    throw new Error('SLICER_API_TIMEOUT_MS must be an integer from 1 to 3600000.');
+  }
+  const headers: Record<string, string> = {};
+  const token = process.env.SLICER_API_TOKEN;
+  if (token) {
+    const header = process.env.SLICER_API_TOKEN_HEADER || 'Authorization';
+    if (!/^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$/.test(header) ||
+        ['host', 'content-type', 'content-length', 'connection', 'transfer-encoding'].includes(header.toLowerCase()) ||
+        /[^\x20-\x7e]/.test(token)) {
+      throw new Error('Invalid remote slicing authentication configuration.');
+    }
+    headers[header] = header.toLowerCase() === 'authorization' ? `Bearer ${token}` : token;
+  }
+  return { base: url.href.replace(/\/+$/, ''), headers, mode, timeout };
+}
+
+export function validateRemoteSliceOptions(options: BambuSliceOptions = {}): number {
+  for (const [key, value] of Object.entries(options)) {
+    if (value !== undefined && !SUPPORTED_OPTIONS.has(key)) {
+      throw new Error(`Remote slicing option ${key} is unsupported by orca-slicer-api; use a local backend for this workflow.`);
+    }
+  }
+  // Upstream evaluates multipart values by truthiness, so the string "false"
+  // becomes true. Never silently turn an explicit false into an enabled flag.
+  if (options.arrange === false || options.orient === false) {
+    throw new Error('Remote arrange=false and orient=false are unsupported by the upstream multipart API.');
+  }
+  const plate = options.slicePlate ?? 1;
+  if (!Number.isInteger(plate) || plate < 1) throw new Error('Remote slicing requires one positive plate number; slicing all plates is unsupported.');
+  return plate;
+}
+
+/** The remote API forwards this display name to Orca's --curr-bed-type. */
+function remoteBedType(value: unknown): string {
+  const names: Record<string, string> = {
+    textured_plate: 'Textured PEI Plate', textured_pei_plate: 'Textured PEI Plate',
+    cool_plate: 'Cool Plate', engineering_plate: 'Engineering Plate',
+    hot_plate: 'High Temp Plate', high_temp_plate: 'High Temp Plate',
+  };
+  const key = typeof value === 'string' ? value.trim().toLowerCase().replace(/[\s-]+/g, '_') : '';
+  if (typeof names[key] !== 'string') throw new Error('Unsupported remote bed type; use textured_plate, cool_plate, engineering_plate, or hot_plate.');
+  return names[key];
+}
+
+async function readResponse(response: Response, limit: number): Promise<Buffer> {
+  const size = Number(response.headers.get('content-length'));
+  if (size > limit) { await response.body?.cancel(); throw new Error('Remote slicing response exceeds the size limit.'); }
+  if (!response.body) throw new Error('Remote slicing returned an empty response.');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > limit) throw new Error('Remote slicing response exceeds the size limit.');
+      chunks.push(value);
+    }
+  } finally { await reader.cancel(); }
+  return Buffer.concat(chunks);
+}
+
+async function readJob(response: Response): Promise<Record<string, unknown>> {
+  try {
+    const job: unknown = JSON.parse((await readResponse(response, 65536)).toString('utf8'));
+    if (job && typeof job === 'object' && !Array.isArray(job)) return job as Record<string, unknown>;
+  } catch { /* Do not echo an untrusted response, which may contain credentials. */ }
+  throw new Error('Remote slicing returned invalid job metadata.');
+}
+
+/** Upload only locally prepared profiles, then inspect the exact downloaded 3MF. */
+export async function sliceWithOrcaApi(input: {
+  inputPath: string;
+  machinePath: string;
+  processPath: string;
+  filamentPaths: string[];
+  outputPath: string;
+  options?: BambuSliceOptions;
+  isCancelled: () => boolean;
+}): Promise<string> {
+  const options = input.options ?? {};
+  const plate = validateRemoteSliceOptions(options);
+  if (input.filamentPaths.length !== 1 || (options.filamentColours && options.filamentColours.length !== 1)) {
+    throw new Error('orca-slicer-api supports exactly one filament slot; multi-slot projects require a local slicer.');
+  }
+  const config = configuration();
+  const machine = JSON.parse(await fs.readFile(input.machinePath, 'utf8'));
+  const filament = JSON.parse(await fs.readFile(input.filamentPaths[0], 'utf8'));
+  const processProfile = JSON.parse(await fs.readFile(input.processPath, 'utf8'));
+  const bedType = remoteBedType(options.bedType ?? processProfile.curr_bed_type ?? 'textured_plate');
+  const model = normalizeModel(machine.printer_model);
+  const nozzles = Array.isArray(machine.nozzle_diameter) ? machine.nozzle_diameter.map(Number) : [];
+  const materialValues: unknown[] = Array.isArray(filament.filament_type) ? filament.filament_type : [];
+  const materials = materialValues.map(normalizeMaterial);
+  if (!model || !nozzles.length || nozzles.some((n: number) => ![0.2, 0.4, 0.6, 0.8].includes(n)) ||
+      materials.length !== 1 || !materials[0]) {
+    throw new Error('Remote slicing requires explicit model, nozzle and single-material metadata in the prepared profiles.');
+  }
+  const controller = new AbortController();
+  let timedOut = false;
+  const deadline = setTimeout(() => { timedOut = true; controller.abort(); }, config.timeout);
+  const cancelCheck = setInterval(() => { if (input.isCancelled()) controller.abort(); }, 100);
+  let requestId: string | undefined;
+  let terminalJob = false;
+  let wroteOutput = false;
+  const request = async (route: string, init: RequestInit = {}): Promise<Response> => {
+    if (input.isCancelled()) controller.abort();
+    // Do not pass multipart data to fetch after cancellation: undici may start
+    // its body producer before checking the signal and close it mid-enqueue.
+    controller.signal.throwIfAborted();
+    let response: Response;
+    try {
+      response = await fetch(config.base + route, { ...init, headers: config.headers, signal: controller.signal, redirect: 'manual' });
+    } catch { throw new Error('Remote slicing HTTP request failed; check the trusted service configuration.'); }
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`Remote slicing HTTP ${response.status}.`); }
+    return response;
+  };
+  try {
+    const ext = path.extname(input.inputPath).toLowerCase();
+    if (!['.stl', '.3mf'].includes(ext)) throw new Error('Remote slicing supports only STL or 3MF input.');
+    const bytes = await fs.readFile(input.inputPath);
+    if (bytes.length > MAX_BYTES) throw new Error('Remote slicing input exceeds the 100 MB upstream limit.');
+    const form = new FormData();
+    form.set('file', new Blob([new Uint8Array(bytes)], { type: ext === '.3mf' ? 'model/3mf' : 'model/stl' }), `model${ext}`);
+    for (const [field, filePath, type] of [
+      ['printerProfile', input.machinePath, 'machine'],
+      ['presetProfile', input.processPath, 'process'],
+      ['filamentProfile', input.filamentPaths[0], 'filament'],
+    ]) {
+      const profile = JSON.parse(await fs.readFile(filePath, 'utf8'));
+      // The remote validator requires these metadata fields even for standalone
+      // user profiles. They do not change the resolved machine/process settings.
+      const data = { ...profile, type, from: profile.from || 'User' };
+      form.set(field, new Blob([JSON.stringify(data)], { type: 'application/json' }), `${field}.json`);
+    }
+    form.set('exportType', '3mf');
+    form.set('plate', String(plate));
+    form.set('bedType', bedType);
+    form.set('resolveProfileInheritance', 'false');
+    if (options.arrange === true) form.set('arrange', 'true');
+    if (options.orient === true) form.set('orient', 'true');
+    let response = await request(config.mode === 'async' ? '/slice-async' : '/slice', { method: 'POST', body: form });
+    if (config.mode === 'async') {
+      const submitted = await readJob(response);
+      if (typeof submitted.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(submitted.requestId)) {
+        throw new Error('Remote slicing returned an invalid request ID.');
+      }
+      requestId = submitted.requestId;
+      for (;;) {
+        // Construct the documented same-service paths. Returned URLs cannot
+        // redirect authenticated requests to an arbitrary origin or route.
+        const job = await readJob(await request(`/slice-async/${requestId}`));
+        if (job.status === 'completed' || job.status === 'failed') {
+          terminalJob = true;
+          if (job.status === 'failed') throw new Error('Remote slicing job failed; inspect the service logs.');
+          break;
+        }
+        if (job.status !== 'pending' && job.status !== 'processing') throw new Error('Remote slicing returned an unknown job state.');
+        await delay(500, undefined, { signal: controller.signal });
+      }
+      response = await request(`/slice-async/${requestId}/result`);
+    }
+    const result = await readResponse(response, MAX_BYTES);
+    await fs.writeFile(input.outputPath, result, { flag: 'wx', mode: 0o600 });
+    wroteOutput = true;
+    const inspection = await inspectPrintFile(input.outputPath, {
+      model, nozzleDiameters: nozzles, plateIndex: plate - 1, bedType,
+    });
+    if (JSON.stringify(inspection.materials) !== JSON.stringify(materials)) {
+      throw new Error('Remote sliced file materials contradict the prepared filament profile.');
+    }
+    if (input.isCancelled()) throw new Error('Remote slicing cancelled.');
+    return input.outputPath;
+  } catch (error) {
+    if (wroteOutput) await fs.rm(input.outputPath, { force: true });
+    if (controller.signal.aborted) {
+      throw new Error(`Remote slicing ${timedOut ? 'timed out' : 'cancelled'}; the remote job may continue. No retry was sent.`);
+    }
+    throw error;
+  } finally {
+    // DELETE only removes finished jobs; upstream has no active-job cancellation.
+    // Cleanup never retries submission or masks a valid result / original error.
+    if (requestId && terminalJob && !controller.signal.aborted) {
+      try { await (await request(`/slice-async/${requestId}`, { method: 'DELETE' })).body?.cancel(); }
+      catch { console.error('Remote slicing finished-job cleanup failed; service retention applies.'); }
+    }
+    clearTimeout(deadline);
+    clearInterval(cancelCheck);
+  }
+}