#1896 resident RAM mode: a budget keeps the prompt path's lend region when it has room (#1683)

Descripción

## Title
Issue: Resolves #1683

## Summary
With `--resident-budget-gib`, the RAM copy kept no lend region: `pin_cache_complement` set `lend_from_slot = -1` in its budget branch, so the experts of the cache slots the prompt path borrows were in neither VRAM nor RAM during a prompt and were read from the model files on every chunk (and again when the slots were refilled), even when the budget had room for them. This is the first of the two options in #1683, the one the maintainer reply preferred: the budget branch now appends the lend region after the ranked experts, from the last slot down (the order the borrowing takes them), as far as the budget reaches. The budget stays a hard cap; experts past it keep the file fallback and the warning says so.

Only where experts are placed changes, not the maths: the lent experts are copied from RAM instead of the files.

## What changed
- `src/core/expert_source.cpp`: in the budget branch of `pin_cache_complement`, the lend region's pairs (slot >= `lend_from_slot`, highest slot first) are added to the ranked plan while they fit in `budget_bytes`; a new start-up line reports `the prompt path's lend region: N of its M slots keep their experts in RAM too (X GiB of the budget's remaining Y GiB)`. `complement_lent_slots_` and the existing `N of the prompt path's M lendable slots` line and #1389 warning cover the budget case too; the warning's advice names the budget when one is set.
- `src/program/generate.cpp`: the #669 start warning (lent slots without a RAM copy) also fires with a budget and then says a larger `--resident-budget-gib` is the remedy, not a smaller chunk (with a budget the count used to be 0 whatever the chunk, as #1683 notes).
- `docs/DETAILS.md`: the RAM budget paragraph says the lend region is kept when the budget has room, with the measurement below.

What it leaves alone: `--resident-experts` (the unbudgeted path and `choose_resident_keep_from`), the layer split's stage lend regions, the soft what-fits mode's ranking (the lend region comes after the ranked experts there as well), every expert tier's behaviour once the copy is built.

## Measured
RX 6900 XT 16 GB (HIP, gfx1030), Ryzen 9 5950X, 125 GB RAM, Arch Linux, ROCm 7.2.4, engine 0.1.42, Unsloth UD-Q4_K_XL, `--resident-budget-gib 71 --prefill auto --kv int8 --kv-resident 32768 --max-context 131072`. The copy held all 63.47 GiB of experts outside the GPU cache and 7.5 GiB of the budget stayed unused; the prompt path borrows 1,231 slots (3.60 GiB). Before the change the start log had no lendable-slots line at all; after it: `1231 of its 1231 slots keep their experts in RAM too (3.60 GiB of the budget's remaining 7.53 GiB)`. One run per case, greedy, the same prompts, the server's own log lines:

| request | before: expert reads from the files / SSD reads / host staging | after |
|---|---|---|
| 256-token follow-up on a 1K chat | 680 MB / 203 MB (684 major faults) / 1.0 s | 0 / 15 MB (3) / 0.13 s |
| fresh 7.8K prompt | 7.5 GB / 2.8 GB (10,735) / 1.27 s | 0 / 0.3 GB (0) / 0.23 s |
| 561-token follow-up on an 8K chat | 1.2 GB / 244 MB (925) / 1.5 s | 0 / 10 MB (0) / 0.30 s |
| fresh 15.8K prompt | 11.6 GB / 1.9 GB (6,219) / 1.85 s | 0 / 0.3 GB (0) / 0.50 s |

Prompt speed on those fresh prompts: 887 tokens 180 -> 194 tok/s, 7.8K 633 -> 676, 15.8K 677 -> 698 (the staging mostly overlapped the GPU here; the gain is in the SSD traffic and on machines where it does not). Decode unchanged (58-68 ms per verify window in both runs). The 0.1.42 production log of the same machine showed 0.5-2.6 GB of file reads per agent turn and 24 GB for one fresh 17K prompt, all gone after this.

Not tested: a layer split, a helper GPU, Windows, a budget too small for the whole lend region (the code path takes the contiguous tail that fits and warns), CUDA (host code only, no backend-specific lines).

Measured and written with Claude Code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HfV9GaWcc3RmPgCvhX2eUf