`ensure_reserve` was unconditional: every RuntimeImpl construction
re-acquired the 64 MiB reserve via fallocate. That breaks the
documented recovery flow:

  host: 0 free, .reserve = 64 MiB
  $ boxlite reserve-release   → host: 64 MiB free, reserve gone
  $ boxlite rm -f bigbox
      RuntimeImpl::new
        ensure_reserve         → fallocate 64 MiB succeeds
                                 host: 0 free again, reserve back
        SQLite WAL grow        → ENOSPC

The operator's 64 MiB lifeboat is consumed by the reserve top-up
before the recovery command can spend a byte of it.

Fix: hysteretic top-up. If the reserve is missing AND host_free is
below `2 × RESERVE_BYTES` (128 MiB), log a warn and defer. The
recovery now has a full reserve's worth of headroom; the reserve
self-heals on a later runtime construction after free recovers.

Implementation: extract `ensure_reserve_with_free(home, free)` so
the deferral rule can be exercised against hand-crafted free-byte
counts without filling a real filesystem. Promote the test-only
`statvfs_bavail_bytes` to module-scope `host_free_bytes` so we
don't duplicate the libc dance.

Also drop `boxlite gc` from the ENOSPC hint in main.rs — that
command isn't in this PR's scope (deferred to boxlite-ai#639). Sending the
operator to a non-existent command at the worst possible moment
is worse than no hint.

Two-side verified: with the deferral check reverted, the new
`defers_topup_when_host_free_below_threshold` test fails on its
"reserve file must not exist" assertion — proving the test
exercises the new branch and that without hysteresis the race
is silent (no error, just wrong outcome).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…anism

The four existing reserve tests pinned the mechanism (file created /
removed / recreated / idempotent). They didn't verify the
user-visible outcome the reserve exists for: "after I run
reserve-release on a full host, can I actually write again?" Add two
tests covering that gap.

  - release_returns_bytes_to_host_available (lib unit) — pins that
    statvfs.f_bavail really climbs by ~RESERVE_BYTES after release,
    not just that the file disappears.

  - release_unblocks_writes_on_a_full_host (CLI integration, gated)
    — drives the whole story end-to-end on a real bounded fs:
    bootstrap reserve, fill the host with garbage until every chunk
    size from 4 MiB down to 1 byte returns ENOSPC, verify a small
    probe write fails with ENOSPC, run `boxlite reserve-release`,
    verify the *same* probe write now succeeds. Gated on
    BOXLITE_RESERVE_TEST_HOME pointing at a dedicated small mount.

The progressive-chunk fill (4 MiB → 64 KiB → 4 KiB → 1 byte) is
deliberate — without the small-chunk passes, the 4 MiB write returns
ENOSPC while there are still 3.99 MiB free, and the 1-byte probe
slips through and falsifies step 3. Pre-fix verified on a 256 MiB
loop ext4: the single-pass version of this test mistakenly passed
because the probe found 1 byte to land in; the multi-pass version
now stably reproduces the "every write ENOSPCs" precondition.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CI's macOS clippy job failed on src/boxlite/src/util/reserve.rs:135 —
`libc::fallocate` is Linux-only, doesn't exist on macOS / *BSD. Wrap the
fast-path fallocate call in `#[cfg(target_os = "linux")]` so non-Linux
builds skip straight to the zero-write fallback, which works
cross-platform. Semantics are identical (the reserve still consumes
64 MiB of real disk); only the cost shifts from one syscall to ~16
4-MiB sequential writes. boxlite's runtime is Linux-only anyway —
the macOS build target exists only for CLI / SDK build-validation.

Also gates the now-Linux-only `AsRawFd` import to keep the unused-
import warning quiet on macOS clippy.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Empirical finding from manual host-fill testing (2026-06-01): the
`ensure_reserve` / `release_reserve` lifecycle touches only the
`.reserve` inode under `$BOXLITE_HOME` and never any `boxes/<id>/`
content, so running boxes are unaffected by recovery operations. That
property is critical for the documented recovery flow — without it,
operators hitting ENOSPC would have to choose between recovering disk
and losing their boxes.

Add two integration tests that pin this invariant without needing
sudo or actual host-fs filling:

  - `reserve_release_does_not_disturb_running_box`: start an idle
    `sleep 3600` box, run `reserve-release`, assert the box is still
    `Running` and the next runtime construction auto-restores the
    reserve without disturbing the box again.

  - `box_survives_multiple_reserve_cycles`: stress the lifecycle with
    five release/restore cycles to catch stateful regressions that
    might not surface on the first iteration.

What this does NOT verify (documented in module header): the
`f_bavail=0` scenarios that need a privileged tmpfs mount —
shim-process survival, CLI ENOSPC handling, metadata-only unlink at
zero free. Those were empirically confirmed in manual testing and the
runbook for re-running them is to be added separately.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds three reserve unit tests that close gaps in the existing matrix:

  - `zero_write_to_produces_exact_size_filled_with_zeros`: the
    fallocate-fallback path (used on tmpfs / NFSv3 / some FUSE where
    `fallocate(mode=0)` returns EOPNOTSUPP) was previously untested
    because we can't easily get a tempdir to return EOPNOTSUPP.
    Factor the zero-write loop out into a `zero_write_to(file, total)`
    helper and drive it directly with a fresh file. The helper is
    size-agnostic so 4 MiB + 7 bytes exercises the same full-buffer +
    tail-partial logic as 64 MiB.

  - `ensure_reserve_self_heals_partial_reserve_file`: pin the
    `meta.len() >= RESERVE_BYTES` self-heal branch. Pre-create the
    reserve at RESERVE_BYTES / 2 (simulating a crash mid-fallocate or
    an external truncate), call `ensure_reserve`, assert the file is
    topped up to the full RESERVE_BYTES. Without this, a loosened
    check (e.g. `> 0` instead of `>= RESERVE_BYTES`) would silently
    let undersized reserves stand.

  - `concurrent_ensure_reserve_is_safe`: spawn 4 threads all calling
    `ensure_reserve` on the same home dir, assert no thread errors
    and the final file is exactly RESERVE_BYTES (not torn, not
    doubled). Pins the architectural race-safety expectation against
    a future refactor that might introduce non-atomic operations
    (e.g. switching `truncate(false)` to `truncate(true)`).

Two-side verified manually (logged here since the corresponding
production change is only the small zero_write_to extraction, not
a fix):

  - zero_write_to: replaced `remaining = total_bytes` with
    `remaining = total_bytes / 2`. Test failed:
    "zero_write_to must produce a file of exactly `total_bytes` long
     left: 2097155, right: 4194311" — proves the size assertion is
    real, not tautological.

  - self_heals_partial: replaced
    `meta.len() >= RESERVE_BYTES` with just `if meta exists` (no size
    check). Test failed:
    "ensure_reserve must top up a partial reserve to RESERVE_BYTES;
     saw 33554432, left: 33554432, right: 67108864" — proves the
    test exercises the self-heal branch.

  - concurrent: replaced `RESERVE_BYTES` in the fallocate call with
    `RESERVE_BYTES / 2`. Test failed:
    "after concurrent ensure_reserve, file must be exactly
     RESERVE_BYTES; got 33554432, left: 33554432, right: 67108864" —
    confirms the test catches at least the size-based regression
    class.  The truncate(false) → truncate(true) race regression
    did *not* trip the test (fallocate-of-equal-size is essentially
    atomic on Linux), which is honest evidence that the test mostly
    pins regression against size mistakes, not race mistakes per se.

Module-scope `host_free_bytes` is unchanged; gamnaansong's existing
4 tests for `looks_like_host_enospc` in main.rs already cover the
ENOSPC hint plumbing — no gap there.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…eserve

boxlite-ai#618's structural fallocate reserve (`~/.boxlite/.reserve`, 64 MiB) replaced
the old per-write admission walls + `boxlite gc`, but left two gaps that
made the reserve a recovery-only mechanism: no proactive cache reclaim,
no operator visibility into where the home dir's space went.

Adds two layers on top of boxlite-ai#618 without resurrecting the policy walls
the redesign deleted:

  * `boxlite gc` — three-pass sweep of orphan `boxes/<id>/`, orphan
    `bases/*.qcow2`, and orphan `images/disk-images/*.ext4`. Sweep order
    is load-bearing: orphan box dirs must drop first so their stale
    qcow2 chains don't pin image disk-images in the third pass. Salvaged
    verbatim from boxlite-ai#639 — gc.rs only touches `BoxManager` / `BaseDiskManager`
    / `Layout` / backing-chain reader, so it doesn't reach into the
    `enforce_recovery_budget` API that boxlite-ai#618 deleted.

  * `boxlite df` — three-block operator view: host headroom + reserve
    health, `~/.boxlite/` footprint by category, dry-run GC reclaim
    preview. Replaces boxlite-ai#640's `DiskSpaceVerdict` admission-tied output
    with a `ReserveStatus::{Healthy, Partial, Absent}` enum that
    reflects the actual `.reserve` file state — `Healthy` when the
    fallocate floor is in place, `Absent` after `boxlite reserve-release`
    consumed it. Reclaimable count is sourced from `gc(dry_run=true)`
    so `df` and `gc` can't drift.

Out of scope (deliberately): the `enforce_recovery_budget` admission
sink (boxlite-ai#640's RuntimeBackend extension) — that API was removed by the
boxlite-ai#618 redesign in favor of the structural floor; reinstating it would
revert the redesign.

Tests: 3 new for df (fresh-runtime healthy, released → Absent, footprint
sum), 7 inherited gc tests cover orphan box-dir / bases / disk-image
sweeps + grace window + foreign-file safety + concurrent-start race.
gc_cli.rs covers the CLI plumb-through end-to-end.

Two-side verified: `sweep_orphan_box_dirs` no-op → `sweeps_orphan_box_dirs_only`
fails `0 vs 1`; `sweep_orphan_bases` no-op → `sweeps_orphan_bases_only`
fails `0 vs 1`; `reserve_status` always-Healthy → `released_reserve_shows_absent`
fails `Healthy{64MiB} vs Absent`. Restore → all pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>