@tikoci/quickchr 0.5.0 → 0.5.2

package/.bun-version

@@ -0,0 +1 @@
+1.4.4

package/DESIGN.md

@@ -144,7 +144,8 @@ Current consumers are all first-party tikoci projects (centrs, donny, restraml),
 ├── machines/
 │   └── 7.22.1-arm64-1/
 │       ├── machine.json       # Config + state
-│       ├── disk.img           # Working copy
+│       ├── boot.qcow2         # Boot disk, qcow2 — or disk.img when raw (see below)
+│       ├── disk<N>.qcow2      # Extra disks
 │       ├── efi-vars.qcow2     # UEFI vars (arm64; qcow2 so savevm works — #31)
 │       ├── monitor.sock       # QEMU monitor
 │       ├── serial.sock        # Serial console
@@ -156,12 +157,60 @@ Current consumers are all first-party tikoci projects (centrs, donny, restraml),
     └── boot-failure-<machine>-<iso8601>.json
 ```
 
+**One boot disk per machine.** A raw machine boots `disk.img`, a copy of the cached
+image. A qcow2 machine boots `boot.qcow2`, converted straight from the cached image
+into a `.tmp` file, checked to be a standalone qcow2 (no backing file), then renamed
+into place. Machines created before 0.5.1 also kept the raw `disk.img` the qcow2 came
+from: a full-size copy (128 MiB x86) that nothing reads. Restart no longer requires it
+(#200). `clean` removes it, and nothing else deletes it implicitly (#199). The shared
+cache image stays: `clean` and a failed first boot's rollback rebuild from it.
+
+A missing disk is rebuilt only while the machine has never booted. A booted machine's
+disks hold guest state, so a missing `boot.qcow2`, `disk.img` or extra disk is
+`MACHINE_NOT_FOUND`, never a silent rebuild from factory. The way out is to restore the
+file or run `quickchr clean`.
+
+**Storage admission (#199).** An operation that writes new data (creating a machine,
+an image or package download) is admitted when **each filesystem it writes to** has
+`estimate + storage-reserve` free there. It replaced a flat 10 GiB floor that refused
+small hosts which had room. The operation's writes are parts with paths (boot disk →
+`machines/`, downloads → the cache it writes to), grouped by `stat().dev`. The estimate
+is a per-stage constant (`STORAGE_ESTIMATES` in `storage.ts`), rounded up from one
+host's measurements and written down there. The reserve (default 2 GiB) absorbs the
+estimate's error and keeps the host usable. Restart is never gated. Virtual disk
+capacity is not charged: a sparse disk's growth is the guest's, after admission.
+
+Under pressure, eligible cache entries are evicted, but only from a cache on the short
+filesystem, and only when everything eligible could cover the gap. Free space is then
+**measured again**, in passes, until the measurement admits or nothing more can be
+evicted. Logical sizes are not proof of room (sparse files, APFS clones).
+
+**Coordination** (`storage-lease.ts`, after Codex's review of #203 reproduced both
+races). One data-dir lock, held for milliseconds: a check-and-record, or an eviction
+pass. Under it, an operation records a **lease** naming the cache entries it is about
+to read (pins) and the bytes it is about to write, per filesystem. Admission subtracts
+other live leases' bytes from measured free space, so two creators cannot spend the
+same bytes. Eviction skips pinned entries. A pin is recorded before the reader checks
+the entry exists, so an eviction either sees it or has already finished, and then the
+reader fetches the entry again. A create's lease lasts until its `machine.json` is
+saved, which protects the image from then on. A download's lease lasts the download.
+A dead pid's lease is ignored and deleted. A create's own downloads are checked up
+front, so it refuses early, but are reserved only by the download itself, so they are
+not counted twice. Automatic eviction also skips anything used in the last 30
+minutes (a cache hit bumps its mtime). That rule is not what protects a reader; pins
+are. It spares what a finished `cache add` fetched for a later process.
+
+The cache cap (`cache-max-size`) is retention, separate from admission. It counts
+images, package archives with their extractions (one entry: the extraction is only a
+hit while its archive exists) and interrupted downloads. Files quickchr did not write
+are reported and never deleted. A failed delete is reported as failed, not freed.
+
 **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 6 managed keys:
-`default-channel`, `default-arch`, `accel`, `cache-max-size`, `timeout-extra`,
-`secure-login`.
+`QUICKCHR_<KEY>` env var > `quickchr.env` > built-in default. The 7 managed keys:
+`default-channel`, `default-arch`, `accel`, `cache-max-size`, `storage-reserve`,
+`timeout-extra`, `secure-login`.
 See MANUAL.md's CLI reference and environment-variables sections for the full surface.
 
 ## Platform Support
@@ -196,7 +245,9 @@ CI, integration and release all install, enforced by `scripts/check-bun-pin.ts`
 runtime could change between two identical commits — and did: a six-week gap with no `ci.yml`
 runs spanned the Bun 1.4.0 release, and the next PR inherited a 1.3.14 → 1.4.2 jump as if it
 were its own regression. Anything that can turn the build red is a dependency and belongs in
-a reviewable diff; "whatever is newest at run time" is not a version.
+a reviewable diff; "whatever is newest at run time" is not a version. The same
+`.bun-version` file ships in the npm package so `doctor` can name the tested
+runtime and warn when the running Bun is older without duplicating the pin.
 
 **The 2026-07 refactor (#29)** replaced the organically-grown scheme (integration on every
 PR push, three parallel copies of the runner logic, `continue-on-error` green-washing)
@@ -229,9 +280,10 @@ with a layered design:
 - **`release.yml`** — one-click publish from committed release state: freshness gate
   (no suite re-run — main is kept continuously release-able) + `package.json` version
   with a matching non-empty CHANGELOG section → tag + GitHub Release + `npm publish
