mcp-3d-printer-server 1.2.5 → 1.2.11

package/dist/printers/bambu.js

@@ -1,17 +1,51 @@
 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, GCodeFileCommand, GCodeLineCommand, PushAllCommand, UpdateStateCommand, } from "bambu-node";
+import { BambuClient, PushAllCommand } from "bambu-node";
+import { MAX_PRINT_FILE_BYTES, readSafe3mfArchive } from "../safety/archive.js";
+import { inspectPrintFile } from "../safety/print-file.js";
+import { normalizeModel, validateTemperature } from "../safety/limits.js";
+import { manualHeatingRequirements, publishBambuCommand, readFreshPrinterStatus, validatePrinterState, } from "../safety/printer-state.js";
+import { cancelPendingPrinterOperations, normalizedRemotePath, uniquePrintName, withPrinterOperation, withPrintSnapshot, } from "../safety/artifact.js";
+import { requireHumanConfirmation } from "../safety/confirmation.js";
+import { installBambuNodeRejectionGuard } from "./bambu-node-guard.js";
+import { assertExpectedPeaks, validateExpectedPeaks } from "../safety/expected-peaks.js";
+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() {
+    const raw = process.env.BAMBU_DISPATCH_CHECK_MS?.trim();
+    const value = raw ? Number(raw) : 15000;
+    return Number.isInteger(value) && value >= 0 && value <= 60000 ? value : 15000;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function validateTrayValue(value, label) {
+    if (!Number.isInteger(value) ||
+        value < -1 ||
+        (value > 15 && value < 128) ||
+        value > 254) {
+        throw new Error(`${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${String(value)}`);
+    }
+}
 class BambuClientStore {
     constructor() {
         this.printers = new Map();
         this.initialConnectionPromises = new Map();
     }
     async getPrinter(host, serial, token) {
+        installBambuNodeRejectionGuard();
         const key = `${host}-${serial}`;
         if (this.printers.has(key)) {
             return this.printers.get(key);
@@ -69,36 +103,71 @@ class BambuClientStore {
     }
 }
 export class BambuImplementation extends PrinterImplementation {
-    constructor(apiClient) {
+    constructor(apiClient, confirm) {
         super(apiClient);
+        this.confirm = confirm;
         this.printerStore = new BambuClientStore();
     }
+    async confirmHardwareAction(message, physicalCheck = false) {
+        await requireHumanConfirmation(this.confirm, message, "bambu", physicalCheck);
+    }
+    finishedJobIdentity(status) {
+        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;
+    }
+    async confirmPrintPreflight(serial, status, inspection) {
+        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;
+    }
+    assertBedClearance(status, confirmedFinishedJob) {
+        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.");
+        }
+    }
     async getPrinter(host, serial, token) {
         return this.printerStore.getPrinter(host, serial, token);
     }
-    async resolveProjectFileMetadata(localThreeMfPath, plateIndex) {
-        const archive = await fs.readFile(localThreeMfPath);
-        const zip = await JSZip.loadAsync(archive);
-        const plateEntries = Object.values(zip.files).filter((entry) => !entry.dir && /^Metadata\/plate_\d+\.gcode$/i.test(entry.name));
-        if (plateEntries.length === 0) {
-            throw new Error("3MF does not contain any Metadata/plate_<n>.gcode entries. Re-slice and export a printable 3MF.");
-        }
-        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());
-            if (!matchedEntry) {
-                const available = plateEntries.map((entry) => entry.name).join(", ");
-                throw new Error(`Requested plateIndex=${plateIndex} (${expectedEntryName}) not present in 3MF. Available: ${available}`);
-            }
-            selectedEntry = matchedEntry;
+    /** Safety reads never use the display cache or configured-serial model inference. */
+    async getSafetyStatus(host, serial, token) {
+        return readFreshPrinterStatus(await this.getPrinter(host, serial, token), serial);
+    }
+    /** Raw gcode_file printing cannot remap spools: verify the material already at the nozzle. */
+    validateLoadedGcodeState(status, inspection) {
+        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(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;
+    }
+    async resolveProjectFileMetadata(localThreeMfPath, plateIndex, inspectedPlatePath) {
+        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"),
         };
     }
     async getStatus(host, port, apiKey) {
@@ -144,35 +213,81 @@ export class BambuImplementation extends PrinterImplementation {
         }
         catch (error) {
             console.error(`Failed to get Bambu status for ${serial}:`, error);
-            return { status: "error", connected: false, error: error.message };
+            const message = 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." }
+                    : {}),
+            };
         }
     }
     async print3mf(host, serial, token, options) {
+        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.");
         }
-        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}`);
-        // 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;
-        if (options.amsMapping && options.amsMapping.length > 0) {
-            amsMapping = Array.from({ length: 5 }, (_, i) => i < options.amsMapping.length ? options.amsMapping[i] : -1);
+        validateExpectedPeaks(options.expectedPeaks);
+        return withPrinterOperation(host, serial, (assertActive) => withPrintSnapshot(options.filePath, (filePath) => this.print3mfPrepared(host, serial, token, { ...options, filePath }, assertActive)));
+    }
+    async print3mfPrepared(host, serial, token, options, assertActive) {
+        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.");
+        }
+        for (const value of options.amsMapping ?? [])
+            validateTrayValue(value, "ams_mapping");
+        const useAMS = options.useAMS !== false;
+        let checkedMapping;
+        if (useAMS) {
+            checkedMapping = (options.amsMapping ?? []).slice();
         }
         else {
-            amsMapping = [-1, -1, -1, -1, 0];
+            checkedMapping = Array(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 = { ...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,
@@ -182,7 +297,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",
@@ -191,72 +306,190 @@ export class BambuImplementation extends PrinterImplementation {
                 task_id: "0",
             },
         };
+        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.
+     */
+    watchDispatch(printer, host, serial, token, before, assertActive) {
+        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) => `${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) => {
+            const hms = Array.isArray(report?.hms) ? report.hms : [];
+            if (hms.some((entry) => 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;
+        const outcome = new Promise((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, payload) => {
+            if (topic !== `device/${serial}/report`)
+                return;
+            let parsed;
+            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;
+                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, port, apiKey) {
         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.message}`);
         }
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
-        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.");
+    async setTemperature(host, port, apiKey, component, temperature, options = {}) {
+        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.`);
         }
-        let gcode;
-        if (normalizedComponent === "bed") {
-            gcode = `M140 S${targetTemperature}`;
+        // 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.");
         }
-        else if (normalizedComponent === "extruder" ||
-            normalizedComponent === "nozzle" ||
-            normalizedComponent === "tool" ||
-            normalizedComponent === "tool0") {
-            gcode = `M104 S${targetTemperature}`;
+        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.");
         }
-        else {
-            throw new Error(`Unsupported temperature component: ${component}. Use one of: bed, nozzle, extruder.`);
+        if (temperature > 0 && heater === "nozzle" && (!Number.isFinite(nozzleDiameter) || nozzleDiameter <= 0)) {
+            throw new Error("nozzle_diameter must be a positive number for nozzle heating.");
         }
-        await printer.executeCommand(new GCodeLineCommand({ gcodes: [gcode] }));
-        return {
-            status: "success",
-            message: `Temperature command sent for ${normalizedComponent}.`,
-            command: gcode,
+        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) => {
+            if (targetTemperature > 0) {
+                const validateHeatingStatus = (current) => 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, port, apiKey) {
-        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 = {};
-        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(15000);
+        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}`));
         return {
             files,
@@ -264,67 +497,141 @@ export class BambuImplementation extends PrinterImplementation {
         };
     }
     async getFile(host, port, apiKey, filename) {
-        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);
         const baseName = path.posix.basename(normalized);
         let exists = false;
-        await printer.manipulateFiles(async (context) => {
-            const entries = await context.readDir(directory);
-            exists = entries.includes(baseName);
-        });
+        const client = new FTPClient(15000);
+        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}`,
             exists,
         };
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    async uploadFile(host, port, apiKey, filePath, filename, print, options = {}) {
         await fs.access(filePath);
         const [serial, token] = this.extractBambuCredentials(apiKey);
-        const normalizedFileName = filename.replace(/^\/+/, "");
-        const remotePath = normalizedFileName.includes("/")
-            ? normalizedFileName
-            : `cache/${normalizedFileName}`;
-        // Use direct FTP upload (bypasses bambu-js double-path bug)
+        const remotePath = normalizedRemotePath(filename);
+        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,
+            };
+        }
+        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)));
+    }
+    async printRawPrepared(host, serial, token, filePath, filename, model, assertActive, expectedPeaks) {
+        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 response = {
+        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, port, apiKey, filename) {
+    async startJob(host, port, apiKey, filename, options = {}) {
         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}`;
-        await printer.executeCommand(new GCodeFileCommand({ fileName: remoteFile }));
+        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);
+        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 });
+            }
+        });
+    }
+    ftpsOptions(host, token) {
         return {
-            status: "success",
-            message: `Start command sent for ${remoteFile}.`,
-            file: remoteFile,
+            host,
+            port: 990,
+            user: "bblp",
+            password: token,
+            secure: "implicit",
+            // 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", maxVersion: "TLSv1.2" },
         };
     }
+    async ftpDownload(host, token, remotePath, localPath) {
+        const client = new FTPClient(15000);
+        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
@@ -334,14 +641,7 @@ export class BambuImplementation extends PrinterImplementation {
     async ftpUpload(host, token, localPath, remotePath) {
         const client = new FTPClient(15000);
         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);