@tikoci/quickchr 0.4.5 → 0.4.6

package/DESIGN.md

@@ -54,6 +54,14 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
    **Sister-project routing.** Because `fetchResilient` already absorbs a flaky resolver, a download/version-resolve failure should not be papered over downstream with `/etc/hosts` pins or IPv6 toggles in a consuming repo's workflow — fix it (or extend the failback) here in quickchr. The historical `getent ahostsv4` `/etc/hosts` workaround was both in the wrong layer and non-functional (it hit the same broken stub resolver, returning empty). The failback is best-effort, not a guarantee: it recovers connection-class DNS failures, not arbitrary network breakage. Covered by `test/unit/net.test.ts`.
 
+10. **arm64 CHR is forced onto TCG on all Apple Silicon** — `detectAccel("arm64")` never returns `hvf` on macOS; the launch path surfaces `accelNote()` explaining why (`src/lib/platform.ts`). The cause is an **image artifact**, not an accelerator or CPU-model bug: current arm64 CHR images (7.20.8 – 7.23beta5 verified) ship an AArch64 kernel over a **32-bit ARM userspace** — the appended initramfs `/init` is `ELF 32-bit LSB ARM, EABI5, static`, and the 7.22.1 `system` package holds **101 further ARM32 executables and 18 ARM32 shared objects** (the only AArch64 executables are `kexec` and `vmcore-dmesg`). Apple Silicon implements **no AArch32 at any exception level**: `ID_AA64PFR0_EL1` reports AArch64-only for EL0/EL1, and QEMU under HVF passes that hardware register straight through (`hvf_arch_init_vcpu()` re-reads the live vCPU register and only edits the GIC bit; the `-cpu` model is inert). So the guest kernel never sets `ARM64_HAS_32BIT_EL0`, `compat_elf_check_arch()` rejects the `EM_ARM` `/init` with `-ENOEXEC`, the initramfs has no fallback init, and Linux panics at t≈0.076 s with `No working init found`. TCG's emulated models do provide AArch32 EL0, so the same unmodified image boots to `MikroTik Login:`. Grounded in the guest's own panic-time capability bitmap: the M4/HVF guest printed `0x20012,28000230` (8 caps, `ARM64_HAS_32BIT_EL0` absent) against TCG's `0x20013,28402230` (11 caps, present). Full chain in [`docs/m4-hvf-arm64-investigation.md`](docs/m4-hvf-arm64-investigation.md).
+
+    **Scope is every Apple Silicon generation, not M4+.** The first report came from an M4 (tikoci/mikropkl#11) and the original fix keyed on `hw.optional.arm.FEAT_SSBS == 0`, which M4 is the first Apple chip to report — but SSBS was a **coincident marker of the reporting host, not the mechanism**. Linux 5.6 treats SSBS as an optional mitigation and boots fine without it (`cortex-a53`/`neoverse-n1` lack it), while *no* Apple CPU since 2020 implements AArch32. The SSBS predicate therefore left M1/M2/M3 on HVF and panicking — a live bug, not merely a narrow gate. Ordinary server ARM (Ampere, Graviton) does implement AArch32 EL0, which is why arm64 CHR runs there under KVM; this is an Apple-Silicon-and-CHR-artifact interaction, not a RouterOS-on-ARM defect.
+
+    **No QEMU flag or version fixes this.** Apple's `Hypervisor.framework` exposes only `hv_vcpu_config_get_feature_reg()` — there is no setter — so no macOS VMM can present a feature the silicon lacks (UTM's fork behaves identically). A QEMU version floor is therefore *not* a valid restore signal, and the deferred `getQemuVersion()` guard the SSBS-era decision contemplated has been dropped. **The restore signal is the guest artifact:** a future arm64 CHR whose appended `/init` *and* required system-package executables/shared objects are all AArch64, confirmed by a real HVF boot. That check is mechanical (§"Reproduction" in the investigation doc) and could become a release-time guard.
+
+    **Escape hatch.** Because the fallback is unconditional, `--accel <auto|tcg|hvf|kvm>` (and the `accel` setting / `QUICKCHR_ACCEL` env var) forces the accelerator verbatim and bypasses detection — so a fixed future image can be tested on HVF without a code change, and so forcing TCG stays possible for debugging elsewhere. `--accel hvf` on an arm64 guest still prints the panic caveat rather than silently obeying. This complements, and does not replace, the reactive respawn-once net in #8. Covered by `test/unit/platform.test.ts`. → [#97](https://github.com/tikoci/quickchr/issues/97)
+
 ## Port Layout
 
 | Offset | Service    | Guest Port |
