[lunks]

Stacked on #1391 (the guard): review only the top commit. Its test is t_res_guard, and it builds on the guard's 100 ms timer.

What and why

Ocarina of Time (Switch 2, 0400486024DEC000) out of focus went from 11 to 20 GB of GPU allocated in 12 s with the residency set flat, and swap grew 6.7 GB in 20 s until the run was killed. Out of focus the game's main thread waits in oe::PopNotificationMessage and submits nothing, while its streaming threads remake a run of about 10 MB of a virtual pool 70 times a second. Each old buffer went to the deferred queue behind a fence no submission would pass, and only a submission's feedback drains that queue: 770 MB a second, 881 buffers at the end of the log. A user's session froze for good at a window switch (frames not back at focus, audio on, no GPU error). That this pile-up is what froze it is inferred, not shown: the old host was not reproduced. What was seen is that a 43 s window switch resumed, with retired buffers flat where they had grown from 11 to 20 GB in 12 s out of focus, so the cause is called likely.

Change: a pool's buffer retired with no submission open waits only for what was committed, as none can reach it once it left the table, and the guard's 100 ms timer drains the queue while no feedback is due (defer_idle, the timer runs with the guard off too). The guard also counts what res_add added since the last commit, as the set's size leaves that out and the device's size could lag it. DM_CTL "focus <n>" sets the focus state, which a windowless boot needs to test this.

Checked

• Tests (Apple M5 Pro, macOS 27, niced): check_t_res_guard 26 checks and the stuck run 2 checks, 0 failed (new: a retired pool buffer goes at the next tick between submissions, and behind the submission when one is open); build/t_hid (host, dm/host/tests) 156 checks, 0 failed; test_docs.py, test_env_switches.py, test_gfx_tests_makefile.py OK; docs_symptoms.py --check current; lint_c.py tidy on nvn_mtl.m, hle_hid.c, t_hid.c, t_res_guard.m: 0 pairs above the baseline.
• Games run: none for this branch. The commit message calls the cause "likely": the measurement is the out-of-focus log above; no run after the fix is recorded in the message. Tested on our stack's version of the change (stack-next, Apple M5 Pro), not on main.
• Not run: the rest of the Metal and host suites, regress.py, any game.
• Overlap: PRAGMATA's opening load fits an 8 GB Mac's GPU working set: large-pool chunks retire, pools from 128 MB are chunked, and DM_NVN_TEX_MIP_SKIP #1319 retires replaced large-pool chunks (big_lookup) and edits mtl_pool_del; this PR changes how a retired pool buffer waits (mtl_pool_del, big_moved). git apply --3way --check of PRAGMATA's opening load fits an 8 GB Mac's GPU working set: large-pool chunks retire, pools from 128 MB are chunked, and DM_NVN_TEX_MIP_SKIP #1319 on this branch conflicts in nvn_mtl.m, docs/env_switches.tsv, docs/reference/memory.md, docs/agents/symptoms.md (the first three through the guard PR).

Docs

• The finding is in docs/reference/memory.md and docs_symptoms.py was run
• No chain tool changed
• No game files, keys or data extracted from a game in the change

[jonpage0]

Bounded M3 Max window-switch check (2026-11-06): a local Ocarina build carrying #1392 together with #1391/#1482 loaded Kokiri Forest, switched to Finder, returned, accepted movement/camera input and exited cleanly. No freeze occurred. I did not establish that this game's submissions stopped for the entire out-of-focus interval, so this is only a window-switch smoke check, not proof of the retired-buffer stall path or a long suspension stress test.

[lunks]

Thank you for the window-switch check with #1391/#1392. Noted that it doesn't show the retired-buffer path itself; we'll keep it described that way.

[seedds]

Thank you for the diagnosis and the measurements. The fix landed in 1d37720, rewritten so it no longer depends on #1391, with you credited as co-author.

What changed from this PR:

• The race when choosing the fence. mtl_pool_del read g_cb before bumping g_pool_gen, and the submit thread finds pool buffers through the lock-free per-thread cache (pc_get). A submission could open in that window and encode the old buffer, and the buffer would then be released behind the previous fence while that submission still used it. Now the generation is bumped first, then an atomic g_sub_on is read (set in mtl_sub_begin before any lookup), with a full fence on both sides.
• No timer. An entry queued with its fence already passed starts one background drain (defer_kick), so nothing depends on the guard's 100 ms timer.
• The residency set's commit. A drain's removals free nothing until the set is committed again, and only the next submission did that. A feedback handler, or a submission closing, that finds no submission open now commits through the same background drain (defer_idle_commit). Without it, t_pool_retire showed a buffer drained but still held.
• Left out: the g_guard_set accounting (it belongs with A GPU memory guard before each residency commit stops the game instead of freezing the Mac #1391), and DM_CTL focus, since DM_OE_SCRIPT="focus=2@60,focus=1@90" already sets the focus state without a window.

On an M6 the pile-up was not reproduced. On the village-deck route Ocarina stopped submitting for 40 s out of focus, but made no pool deletions, both during the load and on the deck, so GPU allocated stayed flat on main too. If you know the scene where the 770 MB a second happened, a route to it would let us confirm the fix in the game. Fire Emblem Engage's attract demo, which deletes pools, behaved the same before and after.