@tikoci/quickchr 0.4.7 → 0.5.0

package/src/lib/network.ts

@@ -20,7 +20,13 @@ import {
 	SERVICE_PORTS,
 	QuickCHRError,
 } from "./types.ts";
-import { getNamedSocket } from "./socket-registry.ts";
+import {
+	getNamedSocket,
+	getSocketSlot,
+	socketEndpointPath,
+	type SocketEntry,
+} from "./socket-registry.ts";
+import { assertValidResourceName } from "./names.ts";
 import { resolveInterfaceAlias, isSocketVmnetDaemonRunning } from "./platform.ts";
 
 /** Allocate a port block for a new instance, avoiding conflicts with existing machines. */
@@ -32,15 +38,15 @@ export function allocatePortBlock(
 		return requestedBase;
 	}
 
-	let base = DEFAULT_PORT_BASE;
-	const sorted = [...usedBases].sort((a, b) => a - b);
+	return nextUnusedBase(DEFAULT_PORT_BASE, usedBases);
+}
 
-	for (const used of sorted) {
-		if (base >= used && base < used + PORTS_PER_BLOCK) {
-			base = used + PORTS_PER_BLOCK;
-		}
+/** The lowest base at or above `from` whose block overlaps no used block. */
+function nextUnusedBase(from: number, usedBases: number[]): number {
+	let base = from;
+	for (const used of [...usedBases].sort((a, b) => a - b)) {
+		if (Math.abs(base - used) < PORTS_PER_BLOCK) base = used + PORTS_PER_BLOCK;
 	}
-
 	return base;
 }
 
@@ -213,7 +219,10 @@ export async function findAvailablePortBlock(
 		if (conflicts.length === 0) {
 			return base;
 		}
-		base += PORTS_PER_BLOCK;
+		// Step past the probed conflict without stepping onto a used block: a block
+		// that is free on the wire can still belong to a stopped machine or to a
+		// creation that has not bound its ports yet (#140).
+		base = nextUnusedBase(base + PORTS_PER_BLOCK, usedBases);
 	}
 
 	throw new QuickCHRError(
@@ -329,6 +338,9 @@ function parseSocketSpecifier(input: string): NetworkSpecifier {
 				"socket:: requires a link name (e.g. socket::mylink)",
 			);
 		}
+		// start() auto-creates a registry entry (and a networks/<name>.json file) for an
+		// unknown name, so the specifier is the other door into createNamedSocket().
+		assertValidResourceName(name, "named socket");
 		return { type: "socket", name };
 	}
 
@@ -388,6 +400,77 @@ export function resolveStartNetworks(
 	return [{ specifier: "user", id: "net0" }];
 }
 