@@ -100,8 +108,9 @@ Current consumers are all first-party tikoci projects (centrs, donny, restraml),
 **Global settings** live separately, under the XDG **config** tier (not the data tree
 above): `~/.config/quickchr/quickchr.env`, dotenv-style (`QUICKCHR_KEY=value` lines).
 Managed via `quickchr settings get|set|print|reset`. Precedence per key: CLI flag >
-`QUICKCHR_<KEY>` env var > `quickchr.env` > built-in default. The 5 managed keys:
-`default-channel`, `default-arch`, `cache-max-size`, `timeout-extra`, `secure-login`.
+`QUICKCHR_<KEY>` env var > `quickchr.env` > built-in default. The 6 managed keys:
+`default-channel`, `default-arch`, `accel`, `cache-max-size`, `timeout-extra`,
+`secure-login`.
 See MANUAL.md's CLI reference and environment-variables sections for the full surface.
 
 ## Platform Support
@@ -109,16 +118,20 @@ See MANUAL.md's CLI reference and environment-variables sections for the full su
 | Platform               | x86 CHR | arm64 CHR | Notes |
 |------------------------|---------|-----------|-------|
 | macOS x86_64           | HVF     | TCG       | Intel Mac |
-| macOS arm64 (native)   | HVF     | HVF       | Apple Silicon, bun is arm64 |
-| macOS arm64 (Rosetta)  | HVF     | TCG       | bun is x86_64; arm64 HVF skipped |
+| macOS arm64 (native)   | TCG     | TCG¹     | Apple Silicon, bun is arm64 |
+| macOS arm64 (Rosetta)  | TCG     | TCG¹     | Apple Silicon, bun reports x86_64 |
 | Linux x86_64           | KVM     | TCG       | KVM requires `/dev/kvm` writable |
 | Linux aarch64          | TCG     | KVM       | x86 TCG on arm64 Linux |
 | Windows x86_64         | TCG     | TCG       | HVF/KVM not available |
 
+¹ arm64 CHR is forced to **TCG on every Apple Silicon generation**: the image's required userspace is 32-bit ARM and Apple CPUs implement no AArch32, so an HVF guest panics at init (see Design Decisions #10). x86 CHR also uses TCG because HVF cannot virtualize x86 on an arm64 host. Override with `--accel hvf` to test a future AArch64-only image.
+
 **Acceleration detection** (`detectAccel`):
