[leehack]

Summary

• Root cause of Diagnose backend-initialization timeout in desktop text/image coexistence smoke #1674. flutter test -d macos often cannot foreground the app it launches: the log shows Failed to foreground app; open returned 1, in the historical log and in every early run here. macOS then naps the app. On a busy host the napped app runs at scheduler priority 4 and gets almost no CPU. The llama.cpp worker misses its 30 s startup deadline, and the test fails with exactly Timed out after 30000 ms waiting for the llama.cpp worker to initialize its backend. The runtime itself is fine.
• run_local_e2e.dart now runs Flutter through the new tool/testing/without_app_nap.sh for every -d macos device scenario. The script sets NSAppSleepDisabled for com.example.llamaDartChatExample, runs the command, then restores the previous value: absent, YES or NO. The exit status is kept. Other devices, and the host-only macOS quit/shutdown scenarios, are unchanged.

Production-readiness scope

• User-facing scope: none. This is local E2E tooling only, so maintained macOS device smokes no longer fail with a false backend-init timeout on a loaded host.
• Supported platforms/paths: run_local_e2e.dart Flutter device scenarios with --device macos.
• Unsupported or intentionally unavailable paths: the library deadline is unchanged. A real app that is napped on a saturated host can still time out at 30 s. That is a separate design question, noted on Diagnose backend-initialization timeout in desktop text/image coexistence smoke #1674.
• Out of scope / follow-ups: None.

Completeness checklist

• Declared scope is fully implemented, or explicitly reduced above.
• Unsupported platform/option combinations fail loudly with actionable diagnostics or are clearly documented as unavailable.
• Public API docs, README/website docs, examples, support matrices, and changelog entries are updated where relevant. N/A: maintainer tooling with no user-facing change.
• Regression coverage covers the original issue plus key negative/version-skew paths where relevant.
• Public capability changes update the validation coverage registry with a pack or a reasoned, issue-linked exemption; inventory checks pass (or N/A with scope). N/A: no capability change.
• Security/privacy review completed: no secrets, bearer tokens, signed URLs, or raw secret-bearing paths leak through logs, cache keys, metadata, errors, or snapshots.
• Follow-up work that is useful but not required for this PR is tracked in GitHub Issues, or explicitly marked "None" above.

PR type guidance

• Bugfix PR: the root cause is above. The regression tests are run_local_e2e_test.dart (every macOS device scenario is wrapped; iOS is not) and without_app_nap_script_test.dart (a fake defaults checks that App Nap is disabled during the command, that each prior state is restored, that the exit status is kept, and that the bundle id matches AppInfo.xcconfig). The script tests are skipped on Windows. The bundle-id check runs on every platform. Platform: macOS hosts only.

Test Plan

• dart run tool/prepare_workspace.dart
• dart format --output=none --set-exit-if-changed .
• dart analyze: no issues.
• dart test -p vm -j 1 --exclude-tags local-only: ran test/unit/tooling/, 1619 passed. windows_registry_qualification_test.dart fails 6 cases identically on unmodified main on this Mac. It is pre-existing and unrelated.
• dart test -p chrome --exclude-tags local-only N/A: VM tooling only.
• coverage-lib matrix row when lib/ behavior changes. N/A: no lib/ change.
• Other targeted/local-only validation: failing-first, mutations and the macOS causal runs below. chat-app-text-image-coexistence --device macos rerun: see Matrix Evidence.

Matrix Evidence

Matrix row	Scope covered	Platform / model / backend	Result	Evidence / notes
Failing-first	new and updated tests against origin/main tooling	VM	FAIL 8 (3 pinned macOS dry-runs, new wrapper test, 4 script tests) → PASS 146 with the change
Mutations	M1 wrap every device · M2 never wrap · M3 no restore trap · M4 never disable · M5 swallow exit status · M6 drop a prior YES	VM	each fails 1–5 tests; restored tree passes 146
Startup under App Nap (causal)	scratch integration probe, not committed: fresh NativeLlamaBackend startups with the default 30 s deadline	macOS 26 M4, Flutter 3.47.1 debug, chat app	64 busy processes, host load 190–270, app not foregrounded: app sampled at pri 4, 0 % CPU. 1/20 startups failed with the exact historical error after 370 s wall time (the timer itself was starved)	llamadart-evidence/issue-1674-lane6/
Same, App Nap disabled	NSAppSleepDisabled YES, same load	same	0/60 startups failed over 3 runs; max 2.8 s (first launch); app at pri 47. These runs did not log the foreground failure (one hid the app), so the starvation pair below is the matched control
Timer starvation pair	1 s timer gaps while idle, both runs with open returned 1	32 busy processes	App Nap allowed: max gap 17.5 s, 63 of 90 ticks. App Nap disabled: max gap 1.0 s, 60 of 60 ticks
chat-app-text-image-coexistence --device macos	maintained scenario through the guard	Qwen3.5-0.8B Q4_0 (57d19977…) CPU + SDXS-512 Q8_0 (409ab235…) MTL0, native llama v0.9.0, sd v0.3.0-3, 32 busy processes, host load 130–180, open returned 1 (not foregrounded)	PASS: app at pri 54 with NSAppSleepDisabled=1 during the run and the setting restored to absent afterwards. Both 32-token replies d5208dd3…, both 512×512 images b5624e7d… (the same hashes as the 2026-11 maintainer runs), dispose OK	coexist-fixed-load32.log. Earlier unguarded runs under load never reached text_load: the napped app's SDXS download stalled at 504 MB for over 1.5 h, and through the guard it finished in 14 s

Review Notes

• Independent review status: N/A: standard-risk tooling change (classify_high_risk_changes.dart: standard).
• CI status / head SHA: green at 2e81b00d3319943be50940ee84ef0d058c796097 (34 pass, 9 skipped by selection or manual). At the first head, 2b96823, the Windows tooling shard failed because the Bash script tests ran without POSIX Bash. The second commit skips those on Windows, as the other script tests do, and makes the bundle-id check tolerate CRLF.

High-risk regression review

• Classification: standard
• Implementation task: N/A
• Independent blocking QA task: N/A
• Exact head / current base: N/A
• Production-branch deletion, bypass, or miswire proof: N/A
• Affected-family real-model/artifact evidence: N/A
• Explicit unavailable-family or other N/A evidence: N/A
• Known PR-caused P1 regressions: 0
• Unresolved review threads: 0

Fixes #1674
Refs #1845

[leehack]

Landed through the 0.19.2 batch integration PR #1870 (rebase merge, one commit per constituent; this PR's pinned head was audited/CI-gated there).

[github-actions]

Chat app preview removed for leehack/llamadart-chat-pr-1860.