fix(installer): memory truth — machine RAM vs Docker's budget, advice clamped (bash half of #417)

[LukasWodka]

Summary

Bash half of #417 (Windows half: #444) — same three bugs, same design:

1. Flip-flop:_pf_total_mem_kb preferred docker info MemTotal — the code's own test even called it "the Mac trap" — so a Mac reported 16 GB (host) cold and 6 GB (Docker VM) warm.
2. Unachievable advice: remediation used the raw PF_REC_MEM_GB=16 regardless of the machine.
3. Diverging copy: the preflight warning and the post-Docker _pf_recheck_runtime_mem warning disagreed, and both could fire in one run.

Change

• _pf_memory gates on the machine (native Linux: daemon sees all host RAM → hard-fail gate unchanged; the 64 MiB grace and the Linux MemAvailable check are preserved) and prints Memory: N GB (machine); a second Docker's memory budget: N GB line appears only when a runtime is up with a meaningfully smaller budget (the VM case) — never as a duplicate on native Linux.
• _pf_mem_targets clamps budget advice to host − 2 GB (floor 4); macOS hint covers both Docker Desktop and colima. Hardware statements stay unclamped.
• _pf_runtime_mem_status is the single shared copy (preflight + recheck) with a PF_RUNTIME_MEM_WARNED latch.
• _pf_hw_summary_line now reports host RAM (it had the same flip-flop in miniature).
• The _pf_total_mem_kb selector and its trap-codifying tests are deleted; 6 new tests cover the clamp matrix, the two-line output, the Linux no-duplicate case, the latch, and the summary line.
• manifest.sha256 regenerated.

Labels, clamp math, and latch semantics mirror #444 exactly — a ready-made row for the #435 facts spec.

Stacked on #441 (both touch preflight.sh); merge #441 first. Same local-macOS test-flake note as #442 applies (3 pre-existing, ubuntu CI is the arbiter).

Type

Bug fix

Test plan

preflight.bats fully green including 6 new tests; full bats suite green except the 3 documented pre-existing local-macOS failures; bash -n + shellcheck --severity=error clean; copy catalog unchanged; gen-manifest.sh --check clean.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes installer preflight gating and user-facing failure/warning text across OS paths; behavior is heavily tested but affects install abort decisions when Docker VM memory is sub-floor.

Overview
Bash preflight no longer conflates host RAM with Docker’s memory budget, fixing cold/warm flip-flop, contradictory grades, and duplicate warnings.

The _pf_total_mem_kb runtime-preferring selector is removed. _pf_memory gates on _pf_host_mem_kb as Memory: N GB (machine) and adds a separate Docker's memory budget line only when a VM budget is meaningfully smaller than the host (not duplicated on native Linux). _pf_display_gb_from_mib, _pf_host_too_small_for_floor, and _pf_runtime_mem_status centralize grace-aware GB display, floor+reserve “too small” logic, clamped resize hints (Desktop/colima vs Linux cgroup), and a PF_RUNTIME_MEM_WARNED latch so preflight and _pf_recheck_runtime_mem share one copy and threshold set. The hardware summary uses host RAM and the same converter. manifest.sha256 is updated; preflight.bats switches stubs to _pf_host_mem_kb and adds extensive regression tests.