-  --provenance` (odd minor → `next`, even → `latest`; a stable release is then also
-  tagged `next`, since there is no separately maintained pre-release line and `next`
-  must not point at something older than `latest`). CI never bumps versions or pushes
+  --provenance` under the dispatch-time `npm-tag` (default `next`; promoted to `latest`
+  after QA — not derived from the version number; a `latest` release is also tagged
+  `next`, since there is no separately maintained pre-release line and `next` must not
+  point at something older than `latest`). CI never bumps versions or pushes
   to protected `main`.
 - **`ros-versions.yml`** — daily: new RouterOS versions (per channel) with no linux-x86
   record in `ci-data/tested-versions.json` ride the `routeros-targets` matrix of a

package/MANUAL.md

@@ -64,7 +64,7 @@ by the user (or their AI agent) using `quickchr` as a building block.
 | Bun ≥ 1.1 | runtime | macOS/Linux: `curl -fsSL https://bun.sh/install \| bash` · Windows: `powershell -c "irm bun.sh/install.ps1 \| iex"` (or `winget install Oven-sh.Bun`) |
 | `qemu-system-x86_64` | x86 CHR | brew/apt/dnf/pacman · Windows: `winget install SoftwareFreedomConservancy.QEMU` |
 | `qemu-system-aarch64` | arm64 CHR | brew/apt/dnf/pacman · Windows: bundled in the SFC QEMU package above |
-| `qemu-img` | `--boot-size`, `--add-disk`, snapshots | included in all standard QEMU packages (brew, apt, dnf, SFC installer) |
+| `qemu-img` | Default qcow2 creation, setup wizard, `--boot-size`, `--add-disk`, snapshots | included in all standard QEMU packages (brew, apt, dnf, SFC installer) |
 | UEFI firmware (edk2) | arm64 CHR | `qemu-efi-aarch64` (apt), `edk2-aarch64` (dnf), bundled with `qemu` (brew) |
 | `socket_vmnet` (optional) | rootless `shared`/`bridged` networking on macOS | `brew install socket_vmnet` |
 | `socat` (optional) | piping serial console externally | brew/apt |
@@ -72,31 +72,40 @@ by the user (or their AI agent) using `quickchr` as a building block.
 
 ### Install quickchr
 
-The first GitHub release is **0.1.1** — pre-release per the changelog's
-odd/even policy. Not yet on npm.
+Install the stable npm channel:
 
 ```bash
-# Library
-bun add github:tikoci/quickchr
+bun install -g @tikoci/quickchr
+bun add @tikoci/quickchr
+```
 
-# CLI from source (until npm publish)
-git clone https://github.com/tikoci/quickchr
-cd quickchr
-bun install
-bun run dev -- doctor
+For prerelease QA, use `@next` for the current candidate or, after publication,
+`@0.5.1` to pin this candidate. A release is published to `next` first and promoted
+to `latest` once QA passes; `next` is never older than `latest`. The quickchr package
+channel is independent of `--channel`, which selects a RouterOS firmware channel.
+
+```bash
+bun install -g @tikoci/quickchr@0.5.1
+bun add @tikoci/quickchr@0.5.1
+quickchr --version
 ```
 
-Once `0.2.0` is published to npm:
+To run an unpublished checkout:
 
 ```bash
-bun install -g @tikoci/quickchr
+git clone https://github.com/tikoci/quickchr
+cd quickchr
+bun install
+bun run dev -- doctor
 ```
 
 ### `quickchr doctor`
 
 Reports prerequisite status, accelerator availability, image cache
 size, machine count, free disk space, and shell-completion install
