mcp-3d-printer-server 1.2.25 → 1.2.26

package/src/safety/print-file.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { projectFilaments, type ProjectFilament } from "../ams-mapping.js";
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 
 export interface PrintFileInspection {
   model: string;
@@ -16,6 +17,10 @@ export interface PrintFileInspection {
   selectsAms: boolean;
   nozzleTypes?: string[];
   nozzleFlows?: string[];
+  /** Physical nozzle index for each declared filament, composed from the selected plate headers. */
+  filamentNozzleIndices?: number[];
+  /** Every project filament as project_settings.config declares it, for PrintParams.ams_mapping_info. */
+  projectFilaments?: ProjectFilament[];
 }
 type Metadata = Record<string, unknown>;
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
@@ -43,6 +48,60 @@ function consistent<T>(values: unknown[], convert: (v: unknown)=>T|undefined, fi
   if (converted.some(value=>JSON.stringify(value)!==JSON.stringify(converted[0]))) return fail(`contradictory ${field} metadata`);
   return converted[0]!;
 }
+/** Bambu Studio keeps filament options per variant in the project, but writes
+ * one selected row per filament in the plate header (Print::full_print_config).
+ * Match the declared 1-based self index and variant, never truncate the table
+ * or borrow the slicer's row-zero fallback for a missing selection.
+ */
+function firstLayerTemperatures(project:Metadata, headers:Metadata[], count:number):number[] {
+  const key='nozzle_temperature_initial_layer';
+  const field='first-layer nozzle temperature';
+  const temperatures=(value:unknown):number[]|undefined=>{
+    const entries=list(value);
+    return entries.length && entries.every(v=>NUMBER.test(v) && Number.isFinite(Number(v)))?entries.map(Number):undefined;
+  };
+  const perFilament=(value:unknown)=>{
+    const values=temperatures(value);return values?.length===count?values:undefined;
+  };
+  const selectedValues=metadataValues(headers,[key]);
+  if(project[key]===undefined) return consistent(selectedValues,perFilament,field);
+  if(project.filament_extruder_variant===undefined && project.filament_self_index===undefined)
+    return consistent([project[key],...selectedValues],perFilament,field);
+
+  const table=temperatures(project[key]);
+  const variants=list(project.filament_extruder_variant);
+  const ids=list(project.filament_self_index);
+  const validVariant=(value:string)=>/^(Direct Drive|Bowden) (Standard|High Flow|Hybrid|TPU High Flow|E3D High Flow)$/.test(value);
+  if(!table || variants.length!==table.length || ids.length!==table.length ||
+     variants.some(v=>!validVariant(v)) || ids.some(id=>!/^[1-9]\d*$/.test(id) || Number(id)>count))
+    return fail(`unknown or malformed ${field} variant table`);
+  const selectedVariants=consistent(metadataValues(headers,['filament_extruder_variant']),value=>{
+    const values=list(value);return values.length===count && values.every(validVariant)?values:undefined;
+  },'selected filament extruder variant');
+  const selectedIds=consistent(metadataValues(headers,['filament_self_index']),value=>{
+    const values=list(value);return values.length===count && values.every((id,index)=>id===String(index+1))?values:undefined;
+  },'selected filament self index');
+  // These are logical extruders: physical_extruder_map is used for spool
+  // routing, not this variant lookup. Hybrid selects the Standard variant.
+  const mappingKeys=['filament_map','extruder_type','filament_volume_map'];
+  if(mappingKeys.every(key=>metadataValues(headers,[key]).length)) {
+    const selection=(key:string)=>consistent(metadataValues(headers,[key]),value=>{
+      const entries=list(value);return entries.length?entries:undefined;
+    },`selected ${key.replace(/_/g,' ')}`);
+    const map=selection('filament_map');const types=selection('extruder_type');const volumes=selection('filament_volume_map');
+    const flows:Record<string,string>={'0':'Standard','1':'High Flow','2':'Standard','3':'TPU High Flow','5':'E3D High Flow'};
+    if(map.length!==count || volumes.length!==count || map.some(id=>!/^[1-9]\d*$/.test(id) || Number(id)>types.length) ||
+       volumes.some(v=>!Object.prototype.hasOwnProperty.call(flows,v)) || types.some(v=>!['Direct Drive','Bowden'].includes(v)) ||
+       selectedVariants.some((variant,i)=>variant!==`${types[Number(map[i])-1]} ${flows[volumes[i]]}`))
+      return fail('contradictory selected filament extruder variant mapping');
+  }
+  const resolved=selectedIds.map((id,index)=>{
+    const rows=ids.flatMap((candidate,row)=>candidate===id && variants[row]===selectedVariants[index]?[row]:[]);
+    if(rows.length!==1) return fail(`ambiguous or missing ${field} variant for filament ${id}`);
+    return table[rows[0]];
+  });
+  return consistent([resolved,...selectedValues],perFilament,field);
+}
 function stripComments(line: string): string {
   let clean=''; let depth=0;
   for(const char of line) {
@@ -57,6 +116,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 +199,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 +297,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,15 +354,21 @@ 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');
       if(/^SYNC(?=$|\s)/i.test(line)) {
-        // H2D change_filament_gcode emits SYNC T{ceil(flush_length / 125) * 5}.
-        // T is a synchronization duration here, not a nozzle temperature. The
-        // vendor template establishes no independent maximum duration.
+        // Vendor SYNC T is a duration, not a heater target. X2D and P2S
+        // startup templates additionally emit R0; no other R form is supported.
         const args=parameters(line.slice(4));
+        if(args.has('R')) {
+          if(!['x2d','p2s'].includes(model) || args.get('R')!==0) fail('unsupported SYNC reset parameters');
+          args.delete('R');
+        }
         if(args.size!==1 || !args.has('T') || !Number.isFinite(args.get('T')) || args.get('T')!<0) fail('unsupported SYNC duration parameters');
         commandCount++;continue;
       }
@@ -289,6 +376,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, H2D and H2C 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','h2c'].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)) ||
+           // These models 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.
@@ -301,7 +408,14 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
         continue;
       }
       if(['M104','M109','M140','M190','M141','M191'].includes(code)) {
-        const args=parameters(argumentsText,'A');
+        const args=parameters(argumentsText,code==='M104'?'AM':'A');
+        // Studio 2.9's GCodeWriter marks layer-temperature changes with bare M.
+        // Accept only its exact S-target / optional T form; targets and tool
+        // selectors still pass through the independent thermal checks below.
+        if(args.has('M')) {
+          if(!Number.isNaN(args.get('M')!) || !args.has('S') || [...args.keys()].some(key=>!'MST'.includes(key))) fail('unsupported M104 layer-change temperature parameters');
+          args.delete('M');
+        }
         // Official A1 and A1 mini start G-code waits with M109 S<target> H<limit>
         // (S25 H140, S100 H170, S220 H300). H is not a heater target: S stays the
         // checked target, so H is accepted only within those vendor bounds.
@@ -310,9 +424,7 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
           // first-layer targets. Check every base and derived target, never use
           // editable maxima or an unchecked offset as thermal evidence.
           if(code!=='M104' || !h2cStartup(index) || args.size!==2 || args.get('O')!==-80 || !Number.isNaN(args.get('A')!)) fail('unsupported H2C startup offset parameters');
-          const targets=consistent(metadataValues(metadata,['nozzle_temperature_initial_layer']),value=>{
-            const values=list(value);return values.length===materials.length && values.every(v=>NUMBER.test(v) && Number.isFinite(Number(v)))?values.map(Number):undefined;
-          },'first-layer nozzle temperature');
+          const targets=firstLayerTemperatures(project,headers,materials.length);
           for(let position=0;position<targets.length;position++) {
             validateTemperature('nozzle',targets[position],model,[materials[position]]);
             const preheat=Math.max(0,targets[position]-80);
@@ -327,17 +439,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');
@@ -368,8 +486,9 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
         fail(`unsupported thermal-affecting wipe command ${code}`);
       } else if(code==='M620.14') {
         const args=parameters(argumentsText);
-        // H2C tower coordinates include the rear wipe area outside object bounds.
-        if(!h2cStartup(index) || args.size!==2 || !['X','Y'].every(key=>args.has(key) && Number.isFinite(args.get(key)) && args.get(key)!>=0 && args.get(key)!<=350)) fail('unsupported H2C startup tower parameters');
+        // H2C uses these coordinates during startup and a selected filament change.
+        // The rear wipe area extends outside object bounds (official fallback Y336).
+        if(!(h2cStartup(index) || (model==='h2c' && pending!==undefined)) || args.size!==2 || !['X','Y'].every(key=>args.has(key) && Number.isFinite(args.get(key)) && args.get(key)!>=0 && args.get(key)!<=350)) fail('unsupported H2C tower parameters');
       } else if(model==='h2c' && ['G383','G383.3','G383.7'].includes(code) && /U/i.test(argumentsText)) {
         const args=parameters(argumentsText);
         const expected=code==='G383.7'?'UJ':code==='G383.3'?'UL':'OUL';
@@ -400,8 +519,11 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
         // H2D change_filament_gcode supplies the incoming filament's cooling
         // temperature as C{new_filament_temp - filament_cooling_before_tower}.
         const args=parameters(argumentsText);
-        if(args.size!==1 || !args.has('C')) fail('unsupported M620.15 cooling temperature parameters');
-        heat('nozzle',args.get('C')!,pending ?? active);
+        // H2C also supplies P{filament_pre_cooling_temperature_nc[next_filament_id]}
+        // before switching hotends. P and C both constrain the incoming material.
+        const target=model==='h2c' && args.has('P')?'P':'C';
+        if(args.size!==1 || !args.has(target)) fail('unsupported M620.15 cooling temperature parameters');
+        heat('nozzle',args.get(target)!,pending ?? active);
       } else if(code==='M620.17') {
         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');
@@ -436,5 +558,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,...(Array.isArray(project.filament_type)?{projectFilaments:projectFilaments(project)}:{})};
 }

package/src/safety/printer-state.ts

@@ -1,25 +1,13 @@
+import { HIDDEN_HMS } from "./hidden-hms.js";
 import type { BambuClient } from "bambu-node";
-import { normalizeMaterial, normalizeModel } from "./limits.js";
-
-let sequence = 0;
-/**
- * Publish one MQTT command with a string sequence id and no ACK wait.
- * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
- * bambu-printer-mcp patches them to strings for H2-series firmware. This
- * server does not install that patch, so safety-relevant commands are
- * published here with the patched wire shape: {category:{sequence_id,command,...}}.
- */
-export function publishBambuCommand(printer: Pick<BambuClient, "publish">, category: "print" | "pushing" | "info", command: string, extra: Record<string, unknown> = {}): Promise<void> {
-  sequence = (sequence + 1) % 1_000_000_000;
-  return printer.publish({ [category]: { sequence_id: String(sequence), command, ...extra } });
-}
+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",
 };
@@ -104,7 +92,8 @@ export function readFreshPrinterStatus(printer: BambuClient, serial: string, tim
     printer.on("rawMessage", onRaw);
     printer.on("client:disconnect", onDisconnect);
     printer.on("client:error", onError);
-    // Publish only; an ACK wait would add a dependency that H2 firmware lacks.
+    // invoke() publishes only; executeCommand() would add an ACK dependency that H2 firmware lacks.
+    // String sequence ids without bambu-printer-mcp's bambu-node patch (H2-series firmware needs them).
     void Promise.all([publishBambuCommand(printer, "pushing", "pushall"), publishBambuCommand(printer, "info", "get_version")])
       .then(() => { requestsPublished = true; maybeResolve(); }, fail);
   });