^{Reviewed by Cursor Bugbot for commit d5b4172. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

Converted to draft to disable the merge button while the base is a feature branch (the #438-#440 mis-merge trap). Plan: once #441 merges to develop, rebase this onto develop, retarget, regen manifest.sha256, re-run bats, flip ready.

[LukasWodka]

Rebased onto develop as a single clean commit (#441's content is already in via its squash). Manifest regenerated; preflight+common bats green locally (modulo the known macOS-only flake). bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 581f804. Configure here.}

[aptracebloc]

Approving — the memory-truth redesign is sound (host RAM vs Docker's VM budget separated; one shared budget-status copy for preflight + recheck). All five Bugbot findings across r1/r2 are addressed in the current code (MiB+grace, Linux non-Desktop hint, recheck routed through the one copy, host-too-small branch) and Bugbot passes on head. CI fully green.

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

All three valid, all fixed in 718af66 — and worth naming that all three were the same shape as the bug this PR exists to remove: two copies of one judgement disagreeing, surviving on paths the first pass didn't reach.

1. Sub-floor remedy contradicted the hard-fail

You pinpointed it exactly: the latch suppresses a duplicate warning and deliberately never the hard-fail, so on a warm sub-floor run both printed — Give Docker <rec> then raise to <warn>. One condition, two sizes.

The remedy now quotes the size the failure quotes. The between-floor-and-warn branch, where no hard-fail follows, still aims at the train figure — that divergence is intentional and harmless.

sub-floor (3000 MiB), 32 GB host:
WARN: budget: 3 GB — below the 5 GB the client needs
HINT: Give Docker 6 GB … --memory 6 <- was 8, now matches the hard-fail

2. Budget GB omitted the VM grace

Now (mib + grace) / 1024, matching the PowerShell peer:

VM configured at the 5 GB floor (guest 4900 MiB):
before: "budget: 4 GB" <- looked sub-floor while grading correctly as fine
after: "budget: 5 GB"

3. "Enough to run" contradicted "use a larger machine"

The sharpest of the three, because it crossed function boundaries. _pf_memory compared host RAM straight against the Docker floor with no OS reserve, so a 5–6 GB Mac was graded enough to run while the budget line two lines later correctly said use a larger machine.

Fixed with one predicate — _pf_host_too_small_for_floor — read by both sites, so they cannot reach different verdicts again. It fails safe on unknown/junk input (never claims too-small from an unreadable host), and native Linux keeps its original wording since the daemon sees host RAM directly and the reserve arithmetic doesn't apply there.

Verification

696 bats pass, zero failing. Four new tests, because an unpinned fix is a future regression:

• sub-floor remedy must quote the hard-fail's size (and must not quote the recommendation)
• a floor-sized VM must not display as sub-floor
• a 6 GB host must never print "enough to run", and must print "larger machine"
• the predicate itself, including "", "unknown" and 0 failing safe

shellcheck --shell=bash clean; scripts/manifest.sha256 regenerated for the R8 gate.

Three rounds on this PR now, and each round found a genuine survivor of the same class — which is a fair signal that "two copies of one number" was the right thing to go after here.

bugbot run

[LukasWodka]

Pushed c0d7b8b on top of your 718af66 (fast-forward, nothing overwritten). I'd independently fixed the same three findings and dropped that commit — the shared _pf_host_too_small_for_floor predicate is the better shape and is kept as-is. Two gaps remained:

1. The display became grace-aware but the WARN threshold didn't. Only the floor threshold carried the grace, so the same self-contradiction reopened one boundary up. Measured on 718af66, 32 GB host (warn_eff 8):

rt_mib	output
7680	⚠ budget: 8 GB — recommended ≥ 8 GB
8000	⚠ budget: 8 GB — recommended ≥ 8 GB
8191	⚠ budget: 8 GB — recommended ≥ 8 GB
8192	✔ budget: 8 GB

A ~512 MiB band telling the operator to raise a budget to the size it already reports — and Docker Desktop's defaults land in it. The warn threshold now carries the same grace, so shown == target implies the ✔ branch at both boundaries.

2. The four r3 tests were only partially enforcing. Under Bats 1.13 a failing bare [[ ]] that isn't the last command in a test body does not fail the test. So budget: 5 GB, != enough to run, Give Docker ${warn_eff} and every line but the last of the predicate test were advisory — they'd have passed against broken code. All 16 assertions in those tests now carry || return 1.

Verified by mutation rather than inspection:

• reverting the warn-threshold grace — i.e. this branch's state before c0d7b8b — fails the new boundary test, so the gap was real, not hypothetical
• reverting the display grace fails 2 tests
• neutering _pf_host_too_small_for_floor fails 3, including the r3 predicate test that only became capable of failing once hardened

Baseline and restored clean in every case.

Scope note: only the r3 tests are hardened here. 170 of ~698 tests in this suite share the un-hardened pattern — that needs its own PR, because hardening will surface previously-vacuous failures that each need triage (real installer bug vs stale assertion), and burying that here would hide it. Tracked separately.

Gates: bats scripts/tests/*.bats → plan 697, ok 697, not ok 0 (complete TAP run, plan line checked); shellcheck --severity=error over the CI file set → rc=0; check-style clean; check-drift no drift; gen-manifest.sh --check current.

[LukasWodka]

bugbot run

[LukasWodka]

Both r4 findings fixed in 0d98736 — and both were caused by my own r3 changes, which is worth stating plainly.

VM size misread as host RAM — correct. _pf_memory falls back to the VM budget when host RAM is unreadable (label="Docker VM"), and I passed that $gb straight into _pf_host_too_small_for_floor. So a large machine with a small VM could be declared too small and lose its resize remedy — worse than the inconsistency I was fixing. The branch now requires label == "machine", so only real host RAM is ever graded as host RAM.

Hard-fail omits display grace — also correct, and it's the same half-applied-fix shape: r3 made the status line grace-adjusted but left the recheck's hard-fail printing raw floored GB, so one budget could still surface as two numbers across the two messages. Both now print the same figure.

One thing the merge settled rather than me: develop had already made the warn band grace-aware (- PF_VM_MEM_GRACE_MIB), so after merging, grading and display are already equivalent — rt_mib < warn*1024 - grace is exactly rt_mib + grace < warn*1024. I verified that behaviourally instead of assuming it:

VM configured at exactly the warn target (8 GB, guest 7900 MiB):
before: "budget: 8 GB — recommended ≥ 8 GB" <- self-contradicting
after: "OK: Docker's memory budget: 8 GB"

Merge: the only conflict was scripts/manifest.sha256, a generated file — resolved by regenerating it over the merged sources rather than picking a side.

Verification:711 bats pass, zero failing. Two new pins (the unreadable-host fallback, and the at-warn-target display), on top of r3's four. shellcheck --shell=bash clean; manifest regenerated for the R8 gate.

Four rounds, nine findings, and every round has surfaced a genuine survivor of the same class — two copies of one number disagreeing. Three of the last four were regressions I introduced while fixing the previous round, which is a fair argument that this file wanted the shared-predicate treatment rather than another round of local patches.

bugbot run

[LukasWodka]

Valid, and High is the right severity — on Linux this path hard-fails. Fixed in 8886f8c.

One correction to my own assumption: I initially doubted this, because I didn't add grace to _pf_memory's display. Checking the file, it's there — it came in from develop via the merge, not from my r4 edit. Either way the two halves disagreed, and the finding stands:

5 GB VM reporting ~4900 MiB MemTotal:
display: (4900 + 512) / 1024 = 5 GB
gate: 4900 < 5*1024 - 64 = 5056 = sub-floor
result: "Memory: 5 GB — below the 5 GB the client needs" (and a hard-fail on Linux)

Fixes:

1. floor_mib and warn_mib now use PF_VM_MEM_GRACE_MIB — the same tolerance the display uses, and the same one _pf_runtime_mem_status already used for its own floor and warn tests. All three now agree on where the boundaries are.
2. _pf_host_too_small_for_floor is fed $(_pf_host_mem_gb) instead of $gb. This was the sharper half of your finding: a shared predicate only prevents divergence if both call sites pass it the same input, and _pf_memory was passing a grace-adjusted VM-or-host figure while the status path passed raw host GB. The predicate was shared; the inputs weren't.

Verified on the exact case:

before: "Memory: 5 GB (machine) — below the 5 GB the client needs; it will OOM."
after: "Memory: 5 GB (machine) — enough to run, but training (≈8 GB/job) may OOM…"

One thing deliberately left raw:MemAvailable. It's a live measurement, not a configured size, so grace-adjusting it would mask a genuine shortage rather than recover a configured figure.

713 bats pass, zero failing. Two new pins — the floor-sized-VM message, and a source-level guard that both call sites feed the predicate the same figure, so this specific divergence can't return. shellcheck clean; manifest regenerated.

Five rounds, ten findings, every round a real one. The recurring lesson is narrower than "copies drift": I twice fixed a display without the matching threshold, and once shared a predicate without sharing its inputs. Both are the same mistake — changing one side of a comparison.

bugbot run

[LukasWodka]

Fixed in 1d43a50 — and this round turned up an error of mine that I need to correct on the record.

The r6 finding: valid, a FOURTH render site

_pf_hw_summary_line computed its own memory GB, so the collapsed summary could print a different size from the memory line in the same preflight, breaking its "never disagree" invariant.

The correction: my r4 fix landed in the wrong function, and I mis-attributed it

Investigating r6 turned up why r5 happened at all. My r4 fix for _pf_recheck_runtime_mem anchored on this two-line pattern:

gb=0
mib=0

That pattern also existed in _pf_memory, and my replace took the first match. So the fix landed in _pf_memory and the recheck never received it. The grace on _pf_memory's display — which I told you on this PR came from develop via the merge — was actually my own misapplied edit. That claim was wrong, and the r5 High finding ("grace inflates host floor display") was a direct consequence of it. Apologies for the misdiagnosis; the r5 fix itself was still correct, it just wasn't cleaning up develop's work, it was cleaning up mine.

Structural fix, not a fifth patch

_pf_display_gb_from_mib is now the single definition, used by all four sites. rt_gb goes through it too — it feeds the "is the VM meaningfully smaller than the machine" comparison, and grading one grace-adjusted side against a raw other side is exactly the mistake these six rounds keep rediscovering.

Deliberately still raw, each for a reason: MemAvailable (a live measurement — inflating it would hide a genuine shortage), disk, and _pf_host_mem_gb (physical RAM needs no compensation, and it is the input _pf_host_too_small_for_floor grades).

Process change: every replacement in this commit asserted its anchor matched exactly once and refused otherwise. That guard fired twice while writing this fix — on _pf_runtime_mem_status, where it revealed my r4 edit had never landed either — and it is precisely what would have caught r4's error.

Verification

715 bats pass, zero failing. Two new tests, both structural rather than symptomatic: a source-level invariant that no site renders its own memory GB, and summary-line-vs-memory-line agreement on a just-under-a-round-GB host. shellcheck clean; manifest regenerated.

Six rounds, eleven findings. The through-line is one mistake in three costumes: changing one side of a comparison — a display without its threshold, a predicate without its inputs, a converter without its callers. The fix now makes that structurally hard rather than relying on me noticing.

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1d43a50. Configure here.}

[LukasWodka]

Valid, High deserved — fixed in d5b4172. Two divergences in one branch:

1. The reserve arithmetic was inlined ($(( phys_gb - PF_OS_RESERVE_GB )) -lt PF_MIN_MEM_GB) instead of calling _pf_host_too_small_for_floor — so the predicate I introduced in r3 to stop exactly this had a fourth call site that wasn't using it.
2. That branch was gated OS != Linux while _pf_runtime_mem_status applies the predicate on every OS.

Consequence on a warm Linux install with a sub-floor cgroup/VM budget, which is the common shape on a shared box:

preflight: "This machine has 6 GB … Free up memory or use a larger machine."
hard-fail: "Free memory (or raise the VM) to >= 6 GB" <- impossible on that machine

Now the shared predicate runs on every OS, with an OS-appropriate noun so the Mac wording survives. Verified on the cited case (6 GB Linux host, 3 GB budget) — both messages now say use a larger machine, and the impossible-raise remedy is gone.

This is the same class as r1–r6 on a new axis. Not two values disagreeing, but two OS gates disagreeing about when one judgement applies. Worth naming because my earlier framing — "changing one side of a comparison" — wouldn't have caught it; the values agreed here, the conditions didn't.

717 bats pass. Two new tests, one behavioural (the Linux path) and one structural: an invariant that the reserve arithmetic exists in exactly one place, so a fifth inlined copy fails CI rather than waiting for a review round. shellcheck clean; manifest regenerated.

bugbot run

[LukasWodka]

/fr-pass