-state. Exit code is `0` when no checks return `error` (warnings are OK).
+state. The disk check measures the data dir's filesystem and warns when free
+space is under `storage-reserve` + 2 GiB. Exit code is `0` when no checks return
+`error` (warnings are OK).
 
 ```bash
 quickchr doctor              # human-readable
@@ -107,7 +116,9 @@ The `--json` form emits `{ ok, checks, staleImages }`, where `checks` is an
 array of `{ label, status, detail }` and `staleImages` lists cached images older
 than the current long-term release. The exit code still reflects `ok`.
 
-![quickchr doctor output](./images/doctor-demo.gif)
+`doctor` reports the tested Bun pin and warns when the running runtime is older.
+
+![quickchr doctor output](./docs/images/doctor-demo.gif)
 
 Use this whenever a `start` fails — the diagnostic almost always points
 at a missing dependency, missing firmware, or insufficient disk.
@@ -116,7 +127,7 @@ at a missing dependency, missing firmware, or insufficient disk.
 
 ## 3. CLI command reference
 
-The dispatcher lives in `src/cli/index.ts` (lines 121–194). Help text is
+The dispatcher lives in `src/cli/index.ts`. Help text is
 available for every command via `quickchr help <command>`.
 
 ### Lifecycle
@@ -129,14 +140,14 @@ directory, downloads the RouterOS image (cached), and writes
 
 | Flag | Default | Notes |
 |---|---|---|
-| `--name <s>` | auto | `host-arch-N` if omitted |
+| `--name <s>` | auto | `version-arch-N` if omitted |
 | `--version <ver>` | latest in channel | e.g., `7.22.1` |
 | `--channel <ch>` | `stable` | `stable`, `long-term`, `testing`, `development` |
 | `--arch <a>` | host native | `arm64`, `x86`, or `auto` |
 | `--cpu <n>` | `1` | vCPU count |
 | `--mem <mb>` | `512` | RAM (cross-arch TCG bumps to `1024`) |
 | `--boot-disk-format <f>` | `qcow2` | `qcow2` or `raw` |
-| `--boot-size <size>` | — | Resize boot disk; needs `qemu-img`; auto-converts to qcow2 |
+| `--boot-size <size>` | — | Resize qcow2 boot disk; needs `qemu-img`; explicit raw is refused |
 | `--add-disk <size>` | — | Extra blank qcow2 disk; repeatable |
 | `--forward <spec>` | — | Extra hostfwd port or built-in service host-port pin; repeatable. See §Custom port forwards. |
 | `--add-package <pkg>` | — | Provisioning, repeatable, ≥ 7.20.8 |
@@ -150,6 +161,7 @@ directory, downloads the RouterOS image (cached), and writes
 | `--device-mode <m>` | — | `rose`, `advanced`, `basic`, `home`, `auto`, `skip`, ≥ 7.20.8 |
 | `--device-mode-enable <f,...>` | — | Repeatable, comma-separated |
 | `--device-mode-disable <f,...>` | — | Repeatable, comma-separated |
+| `--no-device-mode` | — | Skip device-mode provisioning entirely |
 | `--add-network <spec>` | `user` | See §7. Repeatable. |
 | `--no-network` | false | Headless, no NICs |
 | `--no-winbox` | false | Exclude WinBox port |
@@ -168,15 +180,19 @@ stdio to your terminal (`--fg`). Accepts the same provisioning flags as `add`.
 QEMU runs detached in its own session either way, so it survives a signal to the
 shell that started it.
 
+When `<name>` matches no machine (a typo, or one removed earlier), `start` creates a
+factory CHR under that name and says so: `<name> created and started`, or
+`created — not waiting for RouterOS` with `--no-wait`. A machine that already
+existed, including one made by `add`, prints `started`.
+
 Additional flags:
 
 | Flag | Notes |
 |---|---|
-| `--all` | Start every stopped machine in background; accepts readiness, acceleration, timeout and secure-login options only. Other options are refused rather than ignored |
+| `--all` | Start every stopped machine in background; accepts readiness, acceleration, timeout and secure-login options only. Other options are refused rather than ignored. `--secure-login` is resolved per machine: one that has never booted creates the managed login; one that already booted accepts it as a no-op only if it already has one, and is refused otherwise. With `--no-wait`, a never-booted machine refuses it (provisioning needs the wait). Machines start one at a time, so a refusal stops the batch after the earlier machines have started |
 | `--no-wait` | Return as soon as QEMU is running (past the 1.5 s early-exit check), with state and ports persisted; do not wait for RouterOS. Refused with any provisioning flag, including first-boot options `add` recorded, and with `--fg` |
 | `--fg` / `--foreground` (alias `--no-bg`, `--no-background`) | Serial console on stdio |
 | `--bg` / `--background` | **Deprecated, does nothing.** Background is the default, and the flag never made `start` return early — it only ever chose where the serial console went. Prints a warning; use `--no-wait` |
-| `--install-deps` | Auto-install missing host deps (calls package manager) |
 | `--timeout-extra <s>` / `-T <s>` | Add extra seconds to computed boot timeout |
 | `--dry-run` | Print resolved options and QEMU command, exit |
 
@@ -394,7 +410,8 @@ the Library API reference.
 #### `exec <name> <command> [--via=auto|rest|qga|console|ssh] [--user u] [--password p] [--timeout=ms]`
 
 Run a RouterOS CLI command. See §12 for transport details and JSON
-output trick.
+output trick. Exit 0 means the command was delivered, not that RouterOS
+accepted it — see §12 "Exit status" for the pass/fail route.
 
 #### `console <name>`
 
@@ -471,7 +488,7 @@ Interactive wizard (`@clack/prompts`) that walks through all machine creation
 options and starts the CHR. Triggered by `quickchr setup` or automatically
 when `quickchr` is run with no subcommand on a TTY.
 
-![quickchr setup wizard walkthrough](./images/wizard-demo.gif)
+![quickchr setup wizard walkthrough](./docs/images/wizard-demo.gif)
 
 **First-run detection**: if no machines exist yet, the wizard opens with a
 welcome message before the first prompt.
@@ -498,7 +515,10 @@ another machine, view status, or quit.
 | 12 | Run mode: background / foreground | background | (default) / `--fg` |
 | 13 | Final confirmation | — | — |
 
-Steps 7–9 are skipped when `qemu-img` is absent (a warning is shown). Step 10
+The wizard requires `qemu-img` and refuses before any prompts or image downloads
+when it is absent, showing the install remedy. For a raw x86 boot without `qemu-img`,
+use `quickchr add --arch x86 --boot-disk-format raw` to create a stopped machine,
+then `quickchr start <name>` with the returned name to boot it. Step 10
 only appears when the platform supports networks beyond user-mode (macOS or
 Linux). The provisioning gate (step 11) only appears for RouterOS ≥ 7.20.8;
 older versions show an upgrade prompt.
@@ -567,6 +587,64 @@ appended directly to `$GITHUB_OUTPUT`.
 `--json` intentionally emits one JSON object for programmatic parsing; use the
 default output form when writing step outputs directly.
 
+`cache list [--json]` shows each cache entry with its version, arch, size, age
+(time since it was cached or last used) and whether it is in use. Entries are:
+
+- **images** (`chr-<ver>[-arm64].img`, and a `.img.zip` not yet extracted). An
+  image is **in use** while any machine, running or stopped, was created from
+  that version and arch: `clean` and a failed first boot rebuild from it.
+- **package archives** (`packages-<arch>-<ver>`): the `all_packages` ZIP and its
+  extraction, sized and deleted together, since the extraction is only a cache
+  hit while its ZIP is there. In use while a machine that asks for packages has
+  not finished its first boot.
+- **partial** entries: an interrupted download (`*.<pid>-<id>.part`) or
+  extraction (`.quickchr-image-*`, `.quickchr-packages-*`). In use while the
+  process that wrote it is alive (an extraction: for 30 minutes after its last
+  write). `prune` removes stale ones before anything else.
+
+`cache list --json` prints an array of entry objects, including `kind` (`image`, `image-zip`,
+`packages` or `partial`) and `paths` (every file deleting the entry removes).
+Files in the cache that quickchr did not write are reported as "Other files"
+and never deleted. `prune` and `clear` never delete an in-use entry.
+
+```bash
+quickchr cache list
+quickchr cache prune --older-than 7.22 --dry-run   # versions below 7.22
+quickchr cache prune --max-age 30d                 # not used for more than 30 days
+quickchr cache prune --max-size 2G                 # oldest versions first, until <= 2 GiB
+quickchr cache clear --all                         # every entry not in use
+```
+
+`prune` needs at least one of `--older-than <ver>`, `--max-age <dur>` or
+`--max-size <size>`, and applies them in that order when combined. `--max-size`
+evicts the oldest RouterOS version first (oldest cache time breaks ties) until
+the total, in-use entries included, fits. Durations are `<N>(s|m|h|d|w)`; sizes
+are `<N>(K|M|G|T)` with an optional `i`/`B`, read as IEC binary. `--dry-run`
+lists what `prune` or `clear` would delete without deleting it. `clear` refuses
+without `--all`. A delete that fails is listed on stderr, is not counted as
+freed, and makes the command exit 1. A cache hit counts as a use, so `--max-age`
+measures time since an entry was last used.
+
+Separately, a successful `start` prunes to the `cache-max-size` setting (default
+`2G`; see `settings` below). That automatic prune, and the one below, skip any
+entry used in the last 30 minutes, which another create may be reading.
+
+**Disk space.** Creating a machine (`add`, or `start` with a new name) and
+filling the cache (an image or package download) are admitted when each
+filesystem the operation writes to has room for what it writes there plus the
+`storage-reserve` setting (default `2G`), less what other quickchr operations
+in progress have already claimed. The estimate is the boot disk
+(192 MiB), plus an image download (256 MiB) and a package download (192 MiB)
+when those are not cached yet, so a cold create needs about 2.6 GiB free and a
+warm one about 2.2 GiB. When there is not enough, quickchr first evicts what the
+cache can spare on that filesystem (oldest version first; never entries a
+machine or an operation in progress needs, nor recently used ones), measures
+again until there is room or nothing more can go, and only then refuses with `INSUFFICIENT_DISK_SPACE`,
+naming the free space, what it needed, what it evicted and what it kept.
+Restarting an existing machine, `stop`, `remove` and read-only commands are
+never gated. The estimate covers creation, not a guest that later fills its
+disk: extra disks and `--boot-size` are sparse and grow as the guest writes.
+
 #### `settings [print|get|set|reset] [key] [value] [--json]`
 
 Manage quickchr's own global preferences — repeated flags/defaults that
@@ -583,6 +661,7 @@ Precedence per key (highest wins): CLI flag > `QUICKCHR_<KEY>` env var >
 | `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` |
+| `storage-reserve` | Free space creating a machine or filling the cache must leave, beyond what it writes | size string | `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) |
 