@@ -115,6 +104,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;
@@ -131,11 +122,34 @@ interface ReportedNozzle { index: number; diameter: number; type?: string; flow?
 interface ReportedFilament { position: number; material: string; trayIndex: number; nozzleMin?: number; nozzleMax?: number }
 export interface ValidatedPrinterState { model: string; reportedNozzles: ReportedNozzle[]; filaments: ReportedFilament[] }
 
-function finiteNumber(value: unknown): number | undefined {
+export function finiteNumber(value: unknown): number | undefined {
   if (typeof value !== "number" && (typeof value !== "string" || !value.trim())) return undefined;
   const number = Number(value);
   return Number.isFinite(number) ? number : undefined;
 }
+
+/**
+ * X2D retains FAILED after a canceled job even with no active print error.
+ * Bambu Studio classifies FAILED as a finished job; its v02.08.02.61
+ * hms_en_20P table (926a7192574bcb9b3a732e1ec59a46d79cb45466)
+ * calls 0300400C "The task was canceled."
+ * Only this observed terminal condition qualifies, never an arbitrary failure.
+ * Callers still validate HMS, identity, hardware and material configuration,
+ * and print dispatch rechecks the identity of the observed job.
+ */
+export function isCancelledX2DJob(raw: Record<string, any>, model: string): boolean {
+  return normalizeModel(model) === "x2d" && raw.gcode_state === "FAILED" &&
+    finiteNumber(raw.print_error) === 0 && finiteNumber(raw.fail_reason) === 0x0300400c &&
+    [raw.gcode_file, raw.subtask_name].some(value => typeof value === "string" && value.trim().length > 0);
+}
+/** Bambu Studio 2.8.2.61 marks FAILED as finished. Limit P1S recovery to
+ * a named prior job explicitly reporting idle, no print error and no HMS.
+ * Dispatch rechecks the observed job identity. */
+export function isFinishedP1SJob(raw: Record<string, any>, model: string): boolean {
+  return normalizeModel(model) === "p1s" && raw.gcode_state === "FAILED" && raw.print_type === "idle" &&
+    finiteNumber(raw.print_error) === 0 && Array.isArray(raw.hms) && raw.hms.length === 0 &&
+    [raw.gcode_file, raw.subtask_name].some(value => typeof value === "string" && value.trim().length > 0);
+}
 const token = (value: unknown) => typeof value === "string" ? value.trim().toLowerCase().replace(/[\s_-]/g, "") : "";
 function nozzleTypeAndFlow(value: unknown): {type?: string; flow?: string} {
   const text = String(value ?? "");
@@ -170,7 +184,7 @@ export function unchippedNozzles(raw: unknown): number[] {
     const index = finiteNumber(entry?.id);
     const stat = finiteNumber(entry?.stat);
     return index !== undefined && Number.isInteger(index) && index >= 0 && index < 16 &&
-      stat !== undefined && Number.isInteger(stat) && stat >= 0 && unreliableWithoutChip(entry, stat) ? [index] : [];
+      stat !== undefined && Number.isInteger(stat) && unreliableWithoutChip(entry, stat) ? [index] : [];
   });
 }
 
@@ -236,24 +250,96 @@ 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)]));
+
+export type HmsEntry = { attr: number; code: number; severity: number; hex: string };
+export 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.
+ */
+export 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.`);
+  const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
+  if (requireIdle && !["IDLE","FINISH"].includes(state) && !terminal) throw new Error(`Printer state ${state} is not safely idle.`);
+  if (!requireIdle && !["IDLE","FINISH","RUNNING","PAUSE"].includes(state) && !terminal) 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 on the printer 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;
@@ -261,13 +347,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> {
@@ -301,7 +394,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.");
@@ -313,7 +406,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.");
   }
@@ -341,13 +434,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");
@@ -366,7 +473,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 = {
@@ -383,3 +490,35 @@ export function manualHeatingRequirements(status: any, model: string, nozzleDiam
   if (tray < 254) { requirements.useAMS = true; requirements.amsMapping = [tray]; }
   return requirements;
 }
+
+export type ExternalStorageState = "none" | "normal" | "abnormal" | "readonly";
+const EXTERNAL_STORAGE_STATES: readonly ExternalStorageState[] = ["none", "normal", "abnormal", "readonly"];
+
+/**
+ * The SD card or USB stick state, read as Bambu Studio does: the `sdcard`
+ * flag, then `home_flag` bits 8-9, then on firmware that reports cfg/fun/aux/stat
+ * the `aux` bits 12-13, each later source overriding the earlier one
+ * (DevStorage.cpp, DeviceManager.cpp parse_home_flag and parse_new_info).
+ */
+export function externalStorageState(raw: unknown): ExternalStorageState {
+  if (!object(raw)) return "none";
+  let state: ExternalStorageState = raw.sdcard === true ? "normal" : "none";
+  if (Number.isInteger(raw.home_flag)) state = EXTERNAL_STORAGE_STATES[(raw.home_flag >> 8) & 3];
+  if (["cfg", "fun", "aux", "stat"].every(key => key in raw) && typeof raw.aux === "string" && /^[0-9a-f]+$/i.test(raw.aux)) {
+    state = EXTERNAL_STORAGE_STATES[Number((BigInt(`0x${raw.aux}`) >> 12n) & 3n)];
+  }
+  return state;
+}
+
+let sequence = 0;
+/**
+ * Publish one MQTT command with a string sequence id and no ACK wait.
+ * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
+ * bambu-printer-mcp patches them to strings for H2-series firmware. This
+ * server does not install that patch, so safety-relevant commands are
+ * published here with the patched wire shape: {category:{sequence_id,command,...}}.
+ */
+export function publishBambuCommand(printer: Pick<BambuClient, "publish">, category: "print" | "pushing" | "info", command: string, extra: Record<string, unknown> = {}): Promise<void> {
+  sequence = (sequence + 1) % 1_000_000_000;
+  return printer.publish({ [category]: { sequence_id: String(sequence), command, ...extra } });
+}