package_manager/src/ImmutablePathList.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager;
+
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
+
+/**
+ * Defines a path list that cannot be changed.
+ *
+ * @internal
+ *   This is an internal part of Package Manager and may be changed or removed
+ *   at any time without warning. External code should not interact with this
+ *   class.
+ */
+final class ImmutablePathList implements PathListInterface {
+
+  /**
+   * Constructs an ImmutablePathList object.
+   *
+   * @param \PhpTuf\ComposerStager\API\Path\Value\PathListInterface $decorated
+   *   The decorated path list.
+   */
+  public function __construct(private readonly PathListInterface $decorated) {}
+
+  /**
+   * {@inheritdoc}
+   */
+  public function add(string ...$paths): never {
+    throw new \LogicException('Immutable path lists cannot be changed.');
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getAll(): array {
+    return $this->decorated->getAll();
+  }
+
+}

package_manager/src/InstalledPackage.php

@@ -40,9 +40,12 @@ final class InstalledPackage {
    */
   public static function createFromArray(array $data): static {
     $path = isset($data['path']) ? realpath($data['path']) : NULL;
-    assert(($data['type'] === 'metapackage') === is_null($path), 'Metapackage install path must be NULL.');
+    // Fall back to `library`.
+    // @see https://getcomposer.org/doc/04-schema.md#type
+    $type = $data['type'] ?? 'library';
+    assert(($type === 'metapackage') === is_null($path), 'Metapackage install path must be NULL.');
 
-    return new static($data['name'], $data['version'], $path, $data['type']);
+    return new static($data['name'], $data['version'], $path, $type);
   }
 
   /**

package_manager/src/NoSymlinksPointToADirectory.php

@@ -6,9 +6,11 @@ namespace Drupal\package_manager;
 
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
-use PhpTuf\ComposerStager\Domain\Service\Precondition\NoSymlinksPointToADirectoryInterface;
-use PhpTuf\ComposerStager\Domain\Value\Path\PathInterface;
-use PhpTuf\ComposerStager\Domain\Value\PathList\PathListInterface;
+use PhpTuf\ComposerStager\API\Path\Value\PathInterface;
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
+use PhpTuf\ComposerStager\API\Precondition\Service\NoSymlinksPointToADirectoryInterface;
+use PhpTuf\ComposerStager\API\Process\Service\ProcessInterface;
+use PhpTuf\ComposerStager\API\Translation\Value\TranslatableInterface;
 
 /**
  * Checks if the code base contains any symlinks that point to a directory.
@@ -29,7 +31,7 @@ final class NoSymlinksPointToADirectory implements NoSymlinksPointToADirectoryIn
   /**
    * Constructs a NoSymlinksPointToADirectory object.
    *
-   * @param \PhpTuf\ComposerStager\Domain\Service\Precondition\NoSymlinksPointToADirectoryInterface $decorated
+   * @param \PhpTuf\ComposerStager\API\Precondition\Service\NoSymlinksPointToADirectoryInterface $decorated
    *   The decorated precondition.
    * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
    *   The config factory.
@@ -42,21 +44,21 @@ final class NoSymlinksPointToADirectory implements NoSymlinksPointToADirectoryIn
   /**
    * {@inheritdoc}
    */
-  public function getName(): string {
+  public function getName(): TranslatableInterface {
     return $this->decorated->getName();
   }
 
   /**
    * {@inheritdoc}
    */
-  public function getDescription(): string {
+  public function getDescription(): TranslatableInterface {
     return $this->decorated->getDescription();
   }
 
   /**
    * {@inheritdoc}
    */
-  public function getStatusMessage(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL,): string {
+  public function getStatusMessage(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL, int $timeout = ProcessInterface::DEFAULT_TIMEOUT,): TranslatableInterface {
     if ($this->isUsingRsync()) {
       return $this->t('Symlinks to directories are supported by the rsync file syncer.');
     }
@@ -66,14 +68,14 @@ final class NoSymlinksPointToADirectory implements NoSymlinksPointToADirectoryIn
   /**
    * {@inheritdoc}
    */
-  public function isFulfilled(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL,): bool {
+  public function isFulfilled(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL, int $timeout = ProcessInterface::DEFAULT_TIMEOUT,): bool {
     return $this->isUsingRsync() || $this->decorated->isFulfilled($activeDir, $stagingDir, $exclusions);
   }
 
   /**
    * {@inheritdoc}
    */
-  public function assertIsFulfilled(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL,): void {
+  public function assertIsFulfilled(PathInterface $activeDir, PathInterface $stagingDir, ?PathListInterface $exclusions = NULL, int $timeout = ProcessInterface::DEFAULT_TIMEOUT,): void {
     if ($this->isUsingRsync()) {
       return;
     }
@@ -94,4 +96,11 @@ final class NoSymlinksPointToADirectory implements NoSymlinksPointToADirectoryIn
     return $syncer === 'rsync';
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function getLeaves(): array {
+    return [$this];
+  }
+
 }

package_manager/src/PackageManagerServiceProvider.php

@@ -6,8 +6,7 @@ namespace Drupal\package_manager;
 
 use Drupal\Core\DependencyInjection\ContainerBuilder;
 use Drupal\Core\DependencyInjection\ServiceProviderBase;
-use PhpTuf\ComposerStager\Domain\Core\Beginner\BeginnerInterface;
-use PhpTuf\ComposerStager\Domain\Service\Precondition\NoSymlinksPointToADirectoryInterface;
+use PhpTuf\ComposerStager\API\Core\BeginnerInterface;
 
 /**
  * Defines dynamic container services for Package Manager.
@@ -33,13 +32,15 @@ final class PackageManagerServiceProvider extends ServiceProviderBase {
     // Use an interface that we know exists to determine the absolute path where
     // Composer Stager is installed.
     $mirror = new \ReflectionClass(BeginnerInterface::class);
-    $path = dirname($mirror->getFileName(), 4);
+    $path = dirname($mirror->getFileName(), 3);
 
     // Certain subdirectories of Composer Stager shouldn't be scanned for
     // services.
     $ignore_directories = [
-      $path . '/Domain/Exception',
-      $path . '/Infrastructure/Value',
+      $path . '/API/Exception',
+      $path . '/Internal/Helper',
+      $path . '/Internal/Path/Value',
+      $path . '/Internal/Translation/Value',
     ];
     // As we scan for services, compile a list of which classes implement which
     // interfaces so that we can set up aliases for interfaces that are only
@@ -108,6 +109,9 @@ final class PackageManagerServiceProvider extends ServiceProviderBase {
       'class_resolver' => 'Drupal\Core\DependencyInjection\ClassResolverInterface',
       'request_stack' => 'Symfony\Component\HttpFoundation\RequestStack',
       'theme_handler' => 'Drupal\Core\Extension\ThemeHandlerInterface',
+      'cron' => 'Drupal\Core\CronInterface',
+      'logger.factory' => 'Drupal\Core\Logger\LoggerChannelFactoryInterface',
+      'string_translation' => 'Drupal\Core\StringTranslation\TranslationInterface',
     ];
     foreach ($aliases as $service_id => $alias) {
       if (!$container->hasAlias($alias)) {
@@ -115,11 +119,6 @@ final class PackageManagerServiceProvider extends ServiceProviderBase {
       }
     }
     // END: DELETE FROM CORE MERGE REQUEST
-    // Decorate certain Composer Stager preconditions.
-    $container->register(NoSymlinksPointToADirectory::class)
-      ->setPublic(FALSE)
-      ->setAutowired(TRUE)
-      ->setDecoratedService(NoSymlinksPointToADirectoryInterface::class);
   }
 
 }

package_manager/src/PackageManagerUninstallValidator.php

@@ -4,11 +4,16 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager;
 
+use Drupal\Component\Datetime\TimeInterface;
 use Drupal\Core\Extension\ModuleUninstallValidatorInterface;
+use Drupal\Core\Queue\QueueFactory;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
-use PhpTuf\ComposerStager\Infrastructure\Factory\Path\PathFactoryInterface;
-use Symfony\Component\DependencyInjection\ContainerAwareInterface;
-use Symfony\Component\DependencyInjection\ContainerAwareTrait;
+use Drupal\Core\TempStore\SharedTempStoreFactory;
+use PhpTuf\ComposerStager\API\Core\BeginnerInterface;
+use PhpTuf\ComposerStager\API\Core\CommitterInterface;
+use PhpTuf\ComposerStager\API\Core\StagerInterface;
+use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 
 /**
  * Prevents any module from being uninstalled if update is in process.
@@ -18,26 +23,62 @@ use Symfony\Component\DependencyInjection\ContainerAwareTrait;
  *   at any time without warning. External code should not interact with this
  *   class.
  */
-final class PackageManagerUninstallValidator implements ModuleUninstallValidatorInterface, ContainerAwareInterface {
+final class PackageManagerUninstallValidator implements ModuleUninstallValidatorInterface {
 
-  use ContainerAwareTrait;
   use StringTranslationTrait;
 
+  /**
+   * Constructs a new PackageManagerUninstallValidator object.
+   *
+   * @param \Drupal\package_manager\PathLocator $pathLocator
+   *   The path locator service.
+   * @param \PhpTuf\ComposerStager\API\Core\BeginnerInterface $beginner
+   *   The beginner service.
+   * @param \PhpTuf\ComposerStager\API\Core\StagerInterface $stager
+   *   The stager service.
+   * @param \PhpTuf\ComposerStager\API\Core\CommitterInterface $committer
+   *   The committer service.
+   * @param \Drupal\Core\Queue\QueueFactory $queueFactory
+   *   The queue factory service.
+   * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $eventDispatcher
+   *   The event dispatcher service.
+   * @param \Drupal\Core\TempStore\SharedTempStoreFactory $sharedTempStoreFactory
+   *   The shared temp store factory service.
+   * @param \Drupal\Component\Datetime\TimeInterface $time
+   *   The time service.
+   * @param \PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface $pathFactory
+   *   The path factory service.
+   * @param \Drupal\package_manager\FailureMarker $failureMarker
+   *   The failure marker service.
+   */
+  public function __construct(
+    private readonly PathLocator $pathLocator,
+    private readonly BeginnerInterface $beginner,
+    private readonly StagerInterface $stager,
+    private readonly CommitterInterface $committer,
+    private readonly QueueFactory $queueFactory,
+    private readonly EventDispatcherInterface $eventDispatcher,
+    private readonly SharedTempStoreFactory $sharedTempStoreFactory,
+    private readonly TimeInterface $time,
+    private readonly PathFactoryInterface $pathFactory,
+    private readonly FailureMarker $failureMarker
+  ) {}
+
   /**
    * {@inheritdoc}
    */
   public function validate($module) {
     $stage = new class(
-      $this->container->get('package_manager.path_locator'),
-      $this->container->get('package_manager.beginner'),
-      $this->container->get('package_manager.stager'),
-      $this->container->get('package_manager.committer'),
-      $this->container->get('file_system'),
-      $this->container->get('event_dispatcher'),
-      $this->container->get('tempstore.shared'),
-      $this->container->get('datetime.time'),
-      $this->container->get(PathFactoryInterface::class),
-      $this->container->get('package_manager.failure_marker')) extends StageBase {};
+      $this->pathLocator,
+      $this->beginner,
+      $this->stager,
+      $this->committer,
+      $this->queueFactory,
+      $this->eventDispatcher,
+      $this->sharedTempStoreFactory,
+      $this->time,
+      $this->pathFactory,
+      $this->failureMarker) extends StageBase {};
     if ($stage->isAvailable() || !$stage->isApplying()) {
       return [];
     }

package_manager/src/PackageManagerUpdateProcessor.php

@@ -4,6 +4,7 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager;
 
+use Drupal\Component\Datetime\TimeInterface;
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\KeyValueStore\KeyValueExpirableFactoryInterface;
 use Drupal\Core\KeyValueStore\KeyValueFactoryInterface;
@@ -48,18 +49,24 @@ final class PackageManagerUpdateProcessor extends UpdateProcessor {
    *   The key/value factory.
    * @param \Drupal\Core\KeyValueStore\KeyValueExpirableFactoryInterface $key_value_expirable_factory
    *   The expirable key/value factory.
+   * @param \Drupal\Component\Datetime\TimeInterface $time
+   *   The time service.
    */
-  public function __construct(ConfigFactoryInterface $config_factory, QueueFactory $queue_factory, UpdateFetcherInterface $update_fetcher, StateInterface $state_store, PrivateKey $private_key, KeyValueFactoryInterface $key_value_factory, KeyValueExpirableFactoryInterface $key_value_expirable_factory) {
-    $this->updateFetcher = $update_fetcher;
-    $this->updateSettings = $config_factory->get('update.settings');
+  public function __construct(
+    ConfigFactoryInterface $config_factory,
+    QueueFactory $queue_factory,
+    UpdateFetcherInterface $update_fetcher,
+    StateInterface $state_store,
+    PrivateKey $private_key,
+    KeyValueFactoryInterface $key_value_factory,
+    KeyValueExpirableFactoryInterface $key_value_expirable_factory,
+    TimeInterface $time,
+  ) {
+    parent::__construct(...func_get_args());
     $this->fetchQueue = $queue_factory->get('package_manager.update_fetch_tasks');
     $this->tempStore = $key_value_expirable_factory->get('package_manager.update');
     $this->fetchTaskStore = $key_value_factory->get('package_manager.update_fetch_task');
     $this->availableReleasesTempStore = $key_value_expirable_factory->get('package_manager.update_available_releases');
-    $this->stateStore = $state_store;
-    $this->privateKey = $private_key;
-    $this->fetchTasks = [];
-    $this->failed = [];
   }
 
   /**

package_manager/src/PathExcluder/SiteConfigurationExcluder.php

@@ -4,7 +4,12 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager\PathExcluder;
 
+use Drupal\Core\File\Exception\FileException;
+use Drupal\Core\File\FileSystemInterface;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
+use Drupal\package_manager\Event\PostCreateEvent;
+use Drupal\package_manager\Event\PreApplyEvent;
+use Drupal\package_manager\PathLocator;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
@@ -22,8 +27,16 @@ class SiteConfigurationExcluder implements EventSubscriberInterface {
    *
    * @param string $sitePath
    *   The current site path, relative to the Drupal root.
+   * @param \Drupal\package_manager\PathLocator $pathLocator
+   *   The path locator service.
+   * @param \Drupal\Core\File\FileSystemInterface $fileSystem
+   *   The file system service.
    */
-  public function __construct(protected string $sitePath) {}
+  public function __construct(
+    protected string $sitePath,
+    private readonly PathLocator $pathLocator,
+    private readonly FileSystemInterface $fileSystem
+  ) {}
 
   /**
    * Excludes site configuration files from stage operations.
@@ -32,8 +45,11 @@ class SiteConfigurationExcluder implements EventSubscriberInterface {
    *   The event object.
    */
   public function excludeSiteConfiguration(CollectPathsToExcludeEvent $event): void {
-    // Site configuration files are always excluded relative to the web root.
-    $paths = [];
+    // These two files are never relevant to existing sites.
+    $paths = [
+      'sites/default/default.settings.php',
+      'sites/default/default.services.yml',
+    ];
 
     // Exclude site-specific settings files, which are always in the web root.
     // By default, Drupal core will always try to write-protect these files.
@@ -46,15 +62,92 @@ class SiteConfigurationExcluder implements EventSubscriberInterface {
       $paths[] = $this->sitePath . '/' . $settings_file;
       $paths[] = 'sites/default/' . $settings_file;
     }
+    // Site configuration files are always excluded relative to the web root.
     $event->addPathsRelativeToWebRoot($paths);
   }
 
+  /**
+   * Makes the staged `sites/default` directory owner-writable.
+   *
+   * This is done to allow the core scaffold plugin to make changes in
+   * `sites/default`, if necessary, without breaking if `sites/default` is not
+   * writable (this can happen because rsync preserves directory permissions,
+   * and Drupal will try to harden the site directory's permissions as much as
+   * possible). We specifically exclude the `default.settings.php` and
+   * `default.services.yml` files from Package Manager operations, so we want to
+   * allow the scaffold plugin to make whatever changes it wants to those files
+   * in the stage directory.
+   *
+   * @param \Drupal\package_manager\Event\PostCreateEvent $event
+   *   The event being handled.
+   *
+   * @see ::excludeSiteConfiguration()
+   */
+  public function makeDefaultSiteDirectoryWritable(PostCreateEvent $event): void {
+    $dir = $this->getDefaultSiteDirectoryPath($event->stage->getStageDirectory());
+    // If the directory doesn't even exist, there's nothing to do here.
+    if (!is_dir($dir)) {
+      return;
+    }
+    if (!$this->fileSystem->chmod($dir, 0700)) {
+      throw new FileException("Could not change permissions on '$dir'.");
+    }
+  }
+
+  /**
+   * Makes `sites/default` permissions the same in live and stage directories.
+   *
+   * @param \Drupal\package_manager\Event\PreApplyEvent $event
+   *   The event being handled.
+   *
+   * @throws \Drupal\Core\File\Exception\FileException
+   *   If the permissions of the live `sites/default` cannot be determined, or
+   *   cannot be changed on the staged `sites/default`.
+   */
+  public function syncDefaultSiteDirectoryPermissions(PreApplyEvent $event): void {
+    $staged_dir = $this->getDefaultSiteDirectoryPath($event->stage->getStageDirectory());
+    // If the directory doesn't even exist, there's nothing to do here.
+    if (!is_dir($staged_dir)) {
+      return;
+    }
+    $live_dir = $this->getDefaultSiteDirectoryPath($this->pathLocator->getProjectRoot());
+
+    $permissions = fileperms($live_dir);
+    if ($permissions === FALSE) {
+      throw new FileException("Could not determine permissions for '$live_dir'.");
+    }
+
+    if (!$this->fileSystem->chmod($staged_dir, $permissions)) {
+      throw new FileException("Could not change permissions on '$staged_dir'.");
+    }
+  }
+
+  /**
+   * Returns the full path to `sites/default`, relative to a root directory.
+   *
+   * @param string $root_dir
+   *   The root directory.
+   *
+   * @return string
+   *   The full path to `sites/default` within the given root directory.
+   */
+  private function getDefaultSiteDirectoryPath(string $root_dir): string {
+    $dir = [$root_dir];
+    $web_root = $this->pathLocator->getWebRoot();
+    if ($web_root) {
+      $dir[] = $web_root;
+    }
+    return implode(DIRECTORY_SEPARATOR, [...$dir, 'sites', 'default']);
+  }
+
   /**
    * {@inheritdoc}
    */
   public static function getSubscribedEvents(): array {
     return [
       CollectPathsToExcludeEvent::class => 'excludeSiteConfiguration',
+      PostCreateEvent::class => 'makeDefaultSiteDirectoryWritable',
+      PreApplyEvent::class => 'syncDefaultSiteDirectoryPermissions',
     ];
   }
 

package_manager/src/PathExcluder/SiteFilesExcluder.php

@@ -59,7 +59,9 @@ final class SiteFilesExcluder implements EventSubscriberInterface {
         $path = $wrapper->getDirectoryPath();
 
         if ($this->fileSystem->isAbsolutePath($path)) {
-          $event->addPathsRelativeToProjectRoot([realpath($path)]);
+          if ($path = realpath($path)) {
+            $event->addPathsRelativeToProjectRoot([$path]);
+          }
         }
         else {
           $event->addPathsRelativeToWebRoot([$path]);

package_manager/src/PathExcluder/SqliteDatabaseExcluder.php

@@ -6,7 +6,7 @@ namespace Drupal\package_manager\PathExcluder;
 
 use Drupal\Core\Database\Connection;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
-use Drupal\package_manager\PathLocator;
+use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
@@ -22,16 +22,14 @@ class SqliteDatabaseExcluder implements EventSubscriberInterface {
   /**
    * Constructs a SqliteDatabaseExcluder object.
    *
-   * @param \Drupal\package_manager\PathLocator $pathLocator
-   *   The path locator service.
+   * @param \PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface $pathFactory
+   *   The path factory service.
    * @param \Drupal\Core\Database\Connection $database
    *   The database connection.
    */
   public function __construct(
-    private readonly PathLocator $pathLocator,
-    // TRICKY: this cannot be private nor readonly for testing purposes.
-    // @see \Drupal\Tests\package_manager\Kernel\PathExcluder\SqliteDatabaseExcluderTest::mockDatabase()
-    protected Connection $database
+    private readonly PathFactoryInterface $pathFactory,
+    private readonly Connection $database,
   ) {}
 
   /**
@@ -50,19 +48,27 @@ class SqliteDatabaseExcluder implements EventSubscriberInterface {
    *   The event object.
    */
   public function excludeDatabaseFiles(CollectPathsToExcludeEvent $event): void {
-    // If the database is SQLite, it might be located in the active directory
-    // and we should exclude it. Always treat it as relative to the project root.
+    // If the database is SQLite, it might be located in the project directory
+    // and we should exclude it.
     if ($this->database->driver() === 'sqlite') {
-      $options = $this->database->getConnectionOptions();
-      // Nothing to exclude if the database lives outside the project root.
-      if (str_starts_with($options['database'], '/') && !str_starts_with($options['database'], $this->pathLocator->getProjectRoot())) {
-        return;
+      $db_path = $this->database->getConnectionOptions()['database'];
+      // Exclude the database file and auxiliary files created by SQLite.
+      $paths = [$db_path, "$db_path-shm", "$db_path-wal"];
+
+      // If the database path is absolute, it might be outside the project root,
+      // in which case we don't need to do anything.
+      if ($this->pathFactory->create($db_path)->isAbsolute()) {
+        try {
+          $event->addPathsRelativeToProjectRoot($paths);
+        }
+        catch (\LogicException) {
+          // The database is outside of the project root, so we're done.
+        }
+      }
+      else {
+        // The database is in the web root, and must be excluded relative to it.
+        $event->addPathsRelativeToWebRoot($paths);
       }
-      $event->addPathsRelativeToProjectRoot([
-        $options['database'],
-        $options['database'] . '-shm',
-        $options['database'] . '-wal',
-      ]);
     }
   }
 

package_manager/src/PathExcluder/UnknownPathExcluder.php

@@ -5,9 +5,15 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\PathExcluder;
 
 use Drupal\Component\Serialization\Json;
+use Drupal\Core\Config\ConfigFactoryInterface;
+use Drupal\Core\StringTranslation\StringTranslationTrait;
 use Drupal\package_manager\ComposerInspector;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
+use Drupal\package_manager\Event\StatusCheckEvent;
 use Drupal\package_manager\PathLocator;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
@@ -23,12 +29,22 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  *
  * If web root and project root are the same, nothing is excluded.
  *
+ * This excluder can be disabled by changing the config setting
+ * `package_manager.settings:include_unknown_files_in_project_root` to TRUE.
+ * This may be needed for sites that have files outside the web root (besides
+ * the vendor directory) which are nonetheless needed in order for Composer to
+ * assemble the code base correctly; a classic example would be a directory of
+ * patch files used by `cweagans/composer-patches`.
+ *
  * @internal
  *   This is an internal part of Package Manager and may be changed or removed
  *   at any time without warning. External code should not interact with this
  *   class.
  */
-final class UnknownPathExcluder implements EventSubscriberInterface {
+final class UnknownPathExcluder implements EventSubscriberInterface, LoggerAwareInterface {
+
+  use LoggerAwareTrait;
+  use StringTranslationTrait;
 
   /**
    * Constructs a UnknownPathExcluder object.
@@ -37,11 +53,16 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
    *   The Composer inspector service.
    * @param \Drupal\package_manager\PathLocator $pathLocator
    *   The path locator service.
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
+   *   The config factory service.
    */
   public function __construct(
     private readonly ComposerInspector $composerInspector,
     private readonly PathLocator $pathLocator,
-  ) {}
+    private readonly ConfigFactoryInterface $configFactory,
+  ) {
+    $this->setLogger(new NullLogger());
+  }
 
   /**
    * {@inheritdoc}
@@ -49,53 +70,110 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
   public static function getSubscribedEvents(): array {
     return [
       CollectPathsToExcludeEvent::class => 'excludeUnknownPaths',
+      StatusCheckEvent::class => 'logExcludedPaths',
     ];
   }
 
   /**
-   * Excludes unknown paths from stage operations.
+   * Returns the paths to exclude from stage operations.
    *
-   * @param \Drupal\package_manager\Event\CollectPathsToExcludeEvent $event
-   *   The event object.
+   * @return string[]
+   *   The paths that should be excluded from stage operations, relative to the
+   *   project root.
    *
    * @throws \Exception
    *   See \Drupal\package_manager\ComposerInspector::validate().
    */
-  public function excludeUnknownPaths(CollectPathsToExcludeEvent $event): void {
-    $project_root = $this->pathLocator->getProjectRoot();
-    $web_root = $project_root . DIRECTORY_SEPARATOR . $this->pathLocator->getWebRoot();
-    if (realpath($web_root) === $project_root) {
-      return;
+  private function getExcludedPaths(): array {
+    // If this excluder is disabled, or the project root and web root are the
+    // same, we are not excluding any paths.
+    $is_disabled = $this->configFactory->get('package_manager.settings')
+      ->get('include_unknown_files_in_project_root');
+    $web_root = $this->pathLocator->getWebRoot();
+    if ($is_disabled || empty($web_root)) {
+      return [];
     }
 
-    // To determine the scaffold files to exclude, the installed packages must
-    // be known, and that requires Composer commands to be able to run. This
-    // intentionally does not catch exceptions: failed Composer validation in
-    // the project root implies that this excluder cannot function correctly.
-    // Note: the call to ComposerInspector::getInstalledPackagesList() would
+    // To determine the files to include, the installed packages must be known,
+    // and that requires Composer commands to be able to run. This intentionally
+    // does not catch exceptions: failed Composer validation in the project root
+    // implies that this excluder cannot function correctly.
+    // Note: the call to ComposerInspector::getConfig() would
     // also have triggered this, but explicitness is preferred here.
     // @see \Drupal\package_manager\StatusCheckTrait::runStatusCheck()
+    $project_root = $this->pathLocator->getProjectRoot();
     $this->composerInspector->validate($project_root);
 
-    $vendor_dir = $this->pathLocator->getVendorDirectory();
-    $scaffold_files_paths = $this->getScaffoldFiles();
-    // Search for all files (including hidden ones) in project root.
-    $paths_in_project_root = glob("$project_root/{,.}*", GLOB_BRACE);
-    $paths = [];
-    $known_paths = array_merge([$vendor_dir, $web_root, "$project_root/composer.json", "$project_root/composer.lock"], $scaffold_files_paths);
-    foreach ($paths_in_project_root as $path_in_project_root) {
-      if (!in_array($path_in_project_root, $known_paths, TRUE)) {
-        $paths[] = $path_in_project_root;
+    // The vendor directory and web root are always included in staging
+    // operations, along with `composer.json`, `composer.lock`, and any scaffold
+    // files provided by Drupal core.
+    $always_include = [
+      $this->composerInspector->getConfig('vendor-dir', $project_root),
+      $web_root,
+      'composer.json',
+      'composer.lock',
+    ];
+    foreach ($this->getScaffoldFiles() as $scaffold_file_path) {
+      // The web root is always included in staging operations, so we don't need
+      // to do anything special for scaffold files that live in it.
+      if (str_starts_with($scaffold_file_path, '[web-root]')) {
+        continue;
       }
+      $always_include[] = ltrim($scaffold_file_path, '/');
+    }
+
+    // Search for all files (including hidden ones) in the project root. We need
+    // to use readdir() and friends here, rather than glob(), since certain
+    // glob() flags aren't supported on all systems. We also can't use
+    // \Drupal\Core\File\FileSystemInterface::scanDirectory(), because it
+    // unconditionally ignores hidden files and directories.
+    $files_in_project_root = [];
+    $handle = opendir($project_root);
+    if (empty($handle)) {
+      throw new \RuntimeException("Could not scan for files in the project root.");
+    }
+    while ($entry = readdir($handle)) {
+      $files_in_project_root[] = $entry;
+    }
+    closedir($handle);
+
+    return array_diff($files_in_project_root, $always_include, ['.', '..']);
+  }
+
+  /**
+   * Excludes unknown paths from stage operations.
+   *
+   * @param \Drupal\package_manager\Event\CollectPathsToExcludeEvent $event
+   *   The event object.
+   */
+  public function excludeUnknownPaths(CollectPathsToExcludeEvent $event): void {
+    // We can exclude the paths as-is; they are already relative to the project
+    // root.
+    $event->add(...$this->getExcludedPaths());
+  }
+
+  /**
+   * Logs the paths that will be excluded from stage operations.
+   */
+  public function logExcludedPaths(): void {
+    $excluded_paths = $this->getExcludedPaths();
+    if ($excluded_paths) {
+      sort($excluded_paths);
+
+      $message = $this->t("The following paths in @project_root aren't recognized as part of your Drupal site, so to be safe, Package Manager is excluding them from all stage operations. If these files are not needed for Composer to work properly in your site, no action is needed. Otherwise, you can disable this behavior by setting the <code>package_manager.settings:include_unknown_files_in_project_root</code> config setting to <code>TRUE</code>.\n\n@list", [
+        '@project_root' => $this->pathLocator->getProjectRoot(),
+        '@list' => implode("\n", $excluded_paths),
+      ]);
+      $this->logger->info($message);
     }
-    $event->addPathsRelativeToProjectRoot($paths);
   }
 
   /**
    * Gets the path of scaffold files, for example 'index.php' and 'robots.txt'.
    *
-   * @return array
-   *   The array of scaffold file paths.
+   * @return string[]
+   *   The paths of scaffold files provided by `drupal/core`, relative to the
+   *   project root.
    *
    * @todo Intelligently load scaffold files in https://drupal.org/i/3343802.
    */
@@ -103,10 +181,9 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
     $project_root = $this->pathLocator->getProjectRoot();
     $packages = $this->composerInspector->getInstalledPackagesList($project_root);
     $extra = Json::decode($this->composerInspector->getConfig('extra', $packages['drupal/core']->path . '/composer.json'));
-    if (isset($extra['drupal-scaffold']['file-mapping'])) {
-      return array_keys($extra['drupal-scaffold']['file-mapping']);
-    }
-    return [];
+
+    $scaffold_files = $extra['drupal-scaffold']['file-mapping'] ?? [];
+    return str_replace('[project-root]', '', array_keys($scaffold_files));
   }
 
 }

package_manager/src/Plugin/QueueWorker/Cleaner.php

+<?php
+
+namespace Drupal\package_manager\Plugin\QueueWorker;
+
+use Drupal\Core\File\FileSystemInterface;
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Drupal\Core\Queue\QueueWorkerBase;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+/**
+ * Processes a queue of defunct stage directories, deleting them.
+ *
+ * @QueueWorker(
+ *   id = "package_manager_cleanup",
+ *   title = @Translation("Stage directory cleaner"),
+ *   cron = {"time" = 30}
+ * )
+ */
+final class Cleaner extends QueueWorkerBase implements ContainerFactoryPluginInterface {
+
+  /**
+   * Constructs a new Cleaner instance.
+   *
+   * @param array $configuration
+   *   A configuration array containing information about the plugin instance.
+   * @param string $plugin_id
+   *   The plugin ID.
+   * @param mixed $plugin_definition
+   *   The plugin implementation definition.
+   * @param \Drupal\Core\File\FileSystemInterface $fileSystem
+   *   The file system service.
+   */
+  public function __construct(array $configuration, string $plugin_id, mixed $plugin_definition, private readonly FileSystemInterface $fileSystem) {
+    parent::__construct($configuration, $plugin_id, $plugin_definition);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
+    return new static(
+      $configuration,
+      $plugin_id,
+      $plugin_definition,
+      $container->get(FileSystemInterface::class),
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function processItem($dir) {
+    assert(is_string($dir));
+
+    if (file_exists($dir)) {
+      $this->fileSystem->deleteRecursive($dir, function (string $path): void {
+        $this->fileSystem->chmod($path, is_dir($path) ? 0700 : 0600);
+      });
+    }
+  }
+
+}

package_manager/src/ProcessFactory.php

@@ -6,9 +6,8 @@ namespace Drupal\package_manager;
 
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\File\FileSystemInterface;
-use PhpTuf\ComposerStager\Infrastructure\Factory\Process\ProcessFactoryInterface;
-use PhpTuf\ComposerStager\Infrastructure\Factory\Process\ProcessFactory as StagerProcessFactory;
-use Symfony\Component\Process\Process;
+use PhpTuf\ComposerStager\API\Process\Factory\ProcessFactoryInterface;
+use PhpTuf\ComposerStager\API\Process\Service\ProcessInterface;
 
 // cspell:ignore BINDIR
 
@@ -22,13 +21,6 @@ use Symfony\Component\Process\Process;
  */
 final class ProcessFactory implements ProcessFactoryInterface {
 
-  /**
-   * The decorated process factory.
-   *
-   * @var \PhpTuf\ComposerStager\Infrastructure\Factory\Process\ProcessFactoryInterface
-   */
-  private $decorated;
-
   /**
    * Constructs a ProcessFactory object.
    *
@@ -36,13 +28,14 @@ final class ProcessFactory implements ProcessFactoryInterface {
    *   The file system service.
    * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
    *   The config factory service.
+   * @param \PhpTuf\ComposerStager\API\Process\Factory\ProcessFactoryInterface $decorated
+   *   The decorated process factory service.
    */
   public function __construct(
     private readonly FileSystemInterface $fileSystem,
-    private readonly ConfigFactoryInterface $configFactory
-  ) {
-    $this->decorated = new StagerProcessFactory();
-  }
+    private readonly ConfigFactoryInterface $configFactory,
+    private readonly ProcessFactoryInterface $decorated,
+  ) {}
 
   /**
    * Returns the value of an environment variable.
@@ -63,11 +56,11 @@ final class ProcessFactory implements ProcessFactoryInterface {
   /**
    * {@inheritdoc}
    */
-  public function create(array $command): Process {
+  public function create(array $command): ProcessInterface {
     $process = $this->decorated->create($command);
 
     $env = $process->getEnv();
-    if ($this->isComposerCommand($command)) {
+    if ($command && $this->isComposerCommand($command)) {
       $env['COMPOSER_HOME'] = $this->getComposerHomePath();
     }
     // Ensure that the current PHP installation is the first place that will be
@@ -87,7 +80,7 @@ final class ProcessFactory implements ProcessFactoryInterface {
    * @see php_sapi_name()
    * @see https://www.php.net/manual/en/reserved.constants.php
    */
-  protected static function getPhpDirectory(): string {
+  private static function getPhpDirectory(): string {
     if (PHP_SAPI === 'cli' || PHP_SAPI === 'cli-server') {
       return dirname(PHP_BINARY);
     }

package_manager/src/ProcessOutputCallback.php

@@ -4,7 +4,8 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager;
 
-use PhpTuf\ComposerStager\Domain\Service\ProcessOutputCallback\ProcessOutputCallbackInterface;
+use PhpTuf\ComposerStager\API\Process\Service\OutputCallbackInterface;
+use PhpTuf\ComposerStager\API\Process\Value\OutputTypeEnum;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerAwareTrait;
 use Psr\Log\NullLogger;
@@ -19,7 +20,7 @@ use Psr\Log\NullLogger;
  *   at any time without warning. External code should not interact with this
  *   class.
  */
-final class ProcessOutputCallback implements ProcessOutputCallbackInterface, LoggerAwareInterface {
+final class ProcessOutputCallback implements OutputCallbackInterface, LoggerAwareInterface {
 
   use LoggerAwareTrait;
 
@@ -47,16 +48,14 @@ final class ProcessOutputCallback implements ProcessOutputCallbackInterface, Log
   /**
    * {@inheritdoc}
    */
-  public function __invoke(string $type, string $buffer): void {
-    if ($type === self::OUT) {
+  public function __invoke(OutputTypeEnum $type, string $buffer): void {
+
+    if ($type === OutputTypeEnum::OUT) {
       $this->outBuffer .= $buffer;
     }
-    elseif ($type === self::ERR) {
+    elseif ($type === OutputTypeEnum::ERR) {
       $this->errorBuffer .= $buffer;
     }
-    else {
-      throw new \InvalidArgumentException("Unsupported output type: '$type'");
-    }
   }
 
   /**

package_manager/src/ProjectInfo.php

@@ -192,7 +192,7 @@ final class ProjectInfo {
     // update processor service.
     if (!isset($available_projects[$this->name])) {
       /** @var \Drupal\package_manager\PackageManagerUpdateProcessor $update_processor */
-      $update_processor = \Drupal::service('package_manager.update_processor');
+      $update_processor = \Drupal::service(PackageManagerUpdateProcessor::class);
       if ($project_data = $update_processor->getProjectData($this->name)) {
         $available_projects[$this->name] = $project_data;
       }

package_manager/src/StageBase.php

@@ -6,21 +6,19 @@ namespace Drupal\package_manager;
 
 use Composer\Semver\VersionParser;
 use Drupal\Component\Datetime\TimeInterface;
-use Drupal\Component\Utility\Crypt;
-use Drupal\Core\File\Exception\FileException;
-use Drupal\Core\File\FileSystemInterface;
+use Drupal\Component\Utility\Random;
+use Drupal\Core\Queue\QueueFactory;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
 use Drupal\Core\StringTranslation\TranslatableMarkup;
 use Drupal\Core\TempStore\SharedTempStore;
 use Drupal\Core\TempStore\SharedTempStoreFactory;
+use Drupal\Core\Utility\Error;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
 use Drupal\package_manager\Event\PostApplyEvent;
 use Drupal\package_manager\Event\PostCreateEvent;
-use Drupal\package_manager\Event\PostDestroyEvent;
 use Drupal\package_manager\Event\PostRequireEvent;
 use Drupal\package_manager\Event\PreApplyEvent;
 use Drupal\package_manager\Event\PreCreateEvent;
-use Drupal\package_manager\Event\PreDestroyEvent;
 use Drupal\package_manager\Event\PreOperationStageEvent;
 use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\Event\StageEvent;
@@ -28,13 +26,13 @@ use Drupal\package_manager\Exception\ApplyFailedException;
 use Drupal\package_manager\Exception\StageEventException;
 use Drupal\package_manager\Exception\StageException;
 use Drupal\package_manager\Exception\StageOwnershipException;
-use PhpTuf\ComposerStager\Domain\Core\Beginner\BeginnerInterface;
-use PhpTuf\ComposerStager\Domain\Core\Committer\CommitterInterface;
-use PhpTuf\ComposerStager\Domain\Core\Stager\StagerInterface;
-use PhpTuf\ComposerStager\Domain\Exception\InvalidArgumentException;
-use PhpTuf\ComposerStager\Domain\Exception\PreconditionException;
-use PhpTuf\ComposerStager\Infrastructure\Factory\Path\PathFactoryInterface;
-use PhpTuf\ComposerStager\Infrastructure\Value\PathList\PathList;
+use PhpTuf\ComposerStager\API\Core\BeginnerInterface;
+use PhpTuf\ComposerStager\API\Core\CommitterInterface;
+use PhpTuf\ComposerStager\API\Core\StagerInterface;
+use PhpTuf\ComposerStager\API\Exception\InvalidArgumentException;
+use PhpTuf\ComposerStager\API\Exception\PreconditionException;
+use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerAwareTrait;
 use Psr\Log\NullLogger;
@@ -161,26 +159,37 @@ abstract class StageBase implements LoggerAwareInterface {
    */
   protected SharedTempStore $tempStore;
 
+  /**
+   * The stage type.
+   *
+   * To ensure that stage classes do not unintentionally use another stage's
+   * type, all concrete subclasses MUST explicitly define this property.
+   * The recommended pattern is `MODULE:TYPE`.
+   *
+   * @var string
+   */
+  protected string $type;
+
   /**
    * Constructs a new Stage object.
    *
    * @param \Drupal\package_manager\PathLocator $pathLocator
    *   The path locator service.
-   * @param \PhpTuf\ComposerStager\Domain\Core\Beginner\BeginnerInterface $beginner
+   * @param \PhpTuf\ComposerStager\API\Core\BeginnerInterface $beginner
    *   The beginner service.
-   * @param \PhpTuf\ComposerStager\Domain\Core\Stager\StagerInterface $stager
+   * @param \PhpTuf\ComposerStager\API\Core\StagerInterface $stager
    *   The stager service.
-   * @param \PhpTuf\ComposerStager\Domain\Core\Committer\CommitterInterface $committer
+   * @param \PhpTuf\ComposerStager\API\Core\CommitterInterface $committer
    *   The committer service.
-   * @param \Drupal\Core\File\FileSystemInterface $fileSystem
-   *   The file system service.
+   * @param \Drupal\Core\Queue\QueueFactory $queueFactory
+   *   The queue factory.
    * @param \Symfony\Contracts\EventDispatcher\EventDispatcherInterface $eventDispatcher
    *   The event dispatcher service.
    * @param \Drupal\Core\TempStore\SharedTempStoreFactory $tempStoreFactory
    *   The shared tempstore factory.
    * @param \Drupal\Component\Datetime\TimeInterface $time
    *   The time service.
-   * @param \PhpTuf\ComposerStager\Infrastructure\Factory\Path\PathFactoryInterface $pathFactory
+   * @param \PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface $pathFactory
    *   The path factory service.
    * @param \Drupal\package_manager\FailureMarker $failureMarker
    *   The failure marker service.
@@ -190,7 +199,7 @@ abstract class StageBase implements LoggerAwareInterface {
     protected readonly BeginnerInterface $beginner,
     protected readonly StagerInterface $stager,
     protected readonly CommitterInterface $committer,
-    protected readonly FileSystemInterface $fileSystem,
+    protected readonly QueueFactory $queueFactory,
     protected EventDispatcherInterface $eventDispatcher,
     protected readonly SharedTempStoreFactory $tempStoreFactory,
     protected readonly TimeInterface $time,
@@ -201,6 +210,31 @@ abstract class StageBase implements LoggerAwareInterface {
     $this->setLogger(new NullLogger());
   }
 
+  /**
+   * Gets the stage type.
+   *
+   * The stage type can be used by stage event subscribers to implement logic
+   * specific to certain stages, without relying on the class name (which may
+   * not be part of module's public API).
+   *
+   * @return string
+   *   The stage type.
+   *
+   * @throws \LogicException
+   *   Thrown if $this->type is not explicitly overridden.
+   */
+  final public function getType(): string {
+    $reflector = new \ReflectionProperty($this, 'type');
+
+    // The $type property must ALWAYS be overridden. This means that different
+    // subclasses can return the same value (thus allowing one stage to
+    // impersonate another one), but if that happens, it is intentional.
+    if ($reflector->getDeclaringClass()->getName() === static::class) {
+      return $this->type;
+    }
+    throw new \LogicException(static::class . ' must explicitly override the $type property.');
+  }
+
   /**
    * Determines if the stage directory can be created.
    *
@@ -223,7 +257,7 @@ abstract class StageBase implements LoggerAwareInterface {
    * @return mixed
    *   The metadata value, or NULL if it is not set.
    */
-  protected function getMetadata(string $key) {
+  public function getMetadata(string $key) {
     $this->checkOwnership();
 
     $metadata = $this->tempStore->get(static::TEMPSTORE_METADATA_KEY) ?: [];
@@ -237,11 +271,13 @@ abstract class StageBase implements LoggerAwareInterface {
    * claimed by its owner, or created during the current request.
    *
    * @param string $key
-   *   The key under which to store the metadata.
+   *   The key under which to store the metadata. To prevent conflicts, it is
+   *   strongly recommended that this be prefixed with the name of the module
+   *   storing the data.
    * @param mixed $data
    *   The metadata to store.
    */
-  protected function setMetadata(string $key, $data): void {
+  public function setMetadata(string $key, $data): void {
     $this->checkOwnership();
 
     $metadata = $this->tempStore->get(static::TEMPSTORE_METADATA_KEY);
@@ -252,7 +288,7 @@ abstract class StageBase implements LoggerAwareInterface {
   /**
    * Collects paths that Composer Stager should exclude.
    *
-   * @return string[]
+   * @return \PhpTuf\ComposerStager\API\Path\Value\PathListInterface
    *   A list of paths that Composer Stager should exclude when creating the
    *   stage directory and applying staged changes to the active directory.
    *
@@ -262,15 +298,14 @@ abstract class StageBase implements LoggerAwareInterface {
    * @see ::create()
    * @see ::apply()
    */
-  protected function getPathsToExclude(): array {
+  protected function getPathsToExclude(): PathListInterface {
     $event = new CollectPathsToExcludeEvent($this, $this->pathLocator, $this->pathFactory);
     try {
-      $this->eventDispatcher->dispatch($event);
+      return $this->eventDispatcher->dispatch($event);
     }
     catch (\Throwable $e) {
       $this->rethrowAsStageException($e);
     }
-    return $event->getAll();
   }
 
   /**
@@ -309,26 +344,40 @@ abstract class StageBase implements LoggerAwareInterface {
     // to create a stage directory at around the same time. If an error occurs
     // while the event is being processed, the stage is marked as available.
     // @see ::dispatch()
-    $id = Crypt::randomBytesBase64();
+    // We specifically generate a random 32-character alphanumeric name in order
+    // to guarantee that the the stage ID won't start with -, which could cause
+    // it to be interpreted as an option if it's used as a command-line
+    // argument. (For example,
+    // \Drupal\Component\Utility\Crypt::randomBytesBase64() would be vulnerable
+    // to this; the stage ID needs to be unique, but not cryptographically so.)
+    $id = (new Random())->name(32);
     // Re-acquire the tempstore to ensure that the lock is written by whoever is
     // actually logged in (or not) right now, since it's possible that the stage
     // was instantiated (i.e., __construct() was called) by a different session,
     // which would result in the lock having the wrong owner and the stage not
     // being claimable by whoever is actually creating it.
     $this->tempStore = $this->tempStoreFactory->get('package_manager_stage');
-    $this->tempStore->set(static::TEMPSTORE_LOCK_KEY, [$id, static::class]);
+    // For the lock value, we use both the stage's class and its type in order
+    // to prevent a stage from being manipulated by two different classes during
+    // a single life cycle.
+    $this->tempStore->set(static::TEMPSTORE_LOCK_KEY, [
+      $id,
+      static::class,
+      $this->getType(),
+    ]);
     $this->claim($id);
 
     $active_dir = $this->pathFactory->create($this->pathLocator->getProjectRoot());
     $stage_dir = $this->pathFactory->create($this->getStageDirectory());
 
-    $event = new PreCreateEvent($this, $this->getPathsToExclude());
+    $excluded_paths = $this->getPathsToExclude();
+    $event = new PreCreateEvent($this, $excluded_paths);
     // If an error occurs and we won't be able to create the stage, mark it as
     // available.
     $this->dispatch($event, [$this, 'markAsAvailable']);
 
     try {
-      $this->beginner->begin($active_dir, $stage_dir, new PathList($event->getExcludedPaths()), NULL, $timeout);
+      $this->beginner->begin($active_dir, $stage_dir, $excluded_paths, NULL, $timeout);
     }
     catch (\Throwable $error) {
       $this->destroy();
@@ -407,7 +456,7 @@ abstract class StageBase implements LoggerAwareInterface {
 
     // If constraints were changed, update those packages.
     if ($runtime || $dev) {
-      $command = array_merge(['update', '--with-all-dependencies'], $runtime, $dev);
+      $command = array_merge(['update', '--with-all-dependencies', '--optimize-autoloader'], $runtime, $dev);
       $do_stage($command);
     }
     $this->dispatch(new PostRequireEvent($this, $runtime, $dev));
@@ -440,27 +489,24 @@ abstract class StageBase implements LoggerAwareInterface {
     $active_dir = $this->pathFactory->create($this->pathLocator->getProjectRoot());
     $stage_dir = $this->pathFactory->create($this->getStageDirectory());
 
+    $excluded_paths = $this->getPathsToExclude();
+    $event = new PreApplyEvent($this, $excluded_paths);
     // If an error occurs while dispatching the events, ensure that ::destroy()
     // doesn't think we're in the middle of applying the staged changes to the
     // active directory.
-    $event = new PreApplyEvent($this, $this->getPathsToExclude());
     $this->tempStore->set(self::TEMPSTORE_APPLY_TIME_KEY, $this->time->getRequestTime());
-    $this->dispatch($event, $this->setNotApplying());
+    $this->dispatch($event, $this->setNotApplying(...));
 
     // Create a marker file so that we can tell later on if the commit failed.
     $this->failureMarker->write($this, $this->getFailureMarkerMessage());
-    // Exclude the failure file from the commit operation.
-    $paths_to_exclude = new PathList($event->getExcludedPaths());
-    $paths_to_exclude->add([
-      str_replace($this->pathLocator->getProjectRoot() . DIRECTORY_SEPARATOR, '', $this->failureMarker->getPath()),
-    ]);
 
     try {
-      $this->committer->commit($stage_dir, $active_dir, $paths_to_exclude, NULL, $timeout);
+      $this->committer->commit($stage_dir, $active_dir, $excluded_paths, NULL, $timeout);
     }
     catch (InvalidArgumentException | PreconditionException $e) {
       // The commit operation has not started yet, so we can clear the failure
-      // marker.
+      // marker and release the flag that says we're applying.
+      $this->setNotApplying();
       $this->failureMarker->clear();
       $this->rethrowAsStageException($e);
     }
@@ -469,7 +515,7 @@ abstract class StageBase implements LoggerAwareInterface {
       // is in an indeterminate state. Release the flag which says we're still
       // applying, because in this situation, the site owner should probably
       // restore everything from a backup.
-      $this->setNotApplying()();
+      $this->setNotApplying();
       // Update the marker file with the information from the throwable.
       $this->failureMarker->write($this, $this->getFailureMarkerMessage(), $throwable);
       throw new ApplyFailedException($this, $this->failureMarker->getMessage(), $throwable->getCode(), $throwable);
@@ -480,15 +526,9 @@ abstract class StageBase implements LoggerAwareInterface {
 
   /**
    * Returns a closure that marks this stage as no longer being applied.
-   *
-   * @return \Closure
-   *   A closure that, when called, marks this stage as no longer in the process
-   *   of being applied to the active directory.
    */
-  private function setNotApplying(): \Closure {
-    return function (): void {
-      $this->tempStore->delete(self::TEMPSTORE_APPLY_TIME_KEY);
-    };
+  private function setNotApplying(): void {
+    $this->tempStore->delete(self::TEMPSTORE_APPLY_TIME_KEY);
   }
 
   /**
@@ -513,7 +553,7 @@ abstract class StageBase implements LoggerAwareInterface {
     // unlikely to call newly added code during the current request.
     $this->eventDispatcher = \Drupal::service('event_dispatcher');
 
-    $release_apply = $this->setNotApplying();
+    $release_apply = $this->setNotApplying(...);
     $this->dispatch(new PostApplyEvent($this), $release_apply);
     $release_apply();
   }
@@ -539,26 +579,16 @@ abstract class StageBase implements LoggerAwareInterface {
       throw new StageException($this, 'Cannot destroy the stage directory while it is being applied to the active directory.');
     }
 
-    $this->dispatch(new PreDestroyEvent($this));
-    $staging_root = $this->getStagingRoot();
-    // If the stage root directory exists, delete it and everything in it.
-    if (file_exists($staging_root)) {
-      try {
-        $this->fileSystem->deleteRecursive($staging_root, function (string $path): void {
-          $this->fileSystem->chmod($path, 0777);
-        });
-      }
-      catch (FileException) {
-        // Deliberately swallow the exception so that the stage will be marked
-        // as available and the post-destroy event will be fired, even if the
-        // stage directory can't actually be deleted. The file system service
-        // logs the exception, so we don't need to do anything else here.
-      }
+    // If the stage directory exists, queue it to be automatically cleaned up
+    // later by a queue (which may or may not happen during cron).
+    // @see \Drupal\package_manager\Plugin\QueueWorker\Cleaner
+    if ($this->stageDirectoryExists()) {
+      $this->queueFactory->get('package_manager_cleanup')
+        ->createItem($this->getStageDirectory());
     }
 
     $this->storeDestroyInfo($force, $message);
     $this->markAsAvailable();
-    $this->dispatch(new PostDestroyEvent($this));
   }
 
   /**
@@ -598,6 +628,8 @@ abstract class StageBase implements LoggerAwareInterface {
     }
 
     if (isset($error)) {
+      // Ensure the error is logged for post-mortem diagnostics.
+      Error::logException($this->logger, $error);
       if ($on_error) {
         $on_error();
       }
@@ -651,7 +683,7 @@ abstract class StageBase implements LoggerAwareInterface {
       )->render());
     }
 
-    if ($stored_lock === [$unique_id, static::class]) {
+    if ($stored_lock === [$unique_id, static::class, $this->getType()]) {
       $this->lock = $stored_lock;
       return $this;
     }

package_manager/src/StatusCheckTrait.php

@@ -6,7 +6,7 @@ namespace Drupal\package_manager;
 
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
 use Drupal\package_manager\Event\StatusCheckEvent;
-use PhpTuf\ComposerStager\Infrastructure\Factory\Path\PathFactoryInterface;
+use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 /**
@@ -28,7 +28,7 @@ trait StatusCheckTrait {
    *   (optional) The event dispatcher service.
    * @param \Drupal\package_manager\PathLocator $path_locator
    *   (optional) The path locator service.
-   * @param \PhpTuf\ComposerStager\Infrastructure\Factory\Path\PathFactoryInterface $path_factory
+   * @param \PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface $path_factory
    *   (optional) The path factory service.
    *
    * @return \Drupal\package_manager\ValidationResult[]
@@ -42,22 +42,12 @@ trait StatusCheckTrait {
     try {
       $paths_to_exclude_event = new CollectPathsToExcludeEvent($stage, $path_locator, $path_factory);
       $event_dispatcher->dispatch($paths_to_exclude_event);
-      $event = new StatusCheckEvent($stage, $paths_to_exclude_event->getAll());
     }
     catch (\Throwable $throwable) {
-      // We can dispatch the status check event without the paths to exclude,
-      // but it must be set explicitly to NULL, to allow those status checks to
-      // run that do not need the paths to exclude.
-      $event = new StatusCheckEvent($stage, NULL);
-      // Add the error that was encountered so that regardless of any other
-      // validation errors BaseRequirementsFulfilledValidator will stop the
-      // event propagation after the base requirement validators have run.
-      // @see \Drupal\package_manager\Validator\BaseRequirementsFulfilledValidator
-      $event->addErrorFromThrowable($throwable, t('Unable to collect the paths to exclude.'));
+      $paths_to_exclude_event = $throwable;
     }
-
-    $event_dispatcher->dispatch($event);
-    return $event->getResults();
+    $event = new StatusCheckEvent($stage, $paths_to_exclude_event);
+    return $event_dispatcher->dispatch($event)->getResults();
   }
 
 }

package_manager/src/TranslatableStringAdapter.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager;
+
+use Drupal\Core\StringTranslation\TranslatableMarkup;
+use PhpTuf\ComposerStager\API\Translation\Service\TranslatorInterface;
+use PhpTuf\ComposerStager\API\Translation\Value\TranslatableInterface;
+use PhpTuf\ComposerStager\API\Translation\Value\TranslationParametersInterface;
+
+/**
+ * An adapter for interoperable string translation.
+ *
+ * This class is designed to adapt Drupal's style of string translation so it
+ * can be used with the Symfony-inspired architecture used by Composer Stager.
+ *
+ * If this object is cast to a string, it will be translated by Drupal's
+ * translation system. It will ONLY be translated by Composer Stager if the
+ * trans() method is explicitly called.
+ *
+ * @internal
+ *   This is an internal part of Package Manager and may be changed or removed
+ *   at any time without warning. External code should not interact with this
+ *   class.
+ */
+final class TranslatableStringAdapter extends TranslatableMarkup implements TranslatableInterface, TranslationParametersInterface {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getAll(): array {
+    return $this->getArguments();
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function trans(?TranslatorInterface $translator = NULL, ?string $locale = NULL): string {
+    // This method is NEVER used by Drupal to translate the underlying string;
+    // it exists solely for Composer Stager's translation system to
+    // transparently translate Drupal strings using its own architecture.
+    return $translator->trans(
+      $this->getUntranslatedString(),
+      $this,
+      // The 'context' option is the closest analogue to the Symfony-inspired
+      // concept of translation domains.
+      $this->getOption('context'),
+      $locale ?? $this->getOption('langcode'),
+    );
+  }
+
+}

package_manager/src/TranslatableStringFactory.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager;
+
+use Drupal\Core\StringTranslation\TranslationInterface;
+use PhpTuf\ComposerStager\API\Translation\Factory\TranslatableFactoryInterface;
+use PhpTuf\ComposerStager\API\Translation\Service\DomainOptionsInterface;
+use PhpTuf\ComposerStager\API\Translation\Value\TranslatableInterface;
+use PhpTuf\ComposerStager\API\Translation\Value\TranslationParametersInterface;
+
+/**
+ * Creates translatable strings that can interoperate with Composer Stager.
+ *
+ * @internal
+ *   This is an internal part of Package Manager and may be changed or removed
+ *   at any time without warning. External code should not interact with this
+ *   class.
+ */
+final class TranslatableStringFactory implements TranslatableFactoryInterface {
+
+  /**
+   * Constructs a TranslatableStringFactory object.
+   *
+   * @param \PhpTuf\ComposerStager\API\Translation\Factory\TranslatableFactoryInterface $decorated
+   *   The decorated translatable factory service.
+   * @param \Drupal\Core\StringTranslation\TranslationInterface $translation
+   *   The string translation service.
+   */
+  public function __construct(
+    private readonly TranslatableFactoryInterface $decorated,
+    private readonly TranslationInterface $translation,
+  ) {}
+
+  /**
+   * {@inheritdoc}
+   */
+  public function createDomainOptions(): DomainOptionsInterface {
+    return $this->decorated->createDomainOptions();
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function createTranslatableMessage(string $message, ?TranslationParametersInterface $parameters = NULL, ?string $domain = NULL,): TranslatableInterface {
+    return new TranslatableStringAdapter(
+      $message,
+      $parameters?->getAll() ?? [],
+      // TranslatableMarkup's 'context' option is the closest analogue to the
+      // $domain parameter.
+      ['context' => $domain ?? ''],
+      $this->translation,
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function createTranslationParameters(array $parameters = []): TranslationParametersInterface {
+    return $this->decorated->createTranslationParameters($parameters);
+  }
+
+}

package_manager/src/ValidationResult.php

@@ -7,6 +7,7 @@ namespace Drupal\package_manager;
 use Drupal\Component\Assertion\Inspector;
 use Drupal\Core\StringTranslation\TranslatableMarkup;
 use Drupal\system\SystemManager;
+use PhpTuf\ComposerStager\API\Exception\ExceptionInterface;
 
 /**
  * A value object to contain the results of a validation.
@@ -72,7 +73,10 @@ final class ValidationResult {
    * @return static
    */
   public static function createErrorFromThrowable(\Throwable $throwable, ?TranslatableMarkup $summary = NULL): static {
-    return new static(SystemManager::REQUIREMENT_ERROR, [$throwable->getMessage()], $summary, FALSE);
+    // All Composer Stager exceptions are translatable.
+    $is_translatable = $throwable instanceof ExceptionInterface;
+    $message = $is_translatable ? $throwable->getTranslatableMessage() : $throwable->getMessage();
+    return new static(SystemManager::REQUIREMENT_ERROR, [$message], $summary, $is_translatable);
   }
 
   /**

package_manager/src/Validator/ComposerPatchesValidator.php

@@ -4,6 +4,7 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager\Validator;
 
+use Composer\Semver\Semver;
 use Drupal\Component\Serialization\Json;
 use Drupal\Core\Extension\ModuleHandlerInterface;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
@@ -155,15 +156,26 @@ final class ComposerPatchesValidator implements EventSubscriberInterface {
    */
   private function computePatcherStatus(string $working_dir): array {
     $list = $this->composerInspector->getInstalledPackagesList($working_dir);
-    $is_installed = isset($list[static::PLUGIN_NAME]);
+    $installed_version = $list[static::PLUGIN_NAME]?->version;
 
     $info = $this->composerInspector->getRootPackageInfo($working_dir);
     $is_root_requirement = array_key_exists(static::PLUGIN_NAME, $info['requires'] ?? []) || array_key_exists(static::PLUGIN_NAME, $info['devRequires'] ?? []);
 
-    $extra = Json::decode($this->composerInspector->getConfig('extra', $working_dir));
-    $exit_on_failure = $extra['composer-exit-on-patch-failure'] ?? FALSE;
+    // The 2.x version of the plugin always exits with an error if a patch can't
+    // be applied.
+    if ($installed_version && Semver::satisfies($installed_version, '^2')) {
+      $exit_on_failure = TRUE;
+    }
+    else {
+      $extra = Json::decode($this->composerInspector->getConfig('extra', $working_dir));
+      $exit_on_failure = $extra['composer-exit-on-patch-failure'] ?? FALSE;
+    }
 
-    return [$is_installed, $is_root_requirement, $exit_on_failure];
+    return [
+      is_string($installed_version),
+      $is_root_requirement,
+      $exit_on_failure,
+    ];
   }
 
   /**