@@ -601,7 +680,7 @@ the wizard's own recommended "managed login" highlighted). Giving it a real
 the setting resolves to exactly `true`.
 
 ```bash
-quickchr settings print                       # all 6 keys, resolved value + source
+quickchr settings print                       # all 7 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
@@ -609,14 +688,14 @@ quickchr settings reset                       # clear all managed lines
 ```
 
 Credentials (`--add-user`, `MIKROTIK_WEB_ACCOUNT`/`MIKROTIK_WEB_PASSWORD`) are
-never stored here — `settings` only manages the 6 keys above, and does not
+never stored here — `settings` only manages the 7 keys above, and does not
 mutate any machine's `machine.json`.
 
 ### Global behavior
 
 | Env var | Effect |
 |---|---|
-| `QUICKCHR_DATA_DIR` | Override the data root (defaults to `$XDG_DATA_HOME/quickchr` or platform equivalent — see §8) |
+| `QUICKCHR_DATA_DIR` | Override the data root (defaults to `~/.local/share/quickchr` on POSIX or the Windows path — see §8) |
 | `QUICKCHR_NO_PROMPT` | Force non-interactive mode (skips all wizards) |
 | `QUICKCHR_DEBUG` | Emit `[debug]` lines from the progress logger |
 | `QUICKCHR_INTEGRATION` | Required to run `test/integration/` |
