@tikoci/quickchr 0.4.8 → 0.5.1

package/src/lib/quickchr.ts

@@ -20,14 +20,15 @@ import type {
 	NetworkTopologyEntry,
 	PlatformInfo,
 	PortMapping,
+	ProvisioningStep,
 	QgaCommand,
 	ServiceEndpoint,
 	SnapshotInfo,
 	SshServiceEndpoint,
 	StartOptions,
 } from "./types.ts";
-import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION, HOST_GATEWAY_IP } from "./types.ts";
-import { assertValidResourceName, assertPathSafeName } from "./names.ts";
+import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION, HOST_GATEWAY_IP, PORTS_PER_BLOCK } from "./types.ts";
+import { assertValidResourceName, assertPathSafeName, shellQuote } from "./names.ts";
 import packageJson from "../../package.json";
 import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
@@ -35,6 +36,9 @@ import {
 	isValidVersion,
 	generateMachineName,
 	assertProvisioningSupportedVersion,
+	assertRestAvailable,
+	assertRouterOs6Arch,
+	isRouterOs6,
 	PROVISIONING_FEATURE_LABEL,
 } from "./versions.ts";
 import { buildPortMappings, findAvailablePortBlock, resolveStartNetworks, resolveAllNetworks, assignMacs, buildHostfwdString, hasUserModeNetwork, validateExplicitExtraPorts, describeSocketTransport } from "./network.ts";
@@ -58,19 +62,20 @@ import {
 	getDataDir,
 	appendBootLog,
 } from "./state.ts";
-import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
+import { ensureCachedImage, listCachedImages } from "./images.ts";
 import { autoPruneIfOverCap } from "./cache.ts";
 import { resolveSetting } from "./settings.ts";