+/** Derive a stable MAC for one NIC of one machine.
+ *
+ * QEMU's default is `52:54:00:12:34:56` incremented per NIC **within** a guest, so
+ * NIC index *N* holds the same address in *every* guest. Harmless while machines
+ * only have `user` NICs (separate SLIRP namespaces), fatal the moment two share an
+ * L2 segment — a named socket, a listen/connect pair, a TAP, or a RouterOS bridge
+ * on a hub VM. Forwarding then breaks in ways that look like a RouterOS or overlay
+ * defect rather than a launcher one (#154).
+ *
+ * The first octet is `0x02`: locally administered (bit 1 set) and unicast (bit 0
+ * clear), so these never collide with a vendor-assigned address. The remaining five
+ * octets come from a SHA-256 of the machine name, NIC index and `salt`, which makes
+ * the address reproducible for a given name instead of random per boot — the same
+ * lab rebuilt under the same names presents the same addresses.
+ */
+export function deriveMac(name: string, index: number, salt = 0): string {
+	const digest = new Bun.CryptoHasher("sha256")
+		.update(`${name}\u0000${index}\u0000${salt}`)
+		.digest();
+	// Five octets after the fixed `02`, so a NIC's address is 48 bits total.
+	const octets = Array.from(digest.subarray(0, 5), (o) =>
+		o.toString(16).padStart(2, "0"),
+	);
+	return ["02", ...octets].join(":");
+}
+
+/** Assign a MAC to every NIC that lacks one, avoiding `taken`.
+ *
+ * Mutates and returns `networks`. Idempotent: a NIC that already has a MAC keeps it,
+ * so a machine's addresses are fixed at creation and survive restart, a re-resolve on
+ * a different platform, and any later change to {@link deriveMac} itself.
+ *
+ * **Call this only where a machine is created.** Changing a MAC on a machine that has
+ * already booted breaks it: RouterOS ties its persisted interface identity to the
+ * address, so a new one orphans the `ether1` holding the DHCP client and the guest
+ * comes up with no IP. Verified by A/B on a live CHR — see DESIGN.md, "NIC MAC
+ * Addresses". Machines created before #154 keep QEMU's defaults and must be recreated.
+ *
+ * A SHA-256 collision across five octets is vanishingly unlikely, but `taken` makes
+ * the guarantee structural rather than probabilistic — a duplicate here is the exact
+ * silent-L2 failure this exists to prevent, so it is worth not leaving to odds.
+ *
+ * `taken` is a snapshot, so it is only complete if no other creation is choosing at
+ * the same moment. Callers that create machines go through `claimNewMachine()` in
+ * quickchr.ts, which holds the allocation lock across this call and the port choice
+ * and adds in-flight creations' MACs to `taken` (#140). A new creation path must do
+ * the same rather than call this with a bare `getUsedMacs()`.
+ */
+export function assignMacs(
+	name: string,
+	networks: NetworkConfig[],
+	taken: ReadonlySet<string> = new Set(),
+): NetworkConfig[] {
+	const used = new Set(taken);
+	for (const n of networks) {
+		if (n.mac) used.add(n.mac);
+	}
+	networks.forEach((n, i) => {
+		if (n.mac) return;
+		let salt = 0;
+		let mac = deriveMac(name, i, salt);
+		while (used.has(mac)) {
+			salt++;
+			mac = deriveMac(name, i, salt);
+		}
+		used.add(mac);
+		n.mac = mac;
+	});
+	return networks;
+}
+
 /** Returns true when at least one network uses QEMU user-mode (hostfwd) networking.
  *  Only user-mode networks forward localhost ports — shared/bridged/tap/socket networks
  *  assign a DHCP address that is not reachable from host localhost. */
