@tikoci/quickchr 0.4.7 → 0.5.0

package/src/lib/quickchr.ts

@@ -16,15 +16,19 @@ import type {
 	LicenseInput,
 	LicenseLevel,
 	MachineState,
+	NetworkConfig,
 	NetworkTopologyEntry,
+	PlatformInfo,
 	PortMapping,
+	ProvisioningStep,
 	QgaCommand,
 	ServiceEndpoint,
 	SnapshotInfo,
 	SshServiceEndpoint,
 	StartOptions,
 } from "./types.ts";
-import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./types.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 {
@@ -32,18 +36,25 @@ import {
 	isValidVersion,
 	generateMachineName,
 	assertProvisioningSupportedVersion,
+	assertRestAvailable,
+	assertRouterOs6Arch,
+	isRouterOs6,
 	PROVISIONING_FEATURE_LABEL,
 } from "./versions.ts";
-import { buildPortMappings, findAvailablePortBlock, resolveStartNetworks, resolveAllNetworks, buildHostfwdString, hasUserModeNetwork, validateExplicitExtraPorts } from "./network.ts";
+import { buildPortMappings, findAvailablePortBlock, resolveStartNetworks, resolveAllNetworks, assignMacs, buildHostfwdString, hasUserModeNetwork, validateExplicitExtraPorts, describeSocketTransport } from "./network.ts";
 import {
 	getUsedPortBases,
+	getUsedMacs,
 	saveMachine,
 	loadMachine,
 	loadAllMachines,
+	listUnreadableMachines,
 	removeMachine as removeState,
 	getMachineDir,
 	getMachinesDir,
 	listMachineNames,
+	isOrphanMachineDir,
+	listOrphanMachineDirs,
 	refreshAllStatuses,
 	isMachineRunning,
 	ensureDir,
@@ -54,23 +65,26 @@ import {
 import { ensureCachedImage, copyImageToMachine, 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 { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, waitForApiReady, readinessProbeFor, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, 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";
 import { restRequest, restGet, restPost } from "./rest.ts";
-import { createNamedSocket, getNamedSocket, addSocketMember, removeSocketMember } from "./socket-registry.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,
@@ -79,11 +93,19 @@ 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, readdirSync, rmSync, copyFileSync, writeFileSync, unlinkSync, openSync, writeSync, closeSync, readFileSync } from "node:fs";
+import { existsSync, rmSync, copyFileSync } 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 ---
@@ -133,6 +155,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[];
@@ -178,6 +210,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[] {
@@ -186,19 +234,97 @@ function getSocketNamedNetworks(state: MachineState): string[] {
 		.map((n) => (n.specifier as { type: "socket"; name: string }).name);
 }
 
+/** Refuse a start that a named socket has no room for, before any I/O.
+ *
+ *  Only a *new* member is refused: a machine already holding an endpoint is simply
+ *  restarting into its own slot. An unknown socket is left alone — `start()`
+ *  auto-creates it further down. */
+function assertNamedSocketsHaveRoom(opts: StartOptions, logger: ProgressLogger): void {
+	const named = resolveStartNetworks(opts.networks, opts.network)
+		.map((n) => n.specifier)
+		.filter((spec): spec is { type: "socket"; name: string } =>
+			typeof spec === "object" && spec !== null && spec.type === "socket");
+	for (const { name } of named) {
+		const entry = getNamedSocket(name);
+		if (!entry?.endpoints) continue;
+		if (opts.name && entry.endpoints.includes(opts.name)) continue;
+		if (entry.endpoints.includes(null)) continue;
+		const held = entry.endpoints.filter((m): m is string => m !== null);
+		logger.debug(`socket::${name} endpoints held by ${held.join(", ")}`);
+		throw new QuickCHRError(
+			"NETWORK_UNAVAILABLE",
+			`Named socket "${name}" is a ${entry.mode} link and carries 2 machines; ` +
+			`${held.join(" and ")} already hold both ends. ` +
+			`Stop one of them, or create an N-way segment with 'quickchr networks sockets create <name> --mode mcast'.`,
+		);
+	}
+}
+
+/** QEMU version for the binary this machine's arch will run on, when it can be read.
+ *  `-netdev dgram` needs 7.2, and a named socket should say so rather than failing at
+ *  spawn with a netdev QEMU does not recognize. */
+function qemuVersionForArch(platform: PlatformInfo, arch: Arch): string | undefined {
+	const bin = arch === "arm64" ? platform.qemuBinArm64 : platform.qemuBinX86;
+	return bin ? getQemuVersion(bin) : undefined;
+}
+
 function registerSocketMembers(state: MachineState): void {
 	for (const name of getSocketNamedNetworks(state)) {
 		try {
-			if (!getNamedSocket(name)) {
-				createNamedSocket(name, { autoCreated: true });
-			}
-			addSocketMember(name, state.name);
+			// Create-if-missing and join under one registry lock: two concurrent starts
+			// both pass a test-then-create, and both then claim the same endpoint slot.
+			joinNamedSocket(name, state.name, { autoCreated: true });
 		} catch (e) {
+			// A full two-member link is a refusal, not a warning: carrying on would spawn
+			// QEMU with no endpoint to bind, and on a `dgram` link a second machine
+			// binding the same path unlinks the first one's socket and steals the link
+			// with nothing logged on either side.
+			if (e instanceof QuickCHRError && e.code === "NETWORK_UNAVAILABLE") throw e;
 			console.warn(`Warning: failed to register socket member "${state.name}" on "${name}": ${e instanceof Error ? e.message : String(e)}`);
 		}
 	}
 }
 
+/** Report the transport each named socket resolved to.
+ *
+ *  #158's acceptance bar: nothing about a named socket should require opening a file
+ *  under the data dir. The field report that produced these issues had to read
+ *  `machine.json` to discover its link was UDP multicast, after ping had already
+ *  failed silently. */
+function reportSocketTransports(state: MachineState, logger: ProgressLogger): void {
+	for (const name of getSocketNamedNetworks(state)) {
+		const entry = getNamedSocket(name);
+		if (!entry) continue;
+		logger.status(`  Network socket::${name}: ${describeSocketTransport(entry, getSocketSlot(entry, state.name))}`);
+	}
+}
+
+/** Claim each named socket's endpoint, then resolve — releasing the claims if
+ *  resolution fails.
+ *
+ *  Membership is persisted *before* networks resolve, because the resolver needs to
+ *  know which end this machine holds. So a resolution that throws — a `dgram` link on
+ *  Windows, or on a QEMU older than 7.2 — would otherwise leave the machine holding an
+ *  endpoint it never used, and two failed starts would fill a link with machines that
+ *  are not running. */
+export function registerAndResolveNetworks(
+	state: MachineState,
+	ctx: { platform: PlatformInfo; qemuVersion?: string },
+	hostfwd: string,
+): NetworkConfig[] {
+	try {
+		// Inside the try, not before it: this claims one endpoint per named socket, so a
+		// machine on two links whose second link is full would otherwise keep the first
+		// claim — and the caller cannot clean it either, since it only learns about the
+		// claim once this returns.
+		registerSocketMembers(state);
+		return resolveAllNetworks(state.networks, { ...ctx, machine: state.name }, hostfwd);
+	} catch (e) {
+		unregisterSocketMembers(state);
+		throw e;
+	}
+}
+
 function unregisterSocketMembers(state: MachineState): void {
 	for (const name of getSocketNamedNetworks(state)) {
 		try {
@@ -231,6 +357,193 @@ 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}`);
+	}
+	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"),
+	);
+
+	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);
@@ -319,14 +632,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,
@@ -412,9 +727,12 @@ function createInstance(state: MachineState): ChrInstance {
 		sshPort: ports.ssh,
 		portBase: state.portBase,
 		captureInterface: process.platform === "darwin" ? "lo0" : "any",
-		tzspGatewayIp: "10.0.2.2",
+		hostGatewayIp: 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);
@@ -435,97 +753,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);
-			}
-			// 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> {
@@ -541,6 +794,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
@@ -630,6 +884,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);
@@ -677,15 +934,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[]> {
@@ -772,8 +1076,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>> {
@@ -913,44 +1219,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;
@@ -1130,28 +1398,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}\`.`;
+	}
+	// 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}\`.`;
 	}
-	try { await instance.remove(); } catch { /* ignore */ }
-	return ` Machine "${name}" has been cleaned up automatically.`;
+}
+
+/** 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. */
@@ -1226,7 +1588,11 @@ async function buildLaunchConfigFromState(state: MachineState): Promise<QemuLaun
 	);
 	const platform = await detectPlatform();
 	const hostfwd = buildHostfwdString(state.ports);
-	const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
+	const resolvedNetworks = resolveAllNetworks(
+		state.networks,
+		{ platform, machine: state.name, qemuVersion: qemuVersionForArch(platform, state.arch) },
+		hostfwd,
+	);
 	return {
 		arch: state.arch,
 		machineDir: state.machineDir,
@@ -1241,26 +1607,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) {
@@ -1273,7 +1739,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"),
@@ -1303,6 +1769,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;
@@ -1319,10 +1801,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) {
@@ -1352,10 +1834,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) {
@@ -1367,6 +1849,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.
  *
@@ -1389,10 +1977,10 @@ export class QuickCHR {
 	 *  `extraDisks`) are materialized immediately and require `qemu-img` on the host. */
 	static async add(opts: StartOptions = {}): Promise<MachineState> {
 		opts = normalizeStartOptions(opts);
-		if (opts.name?.startsWith("-")) {
-			throw new QuickCHRError("INVALID_NAME", `Invalid machine name "${opts.name}" — names cannot start with "-"`);
-		}
+		// 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)) {
@@ -1405,13 +1993,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,
@@ -1419,34 +2004,33 @@ 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);
 		if (existingNames.includes(name)) {
-			throw new QuickCHRError("MACHINE_EXISTS", `Machine "${name}" already exists. Use 'quickchr start ${name}' to start it.`);
+			// A directory with no readable machine.json is a half-created machine, not a
+			// machine — `list` cannot show it and `start` cannot boot it, so saying
+			// "already exists" sends the user looking for something that is not there (#155).
+			throw isOrphanMachineDir(name)
+				? new QuickCHRError(
+					"MACHINE_EXISTS",
+					`Machine "${name}" has a leftover directory with no readable machine.json — a create that did not finish. Clear it with 'quickchr remove ${name}', then retry.`,
+				)
+				: 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);
+		const { lock, portBase, ports, networks } = await claimNewMachine(name, "add", opts);
 		try {
 			const cachedImg = await ensureCachedImage(version, arch);
 			copyImageToMachine(cachedImg, machineDir);
@@ -1463,7 +2047,7 @@ export class QuickCHR {
 				arch,
 				cpu: opts.cpu ?? 1,
 				mem: defaultMem(arch, opts.mem),
-				networks: resolveStartNetworks(opts.networks, opts.network),
+				networks,
 				ports,
 				packages: opts.packages ?? [],
 				installAllPackages: opts.installAllPackages,
@@ -1483,8 +2067,22 @@ export class QuickCHR {
 			};
 			saveMachine(state);
 			return state;
+		} catch (err) {
+			// A failed create must leave nothing behind: the directory exists from this
+			// call's ensureDir(), and without readable state it is invisible to `list`
+			// and unremovable by `remove` while still blocking re-add (#155).
+			//
+			// The test is "no *readable* machine.json", not "no machine.json" — a
+			// saveMachine() that died mid-write (disk full) leaves a truncated file, and
+			// a file-exists check would take that for a finished machine and strand the
+			// 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 { removeState(name); } catch { /* best effort */ }
+			}
+			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
 		}
 	}
 
@@ -1492,20 +2090,36 @@ 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.
 	 */
 	static async start(opts: StartOptions = {}): Promise<ChrInstance> {
 		opts = normalizeStartOptions(opts);
-		// Validate name early (before any I/O) so callers get a fast, clear error
+		// Cheap guard before any I/O: a name that reads as a flag is always a mistake.
+		// The full charset rules are applied below, but only when this call creates the
+		// machine — a machine named under the older, looser rules must still start.
 		if (opts.name?.startsWith("-")) {
-			throw new QuickCHRError("INVALID_NAME", `Invalid machine name "${opts.name}" — names cannot start with "-"`);
+			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
+		// taken cannot carry this machine, and #156's rule is that a start that cannot
+		// succeed should not first fetch 43 MB.
+		assertNamedSocketsHaveRoom(opts, logger);
+
 		const requestedDeviceMode = opts.deviceMode;
 		const resolvedDeviceMode = resolveDeviceModeOptions(requestedDeviceMode);
 		for (const warning of resolvedDeviceMode.warnings) {
@@ -1514,6 +2128,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)) {
@@ -1531,7 +2146,7 @@ export class QuickCHR {
 			version = await resolveVersion(channel);
 		}
 
-		if (hasProvisioningMutations({
+		const mutations = {
 			installAllPackages: opts.installAllPackages,
 			packages: opts.packages,
 			hasDeviceModeProvisioning,
@@ -1539,51 +2154,69 @@ 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();
 		const name = opts.name ?? generateMachineName(version, arch, existingNames);
+		// Only a *new* name has to satisfy the current rules — see the guard at the top.
+		if (!existingNames.includes(name)) assertValidResourceName(name, "machine");
 
 		// 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 ||
@@ -1594,49 +2227,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: resolveStartNetworks(opts.networks, opts.network),
+				networks,
 				ports,
 				packages: opts.packages ?? [],
+				installAllPackages: opts.installAllPackages,
 				deviceMode: requestedDeviceMode,
 				user: opts.user,
 				disableAdmin: opts.disableAdmin,
@@ -1654,29 +2281,10 @@ 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}`);
-		ensureDir(machineDir);
-		const lockPath = join(machineDir, ".start-lock");
-		acquireLock(lockPath);
-		try {
-
-		// Download and prepare image
-		const cachedImg = await ensureCachedImage(version, arch, undefined, logger);
-		copyImageToMachine(cachedImg, machineDir);
-
-		// Prepare disks (boot resize + extra disks)
-		const diskArtifacts = await ensureConfiguredDisks(
-			machineDir,
-			diskOpts.bootSize,
-			diskOpts.extraDisks,
-			diskOpts.bootDiskFormat,
-		);
-		const bootDisk = diskArtifacts.bootDisk;
-		const extraDiskConfigs = diskArtifacts.extraDisks;
+		const dirCreatedHere = !existsSync(machineDir);
 
-		// Build machine config
 		const background = opts.background ?? true;
 
 		// Provisioning includes any work that requires the machine to have booted first.
@@ -1693,7 +2301,33 @@ export class QuickCHR {
 			opts.secureLogin === true
 		);
 
-		const networkConfigs = resolveStartNetworks(opts.networks, opts.network);
+		const { lock, portBase, ports, networks: networkConfigs } = await claimNewMachine(
+			name,
+			!background && !hasProvisioning ? "foreground" : "start",
+			opts,
+		);
+		// 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
+		// machine holding an end of a link it never used — and two of those fill the link.
+		// Cleared once saveMachine() has committed the claim.
+		let unpersistedSocketClaim: MachineState | undefined;
+		try {
+
+		// Download and prepare image
+		const cachedImg = await ensureCachedImage(version, arch, undefined, logger);
+		copyImageToMachine(cachedImg, machineDir);
+
+		// Prepare disks (boot resize + extra disks)
+		const diskArtifacts = await ensureConfiguredDisks(
+			machineDir,
+			diskOpts.bootSize,
+			diskOpts.extraDisks,
+			diskOpts.bootDiskFormat,
+		);
+		const bootDisk = diskArtifacts.bootDisk;
+		const extraDiskConfigs = diskArtifacts.extraDisks;
+
 		if (hasProvisioning && !hasUserModeNetwork(networkConfigs)) {
 			throw new QuickCHRError(
 				"NETWORK_UNAVAILABLE",
@@ -1712,6 +2346,7 @@ export class QuickCHR {
 			networks: networkConfigs,
 			ports,
 			packages: opts.packages ?? [],
+			installAllPackages: opts.installAllPackages,
 			deviceMode: requestedDeviceMode,
 			user: opts.user,
 			disableAdmin: opts.disableAdmin,
@@ -1732,9 +2367,14 @@ export class QuickCHR {
 		const accel = await detectAccel(arch);
 		const note = accelNote(arch, accel);
 		if (note) logger.warn(note);
-		registerSocketMembers(state);
 		const hostfwd = buildHostfwdString(state.ports);
-		const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
+		const resolvedNetworks = registerAndResolveNetworks(
+			state,
+			{ platform, qemuVersion: qemuVersionForArch(platform, state.arch) },
+			hostfwd,
+		);
+		unpersistedSocketClaim = state;
+		reportSocketTransports(state, logger);
 
 		const launchConfig: QemuLaunchConfig = {
 			arch,
@@ -1757,9 +2397,15 @@ export class QuickCHR {
 
 		// Foreground (no provisioning): spawnQemu blocks until QEMU exits
 		if (!background && !hasProvisioning) {
+			// QEMU has already exited here — spawnQemu() blocks in foreground. A machine
+			// that is not running must not keep holding an end of a link: stop() and
+			// remove() unregister, and this path reaches "stopped" without going through
+			// either of them.
+			unregisterSocketMembers(state);
 			state.status = "stopped";
 			state.lastStartedAt = new Date().toISOString();
 			saveMachine(state);
+			unpersistedSocketClaim = undefined;
 			return createInstance(state);
 		}
 
@@ -1767,8 +2413,10 @@ export class QuickCHR {
 		state.lastStartedAt = new Date().toISOString();
 
 		saveMachine(state);
+		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
+		if (opts.wait === false) return instance;
 
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
 
@@ -1818,7 +2466,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}`,
 			);
 		}
@@ -1842,15 +2490,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.
@@ -1858,25 +2511,34 @@ 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);
 		}
 
 			return instance;
 		} catch (err) {
-			// Clean up orphaned machine directory if spawn failed before machine.json was saved
-			const machineJsonPath = join(machineDir, "machine.json");
-			if (!existsSync(machineJsonPath)) {
-				try { rmSync(machineDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			// Release an endpoint this launch claimed but never committed. stop()/remove()
+			// would do it for a machine that reached persisted state; one that did not has
+			// no instance to do it.
+			if (unpersistedSocketClaim) unregisterSocketMembers(unpersistedSocketClaim);
+			// Clean up an orphaned machine directory if the spawn failed before readable
+			// state was saved — same predicate as add()'s cleanup, so a truncated
+			// machine.json is not mistaken for a finished machine.
+			//
+			// `dirCreatedHere` is the difference from add(): start() also starts machines
+			// 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 { removeState(name); } catch { /* best effort */ }
 			}
 			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
 		}
 	}
 
@@ -1898,6 +2560,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({
@@ -1928,6 +2593,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...");
@@ -1937,10 +2603,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) {
@@ -1969,6 +2639,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;
@@ -1980,6 +2651,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 —
@@ -2007,6 +2681,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. */
@@ -2023,11 +2702,47 @@ 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 {
 
+		// `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;
+		}
+
 		const diskPath = join(state.machineDir, "disk.img");
 		if (!existsSync(diskPath)) {
 			throw new QuickCHRError("MACHINE_NOT_FOUND", `Disk image not found for "${state.name}"`);
@@ -2042,27 +2757,30 @@ export class QuickCHR {
 		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);
 		const note = accelNote(state.arch, accel);
 		if (note) (logger ?? createLogger()).warn(note);
-		registerSocketMembers(state);
 		const hostfwd = buildHostfwdString(state.ports);
-		const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
+		const resolvedNetworks = registerAndResolveNetworks(
+			state,
+			{ platform, qemuVersion: qemuVersionForArch(platform, state.arch) },
+			hostfwd,
+		);
+		unpersistedSocketClaim = state;
+		reportSocketTransports(state, logger ?? createLogger());
 
 		const launchConfig: QemuLaunchConfig = {
 			arch: state.arch,
@@ -2085,9 +2803,12 @@ export class QuickCHR {
 
 		// Foreground without provisioning: spawnQemu blocks until QEMU exits
 		if (!background && !hasProvisioning) {
+			// See the same branch in start(): QEMU has exited, so the endpoint goes back.
+			unregisterSocketMembers(state);
 			state.status = "stopped";
 			state.lastStartedAt = new Date().toISOString();
 			saveMachine(state);
+			unpersistedSocketClaim = undefined;
 			return createInstance(state);
 		}
 
@@ -2095,8 +2816,10 @@ export class QuickCHR {
 		state.status = "running";
 		state.lastStartedAt = new Date().toISOString();
 		saveMachine(state);
+		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);
@@ -2126,7 +2849,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}`,
 			);
 		}
@@ -2148,7 +2871,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 {
@@ -2160,8 +2887,11 @@ export class QuickCHR {
 		} catch { /* never propagate */ }
 
 		return instance;
+		} catch (err) {
+			if (unpersistedSocketClaim) unregisterSocketMembers(unpersistedSocketClaim);
+			throw err;
 		} finally {
-			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			lock.release();
 		}
 	}
 
@@ -2185,6 +2915,54 @@ export class QuickCHR {
 		return createInstance(state);
 	}
 
+	/** Machines whose `machine.json` is present but cannot be turned into state, each
+	 *  with the reason: the file would not read, the JSON is invalid, or it parsed into
+	 *  something that is not a machine.
+	 *
+	 *  `list()` skips these so one corrupt file cannot abort the enumeration; this is
+	 *  where they stay visible. `get(name)` still throws for such a machine — a lookup
+	 *  by name is not an enumeration (#165). */
+	static listUnreadable(): Array<{ name: string; error: string }> {
+		return listUnreadableMachines();
+	}
+
+	/** Names of machine directories with no readable `machine.json` — half-created
+	 *  machines that `list()` cannot show and `get()` cannot resolve (#155). */
+	static listOrphans(): string[] {
+		return listOrphanMachineDirs();
+	}
+
+	/** Delete a half-created machine directory. Returns false when `name` is a real
+	 *  machine (use `get(name)?.remove()`) or does not exist at all.
+	 *
+	 *  A crash or SIGKILL can strand a directory even with add()'s cleanup in place, and
+	 *  a stranded directory blocks re-add while being invisible to `list` — so clearing
+	 *  one must not require knowing that the data dir exists. */
+	static removeOrphan(name: string): boolean {
+		// Explicit, before the predicate: this deletes a directory tree, and `join()`
+		// turns ".." into the data dir itself. Say why rather than answering `false`.
+		assertPathSafeName(name, "machine");
+		if (!isOrphanMachineDir(name)) return false;
+
+		// 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
+		// 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();
+		}
+	}
+
 	/** Run doctor checks for prerequisites. */
 	static async doctor(): Promise<DoctorResult> {
 		const checks: DoctorResult["checks"] = [];
@@ -2373,29 +3151,20 @@ export class QuickCHR {
 		}
 
 		// Orphaned machine directories (have files but no machine.json)
-		const machinesDir = getMachinesDir();
-		if (existsSync(machinesDir)) {
-			const dirs = readdirSync(machinesDir, { withFileTypes: true })
-				.filter(e => e.isDirectory());
-			const orphans: string[] = [];
-			for (const dir of dirs) {
-				const mjPath = join(machinesDir, dir.name, "machine.json");
-				if (!existsSync(mjPath)) {
-					orphans.push(dir.name);
-				}
-			}
+		if (existsSync(getMachinesDir())) {
+			const orphans = listOrphanMachineDirs();
 			if (orphans.length > 0) {
-				const removeLines = orphans.map((o) => `  rm -rf ${join(machinesDir, o)}`).join("\n");
+				const removeLines = orphans.map((o) => `  quickchr remove ${o}`).join("\n");
 				checks.push({
 					label: "Orphaned machine dirs",
 					status: "warn",
-					detail: `${orphans.length} dir(s) without machine.json: ${orphans.join(", ")}\nRemove manually:\n${removeLines}`,
+					detail: `${orphans.length} dir(s) with no readable machine.json: ${orphans.join(", ")}\nClear them with:\n${removeLines}`,
 				});
 			} else {
 				checks.push({
 					label: "Machine state",
 					status: "ok",
-					detail: `${dirs.length} machine(s), no orphans`,
+					detail: `${listMachineNames().length} machine(s), no orphans`,
 				});
 			}
 		}