[rush reporter][R6A] Add bootstrap handoff and compatibility adapters

[Sean Larkin (TheLarkInn)]

Part of #5979.

Stack

graph LR
  M["main: Reporter core merged"] --> R6A["This PR: R6 bootstrap handoff"]

Loading

Base: main. All Reporter core prerequisites, including #5989 and #5988, have landed. The main-relative diff remains exactly 36 R6 paths. Bootstrap replay, compatibility, retention and initialization cleanup compose with the landed canonical unfiltered debug log. Parallel Heft, AI qualification and later follow-up features are not imported.

Merge remains gated on current-head CI and independent approval.

Design choice

Use a minimal prelude in the existing generated install-run-rush path rather than add a reporter-specific script variant. This keeps every existing bootstrap entry point and update mechanism intact, uses the frozen zero-dependency encoder/protocol major from #5986, and gates all changed visible behavior behind an explicit reporter request or the repository experiment.

The prelude parses only early reporter/log-level controls plus the comment-aware useRushReporter experiment. It incrementally builds a 1 MiB bounded NDJSON buffer, chunks external output at 64 KiB, preserves required records, evicts only replaceable activity status, appends the RFC truncation marker, and fails if required output cannot be retained. npm stdout/stderr are captured as ordered framed records with a hard capture ceiling and persistent UTF-8 decoding.

The handoff is written under the OS temp directory with owner-only permissions where supported, an exclusive filename, and a nonce duplicated in private path/nonce environment variables. The frontend creates the authoritative host before version selection, replays then deletes the file, clears the private environment, and sweeps abandoned files using the existing retention policy.

Compatibility behavior

• No explicit or repository opt-in: the existing bootstrap logger, inherited npm output, and legacy Rush rendering are unchanged.
• Explicit unsupported reporter/log-level requests fail before loading rush-lib; explicit protocol-major incompatibility fails with an update/use-legacy diagnostic.
• Implicit environment detection does not enable the pre-major path. Repository opt-in safely falls back to legacy for an older frontend or incompatible handoff, replaying bounded raw fallback output instead of losing it.
• New frontend + old engine: legacy engine output remains visible on stderr and is bridged as ordered externalOutput events without contaminating machine-reporter stdout.
• Old frontend + new engine: the engine receives no host sink and retains the existing LegacyFallbackSink/legacy rendering behavior.
• Direct rush invocation has no handoff and converges on the same authoritative frontend host used by bootstrap invocation.

Current landing qualification (September 11, 2026)

Published 67ac6545cad54d2234d4c723686c09c5a023661a preserves the former R6 head and landed main@130daa8 as its two parents. Normal consumer build/types/lint/API and 392 focused Linux tests passed, including full-debug canonical logs under file/normal, physical-close failures, initialization cleanup and concurrent shutdown. New hosted CI and human approval are still required.

Earlier validation (pre-landing snapshot)

• node libraries/reporter/scripts/generateBootstrapProtocol.js --check
• node common/scripts/install-run-rush.js test --only @rushstack/rush-reporter --only @microsoft/rush-lib --only @microsoft/rush
• Built webpack install-run npm-capture smoke test using cowsay@1.6.0 (ordered stdout/stderr frames, no overflow)
• node common/scripts/install-run-rush.js check
• node common/scripts/install-run-rush.js change --verify --no-fetch
• git diff --check

Focused coverage includes direct/bootstrap startup, replay/deletion, invalid path/nonce, missing/unreadable handoffs, permissions, abandoned cleanup, truncation and required overflow, ordered external output, UTF-8 boundaries, unsupported explicit requests, implicit fallback, and old/new frontend-engine combinations.

Rollback

Revert this single commit. The optional hooks in install-run disappear with the prelude, and the default no-opt-in bootstrap/legacy path remains the unchanged fallback throughout the rollout.

Non-goals

• R5 operation rendering or replacing StreamCollator
• Heft child protocol/problem matcher integration
• agent auto-selection or the Rush 6 default flip
• removing legacy terminal APIs, rendering, or fallback behavior

[Sean Larkin (TheLarkInn)]

Independent /pr-agentmerge review completed against #5979 and RFC sections 4.3, 5.5, and 8.

Fixed in 2b8d8e5ede:

• unsupported required bootstrap records now fail explicit reporter requests and trigger ordered legacy fallback for repository opt-in;
• authenticated handoff files are deleted and private environment variables are cleared when frontend selection or reporter initialization fails before replay;
• both older and newer structured engine protocol-major mismatches now fail explicit requests or receive a LegacyFallbackSink for implicit fallback, rather than an incompatible live manager sink.

Verified the minimal zero-dependency prelude, 1 MiB bounded buffering, 64 KiB UTF-8-safe external-output chunks, required-overflow failure, truncation marker, exclusive nonce/path handoff with owner-only permissions, ordered npm capture, replay/delete/retention cleanup, direct invocation, no-opt-in legacy behavior, and no R5 operation-rendering, Heft, or Rush 6 default-flip scope. The old-engine stderr bridge remains intentional to preserve machine-reporter stdout purity; default/no-opt-in output bypasses it and remains unchanged.

Validation completed: focused @rushstack/rush-reporter, @microsoft/rush, and @microsoft/rush-lib tests/builds; bootstrap generation check; rush check; rush change --verify --no-fetch; and git diff --check.

Stack remains intentionally linear with child auto-merge disabled. Required retarget order after each predecessor merges: #5985 -> retarget #5986 to main -> retarget #5987 to main -> retarget #5989 to main -> retarget #5993 to main. At each step, verify the slice-only diff, full CI, and reviews before advancing. Current external gate: #5985 is mergeable with green checks and auto-merge enabled, but still requires approval; the #5986 Windows Node 26 rerun is still pending. No review threads exist on #5993.

[Sean Larkin (TheLarkInn)]

Combined deep review of current head 2b8d8e5ede.

1. HIGH bootstrap events classify full argv and cwd as public. Omit them or use non-public classified values.
2. HIGH the old-engine adapter writes captured stdout back to stderr. Restore each stream to itself.
3. MEDIUM npm install output is captured but not shown live, so long installs appear frozen. Tee while capturing.
4. MEDIUM bootstrap reporter parsing repeats the pass-through -- bug. Stop scanning at the separator.
5. MEDIUM rush.json discovery and version resolution occur outside the friendly error handler, producing raw stack traces. Move them inside the guarded path.

[Sean Larkin (TheLarkInn)]

Fixed all five bootstrap review findings in c1e13cd.

• Removed argv and cwd from public bootstrap events and sanitized reporter-mode invocation output.
• Preserved stdout and stderr separation for old engines, including async output, cleanup, machine-readable stdout, and hard-exit delivery.
• Teed npm output live to the correct streams while retaining ordered handoff records without duplicate visible replay.
• Stopped reporter control parsing at standalone -- and preserved pass-through arguments.
• Moved rush.json discovery and Rush version resolution into the friendly guarded error path.

Validation: deterministic bootstrap generation; reporter build and 299 tests; rush-lib build and 774 tests; Rush frontend build and 62 tests; rush check; stacked rush change --verify; slice-only diff. Rebased the three R6 commits directly onto 62d9e7a. Auto-merge remains disabled. Ready for review.