Meta: burn down remaining open issues one by one (#1009 → #1010, then #574)

[zackees]

Meta / tracking issue: burn down the remaining open fbuild issues, one at a time

Sequencing/tracking issue for the 3 remaining open work items on FastLED/fbuild. Worked and merged one by one in the order below — chosen by dependency first, then scope (the tight, shared-code daemon pair before the large architectural refactor). Check each box as its PR merges; this meta auto-closes when all are CLOSED.

Snapshot taken 2026-07-09. Open work: #1009, #1010, #574. (Successor to #1007, whose only remaining item is #574 — see Phase 2.) The recently-completed compile-parallelism split is #1008.

---

Phase 1 — daemon robustness cluster

These two are siblings sharing one code surface (crates/fbuild-cli/src/daemon_client.rs spawn/endpoint logic) — both fallout from the #940 → #1006 daemon-identity work. Do them together, correctness-first, since #1009's per-checkout endpoint keying gives #1010 a natural bind target.

• daemon: endpoint isolation follow-up to #940 — key the default endpoint by cache-identity/checkout + deterministic version arbitration #1009 (DONE — PR fix(daemon): version+identity-keyed endpoint + version arbitration (#1009) #1020 merged) — key the default endpoint by cache-identity/checkout + deterministic version arbitration

  • Why first: correctness, and it establishes the per-checkout endpoint that daemon: concurrent fbuild invocations stampede daemon spawn — add single-flight + bind before heavy init #1010 binds against. Today two checkouts still share the fixed per-user port (8765/8865) and can silently serve each other wrong-version builds; Warn on daemon identity mismatches #1006 only made the mismatch warn, not stop. Root cause: the endpoint is a fixed per-user TCP port, not keyed by version or checkout.
  • Work: key the default endpoint by cache-identity/checkout so distinct checkouts get distinct endpoints; add deterministic version arbitration so the right-version daemon wins instead of whoever bound first. Follow-up to Multi-checkout daemon collision: two repos share port 8765, wrong-version daemon serves both (stale flags, dead-endpoint deploys) #940 (closed by Warn on daemon identity mismatches #1006, warn-only).

• daemon: concurrent fbuild invocations stampede daemon spawn — add single-flight + bind before heavy init #1010 (DONE — PR fix(daemon): bind-before-heavy-init single-flight for concurrent spawns (#1010) #1021 merged) — single-flight daemon spawn + bind-before-heavy-init

  • Why second: builds on daemon: endpoint isolation follow-up to #940 — key the default endpoint by cache-identity/checkout + deterministic version arbitration #1009's endpoint keying. N concurrent fbuild invocations with no daemon running (common CI / parallel-build pattern) all spawn a full fbuild-daemon — the direct spawn path (ensure_direct_daemon_running) has no spawn lock, no single-flight, no pre-bind probe.
  • Work: add a spawn lock / single-flight so only one invocation spawns; bind the port before heavy init so late arrivers detect the winner and wait rather than racing; arbitrate early instead of after a 10 s poll × 3. The broker path exists but silently falls back to the direct path when no broker runs (the common case) — close that gap.

---

Phase 2 — architecture (largest refactor, do last)

• fbuild: design unified namespaced routing for platform/framework/library artifacts driven by platformio.ini [env:*] #574 (DONE — PR feat(build): EnvNamespace + unified build_flags overlay propagation (#574) #1022 merged) — unified namespaced routing for platform/framework/library artifacts driven by platformio.ini [env:*]
  • Why last: largest architectural change; touches every per-platform orchestrator. The lone remaining item from the prior meta Meta: burn down all open fbuild issues one by one (#962 → #959 → #722, then #527, then #574) #1007 (its other four sub-issues — fbuild port scan misses all PJRC/Teensy (VID 16C0) serial ports + no vendor/product resolution for them #962, follow up all known vids needs built in embedding #959, feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722, Proposal: first-class fbuild cache save / restore for toolchains + platforms + framework + zccache sidecar #527 — are done). Landing this closes Meta: burn down all open fbuild issues one by one (#962 → #959 → #722, then #527, then #574) #1007 as well.
  • Work: define a typed EnvNamespace { platform, board, framework, env_id } in fbuild-core/fbuild-config; thread it through every package fetcher, compile invocation, cache path, and output dir; propagate [env:*] build_flags to framework/lib/sketch compiles (currently dropped on nxplpc — the concrete pain point from the LPC845 bring-up); env-scoped lib cache keys; namespace-keyed deployer dispatch; docs/namespacing.md.
  • Verifiable increment: the build_flags propagation is the highest-value, testable core — confirmable via the uno (avr8js) and esp32 (QEMU) emulators with no hardware. Success = one sample sketch builds on uno, teensy40, lpc845brk, esp32s3, esp32c6, teensy41 from one project root with one build_flags mechanism.

---

Working rules for each item

1. Confirm the issue is still open and re-read its body (bodies drift).
2. Plan non-trivial work in the issue thread first (per repo CLAUDE.md).
3. One PR per issue, conventional-commit title, TDD (red → green → refactor).
4. soldr cargo for Rust, uv run --no-project for CI Python — never bare cargo/python.
5. Merge, tick the box here, move to the next. Do not parallelize across phases.

Dependency summary

#1009 ──▶ #1010          [daemon cluster, sequential — shared code, #1009 keys the endpoint #1010 binds]
#574                     [architecture, last; also closes the prior meta #1007]

🤖 Filed via Claude Code — successor burn-down to #1007.

[zackees]

Done — all three items merged

#	PR	What
#1009	#1020	Daemon endpoint keyed by version+cache-identity (dynamic port + daemon-<key>.port) + semver arbitration that never evicts a newer daemon
#1010	#1021	Daemon binds before heavy init; losers of the spawn race yield (exit 0) in ms; CLI adopts a concurrently-started daemon
#574	#1022	Typed EnvNamespace + single-source-of-truth compile_overlays() guaranteeing [env:*] build_flags reach framework+lib+sketch uniformly (also fixes extra_build_flags being dropped on non-ESP32 paths)

Each verified with a local Linux Docker build (cargo check --workspace + tests) in lieu of GHA. Closing as completed. (#574 was also the last open item of the prior meta #1007, which is now closable too.)