-- macOS: checks `kern.hv_support` via sysctl; for arm64 guest additionally checks `process.arch === "arm64"` (native bun = Apple Silicon).
+- An explicit override (`--accel` flag > `QUICKCHR_ACCEL` env > `accel` in `quickchr.env`) short-circuits detection entirely; `auto` (the default) runs the checks below.
+- macOS: checks `kern.hv_support` via sysctl. Intel x86 guests get HVF; **all guests on Apple Silicon get TCG** — x86 because HVF cannot virtualize across architectures, arm64 because the CHR image needs AArch32 (Design Decisions #10). A Rosetta process is identified via `sysctl.proc_translated`.
 - Linux: checks `/dev/kvm` writability.
-- Falling back to TCG is always safe, just slower (~20s x86 TCG boot on Apple Silicon; ~2 min arm64 TCG on Intel).
+- Falling back to TCG is safe but can be significantly slower; measure with the
+  target host, guest architecture, and RouterOS version.
 
 ## CI System
 

package/MANUAL.md

@@ -398,12 +398,18 @@ Precedence per key (highest wins): CLI flag > `QUICKCHR_<KEY>` env var >
 |---|---|---|---|
 | `default-channel` | `add`/`start`'s `--channel`, wizard's channel prompt | `stable`\|`long-term`\|`testing`\|`development` | `stable` |
 | `default-arch` | `add`/`start`'s `--arch`, wizard's arch prompt | `arm64`\|`x86`\|`auto` | `auto` (host native) |
+| `accel` | `add`/`start`'s `--accel`; every `detectAccel()` call in the run | `auto`\|`tcg`\|`hvf`\|`kvm` | `auto` (detect) |
 | `cache-max-size` | Auto-prune cap applied after each successful `start` | size string (e.g. `2G`, `512M`) | `2G` |
 | `timeout-extra` | `start`'s `--timeout-extra`/`-T` when omitted | non-negative integer seconds | `0` |
 | `secure-login` | `add`/`start`'s `--secure-login` when neither `--secure-login` nor `--no-secure-login` is passed | boolean | `unset` (reported as `(unset)` — see note) |
 
+Anything other than `auto` for `accel` is handed to QEMU verbatim and **skips detection
+entirely**, including the arm64-on-Apple-Silicon TCG fallback (§Platform notes) and the
+availability checks — force `kvm` on macOS and QEMU itself reports the error. That is
+deliberate: the override exists to test an accelerator the detector currently refuses.
+
 `secure-login` is the one key `settings print`/`get` report as `(unset)` rather than a
-concrete `false`, unlike the other four: the setup wizard's login prompt needs to tell
+concrete `false`, unlike the others: the setup wizard's login prompt needs to tell
 "not configured" apart from "explicitly set to false" (it only pre-highlights "Keep
 admin with no password" when the setting is concretely `false`; leaving it unset keeps
 the wizard's own recommended "managed login" highlighted). Giving it a real
@@ -412,7 +418,7 @@ the wizard's own recommended "managed login" highlighted). Giving it a real
 the setting resolves to exactly `true`.
 
 ```bash
-quickchr settings print                       # all 5 keys, resolved value + source
+quickchr settings print                       # all 6 keys, resolved value + source
 quickchr settings set default-channel testing # write one key to quickchr.env
 quickchr settings get default-arch            # print one key's resolved value
 quickchr settings reset default-channel       # delete one managed line
@@ -420,7 +426,7 @@ quickchr settings reset                       # clear all managed lines
 ```
 
 Credentials (`--add-user`, `MIKROTIK_WEB_ACCOUNT`/`MIKROTIK_WEB_PASSWORD`) are
-never stored here — `settings` only manages the 5 keys above, and does not
+never stored here — `settings` only manages the 6 keys above, and does not
 mutate any machine's `machine.json`.
 
 ### Global behavior
@@ -923,16 +929,20 @@ arch:
 |---|---|---|
 | macOS x86_64 | x86 | HVF |
 | macOS x86_64 | arm64 | TCG |
-| macOS arm64 (native bun) | arm64 | HVF |
+| macOS arm64 (native bun) | arm64 | TCG |
 | macOS arm64 (native bun) | x86 | TCG |
 | macOS arm64 (Rosetta bun) | arm64 | TCG |
+| macOS arm64 (Rosetta bun) | x86 | TCG |
 | Linux x86_64 + `/dev/kvm` writable | x86 | KVM |
 | Linux aarch64 + `/dev/kvm` writable | arm64 | KVM |
 | any other combo | any | TCG |
 
 `Bun` running under Rosetta on Apple Silicon reports `process.arch ===
-"x64"`, so HVF for arm64 is skipped (architecture mismatch). Run with
-native arm64 Bun to get arm64 HVF.
+"x64"`, so quickchr checks `sysctl.proc_translated` to identify the physical
+arm64 host. Auto-selection uses TCG for both guest architectures there: HVF
+cannot virtualize x86 across architectures, and current arm64 CHR images need
+AArch32 userspace support that Apple Silicon does not provide. Use `--accel`
+(or `QUICKCHR_ACCEL` / the `accel` setting) only to override this deliberately.
 
 ### Boot timeout
 
@@ -996,7 +1006,7 @@ managed via `quickchr settings get|set|print|reset` (§3, Meta). Atomic writes
 preserve every other line (comments, blank lines, foreign vars) byte-for-byte.
 `reset <key>` deletes the line entirely rather than blanking it, since a blank
 `KEY=` line is still "set" to a bash-sourced file. Never stores credentials —
-the 5 managed keys are all structural preferences, not secrets.
+the 6 managed keys are all structural preferences, not secrets.
 
 ### Environment variables consumed
 
@@ -1008,6 +1018,7 @@ the 5 managed keys are all structural preferences, not secrets.
 | `QUICKCHR_INTEGRATION` | `bun:test` gate for `test/integration/` |
 | `QUICKCHR_DEFAULT_CHANNEL` | `settings.ts` — env tier for the `default-channel` setting |
 | `QUICKCHR_DEFAULT_ARCH` | `settings.ts` — env tier for the `default-arch` setting |
+| `QUICKCHR_ACCEL` | `settings.ts` / `platform.ts` — env tier for the `accel` setting; forces `-accel` and bypasses detection |
 | `QUICKCHR_CACHE_MAX_SIZE` | `settings.ts` — env tier for the `cache-max-size` setting |
 | `QUICKCHR_TIMEOUT_EXTRA` | `settings.ts` — env tier for the `timeout-extra` setting |
 | `QUICKCHR_SECURE_LOGIN` | `settings.ts` — env tier for the `secure-login` setting |
@@ -1255,6 +1266,9 @@ prevents orphan disks accumulating across attempts.
   (MNDP) on the host via a `socket-connect` NIC.
 - **docs/qga-x86-macos-qemu10-investigation.md** — root cause for the
   QGA-on-macOS-arm64 limitation.
+- **docs/m4-hvf-arm64-investigation.md** — **open** investigation into why arm64
+  CHR panics under HVF on Apple M4 (why arm64 falls back to TCG there); evidence
+  ledger, competing theories, and the test plan to settle them.
 - **`.github/instructions/`** — agent-facing rules (testing, qemu,
   routeros-rest, provisioning, ci, bun-http, general).
 - **`examples/`** — runnable scripts (`bun run`): `quickstart` (single-CHR smoke),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/index.ts

@@ -157,6 +157,26 @@ export async function resolveTimeoutExtraMs(flags: Record<string, string | boole
 	return seconds !== undefined ? seconds * 1000 : undefined;
 }
 
+/** Apply an explicit `--accel <auto|tcg|hvf|kvm>` as the process-level accelerator
+ *  override, so every detectAccel() call in this run (QEMU args, boot timeouts,
+ *  respawn logic) agrees on one value. Absent flag → the accel setting's own
+ *  env/file/default tiers apply, so this only installs the top tier. Throws
+ *  INVALID_SETTING_VALUE on an unrecognized mode. Shared by cmdAdd and cmdStart. */
+export async function applyAccelFlag(flags: Record<string, string | boolean | string[]>): Promise<void> {
+	const value = flags.accel;
+	if (value === undefined) return;
+	const raw = Array.isArray(value)
+		? value.at(-1) ?? ""
+		: typeof value === "string"
+			? value
+			: "";
+	const [{ parseAccelMode }, { setAccelOverride }] = await Promise.all([
+		import("../lib/types.ts"),
+		import("../lib/platform.ts"),
+	]);
+	setAccelOverride(parseAccelMode(raw));
+}
+
 /** Resolve --secure-login/--no-secure-login, falling back to the secure-login setting
  *  only when neither flag was passed. Shared by cmdAdd, cmdStart, and cmdStart's
  *  --all bulk-restart path. */
@@ -535,6 +555,7 @@ async function cmdAdd(argv: string[]) {
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, formatPorts, formatNetworks, dim } = await import("./format.ts");
 	const { resolveSetting } = await import("../lib/settings.ts");
+	await applyAccelFlag(flags);
 
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
@@ -1175,6 +1196,8 @@ async function cmdSetup() {
 async function cmdStart(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	applyTimeoutExtraShortFlag(argv, flags, positional);
+	// Before the --all branch: both start paths must see the same override.
+	await applyAccelFlag(flags);
 
 	// --all: start every stopped machine in background
 	if (flagBool(flags, "all")) {
@@ -2720,6 +2743,9 @@ Options:
   --arch <arch>         Architecture: arm64, x86, auto (default: host native)
   --cpu <n>             vCPU count (default: 1)
   --mem <mb>            RAM in MB (default: 512)
+  --accel <mode>        Force QEMU accelerator: auto|tcg|hvf|kvm (default: auto).
+                        Anything but 'auto' bypasses detection, including the
+                        arm64-on-Apple-Silicon TCG fallback (tikoci/quickchr#97).
 	--boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
 	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
 	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
@@ -2802,6 +2828,9 @@ Options:
   --name <name>         Instance name
   --cpu <n>             vCPU count (default: 1)
   --mem <mb>            RAM in MB (default: 512)
+  --accel <mode>        Force QEMU accelerator: auto|tcg|hvf|kvm (default: auto).
+                        Anything but 'auto' bypasses detection, including the
+                        arm64-on-Apple-Silicon TCG fallback (tikoci/quickchr#97).
 	--boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
 	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
 	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
@@ -3056,6 +3085,8 @@ Managed keys:
   default-channel   Default --channel for 'add'/'start' and the setup wizard.
                     stable|long-term|testing|development (default: stable)
   default-arch      Default --arch. arm64|x86|auto (default: auto = host native)
+  accel             QEMU accelerator for 'add'/'start'.
+                    auto|tcg|hvf|kvm (default: auto = detect)
   cache-max-size    Auto-prune cap applied after each successful start.
                     Size string (e.g. 2G, 512M). (default: 2G)
   timeout-extra     Default for 'start's --timeout-extra/-T when omitted.

package/src/lib/platform.ts

@@ -3,8 +3,11 @@
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import type { EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo } from "./types.ts";
-import { QuickCHRError as QError } from "./types.ts";
+import type { AccelMode, EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo } from "./types.ts";
+import { QuickCHRError as QError, parseAccelMode } from "./types.ts";
+// settings-file.ts, not settings.ts: the latter's graph (cache → state → network
+// → platform) is a cycle that would load eagerly on every CLI start.
+import { loadSettingsFileDefaults } from "./settings-file.ts";
 
 /** UEFI firmware search paths by platform. */
 const EFI_CODE_PATHS = [
@@ -111,14 +114,11 @@ export function qgaKvmWarning(): string | null {
 	);
 }
 
-/** Whether guestArch requires cross-architecture emulation (TCG) on this host.
- *  Cross-arch emulation is significantly slower and needs more memory/timeout.
- *  arm64 guest on x86_64 host → TCG (slow).
- *  x86 guest on any host → HVF or KVM when available (fast). */
+/** Whether guestArch differs from the physical host CPU architecture.
+ *  Cross-arch TCG is significantly slower and needs more memory/timeout. */
 export function isCrossArchEmulation(guestArch: "x86" | "arm64"): boolean {
-	// x86 CHR is always runnable under HVF/KVM or TCG — never "slow" cross-arch.
-	// arm64 CHR on an arm64 host uses HVF/KVM; on an x86_64 host it falls back to TCG.
-	return guestArch === "arm64" && process.arch !== "arm64";
+	const hostIsArm64 = isAppleSiliconHost() || (process.platform !== "darwin" && process.arch === "arm64");
+	return (guestArch === "arm64") !== hostIsArm64;
 }
 
 /**
@@ -138,8 +138,132 @@ export function accelTimeoutFactor(accel: string, crossArch: boolean): number {
 	return crossArch ? 15.0 : 4.0;
 }
 
+/**
+ * Whether the physical host is Apple Silicon, including when quickchr itself
+ * runs as an x64 process under Rosetta.
+ *
+ * Apple Silicon implements **no AArch32 at any exception level**: its
+ * `ID_AA64PFR0_EL1` reports AArch64-only for EL0 and EL1, and HVF passes that
+ * hardware register straight through to the guest (the `-cpu` model is inert
+ * under HVF).  Current arm64 CHR images ship an AArch64 kernel over a *32-bit
+ * ARM* userspace — the appended initramfs `/init` is `ELF 32-bit LSB ARM
+ * EABI5`, and the system package holds 101 further ARM32 executables — so the
+ * guest kernel never sets `ARM64_HAS_32BIT_EL0`, `execve("/init")` returns
+ * -ENOEXEC, and Linux panics ~0.08 s in with "No working init found".
+ * TCG's emulated CPU models do provide AArch32 EL0, so the same image boots.
+ *
+ * This is an image-artifact incompatibility, not an accelerator or CPU-model
+ * bug: no QEMU flag and no macOS VMM can present a feature the silicon does not
+ * implement.  See docs/m4-hvf-arm64-investigation.md and tikoci/quickchr#97.
+ */
+let appleSiliconHostMemo: boolean | undefined;
+
+export function isAppleSiliconHost(): boolean {
+	if (process.platform !== "darwin") return false;
+	if (process.arch === "arm64") return true;
+	if (process.arch !== "x64") return false;
+	if (appleSiliconHostMemo !== undefined) return appleSiliconHostMemo;
+	try {
+		const result = Bun.spawnSync(["sysctl", "-n", "sysctl.proc_translated"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		appleSiliconHostMemo =
+			result.exitCode === 0 &&
+			new TextDecoder().decode(result.stdout).trim() === "1";
+	} catch {
+		appleSiliconHostMemo = false;
+	}
+	return appleSiliconHostMemo;
+}
+
+/** @internal Test-only: clear the memoized Rosetta probe between mocked runs. */
+export function resetAppleSiliconHostCache(): void {
+	appleSiliconHostMemo = undefined;
+}
+
+/**
+ * Process-level accelerator override, set by `--accel` (CLI) or by a library
+ * caller.  Highest tier of the documented precedence chain
+ * (flag > QUICKCHR_ACCEL env > quickchr.env > built-in "auto"); `undefined`
+ * means "not set, fall through to the settings tiers".
+ */
+let accelOverride: AccelMode | undefined;
+
+/** Force the accelerator for the rest of this process, or clear with undefined. */
+export function setAccelOverride(mode: AccelMode | undefined): void {
+	accelOverride = mode;
+}
+
+/**
+ * Resolve the accelerator override: process override > QUICKCHR_ACCEL env >
+ * quickchr.env > "auto".  Mirrors settings.ts's `accel` key resolution (same
+ * tiers, same validator) but reads the file tier directly to stay out of that
+ * module's import cycle.  Throws INVALID_SETTING_VALUE on an unrecognized mode.
+ */
+export function resolveAccelOverride(): AccelMode {
+	return resolveAccelOverrideWithSource().mode;
+}
+
+/** Which tier supplied the accelerator, for messages that must say *why*. */
+export type AccelOverrideSource = "flag" | "env" | "file" | "default";
+
+/**
+ * As resolveAccelOverride(), but also reports the tier the value came from.
+ * With three override tiers, "TCG because ~/.config/quickchr/quickchr.env says
+ * so" and "TCG because you passed --accel" are very different support answers,
+ * so the launch note names the source rather than guessing at it.
+ */
+export function resolveAccelOverrideWithSource(): { mode: AccelMode; source: AccelOverrideSource } {
+	if (accelOverride !== undefined) return { mode: accelOverride, source: "flag" };
+	const envRaw = process.env.QUICKCHR_ACCEL;
+	if (envRaw !== undefined) return { mode: parseAccelMode(envRaw), source: "env" };
+	const fileRaw = loadSettingsFileDefaults().QUICKCHR_ACCEL;
+	if (fileRaw !== undefined) return { mode: parseAccelMode(fileRaw), source: "file" };
+	return { mode: "auto", source: "default" };
+}
+
+/**
+ * User-facing name of the override tier — the thing the user would actually go
+ * edit.  Shared by the launch note and `doctor` so both name the same source;
+ * never print the raw AccelOverrideSource enum, which is internal.
+ */
+export function accelSourceLabel(source: AccelOverrideSource): string {
+	if (source === "flag") return "--accel";
+	if (source === "env") return "QUICKCHR_ACCEL";
+	if (source === "file") return "quickchr.env";
+	return "auto-detection";
+}
+
+/**
+ * One-line note about how the accelerator was chosen, or null when there is
+ * nothing worth saying.  Surfaced at launch so a user on slow emulation — or
+ * one who forced a mode that is known not to boot — understands why.
+ */
+export function accelNote(guestArch: "x86" | "arm64", accel: string): string | null {
+	const { mode: forced, source } = resolveAccelOverrideWithSource();
+	if (forced !== "auto") {
+		const base = `Accelerator configured as "${forced}" via ${accelSourceLabel(source)} — auto-detection bypassed.`;
+		if (guestArch === "arm64" && forced === "hvf" && isAppleSiliconHost()) {
+			return `${base} Note: arm64 CHR images still ship a 32-bit ARM userspace, which Apple Silicon cannot execute under HVF — expect "No working init found" unless MikroTik has shipped an AArch64-only image (tikoci/quickchr#97).`;
+		}
+		return base;
+	}
+	if (guestArch !== "arm64" || accel !== "tcg" || !isAppleSiliconHost()) return null;
+	return (
+		"arm64 CHR is running under TCG on Apple Silicon: the image's appended " +
+		"initramfs /init and most of its system package are 32-bit ARM, and Apple " +
+		"CPUs implement no AArch32 at any exception level, so an HVF guest panics " +
+		'with "No working init found". TCG is slower but boots. Override with ' +
+		"--accel hvf once MikroTik ships an AArch64-only arm64 image (tikoci/quickchr#97)."
+	);
+}
+
 /** Detect available QEMU acceleration for a guest architecture. */
 export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
