feat: a memory guard for the local model

[lucazagaia]

Why

A colleague's laptop nearly ran out of memory while running the demo. Measured with 0.1.1 from PyPI, replaying the 8 demo recordings on an 18 GB Mac:

• No leak. Skill++'s own process stays at 20–34 MB, and model memory is flat from one round to the next.
• The cost is the model, not the session. A one-word question locks as much memory as the whole demo (+10.1 GB against +10.4 GB). Every prompt uses a 4,096-token context.
• With other apps open, a fold ran at 92 % used, macOS pressure at warning, with 4.7 GB swapped out in 100 s. Loading the two models took 12.8 GB of free memory.
• Ollama keeps the model 5 minutes after the last call, so the memory stays taken after the fold.

What it does

• Check before loading. The models load only when what they take still leaves 2 GB free. What they take is measured on each computer: estimated from their size on disk at first, then the largest drop a fold has seen there.
• Watchdog. While a fold runs, free memory is read twice a second. Below 2 GB, or at critical macOS pressure, no further model call starts, and the models Skill++ loaded are unloaded at once, including one still loading when it tripped. A half-judged session drops its verdicts; one stopped between episodes resumes after the banked ones (folded).
• Release right away. The models are unloaded when the fold ends, not 5 minutes later. keep_alive: 60s covers a fold that dies first.
• Only its own models, and one Skill++ process holds them at a time (models.lock).
• Folding later. A held session is folded when the computer is idle (macOS HIDIdleTime, Linux loginctl or xprintidle) and the models fit; at the next session start, at most every 10 minutes; or with Fold now on the review page's banner, or fold-pending --now.
• Telling people. A desktop notification (osascript or notify-send) when a fold waits (at most hourly) or is stopped. doctor and stats show the figures.
• Settings: SKILL_PLUS_PLUS_MEMORY_GUARD, SKILL_PLUS_PLUS_MEMORY_RESERVE_GB, SKILL_PLUS_PLUS_IDLE_MINUTES, SKILL_PLUS_PLUS_NOTIFY.

Measured on the same Mac, with this branch

Run	Result
Guard on, 2 GB reserve, 13.5 GB free	All 8 sessions held before loading. Model memory stayed at 0.0 GB, free memory never below 74 %, one notification.
Guard on with room (0.25 GB reserve)	7 folded, 1 rightly held (12.4 GB free against 12.5 needed), then folded with fold-pending --now: 5 entries, as in 0.1.1. The models were gone 0.0–0.5 s after every fold, and the need measured here was 12.2 GiB.
Forced stop (planted need too low, 5 GB reserve)	Tripped 7.9 s in at 14 % free, during the load. gemma4 was gone 2 s later, and free memory back to 72 %. Notice: "stopped and freed 9.5 GB". Sessions 2–8 held without reloading. Resumed later: the same ledger as the uninterrupted run, occurrences [7, 2, 1, 1, 1].

Measuring found three things the unit tests could not:

• Ollama lists a model for a moment after unloading it, so a fold starting then counted gemma4 as someone else's and left it loaded. unload now waits until /api/ps stops listing it, and one process holds the models at a time.
• A trip during a load found nothing listed to unload, and the load finished anyway. The unload now lingers 20 s and unloads what lands.
• The first estimate mixed decimal and binary gigabytes. The factor is 1.39 in bytes.

With gemma4:e4b-it-qat

The QAT default comes from #26: with one line added to the judge's question, gemma4:e4b-it-qat gives the same verdict as gemma4:e4b at all 158 recorded gaps. The docs in this PR state its figures, so merge #26 first. Both branches reword the README's install note; the one merged second keeps this PR's wording.

Local model	A fold needs	A fold starts at
gemma4:e4b	12.2 GiB	14.2 GiB free
gemma4:e4b-it-qat	7.0 GiB	9.0 GiB free, 10.3 GiB before a computer's first fold (estimated from size on disk until measured)

Folding the 8 demo recordings with gemma4:e4b-it-qat under the guard: lowest free memory 7.2 GiB, pressure normal throughout.

Tests

• 569 tests pass: 28 new, 541 unchanged. The existing suite runs with the guard off, set in setUpModule like the other model stubs, and the new tests script the memory readings.
• scripts/leak_guard.py: 0 hits.

Not verified here

• Linux: the readers and notify-send are tested with recorded output only, not on a Linux machine.
• The notification banners: whether they appear on screen needs a person to look.