@@ -400,10 +483,26 @@ export function hasUserModeNetwork(networks: NetworkConfig[]): boolean {
 export interface ResolutionContext {
 	platform: PlatformInfo;
 	socketVmnet?: SocketVmnetInfo;
+	/** Machine being resolved. A named socket's endpoint role is per-machine, so the
+	 *  resolver needs to know who is asking; absent for callers that only want the
+	 *  shape of a specifier (dry runs, unit tests over the non-socket modes). */
+	machine?: string;
+	/** QEMU version string, when the caller knows it. `-netdev dgram` landed in 7.2;
+	 *  an unknown version does not block, because refusing to run on a QEMU we merely
+	 *  failed to parse is worse than the error the spawn would give. */
+	qemuVersion?: string;
 }
 
-function deviceArgs(id: string): string[] {
-	return ["-device", `virtio-net-pci,netdev=${id}`];
+/** `-device` for one NIC — the **only** place a NIC device is emitted.
+ *
+ *  Takes the whole {@link NetworkConfig} rather than an id so a caller physically
+ *  cannot emit a NIC without its MAC. `qemu.ts`'s fallback path builds its own
+ *  `-netdev` strings but shares this, so both paths carry the address; every guest
+ *  would otherwise get QEMU's default `52:54:00:12:34:56` sequence and two machines
+ *  bridged onto one L2 segment would collide (#154). */
+export function deviceArgs(config: NetworkConfig): string[] {
+	const mac = config.mac ? `,mac=${config.mac}` : "";
+	return ["-device", `virtio-net-pci,netdev=${config.id}${mac}`];
 }
 
 function resolveUser(
@@ -416,7 +515,7 @@ function resolveUser(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", netdevValue,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -438,7 +537,7 @@ function resolveShared(
 			return {
 				qemuNetdevArgs: [
 					"-netdev", `socket,id=${config.id},fd=3`,
-					...deviceArgs(config.id),
+					...deviceArgs(config),
 				],
 				wrapper: [svn.client, svn.sharedSocket],
 			};
@@ -446,7 +545,7 @@ function resolveShared(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `vmnet-shared,id=${config.id}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
 			],
 			downgraded: {
 				from: "shared (socket_vmnet)",
@@ -473,7 +572,7 @@ function resolveVmnetShared(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `vmnet-shared,id=${config.id}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -498,7 +597,7 @@ function resolveBridged(
 			return {
 				qemuNetdevArgs: [
 					"-netdev", `socket,id=${config.id},fd=3`,
-					...deviceArgs(config.id),
+					...deviceArgs(config),
 				],
 				wrapper: [svn.client, bridgeSocket],
 			};
@@ -506,7 +605,7 @@ function resolveBridged(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `vmnet-bridged,id=${config.id},ifname=${resolved}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
 			],
 			downgraded: {
 				from: `bridged:${iface} (socket_vmnet)`,
@@ -534,14 +633,45 @@ function resolveVmnetBridged(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `vmnet-bridged,id=${config.id},ifname=${iface}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
 
+/** One-line description of the transport a named socket resolved to, for the line
+ *  `start` prints and for `list`/`info`. The acceptance bar for #158's visibility
+ *  work is that nothing about a named socket requires opening a file under the data
+ *  dir, and this is what makes that true. */
+export function describeSocketTransport(entry: SocketEntry, slot?: number): string {
+	switch (entry.mode) {
+		case "mcast":
+			return `UDP multicast ${entry.mcastGroup}:${entry.port} (N-way)`;
+		case "listen-connect":
+			if (slot === undefined) return `TCP pair on 127.0.0.1:${entry.port}`;
+			return slot === 0
+				? `TCP 127.0.0.1:${entry.port} (listening)`
+				: `TCP 127.0.0.1:${entry.port} (connecting)`;
+		case "dgram": {
+			// Unoccupied: name the pair once rather than printing the directory twice.
+			if (slot === undefined) {
+				return `unix datagram ${socketEndpointPath(entry.name, 0).replace(/\.0\.sock$/, ".{0,1}.sock")}`;
+			}
+			const peer = slot === 0 ? 1 : 0;
+			return `unix datagram ${socketEndpointPath(entry.name, slot)} -> ${socketEndpointPath(entry.name, peer)}`;
+		}
+	}
+}
+
+/** `-netdev dgram` was added in QEMU 7.2. */
+export function qemuSupportsDgram(version: string): boolean {
+	const [major = 0, minor = 0] = version.split(".").map((p) => Number.parseInt(p, 10) || 0);
+	return major > 7 || (major === 7 && minor >= 2);
+}
+
 function resolveSocketNamed(
 	config: NetworkConfig,
 	name: string,
+	ctx: ResolutionContext,
 ): ResolvedNetwork {
 	const entry = getNamedSocket(name);
 	if (!entry) {
@@ -554,18 +684,60 @@ function resolveSocketNamed(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `socket,id=${config.id},mcast=${entry.mcastGroup}:${entry.port}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
+			],
+		};
+	}
+
+	// Two-member modes carry a role. It comes from the persisted slot, claimed when the
+	// machine joined, so a listener that stops and restarts comes back as the listener
+	// instead of silently demoting itself to a second connector.
+	const slot = ctx.machine ? getSocketSlot(entry, ctx.machine) : undefined;
+	if (slot === undefined) {
+		const held = entry.endpoints?.filter((m): m is string => m !== null) ?? [];
+		const who = held.length > 0 ? held.join(" and ") : "no machine";
+		throw new QuickCHRError(
+			"NETWORK_UNAVAILABLE",
+			ctx.machine
+				? `Machine "${ctx.machine}" holds no endpoint on named socket "${name}" — it is a ${entry.mode} link, and its two ends are held by ${who}.`
+				: `Named socket "${name}" is a ${entry.mode} link, so resolving it needs the machine's name (its endpoint role is per-machine). Pass 'machine' in the resolution context.`,
+		);
+	}
+
+	if (entry.mode === "dgram") {
+		// Windows first: it cannot have this transport at any QEMU version.
+		if (ctx.platform.os === "win32") {
+			throw new QuickCHRError(
+				"NETWORK_UNAVAILABLE",
+				`Named socket "${name}" is a unix-datagram link, which Windows cannot provide (AF_UNIX has no SOCK_DGRAM). ` +
+				`Recreate it with 'quickchr networks sockets create ${name} --mode listen-connect'.`,
+			);
+		}
+		if (ctx.qemuVersion && !qemuSupportsDgram(ctx.qemuVersion)) {
+			throw new QuickCHRError(
+				"NETWORK_UNAVAILABLE",
+				`Named socket "${name}" is a unix-datagram link, which needs QEMU 7.2 or newer (found ${ctx.qemuVersion}). ` +
+				`Upgrade QEMU, or recreate the socket with 'quickchr networks sockets create ${name} --mode listen-connect'.`,
+			);
+		}
+		const local = socketEndpointPath(name, slot);
+		const remote = socketEndpointPath(name, slot === 0 ? 1 : 0);
+		return {
+			qemuNetdevArgs: [
+				"-netdev",
+				`dgram,id=${config.id},local.type=unix,local.path=${local},remote.type=unix,remote.path=${remote}`,
+				...deviceArgs(config),
 			],
 		};
 	}
-	const isFirst = entry.members.length === 0;
-	const netdevArg = isFirst
+
+	const netdevArg = slot === 0
 		? `socket,id=${config.id},listen=:${entry.port}`
 		: `socket,id=${config.id},connect=127.0.0.1:${entry.port}`;
 	return {
 		qemuNetdevArgs: [
 			"-netdev", netdevArg,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -577,7 +749,7 @@ function resolveSocketListen(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},listen=:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -589,7 +761,7 @@ function resolveSocketConnect(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},connect=127.0.0.1:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -602,7 +774,7 @@ function resolveSocketMcast(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},mcast=${group}:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -621,7 +793,7 @@ function resolveTap(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `tap,id=${config.id},ifname=${ifname},script=no,downscript=no`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -650,7 +822,7 @@ export function resolveNetworkConfig(
 				resolved = resolveVmnetBridged(config, spec.iface, ctx);
 				break;
 			case "socket":
-				resolved = resolveSocketNamed(config, spec.name);
+				resolved = resolveSocketNamed(config, spec.name, ctx);
 				break;
 			case "socket-listen":
 				resolved = resolveSocketListen(config, spec.port);

package/src/lib/packages.ts

@@ -2,9 +2,9 @@
  * Extra package download and installation for CHR instances.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
-import type { Arch } from "./types.ts";
+import { QuickCHRError, type Arch } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
 import { downloadToFile } from "./download.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
@@ -13,6 +13,51 @@ import { restPost } from "./rest.ts";
 import { scpPush } from "./scp.ts";
 import { extractZip } from "./zip.ts";
 
+const PACKAGE_CACHE_MANIFEST = ".quickchr-complete.json";
+
+interface PackageCacheManifest {
+	version: string;
+	arch: Arch;
+	archiveSize: number;
+	packages: Array<{ name: string; size: number }>;
+}
+
+function packageFiles(extractDir: string): Array<{ name: string; size: number }> {
+	try {
+		return readdirSync(extractDir)
+			.filter((name) => name.endsWith(".npk"))
+			.map((name) => ({ name, size: statSync(join(extractDir, name)).size }))
+			.filter((entry) => entry.size > 0)
+			.sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return [];
+	}
+}
+
+/** Verify the archive and every package recorded after atomic extraction. */
+export async function isCompletePackageCache(
+	version: string,
+	arch: Arch,
+	cacheDir?: string,
+): Promise<boolean> {
+	const cache = cacheDir ?? getCacheDir();
+	const zipPath = join(cache, `all_packages-${arch}-${version}.zip`);
+	const extractDir = join(cache, `packages-${arch}-${version}`);
+	try {
+		const archiveSize = statSync(zipPath).size;
+		if (archiveSize <= 0) return false;
+		const manifest = await Bun.file(join(extractDir, PACKAGE_CACHE_MANIFEST)).json() as PackageCacheManifest;
+		const packages = packageFiles(extractDir);
+		return manifest.version === version &&
+			manifest.arch === arch &&
+			manifest.archiveSize === archiveSize &&
+			packages.length > 0 &&
+			JSON.stringify(manifest.packages) === JSON.stringify(packages);
+	} catch {
+		return false;
+	}
+}
+
 /** Download and extract the all-packages ZIP for a version/arch. Returns the extract dir. */
 export async function downloadPackages(
 	version: string,
@@ -28,7 +73,7 @@ export async function downloadPackages(
 	const zipPath = join(cache, zipName);
 	const extractDir = join(cache, `packages-${arch}-${version}`);
 
-	if (existsSync(extractDir)) {
+	if (await isCompletePackageCache(version, arch, cache)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached packages: ${version} (${arch})`);
 		return extractDir;
@@ -44,9 +89,38 @@ export async function downloadPackages(
 		await downloadToFile(url, zipPath, { logger: log });
 	}
 
-	// Extract
-	ensureDir(extractDir);
-	extractZip(zipPath, extractDir);
+	// Extract into a sibling directory, record the exact complete set, then
+	// rename it into place. A killed extraction can never look like a cache hit.
+	const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+	try {
+		extractZip(zipPath, tempDir);
+		const packages = packageFiles(tempDir);
+		if (packages.length === 0) {
+			throw new Error(`No non-empty .npk files found in ${zipName}`);
+		}
+		const manifest: PackageCacheManifest = {
+			version,
+			arch,
+			archiveSize: statSync(zipPath).size,
+			packages,
+		};
+		await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
+		if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
+		renameSync(tempDir, extractDir);
+	} catch (error) {
+		rmSync(tempDir, { recursive: true, force: true });
+		if (error instanceof Error && error.message.startsWith("No non-empty")) {
+			throw new QuickCHRError("PROCESS_FAILED", error.message);
+		}
+		throw error;
+	}
+
+	if (!(await isCompletePackageCache(version, arch, cache))) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`Package cache verification failed for ${version} (${arch})`,
+		);
+	}
 
 	return extractDir;
 }

package/src/lib/provision.ts

@@ -67,12 +67,82 @@ async function waitForRest(
 	}
 }
 
+/** Wait until RouterOS actually accepts `auth`, returning how long that took.
+ *
+ * Deliberately *not* `waitForBoot()`: that one counts 401/403 as ready, because
+ * for a liveness probe an auth rejection still proves `www` is answering. Here
+ * a 401 is the thing being waited out, so it needs the opposite predicate.
+ *
+ * **This is hardening and an instrument, not a proven fix for #69.** The known
+ * symptom is a 401 on the first request made with freshly created credentials —
+ * four Windows CI legs across runs 35135008624 and 35386692051, always on the
+ * path that does no work between `createUser()` and that request. A local
+ * attempt to reproduce it found no window to close: on an Intel host against
+ * CHR 7.24.4 (x86 guest), a new user authenticated on attempt #1, 6/6, under
+ * both TCG and HVF. So the cause of the CI 401 is still open, and this wait
+ * does not claim to explain it.
+ *
+ * What it does buy: `createUser()` can no longer resolve while a `full`-group
+ * user's own credentials are rejected, and the outcome is measured either way.
+ * (Limited groups are exempt — see the table at the call site: a valid user
+ * without `rest-api` answers 401, which is indistinguishable from the symptom.) If the CI
+ * 401 is any kind of timing window, this closes it *and* the returned figure
+ * says how wide it was on that platform — which is the quantification #69 asks
+ * for. If it is not a timing window, the wait exhausts its budget and fails
+ * saying so, which is a far stronger signal than today's bare 401.
+ *
+ * Reports `attempts` alongside `elapsedMs`, and **`attempts` is the load-bearing
+ * number**. Elapsed time cannot tell a retry from a slow request: a first
+ * authentication with a new password costs a few hundred ms of ordinary request
+ * latency on an emulated guest, so an elapsed-only figure reads as a wait when
+ * nothing waited. `attempts === 1` means there was no window, whatever the
+ * clock says. (This is not hypothetical — it is the error the first pass at
+ * this investigation made; see `provisioning.instructions.md`.) */
+export async function waitForAuth(
+	httpPort: number,
+	auth: string,
+	timeoutMs: number = 30_000,
+): Promise<{ attempts: number; elapsedMs: number }> {
+	const url = `http://127.0.0.1:${httpPort}/rest/system/resource`;
+	const start = Date.now();
+	const deadline = start + timeoutMs;
+	let lastStatus: number | undefined;
+	let attempts = 0;
+
+	while (Date.now() < deadline) {
+		attempts++;
+		// Bound each request by what is left of the budget, so a stalled request
+		// cannot push the whole wait past the deadline it advertises.
+		const remaining = deadline - Date.now();
+		try {
+			const { status } = await restGet(url, auth, Math.min(5_000, remaining));
+			if (status >= 200 && status < 300) return { attempts, elapsedMs: Date.now() - start };
+			// 401/403 is the propagation window. 5xx also occurs briefly after a
+			// user-database change, and is equally transient, so both are polled
+			// out rather than one being singled out as "the" expected status.
+			lastStatus = status;
+		} catch { /* transport error mid-transition — keep polling */ }
+		await Bun.sleep(250);
+	}
+
+	throw new QuickCHRError(
+		"PROCESS_FAILED",
+		`Credentials were not accepted within ${timeoutMs}ms over ${attempts} attempt(s) ` +
+		`(last HTTP status: ${lastStatus ?? "no response"}) — ` +
+		"the user record exists but RouterOS is not authenticating it",
+	);
+}
+
 /** Create a user via the REST API. */
 export async function createUser(
 	httpPort: number,
 	name: string,
 	password: string,
 	group: string = "full",
+	logger?: ProgressLogger,
+	/** Budget for the post-visibility authentication wait. Injectable so tests
+	 *  can exercise the failure path without burning the 30 s default. */
+	authTimeoutMs: number = 30_000,
 ): Promise<void> {
 	await waitForRest(httpPort);
 
@@ -95,6 +165,7 @@ export async function createUser(
 	// Verify visibility (and group) so callers get deterministic behavior.
 	const expectedGroup = group.trim().toLowerCase();
 	const deadline = Date.now() + 30_000;
+	let visible = false;
 	while (Date.now() < deadline) {
 		try {
 			const user = await readUser(httpPort, auth, name);
@@ -110,7 +181,8 @@ export async function createUser(
 						`User "${name}" created with unexpected group (expected=${expectedGroup}, actual=${actualGroup})`,
 					);
 				}
-				return;
+				visible = true;
+				break;
 			}
 		} catch (e) {
 			// Rethrow deliberate group mismatch errors; retry transient HTTP failures
@@ -120,9 +192,58 @@ export async function createUser(
 		await Bun.sleep(500);
 	}
 
-	throw new QuickCHRError(
-		"PROCESS_FAILED",
-		`User "${name}" creation was acknowledged but did not become visible in RouterOS`,
+	if (!visible) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`User "${name}" creation was acknowledged but did not become visible in RouterOS`,
+		);
+	}
+
+	// Only the `full` group is gated, because only there does "the probe answers
+	// 2xx" mean "the credentials work". RouterOS separates authentication from
+	// authorization, and a correctly created user in a limited group cannot
+	// answer this probe at all. Measured on CHR 7.24.4 by creating one user per
+	// group and issuing GET /rest/system/resource as that user:
+	//
+	//   group policy                              | status
+	//   ------------------------------------------|---------------------------
+	//   local,ssh,winbox,read      (no rest-api)   | 401 Unauthorized
+	//   local,ssh,winbox,rest-api,write (no read)  | 500 std failure: not allowed (9)
+	//   local,winbox,rest-api,read (no web)        | 500 std failure: not allowed (9)
+	//   read / write / full (defaults)             | 200
+	//
+	// The 401 is byte-identical to #69's symptom, so no amount of polling can
+	// tell an unauthorized user from a credential that has not propagated, and the 500 is
+	// a permanent condition this wait would poll through to its deadline. Gating
+	// those would turn a correctly created user into a 30 s stall and a false
+	// "not authenticating" failure. `provision()` only ever creates `full`.
+	if (expectedGroup !== "full") {
+		logger?.debug(
+			`user "${name}" created in group "${group}" — authentication gate skipped: ` +
+			"only the full group is known to be REST-verifiable",
+		);
+		return;
+	}
+
+	// Deliberately outside the loop above. waitForAuth() throws a QuickCHRError,
+	// and that catch swallows every QuickCHRError except the group mismatch — so
+	// running it inside would discard the one diagnostic this wait exists to
+	// produce and report "did not become visible" for a user that plainly is.
+	//
+	// "Visible in /rest/user" was the whole done-when here, which is a weaker
+	// promise than every caller relies on: they use the credentials next.
+	const { attempts, elapsedMs } = await waitForAuth(
+		httpPort,
+		`Basic ${btoa(`${name}:${password}`)}`,
+		authTimeoutMs,
+	);
+	// attempts is the signal; elapsedMs alone cannot separate a retry from a slow
+	// first authentication on an emulated guest. The earlier attempts are only
+	// known to have not-succeeded — waitForAuth also polls through 5xx and
+	// transport errors — so they are not reported as rejections.
+	logger?.debug(
+		`user "${name}" accepted after ${attempts} attempt(s), ${elapsedMs}ms` +
+		(attempts > 1 ? ` — ${attempts - 1} earlier probe(s) did not succeed (#69)` : ""),
 	);
 }
 
@@ -547,8 +668,9 @@ export async function installSshKey(
 /** Run all provisioning steps based on the config.
  *
  * When `user` is provided, creates that exact user. When `user` is omitted
- * but `secureLogin` is true (or unset — it defaults to true), a `quickchr`
- * managed account is created automatically with a generated password.
+ * and `secureLogin` is exactly `true`, a `quickchr` managed account is created
+ * automatically with a generated password; unset or `false` creates none — see
+ * `StartOptions.secureLogin`.
  *
  * When `machineDir` is provided and the REST API does not become available within
  * 30 seconds, provisioning falls back to the serial console transport.
@@ -609,7 +731,7 @@ export async function provision(
 	// REST provisioning path. The console fallback above always returns early,
 	// so reaching here means REST came up and we provision over it.
 	if (effectiveUser) {
-		await createUser(httpPort, effectiveUser.name, effectiveUser.password);
+		await createUser(httpPort, effectiveUser.name, effectiveUser.password, "full", log);
 		// Persist to secret store so resolveAuth() picks it up
 		saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
 	}