mcp-3d-printer-server 1.2.5 → 1.2.11

package/src/printers/bambu.ts

@@ -1,21 +1,37 @@
 import { PrinterImplementation } from "../types.js";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-import JSZip from "jszip";
 import { Client as FTPClient } from "basic-ftp";
-import { BambuPrinter } from "bambu-js";
+import { BambuClient, PushAllCommand } from "bambu-node";
+import { MAX_PRINT_FILE_BYTES, readSafe3mfArchive } from "../safety/archive.js";
+import { inspectPrintFile, type PrintFileInspection } from "../safety/print-file.js";
+import { normalizeModel, validateTemperature } from "../safety/limits.js";
 import {
-  BambuClient,
-  GCodeFileCommand,
-  GCodeLineCommand,
-  PushAllCommand,
-  UpdateStateCommand,
-} from "bambu-node";
-
-interface BambuPrintOptionsInternal {
+  manualHeatingRequirements,
+  publishBambuCommand,
+  readFreshPrinterStatus,
+  validatePrinterState,
+  type PrinterStateRequirements,
+} from "../safety/printer-state.js";
+import {
+  cancelPendingPrinterOperations,
+  normalizedRemotePath,
+  uniquePrintName,
+  withPrinterOperation,
+  withPrintSnapshot,
+} from "../safety/artifact.js";
+import { requireHumanConfirmation, type ConfirmHardware } from "../safety/confirmation.js";
+import { installBambuNodeRejectionGuard } from "./bambu-node-guard.js";
+import { assertExpectedPeaks, validateExpectedPeaks, type ExpectedPeakTemperatures, type PrintSafetyOptions } from "../safety/expected-peaks.js";
+
+export interface BambuPrintOptionsInternal {
   projectName: string;
   filePath: string;
+  bambuModel?: string;
+  /** Requested nozzle diameters; compared with the sliced file when supplied. */
+  nozzleDiameters?: number[];
   useAMS?: boolean;
   plateIndex?: number;
   bedType?: string;
@@ -24,21 +40,62 @@ interface BambuPrintOptionsInternal {
   vibrationCalibration?: boolean;
   layerInspect?: boolean;
   timelapse?: boolean;
+  /** Positional mapping: project filament position -> absolute AMS tray (254 = external spool). */
   amsMapping?: number[];
   md5?: string;
+  expectedPeaks?: ExpectedPeakTemperatures;
 }
 
+export type BambuSafetyOptions = PrintSafetyOptions;
+
 interface ProjectFileMetadata {
   plateFileName: string;
   plateInternalPath: string;
   md5: string;
 }
 
+const COMMAND_SETTLE_MS = 300;
+/** HMS 0500-0500-0001-0007: firmware 01.08.05+ rejected an unsigned MQTT command. */
+const COMMAND_VERIFICATION_HMS = { attr: 0x05000500, code: 0x00010007 };
+const COMMAND_REJECTED_MESSAGE =
+  "The printer rejected the print command (HMS 0500-0500-0001-0007, \"MQTT command verification failed\"). " +
+  "Bambu firmware 01.08.05 and later only accept third-party LAN control with LAN Only Mode and Developer Mode " +
+  "enabled (Settings > WLAN on the printer). The printer keeps this error until it is dismissed on its screen, and the " +
+  "safety check refuses new prints while it is present. The checked file is on the printer's storage, but nothing is printing.";
+const DISPATCH_CANCELLED_MESSAGE =
+  "The print command was sent, then a stop or heater-off request cancelled it before the printer confirmed the start. " +
+  "Check get_printer_status.";
+
+/** How long to watch fresh reports after a print command (BAMBU_DISPATCH_CHECK_MS, 0 disables). */
+function dispatchCheckMs(): number {
+  const raw = process.env.BAMBU_DISPATCH_CHECK_MS?.trim();
+  const value = raw ? Number(raw) : 15_000;
+  return Number.isInteger(value) && value >= 0 && value <= 60_000 ? value : 15_000;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function validateTrayValue(value: unknown, label: string): void {
+  if (
+    !Number.isInteger(value) ||
+    (value as number) < -1 ||
+    ((value as number) > 15 && (value as number) < 128) ||
+    (value as number) > 254
+  ) {
+    throw new Error(
+      `${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${String(value)}`
+    );
+  }
+}
+
 class BambuClientStore {
   private printers: Map<string, BambuClient> = new Map();
   private initialConnectionPromises: Map<string, Promise<void>> = new Map();
 
   async getPrinter(host: string, serial: string, token: string): Promise<BambuClient> {
+    installBambuNodeRejectionGuard();
     const key = `${host}-${serial}`;
 
     if (this.printers.has(key)) {
@@ -110,57 +167,85 @@ class BambuClientStore {
 export class BambuImplementation extends PrinterImplementation {
   private printerStore: BambuClientStore;
 
-  constructor(apiClient: any) {
+  constructor(apiClient: any, private readonly confirm?: ConfirmHardware) {
     super(apiClient);
     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> {
+    await requireHumanConfirmation(this.confirm, message, "bambu", physicalCheck);
   }
 
-  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: PrintFileInspection): Promise<string | undefined> {
+    const finishedJob = this.finishedJobIdentity(status);
+    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." : ""),
+      finishedJob !== undefined
     );
+    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.");
     }
+  }
 
-    let selectedEntry = plateEntries.sort((a, b) => a.name.localeCompare(b.name))[0];
-
-    if (plateIndex !== undefined) {
-      const expectedEntryName = `Metadata/plate_${plateIndex + 1}.gcode`;
-      const matchedEntry = plateEntries.find(
-        (entry) => entry.name.toLowerCase() === expectedEntryName.toLowerCase()
-      );
+  private async getPrinter(host: string, serial: string, token: string): Promise<BambuClient> {
+    return this.printerStore.getPrinter(host, serial, token);
+  }
 
-      if (!matchedEntry) {
-        const available = plateEntries.map((entry) => entry.name).join(", ");
-        throw new Error(
-          `Requested plateIndex=${plateIndex} (${expectedEntryName}) not present in 3MF. Available: ${available}`
-        );
-      }
+  /** 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);
+  }
 
-      selectedEntry = matchedEntry;
+  /** Raw gcode_file printing cannot remap spools: verify the material already at the nozzle. */
+  private validateLoadedGcodeState(status: any, inspection: PrintFileInspection): 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: PrinterStateRequirements = {
+      ...inspection, useAMS: loaded.useAMS, amsMapping: mapping,
+      usedNozzleIndices: loaded.usedNozzleIndices, requireLoadedFilament: true,
+    };
+    validatePrinterState(status, requirements);
+    return requirements;
+  }
 
+  private async resolveProjectFileMetadata(
+    localThreeMfPath: string,
+    plateIndex: number | undefined,
+    inspectedPlatePath?: string
+  ): Promise<ProjectFileMetadata> {
+    const { zip } = await readSafe3mfArchive(localThreeMfPath);
+    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");
-    const md5 = createHash("md5").update(gcodeBuffer).digest("hex");
-
     return {
       plateFileName: path.posix.basename(selectedEntry.name),
       plateInternalPath: selectedEntry.name,
-      md5,
+      md5: createHash("md5").update(gcodeBuffer).digest("hex"),
     };
   }
 
@@ -210,7 +295,13 @@ export class BambuImplementation extends PrinterImplementation {
       };
     } catch (error) {
       console.error(`Failed to get Bambu status for ${serial}:`, error);
-      return { status: "error", connected: false, error: (error as Error).message };
+      const message = (error as Error).message;
+      return {
+        status: "error", connected: false, error: message,
+        ...(/not authori[sz]ed|\b530\b|login incorrect/i.test(message)
+          ? { hint: "The printer rejected its LAN access code. Read the current Access Code on the printer (Settings > Network/WLAN), update BAMBU_TOKEN, and check BAMBU_SERIAL." }
+          : {}),
+      };
     }
   }
 
@@ -220,41 +311,86 @@ export class BambuImplementation extends PrinterImplementation {
     token: string,
     options: BambuPrintOptionsInternal
   ): Promise<any> {
+    if (!normalizeModel(options.bambuModel)) {
+      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.");
     }
+    validateExpectedPeaks(options.expectedPeaks);
+    return withPrinterOperation(host, serial, (assertActive) => withPrintSnapshot(options.filePath, (filePath) =>
+      this.print3mfPrepared(host, serial, token, { ...options, filePath }, assertActive)
+    ));
+  }
 
-    const projectMetadata = await this.resolveProjectFileMetadata(
-      options.filePath,
-      options.plateIndex
-    );
-
-    const remoteFileName = path.basename(options.filePath);
-    const remoteProjectPath = `cache/${remoteFileName}`;
-
-    // Upload via basic-ftp directly (bypasses bambu-js double-path bug)
-    await this.ftpUpload(host, token, options.filePath, `/cache/${remoteFileName}`);
+  private async print3mfPrepared(
+    host: string,
+    serial: string,
+    token: string,
+    options: BambuPrintOptionsInternal,
+    assertActive: () => void
+  ): Promise<any> {
+    const model = normalizeModel(options.bambuModel)!;
+    // Inspect the private snapshot: these exact bytes are uploaded below.
+    const inspection = await inspectPrintFile(options.filePath, {
+      model, nozzleDiameters: options.nozzleDiameters, plateIndex: options.plateIndex ?? 0, bedType: options.bedType,
+    });
+    assertExpectedPeaks(options.expectedPeaks, { nozzle: inspection.maxNozzleTemperature, bed: inspection.maxBedTemperature });
+    const projectMetadata = await this.resolveProjectFileMetadata(options.filePath, options.plateIndex, inspection.plateInternalPath);
+    const md5 = projectMetadata.md5;
+    if (options.md5 !== undefined && options.md5 !== md5) {
+      throw new Error("Provided checksum does not match the inspected plate G-code.");
+    }
 
-    // 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;
-
-    // Build AMS mapping per OpenBambuAPI spec: 5-element array
-    // [-1,-1,-1,-1,0] means slot 0 only; pad unused slots with -1
-    let amsMapping: number[];
-    if (options.amsMapping && options.amsMapping.length > 0) {
-      amsMapping = Array.from({ length: 5 }, (_, i) =>
-        i < options.amsMapping!.length ? options.amsMapping![i] : -1
-      );
+    for (const value of options.amsMapping ?? []) validateTrayValue(value, "ams_mapping");
+    const useAMS = options.useAMS !== false;
+    let checkedMapping: number[];
+    if (useAMS) {
+      checkedMapping = (options.amsMapping ?? []).slice();
     } else {
-      amsMapping = [-1, -1, -1, -1, 0];
+      checkedMapping = Array<number>(inspection.materials.length).fill(-1);
+      inspection.usedFilamentPositions.forEach((position) => { checkedMapping[position] = 254; });
     }
+    for (const position of inspection.usedFilamentPositions) {
+      if (checkedMapping[position] === undefined || checkedMapping[position] < 0) {
+        throw new Error(
+          `Missing physical filament mapping for project filament ${position}. ` +
+          "Pass ams_mapping with a tray for every used project filament, or use_ams:false for the external spool."
+        );
+      }
+    }
+
+    // Wire mapping: position = project filament, value = absolute tray. Never
+    // truncate a checked mapping; pad to the historical five entries.
+    const amsMapping = options.amsMapping && options.amsMapping.length > 0
+      ? Array.from({ length: Math.max(5, options.amsMapping.length) }, (_, i) =>
+          i < options.amsMapping!.length ? options.amsMapping![i] : -1)
+      : [-1, -1, -1, -1, 0];
+
+    const requirements: PrinterStateRequirements = { ...inspection, amsMapping: checkedMapping, useAMS };
+    const initialStatus = await this.getSafetyStatus(host, serial, token);
+    validatePrinterState(initialStatus, requirements);
+    const bedClearance = await this.confirmPrintPreflight(serial, initialStatus, inspection);
+    // Recheck after the human response: the printer may have changed meanwhile.
+    const confirmedStatus = await this.getSafetyStatus(host, serial, token);
+    validatePrinterState(confirmedStatus, requirements);
+    this.assertBedClearance(confirmedStatus, bedClearance);
+    assertActive();
+
+    const remoteFileName = uniquePrintName(options.filePath);
+    const remoteProjectPath = `cache/${remoteFileName}`;
+    await this.ftpUpload(host, token, options.filePath, `/${remoteProjectPath}`);
+    // Uploads can be long. Recheck current state before the command is dispatched.
+    const dispatchStatus = await this.getSafetyStatus(host, serial, token);
+    validatePrinterState(dispatchStatus, requirements);
+    this.assertBedClearance(dispatchStatus, bedClearance);
+    const printer = await this.getPrinter(host, serial, token);
+    assertActive();
 
     const projectFileCmd = {
       print: {
         command: "project_file",
-        param: `Metadata/${projectMetadata.plateFileName}`,
+        param: projectMetadata.plateInternalPath,
         url: `file:///sdcard/${remoteProjectPath}`,
         subtask_name: options.projectName,
         md5,
@@ -264,7 +400,7 @@ export class BambuImplementation extends PrinterImplementation {
         bed_leveling: options.bedLeveling ?? true,
         bed_type: options.bedType || "textured_plate",
         timelapse: options.timelapse ?? false,
-        use_ams: options.useAMS !== false,
+        use_ams: useAMS,
         ams_mapping: amsMapping,
         profile_id: "0",
         project_id: "0",
@@ -274,26 +410,94 @@ export class BambuImplementation extends PrinterImplementation {
       },
     };
 
+    const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
     await printer.publish(projectFileCmd);
-    await new Promise((resolve) => setTimeout(resolve, 300));
+    await sleep(COMMAND_SETTLE_MS);
+    const dispatch = await watcher.settled();
 
     return {
       status: "success",
-      message: `Uploaded and started 3MF print: ${options.projectName}`,
+      dispatch,
+      message: dispatch === "started"
+        ? `The printer accepted and started the checked 3MF print: ${options.projectName}`
+        : `Uploaded the checked 3MF and sent the print command for ${options.projectName}; the printer has not reported starting yet. ` +
+          "Check get_printer_status before assuming it is printing.",
       remoteProjectPath,
       plateFile: projectMetadata.plateFileName,
       platePath: projectMetadata.plateInternalPath,
       md5,
+      sha256: inspection.sha256,
       amsMapping,
+      peakTemperatures: {
+        nozzle: inspection.maxNozzleTemperature,
+        bed: inspection.maxBedTemperature,
+        chamber: inspection.maxChamberTemperature,
+      },
+    };
+  }
+
+  /**
+   * A published print command is not proof the printer took it. Listen to the
+   * reports the printer pushes anyway (no extra pushall polling on weak P1
+   * boards): a new command-verification HMS means the firmware refused the
+   * command; PREPARE/SLICING/RUNNING means it started. Attach before publishing.
+   */
+  private watchDispatch(printer: any, host: string, serial: string, token: string, before: any, assertActive: () => void): { settled: () => Promise<"started" | "unconfirmed"> } {
+    const windowMs = dispatchCheckMs();
+    const stillActive = () => { try { assertActive(); } catch { throw new Error(DISPATCH_CANCELLED_MESSAGE); } };
+    if (windowMs === 0 || typeof printer?.on !== "function") return { settled: async () => { stillActive(); return "unconfirmed"; } };
+    const key = (entry: any) => `${Number(entry?.attr)}:${Number(entry?.code)}:${entry?.timestamp ?? ""}`;
+    const known = new Set((Array.isArray(before?.raw?.hms) ? before.raw.hms : []).map(key));
+    const judge = (report: any): "started" | "rejected" | undefined => {
+      const hms = Array.isArray(report?.hms) ? report.hms : [];
+      if (hms.some((entry: any) => Number(entry?.attr) === COMMAND_VERIFICATION_HMS.attr &&
+          Number(entry?.code) === COMMAND_VERIFICATION_HMS.code && !known.has(key(entry)))) return "rejected";
+      if (["PREPARE", "SLICING", "RUNNING"].includes(String(report?.gcode_state ?? "").toUpperCase())) return "started";
+      return undefined;
+    };
+    let resolveOutcome!: (value: "started" | "rejected" | "cancelled" | undefined) => void;
+    const outcome = new Promise<"started" | "rejected" | "cancelled" | undefined>((resolve) => { resolveOutcome = resolve; });
+    // cancel_print bumps a local generation; notice it without touching the printer.
+    const cancelCheck = setInterval(() => { try { assertActive(); } catch { resolveOutcome("cancelled"); } }, 500);
+    const onRaw = (topic: string, payload: Buffer) => {
+      if (topic !== `device/${serial}/report`) return;
+      let parsed: any;
+      try { parsed = JSON.parse(payload.toString()); } catch { return; }
+      const verdict = judge(parsed?.print);
+      if (verdict) resolveOutcome(verdict);
+    };
+    printer.on("rawMessage", onRaw);
+    const timer = setTimeout(() => resolveOutcome(undefined), windowMs);
+    return {
+      settled: async () => {
+        let verdict: "started" | "rejected" | "cancelled" | undefined;
+        try {
+          verdict = await outcome;
+        } finally {
+          clearTimeout(timer);
+          clearInterval(cancelCheck);
+          printer.off?.("rawMessage", onRaw);
+        }
+        if (verdict === "cancelled") throw new Error(DISPATCH_CANCELLED_MESSAGE);
+        // Nothing pushed during the window: take one full report, not a polling loop.
+        if (verdict === undefined) {
+          try { verdict = judge((await this.getSafetyStatus(host, serial, token))?.raw); } catch { /* stays unconfirmed */ }
+        }
+        if (verdict === "rejected") throw new Error(COMMAND_REJECTED_MESSAGE);
+        stillActive();
+        return verdict ?? "unconfirmed";
+      },
     };
   }
 
+  /** Stop is never gated or queued behind pending checked operations. */
   async cancelJob(host: string, port: string, apiKey: string): Promise<any> {
     const [serial, token] = this.extractBambuCredentials(apiKey);
+    cancelPendingPrinterOperations(host, serial);
     const printer = await this.getPrinter(host, serial, token);
 
     try {
-      await printer.executeCommand(new UpdateStateCommand({ state: "stop" }));
+      await publishBambuCommand(printer, "print", "stop");
       return { status: "success", message: "Cancel command sent successfully." };
     } catch (error) {
       throw new Error(`Failed to cancel print: ${(error as Error).message}`);
@@ -305,57 +509,79 @@ export class BambuImplementation extends PrinterImplementation {
     port: string,
     apiKey: string,
     component: string,
-    temperature: number
+    temperature: unknown,
+    options: BambuSafetyOptions = {}
   ) {
-    const [serial, token] = this.extractBambuCredentials(apiKey);
-    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 normalizedComponent = String(component).toLowerCase();
+    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 printer.executeCommand(new GCodeLineCommand({ gcodes: [gcode] }));
-    return {
-      status: "success",
-      message: `Temperature command sent for ${normalizedComponent}.`,
-      command: gcode,
+    // Validate before any credential use or connection.
+    if (typeof temperature !== "number" || !Number.isFinite(temperature) || temperature < 0) {
+      throw new Error("Temperature must be a finite, non-negative number in °C.");
+    }
+    const [serial, token] = this.extractBambuCredentials(apiKey);
+    const model = normalizeModel(options.bambuModel);
+    const material = options.material?.trim();
+    const nozzleDiameter = options.nozzleDiameter ?? 0.4;
+    if (temperature > 0 && !model) throw new Error("bambu_model is required before heating.");
+    if (temperature > 0 && heater === "nozzle" && !material) {
+      throw new Error("Declare material before nozzle heating, including non-RFID external spools.");
+    }
+    if (temperature > 0 && heater === "nozzle" && (!Number.isFinite(nozzleDiameter) || nozzleDiameter <= 0)) {
+      throw new Error("nozzle_diameter must be a positive number for nozzle heating.");
+    }
+    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) => {
+      if (targetTemperature > 0) {
+        const validateHeatingStatus = (current: any) => validatePrinterState(current, heater === "nozzle"
+          ? manualHeatingRequirements(current, model!, nozzleDiameter, material!)
+          : { model: model!, nozzleDiameters: [] });
+        validateHeatingStatus(await this.getSafetyStatus(host, serial, token));
+        await this.confirmHardwareAction(
+          `Heat ${heater} on ${model!.toUpperCase()} (${serial}) to ${targetTemperature}°C?` +
+          (material && heater === "nozzle" ? ` Declared material: ${material}. Confirm the physical spool label.` : "")
+        );
+        assertActive();
+        validateHeatingStatus(await this.getSafetyStatus(host, serial, token));
+      }
+      const printer = await this.getPrinter(host, serial, token);
+      assertActive();
+      await publishBambuCommand(printer, "print", "gcode_line", { param: `${gcode}\n` });
+      return { status: "success", message: `Temperature command sent for ${normalizedComponent}.`, command: gcode };
     };
+    if (targetTemperature === 0) {
+      // Heater-off is never gated and cancels pending checked operations.
+      cancelPendingPrinterOperations(host, serial);
+      return send(() => undefined);
+    }
+    return withPrinterOperation(host, serial, send);
   }
 
   async getFiles(host: string, port: string, apiKey: string) {
-    const [serial, token] = this.extractBambuCredentials(apiKey);
-    const printer = new BambuPrinter(host, serial, token);
+    const [, token] = this.extractBambuCredentials(apiKey);
     const directories = ["cache", "timelapse", "logs"];
     const filesByDirectory: Record<string, string[]> = {};
-
-    await printer.manipulateFiles(async (context) => {
+    // bambu-js swallowed listing failures as empty folders. List read-only over
+    // the shared FTPS options with absolute paths and surface real failures.
+    const client = new FTPClient(15_000);
+    try {
+      await client.access(this.ftpsOptions(host, token));
+      const root = await client.list("/");
       for (const directory of directories) {
-        try {
-          filesByDirectory[directory] = await context.readDir(directory);
-        } catch {
-          filesByDirectory[directory] = [];
-        }
+        const present = root.some((entry) => entry.name === directory && (entry.isDirectory || entry.isSymbolicLink));
+        filesByDirectory[directory] = present ? (await client.list(`/${directory}`)).map((entry) => entry.name) : [];
       }
-    });
+    } finally {
+      client.close();
+    }
 
     const files = Object.entries(filesByDirectory).flatMap(([directory, names]) =>
       names.map((name) => `${directory}/${name}`)
@@ -368,8 +594,7 @@ export class BambuImplementation extends PrinterImplementation {
   }
 
   async getFile(host: string, port: string, apiKey: string, filename: string) {
-    const [serial, token] = this.extractBambuCredentials(apiKey);
-    const printer = new BambuPrinter(host, serial, token);
+    const [, token] = this.extractBambuCredentials(apiKey);
 
     const normalized = filename.replace(/^\/+/, "");
     const directory = path.posix.dirname(normalized) === "." ? "cache" : path.posix.dirname(normalized);
@@ -377,10 +602,14 @@ export class BambuImplementation extends PrinterImplementation {
 
     let exists = false;
 
-    await printer.manipulateFiles(async (context) => {
-      const entries = await context.readDir(directory);
-      exists = entries.includes(baseName);
-    });
+    const client = new FTPClient(15_000);
+    try {
+      await client.access(this.ftpsOptions(host, token));
+      const entries = await client.list(`/${directory}`);
+      exists = entries.some(entry => entry.name === baseName);
+    } finally {
+      client.close();
+    }
 
     return {
       name: `${directory}/${baseName}`,
@@ -394,65 +623,143 @@ export class BambuImplementation extends PrinterImplementation {
     apiKey: string,
     filePath: string,
     filename: string,
-    print: boolean
+    print: boolean,
+    options: BambuSafetyOptions = {}
   ) {
     await fs.access(filePath);
 
     const [serial, token] = this.extractBambuCredentials(apiKey);
+    const remotePath = normalizedRemotePath(filename);
 
-    const normalizedFileName = filename.replace(/^\/+/, "");
-    const remotePath = normalizedFileName.includes("/")
-      ? normalizedFileName
-      : `cache/${normalizedFileName}`;
+    if (!print) {
+      // Use direct FTP upload (bypasses bambu-js double-path bug)
+      await this.ftpUpload(host, token, filePath, `/${remotePath}`);
+      return {
+        status: "success",
+        uploaded: true,
+        remotePath,
+        printRequested: false,
+      };
+    }
 
-    // Use direct FTP upload (bypasses bambu-js double-path bug)
-    await this.ftpUpload(host, token, filePath, `/${remotePath}`);
+    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.");
+    }
+    const model = normalizeModel(options.bambuModel);
+    if (!model) throw new Error("A supported bambuModel is required before printing.");
+    validateExpectedPeaks(options.expectedPeaks);
+    return withPrinterOperation(host, serial, (assertActive) => withPrintSnapshot(filePath, (snapshot) =>
+      this.printRawPrepared(host, serial, token, snapshot, remotePath, model, assertActive, options.expectedPeaks)
+    ));
+  }
 
-    const response: Record<string, unknown> = {
+  private async printRawPrepared(
+    host: string,
+    serial: string,
+    token: string,
+    filePath: string,
+    filename: string,
+    model: string,
+    assertActive: () => void,
+    expectedPeaks?: ExpectedPeakTemperatures
+  ) {
+    const inspection = await inspectPrintFile(filePath, { model });
+    assertExpectedPeaks(expectedPeaks, { nozzle: inspection.maxNozzleTemperature, bed: inspection.maxBedTemperature });
+    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);
+    this.validateLoadedGcodeState(initialStatus, inspection);
+    const bedClearance = await this.confirmPrintPreflight(serial, initialStatus, inspection);
+    const confirmedStatus = await this.getSafetyStatus(host, serial, token);
+    this.validateLoadedGcodeState(confirmedStatus, inspection);
+    this.assertBedClearance(confirmedStatus, bedClearance);
+    assertActive();
+    // Start a uniquely named copy of the inspected bytes, never a name that can change.
+    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);
+    this.validateLoadedGcodeState(dispatchStatus, inspection);
+    this.assertBedClearance(dispatchStatus, bedClearance);
+    const printer = await this.getPrinter(host, serial, token);
+    assertActive();
+    const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
+    await publishBambuCommand(printer, "print", "gcode_file", { param: remotePath });
+    const dispatch = await watcher.settled();
+    return {
       status: "success",
       uploaded: true,
+      printRequested: true,
+      dispatch,
       remotePath,
-      printRequested: print,
+      sha256: inspection.sha256,
+      message: dispatch === "started"
+        ? `The printer accepted and started ${remotePath}.`
+        : `Sent the print command for ${remotePath}; the printer has not reported starting yet. Check get_printer_status before assuming it is printing.`,
     };
-
-    if (print) {
-      if (remotePath.toLowerCase().endsWith(".gcode")) {
-        response.startResult = await this.startJob(host, port, apiKey, remotePath);
-      } 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."
-        );
-      }
-    }
-
-    return response;
   }
 
-  async startJob(host: string, port: string, apiKey: string, filename: string) {
+  async startJob(host: string, port: string, apiKey: string, filename: string, options: BambuSafetyOptions = {}) {
     if (filename.toLowerCase().endsWith(".3mf")) {
       throw new Error("Use print_3mf for .3mf project files.");
     }
 
     const [serial, token] = this.extractBambuCredentials(apiKey);
-    const printer = await this.getPrinter(host, serial, token);
-
-    const normalizedFileName = filename.replace(/^\/+/, "");
-    const remoteFile = normalizedFileName.includes("/")
-      ? normalizedFileName
-      : `cache/${normalizedFileName}`;
+    const model = normalizeModel(options.bambuModel);
+    if (!model) 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.");
+    }
+    validateExpectedPeaks(options.expectedPeaks);
 
-    await printer.executeCommand(new GCodeFileCommand({ fileName: remoteFile }));
+    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, model, assertActive, options.expectedPeaks)
+        );
+      } finally {
+        await fs.rm(directory, { recursive: true, force: true });
+      }
+    });
+  }
 
+  private ftpsOptions(host: string, token: string) {
     return {
-      status: "success",
-      message: `Start command sent for ${remoteFile}.`,
-      file: remoteFile,
+      host,
+      port: 990,
+      user: "bblp",
+      password: token,
+      secure: "implicit" as const,
+      // basic-ftp passes getSession() to the data socket. Keep both channels
+      // on TLS 1.2, where that session is available at handshake completion;
+      // TLS 1.3 tickets arrive later and can break Bambu's required reuse.
+      // Node also binds resumable sessions to the host identity. basic-ftp
+      // retains these options for its wrapped data socket, so explicitly keep
+      // the same host there (nodejs/node#64402 affects implicit FTPS).
+      secureOptions: { host, rejectUnauthorized: false, minVersion: "TLSv1.2" as const, maxVersion: "TLSv1.2" as const },
     };
   }
 
+  private async ftpDownload(host: string, token: string, remotePath: string, localPath: string): Promise<void> {
+    const client = new FTPClient(15_000);
+    try {
+      await client.access(this.ftpsOptions(host, token));
+      const size = await client.size(`/${remotePath}`);
+      if (!Number.isFinite(size) || size <= 0 || size > MAX_PRINT_FILE_BYTES) {
+        throw new Error("Remote print file is empty or exceeds the 256 MiB inspection limit.");
+      }
+      await client.downloadTo(localPath, `/${remotePath}`);
+    } finally {
+      client.close();
+    }
+  }
+
   /**
    * Upload a file to the printer via FTP using basic-ftp directly.
    * Bypasses bambu-js's sendFile which has a double-path bug (ensureDir CDs
@@ -467,14 +774,7 @@ export class BambuImplementation extends PrinterImplementation {
   ): Promise<void> {
     const client = new FTPClient(15_000);
     try {
-      await client.access({
-        host,
-        port: 990,
-        user: "bblp",
-        password: token,
-        secure: "implicit",
-        secureOptions: { rejectUnauthorized: false },
-      });
+      await client.access(this.ftpsOptions(host, token));
       // Use absolute path to avoid CWD side-effects
       const absoluteRemote = remotePath.startsWith("/") ? remotePath : `/${remotePath}`;
       const remoteDir = path.posix.dirname(absoluteRemote);