+	const forced = resolveAccelOverride();
+	if (forced !== "auto") return forced;
+
 	const hostOs = process.platform;
 	const hostArch = process.arch; // "x64" | "arm64"
 
@@ -157,9 +281,10 @@ export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
 	}
 
 	if (hostOs === "darwin") {
-		// Apple Hypervisor Framework (HVF) is a system capability, not a per-process one.
-		// It is available if kern.hv_support=1, regardless of whether the bun process
-		// itself is arm64 native or running via Rosetta (process.arch="x64").
+		// Apple Hypervisor Framework only runs guests matching the physical host
+		// architecture. Rosetta can translate the quickchr process, but it cannot
+		// make x86 HVF guests run on Apple Silicon.
+		const appleSilicon = isAppleSiliconHost();
 		try {
 			const hvResult = Bun.spawnSync(["sysctl", "-n", "kern.hv_support"], {
 				stdout: "pipe",
@@ -167,13 +292,22 @@ export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
 			});
 			const hv = new TextDecoder().decode(hvResult.stdout).trim();
 			if (hv === "1") {
-				if (guestArch === "x86") return "hvf";
-				// arm64 guest HVF requires a native arm64 host process.
-				// Use process.arch — on Intel Macs this is "x64" so arm64 guests get TCG,
-				// which is correct (Intel can't run arm64 HVF). On Apple Silicon, native
-				// bun reports "arm64" and gets HVF. Rosetta bun reports "x64" and gets TCG
-				// (acceptable — arm64 TCG on Apple Silicon still boots in <5 min).
-				if (process.arch === "arm64") return "hvf";
+				if (guestArch === "x86" && !appleSilicon) return "hvf";
+				// arm64 guest: falls through to TCG on every macOS host.
+				//
+				// On Intel Macs process.arch is "x64" and arm64 HVF is impossible.
+				// On Apple Silicon HVF *is* available but must not be used: no Apple
+				// CPU implements AArch32 at any exception level, and current arm64 CHR
+				// images require a 32-bit ARM userspace, so an HVF guest panics at init
+				// (see isAppleSiliconHost()).  arm64 TCG still boots, but is slower.
+				//
+				// Restore signal (#97) is the *guest artifact*, not the host or QEMU
+				// version: a future arm64 CHR whose appended /init and system-package
+				// executables are all AArch64, verified by a real HVF boot.  Until then
+				// `--accel hvf` / QUICKCHR_ACCEL=hvf is the escape hatch for testing.
+				//
+				// x86 guests also fall through on Apple Silicon because HVF cannot
+				// virtualize across architectures; their escape hatch is the same.
 			}
 		} catch { /* fall through */ }
 	}

