@tikoci/quickchr 0.4.7 → 0.4.8

package/src/lib/qemu.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import type { Arch, BootDiskFormat, MachineState, NetworkMode, NetworkConfig, PortMapping } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { detectAccel, requireQemu, requireFirmware, requireQemuImg } from "./platform.ts";
-import { buildHostfwdString } from "./network.ts";
+import { buildHostfwdString, deviceArgs } from "./network.ts";
 import { ensureDir } from "./state.ts";
 import { restGet } from "./rest.ts";
 import { classifyProbeError, recordBootProbe, serialLogEnabled, type BootProbeStats } from "./diagnostics.ts";
@@ -137,8 +137,15 @@ export async function buildQemuArgs(config: QemuLaunchConfig): Promise<string[]>
 	return args;
 }
 
-/** Build networking arguments from NetworkConfig array. */
-function buildNetworkArgs(
+/** Build networking arguments from a `NetworkConfig` array.
+ *
+ *  Exported because it is one of the two places a NIC reaches QEMU (the other is
+ *  `resolveAllNetworks()` in `network.ts`, whose output the `net.resolved` branch
+ *  below passes straight through). Testing it through {@link buildQemuArgs} would
+ *  require a QEMU binary on the host, which the unit tier does not have — and a
+ *  test that skips itself when QEMU is missing would assert nothing on CI, which
+ *  is how a MAC-less NIC got shipped in the first place (#154). */
+export function buildNetworkArgs(
 	args: string[],
 	ports: Record<string, PortMapping>,
 	networks: NetworkConfig[],
@@ -157,39 +164,39 @@ function buildNetworkArgs(
 		if (spec === "vmnet-shared") {
 			args.push(
 				"-netdev", `vmnet-shared,id=${id}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else if (typeof spec === "object" && spec.type === "vmnet-bridged") {
 			args.push(
 				"-netdev", `vmnet-bridged,id=${id},ifname=${spec.iface}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else if (typeof spec === "object" && spec.type === "socket-listen") {
 			args.push(
 				"-netdev", `socket,id=${id},listen=:${spec.port}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else if (typeof spec === "object" && spec.type === "socket-connect") {
 			args.push(
 				"-netdev", `socket,id=${id},connect=127.0.0.1:${spec.port}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else if (typeof spec === "object" && spec.type === "socket-mcast") {
 			args.push(
 				"-netdev", `socket,id=${id},mcast=${spec.group}:${spec.port}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else if (typeof spec === "object" && spec.type === "tap") {
 			args.push(
 				"-netdev", `tap,id=${id},ifname=${spec.ifname},script=no,downscript=no`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		} else {
 			// Default: user-mode networking with port forwarding (only on the first user NIC)
 			const hostfwd = buildHostfwdString(ports);
 			args.push(
 				"-netdev", `user,id=${id}${hostfwd ? "," + hostfwd : ""}`,
-				"-device", `virtio-net-pci,netdev=${id}`,
+				...deviceArgs(net),
 			);
 		}
 	}
@@ -379,6 +386,20 @@ export async function spawnQemu(
 		// After spawn, close parent's copy; child process inherits its own copy.
 		const logFd = openSync(logPath, "a");
 
+		// A backgrounded QEMU outlives the CLI invocation that started it, so it must
+		// leave the caller's process group. `detached: true` is `setsid()` on POSIX;
+		// `unref()` alone is not enough, because it only covers a *voluntary* parent
+		// exit. It leaves QEMU in the caller's process group, where a group signal
+		// reaches it: Ctrl-C in the terminal, a shell `timeout`, a CI step teardown,
+		// an agent harness killing a stuck command (#159).
+		//
+		// Killing a run's VMs deliberately is by QEMU process name, not by group
+		// (`scripts/ci-file-watchdog.ts`, and the integration workflow's cleanup
+		// steps), so detaching costs no cleanup reach.
+		//
+		// Windows keeps its own spawn below for a different failure — a Job Object
+		// takes everything in it when the parent goes — and the two are not merged
+		// because only this one can be verified here.
 		let spawnedPid: number;
 
 		if (process.platform === "win32") {
@@ -394,6 +415,11 @@ export async function spawnQemu(
 				stdio: ["ignore", logFd, logFd],
 				windowsHide: true,
 			});
+			// A failed exec surfaces asynchronously here, as an `error` event with no
+			// pid — and an unhandled `error` event is a crash, not a thrown
+			// QuickCHRError. Nothing awaits the child, so this listener is what keeps
+			// a qemu binary that is missing, or cannot be executed, reportable.
+			child.on("error", () => { /* surfaced by the liveness check below */ });
 			closeSync(logFd);
 			if (child.pid === undefined) {
 				throw new QuickCHRError("SPAWN_FAILED", "Failed to spawn QEMU process on Windows");
@@ -402,13 +428,14 @@ export async function spawnQemu(
 			spawnedPid = child.pid;
 		} else {
 			const proc = Bun.spawn(spawnCmd, {
+				detached: true,
 				stdout: logFd,
 				stderr: logFd,
 				stdin: "ignore",
 			});
 			closeSync(logFd);
-			// unref() lets the parent Bun process exit without waiting for QEMU.
-			// QEMU becomes an orphan adopted by init/launchd and keeps running.
+			// unref() lets the parent exit without waiting for QEMU; detached keeps
+			// QEMU alive when the parent is signalled rather than exiting.
 			proc.unref();
 			spawnedPid = proc.pid;
 		}

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,
@@ -68,7 +75,7 @@ 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 {
 	formatDeviceModeSelection,
@@ -83,7 +90,7 @@ 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 ---
@@ -186,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 {
@@ -412,7 +497,10 @@ 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, stats?: BootProbeStats): Promise<boolean> {
 			// Use resolved credentials so waitForBoot can validate the response body
@@ -464,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
@@ -1226,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,
@@ -1389,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) {
@@ -1434,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();
@@ -1463,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,
@@ -1483,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 */ }
 		}
@@ -1499,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) {
@@ -1566,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);
@@ -1634,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,
@@ -1657,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
@@ -1693,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",
@@ -1732,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,
@@ -1757,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);
 		}
 
@@ -1767,6 +1911,7 @@ export class QuickCHR {
 		state.lastStartedAt = new Date().toISOString();
 
 		saveMachine(state);
+		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
 
@@ -1869,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;
@@ -2026,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");
@@ -2060,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,
@@ -2085,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);
 		}
 
@@ -2095,6 +2260,7 @@ export class QuickCHR {
 		state.status = "running";
 		state.lastStartedAt = new Date().toISOString();
 		saveMachine(state);
+		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
 
@@ -2160,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 */ }
 		}
@@ -2185,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"] = [];
@@ -2373,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`,
 				});
 			}
 		}