@@ -824,14 +903,14 @@ redact before logging or attaching to bug reports.
 | Field | Type | Default | Notes |
 |---|---|---|---|
 | `name` | string | auto | Must not start with `-` |
-| `version` | string | — | Mutually exclusive with `channel` |
+| `version` | string | — | Wins over `channel`: passing both warns and uses `version` |
 | `channel` | Channel | `"stable"` | |
 | `arch` | `"arm64" \| "x86"` | host | |
 | `cpu` | number | `1` | |
 | `mem` | number | `512` (1024 cross-arch TCG) | MiB |
 | `background` | boolean | `true` | Where the serial console goes — not whether `start()` waits |
 | `wait` | boolean | `true` | `false` resolves once QEMU is running and leaves readiness to the caller (`instance.waitForBoot()`); refused with provisioning or `background: false` (`INVALID_ARGUMENT`) |
-| `bootDiskFormat` | `"raw" \| "qcow2"` | `"raw"` (auto-`qcow2` if `bootSize`) | |
+| `bootDiskFormat` | `"raw" \| "qcow2"` | `"raw"` (auto-`qcow2` if `bootSize`) | The CLI always passes a format, defaulting to `qcow2`; the `"raw"` default applies to library callers only |
 | `bootSize` | string | — | e.g., `"512M"`, `"2G"`. Needs `qemu-img` |
 | `extraDisks` | string[] | `[]` | Each entry is a size string |
 | `networks` | NetworkSpecifier[] | `["user"]` | See §7 |
@@ -845,7 +924,7 @@ redact before logging or attaching to bug reports.
 | `secureLogin` | boolean | `false` | **`true` is the explicit trigger** for managed-account creation |
 | `license` | `LicenseInput` | — | `"p1"` / `"p10"` / `"unlimited"` or `LicenseOptions` |
 | `deviceMode` | `DeviceModeOptions` | — | `{mode?, enable?[], disable?[]}` |
-| `installDeps` | boolean | — | Auto-install missing OS deps |
+| `installDeps` | boolean | — | **Deprecated, ignored.** Never installed anything; run `quickchr doctor` for install hints |
 | `dryRun` | boolean | `false` | Print QEMU command and exit |
 | `timeoutExtra` | number | `0` | Extra **milliseconds** added to boot timeout |
 | `onProgress` | `(msg) => void` | `console.log` | `[debug]` lines only when `QUICKCHR_DEBUG=1` |
@@ -1183,10 +1262,10 @@ restrictions, half-open SLiRP under TCG), see `docs/networking.md`.
 
 ## 8. Storage layout
 
