@tikoci/quickchr 0.4.6 → 0.4.8

package/src/lib/quickchr.ts

@@ -16,7 +16,9 @@ import type {
 	LicenseInput,
 	LicenseLevel,
 	MachineState,
+	NetworkConfig,
 	NetworkTopologyEntry,
+	PlatformInfo,
 	PortMapping,
 	QgaCommand,
 	ServiceEndpoint,
@@ -24,7 +26,8 @@ import type {
 	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 } from "./types.ts";
+import { assertValidResourceName, assertPathSafeName } 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 {
@@ -34,16 +37,20 @@ import {
 	assertProvisioningSupportedVersion,
 	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,
@@ -56,7 +63,8 @@ import { autoPruneIfOverCap } from "./cache.ts";
 import { resolveSetting } from "./settings.ts";
 import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
-import { monitorCommand, serialStreams, qgaCommand, channelEndpoint } from "./channels.ts";
+import { monitorCommand, serialStreams, qgaCommand, channelEndpoint, channelFileExists, channelPath } from "./channels.ts";
+import { captureBootFailure, newBootProbeStats, 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";
@@ -65,9 +73,9 @@ import { scpPush, scpPull } from "./scp.ts";
 import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, getInstanceCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
-import { consoleExec } from "./console.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 {
 	formatDeviceModeSelection,
@@ -79,9 +87,10 @@ import {
 	waitForDeviceModeApi,
 } from "./device-mode.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, writeFileSync, unlinkSync, openSync, writeSync, closeSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 // --- Architecture-aware defaults ---
@@ -184,19 +193,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 {
@@ -410,13 +497,16 @@ 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,
+		// Deprecated alias for hostGatewayIp (#26) — same value, removed no earlier
+		// than the next minor.
+		tzspGatewayIp: HOST_GATEWAY_IP,
 
-		async waitForBoot(timeoutMs?: number): Promise<boolean> {
+		async waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean> {
 			// Use resolved credentials so waitForBoot can validate the response body
 			// on authenticated machines (post-provisioning, post-install reboots).
 			const auth = resolveAuth(state);
-			return waitForBoot(ports.http, timeoutMs, auth.header);
+			return waitForBoot(ports.http, timeoutMs, auth.header, stats);
 		},
 
 		async waitFor(condition: () => Promise<boolean>, timeoutMs = 30_000): Promise<boolean> {
@@ -462,6 +552,10 @@ function createInstance(state: MachineState): ChrInstance {
 			if (state.pid && isMachineRunning(state)) {
 				await stopQemu(state.pid);
 			}
+			// Same invariant as stop()/remove(): a machine that is not running holds no
+			// endpoint. clean() stops QEMU directly rather than through stop(), so without
+			// this a cleaned machine keeps a pair link occupied and blocks its removal.
+			unregisterSocketMembers(state);
 			// NOTE: clean() deliberately does NOT delete efi-vars.fd. On the arm64 `virt`
 			// machine that file stores UEFI boot order (Boot0000 -> first virtio-blk-pci
 			// disk), not OS state; wiping it forces a full device scan (~480s) on the next
@@ -487,18 +581,43 @@ function createInstance(state: MachineState): ChrInstance {
 				state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
 			);
 
-			// Clean up stored instance credentials (re-provisioned on next start)
+			// 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;
 		},
 
 		async monitor(command: string): Promise<string> {
@@ -950,6 +1069,183 @@ async function waitForPidExit(pid: number, timeoutMs: number): Promise<boolean>
 	return false;
 }
 
+/** Where boot-failure reports land: `<dataDir>/failures/`, deliberately outside
+ *  any machine directory so `remove()` — which every integration test calls from
+ *  its `finally` — cannot delete the evidence it was written to explain (#79). */
+function bootFailureReportDir(): string {
+	return join(getDataDir(), "failures");
+}
+
+/**
+ * How long one credential candidate gets inside a single guest-exec call.
+ *
+ * `timeoutMs` is a budget for the whole call, not per attempt: `captureGuestSnapshot()`
+ * sizes its own budget assuming one exec costs at most what it passed in, so N
+ * candidates × the full timeout would spend the snapshot's entire budget on the
+ * first query. Untried candidates therefore share it, and once a credential is
+ * known to work it gets all of it — which is every query after the first.
+ *
+ * The floor is {@link CONSOLE_LOGIN_COST_MS} rather than a round number, because
+ * a share below the cost of a login cannot succeed **by construction** — and a
+ * candidate that can never succeed also never becomes the working one, so every
+ * later query repeats the same doomed division. The floor used to be 5 s against
+ * a measured 11.4 s login, which is why forensics reported "console unreachable"
+ * for guests that were answering serial in 10 ms (#69). A share this large is
+ * affordable only because `captureGuestSnapshot()` adds a login allowance to its
+ * query budget until the console answers; see `GUEST_LOGIN_ALLOWANCE_MS`.
+ *
+ * Exported for tests: this is the arithmetic the #69/B10 fix turns on, and it is
+ * otherwise reachable only through a live serial socket.
+ */
+export function credentialShareMs(timeoutMs: number, candidateCount: number, haveWorking: boolean): number {
+	if (haveWorking) return timeoutMs;
+	return Math.max(CONSOLE_LOGIN_COST_MS, Math.floor(timeoutMs / Math.max(1, candidateCount)));
+}
+
+/** Serial-console executor for boot forensics, or null when there is no serial
+ *  channel to talk to (foreground runs, or QEMU never got far enough).
+ *
+ *  Which account works depends on how far the failed boot got: a machine that
+ *  timed out before provisioning — and any machine after `clean()` — is factory
+ *  fresh and answers only to `admin` with an empty password, while a relaunch of
+ *  an already-provisioned machine needs its stored credentials. Rather than
+ *  guess, candidates are tried in order and the first that reaches a prompt is
+ *  reused for the rest of the snapshot. */
+function bootFailureGuestExec(state: MachineState): { exec: GuestExec; users: string[] } | null {
+	if (!channelFileExists(channelPath(state.machineDir, "serial"))) return null;
+
+	// Order matters only for speed — a wrong candidate costs a ~15 s login timeout
+	// before the next is tried. Stored credentials are the strongest evidence the
+	// machine is provisioned (provisioning stores them on success), so they lead;
+	// factory admin comes next because a cleaned machine has neither (`clean()`
+	// clears both the stored credentials and `state.user`), leaving `state.user`
+	// as the weakest case: a user configured on the machine but never provisioned
+	// onto the guest.
+	const candidates: { user: string; password: string }[] = [];
+	// Guarded even though secrets.ts already swallows unreadable/corrupt stores:
+	// this runs on the BOOT_TIMEOUT path *before* captureBootFailure(), so
+	// anything thrown here would replace the forensics report with an unrelated
+	// error — the exact failure mode the diagnostics modules exist to avoid.
+	let stored: { user: string; password: string } | null = null;
+	try {
+		stored = getInstanceCredentials(state.name);
+	} catch { /* no stored credentials — fall through to the other candidates */ }
+	if (stored) candidates.push(stored);
+	candidates.push({ user: "admin", password: "" });
+	if (state.user && state.user.name !== "admin" && state.user.password !== STORED_IN_SECRETS_PASSWORD) {
+		candidates.push({ user: state.user.name, password: state.user.password });
+	}
+
+	let working: { user: string; password: string } | undefined;
+	const exec: GuestExec = async (command, timeoutMs) => {
+		const order = working ? [working, ...candidates.filter((c) => c !== working)] : candidates;
+		const deadline = Date.now() + timeoutMs;
+		const share = credentialShareMs(timeoutMs, order.length, working !== undefined);
+		let lastError: unknown = new Error("no credential candidates");
+		for (const cred of order) {
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) break;
+			try {
+				const { output, framed } = await consoleExec(
+					state.machineDir, command, cred.user, cred.password, Math.min(share, remaining), state.portBase,
+				);
+				working = cred;
+				return { output, framed };
+			} catch (e) {
+				lastError = e;
+			}
+		}
+		throw lastError instanceof Error ? lastError : new Error(String(lastError));
+	};
+
+	return { exec, users: candidates.map((c) => c.user) };
+}
+
+/**
+ * Capture the boot-failure evidence set for a machine that is **already
+ * running** — a request that failed after the machine was declared REST-ready.
+ *
+ * Same instruments as the BOOT_TIMEOUT path (guest snapshot, per-port slirp
+ * classification, monitor state, QEMU liveness, embedded logs), because #69's
+ * one-line `ECONNRESET` has never been enough to say whether the reset came from
+ * the client, RouterOS `www`, or slirp — and every one of those instruments
+ * answers a different part of that. What it does *not* share is the boot
+ * budget's excuse for the machine looking healthy: {@link FailureTrigger} is
+ * required here, so the report always records which request died and what
+ * changed just before it.
+ *
+ * Does not stop, remove, or otherwise touch the machine — the caller owns its
+ * lifecycle and may well want to keep testing against it. Never throws;
+ * `captureBootFailure()` swallows its own failures.
+ *
+ * One trace it does leave, and the reason that matters more here than on the
+ * boot path: the guest snapshot logs in over the serial console, and a RouterOS
+ * console login survives the host socket closing. A boot-timeout capture is
+ * followed by `stop()`/`remove()`, so nothing outlives it; here the machine
+ * keeps running. Harmless — `consoleExec()` `/quit`s a session belonging to a
+ * different user before it logs in — but a later console interaction on this
+ * machine starts from an already-logged-in prompt, not a `Login:` one.
+ */
+export async function captureRunningFailure(
+	state: MachineState,
+	phase: string,
+	trigger: FailureTrigger,
+): Promise<BootFailureReport> {
+	// Approximate, and labelled as such in the field docs: lastStartedAt is
+	// stamped at spawn and lastBootMs measured from just before it, so their sum
+	// is REST-ready to within the few ms between those two statements. Both are
+	// absent on a machine that never completed a timed boot, in which case the
+	// field is simply omitted rather than guessed at.
+	const readyAt = state.lastStartedAt !== undefined && state.lastBootMs !== undefined
+		? Date.parse(state.lastStartedAt) + state.lastBootMs
+		: undefined;
+	const guest = bootFailureGuestExec(state);
+	return await captureBootFailure({
+		name: state.name,
+		machineDir: state.machineDir,
+		arch: state.arch,
+		accel: state.lastAccel ?? "unknown",
+		pid: state.pid,
+		httpPort: state.ports.http?.host,
+		portBase: state.portBase,
+		phase,
+		trigger: {
+			...trigger,
+			sinceReadyMs: trigger.sinceReadyMs
+				?? (readyAt !== undefined && Number.isFinite(readyAt) ? Date.now() - readyAt : undefined),
+		},
+		reportDir: bootFailureReportDir(),
+		monitorQuery: (cmd) => monitorCommand(state.machineDir, cmd, 3000, state.portBase),
+		forwards: Object.values(state.ports),
+		guestExec: guest?.exec,
+		guestUser: guest?.users.join(" → "),
+	});
+}
+
+/** 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(
+	instance: ChrInstance,
+	name: string,
+	failure: BootFailureReport,
+): Promise<string> {
+	try { await instance.stop(); } catch { /* ignore */ }
+	if (failure.preserved) {
+		return ` Machine "${name}" was preserved for diagnosis (QUICKCHR_PRESERVE_ON_FAILURE=1) — remove it with \`quickchr remove ${name}\`.`;
+	}
+	try { await instance.remove(); } catch { /* ignore */ }
+	return ` Machine "${name}" has been cleaned up automatically.`;
+}
+
 /** Wait for CHR to boot with periodic progress status updates every 20s. */
 async function waitForBootWithProgress(
 	instance: ChrInstance,
@@ -1022,7 +1318,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,
@@ -1185,9 +1485,8 @@ 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");
 
 		let version: string;
 		if (opts.version) {
@@ -1230,7 +1529,15 @@ export class QuickCHR {
 		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();
@@ -1259,7 +1566,7 @@ export class QuickCHR {
 				arch,
 				cpu: opts.cpu ?? 1,
 				mem: defaultMem(arch, opts.mem),
-				networks: resolveStartNetworks(opts.networks, opts.network),
+				networks: assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs()),
 				ports,
 				packages: opts.packages ?? [],
 				installAllPackages: opts.installAllPackages,
@@ -1279,6 +1586,20 @@ 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 { rmSync(machineDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			}
+			throw err;
 		} finally {
 			try { unlinkSync(lockPath); } catch { /* ignore */ }
 		}
@@ -1295,13 +1616,20 @@ export class QuickCHR {
 	 */
 	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)`);
 		}
 
 		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) {
@@ -1362,6 +1690,8 @@ export class QuickCHR {
 		// 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);
@@ -1430,7 +1760,7 @@ export class QuickCHR {
 				arch,
 				cpu: opts.cpu ?? 1,
 				mem: defaultMem(arch, opts.mem),
-				networks: resolveStartNetworks(opts.networks, opts.network),
+				networks: assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs()),
 				ports,
 				packages: opts.packages ?? [],
 				deviceMode: requestedDeviceMode,
@@ -1453,9 +1783,16 @@ export class QuickCHR {
 		// Acquire a lock to prevent concurrent starts of the same machine
 		const machineDir = getMachineDir(name);
 		assertSufficientQuickchrStorage(`start CHR ${name}`);
+		const dirCreatedHere = !existsSync(machineDir);
 		ensureDir(machineDir);
 		const lockPath = join(machineDir, ".start-lock");
 		acquireLock(lockPath);
+		// 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
@@ -1489,7 +1826,7 @@ export class QuickCHR {
 			opts.secureLogin === true
 		);
 
-		const networkConfigs = resolveStartNetworks(opts.networks, opts.network);
+		const networkConfigs = assignMacs(name, resolveStartNetworks(opts.networks, opts.network), getUsedMacs());
 		if (hasProvisioning && !hasUserModeNetwork(networkConfigs)) {
 			throw new QuickCHRError(
 				"NETWORK_UNAVAILABLE",
@@ -1528,9 +1865,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,
@@ -1553,9 +1895,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);
 		}
 
@@ -1563,13 +1911,15 @@ export class QuickCHR {
 		state.lastStartedAt = new Date().toISOString();
 
 		saveMachine(state);
+		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
 
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
 
 		// Always wait for boot in background mode — the JSDoc promises "REST-ready".
-		let booted = await instance.waitForBoot(bootTimeout);
+		const probe = newBootProbeStats();
+		let booted = await instance.waitForBoot(bootTimeout, probe);
 
 		// Hardware-accelerated runners (nested-KVM on CI, HVF on virtualized macOS
 		// runners) occasionally produce a single QEMU process that boots but never
@@ -1586,22 +1936,35 @@ export class QuickCHR {
 			({ pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper));
 			state.pid = pid;
 			saveMachine(state);
-			booted = await instance.waitForBoot(bootTimeout);
+			booted = await instance.waitForBoot(bootTimeout, probe);
 		}
 
 		if (!booted) {
-			let qemuLogTail = "";
-			try {
-				const logPath = join(machineDir, "qemu.log");
-				if (existsSync(logPath)) qemuLogTail = `\nqemu.log:\n${readFileSync(logPath, "utf-8").slice(-1200)}`;
-			} catch { /* ignore */ }
-			try { await instance.stop(); } catch { /* ignore */ }
-			try { await instance.remove(); } catch { /* ignore */ }
+			const guest = bootFailureGuestExec(state);
+			const failure = await captureBootFailure({
+				name,
+				machineDir,
+				arch,
+				accel,
+				bootTimeoutMs: bootTimeout,
+				pid,
+				httpPort: instance.ports.http,
+				portBase: state.portBase,
+				qemuArgs,
+				probe,
+				phase: "start",
+				reportDir: bootFailureReportDir(),
+				monitorQuery: (cmd) => monitorCommand(machineDir, cmd, 3000, state.portBase),
+				forwards: Object.values(state.ports),
+				guestExec: guest?.exec,
+				guestUser: guest?.users.join(" → "),
+			});
 			throw new QuickCHRError(
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				` Machine "${name}" has been cleaned up automatically.${qemuLogTail}`,
+				await cleanupAfterBootFailure(instance, name, failure) +
+				`\n${failure.summary}`,
 			);
 		}
 
@@ -1651,9 +2014,18 @@ export class QuickCHR {
 
 			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)) {
+			// 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 { rmSync(machineDir, { recursive: true, force: true }); } catch { /* best effort */ }
 			}
 			throw err;
@@ -1808,6 +2180,9 @@ export class QuickCHR {
 	): Promise<ChrInstance> {
 		const lockPath = join(state.machineDir, ".start-lock");
 		acquireLock(lockPath);
+		// Same pre-persistence window as start(): a relaunch that claims an endpoint and
+		// then fails to spawn would keep it, with no instance to release it.
+		let unpersistedSocketClaim: MachineState | undefined;
 		try {
 
 		const diskPath = join(state.machineDir, "disk.img");
@@ -1842,9 +2217,14 @@ export class QuickCHR {
 		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,
@@ -1867,9 +2247,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);
 		}
 
@@ -1877,25 +2260,40 @@ export class QuickCHR {
 		state.status = "running";
 		state.lastStartedAt = new Date().toISOString();
 		saveMachine(state);
+		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
 
 		// Always wait for boot in background mode — start() promises "REST-ready".
 		const bootTimeout = defaultBootTimeout(state.arch, provisioningOpts?.installAllPackages, accel);
-		const booted = await instance.waitForBoot(bootTimeout);
+		const probe = newBootProbeStats();
+		const booted = await instance.waitForBoot(bootTimeout, probe);
 		if (!booted) {
-			let qemuLogTail = "";
-			try {
-				const logPath = join(state.machineDir, "qemu.log");
-				if (existsSync(logPath)) qemuLogTail = `\nqemu.log:\n${readFileSync(logPath, "utf-8").slice(-1200)}`;
-			} catch { /* ignore */ }
-			try { await instance.stop(); } catch { /* ignore */ }
-			try { await instance.remove(); } catch { /* ignore */ }
+			const guest = bootFailureGuestExec(state);
+			const failure = await captureBootFailure({
+				name: state.name,
+				machineDir: state.machineDir,
+				arch: state.arch,
+				accel,
+				bootTimeoutMs: bootTimeout,
+				pid,
+				httpPort: instance.ports.http,
+				portBase: state.portBase,
+				qemuArgs,
+				probe,
+				phase: "_launchExisting",
+				reportDir: bootFailureReportDir(),
+				monitorQuery: (cmd) => monitorCommand(state.machineDir, cmd, 3000, state.portBase),
+				forwards: Object.values(state.ports),
+				guestExec: guest?.exec,
+				guestUser: guest?.users.join(" → "),
+			});
 			throw new QuickCHRError(
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				` Machine "${state.name}" has been cleaned up automatically.${qemuLogTail}`,
+				await cleanupAfterBootFailure(instance, state.name, failure) +
+				`\n${failure.summary}`,
 			);
 		}
 
@@ -1928,6 +2326,9 @@ export class QuickCHR {
 		} catch { /* never propagate */ }
 
 		return instance;
+		} catch (err) {
+			if (unpersistedSocketClaim) unregisterSocketMembers(unpersistedSocketClaim);
+			throw err;
 		} finally {
 			try { unlinkSync(lockPath); } catch { /* ignore */ }
 		}
@@ -1953,6 +2354,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
+		// start-lock is what tells them apart, so take it: acquireLock() throws
+		// MACHINE_LOCKED while a live creator holds it, and replaces one whose owner is
+		// gone — which is the case this recovery exists for.
+		const lockPath = join(getMachineDir(name), ".start-lock");
+		acquireLock(lockPath);
+
+		// The creator may have finished between the check above and the lock.
+		if (!isOrphanMachineDir(name)) {
+			try { unlinkSync(lockPath); } catch { /* ignore */ }
+			return false;
+		}
+
+		removeState(name);
+		return true;
+	}
+
 	/** Run doctor checks for prerequisites. */
 	static async doctor(): Promise<DoctorResult> {
 		const checks: DoctorResult["checks"] = [];
@@ -2141,29 +2590,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`,
 				});
 			}
 		}