feat(matchmaking): queue guard for run start + reusable guard_queued helper

[ChronoFinale]

A queued player could still click Play → New Run (also Continue, Challenges, and the in-run restart). The run tore down the main menu while the search stayed active server-side, with no feedback. This PR ships two things: a run-start gate applied here, and the reusable MPAPI.matchmaking.guard_queued(replay) helper the consumer-mod PRs build on to guard lobby create/join.

The bug

Nothing on the run-start path checked matchmaking state; G.FUNCS.start_run tears down the menu (clear_queue, Game:start_run) regardless.

The fix

G.FUNCS.start_run is the single vanilla funnel for New Run, Continue, Challenges, and the in-run restart. Gating there runs before menu teardown: one wrap covers every entry point, and the menu stays untouched when blocked.

function MPAPI.matchmaking.guard_queued(replay)
	if not MPAPI.matchmaking.is_queued() then
		return false
	end
	mm.pending_action = replay
	G.SETTINGS.paused = true
	MPAPI.queue_guard_overlay:as_overlay()
	return true
end

Returns false when not queued (caller proceeds), true when queued (caller aborts; the blocked call is stashed; the overlay offers Leave Queue & Continue / Leave Queue / Stay Queued).

The replay closure must re-enter the caller's OWN complete entry point, not a lower-level primitive. Replaying MPAPI.join_lobby directly would join server-side but skip the consumer's post-join setup, stranding the player. The replay re-enters a guarded entry point, so the gate is re-checked: is_queued() is false after a successful leave; if the leave did not take, it re-blocks instead of soft-locking. Only Leave Queue & Continue consumes the stash; otherwise the next guard_queued call overwrites it.

Behavior change: leave() fires left

handle:leave() now fires the left event locally, before the server round-trip, idempotent via the existing _left guard. Cancel-search UI resets regardless of which path initiated the leave.

Deliberately not here: lobby create/join guarding

An earlier revision guarded MPAPI.create_lobby/join_lobby in the API; replaying the primitive skipped the consumer's post-join setup and stranded the client. It was removed; each consumer mod guards its own entry points instead (see Related).

How to review

1. api/matchmaking/queue_guard.lua — the core gate and the start_run wrap.
2. ui/queue_guard_overlay.lua — the overlay, leave_all_handles, stash consume/replay. Esc/back = Stay Queued.
3. api/matchmaking/handle.lua — the left event change.
4. localization/en-us.lua — strings only.
5. dev/test_queue_guard.lua — tests.

Tests

luajit dev/test_queue_guard.lua from the repo root; only a LuaJIT binary needed. The script stubs the Balatro/MPAPI surface and drives the real module source. Covers the guard_queued contract, the run-start gate (block, stash, replay-after-leave, re-block while still searching), a pre-fix control that fails without the gate, and handle:left firing exactly once.

Related

• fix(networking): FIFO-queue api_client responses so concurrent requests don't collide #10 (api_client FIFO fix): Leave Queue & Continue in the consumer lobby flows fires leave+join back-to-back, which the old single-callback client clobbered. This PR's run-start path works without fix(networking): FIFO-queue api_client responses so concurrent requests don't collide #10, but land fix(networking): FIFO-queue api_client responses so concurrent requests don't collide #10 first or together.
• Consumer PRs building on guard_queued (need both API PRs): feat(lobby): block create/join while in matchmaking BalatroMultiplayer#496, feat(lobby): block create/join while in matchmaking V-rtualized/BalatroSpeedrunning#1.

What it looks like — every entry point, every button

Captured by scripted visual test scenarios (maintained alongside the dev tooling, not part of this PR; each scene fakes the queued state and goes through the real wrapped G.FUNCS paths). Full annotated gallery: VERIFICATION.md.

The guard, with the search visibly running ("Queueing m:ss", left panel):

The story from the New Run setup screen — queued, then blocked on Play. Note the guard replaces the setup overlay rather than stacking, so dismissing lands on the main menu (worth a maintainer opinion on whether that's acceptable):

Outcomes: Stay Queued (search still ticking) · Leave Queue (search gone, no run) · Leave Queue & Continue (queue left AND the blocked run really starts):

[ChronoFinale]

What shows up if you try to start a new run, continue a run, or start a challenge when you are queued up.

1. Tested leaving queue,
2. Tested leaving queue + play correctly plays the selected game option
3. Tested stay queued

[ChronoFinale]

Updated to block create/join lobby when queued