-import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
-import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
+import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, waitForApiReady, readinessProbeFor, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
+import { bootDiskFormatOf, bootDiskPath, cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, writeBootDisk, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
 import { monitorCommand, serialStreams, qgaCommand, channelEndpoint, channelFileExists, channelPath } from "./channels.ts";
-import { captureBootFailure, newBootProbeStats, type BootFailureReport, type BootProbeStats, type FailureTrigger } from "./diagnostics.ts";
+import { captureBootFailure, newBootProbeStats, preserveOnFailure, type BootFailureReport, type BootProbeStats, type FailureTrigger } from "./diagnostics.ts";
 import { installPackages, installAllPackages, downloadAndListPackages, downloadPackages, findPackageFile, uploadPackages } from "./packages.ts";
 import { provision } from "./provision.ts";
 import { renewLicense, getLicenseInfo } from "./license.ts";
 import { resolveAuth, resolveCreds } from "./auth.ts";
 import { scpPush, scpPull } from "./scp.ts";
 import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, getInstanceCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
+import { DEFAULT_SHUTDOWN_TIMEOUT_MS, shutdownGuest, validateShutdownTimeout } from "./shutdown.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
 import { consoleExec, CONSOLE_LOGIN_COST_MS } from "./console.ts";
@@ -78,6 +83,8 @@ import { restRequest, restGet, restPost } from "./rest.ts";
 import { getNamedSocket, joinNamedSocket, removeSocketMember, getSocketSlot } from "./socket-registry.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import {
+	describeDeviceModeChange,
+	FACTORY_AUTH_HEADER,
 	formatDeviceModeSelection,
 	readDeviceMode,
 	resolveDeviceModeOptions,
@@ -86,11 +93,20 @@ import {
 	verifyDeviceMode,
 	waitForDeviceModeApi,
 } from "./device-mode.ts";
+import {
+	appliedDeviceModeRecord,
+	assertProvisioningWindow,
+	hasProvisioningRequest,
+	isProvisioningWindowOpen,
+	pendingProvisioningFor,
+} from "./provisioning-window.ts";
 import type { LicenseOptions } from "./types.ts";
 import type { GuestExec } from "./guest-snapshot.ts";
 import { toChrPorts } from "./network.ts";
-import { assertSufficientQuickchrStorage, formatQuickchrUsage, getQuickchrStorageReport } from "./storage.ts";
-import { existsSync, rmSync, copyFileSync, writeFileSync, unlinkSync, openSync, writeSync, closeSync, readFileSync } from "node:fs";
+import { admitStorage, estimateMachineCreation, formatQuickchrUsage, getQuickchrStorageReport } from "./storage.ts";
+import { pinCacheEntries } from "./storage-lease.ts";
+import { existsSync, rmSync } from "node:fs";
+import { acquireLock, acquireLockNow, allocationLockPath, legacyMachineLockPath, listReservations, machineLockPath, type HeldLock, type LockOperation } from "./lock.ts";
 import { join } from "node:path";
 
 // --- Architecture-aware defaults ---
@@ -140,6 +156,16 @@ function normalizeStartOptions(opts: StartOptions): StartOptions {
 	return opts;
 }
 
+/** `version` and `channel` both name the release, so a caller passing both has asked
+ *  for two things and gets one: `version` wins. Say so rather than drop `channel` in
+ *  silence — the TSDoc used to call them "mutually exclusive" while nothing enforced
+ *  it (#178). A warning, not a throw, matching the channel-name-as-version case. */
+function warnVersionWithChannel(opts: StartOptions, logger: ProgressLogger): void {
+	if (opts.version && opts.channel) {
+		logger.warn(`Both version "${opts.version}" and channel "${opts.channel}" were given — using version ${opts.version}; channel is ignored.`);
+	}
+}
+
 function listProvisioningMutations(opts: {
 	installAllPackages?: boolean;
 	packages?: string[];
@@ -185,6 +211,22 @@ function describeProvisioningOperation(opts: Parameters<typeof listProvisioningM
 	return `use ${PROVISIONING_FEATURE_LABEL} (${joinHumanList(operations)})`;
 }
 
+/** `wait: false` returns before the guest has booted, and provisioning needs a booted
+ *  guest — so the pair is refused by name rather than the provisioning silently
+ *  skipped (#159). `machine` is set when the provisioning is first-boot intent that
+ *  `add()` recorded, which the caller may not have typed on this command line. */
+function assertWaitAllowsProvisioning(opts: StartOptions, operation: string, machine?: string): void {
+	if (opts.wait !== false) return;
+	const source = machine
+		? `machine "${machine}" has first-boot provisioning recorded by 'add' (${operation})`
+		: `provisioning was requested (${operation})`;
+	throw new QuickCHRError(
+		"INVALID_ARGUMENT",
+		`--no-wait (wait: false) cannot be combined with provisioning: ${source}, and provisioning runs against the booted guest, so start has to wait for it. ` +
+		"Drop --no-wait for this first boot — later starts can use it.",
+	);
+}
+
 // --- Socket registry lifecycle helpers ---
 
 function getSocketNamedNetworks(state: MachineState): string[] {
@@ -316,6 +358,189 @@ async function resolveLicenseInput(input: LicenseInput): Promise<LicenseOptions
 	return null;
 }
 
+/** Put a machine's disks back to the factory image and drop the credential material
+ *  that authenticated to the erased guest. Machine state is the caller's to update:
+ *  `clean()` clears the guest facts and keeps intent, a provisioning rollback restores
+ *  the record it had before the failed run. QEMU must already be stopped. */
+async function resetGuestToFactory(state: MachineState): Promise<void> {
+	// NOTE: this deliberately does NOT delete efi-vars.fd. On the arm64 `virt`
+	// machine that file stores UEFI boot order (Boot0000 -> first virtio-blk-pci
+	// disk), not OS state; wiping it forces a full device scan (~480s) on the next
+	// boot. The fresh disk re-copy below is a sufficient factory reset. Regression
+	// anchor: the "clean() resets disk to factory defaults" arm64 integration test
+	// (120s reboot wait would blow past 480s if the wipe were reintroduced).
+	// Re-copy fresh image from cache
+	const imgPath = join(getCacheDir(), `chr-${state.version}${state.arch === "arm64" ? "-arm64" : ""}.img`);
+	if (!existsSync(imgPath)) {
+		throw new QuickCHRError("MACHINE_NOT_FOUND", `Cached image not found: ${imgPath}`);
+	}
+	// Drop boot.qcow2 and the extra disks, then rebuild the boot disk from the cache.
+	// A raw disk.img is replaced atomically. On a qcow2 machine, disk.img is the unused
+	// raw copy machines created before 0.5.1 kept: the new boot.qcow2 is converted from
+	// the cache, so the copy goes too (#199).
+	const format = bootDiskFormatOf(state);
+	cleanDiskFiles(state.machineDir);
+	await writeBootDisk(state.machineDir, imgPath, format, state.bootSize);
+	if (format === "qcow2") rmSync(join(state.machineDir, "disk.img"), { force: true });
+	await ensureConfiguredDisks(state.machineDir, state.bootSize, state.extraDisks, format, { booted: false });
+
+	deleteInstanceCredentials(state.name);
+	// The managed keypair authenticated to the account factory reset erased,
+	// so it is dead credential material sitting in the machine dir. Removing
+	// it also keeps a future re-provision viable: `ssh-keygen -f <path>` on an
+	// existing file exits 1 with "already exists" rather than overwriting
+	// (verified locally), so a leftover key would break `installSshKey()`.
+	rmSync(join(state.machineDir, "ssh"), { recursive: true, force: true });
+}
+
+/** Options every machine-lock acquisition passes: the pre-0.5 lock to honour, and the
+ *  noun for `MACHINE_LOCKED`. */
+function machineLockOptions(name: string, machineDir: string): { legacyPath: string; subject: string } {
+	return { legacyPath: legacyMachineLockPath(machineDir), subject: `Machine "${name}"` };
+}
+
+/** The machine lock outlives its machine (see lock.ts), so a caller that has just
+ *  taken it must check that the machine it was asked about is still there, and is not
+ *  another machine created under the same name while it waited. Acting on the old
+ *  snapshot would mean stopping a stale pid. */
+function assertSameMachine(state: MachineState): void {
+	const fresh = loadMachine(state.name);
+	if (!fresh || fresh.createdAt !== state.createdAt) {
+		throw new QuickCHRError(
+			"MACHINE_NOT_FOUND",
+			`Machine "${state.name}" was removed${fresh ? " and created again" : ""} while this operation waited for it.`,
+		);
+	}
+}
+
+/** How long `stop`/`clean`/`remove` wait for an operation already holding the machine
+ *  lock. The holder is almost always a start or relaunch waiting for boot, so the wait
+ *  is that boot budget: a `stop` issued during a `start` runs after it rather than
+ *  failing, and a holder that never finishes still cannot block it forever (#181). */
+function lifecycleLockWaitMs(state: MachineState): number {
+	const withPackages = !!state.installAllPackages || (state.packages?.length ?? 0) > 0;
+	return defaultBootTimeout(state.arch, withPackages, state.lastAccel);
+}
+
+/** Run a lifecycle operation under the machine's lock, waiting for a current holder.
+ *  State is re-read once the lock is held: a handle's snapshot predates whatever the
+ *  holder just did, and `state.pid` read from it may name a process that has exited or
+ *  one the OS has since reused (#180, #181). */
+async function withMachineLock<T>(state: MachineState, op: LockOperation, fn: () => Promise<T>): Promise<T> {
+	const lock = await acquireLock(machineLockPath(state.machineDir), op, {
+		...machineLockOptions(state.name, state.machineDir),
+		waitMs: lifecycleLockWaitMs(state),
+		onWait: (holder) => createLogger().warn(
+			`Machine "${state.name}" is busy with \`${holder.op}\` (pid ${holder.pid}) — waiting for it to finish before \`${op}\`.`,
+		),
+	});
+	try {
+		assertSameMachine(state);
+		refreshMachineState(state);
+		return await fn();
+	} finally {
+		lock.release();
+	}
+}
+
+/** The body of `stop()`, for a caller that already holds the machine lock. The lock is
+ *  not reentrant, so code inside a locked start or relaunch calls this, never
+ *  `instance.stop()`. */
+async function stopUnderLock(state: MachineState): Promise<void> {
+	if (state.pid) {
+		await stopQemu(state.pid);
+	}
+	finalizeStoppedState(state);
+}
+
+/** Persist stopped state and release endpoints. Caller holds the lifecycle lock. */
+function finalizeStoppedState(state: MachineState): void {
+	unregisterSocketMembers(state);
+	// Update persisted state
+	const current = loadMachine(state.name);
+	if (current) {
+		current.status = "stopped";
+		current.pid = undefined;
+		saveMachine(current);
+	}
+	state.status = "stopped";
+	state.pid = undefined;
+}
+
+/** The body of `remove()`, for a caller that already holds the machine lock. The lock
+ *  file goes with the directory. */
+async function removeUnderLock(state: MachineState): Promise<void> {
+	if (state.pid && isMachineRunning(state)) {
+		await stopQemu(state.pid);
+	}
+	unregisterSocketMembers(state);
+	// Clean up stored instance credentials
+	deleteInstanceCredentials(state.name);
+	removeState(state.name);
+}
+
+/** The body of `clean()`, for a caller that already holds the machine lock. */
+async function cleanUnderLock(state: MachineState): Promise<void> {
+	if (state.pid && isMachineRunning(state)) {
+		await stopQemu(state.pid);
+	}
+	// Same invariant as stop()/remove(): a machine that is not running holds no
+	// endpoint. clean() stops QEMU directly rather than through stop(), so without
+	// this a cleaned machine keeps a pair link occupied and blocks its removal.
+	unregisterSocketMembers(state);
+	await resetGuestToFactory(state);
+
+	// Every guest-side credential went with the old disk, so the credential
+	// facts in machine.json now describe a machine that no longer exists.
+	// Left in place, `resolveAuth()` /
+	// `resolveCreds()` prefer `state.user` and authenticate every REST call,
+	// exec, and SCP as a deleted user — the confound #79 removes here.
+	// Clearing them restores the documented fallback: factory `admin` with an
+	// empty password, which is what a fresh CHR image actually answers to
+	// (anchored by the "clean() resets disk to factory defaults" integration
+	// test). `disableAdmin` goes with them because it is read as a live fact
+	// about the guest (buildDescriptor's `disableAdminLockout`) and a fresh
+	// image has admin enabled again. `licenseLevel` goes with them for the same
+	// reason: it is a read-back of the license the erased disk held, not an
+	// intent — quickchr never persists the license *input* — so leaving it
+	// behind would report a level the fresh image does not have. Provisioning
+	// *intent* — packages, deviceMode, secureLogin — is not guest state and
+	// survives, and is what the next `start()` re-applies now that the window
+	// reopens.
+	// (`resetGuestToFactory()` has already dropped the secret-store entry and the
+	// managed keypair, which describe the same erased account.)
+
+	// Update state. `provisioning` and `lastStartedAt` go with the credentials:
+	// both describe a guest that no longer exists, and together they are what
+	// closes the provisioning window. Leaving them behind is what stopped a cleaned
+	// machine from ever being provisioned again — the disk was factory-fresh and
+	// `start()` still refused to provision it (#176). `cleanedAt` keeps the
+	// forensic clue that the timestamp carried.
+	const cleanedAt = new Date().toISOString();
+	const current = loadMachine(state.name);
+	if (current) {
+		current.status = "stopped";
+		current.pid = undefined;
+		current.user = undefined;
+		current.managedSshKey = undefined;
+		current.disableAdmin = undefined;
+		current.provisioning = undefined;
+		current.lastStartedAt = undefined;
+		current.licenseLevel = undefined;
+		current.cleanedAt = cleanedAt;
+		saveMachine(current);
+	}
+	state.status = "stopped";
+	state.pid = undefined;
+	state.user = undefined;
+	state.managedSshKey = undefined;
+	state.disableAdmin = undefined;
+	state.provisioning = undefined;
+	state.lastStartedAt = undefined;
+	state.licenseLevel = undefined;
+	state.cleanedAt = cleanedAt;
+}
+
 /** Create a ChrInstance handle from persisted MachineState. */
 function createInstance(state: MachineState): ChrInstance {
 	const ports = toChrPorts(state.ports);
@@ -404,14 +629,16 @@ function createInstance(state: MachineState): ChrInstance {
 		// keeps the excludePorts fix: excluding "http" while keeping "https" now
 		// resolves rest-api onto the surviving secure port instead of a port that
 		// doesn't exist.
-		const restApi = buildHttpService(
-			state.ports.https,
-			state.ports.http,
-			"rest-api",
-			{ secure: "https", plain: "http" },
-			{ username: creds.user, password: creds.password, basic, header: auth.header },
-			"/rest",
-		);
+		const restApi: ServiceEndpoint = isRouterOs6(state.version)
+			? { available: false, unavailableReason: `RouterOS ${state.version} has no REST API — use native-api` }
+			: buildHttpService(
+				state.ports.https,
+				state.ports.http,
+				"rest-api",
+				{ secure: "https", plain: "http" },
+				{ username: creds.user, password: creds.password, basic, header: auth.header },
+				"/rest",
+			);
 		const nativeApi = buildHttpService(
 			state.ports["api-ssl"],
 			state.ports.api,
@@ -498,11 +725,11 @@ function createInstance(state: MachineState): ChrInstance {
 		portBase: state.portBase,
 		captureInterface: process.platform === "darwin" ? "lo0" : "any",
 		hostGatewayIp: HOST_GATEWAY_IP,
-		// Deprecated alias for hostGatewayIp (#26) — same value, removed no earlier
-		// than the next minor.
-		tzspGatewayIp: HOST_GATEWAY_IP,
 
 		async waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean> {
+			if (readinessProbeFor(state.version) === "api") {
+				return waitForApiReady(ports.api, timeoutMs ?? 120_000, resolveCreds(state), stats);
+			}
 			// Use resolved credentials so waitForBoot can validate the response body
 			// on authenticated machines (post-provisioning, post-install reboots).
 			const auth = resolveAuth(state);
@@ -523,101 +750,32 @@ function createInstance(state: MachineState): ChrInstance {
 		},
 
 		async stop(): Promise<void> {
-			if (state.pid) {
-				await stopQemu(state.pid);
-			}
-			unregisterSocketMembers(state);
-			// Update persisted state
-			const current = loadMachine(state.name);
-			if (current) {
-				current.status = "stopped";
-				current.pid = undefined;
-				saveMachine(current);
-			}
-			state.status = "stopped";
-			state.pid = undefined;
+			await withMachineLock(state, "stop", () => stopUnderLock(state));
+		},
+
+		async shutdown(options) {
+			const timeoutMs = validateShutdownTimeout(options?.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
+			return withMachineLock(state, "shutdown", async () => {
+				if (!state.pid || !isMachineRunning(state)) {
+					finalizeStoppedState(state);
+					return { outcome: "already-stopped" };
+				}
+				const pid = state.pid;
+				const result = await shutdownGuest(timeoutMs, async (requestTimeoutMs) => {
+					// Rebuild after the locked refresh: a waiting handle may predate a relaunch.
+					return createInstance(state).exec("/system/shutdown", { via: "rest", timeout: requestTimeoutMs });
+				}, () => isMachineRunning(state), () => stopQemu(pid));
+				finalizeStoppedState(state);
+				return result;
+			});
 		},
 
 		async remove(): Promise<void> {
-			if (state.pid && isMachineRunning(state)) {
-				await stopQemu(state.pid);
-			}
-			unregisterSocketMembers(state);
-			// Clean up stored instance credentials
-			deleteInstanceCredentials(state.name);
-			removeState(state.name);
+			await withMachineLock(state, "remove", () => removeUnderLock(state));
 		},
 
 		async clean(): Promise<void> {
-			if (state.pid && isMachineRunning(state)) {
-				await stopQemu(state.pid);
-			}
-			// Same invariant as stop()/remove(): a machine that is not running holds no
-			// endpoint. clean() stops QEMU directly rather than through stop(), so without
-			// this a cleaned machine keeps a pair link occupied and blocks its removal.
-			unregisterSocketMembers(state);
-			// NOTE: clean() deliberately does NOT delete efi-vars.fd. On the arm64 `virt`
-			// machine that file stores UEFI boot order (Boot0000 -> first virtio-blk-pci
-			// disk), not OS state; wiping it forces a full device scan (~480s) on the next
-			// boot. The fresh disk re-copy below is a sufficient factory reset. Regression
-			// anchor: the "clean() resets disk to factory defaults" arm64 integration test
-			// (120s reboot wait would blow past 480s if the wipe were reintroduced).
-			// Re-copy fresh image from cache
-			const imgPath = join(getCacheDir(), `chr-${state.version}${state.arch === "arm64" ? "-arm64" : ""}.img`);
-			if (!existsSync(imgPath)) {
-				throw new QuickCHRError("MACHINE_NOT_FOUND", `Cached image not found: ${imgPath}`);
-			}
-			const destPath = join(state.machineDir, "disk.img");
-			copyFileSync(imgPath, destPath);
-
-			// Clean up disk files (boot.qcow2, extra disks)
-			cleanDiskFiles(state.machineDir);
-
-			// Re-prepare disks if the machine had disk customizations
-			await ensureConfiguredDisks(
-				state.machineDir,
-				state.bootSize,
-				state.extraDisks,
-				state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
-			);
-
-			// Every guest-side credential went with the old disk, so the credential
-			// facts in machine.json now describe a machine that no longer exists.
-			// Nothing re-provisions them either: a post-clean() start() takes the
-			// `_launchExisting(…, undefined)` path (lastStartedAt is set), so the
-			// erased account is never recreated. Left in place, `resolveAuth()` /
-			// `resolveCreds()` prefer `state.user` and authenticate every REST call,
-			// exec, and SCP as a deleted user — the confound #79 removes here.
-			// Clearing them restores the documented fallback: factory `admin` with an
-			// empty password, which is what a fresh CHR image actually answers to
-			// (anchored by the "clean() resets disk to factory defaults" integration
-			// test). `disableAdmin` goes with them because it is read as a live fact
-			// about the guest (buildDescriptor's `disableAdminLockout`) and a fresh
-			// image has admin enabled again. Provisioning *intent* — packages,
-			// deviceMode, secureLogin — is not guest state and survives.
-			deleteInstanceCredentials(state.name);
-			// The managed keypair authenticated to the account factory reset erased,
-			// so it is dead credential material sitting in the machine dir. Removing
-			// it also keeps a future re-provision viable: `ssh-keygen -f <path>` on an
-			// existing file exits 1 with "already exists" rather than overwriting
-			// (verified locally), so a leftover key would break `installSshKey()`.
-			rmSync(join(state.machineDir, "ssh"), { recursive: true, force: true });
-
-			// Update state
-			const current = loadMachine(state.name);
-			if (current) {
-				current.status = "stopped";
-				current.pid = undefined;
-				current.user = undefined;
-				current.managedSshKey = undefined;
-				current.disableAdmin = undefined;
-				saveMachine(current);
-			}
-			state.status = "stopped";
-			state.pid = undefined;
-			state.user = undefined;
-			state.managedSshKey = undefined;
-			state.disableAdmin = undefined;
+			await withMachineLock(state, "clean", () => cleanUnderLock(state));
 		},
 
 		async monitor(command: string): Promise<string> {
@@ -633,6 +791,7 @@ function createInstance(state: MachineState): ChrInstance {
 		},
 
 		async rest(path: string, opts?: RequestInit): Promise<unknown> {
+			assertRestAvailable(state, "rest()");
 			const url = `${restUrl}/rest${path.startsWith("/") ? path : "/" + path}`;
 
 			// Retry on ECONNRESET — RouterOS can transiently reset connections in the
@@ -722,6 +881,9 @@ function createInstance(state: MachineState): ChrInstance {
 					`exec transport "${via}" is not yet implemented`,
 				);
 			}
+			// Before the auto→console fallback below: that fallback exists for an
+			// unreachable REST endpoint, not for one that cannot exist.
+			assertRestAvailable(state, "exec");
 			const auth = resolveAuth(state, opts?.user, opts?.password);
 			if (via === "rest") {
 				return restExecute(restUrl, auth, command, opts);
@@ -769,15 +931,62 @@ function createInstance(state: MachineState): ChrInstance {
 			const log = logger ?? createLogger();
 			const resolved = resolveDeviceModeOptions(options);
 			for (const w of resolved.warnings) log.warn(`Device-mode: ${w}`);
-			const launchConfig = await buildLaunchConfigFromState(state);
-			await applyDeviceMode(this as ChrInstance, state, resolved, launchConfig, log);
-			// Persist updated device-mode in state
-			const current = loadMachine(state.name);
-			if (current) {
-				current.deviceMode = options;
-				saveMachine(current);
+			if (!shouldApplyDeviceMode(resolved)) {
+				throw new QuickCHRError(
+					"INVALID_ARGUMENT",
+					`Nothing to set: device-mode options for "${state.name}" resolved to no change ` +
+					"(mode=skip disables device-mode entirely; pass a mode or a feature to enable/disable).",
+				);
+			}
+			// The same machine lock every other relaunch takes. This one is a relaunch:
+			// it terminates QEMU, spawns a replacement and rewrites `machine.json`, so a
+			// concurrent `start` would otherwise spawn a second QEMU into the power-cycle
+			// window and both would persist over each other. Fail-fast like a second
+			// `start`: waiting would only power-cycle the machine twice.
+			const lock = acquireLockNow(machineLockPath(state.machineDir), "device-mode", machineLockOptions(state.name, state.machineDir));
+			try {
+				assertSameMachine(state);
+				// Re-read under the lock before anything reads `state`. This handle's
+				// snapshot is taken once, at `createInstance`, and a library consumer can
+				// hold it across another process's stop/start — after which `state.pid`
+				// names a process that has exited (a false MACHINE_STOPPED) or, worse, one
+				// the OS has since reused, which `hardRebootMachine()` would then
+				// terminate. `state.provisioning` and `state.deviceMode` go stale the same
+				// way, and both feed `appliedDeviceModeRecord()`.
+				refreshMachineState(state);
+				// Inside the lock: the applicability check has to hold for the operation,
+				// not merely at the moment it was made.
+				assertDeviceModeApplicable(state);
+				const launchConfig = await buildLaunchConfigFromState(state);
+				// Post-boot auth, not factory admin: a machine provisioned with
+				// `--disable-admin` answers 401 to `admin:`, and those are exactly the
+				// machines this route exists for.
+				await applyDeviceMode(this as ChrInstance, state, resolved, launchConfig, log, resolveAuth(state).header);
+
+				// Persist what is now true of the guest: the applied selection folded into
+				// what was already *applied*, not the request on its own. Device-mode
+				// updates are cumulative — only the settings a request names move — so
+				// overwriting would leave `machine.json` describing a machine that does
+				// not exist.
+				//
+				// `appliedDeviceModeRecord` gates the carry-forward on the step record, for
+				// the reason #176 keeps running into: desired config is not evidence that
+				// a step ran.
+				const deviceMode = appliedDeviceModeRecord(state, resolved);
+				const current = loadMachine(state.name);
+				if (current) {
+					current.deviceMode = deviceMode;
+					saveMachine(current);
+				}
+				state.deviceMode = deviceMode;
+				// This is quickchr applying a provisioning step, so it belongs in the
+				// record the window reads (#176). It does not reopen the window — it adds
+				// the one step that just ran, so a later `start` passing the same
+				// device-mode is recognised as already applied instead of refused.
+				recordProvisioningStep(state, "deviceMode");
+			} finally {
+				lock.release();
 			}
-			state.deviceMode = options;
 		},
 
 		async availablePackages(): Promise<string[]> {
@@ -789,21 +998,28 @@ function createInstance(state: MachineState): ChrInstance {
 			const names = typeof packages === "string" ? [packages] : packages;
 			if (names.length === 0) return [];
 
-			const extractDir = await downloadPackages(state.version, state.arch);
+			// A booted machine no longer holds its package cache in use, so pin it until the
+			// upload is done: a concurrent eviction must not remove it mid-read.
+			const pin = pinCacheEntries(`install packages on ${state.name}`, [`packages-${state.arch}-${state.version}`]);
 			const packagePaths: string[] = [];
 			const installed: string[] = [];
-			for (const pkg of names) {
-				const pkgPath = findPackageFile(extractDir, pkg);
-				if (!pkgPath) {
-					console.warn(`Package "${pkg}" not found in all_packages for ${state.version} (${state.arch})`);
-					continue;
+			try {
+				const extractDir = await downloadPackages(state.version, state.arch);
+				for (const pkg of names) {
+					const pkgPath = findPackageFile(extractDir, pkg);
+					if (!pkgPath) {
+						console.warn(`Package "${pkg}" not found in all_packages for ${state.version} (${state.arch})`);
+						continue;
+					}
+					packagePaths.push(pkgPath);
+					installed.push(pkg);
 				}
-				packagePaths.push(pkgPath);
-				installed.push(pkg);
-			}
-			if (packagePaths.length === 0) return [];
+				if (packagePaths.length === 0) return [];
 
-			await uploadPackages(packagePaths, ports.ssh);
+				await uploadPackages(packagePaths, ports.ssh);
+			} finally {
+				pin.release();
+			}
 
 			// Reboot to activate packages
 			let rebootAuth: string;
@@ -864,8 +1080,10 @@ function createInstance(state: MachineState): ChrInstance {
 		},
 
 		async destroy(): Promise<void> {
-			await this.stop();
-			await this.remove();
+			await withMachineLock(state, "remove", async () => {
+				await stopUnderLock(state);
+				await removeUnderLock(state);
+			});
 		},
 
 		async subprocessEnv(): Promise<Record<string, string>> {
@@ -905,7 +1123,7 @@ function createInstance(state: MachineState): ChrInstance {
 
 		snapshot: {
 			async list(): Promise<SnapshotInfo[]> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") return [];
 
 				// Try monitor first (works on running machines, gives live state)
@@ -917,7 +1135,7 @@ function createInstance(state: MachineState): ChrInstance {
 				}
 
 				// Fall back to qemu-img info (works on stopped machines too)
-				const bootPath = join(state.machineDir, "boot.qcow2");
+				const bootPath = bootDiskPath(state.machineDir, "qcow2");
 				if (existsSync(bootPath)) {
 					return listSnapshots(bootPath);
 				}
@@ -925,7 +1143,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async save(name?: string): Promise<SnapshotInfo> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk. Recreate with bootDiskFormat: \"qcow2\".");
 				}
@@ -962,7 +1180,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async load(name: string): Promise<void> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk.");
 				}
@@ -988,7 +1206,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async delete(name: string): Promise<void> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk.");
 				}
@@ -1005,44 +1223,6 @@ function createInstance(state: MachineState): ChrInstance {
 	};
 }
 
-/**
- * Atomically acquire an exclusive start lock for a machine directory.
- * Uses O_CREAT|O_EXCL so concurrent attempts are rejected by the OS — no TOCTOU race.
- * If the lock is stale (owning process is dead) it is silently replaced.
- * Throws MACHINE_LOCKED if the lock is held by a live process.
- */
-export function acquireLock(lockPath: string): void {
-	let fd: number;
-	try {
-		fd = openSync(lockPath, "wx"); // O_WRONLY | O_CREAT | O_EXCL — atomic
-		writeSync(fd, String(process.pid));
-		closeSync(fd);
-		return;
-	} catch {
-		// File already exists — check whether owner is still alive
-	}
-
-	let ownerPid: number | undefined;
-	try {
-		ownerPid = Number.parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
-	} catch { /* unreadable — treat as stale */ }
-
-	if (ownerPid && !Number.isNaN(ownerPid)) {
-		try {
-			process.kill(ownerPid, 0); // probes liveness; throws ESRCH if process not found
-			throw new QuickCHRError("MACHINE_LOCKED", `Machine is already being started (pid ${ownerPid})`);
-		} catch (e) {
-			if (e instanceof QuickCHRError) throw e;
-			// Process is dead — stale lock, overwrite
-			writeFileSync(lockPath, String(process.pid));
-			return;
-		}
-	}
-
-	// Owner unreadable or zero — treat as stale, overwrite
-	writeFileSync(lockPath, String(process.pid));
-}
-
 /** Resolve the host architecture to a CHR architecture. */
 function hostArchToChr(): Arch {
 	const arch = process.arch;
@@ -1222,28 +1402,122 @@ export async function captureRunningFailure(
 	});
 }
 
-/** Tear down a machine that failed to boot, and describe what was done.
- *
- *  Default is full cleanup — a failed `start()` must not leave a half-dead
- *  machine behind for the next call to trip over. QUICKCHR_PRESERVE_ON_FAILURE=1
- *  inverts that for **local** debugging: the QEMU process is still stopped (it is
- *  wedged, and its port block must be released), but the machine directory
- *  survives so it can be inspected by hand.
- *
- *  Evidence does not depend on that flag, and CI deliberately does not set it —
- *  `captureBootFailure()` has already written its report outside the machine dir
- *  with qemu.log and serial.log embedded, so cleanup cannot destroy it (#79). */
-async function cleanupAfterBootFailure(
+/** Cleanup intent is captured under the lifecycle lock, before launch mutates state. */
+export type BootFailureCleanup =
+	| { kind: "remove-new" }
+	| { kind: "reset-first-boot"; restore: MachineState }
+	| { kind: "preserve-existing" };
+
+/** Stop the failed guest, then apply the launch's cleanup intent.
+ * Diagnostics have already been captured outside the machine directory. */
+export async function cleanupAfterBootFailure(
 	instance: ChrInstance,
 	name: string,
 	failure: BootFailureReport,
+	cleanup: BootFailureCleanup,
 ): Promise<string> {
-	try { await instance.stop(); } catch { /* ignore */ }
+	const quoted = shellQuote(name);
+	// Called from inside a start or relaunch that holds the machine lock.
+	try {
+		await stopUnderLock(instance.state);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		return ` Machine "${name}" was retained, but stopping QEMU failed (${reason}) — retry with \`quickchr stop ${quoted}\` before starting or removing it.`;
+	}
+	if (cleanup.kind === "preserve-existing") {
+		return ` Machine "${name}" was stopped and preserved with its disks and configuration — ` +
+			`retry with \`quickchr start ${quoted}\`, or explicitly remove it with \`quickchr remove ${quoted}\`.`;
+	}
+	const restore = cleanup.kind === "reset-first-boot" ? cleanup.restore : undefined;
 	if (failure.preserved) {
-		return ` Machine "${name}" was preserved for diagnosis (QUICKCHR_PRESERVE_ON_FAILURE=1) — remove it with \`quickchr remove ${name}\`.`;
+		return ` Machine "${name}" was preserved for diagnosis (QUICKCHR_PRESERVE_ON_FAILURE=1) — ` +
+			(restore ? `reset it with \`quickchr clean ${quoted}\` and start it again, or ` : "") +
+			`remove it with \`quickchr remove ${quoted}\`.`;
 	}
-	try { await instance.remove(); } catch { /* ignore */ }
-	return ` Machine "${name}" has been cleaned up automatically.`;
+	// An add()-created machine on its first boot: the same reset a failed provisioning
+	// run gets (#187), so the retry is `start` again rather than `add` + `start`. The
+	// guest may have written to its disk before stalling, so the disk goes back to the
+	// factory image along with the record — the window is open again, and an open
+	// window promises a factory disk.
+	if (restore) {
+		try {
+			await resetGuestToFactory(restore);
+			saveMachine({ ...restore, status: "stopped", pid: undefined });
+			refreshMachineState(instance.state);
+			return ` Machine "${name}" was reset to its never-booted state, with the options \`add\` recorded — ` +
+				`retry with \`quickchr start ${quoted}\`. Set QUICKCHR_PRESERVE_ON_FAILURE=1 to keep a failed machine as it is for diagnosis.`;
+		} catch (resetErr) {
+			const reason = resetErr instanceof Error ? resetErr.message : String(resetErr);
+			return ` Resetting machine "${name}" also failed (${reason}) — reset it with \`quickchr clean ${quoted}\` or remove it with \`quickchr remove ${quoted}\`.`;
+		}
+	}
+	try { await removeUnderLock(instance.state); } catch { /* ignore */ }
+	return ` Machine "${name}" has been cleaned up automatically — set QUICKCHR_PRESERVE_ON_FAILURE=1 to keep a failed machine for diagnosis.`;
+}
+
+/** Undo a first boot whose provisioning threw, so that retrying is re-running the same
+ *  command (#176).
+ *
+ *  Provisioning is transactional — you get the machine you asked for or you don't —
+ *  and the throw used to break that: the guest was left running and half-provisioned,
+ *  with `lastStartedAt` set, so the window was closed and the retry a user reaches for
+ *  was refused. Resuming from the steps that landed is not the fix. A step can throw
+ *  half-applied (the login group creates a user and then disables `admin` in one call),
+ *  and quickchr cannot tell how far it got without reading the guest. So the rollback
+ *  reverts the whole run, and the retry starts again from a factory disk:
+ *
+ *  - **`restore` given** — an `add()`-created machine on its first boot. The disk is
+ *    reset to the factory image and `machine.json` goes back to the record `add()`
+ *    wrote, window open and intent intact, so `quickchr start <name>` tries again.
+ *  - **no `restore`** — `start()` created the machine in this call, so it is removed,
+ *    exactly as a boot timeout removes it.
+ *
+ *  `QUICKCHR_PRESERVE_ON_FAILURE=1` keeps the half-provisioned machine for inspection,
+ *  as it does for a boot failure. QEMU is stopped either way.
+ *
+ *  Returns the sentence to append to the error. A rollback that fails is reported in
+ *  that sentence, never swallowed — the provisioning error stays the primary one. */
+export async function rollbackFailedProvisioning(
+	instance: ChrInstance,
+	restore: MachineState | undefined,
+): Promise<string> {
+	const name = instance.state.name;
+	const quoted = shellQuote(name);
+	// Called from inside a start or relaunch that holds the machine lock.
+	try {
+		await stopUnderLock(instance.state);
+		if (preserveOnFailure()) {
+			return ` Machine "${name}" was preserved half-provisioned for diagnosis (QUICKCHR_PRESERVE_ON_FAILURE=1) — reset it with \`quickchr clean ${quoted}\` and repeat the start command, or remove it with \`quickchr remove ${quoted}\`.`;
+		}
+		if (!restore) {
+			await removeUnderLock(instance.state);
+			return ` Machine "${name}" has been removed — re-run the same command to retry.`;
+		}
+		await resetGuestToFactory(restore);
+		saveMachine({ ...restore, status: "stopped", pid: undefined });
+		refreshMachineState(instance.state);
+		return ` Machine "${name}" was reset to its never-booted state, with the options \`add\` recorded — re-run the same start command to retry.`;
+	} catch (rollbackErr) {
+		const reason = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+		return ` Rolling back machine "${name}" also failed (${reason}) — reset it with \`quickchr clean ${quoted}\` or remove it with \`quickchr remove ${quoted}\`.`;
+	}
+}
+
+/** Append the rollback outcome to a provisioning error and hand it back for rethrow.
+ *  The error keeps its own type, code and stack: the rollback is context, not the
+ *  failure. */
+export async function failProvisioning(
+	err: unknown,
+	instance: ChrInstance,
+	restore: MachineState | undefined,
+): Promise<unknown> {
+	// Its own line: the provisioning error often ends in a RouterOS JSON body.
+	const outcome = (await rollbackFailedProvisioning(instance, restore)).trim();
+	if (err instanceof Error) {
+		err.message += `\n${outcome}`;
+		return err;
+	}
+	return new QuickCHRError("PROCESS_FAILED", `Provisioning failed: ${String(err)}\n${outcome}`);
 }
 
 /** Wait for CHR to boot with periodic progress status updates every 20s. */
@@ -1314,7 +1588,8 @@ async function buildLaunchConfigFromState(state: MachineState): Promise<QemuLaun
 		state.machineDir,
 		state.bootSize,
 		state.extraDisks,
-		state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
+		bootDiskFormatOf(state),
+		{ booted: true },
 	);
 	const platform = await detectPlatform();
 	const hostfwd = buildHostfwdString(state.ports);
@@ -1337,26 +1612,126 @@ async function buildLaunchConfigFromState(state: MachineState): Promise<QemuLaun
 	};
 }
 
+/** Persist what provisioning landed on the current disk, in state and on disk.
+ *  A run with nothing to do still records — an empty `steps` says "provisioning ran
+ *  and had nothing to apply", which is a different fact from never having run. */
+function recordProvisioning(state: MachineState, steps: ProvisioningStep[]): void {
+	const record = { at: new Date().toISOString(), steps };
+	const current = loadMachine(state.name);
+	if (current) {
+		current.provisioning = record;
+		saveMachine(current);
+	}
+	state.provisioning = record;
+}
+
+/** Re-read `machine.json` into an existing state object, in place.
+ *
+ *  **In place** because `createInstance` closes over this object and exposes it as
+ *  `instance.state`: rebinding a local would leave the caller's view stale, and every
+ *  other method on the handle would keep reading the old snapshot.
+ *
+ *  Keys the reloaded record does not have are deleted rather than left behind.
+ *  `clean()` removes `provisioning`, `user` and `disableAdmin` precisely because they
+ *  stopped being true, so a leftover would be read as fact by the next caller —
+ *  `appliedDeviceModeRecord()` reads exactly one of them. A plain `Object.assign`
+ *  cannot express a field that went away. */
+export function refreshMachineState(state: MachineState): void {
+	const fresh = loadMachine(state.name);
+	if (!fresh) return;
+	const mutable = state as unknown as Record<string, unknown>;
+	for (const key of Object.keys(mutable)) {
+		if (!(key in fresh)) delete mutable[key];
+	}
+	Object.assign(state, fresh);
+}
+
+/** Add one step to the provisioning record, keeping whatever is already there.
+ *
+ *  `recordProvisioning()` stamps a whole first-boot run; this is for a step applied on
+ *  its own afterwards — `setDeviceMode()` today, `installPackage()` when #24 lands.
+ *  `steps` accumulates and `at` moves to now, which is what `ProvisioningRecord`
+ *  promises: the last time quickchr applied provisioning to this disk.
+ *
+ *  It cannot reopen or close a window by accident. The only caller requires a running
+ *  machine, and a running machine has `lastStartedAt`, so the window was already shut
+ *  before this wrote anything. */
+function recordProvisioningStep(state: MachineState, step: ProvisioningStep): void {
+	const steps = [...new Set([...(state.provisioning?.steps ?? []), step])];
+	const record = { at: new Date().toISOString(), steps };
+	const current = loadMachine(state.name);
+	if (current) {
+		current.provisioning = record;
+		saveMachine(current);
+	}
+	state.provisioning = record;
+}
+
+/** Preconditions a post-boot device-mode change inherits from provisioning.
+ *
+ *  Both were undocumented and both fail confusingly when unchecked (#176):
+ *  `applyDeviceMode()` polls `waitForDeviceModeApi` before it does anything, so a
+ *  stopped machine spends 60 s to report a timeout, and a machine with no user-mode
+ *  NIC has no localhost route to REST at all and never recovers.
+ *
+ *  This is the same guard `start()` applies to provisioning, moved to the one step
+ *  that may also run afterwards. */
+function assertDeviceModeApplicable(state: MachineState): void {
+	if (!isMachineRunning(state)) {
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			`Device-mode is applied through the guest's REST API, so "${state.name}" has to be running. ` +
+			`Start it with 'quickchr start ${shellQuote(state.name)}', then set device-mode.`,
+		);
+	}
+	if (!hasUserModeNetwork(state.networks)) {
+		throw new QuickCHRError(
+			"NETWORK_UNAVAILABLE",
+			`Device-mode is applied over localhost REST, which needs a user-mode network interface — ` +
+			`"${state.name}" has none, so quickchr cannot reach its REST API. ` +
+			"Recreate the machine with a user-mode NIC alongside its other networks.",
+		);
+	}
+}
+
 /** Apply a device-mode change to a running CHR instance (may require hard power-cycle).
- *  Extracted from _provisionInstance so setDeviceMode() can reuse the same logic. */
+ *  Extracted from _provisionInstance so setDeviceMode() can reuse the same logic.
+ *
+ *  `authHeader` is the caller's, because the two callers genuinely differ and the
+ *  difference is not cosmetic. During first-boot provisioning device-mode is step 2 and
+ *  the user step is step 4, so factory `admin:` is the *only* credential that exists
+ *  yet — `state.user` is already populated at that point but names an account nobody
+ *  has created, so resolving it here would 401 the shipped path. Post-boot the reverse
+ *  holds: a machine provisioned with `--disable-admin` answers 401 to factory admin,
+ *  which is what made `quickchr set <name> --device-mode` fail on exactly the machines
+ *  the route was written for. Same field, opposite answers, decided by the caller
+ *  rather than guessed here. */
 async function applyDeviceMode(
 	instance: ChrInstance,
 	machineState: MachineState,
 	resolvedDeviceMode: ReturnType<typeof resolveDeviceModeOptions>,
 	launchConfig: QemuLaunchConfig,
 	log: ProgressLogger,
+	authHeader: string,
 ): Promise<void> {
 	const httpPort = toChrPorts(machineState.ports).http;
 	const accel = await detectAccel(machineState.arch);
 	const bootTimeout = defaultBootTimeout(machineState.arch, undefined, accel);
-	await waitForDeviceModeApi(httpPort, 60_000);
+	await waitForDeviceModeApi(httpPort, 60_000, authHeader);
 	log.status(`Applying device-mode (${formatDeviceModeSelection(resolvedDeviceMode)})...`);
 
 	let alreadyActive = false;
 	try {
-		const beforeMode = await readDeviceMode(httpPort);
+		const beforeMode = await readDeviceMode(httpPort, authHeader);
 		log.debug(`Device-mode before update: ${JSON.stringify(beforeMode)}`);
 		alreadyActive = verifyDeviceMode(resolvedDeviceMode, beforeMode).ok;
+		// Say what the power cycle is buying before spending it. `mode` moves as a
+		// side-effect of enabling a feature — `--device-mode-enable container` resolves
+		// `auto` to `rose` — and a change nobody asked for should at least be announced
+		// (#176).
+		for (const change of describeDeviceModeChange(resolvedDeviceMode, beforeMode)) {
+			log.status(`  ${change}`);
+		}
 	} catch { /* CHR unexpectedly unreachable — proceed with update */ }
 
 	if (alreadyActive) {
@@ -1369,7 +1744,7 @@ async function applyDeviceMode(
 	let requiresPowerCycle = false;
 
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		const request = startDeviceModeUpdate(httpPort, resolvedDeviceMode);
+		const request = startDeviceModeUpdate(httpPort, resolvedDeviceMode, authHeader);
 		// RouterOS blocks this connection while waiting for hard power-cycle confirmation.
 		// We race against 2s: if still pending at 2s, RouterOS has entered blocking state
 		// and we can confirm by killing QEMU. If it resolves in <2s ("returned early"),
@@ -1399,6 +1774,22 @@ async function applyDeviceMode(
 		}
 
 		log.debug(`Device-mode update response: HTTP ${outcome.response.status}`);
+
+		// A rejection is an answer, not a race — say what RouterOS said and stop.
+		// Retrying here used to cost five POSTs and ~33 s and then report a *mismatch*
+		// (`bogus-feature: expected=yes, actual=(missing)`) while RouterOS had replied
+		// `HTTP 400 — unknown parameter bogus-feature` on the first attempt. RouterOS
+		// also counts device-mode update attempts (`attempt-count` on
+		// `/system/device-mode`), so the retries spend a budget that is not ours to
+		// spend. Only a 2xx that came back before activation is worth trying again.
+		const { status, body } = outcome.response;
+		if (status < 200 || status >= 300) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`Device-mode update rejected by RouterOS: HTTP ${status} — ${body.trim() || "(empty body)"}`,
+			);
+		}
+
 		await Bun.sleep(5000);
 
 		let routerOsOffline = false;
@@ -1415,10 +1806,10 @@ async function applyDeviceMode(
 			if (!rebooted) {
 				throw new QuickCHRError("BOOT_TIMEOUT", "RouterOS device-mode internal reboot timed out");
 			}
-			await waitForDeviceModeApi(httpPort, bootTimeout);
+			await waitForDeviceModeApi(httpPort, bootTimeout, authHeader);
 		}
 
-		const actualNow = await readDeviceMode(httpPort);
+		const actualNow = await readDeviceMode(httpPort, authHeader);
 		log.debug(`Device-mode after update attempt ${attempt}: ${JSON.stringify(actualNow)}`);
 		const immediateVerification = verifyDeviceMode(resolvedDeviceMode, actualNow);
 		if (immediateVerification.ok) {
@@ -1448,10 +1839,10 @@ async function applyDeviceMode(
 				`Device-mode activation reboot did not come back within ${bootTimeout / 1000}s`,
 			);
 		}
-		await waitForDeviceModeApi(httpPort, bootTimeout);
+		await waitForDeviceModeApi(httpPort, bootTimeout, authHeader);
 	}
 
-	const actual = await readDeviceMode(httpPort);
+	const actual = await readDeviceMode(httpPort, authHeader);
 	log.debug(`Device-mode post-reboot: ${JSON.stringify(actual)}`);
 	const verification = verifyDeviceMode(resolvedDeviceMode, actual);
 	if (!verification.ok) {
@@ -1463,6 +1854,112 @@ async function applyDeviceMode(
 	log.status(`  Device-mode verified: ${formatDeviceModeSelection(resolvedDeviceMode)}`);
 }
 
+/** How long a creation waits for another to finish choosing its port block. The
+ *  critical section is a handful of loopback connect probes, so this is headroom for a
+ *  busy host, not an expected wait. */
+const ALLOCATION_LOCK_WAIT_MS = 60_000;
+
+/** An explicit `portBase` is the caller's choice and is never moved: one that overlaps
+ *  another machine's block — persisted or still being created — is a `PORT_CONFLICT`
+ *  here rather than a `SPAWN_FAILED` from QEMU's bind later. */
+function assertPortBaseFree(
+	portBase: number,
+	name: string,
+	machines: MachineState[],
+	reserved: Array<{ name: string; portBase: number }>,
+): void {
+	const others = [
+		...machines.filter((m) => m.name !== name).map((m) => ({ name: m.name, portBase: m.portBase })),
+		...reserved,
+	];
+	const clash = others.find((o) => Math.abs(o.portBase - portBase) < PORTS_PER_BLOCK);
+	if (clash) {
+		throw new QuickCHRError(
+			"PORT_CONFLICT",
+			`portBase ${portBase} overlaps machine "${clash.name}" (portBase ${clash.portBase}) — each machine takes a block of ${PORTS_PER_BLOCK} ports. Pick a base at least ${PORTS_PER_BLOCK} away, or omit portBase to have one allocated.`,
+		);
+	}
+}
+
+/** Choose a new machine's port block and NIC MACs, avoiding every persisted machine
+ *  and every creation still in flight. Choosing is not claiming: only
+ *  `claimNewMachine()` makes the result safe from a concurrent creation. */
+async function pickNewMachineResources(
+	name: string,
+	opts: StartOptions,
+): Promise<{ portBase: number; ports: Record<string, PortMapping>; networks: NetworkConfig[] }> {
+	const machines = loadAllMachines();
+	const reserved = listReservations(name);
+	if (opts.portBase) assertPortBaseFree(opts.portBase, name, machines, reserved);
+	const usedBases = [...getUsedPortBases(), ...reserved.map((r) => r.portBase)];
+	const portBase = opts.portBase || await findAvailablePortBlock(usedBases, opts.excludePorts, opts.extraPorts);
+	validateExplicitExtraPorts(opts.extraPorts, portBase, opts.excludePorts, machines, name);
+	const ports = buildPortMappings(portBase, opts.excludePorts, opts.extraPorts);
+
+	const usedMacs = getUsedMacs();
+	for (const r of reserved) for (const mac of r.macs) usedMacs.add(mac);
+	const networks = assignMacs(name, resolveStartNetworks(opts.networks, opts.network), usedMacs);
+	return { portBase, ports, networks };
+}
+
+/** Choose a new machine's resources and take its machine lock with them recorded in
+ *  it, all while holding the data-dir allocation lock (#140).
+ *
+ *  Without this, two concurrent creations both read the same machine list, both probe
+ *  the same free ports, and both pick the same block; one QEMU then fails its
+ *  `hostfwd` bind. Nothing persists the choice until `saveMachine()`, which for
+ *  `start()` is after the download and the spawn, so the choice itself has to be
+ *  visible: the machine lock carries it as a reservation, `listReservations()` reads
+ *  it, and it ends when the lock is released — by which time `machine.json` holds it,
+ *  or the creation failed and there is nothing left to hold. A crashed creator's
+ *  reservation dies with its pid.
+ *
+ *  The machine lock is fail-fast. A live holder is another create of the same name. */
+export async function claimNewMachine(
+	name: string,
+	op: Extract<LockOperation, "add" | "start" | "foreground">,
+	opts: StartOptions,
+): Promise<{ lock: HeldLock; portBase: number; ports: Record<string, PortMapping>; networks: NetworkConfig[] }> {
+	ensureDir(getDataDir());
+	const allocation = await acquireLock(allocationLockPath(), "allocate", {
+		waitMs: ALLOCATION_LOCK_WAIT_MS,
+		subject: "The port allocator",
+	});
+	try {
+		const picked = await pickNewMachineResources(name, opts);
+		const machineDir = getMachineDir(name);
+		const lockOpts = {
+			...machineLockOptions(name, machineDir),
+			reserve: {
+				portBase: picked.portBase,
+				macs: picked.networks.flatMap((n) => (n.mac ? [n.mac] : [])),
+			},
+		};
+		// The lock lives in the directory, so the directory comes first. A refusal here
+		// means a live holder owns the directory — a create of the same name, or a
+		// remove — and it, not this call, cleans it up. A remove renames the directory
+		// away in one step; if that lands between the two lines, make a fresh one.
+		let lock: HeldLock | undefined;
+		for (let tries = 0; !lock; tries++) {
+			ensureDir(machineDir);
+			try {
+				lock = acquireLockNow(machineLockPath(machineDir), op, lockOpts);
+			} catch (e) {
+				if (!(e instanceof QuickCHRError && e.code === "MACHINE_NOT_FOUND") || tries >= 2) throw e;
+			}
+		}
+		// Another create of this name may have finished between the caller's existence
+		// check and this lock.
+		if (existsSync(join(machineDir, "machine.json"))) {
+			lock.release();
+			throw new QuickCHRError("MACHINE_EXISTS", `Machine "${name}" was created by another process while this one was starting.`);
+		}
+		return { lock, ...picked };
+	} finally {
+		allocation.release();
+	}
+}
+
 /**
  * Main entry point for managing MikroTik CHR virtual machines via QEMU.
  *
@@ -1488,6 +1985,7 @@ export class QuickCHR {
 		// add() always creates, so the full name rules apply before any I/O.
 		if (opts.name !== undefined) assertValidResourceName(opts.name, "machine");
 
+		warnVersionWithChannel(opts, createLogger(opts.onProgress));
 		let version: string;
 		if (opts.version) {
 			if (!isValidVersion(opts.version)) {
@@ -1500,13 +1998,10 @@ export class QuickCHR {
 		}
 
 		const arch: Arch = resolveArch(opts.arch);
-		requireQemu(arch);
-		if (arch === "arm64") requireFirmware();
-		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
+		assertRouterOs6Arch(version, arch);
 		const resolvedDeviceMode = resolveDeviceModeOptions(opts.deviceMode);
 		const hasDeviceModeProvisioning = shouldApplyDeviceMode(resolvedDeviceMode);
-
-		if (hasProvisioningMutations({
+		const mutations = {
 			installAllPackages: opts.installAllPackages,
 			packages: opts.packages,
 			hasDeviceModeProvisioning,
@@ -1514,17 +2009,15 @@ export class QuickCHR {
 			disableAdmin: opts.disableAdmin,
 			license: opts.license,
 			secureLogin: opts.secureLogin,
-		})) {
-			assertProvisioningSupportedVersion(version, describeProvisioningOperation({
-				installAllPackages: opts.installAllPackages,
-				packages: opts.packages,
-				hasDeviceModeProvisioning,
-				user: opts.user,
-				disableAdmin: opts.disableAdmin,
-				license: opts.license,
-				secureLogin: opts.secureLogin,
-			}));
+		};
+		// Version refusals before host checks: a request that can never succeed should
+		// say why, not first ask for QEMU to be installed.
+		if (hasProvisioningMutations(mutations)) {
+			assertProvisioningSupportedVersion(version, describeProvisioningOperation(mutations));
 		}
+		requireQemu(arch);
+		if (arch === "arm64") requireFirmware();
+		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
 
 		const existingNames = listMachineNames();
 		const name = opts.name ?? generateMachineName(version, arch, existingNames);
@@ -1540,24 +2033,29 @@ export class QuickCHR {
 				: new QuickCHRError("MACHINE_EXISTS", `Machine "${name}" already exists. Use 'quickchr start ${name}' to start it.`);
 		}
 
-		const usedBases = getUsedPortBases();
-		const portBase = opts.portBase ?? await findAvailablePortBlock(usedBases, opts.excludePorts, opts.extraPorts);
-		validateExplicitExtraPorts(opts.extraPorts, portBase, opts.excludePorts, loadAllMachines(), name);
-		const ports = buildPortMappings(portBase, opts.excludePorts, opts.extraPorts);
-
 		const machineDir = getMachineDir(name);
-		assertSufficientQuickchrStorage(`prepare CHR ${name}`);
-		ensureDir(machineDir);
-		const lockPath = join(machineDir, ".start-lock");
-		acquireLock(lockPath);
+		// Held until machine.json is saved: it reserves the boot disk's bytes and pins the
+		// image against a concurrent eviction (storage-lease.ts).
+		const storageLease = admitStorage(
+			`prepare CHR ${name}`,
+			estimateMachineCreation({ version, arch, packages: !!(opts.installAllPackages || opts.packages?.length) }),
+		);
+		let claimed: Awaited<ReturnType<typeof claimNewMachine>>;
+		try {
+			claimed = await claimNewMachine(name, "add", opts);
+		} catch (err) {
+			storageLease.release();
+			throw err;
+		}
+		const { lock, portBase, ports, networks } = claimed;
 		try {
 			const cachedImg = await ensureCachedImage(version, arch);
-			copyImageToMachine(cachedImg, machineDir);
 			const diskArtifacts = await ensureConfiguredDisks(
 				machineDir,
 				diskOpts.bootSize,
 				diskOpts.extraDisks,
 				diskOpts.bootDiskFormat,
+				{ booted: false, factoryImage: async () => cachedImg },
 			);
 
 			const state: MachineState = {
@@ -1566,7 +2064,7 @@ export class QuickCHR {
 				arch,
 				cpu: opts.cpu ?? 1,
 				mem: defaultMem(arch, opts.mem),
-				networks: assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs()),
+				networks,
 				ports,
 				packages: opts.packages ?? [],
 				installAllPackages: opts.installAllPackages,
@@ -1597,11 +2095,12 @@ export class QuickCHR {
 			// directory it was supposed to clean up. Nothing runs after saveMachine()
 			// but `return state`, so a readable file here means the create succeeded.
 			if (isOrphanMachineDir(name)) {
-				try { rmSync(machineDir, { recursive: true, force: true }); } catch { /* best effort */ }
+				try { removeState(name); } catch { /* best effort */ }
 			}
 			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
+			storageLease.release();
 		}
 	}
 
@@ -1609,7 +2108,9 @@ export class QuickCHR {
 	 * Start a new or existing CHR instance.
 	 *
 	 * The returned {@link ChrInstance} is REST-ready: all provisioning (packages, license,
-	 * device-mode, user) has completed before this promise resolves.
+	 * device-mode, user) has completed before this promise resolves. Two exceptions:
+	 * `wait: false` resolves once QEMU is running and leaves readiness to the caller, and
+	 * a RouterOS 6 guest (boot-only, no REST) is ready when its native API answers a login.
 	 * Callers do not need to call {@link ChrInstance.waitForBoot} again unless they have
 	 * stopped and restarted the instance manually. Disk options (`bootSize`, `extraDisks`)
 	 * apply when creating a new machine and require `qemu-img` on the host.
@@ -1623,6 +2124,13 @@ export class QuickCHR {
 			throw new QuickCHRError("INVALID_NAME", `Invalid machine name "${opts.name}" — names cannot start with "-" (it would be read as a flag)`);
 		}
 
+		if (opts.wait === false && opts.background === false) {
+			throw new QuickCHRError(
+				"INVALID_ARGUMENT",
+				"--no-wait (wait: false) cannot be combined with --fg (background: false): a foreground start holds the serial console until QEMU exits, so there is nothing to return early from.",
+			);
+		}
+
 		const logger = createLogger(opts.onProgress);
 
 		// Before any download or disk work: a named socket whose two ends are already
@@ -1638,6 +2146,7 @@ export class QuickCHR {
 		const hasDeviceModeProvisioning = shouldApplyDeviceMode(resolvedDeviceMode);
 
 		// Resolve version
+		warnVersionWithChannel(opts, logger);
 		let version: string;
 		if (opts.version) {
 			if ((CHANNELS as readonly string[]).includes(opts.version)) {
@@ -1655,7 +2164,7 @@ export class QuickCHR {
 			version = await resolveVersion(channel);
 		}
 
-		if (hasProvisioningMutations({
+		const mutations = {
 			installAllPackages: opts.installAllPackages,
 			packages: opts.packages,
 			hasDeviceModeProvisioning,
@@ -1663,29 +2172,20 @@ export class QuickCHR {
 			disableAdmin: opts.disableAdmin,
 			license: opts.license,
 			secureLogin: opts.secureLogin,
-		})) {
-			assertProvisioningSupportedVersion(version, describeProvisioningOperation({
-				installAllPackages: opts.installAllPackages,
-				packages: opts.packages,
-				hasDeviceModeProvisioning,
-				user: opts.user,
-				disableAdmin: opts.disableAdmin,
-				license: opts.license,
-				secureLogin: opts.secureLogin,
-			}));
+		};
+		if (hasProvisioningMutations(mutations)) {
+			assertProvisioningSupportedVersion(version, describeProvisioningOperation(mutations));
+			assertWaitAllowsProvisioning(opts, describeProvisioningOperation(mutations));
 		}
 
 		// Resolve architecture
 		const arch: Arch = resolveArch(opts.arch);
-		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
-
-		// Check prerequisites (skip for dry-run — no QEMU needed)
-		if (!opts.dryRun) {
-			requireQemu(arch);
-			if (arch === "arm64") {
-				requireFirmware();
-			}
-		}
+		// Host prerequisites are checked just before each launch below, after every
+		// refusal: a request that cannot succeed says why before asking for QEMU.
+		const requireHostFor = (target: Arch) => {
+			requireQemu(target);
+			if (target === "arm64") requireFirmware();
+		};
 
 		// Resolve name
 		const existingNames = listMachineNames();
@@ -1696,20 +2196,45 @@ export class QuickCHR {
 		// Check if machine already exists
 		const existing = loadMachine(name);
 		if (existing) {
+			// Both paths below re-launch a guest quickchr did not just create, so neither
+			// can run provisioning. Refuse before either of them: dropping the options in
+			// silence is what #176 removes, and the running-machine path is the quieter of
+			// the two — it returns a handle without so much as a boot.
+			const request = {
+				installAllPackages: opts.installAllPackages,
+				packages: opts.packages,
+				deviceMode: opts.deviceMode,
+				user: opts.user,
+				disableAdmin: opts.disableAdmin,
+				license: opts.license,
+				secureLogin: opts.secureLogin,
+			};
+			// Version before window: on a version that can never be provisioned, the
+			// window refusal's `quickchr clean` route leads to a second refusal (#182).
+			if (hasProvisioningRequest(request)) {
+				assertProvisioningSupportedVersion(existing.version, describeProvisioningOperation({
+					...request,
+					hasDeviceModeProvisioning: shouldApplyDeviceMode(resolveDeviceModeOptions(request.deviceMode)),
+				}));
+			}
+			const satisfied = assertProvisioningWindow(existing, request);
+			for (const ask of satisfied) {
+				(logger ?? createLogger()).status(`${ask.description} is already applied — nothing to do.`);
+			}
 			if (isMachineRunning(existing)) {
 				return createInstance(existing);
 			}
 			// First boot of add()-created machine: apply pending provisioning from stored state
-			if (!existing.lastStartedAt) {
-				const pendingOpts = {
-					installAllPackages: opts.installAllPackages ?? existing.installAllPackages,
-					packages: opts.packages?.length ? opts.packages : (existing.packages.length > 0 ? existing.packages : undefined),
-					deviceMode: opts.deviceMode ?? existing.deviceMode,
-					user: opts.user ?? existing.user,
-					disableAdmin: opts.disableAdmin ?? existing.disableAdmin,
+			if (isProvisioningWindowOpen(existing)) {
+				const pendingOpts = pendingProvisioningFor(existing, {
+					installAllPackages: opts.installAllPackages,
+					packages: opts.packages,
+					deviceMode: opts.deviceMode,
+					user: opts.user,
+					disableAdmin: opts.disableAdmin,
 					license: opts.license,
-					secureLogin: opts.secureLogin ?? existing.secureLogin,
-				};
+					secureLogin: opts.secureLogin,
+				});
 				const hasPending = !!(
 					pendingOpts.installAllPackages ||
 					(pendingOpts.packages?.length ?? 0) > 0 ||
@@ -1720,49 +2245,43 @@ export class QuickCHR {
 					pendingOpts.secureLogin === true
 				);
 				if (hasPending) {
+					// Before the boot, not after it: `_provisionInstance()` re-checks the
+					// version, but only once the guest is up — on RouterOS 6 that is a
+					// download-free boot spent on a refusal known in advance.
+					const pendingMutations = {
+						...pendingOpts,
+						hasDeviceModeProvisioning: shouldApplyDeviceMode(resolveDeviceModeOptions(pendingOpts.deviceMode)),
+					};
+					assertProvisioningSupportedVersion(existing.version, describeProvisioningOperation(pendingMutations));
+					assertWaitAllowsProvisioning(opts, describeProvisioningOperation(pendingMutations), existing.name);
+					requireHostFor(existing.arch);
 					return QuickCHR._launchExisting(existing, opts.background ?? true, pendingOpts, logger);
 				}
 			}
 			// Exists but stopped — restart it
-			return QuickCHR._launchExisting(existing, opts.background ?? true, undefined, logger);
+			requireHostFor(existing.arch);
+			return QuickCHR._launchExisting(existing, opts.background ?? true, undefined, logger, opts.wait ?? true);
 		}
 
-		// Allocate port block
-		const usedBases = getUsedPortBases();
-		const portBase = opts.portBase
-			? opts.portBase
-			: await findAvailablePortBlock(
-				usedBases,
-				opts.excludePorts,
-				opts.extraPorts,
-			);
-
-		validateExplicitExtraPorts(
-			opts.extraPorts,
-			portBase,
-			opts.excludePorts,
-			loadAllMachines(),
-			name,
-		);
-
-		const ports = buildPortMappings(
-			portBase,
-			opts.excludePorts,
-			opts.extraPorts,
-		);
+		assertRouterOs6Arch(version, arch);
+		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
+		if (!opts.dryRun) requireHostFor(arch);
 
-		// Dry run — return instance handle without actually spawning
+		// Dry run — return instance handle without actually spawning. Nothing is
+		// claimed: a dry run persists nothing for another create to collide with.
 		if (opts.dryRun) {
 			const machineDir = getMachineDir(name);
+			const { portBase, ports, networks } = await pickNewMachineResources(name, opts);
 			const state: MachineState = {
 				name,
 				version,
 				arch,
 				cpu: opts.cpu ?? 1,
 				mem: defaultMem(arch, opts.mem),
-				networks: assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs()),
+				networks,
 				ports,
 				packages: opts.packages ?? [],
+				installAllPackages: opts.installAllPackages,
 				deviceMode: requestedDeviceMode,
 				user: opts.user,
 				disableAdmin: opts.disableAdmin,
@@ -1780,13 +2299,40 @@ export class QuickCHR {
 			return createInstance(state);
 		}
 
-		// Acquire a lock to prevent concurrent starts of the same machine
 		const machineDir = getMachineDir(name);
-		assertSufficientQuickchrStorage(`start CHR ${name}`);
+		// Held until machine.json is saved — after the spawn, or in the foreground once
+		// QEMU exits — and released on failure: see add().
+		const storageLease = admitStorage(
+			`start CHR ${name}`,
+			estimateMachineCreation({ version, arch, packages: !!(opts.installAllPackages || opts.packages?.length) }),
+			{ logger: logger ? (message: string) => logger.status(message) : undefined },
+		);
 		const dirCreatedHere = !existsSync(machineDir);
-		ensureDir(machineDir);
-		const lockPath = join(machineDir, ".start-lock");
-		acquireLock(lockPath);
+
+		const background = opts.background ?? true;
+
+		// Provisioning includes any work that requires the machine to have booted first.
+		// When foreground mode is requested WITH provisioning, we must boot in background,
+		// provision (packages/user/license), then attach the serial socket to stdio.
+		// Without provisioning, foreground mode runs QEMU with stdio directly (classic path).
+		const hasProvisioning = !!(
+			opts.installAllPackages ||
+			(opts.packages && opts.packages.length > 0) ||
+			opts.user ||
+			opts.disableAdmin ||
+			opts.license ||
+			hasDeviceModeProvisioning ||
+			opts.secureLogin === true
+		);
+
+		let claimed: Awaited<ReturnType<typeof claimNewMachine>>;
+		try {
+			claimed = await claimNewMachine(name, !background && !hasProvisioning ? "foreground" : "start", opts);
+		} catch (err) {
+			storageLease.release();
+			throw err;
+		}
+		const { lock, portBase, ports, networks: networkConfigs } = claimed;
 		// Endpoints are claimed before QEMU is spawned, because resolution needs to know
 		// which end this machine holds. A launch that fails before its state is persisted
 		// has no instance lifecycle to release them later, so a failed start would leave a
@@ -1797,36 +2343,18 @@ export class QuickCHR {
 
 		// Download and prepare image
 		const cachedImg = await ensureCachedImage(version, arch, undefined, logger);
-		copyImageToMachine(cachedImg, machineDir);
 
-		// Prepare disks (boot resize + extra disks)
+		// Build the boot disk from the cache (resized if asked) and any extra disks
 		const diskArtifacts = await ensureConfiguredDisks(
 			machineDir,
 			diskOpts.bootSize,
 			diskOpts.extraDisks,
 			diskOpts.bootDiskFormat,
+			{ booted: false, factoryImage: async () => cachedImg },
 		);
 		const bootDisk = diskArtifacts.bootDisk;
 		const extraDiskConfigs = diskArtifacts.extraDisks;
 
-		// Build machine config
-		const background = opts.background ?? true;
-
-		// Provisioning includes any work that requires the machine to have booted first.
-		// When foreground mode is requested WITH provisioning, we must boot in background,
-		// provision (packages/user/license), then attach the serial socket to stdio.
-		// Without provisioning, foreground mode runs QEMU with stdio directly (classic path).
-		const hasProvisioning = !!(
-			opts.installAllPackages ||
-			(opts.packages && opts.packages.length > 0) ||
-			opts.user ||
-			opts.disableAdmin ||
-			opts.license ||
-			hasDeviceModeProvisioning ||
-			opts.secureLogin === true
-		);
-
-		const networkConfigs = assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs());
 		if (hasProvisioning && !hasUserModeNetwork(networkConfigs)) {
 			throw new QuickCHRError(
 				"NETWORK_UNAVAILABLE",
@@ -1845,6 +2373,7 @@ export class QuickCHR {
 			networks: networkConfigs,
 			ports,
 			packages: opts.packages ?? [],
+			installAllPackages: opts.installAllPackages,
 			deviceMode: requestedDeviceMode,
 			user: opts.user,
 			disableAdmin: opts.disableAdmin,
@@ -1912,8 +2441,10 @@ export class QuickCHR {
 
 		saveMachine(state);
 		unpersistedSocketClaim = undefined;
+		storageLease.release();
 
 		const instance = createInstance(state);
+		if (opts.wait === false) return instance;
 
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
 
@@ -1963,7 +2494,7 @@ export class QuickCHR {
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				await cleanupAfterBootFailure(instance, name, failure) +
+				await cleanupAfterBootFailure(instance, name, failure, { kind: "remove-new" }) +
 				`\n${failure.summary}`,
 			);
 		}
@@ -1987,15 +2518,20 @@ export class QuickCHR {
 		} catch { /* never propagate */ }
 
 		if (hasProvisioning) {
-			await QuickCHR._provisionInstance(instance, state, {
-				installAllPackages: opts.installAllPackages,
-				packages: opts.packages,
-				deviceMode: requestedDeviceMode,
-				user: opts.user,
-				disableAdmin: opts.disableAdmin,
-				license: opts.license,
-				secureLogin: opts.secureLogin,
-			}, launchConfig, logger);
+			try {
+				await QuickCHR._provisionInstance(instance, state, {
+					installAllPackages: opts.installAllPackages,
+					packages: opts.packages,
+					deviceMode: requestedDeviceMode,
+					user: opts.user,
+					disableAdmin: opts.disableAdmin,
+					license: opts.license,
+					secureLogin: opts.secureLogin,
+				}, launchConfig, logger);
+			} catch (err) {
+				// This call created the machine, so a failed run takes it away again.
+				throw await failProvisioning(err, instance, undefined);
+			}
 		}
 
 		// Foreground + provisioning: all provisioning is done in background mode.
@@ -2003,12 +2539,12 @@ export class QuickCHR {
 		// QEMU mux console (Ctrl-A X to quit, Ctrl-A C for monitor — standard QEMU
 		// shortcuts that are well-documented and googleable).
 		if (!background && hasProvisioning) {
-			await instance.stop();
+			await stopUnderLock(state);
 			// Brief pause for QEMU to flush and release the disk image
 			await Bun.sleep(1000);
-			// Release lock before re-launching — _launchExisting acquires its own.
-			// The outer finally block will attempt a second unlink; that is harmless.
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			// Release the lock before re-launching — _launchExisting acquires its own.
+			// The outer finally releases again, which is a no-op.
+			lock.release();
 			return QuickCHR._launchExisting(state, false, undefined, logger);
 		}
 
@@ -2026,11 +2562,12 @@ export class QuickCHR {
 			// that already exist, and a directory this call did not create is never ours
 			// to delete, whatever state it is in.
 			if (dirCreatedHere && isOrphanMachineDir(name)) {
-				try { rmSync(machineDir, { recursive: true, force: true }); } catch { /* best effort */ }
+				try { removeState(name); } catch { /* best effort */ }
 			}
 			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
+			storageLease.release();
 		}
 	}
 
@@ -2052,6 +2589,9 @@ export class QuickCHR {
 		logger?: ProgressLogger,
 	): Promise<void> {
 		const log = logger ?? createLogger();
+		// What actually ran, persisted at the end as MachineState.provisioning — the
+		// record that says this guest has been provisioned, and with what (#176).
+		const applied: ProvisioningStep[] = [];
 		const resolvedDeviceMode = resolveDeviceModeOptions(opts.deviceMode);
 		const hasDeviceModeProvisioning = shouldApplyDeviceMode(resolvedDeviceMode);
 		assertProvisioningSupportedVersion(machineState.version, describeProvisioningOperation({
@@ -2082,6 +2622,7 @@ export class QuickCHR {
 				saveMachine(current);
 			}
 			machineState.packages = installed;
+			applied.push("packages");
 		} else if (opts.packages && opts.packages.length > 0) {
 			const installed = await installPackages(opts.packages, machineState.version, machineState.arch, chrPorts.ssh, chrPorts.http, log);
 			await waitForBootWithProgress(instance, bootTimeout, log, "  Waiting for CHR to reboot after package installation...");
@@ -2091,10 +2632,14 @@ export class QuickCHR {
 				saveMachine(current);
 			}
 			machineState.packages = installed;
+			applied.push("packages");
 		}
 
 		if (hasDeviceModeProvisioning) {
-			await applyDeviceMode(instance, machineState, resolvedDeviceMode, launchConfig, log);
+			// Factory admin on purpose: this runs at step 2 and the user step is step 4,
+			// so `machineState.user` names an account that does not exist yet.
+			await applyDeviceMode(instance, machineState, resolvedDeviceMode, launchConfig, log, FACTORY_AUTH_HEADER);
+			applied.push("deviceMode");
 		}
 
 		if (opts.license) {
@@ -2123,6 +2668,7 @@ export class QuickCHR {
 					saveMachine(current);
 				}
 				machineState.licenseLevel = actualLevel as LicenseLevel;
+				applied.push("license");
 				log.status(`  License applied: free → ${actualLevel}`);
 			} catch (e) {
 				if (e instanceof QuickCHRError) throw e;
@@ -2134,6 +2680,9 @@ export class QuickCHR {
 		}
 
 		if (opts.user || opts.disableAdmin || opts.secureLogin === true) {
+			if (opts.user) applied.push("user");
+			if (opts.disableAdmin) applied.push("disableAdmin");
+			if (opts.secureLogin === true) applied.push("secureLogin");
 			const result = await provision(chrPorts.http, machineState.name, opts.user, opts.disableAdmin, opts.secureLogin, log, machineState.machineDir, machineState.portBase, chrPorts.ssh);
 			if (result.user || result.managedSshKey) {
 				// Persist user info + managed SSH key fact in state (password placeholder —
@@ -2161,6 +2710,11 @@ export class QuickCHR {
 				}
 			}
 		}
+
+		// Stamped only here, after every requested step returned. A run that throws
+		// leaves the record absent, and the caller rolls the whole run back
+		// (`rollbackFailedProvisioning()`), so the retry starts from a factory disk.
+		recordProvisioning(machineState, applied);
 	}
 
 	/** Re-launch an existing stopped machine. */
@@ -2177,41 +2731,73 @@ export class QuickCHR {
 			secureLogin?: boolean;
 		},
 		logger?: ProgressLogger,
+		wait = true,
 	): Promise<ChrInstance> {
-		const lockPath = join(state.machineDir, ".start-lock");
-		acquireLock(lockPath);
+		const wantsProvisioning = (opts: typeof provisioningOpts) => !!(
+			opts && (
+				opts.installAllPackages ||
+				(opts.packages?.length ?? 0) > 0 ||
+				opts.deviceMode ||
+				opts.user ||
+				opts.disableAdmin ||
+				opts.license ||
+				opts.secureLogin === true
+			)
+		);
+		let hasProvisioning = wantsProvisioning(provisioningOpts);
+		const lock = acquireLockNow(
+			machineLockPath(state.machineDir),
+			!background && !hasProvisioning ? "foreground" : "start",
+			machineLockOptions(state.name, state.machineDir),
+		);
 		// Same pre-persistence window as start(): a relaunch that claims an endpoint and
 		// then fails to spawn would keep it, with no instance to release it.
 		let unpersistedSocketClaim: MachineState | undefined;
 		try {
 
-		const diskPath = join(state.machineDir, "disk.img");
-		if (!existsSync(diskPath)) {
-			throw new QuickCHRError("MACHINE_NOT_FOUND", `Disk image not found for "${state.name}"`);
+		// `state` is the caller's snapshot, read before the lock was taken; everything
+		// below acts on it, `state.pid` included (#180). Re-read it, and if another
+		// start got the machine running in between, hand back that one rather than
+		// booting a second QEMU on the same disk.
+		assertSameMachine(state);
+		refreshMachineState(state);
+		if (isMachineRunning(state)) return createInstance(state);
+		// `provisioningOpts` was worked out from that snapshot too. If another start
+		// booted the machine in between, the window is shut and running them would be
+		// a second first boot: check them against the machine as it is now, and drop
+		// whatever that start already applied.
+		if (provisioningOpts && !isProvisioningWindowOpen(state)) {
+			assertProvisioningWindow(state, provisioningOpts);
+			provisioningOpts = undefined;
+			hasProvisioning = false;
 		}
 
+		// Checks the disk this machine boots from — a qcow2 machine needs only boot.qcow2
+		// (#200) — and refuses, rather than rebuilds, a booted machine's missing disk.
 		const diskArtifacts = await ensureConfiguredDisks(
 			state.machineDir,
 			state.bootSize,
 			state.extraDisks,
-			state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
+			bootDiskFormatOf(state),
+			{
+				booted: !isProvisioningWindowOpen(state),
+				factoryImage: () => ensureCachedImage(state.version, state.arch, undefined, logger),
+			},
 		);
 		const bootDisk = diskArtifacts.bootDisk;
 		const extraDiskConfigs = diskArtifacts.extraDisks;
 
-		const hasProvisioning = !!(
-			provisioningOpts && (
-				provisioningOpts.installAllPackages ||
-				(provisioningOpts.packages?.length ?? 0) > 0 ||
-				provisioningOpts.deviceMode ||
-				provisioningOpts.user ||
-				provisioningOpts.disableAdmin ||
-				provisioningOpts.license ||
-				provisioningOpts.secureLogin === true
-			)
-		);
 		// Always boot in background when provisioning is needed
 		const spawnBackground = hasProvisioning ? true : background;
+		// The record a failed first boot rolls back to — taken before this launch writes
+		// pid, status or lastStartedAt into `state`. Whenever the window is open, not only
+		// when there is provisioning to run: a boot timeout on an add()-created machine is
+		// the same failed first boot as a provisioning error, and resets the same way
+		// instead of deleting what `add` recorded (#182).
+		const beforeLaunch = isProvisioningWindowOpen(state) ? structuredClone(state) : undefined;
+		const bootFailureCleanup: BootFailureCleanup = beforeLaunch
+			? { kind: "reset-first-boot", restore: beforeLaunch }
+			: { kind: "preserve-existing" };
 
 		const platform = await detectPlatform();
 		const accel = await detectAccel(state.arch);
@@ -2263,6 +2849,7 @@ export class QuickCHR {
 		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
+		if (!wait) return instance;
 
 		// Always wait for boot in background mode — start() promises "REST-ready".
 		const bootTimeout = defaultBootTimeout(state.arch, provisioningOpts?.installAllPackages, accel);
@@ -2292,7 +2879,7 @@ export class QuickCHR {
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				await cleanupAfterBootFailure(instance, state.name, failure) +
+				await cleanupAfterBootFailure(instance, state.name, failure, bootFailureCleanup) +
 				`\n${failure.summary}`,
 			);
 		}
@@ -2314,7 +2901,11 @@ export class QuickCHR {
 		} catch { /* never propagate */ }
 
 		if (hasProvisioning && provisioningOpts) {
-			await QuickCHR._provisionInstance(instance, state, provisioningOpts, launchConfig, logger);
+			try {
+				await QuickCHR._provisionInstance(instance, state, provisioningOpts, launchConfig, logger);
+			} catch (err) {
+				throw await failProvisioning(err, instance, beforeLaunch);
+			}
 		}
 
 		try {
@@ -2330,7 +2921,7 @@ export class QuickCHR {
 			if (unpersistedSocketClaim) unregisterSocketMembers(unpersistedSocketClaim);
 			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
 		}
 	}
 
@@ -2386,20 +2977,20 @@ export class QuickCHR {
 		// A create still in flight is indistinguishable from an orphan by directory
 		// contents alone — add()/start() write machine.json last, so the window between
 		// ensureDir() and saveMachine() looks exactly like a half-made machine. The
-		// start-lock is what tells them apart, so take it: acquireLock() throws
-		// MACHINE_LOCKED while a live creator holds it, and replaces one whose owner is
-		// gone — which is the case this recovery exists for.
-		const lockPath = join(getMachineDir(name), ".start-lock");
-		acquireLock(lockPath);
-
-		// The creator may have finished between the check above and the lock.
-		if (!isOrphanMachineDir(name)) {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
-			return false;
+		// machine lock is what tells them apart, so take it: it throws MACHINE_LOCKED
+		// while a live creator holds it, and takes over one whose owner is gone — which
+		// is the case this recovery exists for. No waiting: a live creator means this is
+		// not an orphan, and the answer is to let it finish.
+		const lock = acquireLockNow(machineLockPath(getMachineDir(name)), "remove-orphan", machineLockOptions(name, getMachineDir(name)));
+		try {
+			// The creator may have finished between the check above and the lock.
+			if (!isOrphanMachineDir(name)) return false;
+			removeState(name);
+			return true;
+		} finally {
+			// A no-op once the directory has gone; releases it if removal threw.
+			lock.release();
 		}
-
-		removeState(name);
-		return true;
 	}
 
 	/** Run doctor checks for prerequisites. */
@@ -2506,14 +3097,14 @@ export class QuickCHR {
 			detail: `${machines.length} instance${machines.length !== 1 ? "s" : ""} (${running} running, ${formatDiskSize(storage.machinesBytes)} on disk)`,
 		});
 
-		let storageDetail = `${storage.path}: ${formatDiskSize(storage.freeBytes)} free; ${formatQuickchrUsage(storage)}`;
+		let storageDetail = `${storage.statPath}: ${formatDiskSize(storage.freeBytes)} free; ${formatQuickchrUsage(storage)}`;
 		if (storage.status === "error") {
-			storageDetail += ` — below required minimum ${formatDiskSize(storage.recommendedFreeBytes)}`;
+			storageDetail += ` — below the ${formatDiskSize(storage.reserveBytes)} reserve: new machines and image downloads are refused (after evicting what the cache can spare)`;
 		} else if (storage.status === "warn") {
 			storageDetail += ` — low headroom (target ${formatDiskSize(storage.warningFreeBytes)} free)`;
 		}
 		checks.push({
-			label: storage.label === ".local" ? "Storage (.local)" : "Storage",
+			label: "Storage",
 			status: storage.status,
 			detail: storageDetail,
 		});