package/src/lib/quickchr.ts

@@ -26,7 +26,7 @@ import type {
 } from "./types.ts";
 import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./types.ts";
 import packageJson from "../../package.json";
-import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
+import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
 	resolveVersion,
 	isValidVersion,
@@ -1526,6 +1526,8 @@ export class QuickCHR {
 		// Build QEMU args and spawn
 		const platform = await detectPlatform();
 		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);
@@ -1838,6 +1840,8 @@ export class QuickCHR {
 
 		const platform = await detectPlatform();
 		const accel = await detectAccel(state.arch);
+		const note = accelNote(state.arch, accel);
+		if (note) (logger ?? createLogger()).warn(note);
 		registerSocketMembers(state);
 		const hostfwd = buildHostfwdString(state.ports);
 		const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
@@ -2001,10 +2005,14 @@ export class QuickCHR {
 		try {
 			const platform = await detectPlatform();
 			if (platform.accelAvailable.length > 0) {
+				// Under an override, accelAvailable is just the forced mode for every
+				// arch — say so, or the row reads as a capability report it isn't.
+				const { mode: forced, source } = resolveAccelOverrideWithSource();
+				const suffix = forced === "auto" ? "" : ` — configured override via ${accelSourceLabel(source)}`;
 				checks.push({
 					label: "Acceleration",
 					status: "ok",
-					detail: `${platform.accelAvailable.join(", ")} (host: ${platform.hostArch})`,
+					detail: `${platform.accelAvailable.join(", ")} (host: ${platform.hostArch})${suffix}`,
 				});
 			} else {
 				checks.push({

package/src/lib/settings-file.ts

@@ -0,0 +1,52 @@
+/**
+ * The `quickchr.env` file tier of the settings system — path, raw read, and
+ * dotenv-style parse.
+ *
+ * Split out of settings.ts as a **leaf** module (node:fs + paths.ts only) so
+ * platform.ts can resolve the `accel` override's file tier without pulling in
+ * settings.ts's transitive graph (settings → cache → state → network →
+ * platform). That cycle loads eagerly at CLI startup and measurably slows every
+ * `quickchr` invocation. settings.ts re-exports everything here, so this split
+ * is invisible to callers.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { quickchrConfigDir } from "./paths.ts";
+
+export const SETTINGS_FILE_NAME = "quickchr.env";
+
+/** ~/.config/quickchr/quickchr.env */
+export function settingsFilePath(): string {
+	return join(quickchrConfigDir(), SETTINGS_FILE_NAME);
+}
+
+/** Raw non-empty lines, in file order. [] if the file doesn't exist. */
+export function readSettingsFileLines(): string[] {
+	const path = settingsFilePath();
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+
+/** Parse QUICKCHR_*=value lines into a flat map. Blank/comment lines ignored; later dup wins. */
+export function parseSettingsFileLines(lines: readonly string[]): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+		result[key] = line.slice(eq + 1).trim();
+	}
+	return result;
+}
+
+/** The `file` tier every resolver call reads. {} when the file is absent. */
+export function loadSettingsFileDefaults(): Record<string, string> {
+	return parseSettingsFileLines(readSettingsFileLines());
+}

package/src/lib/settings.ts

@@ -13,12 +13,16 @@
  * input resolution, never per-machine config.
  */
 
-import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, fsyncSync } from "node:fs";
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, fsyncSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { ARCHES, CHANNELS, QuickCHRError } from "./types.ts";
-import type { Channel } from "./types.ts";
+import { ARCHES, CHANNELS, QuickCHRError, parseAccelMode } from "./types.ts";
+import type { AccelMode, Channel } from "./types.ts";
 import { parseSizeString, DEFAULT_CACHE_MAX_BYTES } from "./cache.ts";
-import { quickchrConfigDir } from "./paths.ts";
+import { loadSettingsFileDefaults, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
+
+// The quickchr.env file tier lives in the leaf module settings-file.ts (see its
+// header for why); re-exported here so settings.ts stays the single public entry.
+export { SETTINGS_FILE_NAME, loadSettingsFileDefaults, parseSettingsFileLines, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
 
 export type SettingsValue = string | number | boolean;
 export type SettingsSource = "env" | "file" | "default";
@@ -93,6 +97,17 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		parse: parseArchSetting,
 		serialize: (v) => String(v),
 	},
+	{
+		// "auto" = let detectAccel() choose, including its platform fallbacks
+		// (notably arm64-on-Apple-Silicon → TCG, see DESIGN.md #10). Any other
+		// value is passed to QEMU verbatim and skips detection entirely — the
+		// escape hatch for testing HVF against a future AArch64-only arm64 image.
+		attr: "accel",
+		envKey: "QUICKCHR_ACCEL",
+		builtinDefault: "auto" satisfies AccelMode,
+		parse: (raw) => parseAccelMode(raw),
+		serialize: (v) => String(v),
+	},
 	{
 		attr: "cache-max-size",
 		envKey: "QUICKCHR_CACHE_MAX_SIZE",
@@ -108,7 +123,7 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		serialize: (v) => String(v),
 	},
 	{
-		// No builtinDefault: unlike the other 4 keys, the wizard needs to distinguish
+		// No builtinDefault: unlike the other 5 keys, the wizard needs to distinguish
 		// "not configured" from "explicitly false" (src/cli/wizard.ts's userChoice
 		// initialValue only pre-highlights "admin" when the setting is concretely
 		// false) — a builtinDefault here would collapse that distinction and always
@@ -123,13 +138,6 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 	},
 ];
 
-export const SETTINGS_FILE_NAME = "quickchr.env";
-
-/** ~/.config/quickchr/quickchr.env */
-export function settingsFilePath(): string {
-	return join(quickchrConfigDir(), SETTINGS_FILE_NAME);
-}
-
 /** Accepts "default-channel" | "QUICKCHR_DEFAULT_CHANNEL" | "DEFAULT_CHANNEL" | "default_channel". */
 export function lookupSettingsKey(input: string): SettingsKeyDef | undefined {
 	let name = input.trim();
@@ -150,36 +158,6 @@ function unknownKeyError(input: string): QuickCHRError {
 
 // --- File IO ---
 
-/** Raw non-empty lines, in file order. [] if the file doesn't exist. */
-export function readSettingsFileLines(): string[] {
-	const path = settingsFilePath();
-	if (!existsSync(path)) return [];
-	const text = readFileSync(path, "utf-8");
-	const lines = text.split("\n");
-	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-	return lines;
-}
-
-/** Parse QUICKCHR_*=value lines into a flat map. Blank/comment lines ignored; later dup wins. */
-export function parseSettingsFileLines(lines: readonly string[]): Record<string, string> {
-	const result: Record<string, string> = {};
-	for (const rawLine of lines) {
-		const line = rawLine.trim();
-		if (line.length === 0 || line.startsWith("#")) continue;
-		const eq = line.indexOf("=");
-		if (eq <= 0) continue;
-		const key = line.slice(0, eq).trim();
-		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
-		result[key] = line.slice(eq + 1).trim();
-	}
-	return result;
-}
-
-/** The `file` tier every resolver call reads. {} when the file is absent. */
-export function loadSettingsFileDefaults(): Record<string, string> {
-	return parseSettingsFileLines(readSettingsFileLines());
-}
-
 function lineEnvKey(line: string): string | undefined {
 	const trimmed = line.trim();
 	if (trimmed.length === 0 || trimmed.startsWith("#")) return undefined;

package/src/lib/types.ts

@@ -13,6 +13,28 @@ export const CHANNELS: readonly Channel[] = Object.freeze(["stable", "long-term"
 export type Arch = "arm64" | "x86";
 export const ARCHES: Arch[] = ["arm64", "x86"];
 
+// --- Acceleration ---
+
+/**
+ * QEMU accelerator selection. "auto" means detectAccel() picks, including its
+ * platform safety fallbacks; the other three force `-accel <mode>` verbatim and
+ * bypass detection entirely (see DESIGN.md #10).
+ */
+export type AccelMode = "auto" | "tcg" | "hvf" | "kvm";
+export const ACCEL_MODES: readonly AccelMode[] = Object.freeze(["auto", "tcg", "hvf", "kvm"] as AccelMode[]);
+
+/** Validate an accelerator name from a CLI flag, env var, or settings file. */
+export function parseAccelMode(raw: string): AccelMode {
+	const v = raw.trim().toLowerCase();
+	if (!(ACCEL_MODES as readonly string[]).includes(v)) {
+		throw new QuickCHRError(
+			"INVALID_SETTING_VALUE",
+			`Invalid value "${raw}" for accel — must be one of ${ACCEL_MODES.join(", ")}`,
+		);
+	}
+	return v as AccelMode;
+}
+
 // --- Networking ---
 
 /** @deprecated Use NetworkSpecifier instead. Kept for backward compatibility with old machine.json files. */