@rushstack/rush-sdk 5.169.3 → 5.170.1-pr5378.0

package/dist/rush-lib.d.ts

@@ -31,6 +31,7 @@ import type { StdioSummarizer } from '@rushstack/terminal';
 import { SyncHook } from 'tapable';
 import { SyncWaterfallHook } from 'tapable';
 import { Terminal } from '@rushstack/terminal';
+import type { TerminalWritable } from '@rushstack/terminal';
 
 /**
  * This represents the JSON file specified via the "approvedPackagesFile" option in rush.json.
@@ -537,6 +538,7 @@ export declare class EnvironmentConfiguration {
     private static _cobuildLeafProjectLogOnlyAllowed;
     private static _gitBinaryPath;
     private static _tarBinaryPath;
+    private static _quietMode;
     /**
      * If true, the environment configuration has been validated and initialized.
      */
@@ -629,6 +631,11 @@ export declare class EnvironmentConfiguration {
      * See {@link EnvironmentVariableNames.RUSH_TAR_BINARY_PATH}
      */
     static get tarBinaryPath(): string | undefined;
+    /**
+     * If `true`, Rush will suppress informational startup messages, equivalent to passing `--quiet`.
+     * See {@link EnvironmentVariableNames.RUSH_QUIET_MODE}
+     */
+    static get quietMode(): boolean;
     /**
      * The front-end RushVersionSelector relies on `RUSH_GLOBAL_FOLDER`, so its value must be read before
      * `EnvironmentConfiguration` is initialized (and actually before the correct version of `EnvironmentConfiguration`
@@ -867,10 +874,16 @@ export declare const EnvironmentVariableNames: {
      * if Rush did not explicitly pass along command-line parameters to their process.
      */
     readonly RUSH_INVOKED_ARGS: "RUSH_INVOKED_ARGS";
+    /**
+     * When set to `1` or `true`, this environment variable is equivalent to passing the `--quiet` flag
+     * to `rush`, `rushx`, and `install-run-rush.ts`. It suppresses informational startup messages
+     * while preserving error output.
+     */
+    readonly RUSH_QUIET_MODE: "RUSH_QUIET_MODE";
 };
 
 /**
- * Events happen during Rush runs.
+ * Events happen during Rush invocation.
  * @beta
  */
 declare enum Event_2 {
@@ -1042,6 +1055,31 @@ declare interface IBaseBuildCacheJson {
     cacheHashSalt?: string;
 }
 
+/**
+ * @alpha
+ */
+export declare interface IBaseOperationExecutionResult {
+    /**
+     * The operation itself
+     */
+    readonly operation: Operation;
+    /**
+     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
+     */
+    readonly metadataFolderPath: string;
+    /**
+     * Gets the hash of the state of all registered inputs to this operation.
+     * Calling this method will throw if Git is not available.
+     */
+    getStateHash(): string;
+    /**
+     * Gets the structured components of the state hash. This is useful for debugging and
+     * incremental change detection.
+     * Calling this method will throw if Git is not available.
+     */
+    getStateHashComponents(): IOperationStateHashComponents;
+}
+
 /**
  * @beta
  */
@@ -1182,6 +1220,18 @@ export declare interface ICobuildLockProvider {
     getCompletedStateAsync(context: Readonly<ICobuildContext>): Promise<ICobuildCompletedState | undefined>;
 }
 
+/**
+ * The `IConfigurableOperation` interface represents an {@link Operation} whose
+ * execution can be configured before running.
+ * @alpha
+ */
+export declare interface IConfigurableOperation extends IBaseOperationExecutionResult {
+    /**
+     * True if the operation should execute in this iteration, false otherwise.
+     */
+    enabled: boolean;
+}
+
 /**
  * A collection of environment variables
  * @public
@@ -1234,16 +1284,15 @@ export declare interface ICreateOperationsContext {
      * Maps from the `longName` field in command-line.json to the parser configuration in ts-command-line.
      */
     readonly customParameters: ReadonlyMap<string, CommandLineParameter>;
+    /**
+     * If true, dependencies of the selected phases will be automatically enabled in the execution.
+     */
+    readonly includePhaseDeps: boolean;
     /**
      * If true, projects may read their output from cache or be skipped if already up to date.
      * If false, neither of the above may occur, e.g. "rush rebuild"
      */
     readonly isIncrementalBuildAllowed: boolean;
-    /**
-     * If true, this is the initial run of the command.
-     * If false, this execution is in response to changes.
-     */
-    readonly isInitial: boolean;
     /**
      * If true, the command is running in watch mode.
      */
@@ -1251,45 +1300,28 @@ export declare interface ICreateOperationsContext {
     /**
      * The currently configured maximum parallelism for the command.
      */
-    readonly parallelism: number;
+    readonly parallelism: Parallelism;
     /**
-     * The set of phases original for the current command execution.
-     */
-    readonly phaseOriginal: ReadonlySet<IPhase>;
-    /**
-     * The set of phases selected for the current command execution.
+     * The set of phases selected for execution.
      */
     readonly phaseSelection: ReadonlySet<IPhase>;
-    /**
-     * The set of Rush projects selected for the current command execution.
-     */
-    readonly projectSelection: ReadonlySet<RushConfigurationProject>;
     /**
      * All successfully loaded rush-project.json data for selected projects.
      */
     readonly projectConfigurations: ReadonlyMap<RushConfigurationProject, RushProjectConfiguration>;
     /**
-     * The set of Rush projects that have not been built in the current process since they were last modified.
-     * When `isInitial` is true, this will be an exact match of `projectSelection`.
+     * The set of Rush projects selected for execution.
      */
-    readonly projectsInUnknownState: ReadonlySet<RushConfigurationProject>;
+    readonly projectSelection: ReadonlySet<RushConfigurationProject>;
     /**
-     * The Rush configuration
+     * If true, the operation graph should include all projects in the repository (watch broad graph mode).
+     * Only the projects in projectSelection should start enabled; others are present but disabled.
      */
-    readonly rushConfiguration: RushConfiguration;
+    readonly generateFullGraph?: boolean;
     /**
-     * If true, Rush will automatically include the dependent phases for the specified set of phases.
-     * @remarks
-     * If the selection of projects was "unsafe" (i.e. missing some dependencies), this will add the
-     * minimum number of phases required to make it safe.
-     */
-    readonly includePhaseDeps: boolean;
-    /**
-     * Marks an operation's result as invalid, potentially triggering a new build. Only applicable in watch mode.
-     * @param operation - The operation to invalidate
-     * @param reason - The reason for invalidating the operation
+     * The Rush configuration
      */
-    readonly invalidateOperation?: ((operation: Operation, reason: string) => void) | undefined;
+    readonly rushConfiguration: RushConfiguration;
 }
 
 export { ICredentialCacheEntry }
@@ -1387,22 +1419,6 @@ declare interface IEventHooksJson {
     postRushBuild?: string[];
 }
 
-/**
- * Context used for executing operations.
- * @alpha
- */
-export declare interface IExecuteOperationsContext extends ICreateOperationsContext {
-    /**
-     * The current state of the repository, if available.
-     * Not part of the creation context to avoid the overhead of Git calls when initializing the graph.
-     */
-    readonly inputsSnapshot?: IInputsSnapshot;
-    /**
-     * An abort controller that can be used to abort the current set of queued operations.
-     */
-    readonly abortController: AbortController;
-}
-
 /**
  * The `IExecutionResult` interface represents the results of executing a set of {@link Operation}s.
  * @alpha
@@ -1820,11 +1836,7 @@ export declare interface _IOperationBuildCacheOptions {
  * The `IOperationExecutionResult` interface represents the results of executing an {@link Operation}.
  * @alpha
  */
-export declare interface IOperationExecutionResult {
-    /**
-     * The operation itself
-     */
-    readonly operation: Operation;
+export declare interface IOperationExecutionResult extends IBaseOperationExecutionResult, IOperationLastState {
     /**
      * The current execution status of an operation. Operations start in the 'ready' state,
      * but can be 'blocked' if an upstream operation failed. It is 'executing' when
@@ -1841,6 +1853,10 @@ export declare interface IOperationExecutionResult {
      * If this operation is only present in the graph to maintain dependency relationships, this flag will be set to true.
      */
     readonly silent: boolean;
+    /**
+     * True if the operation should execute in this iteration, false otherwise.
+     */
+    readonly enabled: boolean;
     /**
      * Object tracking execution timing.
      */
@@ -1857,24 +1873,165 @@ export declare interface IOperationExecutionResult {
      * The value indicates the duration of the same operation without cache hit.
      */
     readonly nonCachedDurationMs: number | undefined;
-    /**
-     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
-     */
-    readonly metadataFolderPath: string | undefined;
     /**
      * The paths to the log files, if applicable.
      */
     readonly logFilePaths: ILogFilePaths | undefined;
+}
+
+/**
+ * Public API for the operation graph.
+ * @alpha
+ */
+export declare interface IOperationGraph {
     /**
-     * Gets the hash of the state of all registered inputs to this operation.
-     * Calling this method will throw if Git is not available.
+     * Hooks into the execution process for operations
      */
-    getStateHash(): string;
+    readonly hooks: OperationGraphHooks;
     /**
-     * Gets the components of the state hash. This is useful for debugging purposes.
-     * Calling this method will throw if Git is not available.
+     * The set of operations in the graph.
+     */
+    readonly operations: ReadonlySet<Operation>;
+    /**
+     * A map from each `Operation` in the graph to its current result record.
+     * The map is updated in real time as operations execute during an iteration.
+     * Only statuses representing a completed execution (e.g. `Success`, `Failure`,
+     * `SuccessWithWarning`) write to this map; statuses such as `Skipped` or `Aborted` —
+     * which indicate that an operation did not actually run — do not update it.
+     * For operations that have not yet run in the current iteration, the map retains the
+     * result from whichever prior iteration the operation last ran in.
+     * An entry with status `Ready` indicates that the operation is considered stale and
+     * has been queued to run again.
+     * Empty until at least one operation has completed execution.
+     */
+    readonly resultByOperation: ReadonlyMap<Operation, IOperationExecutionResult>;
+    /**
+     * The maximum allowed parallelism for this operation graph.
+     * Reads as a concrete integer. Accepts a `Parallelism` value and coerces it on write.
+     */
+    get parallelism(): number;
+    set parallelism(value: Parallelism);
+    /**
+     * If additional debug information should be printed during execution.
+     */
+    debugMode: boolean;
+    /**
+     * If true, operations will be executed in "quiet mode" where only errors are reported.
+     */
+    quietMode: boolean;
+    /**
+     * If true, allow operations to oversubscribe the CPU. Defaults to true.
+     */
+    allowOversubscription: boolean;
+    /**
+     * When true, the operation graph will pause before running the next iteration (manual mode).
+     * When false, iterations run automatically when scheduled.
+     */
+    pauseNextIteration: boolean;
+    /**
+     * The current overall status of the execution.
+     */
+    readonly status: OperationStatus;
+    /**
+     * The current set of terminal destinations.
+     */
+    readonly terminalDestinations: ReadonlySet<TerminalWritable>;
+    /**
+     * True if there is a scheduled (but not yet executing) iteration.
+     * This will be false while an iteration is actively executing, or when no work is scheduled.
+     */
+    readonly hasScheduledIteration: boolean;
+    /**
+     * AbortController controlling the lifetime of the overall session (e.g. watch mode).
+     * Aborting this controller should signal all listeners (such as file system watchers) to dispose
+     * and prevent further iterations from being scheduled.
+     */
+    readonly abortController: AbortController;
+    /**
+     * Abort the current execution iteration, if any. Operations that have already started
+     * will run to completion; only operations that have not yet begun will be aborted.
+     */
+    abortCurrentIterationAsync(): Promise<void>;
+    /**
+     * Cleans up any resources used by the operation runners, if applicable.
+     * @param operations - The operations whose runners should be closed, or undefined to close all runners.
+     */
+    closeRunnersAsync(operations?: Iterable<Operation>): Promise<void>;
+    /**
+     * Executes a single iteration of the operations.
+     * @param options - Options for this execution iteration.
+     * @returns A promise that resolves to true if the iteration has work to be done, or false if the iteration was empty and therefore not scheduled.
+     */
+    scheduleIterationAsync(options: IOperationGraphIterationOptions): Promise<boolean>;
+    /**
+     * Executes all operations in the currently scheduled iteration, if any.
+     * @returns A promise which is resolved when all operations have been processed to a final state.
+     */
+    executeScheduledIterationAsync(): Promise<boolean>;
+    /**
+     * Invalidates the specified operations, causing them to be re-executed.
+     * @param operations - The operations to invalidate, or undefined to invalidate all operations.
+     * @param reason - Optional reason for invalidation.
+     */
+    invalidateOperations(operations?: Iterable<Operation>, reason?: string): void;
+    /**
+     * Sets the enabled state for a collection of operations.
+     *
+     * @param operations - The operations whose enabled state should be updated.
+     * @param targetState - The target enabled state to apply.
+     * @param mode - 'unsafe' to directly mutate only the provided operations, 'safe' to also enable
+     * transitive dependencies of enabled operations and disable transitive dependents of disabled operations.
+     * @returns true if any operation's enabled state changed, false otherwise.
+     */
+    setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
+    /**
+     * Adds a terminal destination for output. Only new output will be sent to the destination.
+     * @param destination - The destination to add.
+     */
+    addTerminalDestination(destination: TerminalWritable): void;
+    /**
+     * Removes a terminal destination for output. Optionally closes the stream.
+     * New output will no longer be sent to the destination.
+     * @param destination - The destination to remove.
+     * @param close - Whether to close the stream. Defaults to `true`.
+     */
+    removeTerminalDestination(destination: TerminalWritable, close?: boolean): boolean;
+}
+
+/**
+ * Context used for configuring the operation graph.
+ * @alpha
+ */
+export declare interface IOperationGraphContext extends ICreateOperationsContext {
+    /**
+     * The current state of the repository, if available.
+     * Not part of the creation context to avoid the overhead of Git calls when initializing the graph.
+     */
+    readonly initialSnapshot?: IInputsSnapshot;
+}
+
+/**
+ * Options for a single iteration of operation execution.
+ * @alpha
+ */
+export declare interface IOperationGraphIterationOptions {
+    inputsSnapshot?: IInputsSnapshot;
+    /**
+     * The time when the iteration was scheduled, if available, as returned by `performance.now()`.
+     */
+    startTime?: number;
+}
+
+/**
+ * A snapshot of a previous operation execution, passed to runners to inform incremental behavior.
+ *
+ * @beta
+ */
+export declare interface IOperationLastState {
+    /**
+     * The status from the previous execution of this operation.
      */
-    getStateHashComponents(): ReadonlyArray<string>;
+    readonly status: OperationStatus;
 }
 
 /**
@@ -1909,6 +2066,18 @@ export declare interface IOperationOptions {
      * The Rush project associated with this Operation
      */
     project: RushConfigurationProject;
+    /**
+     * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
+     * This is useful for plugins to alter the scope of the operation graph across executions,
+     * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
+     *
+     * The special value "ignore-dependency-changes" can be used to indicate that this operation should only
+     * be executed if there are local changes in the project. This is useful for operations like
+     * "test" where you may want to skip testing projects that haven't changed.
+     *
+     * The default value is `true`, meaning the operation will be executed if it or any dependencies change.
+     */
+    enabled?: OperationEnabledState;
     /**
      * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
      * running the operation.
@@ -1926,7 +2095,7 @@ export declare interface IOperationOptions {
 
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
- * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * `OperationGraph`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
  * implementation manages the actual process for running a single operation.
  *
  * @beta
@@ -1958,14 +2127,27 @@ export declare interface IOperationRunner {
      * analysis purposes.
      */
     readonly isNoOp?: boolean;
+    /**
+     * If true, this runner currently owns some kind of active resource (e.g. a service or a watch process).
+     * This can be used to determine if the operation is "in progress" even if it is not currently executing.
+     * If the runner supports this property, it should update it as appropriate during execution.
+     * The property is optional to avoid breaking existing implementations of IOperationRunner.
+     */
+    readonly isActive?: boolean;
     /**
      * Method to be executed for the operation.
+     * @param context - The context object containing information about the execution environment.
+     * @param lastState - The last execution result of this operation, if any.
      */
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    executeAsync(context: IOperationRunnerContext, lastState?: IOperationLastState): Promise<OperationStatus>;
     /**
      * Return a hash of the configuration that affects the operation.
      */
     getConfigHash(): string;
+    /**
+     * If this runner performs any background work to optimize future runs, this method will clean it up.
+     */
+    closeAsync?(): Promise<void>;
 }
 
 /**
@@ -2013,6 +2195,12 @@ export declare interface IOperationRunnerContext {
      * it later (for example to re-print errors at end of execution).
      */
     error?: Error;
+    /**
+     * Returns a callback that invalidates this operation so that it will be re-executed in the next iteration.
+     * The returned callback captures only the minimal state needed, avoiding retention of the full context.
+     * Callers should store the result rather than calling this method repeatedly.
+     */
+    getInvalidateCallback(): (reason: string) => void;
     /**
      * Invokes the specified callback with a terminal that is associated with this operation.
      *
@@ -2094,7 +2282,7 @@ export declare interface IOperationSettings {
      * How many concurrency units this operation should take up during execution. The maximum concurrent units is
      *  determined by the -p flag.
      */
-    weight?: number;
+    weight?: number | `${number}%`;
     /**
      * If true, this operation can use cobuilds for orchestration without restoring build cache entries.
      */
@@ -2120,6 +2308,26 @@ export declare interface _IOperationStateFileOptions {
     metadataFolder: string;
 }
 
+/**
+ * Structured components of the state hash for an operation.
+ * @alpha
+ */
+export declare interface IOperationStateHashComponents {
+    /**
+     * The state hashes of operation dependencies, sorted by name.
+     * Each entry is of the form `{dependencyName}={hash}`.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * The hash of the operation's own local inputs (e.g. tracked files, environment variables).
+     */
+    readonly local: string;
+    /**
+     * The hash of the operation's configuration (e.g. CLI parameters).
+     */
+    readonly config: string;
+}
+
 /**
  * @internal
  */
@@ -2140,6 +2348,14 @@ export declare interface IPackageManagerOptionsJsonBase {
     environmentVariables?: IConfigurationEnvironment;
 }
 
+/**
+ * A parallelism value expressed as a fraction of total available concurrency slots.
+ * @beta
+ */
+export declare interface IParallelismScalar {
+    readonly scalar: number;
+}
+
 /**
  * Metadata about a phase.
  * @alpha
@@ -2215,6 +2431,17 @@ export declare interface IPhasedCommand extends IRushCommand {
     readonly sessionAbortController: AbortController;
 }
 
+/**
+ * A plugin that interacts with a phased commands.
+ * @alpha
+ */
+export declare interface IPhasedCommandPlugin {
+    /**
+     * Applies this plugin.
+     */
+    apply(hooks: PhasedCommandHooks): void;
+}
+
 /**
  * Possible values for the `pnpmLockfilePolicies` setting in Rush's pnpm-config.json file.
  * @public
@@ -2942,7 +3169,7 @@ export declare class NpmOptionsConfiguration extends PackageManagerOptionsConfig
 
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
- * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * `OperationGraph`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
  * implementation manages the actual process of running a single operation.
  *
  * The graph of `Operation` instances will be cloned into a separate execution graph after processing.
@@ -2978,17 +3205,23 @@ export declare class Operation {
      */
     runner: IOperationRunner | undefined;
     /**
-     * The weight for this operation. This scalar is the contribution of this operation to the
-     * `criticalPathLength` calculation above. Modify to indicate the following:
-     * - `weight` === 1: indicates that this operation has an average duration
-     * - `weight` &gt; 1: indicates that this operation takes longer than average and so the scheduler
-     *     should try to favor starting it over other, shorter operations. An example might be an operation that
-     *     bundles an entire application and runs whole-program optimization.
-     * - `weight` &lt; 1: indicates that this operation takes less time than average and so the scheduler
-     *     should favor other, longer operations over it. An example might be an operation to unpack a cached
-     *     output, or an operation using NullOperationRunner, which might use a value of 0.
+     * The concurrency weight for this operation. When coerced to an integer via `coerceParallelism`,
+     * this value represents how many concurrency slots the operation consumes while running.
+     *
+     * May be specified as:
+     * - A raw `number`: used directly as the slot count (e.g. `2` consumes two slots).
+     * - An `IParallelismScalar` (e.g. `{ scalar: 0.5 }`): coerced relative to the graph's
+     *   configured `maxParallelism` at execution time, so the weight scales with the available
+     *   concurrency rather than being fixed at parse time.
+     *
+     * Coerced values guide scheduling as follows:
+     * - `1` slot: typical operation consuming one logical thread.
+     * - `> 1` slots: operation that spawns multiple threads or requires significant RAM; reserving
+     *   extra slots prevents overloading the machine (e.g. a whole-program bundler or a test suite
+     *   that runs its own internal parallelism).
+     * - `0` slots: effectively free (e.g. a no-op or cache-restore step).
      */
-    weight: number;
+    weight: Parallelism;
     /**
      * Get the operation settings for this operation, defaults to the values defined in
      *  the project configuration.
@@ -2998,8 +3231,14 @@ export declare class Operation {
      * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
      * This is useful for plugins to alter the scope of the operation graph across executions,
      * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
+     *
+     * The special value "ignore-dependency-changes" can be used to indicate that this operation should only
+     * be executed if there are local changes in the project. This is useful for operations like
+     * "test" where you may want to skip testing projects that haven't changed.
+     *
+     * The default value is `true`, meaning the operation will be executed if it or any dependencies change.
      */
-    enabled: boolean;
+    enabled: OperationEnabledState;
     constructor(options: IOperationOptions);
     /**
      * The name of this operation, for logging.
@@ -3036,7 +3275,7 @@ export declare class _OperationBuildCache {
     private static _tryGetTarUtility;
     get cacheId(): string | undefined;
     static getOperationBuildCache(options: _IProjectBuildCacheOptions): _OperationBuildCache;
-    static forOperation(executionResult: IOperationExecutionResult, options: _IOperationBuildCacheOptions): _OperationBuildCache;
+    static forOperation(executionResult: IBaseOperationExecutionResult, options: _IOperationBuildCacheOptions): _OperationBuildCache;
     tryRestoreFromCacheAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     /**
@@ -3049,6 +3288,139 @@ export declare class _OperationBuildCache {
     private static _getCacheId;
 }
 
+/**
+ * State for the `enabled` property of an `Operation`.
+ *
+ * - `true`: The operation should be executed if it or any dependencies changed.
+ * - `false`: The operation should be skipped.
+ * - `"ignore-dependency-changes"`: The operation should be executed if there are local changes in the project,
+ *   otherwise it should be skipped. This is useful for operations like "test" where you may want to skip
+ *   testing projects that haven't changed.
+ * @alpha
+ */
+export declare type OperationEnabledState = boolean | 'ignore-dependency-changes';
+
+/**
+ * Hooks into the execution process for operations within the graph.
+ *
+ * Per-iteration lifecycle:
+ * 1. `configureIteration` - Synchronously decide which operations to enable for the next iteration.
+ * 2. `onIterationScheduled` - Fires after the iteration is prepared but before execution begins, if it has any enabled operations.
+ * 3. `beforeExecuteIterationAsync` - Async hook that can bail out the iteration entirely.
+ * 4. Operations execute (status changes reported via `onExecutionStatesUpdated`).
+ * 5. `afterExecuteIterationAsync` - Fires after all operations in the iteration have settled.
+ * 6. `onIdle` - Fires when the graph enters idle state awaiting changes (watch mode only).
+ *
+ * Additional hooks:
+ * - `onEnableStatesChanged` - Fires when `setEnabledStates` mutates operation enabled flags.
+ * - `onInvalidateOperations` - Fires when operations are invalidated (e.g. by file watchers).
+ * - `onGraphStateChanged` - Fires on any observable graph state change.
+ *
+ * @alpha
+ */
+export declare class OperationGraphHooks {
+    /**
+     * Hook invoked to decide what work a potential new iteration contains.
+     * Use the `lastExecutedRecords` to determine which operations are new or have had their inputs changed.
+     * Set the `enabled` states on the values in `initialRecords` to control which operations will be executed.
+     *
+     * @remarks
+     * This hook is synchronous to guarantee that the `lastExecutedRecords` map remains stable for the
+     * duration of configuration. This hook often executes while an execution iteration is currently running, so
+     * operations could complete if there were async ticks during the configuration phase.
+     *
+     * If no operations are marked for execution, the iteration will not be scheduled.
+     * If there is an existing scheduled iteration, it will remain.
+     */
+    readonly configureIteration: SyncHook<[
+    ReadonlyMap<Operation, IConfigurableOperation>,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ]>;
+    /**
+     * Hook invoked before operation start for an iteration. Allows a plugin to perform side-effects or
+     * short-circuit the entire iteration.
+     *
+     * If any tap returns an {@link OperationStatus}, the remaining taps are skipped and the iteration will
+     * end immediately with that status. All operations which have not yet executed will be marked
+     * Aborted.
+     */
+    readonly beforeExecuteIterationAsync: AsyncSeriesBailHook<[
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ], OperationStatus | undefined | void>;
+    /**
+     * Batched hook invoked when one or more operation statuses have changed during the same microtask.
+     * The hook receives an array of the operation execution results that changed status.
+     * @remarks
+     * This hook is batched to reduce noise when updating many operations synchronously in quick succession.
+     */
+    readonly onExecutionStatesUpdated: SyncHook<[ReadonlySet<IOperationExecutionResult>]>;
+    /**
+     * Hook invoked when one or more operations have their enabled state mutated via
+     * {@link IOperationGraph.setEnabledStates}. Provides the set of operations whose
+     * enabled state actually changed.
+     */
+    readonly onEnableStatesChanged: SyncHook<[ReadonlySet<Operation>]>;
+    /**
+     * Hook invoked immediately after a new execution iteration is scheduled (i.e. operations selected and prepared),
+     * before any operations in that iteration have started executing. Can be used to snapshot planned work,
+     * drive UIs, or pre-compute auxiliary data.
+     */
+    readonly onIterationScheduled: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
+    /**
+     * Hook invoked when any observable state on the operation graph changes.
+     * This includes configuration mutations (parallelism, quiet/debug modes, pauseNextIteration)
+     * as well as dynamic state (status transitions, scheduled iteration availability, etc.).
+     * Hook is series for stable output.
+     */
+    readonly onGraphStateChanged: SyncHook<[IOperationGraph]>;
+    /**
+     * Hook invoked when operations are invalidated for any reason.
+     */
+    readonly onInvalidateOperations: SyncHook<[Iterable<Operation>, string | undefined]>;
+    /**
+     * Hook invoked after an iteration has finished and the command is watching for changes.
+     * May be used to display additional relevant data to the user.
+     * Only relevant when running in watch mode.
+     */
+    readonly onIdle: SyncHook<void>;
+    /**
+     * Hook invoked after executing a set of operations.
+     * Hook is series for stable output.
+     */
+    readonly afterExecuteIterationAsync: AsyncSeriesWaterfallHook<[
+    OperationStatus,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ]>;
+    /**
+     * Hook invoked after executing an iteration, before the telemetry entry is written.
+     * Allows the caller to augment or modify the log entry.
+     */
+    readonly beforeLog: SyncHook<ITelemetryData, void>;
+    /**
+     * Hook invoked before executing a operation.
+     */
+    readonly beforeExecuteOperationAsync: AsyncSeriesBailHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ], OperationStatus | undefined>;
+    /**
+     * Hook invoked to define environment variables for an operation.
+     * May be invoked by the runner to get the environment for the operation.
+     */
+    readonly createEnvironmentForOperation: SyncWaterfallHook<[
+    IEnvironment,
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    /**
+     * Hook invoked after executing a operation.
+     */
+    readonly afterExecuteOperationAsync: AsyncSeriesHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+}
+
 /**
  * A helper class for managing the meta files of a operation.
  *
@@ -3293,69 +3665,34 @@ export declare abstract class PackageManagerOptionsConfigurationBase implements
 }
 
 /**
- * Hooks into the execution process for phased commands
+ * A parallelism value, either as an absolute integer count or a scalar fraction of available parallelism.
+ * @beta
+ */
+export declare type Parallelism = number | IParallelismScalar;
+
+/**
+ * Hooks into the execution process for phased commands.
+ *
+ * Lifecycle:
+ * 1. `createOperationsAsync` - Invoked to populate the set of operations for execution.
+ * 2. `onGraphCreatedAsync` - Invoked after the operation graph is created, allowing plugins to
+ *    tap into graph-level hooks (e.g. `configureIteration`, `onIdle`).
+ *    See {@link OperationGraphHooks} for the per-iteration lifecycle.
+ *
  * @alpha
  */
 export declare class PhasedCommandHooks {
     /**
      * Hook invoked to create operations for execution.
-     * Use the context to distinguish between the initial run and phased runs.
-     */
-    readonly createOperations: AsyncSeriesWaterfallHook<[Set<Operation>, ICreateOperationsContext]>;
-    /**
-     * Hook invoked before operation start
-     * Hook is series for stable output.
-     */
-    readonly beforeExecuteOperations: AsyncSeriesHook<[
-    Map<Operation, IOperationExecutionResult>,
-    IExecuteOperationsContext
-    ]>;
-    /**
-     * Hook invoked when operation status changed
-     * Hook is series for stable output.
-     */
-    readonly onOperationStatusChanged: SyncHook<[IOperationExecutionResult]>;
-    /**
-     * Hook invoked after executing a set of operations.
-     * Use the context to distinguish between the initial run and phased runs.
-     * Hook is series for stable output.
-     */
-    readonly afterExecuteOperations: AsyncSeriesHook<[IExecutionResult, IExecuteOperationsContext]>;
-    /**
-     * Hook invoked before executing a operation.
-     */
-    readonly beforeExecuteOperation: AsyncSeriesBailHook<[
-    IOperationRunnerContext & IOperationExecutionResult
-    ], OperationStatus | undefined>;
-    /**
-     * Hook invoked to define environment variables for an operation.
-     * May be invoked by the runner to get the environment for the operation.
-     */
-    readonly createEnvironmentForOperation: SyncWaterfallHook<[
-    IEnvironment,
-    IOperationRunnerContext & IOperationExecutionResult
-    ]>;
-    /**
-     * Hook invoked after executing a operation.
      */
-    readonly afterExecuteOperation: AsyncSeriesHook<[
-    IOperationRunnerContext & IOperationExecutionResult
+    readonly createOperationsAsync: AsyncSeriesWaterfallHook<[
+    Set<Operation>,
+    ICreateOperationsContext
     ]>;
     /**
-     * Hook invoked to shutdown long-lived work in plugins.
+     * Hook invoked when the operation graph is created, allowing the plugin to tap into it and interact with it.
      */
-    readonly shutdownAsync: AsyncParallelHook<void>;
-    /**
-     * Hook invoked after a run has finished and the command is watching for changes.
-     * May be used to display additional relevant data to the user.
-     * Only relevant when running in watch mode.
-     */
-    readonly waitingForChanges: SyncHook<void>;
-    /**
-     * Hook invoked after executing operations and before waitingForChanges. Allows the caller
-     * to augment or modify the log entry about to be written.
-     */
-    readonly beforeLog: SyncHook<ITelemetryData, void>;
+    readonly onGraphCreatedAsync: AsyncSeriesHook<[IOperationGraph, IOperationGraphContext]>;
 }
 
 /**