-### macOS / Linux (XDG)
+### macOS / Linux
 
 ```text
-$XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
+~/.local/share/quickchr/
 ├── .allocate.lock/              held while a new machine picks its ports/MACs
 ├── cache/                       Downloaded RouterOS images
 │   ├── chr-7.22.1.img.zip
@@ -1195,8 +1274,8 @@ $XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
 ├── machines/
 │   └── <name>/
 │       ├── machine.json         Persisted MachineState
-│       ├── disk.img | disk.qcow2
-│       ├── extra-disk-*.qcow2
+│       ├── boot.qcow2 | disk.img  boot disk: qcow2 (CLI default) or raw — one, not both
+│       ├── disk<N>.qcow2        extra disks
 │       ├── efi-vars.fd          arm64 only (UEFI vars)
 │       ├── monitor.sock         QEMU monitor
 │       ├── serial.sock          serial console
@@ -1209,8 +1288,8 @@ $XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
     └── <name>.json
 ```
 
-`$XDG_DATA_HOME` defaults to `~/.local/share/quickchr/`. Override the
-whole tree with `QUICKCHR_DATA_DIR=/some/path`.
+The data root is `~/.local/share/quickchr/`; `XDG_DATA_HOME` does not
+change it. Override the whole tree with `QUICKCHR_DATA_DIR=/some/path`.
 
 **Global settings** live separately, under the XDG **config** tier, not this
 data tree: `~/.config/quickchr/quickchr.env` (dotenv-style). See §3's
@@ -1224,7 +1303,7 @@ var list.
 ├── cache\
 ├── machines\<name>\
 │   ├── machine.json
-│   ├── disk.img
+│   ├── boot.qcow2 | disk.img
 │   ├── monitor (named pipe handle, no on-disk file)
 │   └── …
 └── …
@@ -1370,7 +1449,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 6 managed keys are all structural preferences, not secrets.
+the 7 managed keys are all structural preferences, not secrets.
 
 ### Environment variables consumed
 
@@ -1387,6 +1466,7 @@ the 6 managed keys are all structural preferences, not secrets.
 | `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_STORAGE_RESERVE` | `settings.ts` — env tier for the `storage-reserve` setting |
 | `QUICKCHR_SHUTDOWN_TIMEOUT` | CLI `shutdown` grace budget in positive integer seconds; default 10, overridden by `--timeout` |
 | `QUICKCHR_TIMEOUT_EXTRA` | `settings.ts` — env tier for the `timeout-extra` setting |
 | `QUICKCHR_SECURE_LOGIN` | `settings.ts` — env tier for the `secure-login` setting |
@@ -1436,6 +1516,29 @@ funnel through the same transport selector.
 > (see [`docs/centrs-interface.md`](./docs/centrs-interface.md)) — it never reads
 > `machine.json`, and neither should you.
 
