Reporter overhaul (5/6): Heft protocol track (negotiated child descriptors) (#5869)

* Add Heft child descriptor integration with raw fallback

Integrate Heft as a cross-process reporter producer for @rushstack/reporter (#5858).

- Add allocateChildDescriptor and readChildDescriptorFd so Rush passes a
  dynamically allocated inherited descriptor to the child through a private
  environment variable while stdout and stderr stay normal streams
- Add HeftChildEmitter, which emits structured NDJSON over the descriptor or
  falls back to raw stdout and stderr when negotiation is unavailable
- Add HeftDescriptorHost, which negotiates the child hello and correlates each
  child event with the parent session and operation ids, surfacing an
  update-global-Rush diagnostic on rejection
- Keep the raw-stream and problem-matcher path for older Heft versions
- Cover both the new descriptor and old raw-stream paths with tests

Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3

* Add rush change file for Heft descriptor integration

Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3

* Add a streaming parent drain for the Heft descriptor channel

HeftDescriptorHost gains incremental record processing (processChildRecord)
and createStreamProcessor(), which decodes NDJSON chunks as they arrive and
forwards accepted events in receipt order. This continuously drains the child
pipe (a chatty child no longer blocks on a full OS pipe buffer) and surfaces
child progress live, per the design-review realignment. The batch
processChildNdjson path is retained for completed streams and tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Harden Heft reporter descriptor protocol

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address Heft descriptor review feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48b21772-7262-40a9-9524-c2b21582d201

* Fix Heft reporter change file package name

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48b21772-7262-40a9-9524-c2b21582d201

* Document Heft child output streams

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48b21772-7262-40a9-9524-c2b21582d201

---------

Co-authored-by: Sean Larkin <TheLarkInn@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3
Copilot-Session: 48b21772-7262-40a9-9524-c2b21582d201

Author: TheLarkInn

common/changes/@rushstack/rush-reporter/docs-rush-reporter-overhaul-spec_2026-07-15-01-49-01.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/rush-reporter",
+      "comment": "Add Heft integration over a negotiated inherited descriptor: HeftChildEmitter and HeftDescriptorHost with parent/child event correlation, a raw-stream fallback for older Heft, and descriptor allocation helpers",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/rush-reporter",
+  "email": "TheLarkInn@users.noreply.github.com"
+}

common/reviews/api/rush-reporter.api.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+import type { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
 // @beta
 export class AiReporter implements IReporter {
     constructor(options: IAiReporterOptions);
@@ -19,6 +22,9 @@ export class AiReporter implements IReporter {
     report(event: IReporterEventEnvelope<unknown>): void;
 }
 
+// @beta
+export function allocateChildDescriptor(fdNumber?: number): IChildDescriptorPlan;
+
 // @beta
 export const ALREADY_REPORTED_ERROR_NAME: 'AlreadyReportedError';
 
@@ -167,6 +173,30 @@ export function getPrivacyClassificationRank(classification: ReporterPrivacyClas
 // @beta
 export function getSignalExitCode(signal: NodeJS.Signals): number;
 
+// @beta
+export class HeftChildEmitter {
+    constructor(options: IHeftChildEmitterOptions);
+    emitEvent(input: IHeftChildEventInput): string | undefined;
+    readonly mode: HeftChildReporterMode;
+    sendHello(): boolean;
+    writeRaw(stream: 'stdout' | 'stderr', text: string): void;
+}
+
+// @beta
+export type HeftChildReporterMode = 'structured' | 'raw-fallback';
+
+// @beta
+export class HeftDescriptorHost {
+    constructor(options: IHeftDescriptorHostOptions);
+    createStreamProcessor(): {
+        write(chunk: string): void;
+        flush(): IHeftChildResult;
+    };
+    processChildNdjson(ndjson: string): IHeftChildResult;
+    processChildRecord(record: unknown): boolean;
+    processChildRecords(records: readonly unknown[]): IHeftChildResult;
+}
+
 // @beta
 export interface IAiDiagnostic {
     // (undocumented)
@@ -297,6 +327,13 @@ export interface IBootstrapTruncation {
     readonly truncated: boolean;
 }
 
+// @beta
+export interface IChildDescriptorPlan {
+    readonly env: Record<string, string>;
+    readonly fdNumber: number;
+    readonly stdio: (string | number)[];
+}
+
 // @beta
 export interface IClassifiedDiagnosticValue {
     readonly privacy: ReporterPrivacyClassification;
@@ -418,6 +455,63 @@ export interface IGetMatchersOptions {
     readonly version?: string;
 }
 
+// @beta
+export interface IHeftChildEmitterOptions {
+    readonly capabilities?: readonly string[];
+    readonly childSessionId: string;
+    readonly env: Record<string, string | undefined>;
+    readonly now?: () => string;
+    readonly producerVersion: string;
+    readonly protocolVersion?: IReporterProtocolVersion;
+    readonly requiredFeatures?: readonly string[];
+    readonly source: IReporterEventSource;
+    readonly writeDescriptor?: (text: string) => void;
+    readonly writeStderr?: (text: string) => void;
+    readonly writeStdout?: (text: string) => void;
+}
+
+// @beta
+export interface IHeftChildEventInput {
+    // (undocumented)
+    readonly payload?: unknown;
+    // (undocumented)
+    readonly privacy?: 'public' | 'local-sensitive' | 'secret';
+    // (undocumented)
+    readonly scope?: IReporterEventScope;
+    // (undocumented)
+    readonly type: ReporterEventType;
+}
+
+// @beta
+export interface IHeftChildOutputStreams {
+    readonly stderr: Readable | null;
+    readonly stdout: Readable | null;
+}
+
+// @beta
+export interface IHeftChildOutputTargets {
+    readonly stderr: Writable;
+    readonly stdout: Writable;
+}
+
+// @beta
+export interface IHeftChildResult {
+    readonly accepted: boolean;
+    readonly ack?: IReporterHelloAck;
+    readonly diagnostic?: IRushDiagnostic;
+    readonly eventCount: number;
+}
+
+// @beta
+export interface IHeftDescriptorHostOptions {
+    readonly forwardEnvelope: (envelope: IReporterEventEnvelope<unknown>) => void;
+    readonly onNegotiation?: (result: IReporterHandshakeResult) => void;
+    readonly parentOperationId?: string;
+    readonly parentSessionId: string;
+    readonly supportedCapabilities?: readonly string[];
+    readonly supportedProtocolVersion: IReporterProtocolVersion;
+}
+
 // @beta
 export interface IInteractiveTerminal {
     readonly columns: number;
@@ -1131,9 +1225,15 @@ export function readBootstrapHandoffFileAsync(filePath: string): Promise<{
     discardedRecordCount: number;
 }>;
 
+// @beta
+export function readChildDescriptorFd(env: Record<string, string | undefined>): number | undefined;
+
 // @beta
 export function regroupOperationOutput(events: readonly IReporterEventEnvelope<unknown>[]): Map<string, string>;
 
+// @beta
+export function relayHeftChildOutput(child: IHeftChildOutputStreams, targets?: IHeftChildOutputTargets): void;
+
 // @beta
 export function renderActiveProjectsRow(projects: readonly string[], width: number): string;
 
@@ -1285,6 +1385,12 @@ export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS: readonly [{
     readonly defaultSeverity: "error";
     readonly summaryKey: "diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.summary";
     readonly detailKey: "diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.detail";
+}, {
+    readonly code: "RUSH_PROTOCOL_INVALID_CHILD_STREAM";
+    readonly category: "environment";
+    readonly defaultSeverity: "error";
+    readonly summaryKey: "diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.summary";
+    readonly detailKey: "diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.detail";
 }, {
     readonly code: "RUSH_INTERNAL_UNEXPECTED";
     readonly category: "internal";
@@ -1326,6 +1432,9 @@ export const RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_
 // @beta
 export const RUSH_REPORTER_BOOTSTRAP_NONCE_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_NONCE';
 
+// @beta
+export const RUSH_REPORTER_CHILD_FD_ENV_VAR: '_RUSH_REPORTER_CHILD_FD';
+
 // @beta
 export const RUSH_REPORTER_ENV_VAR: 'RUSH_REPORTER';
 

libraries/reporter/src/diagnostics/RushDiagnosticCodeRegistry.ts

@@ -206,6 +206,13 @@ export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS = defineRushDiagnosticCodeDefiniti
     summaryKey: 'diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.summary',
     detailKey: 'diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.detail'
   },
+  {
+    code: 'RUSH_PROTOCOL_INVALID_CHILD_STREAM',
+    category: 'environment',
+    defaultSeverity: 'error',
+    summaryKey: 'diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.summary',
+    detailKey: 'diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.detail'
+  },
   {
     code: RUSH_INTERNAL_ERROR_CODE,
     category: 'internal',

libraries/reporter/src/diagnostics/templates/environment.ts

@@ -15,5 +15,8 @@ export const ENVIRONMENT_DIAGNOSTIC_TEMPLATES = {
   'diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.summary':
     'A reporter protocol feature required by {producerVersion} is not supported by this Rush.',
   'diagnostic.RUSH_PROTOCOL_UPDATE_REQUIRED.detail':
-    'The producer advertised protocol major {producerProtocolMajor}. Update your global Rush installation to a version that supports it.'
+    'The producer advertised protocol major {producerProtocolMajor}. Update your global Rush installation to a version that supports it.',
+  'diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.summary':
+    'A child process sent an invalid reporter protocol stream.',
+  'diagnostic.RUSH_PROTOCOL_INVALID_CHILD_STREAM.detail': 'The child reporter stream was rejected because {reason}.'
 } as const;