perf(indexing): faster cold index that yields to foreground work

[bhavsarpratik]

Summary

• Platform scope: the parallel cold index runs on macOS only. Linux and Windows keep the existing sequential cold index (identical results) until worker processes are verified on those hosts; enable via PlatformCapabilities.parallel_index. All platforms get the matched-pace speedup. Linux keeps its tested /proc/stat/power_supply probes for later enablement; the untested Windows ctypes probes were removed.
• Parallel cold index. The first build after install or restart used to parse every trace on one core. It now prefetches session summaries in a spawn-context worker pool, then reuses the existing sequential loop unchanged. Anything the pool doesn't store goes through the old path: too few sources, a single CPU, a worker error, or a pool that breaks or won't start. Results match the sequential path exactly.
• Doesn't slow the machine. token_meter/services/indexing.py caps the pool at half the logical CPUs (at most 6, and 2 on battery or Low Power Mode). Every second it adjusts the number of workers from measured idle CPU (additive increase, multiplicative decrease): it halves them when less than one CPU is idle and adds one while two or more are idle. When the host is saturated, workers move to macOS Utility QoS. Measured here: lowering priority with nice alone slowed a CPU-bound foreground job by 30–60%, while Utility QoS had no measurable impact. Workers run niced with utility disk I/O, exit with the server (they watch its process handle), and run from the temp directory.
• Platform hooks. PlatformServices gains lower_background_priority, set_background_mode, power_constrained, and cpu_activity for macOS (QoS, pmset, host_statistics), Linux (/proc/stat, power_supply), and Windows (SetPriorityClass, GetSystemTimes, GetSystemPowerStatus). Each one is best-effort: it returns unknown and never raises.
• Memory-safe. Each worker can peak at several hundred MB on a large trace, so the pool allows one worker per 4 GB of RAM (8 GB → 2, 16 GB → 4, 24 GB+ → 6; 2 if unknown). The macOS kernel memory-pressure level (the one behind Activity Monitor's memory graph) caps the workers at half the pool on warn and one worker on critical. Because a Python worker keeps its peak memory until it exits, pressure also restarts the pool at that smaller size. Measured: forcing critical mid-build cut worker memory from about 1.5 GB to one worker (≤ ~750 MB). If the OS refuses to start a worker, a worker is killed, or a restart fails, indexing falls back to the sequential path with identical results (all covered by tests).
• Faster, prompt-free install. When the Swift toolchain is already installed (checked with xcode-select -p, which never prompts), the macOS installer compiles the menu bar companion in the background while the server indexes, then waits only for what is left. Without a toolchain it builds after the server is ready, exactly as main does, so the installer never opens Apple's developer-tools dialog unexpectedly. Output, failure messages, smoke check and LaunchAgent order are unchanged; a failed or interrupted install stops the build and removes its temp files. Live, with a cold build: Server ready 20s, menu bar companion ready 0s after that.
• Codex warm start. Workers receive Codex's signature-checked trace-head metadata, so they don't each reread all 1,324 rollouts to resolve lineage (2.6s → 0.06s per worker).
• Matched-pace speedup, results unchanged. Per-turn features are computed once, a log-output band skips pairs that can't match, and the bootstrap draws are inlined using the same random stream. Output is byte-identical to main.

Results (this Mac, 2,240 sessions, heavily shared machine)

	main	this branch
Cold session summaries	45.1s	11.5s (2,237 settled sessions identical)
Matched-pace CPU	17.0s	8.9s (JSON byte-identical)
LaunchAgent restart → state_ready	56.5s (a second restart took 234s, likely machine load)	31–46s

Discovery (~16s) is unchanged and is the next target.

Test plan

• python3 -m unittest discover -s tests: 1,514 tests, 0 failures (main merged in, including the test_goals fix)
• New tests:
  • tests/integration/test_cold_index.py: fixture parity, real spawned workers including a forked Codex child, every fallback path, AIMD bound, single-flight, worker exit on parent kill.
  • tests/domain/test_matched_pace_parity.py: frozen main reference, checked against an injected change.
  • tests/contracts/test_platform_background_work.py.
  • Codex worker-state round trip.
• py_compile, embedded JS parse, bash -n, git diff --check
• macOS install: /health and /menubar OK, both LaunchAgents running, source/runtime parity checked, 6 workers observed. A restart with workers running left 0 behind.
• Independent tester plus two reviewers (correctness/regressions and platform/packaging/privacy), all passed on 5990bf0.
• Linux and Windows stay sequential: tests assert cross_session rows equal the sequential path with no executor created; suite also passes with the server platform simulated as Linux
• Before enabling Linux: run on a Linux host (systemd user unit, containers, worker exit, priority)
• Before enabling Windows: re-add priority handling and verify on a Windows host (hidden console, reinstall during a cold build)

🤖 Generated with Claude Code