+### Exit status
+
+`quickchr exec` exits 0 when the command was **delivered**, not when RouterOS
+accepted it. `/rest/execute` returns HTTP 200 with the rejection text in the same
+envelope as a success, so a refused command looks like this:
+
+```console
+$ quickchr exec my-chr "/user/add name=-2 group=read password=x"; echo "rc=$?"
+failure: invalid user name (/user/add; line 1)
+rc=0
+```
+
+The library is the same: `chr.exec()` resolves, and `ExecResult` has no failure
+field. quickchr does not pattern-match RouterOS error text, whose wording changes
+between versions (#142). When a script needs a pass/fail exit code, run the
+command through centrs, which validates it first and exits non-zero on a rejection.
+A write command needs `--yes` outside a TTY; without it centrs refuses with
+`usage/confirmation-required` (also exit 1) and sends nothing:
+
+```bash
+centrs execute --quickchr my-chr --yes "/user/add name=-2 group=read password=x"
+```
+
 ### Transports
 
 | `--via` | Source | Notes |
@@ -1483,12 +1586,16 @@ ceiling.
 
 ### Boot disk
 
-Default format is **raw** (the image MikroTik ships). `--boot-size`
-auto-converts to **qcow2** before the first boot and resizes to the
-requested size. Requires `qemu-img` on the host.
+The CLI and wizard default to **qcow2**, converted from the raw MikroTik
+image before first boot. Creating qcow2 requires `qemu-img` even without resize.
+`--boot-size` resizes qcow2 to the requested size; explicitly selecting raw
+with a boot size is refused. Without `--boot-size`, qcow2 keeps the original
+image size and enables snapshots.
 
-`--boot-disk-format=qcow2` (without `--boot-size`) just keeps the
-default size but enables snapshots.
+Library callers default to **raw** unless `bootSize` implies qcow2. CLI users
+can select raw explicitly with `--boot-disk-format raw`. On x86, this permits
+creation without `qemu-img` when no resize or extra disks are requested. ARM64
+also needs `qemu-img` for its writable UEFI firmware disk.
 
 ### Extra disks
 
@@ -1605,7 +1712,7 @@ present, then exits `1`.
 | `DOWNLOAD_FAILED` | image fetch failed | retry; check connectivity to MikroTik download server |
 | `INVALID_VERSION` / `INVALID_ARCH` / `INVALID_NAME` / `INVALID_DISK_SIZE` | argument parse | fix the value |
 | `MACHINE_EXISTS` | name already in `machines/` | choose another name or `QuickCHR.get(name)` |
-| `MACHINE_NOT_FOUND` | name not in `machines/` | `quickchr list` |
+| `MACHINE_NOT_FOUND` | name not in `machines/`, or a booted machine's disk file is missing | `quickchr list`; for a missing disk, restore it or `quickchr clean <name>` |
 | `MACHINE_RUNNING` / `MACHINE_STOPPED` | wrong lifecycle state | `start` or `stop` first |
 | `MACHINE_LOCKED` | another operation holds the machine (the message names it, its pid and age) | wait for it; a `foreground` holder must be quit from its console |
 | `EXEC_FAILED` | RouterOS rejected the command (auth, syntax) | check creds, command syntax |
@@ -1618,7 +1725,7 @@ present, then exits `1`.
 | `PROVISIONING_VERSION_UNSUPPORTED` | provisioning option on RouterOS < 7.20.8 (including any 6.x) | use `--channel long-term` or pin a `7.20.8+` version |
 | `REST_UNAVAILABLE` | REST operation (`exec`, `get`, `rest()`) on a RouterOS 6 machine | use the native API — `centrs … --via native-api --no-validate` |
 | `INVALID_ARGUMENT` | a flag combination quickchr will not honour — e.g. `--no-wait` with provisioning | drop one of the two |
-| `INSUFFICIENT_DISK_SPACE` | host data dir full | free space or move via `QUICKCHR_DATA_DIR` |
+| `INSUFFICIENT_DISK_SPACE` | data dir's filesystem has less than the operation's estimate plus `storage-reserve`, even after evicting what the cache could spare | free space, remove machines, lower `storage-reserve`, or move via `QUICKCHR_DATA_DIR` |
 | `STATE_ERROR` | snapshot on raw boot disk | recreate with `--boot-disk-format=qcow2` |
 | `INVALID_SIZE_STRING` | invalid cache/settings size string | use size syntax like `512M`, `2G`, or `1.5G` |
 | `INVALID_SETTING_KEY` | `settings get`/`set`/`reset` received an unrecognized key | `quickchr settings print` to see the managed keys |

package/README.md

@@ -1,11 +1,5 @@
 # quickchr
 
-> **Experimental** — quickchr is under active development. Most testing has been on
-> macOS (Apple Silicon + Intel), with CI on Linux (x86_64 + aarch64). Windows support
-> is early-stage: unit tests pass on `windows-latest` CI, and a weekly sweep boots a real
-> CHR on Windows (TCG, anchor smoke subset only). Expect rough edges on Windows — bug
-> reports welcome.
-
 CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.
 
 ## Quick Start
@@ -14,7 +8,7 @@ CLI and library to download, launch, and manage MikroTik CHR virtual machines vi
 
 - [Bun](https://bun.sh) runtime
 - [QEMU](https://www.qemu.org) with `qemu-system-x86_64` and/or `qemu-system-aarch64`
-- `qemu-img` for disk resize and extra-disk features (`--boot-size`, `--add-disk`, `quickchr disk`)
+- `qemu-img` for default qcow2 creation, the setup wizard, disk resize, extra disks, and snapshots
 - UEFI firmware (edk2) for arm64 CHR
 
 Install QEMU:
@@ -57,10 +51,28 @@ Library:
 bun add @tikoci/quickchr
 ```
 
+### Prerelease QA (0.5.1)
+
+0.5.1 is published to npm `next` first; the unqualified install above uses `latest`,
+and 0.5.1 is promoted there once QA passes. Pin this published candidate for
+reproducible CLI or library QA:
+
+```bash
+bun install -g @tikoci/quickchr@0.5.1
+bun add @tikoci/quickchr@0.5.1
+quickchr --version
+```
+
+Use `@next` instead of `@0.5.1` to follow later candidates. See the
+[0.5.1 changelog](./CHANGELOG.md#051--2026-10-22) for the changes since 0.5.0,
+including storage admission, cache accounting, and disk preservation fixes.
+The [0.5.0 notes](./CHANGELOG.md#050--2026-10-22) cover migration from 0.4.x.
+
 ### CLI Usage
 
 The easiest way to start is the interactive wizard — it walks through
-every option and starts the CHR for you:
+every option and starts the CHR for you. It requires `qemu-img` and reports
+a missing tool before prompting or downloading:
 
 ```bash
 quickchr setup
@@ -184,6 +196,7 @@ reports a forced power cut if the guest does not stop within the grace budget.
 | `--install-all-packages` | Install all packages from `all_packages.zip` | |
 | `--add-user <user:pass>` | Create a user after boot | |
 | `--disable-admin` | Disable the default admin account | |
+| `--secure-login` | Create a managed login; use `--disable-admin` to disable admin | |
 | `--no-secure-login` | Keep admin with no password (skip managed account creation) | |
 | `--add-network <spec>` | Add a network NIC (repeatable). Specs: `user`, `shared`, `bridged:<iface>`, `socket::<name>`, `tap:<iface>`. Default: single user NIC. | |
 | `--no-network` | Start with no NICs (headless) | |
@@ -195,6 +208,7 @@ reports a forced power cut if the guest does not stop within the grace budget.
 | `--device-mode <m>` | Configure device-mode: rose\|advanced\|basic\|home\|auto\|skip | |
 | `--device-mode-enable <f>` | Set one or more device-mode flags to yes | |
 | `--device-mode-disable <f>` | Set one or more device-mode flags to no | |
+| `--no-device-mode` | Skip device-mode provisioning entirely | |
 | `--port-base <port>` | Starting port number | Auto (9100+) |
 | `--timeout-extra <s>` | Add extra seconds to the auto-computed boot timeout | |
 | `--dry-run` | Print what would run without executing | |
@@ -238,11 +252,12 @@ In **foreground** mode, your terminal becomes the CHR serial console. Use these
 | `Ctrl-A C` | Toggle QEMU monitor (`quit` to force-stop) |
 | `Ctrl-A H` | List all key shortcuts |
 
-> **Note:** Background QEMU processes are true OS-level orphans — `quickchr` does not use shell job control (`&`). After the command returns you can close the terminal and QEMU keeps running. Use `quickchr stop <name>` to shut it down cleanly.
+> **Note:** Background QEMU processes are true OS-level orphans — `quickchr` does not use shell job control (`&`). After the command returns you can close the terminal and QEMU keeps running. `quickchr stop <name>` ends it with a power cut; `quickchr shutdown <name>` asks the guest to shut down first, and still falls back to a power cut if it does not exit in time.
 
 ### Disk Support
 
-- The CHR boot image starts as raw. Using `--boot-size` converts it to qcow2 and resizes it before first boot.
+- CLI and wizard boot disks default to qcow2, converted from the raw MikroTik image using `qemu-img`. Library callers default to raw unless `bootSize` implies qcow2.
+- `--boot-size` resizes qcow2 before first boot; explicitly combining raw with a boot size is refused.
 - Extra disks from `--add-disk` are always created as blank qcow2 images.
 - `quickchr clean <name>` removes any resized boot disk and extra disks, then recreates them from the saved machine config.
 - `quickchr disk <name>` shows the stored disk layout. If `qemu-img` is installed, it also shows virtual and actual sizes.
@@ -437,7 +452,7 @@ afterAll(async () => {
 |----------|-------------|
 | `MIKROTIK_WEB_ACCOUNT` | MikroTik.com account email (for license renewal) |
 | `MIKROTIK_WEB_PASSWORD` | MikroTik.com password (for license renewal) |
-| `QUICKCHR_DEFAULT_CHANNEL`, `QUICKCHR_DEFAULT_ARCH`, `QUICKCHR_CACHE_MAX_SIZE`, `QUICKCHR_TIMEOUT_EXTRA`, `QUICKCHR_SECURE_LOGIN` | Env-tier overrides for the 5 `quickchr settings` keys — see [MANUAL.md §3 `settings`](./MANUAL.md#3-cli-command-reference) |
+| `QUICKCHR_DEFAULT_CHANNEL`, `QUICKCHR_DEFAULT_ARCH`, `QUICKCHR_ACCEL`, `QUICKCHR_CACHE_MAX_SIZE`, `QUICKCHR_STORAGE_RESERVE`, `QUICKCHR_TIMEOUT_EXTRA`, `QUICKCHR_SECURE_LOGIN` | Env-tier overrides for the 7 `quickchr settings` keys — see [MANUAL.md §3 `settings`](./MANUAL.md#3-cli-command-reference) |
 | `QUICKCHR_INTEGRATION` | Set to `1` to run integration tests |
 | `QUICKCHR_TEST_TARGET` | Integration tests only: RouterOS channel (`stable`/`long-term`/`testing`/`development`) or pinned version (e.g. `7.22.1`) to boot. Empty = `stable`. The Integration workflow resolves each `routeros-target` once, then sets this to that exact pin across platforms |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -15,6 +15,7 @@
     }
   },
   "files": [
+    ".bun-version",
     "src",
     "README.md",
     "DESIGN.md",
@@ -25,7 +26,7 @@
     "lint": "biome check . && tsc --noEmit",
     "lint:biome": "biome check .",
     "lint:typecheck": "tsc --noEmit",
-    "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
+    "lint:markdown": "markdownlint-cli2 '**/*.md'",
     "lint:cspell": "cspell lint . --no-progress",
     "lint:examples": "bun run scripts/validate-examples.ts",
     "lint:specifiers": "bun run scripts/validate-network-specifiers.ts",