running-process broker: fbuild adoption tracker

[zackees]

?## Scope

Track fbuild adoption of the upstream running-process v1 broker work.

Source tracker: zackees/running-process#242
Upstream phase gates:

• Phase 2.5: Extract BackendHandle abstraction (foundation for broker) zackees/running-process#232 - Phase 2.5 BackendHandle
• Phase 4: running-process-broker-v1 binary + Hello negotiation + perf-guard CI zackees/running-process#235 - Phase 4 broker client helper
• Phase 7: Default-off → default-on rollout (process discipline) zackees/running-process#238 - Phase 7 default-on rollout discipline
• Phase 8: Remove escape hatch (RUNNING_PROCESS_USE_BROKER=off) zackees/running-process#239 - Phase 8 escape-hatch removal

Related local context:

• Migrate all subprocess spawns to running-process; eliminate direct std::process / tokio::process usage #141 tracks broader subprocess migration to running-process.
• Daemon teardown hardening: process containment + socket lingering + console events #32 tracks daemon teardown hardening and process containment.
• Those are adjacent lifecycle/process-management issues, not this full broker adoption tracker.

Adoption checklist

• Adopt running_process::broker::BackendHandle once Phase 2.5 ships, replacing bespoke daemon probe / recovery / version-match wrappers where applicable.
• Ship a fbuild-daemon.servicedef file in installers/packages at the platform paths defined by running-process, with the intended isolation mode declared.
• Wire broker-client integration through running_process::broker::client::connect_to_backend once Phase 4 ships, including Hello-skip and broker fallback behavior.
• Honor RUNNING_PROCESS_DISABLE=1 as the broker escape hatch while Phase 7 rollout is active.
• Test both broker-mode and direct-daemon-mode paths.
• Document the broker default mode and escape hatch in the fbuild README/docs.
• Phase 7: stage default-off to default-on per the upstream rollout gate.
• Phase 8: remove the escape hatch only as part of the coordinated release wave tracked by Cross-cutting: Per-consumer broker adoption tracking (clud / zccache / fbuild / soldr-daemon) zackees/running-process#242.

Notes

zackees/fbuild is not visible to the GitHub connector; the accessible fbuild repository is FastLED/fbuild. Keep running-process#242 updated if the canonical repo mapping changes.

Minimal working path status

• PR feat: stub running-process broker adoption #529 added the fbuild running-process service metadata seam, platform service-definition path helper, direct fallback mode, and RUNNING_PROCESS_DISABLE=1 diagnostic surface.
• PR feat: stub running-process broker adoption #529 added crates/fbuild-daemon/running-process/fbuild-daemon.servicedef.textproto.in as the packager template stub.
• PR feat: add running-process daemon diagnostics #530 added diagnostics-only fbuild daemon running-process --json and fbuild daemon servicedef --json previews for service metadata, service-definition path, daemon binary candidate/existence, current direct-fallback mode, and deferred broker items.
• Stubbed: encode and install the binary fbuild.servicedef in installers/packages at the platform running-process service directory.
• Stubbed: active BackendHandle endpoint-response probing; fbuild still uses the direct loopback HTTP daemon endpoint for this slice.
• Stubbed: running_process::broker::client::connect_to_backend / Hello-skip broker path.
• Deferred: broker-mode vs direct-daemon-mode integration tests and three-OS acceptance.
• Deferred: Phase 7 default-on rollout and Phase 8 escape-hatch removal.

Current minimal policy

Current-regime fbuild work is satisfied by #529 and #530: fbuild exposes the running-process service metadata seam, direct fallback mode, service-definition template path, and diagnostics-only fbuild daemon running-process --json / fbuild daemon servicedef --json previews.

Everything else stays stubbed for now: binary .servicedef encoding/install, active BackendHandle, running_process::broker::client::connect_to_backend, the broker/direct integration matrix, full lint/dylint, and broad three-OS acceptance. Reopen or split follow-up issues only when stable broker APIs are worth pinning for fbuild.

[zackees]

Merged the minimal running-process adoption slice.

PR: #529
Merge SHA: edb861bac0216fa63a66b6c84d244b88962b444a

What landed:

• service metadata/path seam in fbuild_paths::running_process
• explicit direct fallback mode with RUNNING_PROCESS_DISABLE=1 diagnostic surface
• fbuild-daemon.servicedef.textproto.in template stub for future package/install rendering
• CLI runtime diagnostic/spawn tracing for the current running-process broker state

Critical Windows-local checks run:

• git diff --check
• soldr cargo test -p fbuild-paths running_process -- --nocapture
• soldr cargo check -p fbuild-cli
• soldr cargo fmt -p fbuild-paths -p fbuild-cli -- --check

#510 remains open. Stubbed/deferred items are now listed in this issue body: binary fbuild.servicedef package install, active BackendHandle probing, connect_to_backend / Hello-skip broker path, broker/direct integration tests, three-OS acceptance, and Phase 7/8 rollout/removal.

[zackees]

Updated this tracker with the current minimal policy.

For fbuild, the next small useful slice is diagnostics-only: add a fbuild daemon running-process --json / fbuild daemon servicedef --json preview that reports the computed service metadata, service-definition path, daemon candidate path/existence, and current direct-fallback mode.

Still stubbed/deferred: binary .servicedef encoding/install, active BackendHandle, running_process::broker::client::connect_to_backend, broker/direct integration matrix, full lint/dylint, and broad three-OS acceptance. Functional broker adoption should wait until stable broker APIs are worth pinning.

[zackees]

Current-regime fbuild slice is complete.

Merged PRs:

• feat: stub running-process broker adoption #529: running-process service metadata seam, service-definition template stub, direct fallback mode, and escape-hatch diagnostic surface.
• feat: add running-process daemon diagnostics #530: diagnostics-only fbuild daemon running-process --json plus fbuild daemon servicedef --json alias, reporting service metadata, service-definition path, daemon binary candidate/existence, direct-fallback mode, and deferred broker items.

Focused Windows host checks for #530:

• soldr rustfmt --edition 2021 crates\fbuild-cli\src\cli\args.rs crates\fbuild-cli\src\cli\daemon_cmd.rs crates\fbuild-cli\src\cli\tests.rs
• git diff --check
• soldr cargo test -p fbuild-paths running_process -- --nocapture
• soldr cargo test -p fbuild-cli daemon_running_process -- --nocapture
• soldr cargo test -p fbuild-cli daemon_servicedef -- --nocapture
• soldr cargo check -p fbuild-cli
• soldr cargo run -p fbuild-cli -- daemon running-process --json
• soldr cargo run -p fbuild-cli -- daemon servicedef --json

Closing this tracker as satisfied under the current minimal regime. Deferred/stubbed by design: binary .servicedef encoding/install, active BackendHandle, connect_to_backend, broker/direct integration matrix, full lint/dylint, and broad three-OS acceptance. Those remain visible on zackees/running-process#242 and should be split/reopened only when stable broker APIs are worth pinning for fbuild.