bambu-printer-mcp 1.1.12 → 1.1.14

package/src/printers/bambu.ts

@@ -1,10 +1,15 @@
 import { createHash } from "node:crypto";
+import { readFreshPrinterStatus } from "../safety/printer-state.js";
 import fs from "node:fs/promises";
 import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { Readable } from "node:stream";
-import JSZip from "jszip";
+import { readSafe3mfArchive } from "../safety/archive.js";
+import { inspectPrintFile, type PrintFileInspection } from "../safety/print-file.js";
+import { normalizeModel, validateTemperature } from "../safety/limits.js";
+import { 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";
 import { BambuPrinter } from "bambu-js";
 import * as mqtt from "mqtt";
@@ -57,13 +62,13 @@ const MODEL_ID_TO_NAME: Record<string, string> = {
   C13: "X1E",
 };
 
-const H2_MODEL_NAMES = new Set(["h2", "h2c", "h2d", "h2dpro", "h2d pro", "h2s"]);
+const H2_MODEL_NAMES = new Set(["h2", "h2c", "h2d", "h2dpro", "h2d pro", "h2s", "x2d"]);
 
 export function assertDirectPrintSupported(model: string | undefined, serial?: string): void {
   if (model?.trim().toLowerCase() === "x2d" || serial?.trim().toUpperCase().startsWith("20P")) {
     throw new Error(
-      "X2D direct printing is not supported pending native eMMC transport support. " +
-      "X2D status and slicing remain available; use a supported slicer to print."
+      "X2D direct printing is not supported through legacy MQTT/FTPS. Use the macOS native eMMC route via print_3mf. " +
+      "X2D status and slicing remain available on all supported platforms."
     );
   }
 }
@@ -80,6 +85,7 @@ interface BambuPrintOptionsInternal {
   projectName: string;
   filePath: string;
   bambuModel?: string;
+  nozzleDiameters?: number[];
   useAMS?: boolean;
   plateIndex?: number;
   bedType?: string;
@@ -245,9 +251,18 @@ class TolerantBambuClient extends BambuClient {
   }
 }
 
-/** Build FTPS secureOptions that include the client cert+key when available. */
-function ftpsSecureOptions(): Record<string, unknown> {
-  const opts: Record<string, unknown> = { rejectUnauthorized: false };
+/**
+ * Build FTPS secureOptions that include the client cert+key when available.
+ *
+ * `host` must be included: basic-ftp opens each data connection by wrapping
+ * a plain socket with tls.connect(tlsOptions), and without a host Node can bind
+ * the resumable session to "localhost" instead of the printer host. Printers
+ * that require TLS session reuse (vsftpd require_ssl_reuse, e.g. X2D) refuse
+ * to resume the session and reply "522 SSL connection failed: session reuse
+ * required", failing every LIST, STOR and RETR.
+ */
+function ftpsSecureOptions(host: string): Record<string, unknown> {
+  const opts: Record<string, unknown> = { rejectUnauthorized: false, host };
   if (CLIENT_CREDS) {
     opts.cert = CLIENT_CREDS.cert;
     opts.key = CLIENT_CREDS.key;
@@ -430,48 +445,80 @@ class BambuClientStore {
 
 export class BambuImplementation {
   private printerStore: BambuClientStore;
+  private checkedJobs = new Map<string, { remotePath: string; requirements: PrinterStateRequirements }>();
+  private clearedErrors = new Map<string, string[]>();
 
-  constructor() {
+  constructor(private readonly confirm?: (message: string) => Promise<boolean>) {
     this.printerStore = new BambuClientStore();
   }
 
-  private async getPrinter(host: string, serial: string, token: string): Promise<BambuClient> {
-    return this.printerStore.getPrinter(host, serial, token);
+  async confirmHardwareAction(message: string, physicalCheck = false): Promise<void> {
+    if (!physicalCheck && process.env.BAMBU_REQUIRE_CONFIRMATION === "0") return;
+    if (!this.confirm || !(await this.confirm(message))) {
+      throw new Error("Hardware safety confirmation was declined or unavailable. Use an MCP client with elicitation support. No command was sent.");
+    }
   }
 
-  private async resolveProjectFileMetadata(
-    localThreeMfPath: string,
-    plateIndex?: number
-  ): Promise<ProjectFileMetadata> {
-    const archive = await fs.readFile(localThreeMfPath);
-    const zip = await JSZip.loadAsync(archive);
+  private finishedJobIdentity(status: any): string | undefined {
+    return status.raw.gcode_state === "FINISH" ? JSON.stringify([status.raw.gcode_file, status.raw.subtask_name, status.raw.task_id, status.raw.subtask_id]) : undefined;
+  }
 
-    const plateEntries = Object.values(zip.files).filter(
-      (entry) => !entry.dir && /^Metadata\/plate_\d+\.gcode$/i.test(entry.name)
+  async confirmPrintPreflight(serial: string, status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): Promise<string | undefined> {
+    const finishedJob = this.finishedJobIdentity(status);
+    const cleared = this.clearedErrors.get(serial);
+    await this.confirmHardwareAction(
+      `Start a checked print on ${inspection.model.toUpperCase()} (${serial})? Nozzles: ${inspection.nozzleDiameters.join(", ")} mm. ` +
+      `Materials: ${inspection.materials.join(", ")}. Peak targets: nozzle ${inspection.maxNozzleTemperature}°C, bed ${inspection.maxBedTemperature}°C, chamber ${inspection.maxChamberTemperature}°C. ` +
+      `File SHA-256: ${inspection.sha256}. Confirm the physical spool labels and that the build plate is clear.` +
+      (finishedJob !== undefined ? " The printer reports FINISH: remove the previous part and debris before confirming." : "") +
+      (cleared ? ` Previously cleared hardware codes: ${cleared.join(", ")}. Confirm their physical causes have been resolved.` : ""),
+      finishedJob !== undefined || !!cleared
     );
+    return finishedJob;
+  }
 
-    if (plateEntries.length === 0) {
-      throw new Error(
-        "3MF does not contain any Metadata/plate_<n>.gcode entries. Re-slice and export a printable 3MF."
-      );
+  assertBedClearance(status: any, confirmedFinishedJob: string | undefined): void {
+    const current = this.finishedJobIdentity(status);
+    if (current !== undefined && current !== confirmedFinishedJob) {
+      throw new Error("Printer reports a newly finished job. Confirm that its part and debris have been removed before retrying the print.");
     }
+  }
+
+  private async getPrinter(host: string, serial: string, token: string): Promise<BambuClient> {
+    return this.printerStore.getPrinter(host, serial, token);
+  }
 
-    let selectedEntry = plateEntries.sort((a, b) => a.name.localeCompare(b.name))[0];
+  /** Internal handoff from a successful inspected transport; never exposed as an MCP tool. */
+  recordCheckedJob(host: string, serial: string, remotePath: string, requirements: PrinterStateRequirements): void {
+    this.checkedJobs.set(`${host}\n${serial}`, { remotePath, requirements: structuredClone(requirements) });
+    this.clearedErrors.delete(serial);
+  }
 
-    if (plateIndex !== undefined) {
-      const expectedEntryName = `Metadata/plate_${plateIndex + 1}.gcode`;
-      const matchedEntry = plateEntries.find(
-        (entry) => entry.name.toLowerCase() === expectedEntryName.toLowerCase()
-      );
+  private validateLoadedGcodeState(status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): PrinterStateRequirements {
+    const usedMaterials = inspection.usedFilamentPositions.map(position => inspection.materials[position]);
+    if (new Set(usedMaterials).size !== 1) throw new Error("gcode_file printing cannot verify physical changes between different materials. Use a mapped .3mf project.");
+    const loaded = manualHeatingRequirements(status, inspection.model, inspection.nozzleDiameters[0], usedMaterials[0]);
+    const mapping = Array<number>(inspection.materials.length).fill(-1);
+    inspection.usedFilamentPositions.forEach(position => { mapping[position] = loaded.amsMapping?.[0] ?? 254; });
+    const requirements = { ...inspection, useAMS: loaded.useAMS, amsMapping: mapping, usedNozzleIndices: loaded.usedNozzleIndices, requireLoadedFilament: true };
+    validatePrinterState(status, requirements);
+    return requirements;
+  }
 
-      if (!matchedEntry) {
-        const available = plateEntries.map((entry) => entry.name).join(", ");
-        throw new Error(
-          `Requested plateIndex=${plateIndex} (${expectedEntryName}) not present in 3MF. Available: ${available}`
-        );
-      }
+  private async resolveProjectFileMetadata(
+    localThreeMfPath: string,
+    plateIndex?: number,
+    inspectedPlatePath?: string
+  ): Promise<ProjectFileMetadata> {
+    const { zip } = await readSafe3mfArchive(localThreeMfPath);
 
-      selectedEntry = matchedEntry;
+    const expectedEntryName = `Metadata/plate_${(plateIndex ?? 0) + 1}.gcode`;
+    if (inspectedPlatePath !== undefined && inspectedPlatePath !== expectedEntryName) {
+      throw new Error("Inspected plate path does not match the requested print plate.");
+    }
+    const selectedEntry = zip.file(inspectedPlatePath ?? expectedEntryName);
+    if (!selectedEntry) {
+      throw new Error(`Selected inspected plate ${expectedEntryName} is not present in 3MF. Re-slice that plate.`);
     }
 
     const gcodeBuffer = await selectedEntry.async("nodebuffer");
@@ -525,6 +572,11 @@ export class BambuImplementation {
     };
   }
 
+  /** Safety reads never use the display cache or configured-serial model inference. */
+  async getSafetyStatus(host: string, serial: string, token: string): Promise<any> {
+    return readFreshPrinterStatus(await this.getPrinter(host, serial, token), serial);
+  }
+
   async getStatus(host: string, serial: string, token: string): Promise<any> {
     try {
       const printer = await this.getPrinter(host, serial, token);
@@ -580,6 +632,14 @@ export class BambuImplementation {
     options: BambuPrintOptionsInternal
   ): Promise<any> {
     assertDirectPrintSupported(options.bambuModel, serial);
+    return withPrinterOperation(host, serial, assertActive => withPrintSnapshot(options.filePath, filePath =>
+      this.print3mfPrepared(host, serial, token, { ...options, filePath }, assertActive)
+    ));
+  }
+
+  private async print3mfPrepared(host: string, serial: string, token: string, options: BambuPrintOptionsInternal, assertActive: () => void): Promise<any> {
+    const model = normalizeModel(options.bambuModel);
+    if (!model) throw new Error("A supported bambuModel is required before printing.");
     if (!options.filePath.toLowerCase().endsWith(".3mf")) {
       throw new Error("print3mf requires a .3mf input file.");
     }
@@ -587,7 +647,7 @@ export class BambuImplementation {
     // Normalise remote filename: collapse double-extension artifacts like
     // "Cube.gcode.3mf.gcode.3mf" -> "Cube.gcode.3mf" so firmware can identify
     // the container format from the extension.
-    let remoteFileName = path.basename(options.filePath);
+    let remoteFileName = uniquePrintName(options.filePath);
     remoteFileName = remoteFileName.replace(/\.gcode\.3mf\.gcode\.3mf$/i, ".gcode.3mf");
 
     // H2-series printers land files at the FTP root and reference them via ftp:///<name>.
@@ -610,37 +670,19 @@ export class BambuImplementation {
       ? `ftp:///${remoteProjectPath}`
       : `file:///sdcard/${remoteProjectPath}`;
 
-    // Upload via basic-ftp directly (bypasses bambu-js double-path bug)
-    await this.ftpUpload(host, token, options.filePath, remoteUploadPath);
-
-    // Pre-sliced .gcode.3mf files: routing depends on firmware generation.
-    // Legacy P1/X1/A1 mini: project_file returns 405004002 for .gcode.3mf (firmware
-    // doesn't recognise the container), so use gcode_file instead.
-    // H2-series and P2S: gcode_file is not supported (P2S answers 0500-4002
-    // "Unsupported file path or name"); project_file works because the
-    // firmware can open the zip and find Metadata/plate_<n>.gcode directly.
-    if (options.filePath.toLowerCase().endsWith(".gcode.3mf")) {
-      if (!usesH2ProjectFile && !isA1) {
-        const printer = await this.getPrinter(host, serial, token);
-        await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remoteProjectPath }));
-        return {
-          status: "success",
-          message: `Uploaded and started gcode.3mf print: ${options.projectName}`,
-          remoteProjectPath,
-        };
-      }
-      // H2-series and P2S: fall through to project_file path below
-    }
-
+    const inspection = await inspectPrintFile(options.filePath, {
+      model, nozzleDiameters: options.nozzleDiameters, plateIndex: options.plateIndex ?? 0, bedType: options.bedType,
+    });
     const projectMetadata = await this.resolveProjectFileMetadata(
       options.filePath,
-      options.plateIndex
+      options.plateIndex,
+      inspection.plateInternalPath
     );
 
     // Send project_file command via bambu-node MQTT (bypasses bambu-js
     // hardcoded use_ams=true and missing ams_mapping support)
-    const printer = await this.getPrinter(host, serial, token);
-    const md5 = options.md5 ?? projectMetadata.md5;
+    const md5 = projectMetadata.md5;
+    if (options.md5 !== undefined && options.md5 !== md5) throw new Error("Provided checksum does not match the inspected plate G-code.");
 
     // Build AMS mapping.
     //
@@ -696,7 +738,7 @@ export class BambuImplementation {
         baseMapping[pos] = options.amsSlots![i];
       });
     } else {
-      if (isH2 && projectMetadata.usedFilamentPositions.length > 0) {
+      if (options.useAMS !== false && projectMetadata.usedFilamentPositions.length > 0) {
         throw new Error(
           `H2 project_file requires amsSlots or amsMapping for sliced files with declared filaments. Plate uses project filament positions ${JSON.stringify(projectMetadata.usedFilamentPositions)}.`
         );
@@ -709,7 +751,7 @@ export class BambuImplementation {
       );
       baseMapping = Array<number>(projectLen).fill(-1);
       positions.forEach((pos, i) => {
-        baseMapping[pos] = i;
+        baseMapping[pos] = options.useAMS === false ? 254 : i;
       });
     }
 
@@ -733,6 +775,49 @@ export class BambuImplementation {
       amsMapping2 = [];
     }
 
+    for (const position of inspection.usedFilamentPositions) {
+      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).");
+      }
+    }
+    const legacyContainer = options.filePath.toLowerCase().endsWith(".gcode.3mf") && !usesH2ProjectFile && !isA1;
+    if (legacyContainer) {
+      if (options.useAMS !== false || inspection.selectsAms) {
+        throw new Error("Legacy .gcode.3mf transport cannot apply verified AMS mappings. Export a .3mf project for AMS printing, or use an external-spool-only job with use_ams:false.");
+      }
+      const { zip: archive } = await readSafe3mfArchive(options.filePath);
+      const plates = Object.values(archive.files).filter(entry => !entry.dir && /^Metadata\/plate_\d+\.gcode$/i.test(entry.name));
+      if (plates.length !== 1 || inspection.plateInternalPath?.toLowerCase() !== "metadata/plate_1.gcode") {
+        throw new Error("Legacy gcode_file printing requires a single plate_1.gcode. Export only the selected plate or use a .3mf project_file export.");
+      }
+    }
+    let requirements: PrinterStateRequirements = { ...inspection, amsMapping: baseMapping, useAMS: options.useAMS !== false };
+    const initialStatus = await this.getSafetyStatus(host, serial, token);
+    if (legacyContainer) requirements = this.validateLoadedGcodeState(initialStatus, inspection);
+    else validatePrinterState(initialStatus, requirements);
+    const bedClearance = await this.confirmPrintPreflight(serial, initialStatus, inspection);
+    const confirmedStatus = await this.getSafetyStatus(host, serial, token);
+    if (legacyContainer) requirements = this.validateLoadedGcodeState(confirmedStatus, inspection);
+    else validatePrinterState(confirmedStatus, requirements);
+    this.assertBedClearance(confirmedStatus, bedClearance);
+    assertActive();
+    await this.ftpUpload(host, token, options.filePath, remoteUploadPath);
+    // Uploads can be long. Recheck current state before the command is dispatched.
+    const dispatchStatus = await this.getSafetyStatus(host, serial, token);
+    if (legacyContainer) requirements = this.validateLoadedGcodeState(dispatchStatus, inspection);
+    else validatePrinterState(dispatchStatus, requirements);
+    this.assertBedClearance(dispatchStatus, bedClearance);
+    const printer = await this.getPrinter(host, serial, token);
+    assertActive();
+    if (legacyContainer) {
+      await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remoteProjectPath }));
+      this.recordCheckedJob(host, serial, remoteProjectPath, requirements);
+      return { status: "success", message: `Uploaded and started gcode.3mf print: ${options.projectName}`, remoteProjectPath };
+    }
+
     const b = (v: any) => (v ? 1 : 0);
     let projectFileCmd: Record<string, any>;
     if (usesH2ProjectFile) {
@@ -741,7 +826,7 @@ export class BambuImplementation {
         print: {
           sequence_id: "0",
           command: "project_file",
-          param: `Metadata/${projectMetadata.plateFileName}`,
+          param: projectMetadata.plateInternalPath,
           url: projectUrl,
           file: remoteFileName,
           md5,
@@ -770,9 +855,9 @@ export class BambuImplementation {
       projectFileCmd = {
         print: {
           command: "project_file",
-          param: `Metadata/${projectMetadata.plateFileName}`,
+          param: projectMetadata.plateInternalPath,
           url: projectUrl,
-          subtask_name: options.projectName,
+          subtask_name: remoteFileName.replace(/\.3mf$/i, ""),
           md5,
           flow_cali: options.flowCalibration ?? true,
           layer_inspect: options.layerInspect ?? true,
@@ -792,6 +877,7 @@ export class BambuImplementation {
     }
 
     await printer.publish(projectFileCmd);
+    this.recordCheckedJob(host, serial, remoteProjectPath, requirements);
     await new Promise((resolve) => setTimeout(resolve, 300));
 
     return {
@@ -805,47 +891,78 @@ export class BambuImplementation {
     };
   }
 
-  async cancelJob(host: string, serial: string, token: string): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
+  async cancelJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any> {
+    cancelPendingPrinterOperations(host, serial);
+    this.checkedJobs.delete(`${host}\n${serial}`);
+    const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
 
     try {
-      await invokeWithoutAck(printer, new UpdateStateCommand({ state: "stop" }));
+      if (dispatch) return await dispatch();
+      else await invokeWithoutAck(printer!, new UpdateStateCommand({ state: "stop" }));
+      this.checkedJobs.delete(`${host}\n${serial}`);
       return { status: "success", message: "Cancel command sent successfully." };
     } catch (error) {
       throw new Error(`Failed to cancel print: ${(error as Error).message}`);
     }
   }
 
-  async pauseJob(host: string, serial: string, token: string): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
+  async pauseJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any> {
+    const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
     try {
-      await invokeWithoutAck(printer, new UpdateStateCommand({ state: "pause" }));
+      if (dispatch) return await dispatch();
+      else await invokeWithoutAck(printer!, new UpdateStateCommand({ state: "pause" }));
       return { status: "success", message: "Pause command sent successfully." };
     } catch (error) {
       throw new Error(`Failed to pause print: ${(error as Error).message}`);
     }
   }
 
-  async resumeJob(host: string, serial: string, token: string): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
-    try {
-      await invokeWithoutAck(printer, new UpdateStateCommand({ state: "resume" }));
+  async resumeJob(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any> {
+    return withPrinterOperation(host, serial, async assertActive => {
+      const checked = this.checkedJobs.get(`${host}\n${serial}`);
+      if (!checked) throw new Error("Resume requires a job inspected and started by this server instance. Verify other jobs on the printer before resuming them there.");
+      const beforeDispatch = async () => {
+        assertActive();
+        const status = await this.getSafetyStatus(host, serial, token);
+        validatePrinterState(status, { ...checked.requirements, requireIdle: false });
+        if (status.raw.gcode_state !== "PAUSE") throw new Error("Resume requires a freshly reported paused job.");
+        const stem = (value: string) => path.posix.basename(value).replace(/(?:\.gcode)?\.3mf$|\.gcode$/i, "");
+        const names = [status.raw.gcode_file, status.raw.subtask_name].filter(value => typeof value === "string");
+        if (!names.some(value => stem(value) === stem(checked.remotePath))) throw new Error("Paused job identity does not match this server's inspected artifact.");
+        assertActive();
+      };
+      await beforeDispatch();
+      const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
+      assertActive();
+      if (dispatch) await dispatch(assertActive, beforeDispatch);
+      else await invokeWithoutAck(printer!, new UpdateStateCommand({ state: "resume" }));
       return { status: "success", message: "Resume command sent successfully." };
-    } catch (error) {
-      throw new Error(`Failed to resume print: ${(error as Error).message}`);
-    }
+    });
   }
 
-  async clearHmsErrors(host: string, serial: string, token: string): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
-    await printer.publish({
-      print: {
-        command: "clean_print_error",
-        sequence_id: "0",
-      },
+  async clearHmsErrors(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any> {
+    return withPrinterOperation(host, serial, async assertActive => {
+      const codesFor = (status: any): string[] => {
+        if (!Array.isArray(status.raw?.hms) || status.raw?.print_error === undefined) throw new Error("Fresh error codes are required before clearing hardware errors.");
+        return [`print_error:${status.raw.print_error}`, ...status.raw.hms.map((entry: any) => `hms:${entry.attr}:${entry.code}`)].sort();
+      };
+      const codes = codesFor(await this.getSafetyStatus(host, serial, token));
+      await this.confirmHardwareAction(`Clear reported hardware errors on ${serial}: ${codes.join(", ")}? Inspect the printer and resolve the physical cause first. Confirm only after removing obstructions and correcting the fault.`, true);
+      const beforeDispatch = async () => {
+        assertActive();
+        const current = codesFor(await this.getSafetyStatus(host, serial, token));
+        if (JSON.stringify(current) !== JSON.stringify(codes)) throw new Error("Hardware errors changed before clearing. Inspect the new report before retrying.");
+        assertActive();
+      };
+      await beforeDispatch();
+      const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
+      assertActive();
+      if (dispatch) await dispatch(assertActive, beforeDispatch);
+      else await printer!.publish({ print: { command: "clean_print_error", sequence_id: "0" } });
+      this.clearedErrors.set(serial, codes);
+      await sleep(COMMAND_SETTLE_MS);
+      return { status: "success", message: "Confirmed HMS clear command sent. The next print requires acknowledgment of these cleared codes.", cleared_codes: codes };
     });
-    await sleep(COMMAND_SETTLE_MS);
-    return { status: "success", message: "HMS clear command sent." };
   }
 
   async setPrintSpeed(host: string, serial: string, token: string, speedMode: string | number): Promise<any> {
@@ -910,9 +1027,8 @@ export class BambuImplementation {
     amsId: number,
     slotId: number
   ): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
-    const normalizedAmsId = Math.trunc(amsId);
-    const normalizedSlotId = Math.trunc(slotId);
+    const normalizedAmsId = amsId;
+    const normalizedSlotId = slotId;
 
     if (!Number.isInteger(normalizedAmsId) || normalizedAmsId < 0 || normalizedAmsId > 3) {
       throw new Error("ams_id must be an integer from 0 to 3.");
@@ -921,6 +1037,7 @@ export class BambuImplementation {
       throw new Error("slot_id must be an integer from 0 to 3.");
     }
 
+    const printer = await this.getPrinter(host, serial, token);
     await printer.publish({
       print: {
         command: "ams_get_rfid",
@@ -943,39 +1060,58 @@ export class BambuImplementation {
     serial: string,
     token: string,
     component: string,
-    temperature: number
+    temperature: unknown,
+    bambuModel?: string,
+    material?: string,
+    nozzleDiameter = 0.4,
+    dispatch?: (heater: "bed" | "nozzle", target: number, assertActive: () => void, beforeDispatch?: () => Promise<void>) => Promise<any>
   ) {
-    const printer = await this.getPrinter(host, serial, token);
-
     const normalizedComponent = component.toLowerCase();
-    const targetTemperature = Math.round(temperature);
-
-    if (targetTemperature < 0 || targetTemperature > 300) {
-      throw new Error("Temperature must be between 0 and 300°C.");
-    }
-
-    let gcode: string;
-    if (normalizedComponent === "bed") {
-      gcode = `M140 S${targetTemperature}`;
-    } else if (
-      normalizedComponent === "extruder" ||
-      normalizedComponent === "nozzle" ||
-      normalizedComponent === "tool" ||
-      normalizedComponent === "tool0"
-    ) {
-      gcode = `M104 S${targetTemperature}`;
-    } else {
+    const heater = normalizedComponent === "bed" ? "bed" :
+      ["extruder", "nozzle", "tool", "tool0"].includes(normalizedComponent) ? "nozzle" : undefined;
+    if (!heater) {
       throw new Error(
         `Unsupported temperature component: ${component}. Use one of: bed, nozzle, extruder.`
       );
     }
-
-    await invokeWithoutAck(printer, new GCodeLineCommand({ gcodes: [gcode] }));
-    return {
-      status: "success",
-      message: `Temperature command sent for ${normalizedComponent}.`,
-      command: gcode,
+    if (typeof temperature !== "number" || !Number.isFinite(temperature) || temperature < 0) {
+      throw new Error("Temperature must be a finite, non-negative number in °C.");
+    }
+    const model = normalizeModel(bambuModel);
+    if (temperature > 0 && !model) throw new Error("bambu_model is required before heating.");
+    if (temperature > 0 && heater === "nozzle" && !material?.trim()) {
+      throw new Error("Declare material before nozzle heating, including non-RFID external spools.");
+    }
+    const targetTemperature = temperature === 0 ? 0 : validateTemperature(heater, temperature, model!, material ? [material] : undefined);
+    const gcode = `${heater === "bed" ? "M140" : "M104"}${heater === "nozzle" && targetTemperature > 0 ? " T0" : ""} S${targetTemperature}`;
+    const send = async (assertActive: () => void) => {
+      let beforeDispatch: (() => Promise<void>) | undefined;
+      if (targetTemperature > 0) {
+        const status = await this.getSafetyStatus(host, serial, token);
+        const validateHeatingStatus = (current: any) => validatePrinterState(current, heater === "nozzle"
+          ? manualHeatingRequirements(current, model!, nozzleDiameter, material!)
+          : { model: model!, nozzleDiameters: [] });
+        validateHeatingStatus(status);
+        await this.confirmHardwareAction(`Heat ${heater} on ${model!.toUpperCase()} (${serial}) to ${targetTemperature}°C?${material ? ` Declared material: ${material}. Confirm the physical spool label.` : ""}`);
+        beforeDispatch = async () => {
+          assertActive();
+          const confirmedStatus = await this.getSafetyStatus(host, serial, token);
+          validateHeatingStatus(confirmedStatus);
+          assertActive();
+        };
+        await beforeDispatch();
+      }
+      const printer = dispatch ? undefined : await this.getPrinter(host, serial, token);
+      assertActive();
+      if (dispatch) await dispatch(heater, targetTemperature, assertActive, beforeDispatch);
+      else await invokeWithoutAck(printer!, new GCodeLineCommand({ gcodes: [gcode] }));
+      return { status: "success", message: `Temperature command sent for ${normalizedComponent}.`, command: gcode };
     };
+    if (targetTemperature === 0) {
+      cancelPendingPrinterOperations(host, serial);
+      return send(() => undefined);
+    }
+    return withPrinterOperation(host, serial, send);
   }
 
   async setFanSpeed(
@@ -1058,18 +1194,18 @@ export class BambuImplementation {
     action: string,
     amsId: number
   ): Promise<any> {
-    const printer = await this.getPrinter(host, serial, token);
     const normalizedAction = action.trim().toLowerCase();
     if (normalizedAction !== "start" && normalizedAction !== "stop") {
       throw new Error("AMS drying action must be one of: start, stop.");
     }
 
-    const normalizedAmsId = Math.trunc(amsId);
+    const normalizedAmsId = amsId;
     if (!Number.isInteger(normalizedAmsId) || normalizedAmsId < 0 || normalizedAmsId > 3) {
       throw new Error("ams_id must be an integer from 0 to 3.");
     }
 
     const param = normalizedAction === "start" ? "start_drying" : "stop_drying";
+    const printer = await this.getPrinter(host, serial, token);
     await printer.publish({
       print: {
         command: "ams_control",
@@ -1166,69 +1302,116 @@ export class BambuImplementation {
   }
 
   async uploadFile(
-    host: string,
-    serial: string,
-    token: string,
-    filePath: string,
-    filename: string,
-    print: boolean,
-    bambuModel?: string
+    host: string, serial: string, token: string, filePath: string,
+    filename: string, print: boolean, bambuModel?: string,
+    upload?: (snapshot: string, destination: string, assertActive: () => void) => Promise<void>
   ) {
-    if (print) assertDirectPrintSupported(bambuModel, serial);
-    await fs.access(filePath);
-
-    const normalizedFileName = filename.replace(/^\/+/, "");
-    const remotePath = normalizedFileName.includes("/")
-      ? normalizedFileName
-      : `cache/${normalizedFileName}`;
-
-    // Use direct FTP upload (bypasses bambu-js double-path bug)
-    await this.ftpUpload(host, token, filePath, `/${remotePath}`);
-
-    const response: Record<string, unknown> = {
-      status: "success",
-      uploaded: true,
-      remotePath,
-      printRequested: print,
-    };
-
-    if (print) {
-      if (remotePath.toLowerCase().endsWith(".gcode")) {
-        response.startResult = await this.startJob(host, serial, token, remotePath, bambuModel);
-      } else if (remotePath.toLowerCase().endsWith(".3mf")) {
-        response.note =
-          "3MF upload complete. Use print_3mf to start a project print with plate and metadata options.";
-      } else {
-        throw new Error(
-          "Automatic print after upload supports .gcode only. Use print_3mf for .3mf project prints."
-        );
+    const remotePath = normalizedRemotePath(filename);
+    if (!print) {
+      const sourceExtension = path.extname(filePath).toLowerCase();
+      const destinationExtension = path.posix.extname(remotePath).toLowerCase();
+      const printable = [sourceExtension, destinationExtension].some(extension => extension === ".gcode" || extension === ".3mf");
+      const model = normalizeModel(bambuModel);
+      if (printable && !model) throw new Error("A supported bambuModel is required to inspect printable uploads, even when print is false.");
+      if (printable && sourceExtension !== destinationExtension) {
+        throw new Error("Printable uploads require matching .gcode or .3mf source and destination extensions.");
       }
+      return withPrinterOperation(host, serial, assertActive => withPrintSnapshot(filePath, async snapshot => {
+        const inspections: PrintFileInspection[] = [];
+        if (printable) {
+          if (sourceExtension === ".3mf") {
+            const { zip } = await readSafe3mfArchive(snapshot);
+            const plates = Object.values(zip.files).filter(entry => !entry.dir && /\.gcode$/i.test(entry.name));
+            if (!plates.length) throw new Error("Printable 3MF uploads require a sliced archive containing Metadata/plate_<n>.gcode.");
+            // A later touchscreen start may select any plate in this archive.
+            for (const plate of plates) {
+              const match = plate.name.match(/^Metadata\/plate_([1-9]\d*)\.gcode$/);
+              const plateNumber = match ? Number(match[1]) : NaN;
+              if (!Number.isSafeInteger(plateNumber)) {
+                throw new Error(`Noncanonical printable G-code entry '${plate.name}'. Re-export using exact Metadata/plate_<positive integer>.gcode paths without aliases.`);
+              }
+              const inspection = await inspectPrintFile(snapshot, { model: model!, plateIndex: plateNumber - 1 });
+              if (inspection.plateInternalPath !== plate.name) {
+                throw new Error(`Printable G-code entry '${plate.name}' does not match the inspected plate path.`);
+              }
+              inspections.push(inspection);
+            }
+          } else {
+            inspections.push(await inspectPrintFile(snapshot, { model: model! }));
+          }
+          const status = await this.getSafetyStatus(host, serial, token);
+          for (const inspection of inspections) {
+            validatePrinterState(status, { ...inspection, verifyMaterials: false, requireIdle: false });
+          }
+        }
+        assertActive();
+        const destination = path.posix.join(path.posix.dirname(remotePath), uniquePrintName(remotePath));
+        if (upload) await upload(snapshot, destination, assertActive);
+        else await this.ftpUpload(host, token, snapshot, `/${destination}`);
+        return { status: "success", uploaded: true, remotePath: destination, printRequested: false, inspected: printable };
+      }));
+    }
+    assertDirectPrintSupported(bambuModel, serial);
+    if (!remotePath.toLowerCase().endsWith(".gcode") || !filePath.toLowerCase().endsWith(".gcode")) {
+      throw new Error("Automatic print after upload requires .gcode. Use print_3mf for inspected .3mf project prints.");
     }
+    return withPrinterOperation(host, serial, assertActive => withPrintSnapshot(filePath, snapshot =>
+      this.printRawPrepared(host, serial, token, snapshot, remotePath, bambuModel, assertActive)
+    ));
+  }
 
-    return response;
+  private async printRawPrepared(host: string, serial: string, token: string, filePath: string, filename: string, bambuModel: string | undefined, assertActive: () => void) {
+    const model = normalizeModel(bambuModel);
+    if (!model) throw new Error("A supported bambuModel is required before printing.");
+    const inspection = await inspectPrintFile(filePath, { model });
+    if (inspection.selectsAms) throw new Error("Raw G-code with AMS selection requires a .3mf project export with verified physical slot mappings.");
+    const initialStatus = await this.getSafetyStatus(host, serial, token);
+    let requirements = this.validateLoadedGcodeState(initialStatus, inspection);
+    const bedClearance = await this.confirmPrintPreflight(serial, initialStatus, inspection);
+    const confirmedStatus = await this.getSafetyStatus(host, serial, token);
+    requirements = this.validateLoadedGcodeState(confirmedStatus, inspection);
+    this.assertBedClearance(confirmedStatus, bedClearance);
+    assertActive();
+    const remotePath = path.posix.join(path.posix.dirname(filename), uniquePrintName(filename));
+    await this.ftpUpload(host, token, filePath, `/${remotePath}`);
+    const dispatchStatus = await this.getSafetyStatus(host, serial, token);
+    requirements = this.validateLoadedGcodeState(dispatchStatus, inspection);
+    this.assertBedClearance(dispatchStatus, bedClearance);
+    const printer = await this.getPrinter(host, serial, token);
+    assertActive();
+    await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remotePath }));
+    this.recordCheckedJob(host, serial, remotePath, requirements);
+    return { status: "success", uploaded: true, printRequested: true, remotePath, message: `Checked and started ${remotePath}.` };
   }
 
   async startJob(host: string, serial: string, token: string, filename: string, bambuModel?: string) {
     assertDirectPrintSupported(bambuModel, serial);
-    const lower = filename.toLowerCase();
-    if (lower.endsWith(".3mf") && !lower.endsWith(".gcode.3mf")) {
-      throw new Error("Use print_3mf for .3mf project files.");
+    if (!normalizeModel(bambuModel)) throw new Error("A supported bambuModel is required before printing.");
+    const remotePath = normalizedRemotePath(filename);
+    if (!remotePath.toLowerCase().endsWith(".gcode")) {
+      throw new Error("Remote starts require inspectable .gcode. Use print_3mf with the local project for .3mf printing.");
     }
+    return withPrinterOperation(host, serial, async assertActive => {
+      const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bambu-remote-check-"));
+      const localPath = path.join(directory, path.basename(remotePath));
+      try {
+        await this.ftpDownload(host, token, remotePath, localPath);
+        // Send a unique copy of the downloaded, inspected bytes. Starting the
+        // original remote name would allow it to change after inspection.
+        return await withPrintSnapshot(localPath, snapshot => this.printRawPrepared(host, serial, token, snapshot, remotePath, bambuModel, assertActive));
+      } finally { await fs.rm(directory, { recursive: true, force: true }); }
+    });
+  }
 
-    const printer = await this.getPrinter(host, serial, token);
-
-    const normalizedFileName = filename.replace(/^\/+/, "");
-    const remoteFile = normalizedFileName.includes("/")
-      ? normalizedFileName
-      : `cache/${normalizedFileName}`;
-
-    await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remoteFile }));
-
-    return {
-      status: "success",
-      message: `Start command sent for ${remoteFile}.`,
-      file: remoteFile,
-    };
+  private async ftpDownload(host: string, token: string, remotePath: string, localPath: string): Promise<void> {
+    const client = new FTPClient(15_000);
+    try {
+      await client.access({ host, port: 990, user: "bblp", password: token, secure: "implicit", secureOptions: ftpsSecureOptions(host) });
+      await this.waitForTlsSession(client);
+      const size = await client.size(`/${remotePath}`);
+      if (!Number.isFinite(size) || size <= 0 || size > 512 * 1024 * 1024) throw new Error("Remote print file is empty or exceeds the 512 MiB inspection limit.");
+      await client.downloadTo(localPath, `/${remotePath}`);
+    } finally { client.close(); }
   }
 
   /**
@@ -1253,8 +1436,8 @@ export class BambuImplementation {
    *     [16..16+payloadSize] JPEG (FF D8 ... FF D9)
    *
    * Verified models per upstream docs: A1, A1 mini, P1S, P1P. X1/X1C/X1E
-   * and P2S use RTSP on port 322 instead. H2/H2S/H2D/H2C
-   * are not documented; we fail fast rather than guess at the protocol.
+   * and P2S use RTSP on port 322 instead. H2/H2S/H2D/H2C/X2D
+   * use the same RTSP path.
    *
    * Read-only; no confirm gate. Default 8s timeout for cold-start latency.
    */
@@ -1357,18 +1540,21 @@ export class BambuImplementation {
 
   /**
    * Pull a single JPEG frame from the printer's RTSP/RTSPS stream using
-   * ffmpeg. Used for X1, P2S, and H2 series.
+   * ffmpeg. Used for X1, P2S, H2-family printers, and X2D.
    *
    * URL pattern verified against HA bambulab's models.py example:
    *   rtsps://bblp:<access_code>@<host>:322/streaming/live/1
    *
    * ffmpeg invocation:
-   *   ffmpeg -rtsp_transport tcp -i <url> -frames:v 1 -f image2 -c:v mjpeg -y <out>
+   *   ffmpeg -tls_verify 0 -rtsp_transport tcp -i <url> -frames:v 1 -f image2 -c:v mjpeg -y <out>
    *
-   * -rtsp_transport tcp avoids UDP NAT/firewall issues. -frames:v 1
-   * makes ffmpeg exit as soon as one frame lands. -y overwrites the temp
-   * file. The Bambu printer presents a self-signed cert; ffmpeg's TLS
-   * layer accepts that by default (no host verification).
+   * -tls_verify 0 accepts the printer's self-signed certificate. This is
+   * consistent with the existing local-device TLS/FTPS paths, which do not
+   * have a public CA chain or hostname that ffmpeg can validate. The
+   * connection is still encrypted and remains scoped to the configured
+   * printer host. -rtsp_transport tcp avoids UDP NAT/firewall issues.
+   * -frames:v 1 makes ffmpeg exit as soon as one frame lands. -y overwrites
+   * the temp file.
    */
   private async fetchRtspCameraFrame(
     host: string,
@@ -1389,6 +1575,7 @@ export class BambuImplementation {
     // have to detect ffmpeg version. -rtsp_transport tcp avoids UDP NAT
     // headaches; -frames:v 1 makes ffmpeg exit on first frame.
     const args = [
+      "-tls_verify", "0",
       "-rtsp_transport", "tcp",
       "-i", url,
       "-frames:v", "1",
@@ -1617,7 +1804,7 @@ export class BambuImplementation {
         user: "bblp",
         password: token,
         secure: "implicit",
-        secureOptions: ftpsSecureOptions(),
+        secureOptions: ftpsSecureOptions(host),
       });
       await this.waitForTlsSession(client);
       const absoluteRemote = remotePath.startsWith("/") ? remotePath : `/${remotePath}`;
@@ -1647,7 +1834,7 @@ export class BambuImplementation {
         user: "bblp",
         password: token,
         secure: "implicit",
-        secureOptions: ftpsSecureOptions(),
+        secureOptions: ftpsSecureOptions(host),
       });
       // With TLS 1.3 the session ticket arrives asynchronously; basic-ftp calls
       // getSession() when opening the data channel and gets undefined if the
@@ -1656,6 +1843,11 @@ export class BambuImplementation {
       await this.waitForTlsSession(client);
       // Use absolute path to avoid CWD side-effects
       const absoluteRemote = remotePath.startsWith("/") ? remotePath : `/${remotePath}`;
+      const entries = await client.list(path.posix.dirname(absoluteRemote));
+      const destinationName = path.posix.basename(absoluteRemote).toLowerCase();
+      if (entries.some(entry => entry.name.toLowerCase() === destinationName)) {
+        throw new Error(`Refusing to overwrite existing printer file ${absoluteRemote}. Choose a new filename.`);
+      }
       const fileData = await fs.readFile(localPath);
       await client.uploadFrom(Readable.from(fileData), absoluteRemote);
     } finally {