fix(bazel): pre-subscribe AXL build_events() via local() sink

[gregmagolan]

Summary

Fixes an intermittent late-subscribe race in ctx.bazel.build(...)'s
event stream. The AXL-facing receiver returned by
build.build_events() was created lazily, only when the AXL task
called the method. On a warm bazel daemon with a fully cached build,
BES events stream within milliseconds — fast enough that any work
between ctx.bazel.build(...) returning and the subsequent
build.build_events() (a task_update emit, a buildkite-agent annotate spawn, the gRPC sink's connect attempt) could let the
early burst (build_started, target_completed,
named_set_of_files) flow before the AXL subscriber registered.

Observed symptoms:

• runnable.determine_entrypoint() returned None → Failed to determine the formatter entrypoint. on aspect format (sister
  errors on aspect gazelle / aspect lint). Lint's SARIF
  collector missed reports → "0 findings" on runs that should have
  flagged.
• Live status surfaces stuck on "Spawning bazel build…" until the
  first non-burst event arrived.
• Cold-daemon runs passed; warm-daemon runs flaked. Race that
  escapes local testing.

Two fixes together:

1. Explicit local-iteration intent

New BuildEventSink::Local variant + AXL factory
bazel.build_events.local(buffer_cap=10000). Callers declare
local-iteration intent up front instead of relying on the runtime
to guess from a subsequent build.build_events() call:

build = ctx.bazel.build(
    "//target",
    build_events = [
        bazel.build_events.local(),                # AXL iterates
        bazel.build_events.grpc(uri = "..."),      # remote forwards
    ],
    flags = flags,
)

# Existing `build_events = True` continues to work — it now expands
# to `[bazel.build_events.local()]`.

Build::spawn registers the local subscriber inside the spawn,
before bazel opens the BEP FIFO and before remote gRPC sinks touch
the network. The first call to build.build_events() returns the
pre-subscribed receiver; events broadcast in between were already
buffered.

If no Local sink is configured, build.build_events() errors at
call time — the runtime won't subscribe behind the caller's back,
because every undrained subscription is buffered memory.

2. Capped buffer (memory bound)

A misbehaving task that subscribes but never drains would otherwise
grow the channel without bound. New CappedSubscriber<T> wraps a
Receiver + shared Arc<AtomicUsize>. The broadcaster's subscriber
list becomes Vec<Subscription<T>> with Unbounded (existing —
tracing sink, gRPC sinks) and Capped { tx, queued, cap } variants.
On each send the broadcaster checks the capped entries; when
queued >= cap it drops the subscription and the AXL iterator sees
Disconnected on its next recv. Default cap is 10000 events.

Built-in tasks updated

Every built-in task that iterates BES events now prepends
bazel.build_events.local() to its sink list:

• build / test (via lib/bazel_runner.axl) — gated on
  need_bes (any bazel_trait.build_event handler or
  lifecycle.task_update handler registered).
• lint, format, gazelle, delivery — always (each calls
  build.build_events() unconditionally).

Docs

DEVELOPMENT.md updated: the broadcaster section now describes the
explicit-intent contract, the buffer-cap semantics, and the
late-subscribe escape hatch. The contributor checklist is updated to
remind authors of new tasks to include bazel.build_events.local()
when they iterate.

Relationship to HANG_ANALYSIS.md and PR #1071

HANG_ANALYSIS.md covers a separate GHA-cancel hang with three
root causes. PR #1071 (fix(http): bound read and connect timeouts on the runtime HTTP client, already landed) handled one of them. The
remaining two (signal-handler / process-registry plumbing for
subprocess cleanup on cancel) are in a separate change set and not in
this PR. The two surface areas overlap (BES event-stream
plumbing / cancellation cleanup) but the fixes are independent.

---

Changes are visible to end-users: yes

• Searched for relevant documentation and updated as needed: yes
• Breaking change (forces users to change their own code or config): no
• Suggested release notes appear below: yes

Suggested release notes

• New bazel.build_events.local(buffer_cap=10000) AXL factory.
  Declare it explicitly in the build_events=[...] list of
  ctx.bazel.build(...) / ctx.bazel.test(...) when your task
  iterates the BES stream via build.build_events(). The runtime
  pre-registers your receiver before bazel opens the BEP FIFO,
  eliminating the warm-daemon late-subscribe race that caused
  intermittent Failed to determine the formatter entrypoint. and
  similar errors. ctx.bazel.build(build_events = True) continues to
  work — it now expands to [bazel.build_events.local()].
• build.build_events() now errors when called against a build that
  was configured with remote BES sinks but no local sink. Callers
  that need to iterate locally must opt in via
  bazel.build_events.local(...). Existing callers using the True
  shorthand are unaffected.

Test plan

• New test cases added: 3 broadcaster unit tests covering
  normal-drain, overflow-drop, and capped-coexists-with-unbounded
  paths.
• Covered by existing test cases: every built-in task's snapshot
  suite (PR comment, BK annotation, template, lint, format, gazelle,
  delivery) — 727 AXL tests + 7 snapshot suites pass.
• Manual testing: ran each of aspect build, aspect test,
  aspect lint, aspect format, aspect gazelle, aspect delivery
  against a warm daemon and confirmed entrypoint resolution, SARIF
  collection, and live status-surface phase tags consistently see
  the early-burst events.

[aspect-workflows]

✨ Aspect Workflows Tasks

📅 Wed May 13 04:05:49 UTC 2026

✅ 16 successful tasks

• ✅ build (build-gha) · ⏱ 1m 16s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel build complete (161 built)
• ✅ build (build-gha-debug) · ⏱ 1m 41s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel build complete (161 built)
• ✅ format (buildifier-gha) · ⏱ 1m 27s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Format complete (clean)
• ✅ format (buildifier-gha-debug) · ⏱ 1m 21s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Format complete (clean)
• ✅ delivery (delivery-gha) · ⏱ 1m 45s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Delivery complete (1 delivered)
• ✅ delivery (delivery-gha-debug) · ⏱ 5m 26s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Delivery complete (1 delivered)
• ✅ format (format-gha) · ⏱ 1m 25s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Format complete (clean)
• ✅ format (format-gha-debug) · ⏱ 1m 32s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Format complete (clean)
• ✅ gazelle (gazelle-from-source-gha) · ⏱ 1m 24s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Gazelle complete (clean)
• ✅ gazelle (gazelle-from-source-gha-debug) · ⏱ 1m 18s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Gazelle complete (clean)
• ✅ gazelle (gazelle-gha) · ⏱ 1m 20s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Gazelle complete (clean)
• ✅ gazelle (gazelle-gha-debug) · ⏱ 1m 22s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Gazelle complete (clean)
• ✅ lint (lint-gha) · ⏱ 1m 20s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Lint complete (clean)
• ✅ lint (lint-gha-debug) · ⏱ 1m 31s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Lint complete (clean)
• ✅ test (test-gha) · ⏱ 1m 13s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (25/25 passed · 25 cached)
• ✅ test (test-gha-debug) · ⏱ 1m 35s · ✨ Aspect · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (24/24 passed · 22 cached)

---

_{Powered by Aspect Build · GitHub · X · LinkedIn · YouTube}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f1b6c61af8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".