macOS: run the LaunchDaemon as a Standard job, not Background, so the engine's first Metal compile finishes inside ollama's GPU-discovery window (#1521)

[gen16k]

Fixes #1521

Why

On macOS, the first engine start with a cold Metal shader cache lost the GPU. This happens after the bundled ollama moves to a new version, and whenever the cache is cold. ollama's own GPU discovery was cut off by its fixed 30 s watchdog (llama-server GPU discovery watchdog timed out), and the engine then ran as a CPU host until its next restart (total_vram="0 B", mmap off).

Cause. The LaunchDaemon plist said ProcessType=Background, and every process the daemon spawns inherits that class. So ollama serve and every llama-server ran at background QoS. A llama-server's first start has macOS's MTLCompilerService compile ggml's Metal shaders at the requester's QoS. Under Background that compile outlasted the 30 s window.

What I measured on an M4 Mac mini, from a cold cache:

• The same bundle, started by hand from a shell, discovered the GPU in 12 s.
• Started as the product does, discovery was cut off 3 times out of 3.
• ollama kills the discovery process at 30 s, and the compile it had started is thrown away. So restarting straight away, which is what this PR first did, is cut off the same way (tried on hardware and dropped).

Where Background came from. It dates from the repository's first import, with the reason "tells App Nap to leave us alone". App Nap is a mechanism for apps, not for a LaunchDaemon. The Linux systemd unit and the Windows service set no lower priority.

What changed

• internal/platform/service/service_darwin.go: the plist's ProcessType is Standard (the same as leaving the key out). The comment gives the reason and points to the decision record.
• service_darwin_test.go: pins the key/value pair <key>ProcessType</key>\n <string>Standard</string> as a PRODUCT CONTRACT (owner decision 2026-09-22 on macOS: the first start after the bundled ollama moves to a new version times out its GPU discovery, and that engine runs as a CPU host until it restarts #1521).
• Decision record docs/decisions/20260922/0230-launchdaemon-runs-as-a-standard-job.md, with the measurements.
• The 2026-09-21 knowledge note that left the cause open is corrected in place (docs/knowledges/20260921/2210-…).
• No upgrade path for existing installs: this is pre-release (owner). The plist is written by a fresh install and by waired-agent install.
• Dropped from this PR: the immediate "restart once" (see Why). ollama: check the engine's own GPU discovery against waired's prediction at start (#1513) #1514's WARN (engine_discovery_error) stays as the detector.

Measurements

The product's own start, 3 runs per condition, median unless noted. No other load was running (sharing off). Power is the mean of 5 × 1 s powermetrics samples taken from 3 s into a 1024-token generation.

	M4 Mac mini 16 GB (qwen3.5-4b): Background → Standard	M5 Pro MacBook Pro 48 GB, on AC (qwen3.6-35b-a3b): Background → Standard
GPU discovery, cold cache	30.4 s, cut off 3/3 → 14.2 s, 0/3	30.3 s, 3/3 → 12.1 s, 0/3
Model load, cold cache	121.5 s → 24.3 s	103.1 s → 24.3 s
Model load, warm	7.36 s → 2.37 s	7.22 s → 1.84 s
Generation	26.0 → 26.8 tok/s	59.8 → 77.7 tok/s
Generation while a foreground CPU load runs	21.3 → 22.4 tok/s	39.8 → 47.5 tok/s
Foreground CPU load (one loop per core) during generation, vs. alone	10.25 / 9.84 s → 10.11 / 9.90 s	+15 % → +16 % over its own alone figure
Power while generating	8.75 → 9.23 W (+5.5 %, +3 % per token)	28.2 → 38.9 W (+38 %, +8 % per token)

• The cost is power while generating. Battery life on a Mac laptop is expected to be shorter; this was not measured on battery.
• The foreground was not slowed more under Standard.
• A void first attempt is not in the table: the first round's "foreground load during generation" waited for the generation as well, so it was discarded and redone.

macOS security side (Background Task Management / launchd)

• Disposition: BTM kept the job [enabled, allowed] through every switch and reload on both Macs. There was no disallow or disable.
• launchd: spawn type went from background (5) to daemon (3).
• Notification: a changed plist is registered again as an updated legacy daemon item (new record), and BackgroundTaskManagementAgent prepares a user notification at that moment ("Background Items Added"). That is the same notification a fresh install shows.
• Product path on hardware (M4 Mac mini, this branch built as 0.0.3-dev.20260922+1fda5731):
  • binaries were replaced with install -m 0755, as install.sh does;
  • waired-agent install exited 0, and the plist reads Standard and lints clean;
  • BTM showed [enabled, allowed];
  • the engine was ready at utility QoS;
  • cold-cache discovery took 12.1 s and was not cut off (Metal, Apple M4); the model loaded at +24.3 s and generation worked.
• A trap when testing by hand: overwriting the running /usr/local/bin/waired-agent in place with cp and then running it gets that process killed by macOS (Killed: 9), because code signing is cached per file. The installer's install -m writes a new file and is not affected.

Tests and checks

• TestRenderLaunchDaemonPlist_HappyPath pins the pair. Every darwin test in internal/platform/service passes on an M5 Pro Mac, using the cross-compiled test binary.
• Mutation: rendering Background again fails the test (plist must set ProcessType=Standard).
• Other checks:
  • go test ./internal/platform/service/ on Linux;
  • GOOS=darwin|windows go vet;
  • golangci-lint on Linux: 0 issues. GOOS=darwin reports one finding that is already on main (service_darwin_test.go:627, QF1001) and not from this change;
  • hostname-guard.py;
  • decision-log-guard.py.

Other OSes

• Linux and Windows are not affected by this mechanism. Their services set no lower priority, and ollama's Vulkan and CUDA backends compile lazily, not during discovery.

• Related risks surfaced by the same review are not in this PR. They include:

  • Windows' battery-time QoS for background services;
  • Linux's render-group access for AMD/Intel GPUs.

  They need hardware checks and owner approval before they are filed.

Refs

• macOS: the first start after the bundled ollama moves to a new version times out its GPU discovery, and that engine runs as a CPU host until it restarts #1521
• ollama: check the engine's own GPU discovery against waired's prediction at start (#1513) #1514
• ollama converge: wait for it before the first start, read the binary's own version, keep ROCm (#1511) #1512
• docs/decisions/20260922/0230-launchdaemon-runs-as-a-standard-job.md
• launchd.plist(5) ProcessType

🤖 Generated with Claude Code

https://claude.ai/code/session_01BviBGHJqCeM88hxCRYrtAg