@tikoci/quickchr 0.5.0 → 0.5.1

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
@@ -229,9 +278,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

@@ -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
@@ -150,6 +159,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 +178,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 +408,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>`
 
@@ -567,6 +582,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 one object per entry, 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 +656,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 +675,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,7 +683,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 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
@@ -824,14 +898,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 +919,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` |
@@ -1195,8 +1269,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
@@ -1224,7 +1298,7 @@ var list.
 ├── cache\
 ├── machines\<name>\
 │   ├── machine.json
-│   ├── disk.img
+│   ├── boot.qcow2 | disk.img
 │   ├── monitor (named pipe handle, no on-disk file)
 │   └── …
 └── …
@@ -1370,7 +1444,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 +1461,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 +1511,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 |
@@ -1605,7 +1703,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 +1716,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

@@ -57,6 +57,23 @@ 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. After 0.5.1 is published, pin it 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
@@ -195,6 +212,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,7 +256,7 @@ 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
 
@@ -437,7 +455,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.1",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -25,7 +25,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",

package/src/cli/flags.ts

@@ -25,7 +25,7 @@ const CREATE_FLAGS = [
 /** `start` also boots, so it owns the run-time flags on top of the create set. */
 const START_ONLY_FLAGS = [
 	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
-	"install-deps", "timeout-extra",
+	"timeout-extra",
 	"license-level", "license-account", "license-password",
 ] as const;
 
@@ -96,10 +96,15 @@ export const VALUE_FLAGS: ReadonlySet<string> = new Set([
  *  that `--add-network` already expresses in general (#164). Removing them silently would
  *  repeat the defect they were removed for: a flag that is accepted and does nothing. A
  *  removed name stays known for as long as anyone might still type it, and says what
- *  replaced it. */
+ *  replaced it.
+ *
+ *  `--install-deps` is the same defect from the other side: `start` accepted it from
+ *  the beginning and nothing ever read it (#193). It never installed anything, so the
+ *  replacement is the command that names what to install. */
 export const REMOVED_FLAGS: ReadonlyMap<string, string> = new Map([
 	["vmnet-shared", "--add-network shared"],
 	["vmnet-bridge", "--add-network bridged:<iface>"],
+	["install-deps", "quickchr doctor (it never installed anything; doctor lists missing host dependencies and how to install them)"],
 ]);
 
 /** Value-taking flags with a documented `--no-` spelling, where `false` is a real