@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/components/Application.js

@@ -36,16 +36,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Application = exports.GIT_CREDENTIAL_HELPER_PATH = exports.ASIDE_STAGING_DIR = exports.InvalidCredentialEntryError = exports.InvalidCredentialsPropertyError = exports.InvalidInstallTimeoutError = exports.InvalidInstallCommandError = exports.InvalidInstallPropertyError = exports.InvalidPackageIdentifierError = void 0;
+exports.Application = exports.GIT_CREDENTIAL_HELPER_PATH = exports.DEPLOY_STAGING_DIR = exports.ASIDE_STAGING_DIR = exports.InvalidCredentialEntryError = exports.InvalidBranchedDatabasesError = exports.InvalidCredentialsPropertyError = exports.InvalidInstallTimeoutError = exports.InvalidInstallCommandError = exports.InvalidInstallPropertyError = exports.InvalidPackageIdentifierError = void 0;
 exports.assertApplicationConfig = assertApplicationConfig;
+exports.assertIsolationConfig = assertIsolationConfig;
+exports.assertBranchedDatabases = assertBranchedDatabases;
 exports.isSSHAuthFailure = isSSHAuthFailure;
 exports.parseGitReference = parseGitReference;
+exports.packageHasProductionInstallWork = packageHasProductionInstallWork;
+exports.packageHasAutomaticInstallWork = packageHasAutomaticInstallWork;
 exports.readInstalledPackageMetadata = readInstalledPackageMetadata;
 exports.installedPackageMetadataEqual = installedPackageMetadataEqual;
 exports.installedRuntimeChanged = installedRuntimeChanged;
 exports.extractApplication = extractApplication;
+exports.getStagingRetentionMaxCount = getStagingRetentionMaxCount;
+exports.pruneDormantBuilds = pruneDormantBuilds;
+exports.candidateApplicationPath = candidateApplicationPath;
+exports.makeRollbackPlaceholderMovable = makeRollbackPlaceholderMovable;
+exports.publishClaimOwnership = publishClaimOwnership;
+exports.splitAttributionOwners = splitAttributionOwners;
+exports.unsettleableComponentsFromDisk = unsettleableComponentsFromDisk;
+exports.recoverInterruptedActivations = recoverInterruptedActivations;
+exports.reconcileDormantBuilds = reconcileDormantBuilds;
+exports.markCandidateComplete = markCandidateComplete;
+exports.activateCandidateApplication = activateCandidateApplication;
+exports.buildCandidateApplication = buildCandidateApplication;
+exports.recoverInterruptedComponentExtractions = recoverInterruptedComponentExtractions;
+exports.recoverInterruptedComponentExtraction = recoverInterruptedComponentExtraction;
+exports.retireComponentExtractionStaging = retireComponentExtractionStaging;
+exports.dropComponentDirectory = dropComponentDirectory;
+exports.packageManagerInstallArguments = packageManagerInstallArguments;
 exports.installApplication = installApplication;
 exports.derivePackageIdentifier = derivePackageIdentifier;
+exports.shouldPackLocalDirectory = shouldPackLocalDirectory;
 exports.prepareApplication = prepareApplication;
 exports.installApplications = installApplications;
 exports.recordApplicationPreparation = recordApplicationPreparation;
@@ -59,6 +81,7 @@ exports.terminateProcessTree = terminateProcessTree;
 exports.getEnvBuiltInComponents = getEnvBuiltInComponents;
 const configUtils_ts_1 = require("../config/configUtils.js");
 const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const hdbError_ts_1 = require("../utility/errors/hdbError.js");
 const harper_logger_ts_1 = __importStar(require("../utility/logging/harper_logger.js"));
 const deployLifecycle_ts_1 = require("./deployLifecycle.js");
 const componentPreparationLock_ts_1 = require("./componentPreparationLock.js");
@@ -109,6 +132,12 @@ class InvalidCredentialsPropertyError extends TypeError {
     }
 }
 exports.InvalidCredentialsPropertyError = InvalidCredentialsPropertyError;
+class InvalidBranchedDatabasesError extends TypeError {
+    constructor(applicationName, detail) {
+        super(`Invalid 'branchedDatabases' for application ${applicationName}: ${detail}`);
+    }
+}
+exports.InvalidBranchedDatabasesError = InvalidBranchedDatabasesError;
 class InvalidCredentialEntryError extends TypeError {
     constructor(applicationName) {
         super(`Invalid 'credentials' entry for application ${applicationName}: expected a { registry, secret, scope? } ` +
@@ -117,6 +146,15 @@ class InvalidCredentialEntryError extends TypeError {
 }
 exports.InvalidCredentialEntryError = InvalidCredentialEntryError;
 function assertApplicationConfig(applicationName, applicationConfig) {
+    // The deploy staging directory holds a candidate tree under the component's own name beside dot-prefixed
+    // control files, so a dot-prefixed component name collides with one of them — and an application named
+    // `.activation.json` puts its tree on the journal path, where the journal write takes EEXIST as "a retry
+    // of this activation" and the swap proceeds with no journal at all. Rejected HERE rather than tolerated
+    // downstream: nothing else validates a root-config application key.
+    if (!isJoinableComponentName(applicationName)) {
+        throw new Error(`Invalid application name '${applicationName}': it must be a single path segment and must not begin ` +
+            `with a dot, which is reserved for Harper's own deploy control files`);
+    }
     if (typeof applicationConfig.package !== 'string') {
         throw new InvalidPackageIdentifierError(applicationName, applicationConfig.package);
     }
@@ -162,6 +200,44 @@ function assertApplicationConfig(applicationName, applicationConfig) {
             }
         }
     }
+    assertBranchedDatabases(applicationName, applicationConfig.branchedDatabases);
+    assertIsolationConfig(applicationName, applicationConfig.isolated);
+}
+function assertIsolationConfig(applicationName, isolated) {
+    if (isolated !== undefined && typeof isolated !== 'boolean') {
+        throw new TypeError(`Invalid 'isolated' for application ${applicationName}: expected a boolean, got ${typeof isolated}`);
+    }
+}
+/**
+ * A branch that cannot be honoured fails the application's load: falling back would hand it the
+ * shared database it asked not to have, with no signal that it happened.
+ */
+function assertBranchedDatabases(applicationName, value) {
+    if (value === undefined || value === true)
+        return;
+    if (!Array.isArray(value)) {
+        throw new InvalidBranchedDatabasesError(applicationName, `expected an array or true, got ${typeof value}`);
+    }
+    const seen = new Set();
+    for (const name of value) {
+        if (typeof name !== 'string' || name === '') {
+            throw new InvalidBranchedDatabasesError(applicationName, `expected database names, got ${typeof name}`);
+        }
+        // A branch is a directory named by this value; a separator or traversal segment would escape
+        // the reserved branch root.
+        if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
+            throw new InvalidBranchedDatabasesError(applicationName, `'${name}' is not a usable database name`);
+        }
+        // `system` carries the instance's own catalog, users and jobs; a private fork of it would give
+        // the application a divergent view of the instance rather than of its data.
+        if (name === 'system') {
+            throw new InvalidBranchedDatabasesError(applicationName, `the 'system' database cannot be branched`);
+        }
+        if (seen.has(name)) {
+            throw new InvalidBranchedDatabasesError(applicationName, `'${name}' is listed more than once`);
+        }
+        seen.add(name);
+    }
 }
 /**
  * Returns true when npm/git stderr indicates an SSH authentication failure —
@@ -406,10 +482,42 @@ async function runNpmPack(application, packArgs, cwd, gitCredentialEnv) {
 // during a deploy swap (see extractApplication). The leading dot keeps
 // loadComponentDirectories from loading its contents as components.
 exports.ASIDE_STAGING_DIR = '.deploy-aside';
+// Hidden directory under the components root holding per-deployment candidate builds. A candidate is
+// extracted, installed AND validated here, and only then renamed into the live path, so the previous
+// version keeps serving through the slow, failure-prone work. Dot-prefixed so the three scans over the
+// components root (componentLoader, componentEnvPrepass, resolvePreload) skip it.
+exports.DEPLOY_STAGING_DIR = '.deploy-staging';
+const IN_PROGRESS_ASIDE_PREFIX = '.in-progress-';
+const RETIRED_ASIDE_PREFIX = '.retired-';
+const PRIOR_ABSENT_RECORD_SUFFIX = '-prior-absent';
 const DEFAULT_COMMAND_TIMEOUT_MS = 60 * 60 * 1000;
 const COMPONENT_PREPARATION_WAIT_MARGIN_MS = 30000;
+const COMPONENT_RECOVERY_WAIT_TIMEOUT_MS = 30000;
+const COMPONENT_RECOVERY_TRY_TIMEOUT_MS = 250;
+/**
+ * Lock terms for the boot-time activation scan. It runs before every component load on every thread, so it
+ * probes rather than queues: the default is a two-hour wait that RENEWS while the holder is alive, which
+ * would park a respawning worker behind a deploy's `npm install` and load no components at all until it
+ * finished. A held lock means a live deploy, and a live deploy settles its own journal.
+ */
+const RECOVERY_LOCK_WAIT = {
+    timeoutMs: COMPONENT_RECOVERY_TRY_TIMEOUT_MS,
+    renewTimeoutWhileOwnerAlive: false,
+};
+const COMPONENT_RECOVERY_LOCK_PURPOSE = 'component-recovery';
 const MAX_GIT_EXTRACTION_COMMANDS = 4;
 const MAX_INSTALL_COMMANDS = 2;
+const PRODUCTION_DEPENDENCY_FIELDS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+const INSTALL_LIFECYCLE_SCRIPTS = new Set([
+    'preinstall',
+    'install',
+    'postinstall',
+    'prepublish',
+    'preprepare',
+    'prepare',
+    'postprepare',
+    'dependencies',
+]);
 // The credential helper git executes for a private git-reference deploy. It ships alongside this
 // module (both in source and in dist), holds no secret, and is inert without a live session.
 exports.GIT_CREDENTIAL_HELPER_PATH = (0, node_path_1.join)(__dirname, 'gitCredentialHelper.js');
@@ -421,6 +529,47 @@ const PACKAGE_LOCK_FILES = [
     'bun.lock',
     'bun.lockb',
 ];
+function dependencyFieldHasWork(packageJSON, field) {
+    if (!packageJSON || typeof packageJSON !== 'object' || !Object.hasOwn(packageJSON, field))
+        return false;
+    const value = packageJSON[field];
+    return !value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length > 0;
+}
+function packageHasProductionInstallWork(packageJSON) {
+    if (packageJSON === undefined)
+        return false;
+    if (!packageJSON || typeof packageJSON !== 'object' || Array.isArray(packageJSON))
+        return true;
+    if (PRODUCTION_DEPENDENCY_FIELDS.some((field) => dependencyFieldHasWork(packageJSON, field)))
+        return true;
+    if (!Object.hasOwn(packageJSON, 'workspaces'))
+        return false;
+    const workspaces = packageJSON.workspaces;
+    if (Array.isArray(workspaces))
+        return workspaces.length > 0;
+    if (!workspaces || typeof workspaces !== 'object' || !Object.hasOwn(workspaces, 'packages'))
+        return true;
+    return !Array.isArray(workspaces.packages) || workspaces.packages.length > 0;
+}
+function packageHasExplicitNonNpmManager(packageJSON) {
+    const packageManager = packageJSON?.devEngines?.packageManager;
+    return !!packageManager && packageManager.name !== 'npm';
+}
+function packageHasAutomaticInstallWork(packageJSON) {
+    return packageHasProductionInstallWork(packageJSON) || packageHasExplicitNonNpmManager(packageJSON);
+}
+function packageHasAllowedInstallLifecycleWork(packageJSON) {
+    if (!packageJSON || typeof packageJSON !== 'object' || !Object.hasOwn(packageJSON, 'scripts'))
+        return false;
+    const scripts = packageJSON.scripts;
+    if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts))
+        return true;
+    return [...INSTALL_LIFECYCLE_SCRIPTS].some((name) => {
+        if (!Object.hasOwn(scripts, name))
+            return false;
+        return typeof scripts[name] !== 'string' || scripts[name].trim().length > 0;
+    });
+}
 async function readInstalledPackageMetadata(directory) {
     const files = new Map();
     let readable = true;
@@ -456,13 +605,7 @@ async function readInstalledPackageMetadata(directory) {
         files,
         readable,
         hasLockfile: PACKAGE_LOCK_FILES.some((filename) => files.has(filename)),
-        hasInstallableDependencies: ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].some((field) => {
-            const dependencies = packageJSON?.[field];
-            return (typeof dependencies === 'object' &&
-                dependencies !== null &&
-                !Array.isArray(dependencies) &&
-                Object.keys(dependencies).length > 0);
-        }),
+        hasInstallableDependencies: packageHasAutomaticInstallWork(packageJSON),
     };
 }
 function installedPackageMetadataEqual(previous, current) {
@@ -489,26 +632,8 @@ function canonicalizeJSON(value) {
         canonical[key] = canonicalizeJSON(value[key]);
     return canonical;
 }
-/**
- * Extract an application given payload (content of the application) or package (npm-compatible identifier to the application).
- *
- * Only one of `application.payload` or `application.package` should be specified; otherwise, an error is thrown.
- *
- * Writes the application to the configured components root directory using the `application.name` and overwrites any existing directory.
- *
- * This method may be called from any Harper thread. Same-component calls are serialized across
- * threads by the preparation lock below.
- */
-async function extractApplication(application, deferCommit = false) {
-    // Can't specify neither
-    if (!application.payload && !application.packageIdentifier) {
-        throw new Error('Either payload or package must be provided');
-    }
-    // Can't specify both
-    if (application.payload && application.packageIdentifier) {
-        throw new Error('Both payload and package cannot be provided');
-    }
-    // Resolve the tarball from the input
+/** Resolve `payload` or `package` into a tarball stream. Touches neither the live tree nor staging. */
+async function resolveApplicationTarball(application) {
     let tarballPath;
     let tarball;
     let shouldDeleteTarball = false;
@@ -530,6 +655,8 @@ async function extractApplication(application, deferCommit = false) {
     else {
         // Given a package, there are a a couple options
         const parentDirPath = (0, node_path_1.dirname)(application.dirPath);
+        let packageIdentifierForPack = application.packageIdentifier;
+        let packageNeedsPacking = true;
         // If the package identifier is a file path we need to check if its a tarball or a directory
         if (application.packageIdentifier.startsWith('file:')) {
             const packagePath = application.packageIdentifier.slice(5);
@@ -537,20 +664,29 @@ async function extractApplication(application, deferCommit = false) {
                 // Have to remove the 'file:' prefix in order to use fs methods
                 const stats = await (0, promises_1.stat)(packagePath);
                 if (stats.isDirectory()) {
-                    // If its a directory, symlink
-                    await (0, promises_1.symlink)(packagePath, application.dirPath, 'dir');
-                    // And return early since we're done; no extraction needed
-                    return;
+                    if (!application.packLocalDirectory) {
+                        // Reported, not performed — the caller decides where the link goes, so a candidate build
+                        // links at the candidate path rather than onto the live one.
+                        return { kind: 'link', sourceDirPath: packagePath };
+                    }
+                    // Bare absolute Windows directory inputs historically materialize a copy through npm pack;
+                    // explicit file: and relative directories remain live links.
+                    packageIdentifierForPack = packagePath;
+                    application.logger.debug?.('Packaging local component directory instead of linking it on Windows');
                 }
-                if (!stats.isFile()) {
-                    throw new Error(`File path specified in package identifier is not a file or directory: ${packagePath}`);
+                else {
+                    if (!stats.isFile()) {
+                        throw new Error(`File path specified in package identifier is not a file or directory: ${packagePath}`);
+                    }
+                    // If its a file, we assume it can be unzipped and extracted.
+                    // We are using maybe-gunzip to handle both gzipped and non-gzipped tarballs
+                    // And then we are happy to let the `tar-fs` library handle the extraction.
+                    // Maybe worth adding some detection or at least some error handling if that step below fails.
+                    tarballPath = packagePath;
+                    tarball = (0, node_fs_1.createReadStream)(tarballPath);
+                    packageNeedsPacking = false;
+                    application.logger.debug?.('Using local component archive directly without npm pack');
                 }
-                // If its a file, we assume it can be unzipped and extracted.
-                // We are using maybe-gunzip to handle both gzipped and non-gzipped tarballs
-                // And then we are happy to let the `tar-fs` library handle the extraction.
-                // Maybe worth adding some detection or at least some error handling if that step below fails.
-                tarballPath = packagePath;
-                tarball = (0, node_fs_1.createReadStream)(tarballPath);
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
@@ -561,7 +697,7 @@ async function extractApplication(application, deferCommit = false) {
                 }
             }
         }
-        else {
+        if (packageNeedsPacking) {
             // `npm pack --json` writes a JSON array describing the packed tarball(s). This is also the
             // spawn that clones a git-reference package, so it is the only one given the git credential
             // environment.
@@ -584,188 +720,2706 @@ async function extractApplication(application, deferCommit = false) {
             // packGitReferenceWithoutScripts), which is exactly what Node 22's bundled npm ships. For a
             // recognized git-reference identifier, clone and pack it ourselves with scripts stripped
             // instead, sidestepping that npm code path entirely.
-            const gitRef = allowScripts ? null : parseGitReference(application.packageIdentifier);
-            if (!allowScripts && !gitRef && looksLikeGitReference(application.packageIdentifier)) {
+            const gitRef = allowScripts ? null : parseGitReference(packageIdentifierForPack);
+            if (!allowScripts && !gitRef && looksLikeGitReference(packageIdentifierForPack)) {
                 // Recognized as git, but a form the reclone-and-strip-scripts path above can't safely
                 // handle (a `#path:` committish, or a hosted shorthand other than a plain `owner/repo`) —
                 // fail loudly rather than silently falling through to the unreliable `npm pack
                 // --ignore-scripts` below.
-                throw new Error(`Cannot deploy git-reference package '${application.packageIdentifier}' with install scripts disallowed: this identifier's form (e.g. a '#path:' committish, or a hosted shorthand other than a plain 'owner/repo') isn't one this repo's script-suppression handling supports. Set install.allowInstallScripts to true, or use a plain git URL with a branch/tag/commit committish instead.`);
+                throw new Error(`Cannot deploy git-reference package '${packageIdentifierForPack}' with install scripts disallowed: this identifier's form (e.g. a '#path:' committish, or a hosted shorthand other than a plain 'owner/repo') isn't one this repo's script-suppression handling supports. Set install.allowInstallScripts to true, or use a plain git URL with a branch/tag/commit committish instead.`);
+            }
+            if (gitRef) {
+                tarballPath = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath);
+            }
+            else {
+                const packArgs = ['pack', '--json', packageIdentifierForPack];
+                if (!allowScripts) {
+                    packArgs.push('--ignore-scripts');
+                }
+                else if (application.gitCredentialEnv) {
+                    application.logger.warn(`Deploying ${application.name} from a git reference with install scripts enabled: the repository's ` +
+                        `prepare/build scripts and its dependencies' install scripts run on this node during the clone and ` +
+                        `can read the git credential. Unset install_allow_scripts to keep the credential out of their reach.`);
+                }
+                tarballPath = await runNpmPack(application, packArgs, parentDirPath, application.gitCredentialEnv);
+            }
+            shouldDeleteTarball = true;
+            tarball = (0, node_fs_1.createReadStream)(tarballPath);
+        }
+    }
+    return { kind: 'tarball', tarball, tarballPath, shouldDeleteTarball };
+}
+/**
+ * Extract a tarball into `targetDirPath`, flattening the single wrapping directory npm pack produces.
+ * `scratchDirPath` must be on the same filesystem as the target: the flatten is done by renaming the
+ * wrapper out and back rather than copying, so it stays atomic per entry. Windows moves the children
+ * individually because renaming a directory over its own parent's path fails there.
+ */
+async function extractTarballInto(tarball, targetDirPath, scratchDirPath) {
+    await (0, promises_1.mkdir)(targetDirPath, { recursive: true });
+    await (0, promises_2.pipeline)(tarball, (0, gunzip_maybe_1.default)(), (0, tar_fs_1.extract)(targetDirPath));
+    const extracted = await (0, promises_1.readdir)(targetDirPath, { withFileTypes: true });
+    if (extracted.length === 1 && extracted[0].isDirectory()) {
+        const topLevelDirPath = (0, node_path_1.join)(targetDirPath, extracted[0].name);
+        if (process.platform === 'win32') {
+            for (const childName of await (0, promises_1.readdir)(topLevelDirPath)) {
+                await (0, promises_1.rename)((0, node_path_1.join)(topLevelDirPath, childName), (0, node_path_1.join)(targetDirPath, childName));
+            }
+            await (0, promises_1.rmdir)(topLevelDirPath);
+        }
+        else {
+            const tempDirPath = (0, node_path_1.join)(scratchDirPath, `.normalize-${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
+            await (0, promises_1.rename)(topLevelDirPath, tempDirPath);
+            await (0, promises_1.rmdir)(targetDirPath);
+            await (0, promises_1.rename)(tempDirPath, targetDirPath);
+            return tempDirPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract an application given payload (content of the application) or package (npm-compatible identifier to the application).
+ *
+ * Only one of `application.payload` or `application.package` should be specified; otherwise, an error is thrown.
+ *
+ * Writes the application to the configured components root directory using the `application.name` and overwrites any existing directory.
+ *
+ * This method may be called from any Harper thread. Same-component calls are serialized across
+ * threads by the preparation lock below.
+ */
+async function extractApplication(application, deferCommit = false) {
+    // Can't specify neither
+    if (!application.payload && !application.packageIdentifier) {
+        throw new Error('Either payload or package must be provided');
+    }
+    // Can't specify both
+    if (application.payload && application.packageIdentifier) {
+        throw new Error('Both payload and package cannot be provided');
+    }
+    // Resolve the tarball from the input
+    const resolved = await resolveApplicationTarball(application);
+    if (resolved.kind === 'link') {
+        // Unchanged behavior for this path: a `file:` directory is linked in place, no extraction.
+        await (0, promises_1.symlink)(resolved.sourceDirPath, application.dirPath, 'dir');
+        return;
+    }
+    const { tarball, tarballPath, shouldDeleteTarball } = resolved;
+    // Replace any existing component directory atomically instead of clearing it in
+    // place. A previous version's worker can still be running and actively writing
+    // into this directory — e.g. a live Next.js app writing into `.next/cache` — and
+    // an in-place recursive rm races that writer: rm empties `.next`, then its leaf
+    // `rmdir('.next')` fails with ENOTEMPTY because the worker just re-created a cache
+    // entry. (`force: true` only suppresses ENOENT; ENOTEMPTY is not retried unless
+    // `maxRetries` is set, and a continuously-writing app would outlast retries
+    // anyway.) Renaming the old directory aside is atomic and immune to the race: the
+    // still-running worker keeps writing into the renamed inode harmlessly until it's
+    // replaced on restart. The aside remains the rollback/recovery record until commit
+    // marks it retired and cleanup removes it.
+    //
+    // The aside lives under a hidden, component-scoped staging directory inside the
+    // components root: same filesystem as the source so the rename stays atomic, the
+    // leading dot keeps loadComponentDirectories from picking it up as a phantom
+    // component, and the per-component path means a sibling component never collides
+    // with (or sweeps) another's aside.
+    const asideStagingDir = extractionStagingDirectory(application.dirPath);
+    const transactionPaths = new Set();
+    let asidePath;
+    let recoveryRecordPath;
+    try {
+        await ensureExtractionStagingDirectory(asideStagingDir);
+        await recoverOrCleanupStaleExtractionPaths(application, asideStagingDir);
+        let componentExists = true;
+        try {
+            await (0, promises_1.lstat)(application.dirPath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            componentExists = false;
+        }
+        if (componentExists) {
+            await ensureExtractionStagingDirectory(asideStagingDir);
+            asidePath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
+            await (0, promises_1.rename)(application.dirPath, asidePath);
+            transactionPaths.add(asidePath);
+            recoveryRecordPath = asidePath;
+        }
+        else {
+            await ensureExtractionStagingDirectory(asideStagingDir);
+            recoveryRecordPath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}${PRIOR_ABSENT_RECORD_SUFFIX}`);
+            await (0, promises_1.writeFile)(recoveryRecordPath, '', { flag: 'wx', mode: 0o600 });
+            transactionPaths.add(recoveryRecordPath);
+        }
+        if (asidePath)
+            application.isNewComponent = false;
+        try {
+            // The scratch dir for the pack-wrapper flatten has to be on the component root's filesystem, and
+            // is a transaction path so a crash mid-flatten is cleaned up with the rest.
+            await ensureExtractionStagingDirectory(asideStagingDir);
+            const normalizeTempPath = await extractTarballInto(tarball, application.dirPath, asideStagingDir);
+            if (normalizeTempPath)
+                transactionPaths.add(normalizeTempPath);
+        }
+        catch (error) {
+            try {
+                await rollbackExtractedDirectory(application, asideStagingDir, asidePath, transactionPaths, false);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], `Failed to extract ${application.name}: ${errorMessage(error)}; ` +
+                    `also failed to restore its previous component directory: ${errorMessage(rollbackError)}`);
+            }
+            throw error;
+        }
+    }
+    finally {
+        if (!tarball.destroyed)
+            tarball.destroy();
+        if (shouldDeleteTarball && tarballPath) {
+            await (0, promises_1.rm)(tarballPath, { force: true }).catch((error) => application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error));
+        }
+    }
+    let settled = false;
+    const transaction = {
+        async commit() {
+            if (settled)
+                return;
+            const retiredMarkerPath = await retireExtractionAside(recoveryRecordPath);
+            transactionPaths.add(retiredMarkerPath);
+            settled = true;
+            await cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+        },
+        async rollback() {
+            if (settled)
+                return;
+            await rollbackExtractedDirectory(application, asideStagingDir, asidePath, transactionPaths, true);
+            settled = true;
+        },
+    };
+    if (deferCommit)
+        return transaction;
+    await transaction.commit();
+}
+// Written into a candidate's deployment directory once its build and its validation have BOTH succeeded.
+// Roll-forward authority: recovery may activate an interrupted candidate only if this is present.
+// Every control file is dot-prefixed, and `isJoinableComponentName` rejects a leading dot: a deployment
+// directory holds the candidate tree under the COMPONENT'S name beside these, so an undotted name would
+// share that namespace. A component named `activation.json` would put its tree on the journal path, the
+// journal write would take EEXIST as "a retry of this activation", and the swap would proceed with no
+// journal to hold the legacy pass back; one named `unsettled` would make every settle throw on a
+// non-recursive `rm` of a directory. `assertApplicationConfig` rejects any name `isJoinableComponentName`
+// rejects, so the collision is unreachable from a root-config key as well as from a deploy.
+const CANDIDATE_COMPLETE_MARKER = '.complete';
+// Records activation intent beside the candidate, so recovery finishes or undoes the whole transaction —
+// tree and configuration together — instead of inferring intent from filesystem shape alone.
+const ACTIVATION_JOURNAL = '.activation.json';
+// The component this deployment directory belongs to, as plain text in its own file. Redundant with the
+// journal on purpose: after the swap the candidate has moved to the live path, so a journal that cannot be
+// parsed leaves nothing to infer the component from — and a failure keyed by deployment id fails NOTHING
+// closed, letting the component load over state nobody reconciled.
+const CANDIDATE_COMPONENT_FILE = '.component';
+// Written by main-thread recovery when it could not settle an activation whose journal is otherwise
+// well-formed. Workers cannot infer that case: a well-formed journal is indistinguishable from one belonging
+// to a deploy in flight, so without a record they would treat an unsettled component as healthy and load it.
+const UNSETTLED_MARKER = '.unsettled';
+// Everything the build decided that a later activation cannot re-derive: the root-config entry to publish,
+// whether the installation is opaque to metadata comparison, and the isolation intent that was admitted.
+// Written before `.complete`, so the marker vouches for it. An OPTIONAL record would not do: it could not
+// distinguish a payload build, which owns no root config, from a package build whose record was lost.
+const CANDIDATE_ARTIFACT_FILE = '.artifact.json';
+const ACTIVATION_JOURNAL_VERSION = 1;
+const ARTIFACT_DESCRIPTOR_VERSION = 1;
+const DEFAULT_STAGING_RETENTION_MAX_COUNT = 5;
+/** `deployment_stagingRetention_maxCount`; 0 keeps none. Only a number or numeric string counts, so `true`/`[]`/blank cannot become "keep nothing". */
+function getStagingRetentionMaxCount() {
+    const configured = (0, configUtils_ts_1.getConfigValue)(hdbTerms_ts_1.CONFIG_PARAMS.DEPLOYMENT_STAGINGRETENTION_MAXCOUNT);
+    if (typeof configured !== 'number' && typeof configured !== 'string')
+        return DEFAULT_STAGING_RETENTION_MAX_COUNT;
+    if (typeof configured === 'string' && configured.trim() === '')
+        return DEFAULT_STAGING_RETENTION_MAX_COUNT;
+    const parsed = Number(configured);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : DEFAULT_STAGING_RETENTION_MAX_COUNT;
+}
+async function presentOrAbsent(path) {
+    return (0, promises_1.lstat)(path).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+}
+/**
+ * A dormant build: complete, tree present, no journal. Activation writes `.complete` moments before its
+ * journal under the owner's preparation lock, so only a read under that lock is a verdict. A stale
+ * `.unsettled` makes it residue instead, since only removing the directory clears that marker for workers.
+ * Only ENOENT is absence; any other read error propagates so the caller preserves the entry.
+ */
+async function dormantBuildAt(deploymentDirPath, owner) {
+    const complete = await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER));
+    if (!complete)
+        return undefined;
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER)))
+        return undefined;
+    const tree = await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, owner));
+    if (!tree || !(tree.isDirectory() || tree.isSymbolicLink()))
+        return undefined;
+    return { deploymentDirPath, deploymentId: (0, node_path_1.basename)(deploymentDirPath), completedAt: complete.mtimeMs };
+}
+/**
+ * Remove the oldest dormant builds beyond `maxCount`. The caller must hold the component's preparation lock;
+ * every catalogued build is re-derived under it before the kept set is chosen, so a catalog read unlocked
+ * cannot hold or miss a slot. Never throws: a failure must neither fail a component closed nor replace a
+ * deploy's own error.
+ *
+ * `pinnedDeploymentId` is never evicted. A delayed activation runs this preamble under the same lock it is
+ * about to activate under, so without the pin retention would delete the artifact the request named —
+ * immediately, when the knob is `0`. The pin is applied after the kept set is chosen, so a pinned build in
+ * the eviction tail leaves `maxCount + 1` on disk for the life of the request; the next preamble that does
+ * not pin it brings the count back down.
+ */
+async function pruneDormantBuilds(componentName, builds, maxCount, pinnedDeploymentId) {
+    const current = [];
+    for (const build of builds) {
+        try {
+            const fresh = await dormantBuildAt(build.deploymentDirPath, componentName);
+            if (fresh && !(await presentOrAbsent((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL))))
+                current.push(fresh);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Leaving deploy staging ${build.deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+    const evictions = current
+        .sort((left, right) => right.completedAt - left.completedAt ||
+        (left.deploymentId < right.deploymentId ? -1 : left.deploymentId > right.deploymentId ? 1 : 0))
+        .slice(Math.max(0, maxCount))
+        .filter((build) => build.deploymentId !== pinnedDeploymentId);
+    for (const build of evictions) {
+        try {
+            await (0, promises_1.rm)(build.deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            harper_logger_ts_1.default.debug?.(`Pruned dormant staged build ${build.deploymentId} of ${componentName} beyond deployment_stagingRetention_maxCount=${maxCount}`);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Could not prune dormant staged build ${build.deploymentDirPath} of ${componentName}; it remains beyond ` +
+                `deployment_stagingRetention_maxCount=${maxCount}:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+}
+/** Every dormant build a component owns; an unreadable directory is left out and logged. */
+async function dormantBuildsOf(componentsRootDirPath, componentName) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const builds = [];
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        try {
+            if ((await candidateComponentName(deploymentDirPath)) !== componentName)
+                continue;
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL)))
+                continue;
+            const build = await dormantBuildAt(deploymentDirPath, componentName);
+            if (build)
+                builds.push(build);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Leaving deploy staging ${deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+    return builds;
+}
+/**
+ * Best-effort fsync of a directory. Best-effort by necessity — Node cannot fsync a directory on Windows —
+ * which is why roll-forward requires journal + candidate + complete marker to all be observable: a lost
+ * directory update then degrades to a roll back, never to a wrong decision. See DESIGN.md.
+ */
+async function syncDirectory(dirPath) {
+    let handle;
+    try {
+        handle = await (0, promises_1.open)(dirPath, 'r');
+    }
+    catch (error) {
+        // Same split as `sync` below and as the file path: Windows cannot open a directory for fsync at all,
+        // and a directory removed by cleanup is not a fault either — but an EIO opening it is.
+        if (!isUnsupportedSync(error) && error?.code !== 'ENOENT')
+            throw error;
+        harper_logger_ts_1.default.trace?.(`Directory sync of ${dirPath} unavailable: ${errorMessage(error)}`);
+        return;
+    }
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        // A platform that will not sync directories is tolerated, a storage failure is not: suppressing
+        // EIO/ENOSPC here would let a lost directory entry look durable. The `finally` closes the handle.
+        if (!isUnsupportedSync(error))
+            throw error;
+        harper_logger_ts_1.default.trace?.(`Directory sync of ${dirPath} unsupported: ${errorMessage(error)}`);
+    }
+    finally {
+        // Swallowed: this runs outside any compensation block, so a rejecting close would surface as an
+        // activation failure for something already best-effort.
+        await handle.close().catch((error) => harper_logger_ts_1.default.trace?.(`Closing ${dirPath} failed: ${errorMessage(error)}`));
+    }
+}
+/**
+ * A rename changes an entry in BOTH parents, so both are synced: a surviving source entry reads as
+ * "candidate still there" and would roll an already-completed activation forward twice.
+ */
+async function syncRenameParents(fromPath, toPath) {
+    const parents = new Set([(0, node_path_1.dirname)(fromPath), (0, node_path_1.dirname)(toPath)]);
+    for (const parent of parents)
+        await syncDirectory(parent);
+}
+// Deliberately NOT `EEXIST`/`ENOTEMPTY`/`ENOTDIR`/`EISDIR`: those say the destination exists, which
+// nothing here clears between attempts, so waiting on them would only delay reporting a tree something
+// recreated — the case `settleInterruptedActivation` fails closed rather than guessing.
+// `rollbackExtractedDirectory` does retry them, because its placeholder logic repairs the destination.
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const RENAME_RETRY_BUDGET_MS = 5000;
+const RENAME_RETRY_INITIAL_DELAY_MS = 10;
+const RENAME_RETRY_MAX_DELAY_MS = 500;
+/**
+ * Rename, waiting out a holder that has not let go yet — on Windows a rename is refused outright while
+ * anything still has a handle in the source tree.
+ *
+ * `onBackoff` replaces the sleep between attempts; `deadline` lets a rename it performs share this
+ * call's budget instead of opening its own.
+ */
+async function renameThroughTransientHolder(fromPath, toPath, options = {}) {
+    const deadline = options.deadline ?? performance.now() + RENAME_RETRY_BUDGET_MS;
+    let delayMs = RENAME_RETRY_INITIAL_DELAY_MS;
+    for (let attempts = 1;; attempts++) {
+        try {
+            await (0, promises_1.rename)(fromPath, toPath);
+            if (attempts > 1) {
+                harper_logger_ts_1.default.warn(`Renamed ${fromPath} to ${toPath} only on attempt ${attempts}; something was holding it`);
+            }
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (!TRANSIENT_RENAME_CODES.has(code))
+                throw error;
+            if (performance.now() >= deadline) {
+                // Which side was still there separates a holder on the source from a destination something
+                // recreated, and neither survives on the rethrown error. A failed probe reports its own code:
+                // an `EPERM` reading the destination is itself evidence, and calling it absent would send the
+                // next investigation the wrong way.
+                const state = async (path) => (0, promises_1.lstat)(path).then(() => 'present', (probeError) => probeError?.code ?? 'unreadable');
+                harper_logger_ts_1.default.warn(`Could not rename ${fromPath} to ${toPath}: ${code} after ${attempts} attempts ` +
+                    `(source ${await state(fromPath)}, destination ${await state(toPath)})`);
+                throw error;
+            }
+            if (options.onBackoff)
+                await options.onBackoff(delayMs, deadline);
+            else
+                await (0, promises_3.setTimeout)(delayMs);
+            delayMs = Math.min(delayMs * 2, RENAME_RETRY_MAX_DELAY_MS);
+        }
+    }
+}
+/**
+ * Write a control file so its final name NEVER exists with partial contents. Opening the final path with
+ * `wx` publishes the directory entry before anything is written, so a crash in between leaves a zero-byte
+ * file — which for the journal means "unreadable", failing a component closed over a deploy that had not
+ * actually started. Contents land in a temp name, are fsynced, and only then renamed into place.
+ */
+async function writeControlFileDurably(filePath, contents) {
+    const tempPath = `${filePath}.partial-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+    const handle = await (0, promises_1.open)(tempPath, 'wx', 0o600);
+    try {
+        await handle.writeFile(contents, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        // `wx` on the temp name plus this rename keeps the EEXIST semantics callers rely on to detect a
+        // retry of the same activation.
+        await (0, promises_1.link)(tempPath, filePath);
+    }
+    finally {
+        await (0, promises_1.rm)(tempPath, { force: true });
+    }
+    await syncDirectory((0, node_path_1.dirname)(filePath));
+}
+function candidateCompleteMarkerPath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_COMPLETE_MARKER);
+}
+function candidateComponentFilePath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_COMPONENT_FILE);
+}
+function activationJournalPath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), ACTIVATION_JOURNAL);
+}
+function candidateArtifactFilePath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_ARTIFACT_FILE);
+}
+/**
+ * Read and fully validate a staged artifact's descriptor. Every field is checked, not just the ones the
+ * caller happens to use: a descriptor is activation input for a build this process did not make, possibly
+ * not even on this node, so a partially-checked one is a way to activate under someone else's intent.
+ * Absence is `undefined`; anything present but unusable throws, because a staged artifact that cannot
+ * describe itself must be refused rather than activated under defaults.
+ */
+async function readArtifactDescriptor(deploymentDirPath, componentName) {
+    const descriptorPath = (0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE);
+    // The artifact the caller named exists and is theirs, but does not describe a build this can activate —
+    // a conflict with what is on disk, not a server fault.
+    const unusable = (message) => new hdbError_ts_1.ClientError(message, 409);
+    const raw = await (0, promises_1.readFile)(descriptorPath, 'utf8').catch((error) => {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw unusable(`Artifact descriptor ${descriptorPath} is not readable JSON: ${errorMessage(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.v !== ARTIFACT_DESCRIPTOR_VERSION) {
+        throw unusable(`Artifact descriptor ${descriptorPath} is version ${parsed?.v}, which this build cannot activate`);
+    }
+    if (!isJoinableComponentName(parsed.component) || parsed.component !== componentName) {
+        throw unusable(`Artifact descriptor ${descriptorPath} names component '${parsed.component}', not '${componentName}'`);
+    }
+    if (typeof parsed.installationIsOpaque !== 'boolean' || typeof parsed.isolated !== 'boolean') {
+        throw unusable(`Artifact descriptor ${descriptorPath} does not record its build's runtime decisions`);
+    }
+    if (parsed.rootConfig !== null && (typeof parsed.rootConfig !== 'object' || Array.isArray(parsed.rootConfig))) {
+        throw unusable(`Artifact descriptor ${descriptorPath} does not record a root-config entry or its absence`);
+    }
+    // Admission reads one field and publication writes the other, so two authorities that disagree would
+    // admit one isolation and then publish the opposite.
+    if (parsed.rootConfig && Boolean(parsed.rootConfig.isolated) !== parsed.isolated) {
+        throw unusable(`Artifact descriptor ${descriptorPath} admits isolated=${parsed.isolated} but publishes ` +
+            `isolated=${Boolean(parsed.rootConfig.isolated)}`);
+    }
+    return parsed;
+}
+const SEPARATORS_IN_LINK_TARGETS = process.platform === 'win32' ? /[\\/]/ : /\//;
+// `node_modules/harper` and `node_modules/harperdb` are links the LOADER owns: it points them at the
+// running install on every non-root component load and repairs them when they are missing or stale. They
+// are outside the artifact by construction and by design, so they are the one external link a staged
+// artifact may carry.
+const LOADER_OWNED_LINKS = new Set(['harper', 'harperdb']);
+/**
+ * Reject a staged artifact that reaches outside itself.
+ *
+ * Certification fsyncs the tree but follows no links, and the post-swap relocation repair deliberately
+ * leaves external targets alone — so a symlink into a directory this artifact does not own is a hole in
+ * "activate exactly the bytes that were certified": the target can be edited, or replaced wholesale,
+ * between the stage and the activation. An immediate deploy is not exposed to this, because certification
+ * and activation happen within one call; the delay is what makes it reachable.
+ *
+ */
+async function assertOwnedArtifactTree(candidateDirPath, componentName, action = 'stage') {
+    // The operator supplied a component that cannot be staged (400); or the artifact they named exists and is
+    // theirs but is no longer what was certified (409). Neither is a server fault, and both reached the
+    // operations handler as a bare 500 until a live run showed what that looks like to a caller.
+    const refuse = (message) => new hdbError_ts_1.ClientError(message, action === 'stage' ? 400 : 409);
+    const ownedRoot = await (0, promises_1.realpath)(candidateDirPath);
+    // The loader repairs the component's OWN `node_modules/harper`, not a copy nested inside a dependency,
+    // so only that one path is exempt. Matching the name at any depth would let `dep/node_modules/harper`
+    // point anywhere and still pass.
+    const loaderOwnedDir = (0, node_path_1.join)(candidateDirPath, 'node_modules');
+    const walk = async (dirPath) => {
+        const entries = await (0, promises_1.readdir)(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = (0, node_path_1.join)(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+                continue;
+            }
+            // Junctions report as symbolic links here, which is what makes this cover Windows.
+            if (!entry.isSymbolicLink())
+                continue;
+            if (LOADER_OWNED_LINKS.has(entry.name) && dirPath === loaderOwnedDir)
+                continue;
+            // An unresolvable link is rejected for the same reason a foreign one is: nothing certified what
+            // it will resolve to by the time somebody activates it.
+            const target = await (0, promises_1.realpath)(entryPath).catch(() => undefined);
+            if (target === undefined || (target !== ownedRoot && !target.startsWith(ownedRoot + node_path_1.sep))) {
+                throw refuse(`Cannot ${action} ${componentName}: ${entryPath} links outside the build to ${target ?? 'a missing target'}, ` +
+                    `so the bytes activated later would not be the bytes this build certified`);
+            }
+            // `repairRelocatedDependencyLinks` re-points links after the swap, but it runs PAST THE COMMIT
+            // POINT and can only warn — it logs and continues on a failed re-point, and skips a whole subtree
+            // on EACCES/EMFILE — so a component could go live holding a link to a path that no longer exists
+            // while the operation reports success. Staging fails closed instead. The cost: npm writes absolute
+            // junctions under `node_modules` on Windows for a `file:`/workspace dependency, so such a component
+            // deploys immediately but cannot be staged until its links are relative.
+            const linkTarget = await (0, promises_1.readlink)(entryPath);
+            if ((0, node_path_1.isAbsolute)(linkTarget)) {
+                throw refuse(`Cannot ${action} ${componentName}: ${entryPath} names its target inside the build by absolute path ` +
+                    `(${linkTarget}), which activation moves. Re-link it relatively — on Windows, npm ` +
+                    `writes absolute junctions for 'file:' and workspace dependencies, so those have to be relative ` +
+                    `before the component can be staged.`);
+            }
+            // Where the link ENDS UP is not enough: a target that leaves the candidate and comes back resolves
+            // inside it today and somewhere else once activation renames the tree, because the same relative
+            // expression is then evaluated from `components/<component>/…`. Counting `..` segments does not
+            // catch it either, since an intermediate symlink (`up -> ..`) reduces depth without spelling it.
+            // So every PREFIX of the walk is resolved, with symlinks followed as the filesystem will follow
+            // them, and each one has to still be inside the candidate.
+            let prefix = (0, node_path_1.dirname)(entryPath);
+            // Only Windows treats a backslash as a separator. On POSIX it is an ordinary filename character, so
+            // splitting on it there turns a link to the single legal entry `..\asset` — which resolves inside
+            // the candidate and keeps resolving there after relocation — into `..` plus `asset`, and refuses a
+            // component that never left its own tree.
+            for (const segment of linkTarget.split(SEPARATORS_IN_LINK_TARGETS)) {
+                if (segment === '' || segment === '.')
+                    continue;
+                prefix = await (0, promises_1.realpath)((0, node_path_1.join)(prefix, segment)).catch(() => (0, node_path_1.join)(prefix, segment));
+                if (prefix !== ownedRoot && !prefix.startsWith(ownedRoot + node_path_1.sep)) {
+                    throw refuse(`Cannot ${action} ${componentName}: ${entryPath} reaches ${prefix} on its way to ${linkTarget}, ` +
+                        `leaving the build — after activation moves the tree that path resolves somewhere else`);
+                }
+            }
+        }
+    };
+    await walk(candidateDirPath);
+}
+/** Record the build's decisions beside the candidate. Called before `.complete`, which vouches for it. */
+async function writeArtifactDescriptor(componentDirPath, deploymentId, descriptor) {
+    try {
+        await writeControlFileDurably(candidateArtifactFilePath(componentDirPath, deploymentId), JSON.stringify(descriptor));
+    }
+    catch (error) {
+        // An existing descriptor belongs to this same artifact — the id is claimed exclusively, so nothing
+        // else can have written one — which makes this a retry of its own stage rather than a conflict.
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
+/**
+ * A component name safe to join onto the components root: no separator, no traversal, not dot-prefixed.
+ * Applied to EVERY source of the name — the journal and the sidecar — because validating one and trusting
+ * the other is how a corrupt record reaches an unrelated directory.
+ */
+function isJoinableComponentName(name) {
+    return (typeof name === 'string' &&
+        name.length > 0 &&
+        name === (0, node_path_1.basename)(name) &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.startsWith('.'));
+}
+/**
+ * Read an activation journal. Absent is `undefined` — no activation was attempted. Anything else THROWS:
+ * a truncated or unknown-version journal is an interrupted activation whose intent cannot be read, and
+ * both guesses are destructive (publish a rejected release, or discard a good one), so the component is
+ * failed closed instead.
+ */
+async function readActivationJournal(journalPath) {
+    let raw;
+    try {
+        raw = await (0, promises_1.readFile)(journalPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Activation journal ${journalPath} could not be parsed: ${errorMessage(error)}`);
+    }
+    if (parsed?.v !== ACTIVATION_JOURNAL_VERSION) {
+        throw new Error(`Activation journal ${journalPath} has version ${JSON.stringify(parsed?.v)}, expected ${ACTIVATION_JOURNAL_VERSION}`);
+    }
+    if (!isJoinableComponentName(parsed.component) || typeof parsed.candidateId !== 'string') {
+        throw new Error(`Activation journal ${journalPath} does not identify its component and candidate`);
+    }
+    // The journal must describe the directory it sits in. A syntactically valid journal naming someone
+    // else's deployment would otherwise let recovery act on a component from the wrong record.
+    if (parsed.candidateId !== (0, node_path_1.basename)((0, node_path_1.dirname)(journalPath))) {
+        throw new Error(`Activation journal ${journalPath} names candidate '${parsed.candidateId}', which is not its own deployment`);
+    }
+    return parsed;
+}
+/**
+ * The deployment directory holding one candidate build: `<root>/.deploy-staging/<deploymentId>`.
+ *
+ * The id is asserted here rather than only at the request boundary because every caller funnels through
+ * this one join, and the id is now operator-supplied (`deployment_id`) or replication-supplied
+ * (`_deploymentId`). A traversal-bearing id would otherwise direct both the build and its removal outside
+ * `.deploy-staging`.
+ */
+function candidateDeploymentDirPath(componentDirPath, deploymentId) {
+    if (typeof deploymentId !== 'string' ||
+        deploymentId.length === 0 ||
+        deploymentId !== (0, node_path_1.basename)(deploymentId) ||
+        // `basename` returns these unchanged, so the comparison above admits both.
+        deploymentId === '.' ||
+        deploymentId === '..') {
+        throw new Error(`Deployment id '${deploymentId}' is not a single path segment`);
+    }
+    return (0, node_path_1.join)((0, node_path_1.dirname)(componentDirPath), exports.DEPLOY_STAGING_DIR, deploymentId);
+}
+/** Where a candidate build lives: `<root>/.deploy-staging/<deploymentId>/<component>`. */
+function candidateApplicationPath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), (0, node_path_1.basename)(componentDirPath));
+}
+function extractionStagingDirectory(componentDirPath) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(componentDirPath), exports.ASIDE_STAGING_DIR, (0, node_path_1.basename)(componentDirPath));
+}
+function retiredMarkerForAside(asidePath) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(asidePath), `${RETIRED_ASIDE_PREFIX}${(0, node_path_1.basename)(asidePath).slice(IN_PROGRESS_ASIDE_PREFIX.length)}`);
+}
+async function retireExtractionAside(asidePath) {
+    const retiredMarkerPath = retiredMarkerForAside(asidePath);
+    try {
+        await (0, promises_1.writeFile)(retiredMarkerPath, '', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return retiredMarkerPath;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function makeRollbackPlaceholderMovable(applicationDirPath, placeholderIdentity) {
+    if (!placeholderIdentity)
+        return;
+    try {
+        const current = await (0, promises_1.lstat)(applicationDirPath, { bigint: true });
+        if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+            await (0, promises_1.chmod)(applicationDirPath, 0o700);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+async function identifyRollbackPlaceholder(applicationDirPath) {
+    const userId = process.getuid?.();
+    if (process.platform === 'win32' || userId === undefined || userId === 0)
+        return undefined;
+    try {
+        const current = await (0, promises_1.lstat)(applicationDirPath, { bigint: true });
+        const permissions = Number(current.mode) & 0o777;
+        if ((current.isDirectory() || current.isFile()) &&
+            current.uid === BigInt(userId) &&
+            (permissions === 0 || (current.isDirectory() && (permissions === 0o100 || permissions === 0o300)))) {
+            return { dev: current.dev, ino: current.ino };
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return undefined;
+}
+/**
+ * Create a hidden staging directory and confirm it is the one we created: a real directory rather than a
+ * symlink or junction substituted underneath us, restricted to the owner. Re-checked at every use rather
+ * than once per deploy, because the gap between checking and writing is the exploitable part.
+ */
+async function ensureSecureStagingDirectory(stagingDir) {
+    await (0, promises_1.mkdir)(stagingDir, { recursive: true, mode: 0o700 });
+    const stagingStat = await (0, promises_1.lstat)(stagingDir);
+    if (!stagingStat.isDirectory() || stagingStat.isSymbolicLink()) {
+        throw new Error(`Component deploy staging path is not a directory: ${stagingDir}`);
+    }
+    if (process.platform !== 'win32' && (stagingStat.mode & 0o777) !== 0o700) {
+        await (0, promises_1.chmod)(stagingDir, 0o700).catch((error) => harper_logger_ts_1.default.warn(`Could not restrict component deploy staging permissions for ${stagingDir}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    }
+}
+/**
+ * Claim a deployment directory for this build, EXCLUSIVELY. The id is the public deployment id, which an
+ * operator can repeat and a redelivered replication can repeat for them, so tolerating an existing
+ * directory would let a replayed stage rewrite the bytes under an existing `.complete` and descriptor —
+ * and a crash mid-rebuild would leave a partial tree that still reads as certified.
+ *
+ * The caller holds the component's preparation lock, which is what makes the EEXIST verdicts sound: no
+ * other preparation of THIS component is running, and a directory belonging to another component is not
+ * this lock's to touch.
+ */
+async function claimDeploymentDirectory(deploymentDirPath, componentName) {
+    // Every refusal below is a conflict over an id that already exists, which is the caller's to resolve by
+    // naming a different one — not a server fault, and not the 500 a bare Error reaches the caller as.
+    const taken = (message) => new hdbError_ts_1.ClientError(message, 409);
+    try {
+        await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const owner = await candidateComponentName(deploymentDirPath);
+        if (owner !== undefined && owner !== componentName) {
+            throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} already holds a build of '${owner}'; a deployment id ` +
+                `names one artifact for its lifetime`);
+        }
+        // Ownership has to be POSITIVE to reclaim, and EMPTINESS IS NOT A VERDICT. The sidecar below is
+        // written as part of the claim, so a directory naming nobody is another component between its own
+        // mkdir and that write, and a deploy can hold a nearly empty one for minutes while it resolves and
+        // packs. Nothing on disk separates that from a claim that got no further, and the lock that
+        // serializes it is not this one, so only the exclusive create may conclude the id is free: the
+        // directory can also have been discarded by a failed build between the first mkdir and this read,
+        // and another component can claim it in that same gap.
+        if (owner === undefined) {
+            await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 }).catch((retry) => {
+                if (retry?.code !== 'EEXIST')
+                    throw retry;
+                throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} is already claimed by a build that has not named its ` +
+                    `component yet. If no deploy of any component is in flight, that directory is abandoned and has ` +
+                    `to be removed by hand; deploying again without a deployment_id mints a fresh id`);
+            });
+        }
+        else {
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER))) {
+                throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} already holds a completed build of '${componentName}'; ` +
+                    `deploy it with deployment_id, or deploy again to build a new one`);
+            }
+            // This component's own preparation lock serializes the claim and nothing certified it, so nothing
+            // is lost by rebuilding over it.
+            await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 });
+        }
+    }
+    const claimed = await (0, promises_1.lstat)(deploymentDirPath);
+    if (!claimed.isDirectory() || claimed.isSymbolicLink()) {
+        throw new Error(`Component deploy staging path is not a directory: ${deploymentDirPath}`);
+    }
+    if (process.platform !== 'win32' && (claimed.mode & 0o777) !== 0o700) {
+        await (0, promises_1.chmod)(deploymentDirPath, 0o700).catch((error) => harper_logger_ts_1.default.warn(`Could not restrict component deploy staging permissions for ${deploymentDirPath}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    }
+    await publishClaimOwnership(deploymentDirPath, componentName);
+}
+/**
+ * Name the component that owns a deployment directory THIS CALL created, and take the directory back if that
+ * cannot be recorded.
+ *
+ * Ownership is published as part of the claim rather than at certification, because resolving and packing can
+ * take minutes and until a tree exists to infer an owner from, a directory answering to nobody is one another
+ * component will take for abandoned. Unattributed is a permanent refusal, though, so a failure here — a full
+ * disk, an EIO on the temp write or its sync — would burn this deployment id for good, every retry refused by
+ * its own wreckage. The removal is scoped to the directory this invocation made, and deliberately not
+ * broadened to one found by EEXIST: that directory may be another claimant's, and removing it is the race the
+ * refusal exists to prevent. Best-effort, because the claim failure is what the caller needs to see.
+ *
+ * `write` is a parameter so the failure is testable without a filesystem that can be made to fail on exactly
+ * this write and nothing else.
+ */
+async function publishClaimOwnership(deploymentDirPath, componentName, write = writeControlFileDurably) {
+    try {
+        await write((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPONENT_FILE), componentName);
+    }
+    catch (error) {
+        await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true }).catch((cleanupError) => harper_logger_ts_1.default.warn(`Could not remove the deployment directory ${deploymentDirPath} after failing to publish its ` +
+            `ownership; the id stays unusable until it is removed:`, (0, harper_logger_ts_1.errorForLog)(cleanupError)));
+        throw error;
+    }
+}
+async function ensureExtractionStagingDirectory(asideStagingDir) {
+    for (const stagingDir of [(0, node_path_1.dirname)(asideStagingDir), asideStagingDir]) {
+        await ensureSecureStagingDirectory(stagingDir);
+    }
+}
+/** The single component directory inside a candidate deployment directory, when there is exactly one. */
+async function candidateComponentName(deploymentDirPath) {
+    // The sidecar first: it is the only source that still works once the candidate has been renamed to the
+    // live path, which is exactly when an unreadable journal would otherwise be unattributable.
+    // Only ENOENT is absence. Swallowing every error here reported "unowned", which is a licence to act:
+    // the worker verdict dropped a failure and loaded a component main had failed closed, and a deploy
+    // skipped a journaled activation it owns and stalled the component in the legacy pass instead.
+    const recorded = await (0, promises_1.readFile)((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPONENT_FILE), 'utf8').catch((error) => {
+        if (error?.code === 'ENOENT')
+            return '';
+        throw error;
+    });
+    const named = recorded.trim();
+    if (isJoinableComponentName(named))
+        return named;
+    const entries = await (0, promises_1.readdir)(deploymentDirPath, { withFileTypes: true }).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    // Symlinks count: a `file:<directory>` candidate is deliberately a link, and activation already accepts
+    // one. Filtering to real directories here left those candidates with no owner, so residue removal took
+    // no lock and could delete a build in flight.
+    //
+    // Validated, because this infers an owner from a NAME. A directory-shaped control file — a corrupt
+    // `.activation.json` that is a directory — would otherwise be returned as the owning component, which
+    // both licenses a restore against it and is a name no component can have.
+    const components = entries.filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && isJoinableComponentName(entry.name));
+    return components.length === 1 ? components[0].name : undefined;
+}
+/**
+ * The deployment directory of an activation journal this component still owns, if any.
+ *
+ * The journal is the authority for an interrupted activation. The legacy `.deploy-aside` pass would
+ * otherwise restore the displaced tree over a candidate a completed activation already renamed live, so it
+ * consults this before restoring rather than relying on being sequenced after settlement: a worker
+ * auto-restarted mid-activation reaches it with no settlement in front of it, and settlement that FAILS
+ * deliberately keeps the journal for the next start while the same boot carries on into the legacy pass.
+ */
+async function journaledDeploymentForComponent(componentsRootDirPath, componentName) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
+        // NOTHING is swallowed here. This is the gate that authorizes restoring an old tree over what may be
+        // a committed candidate, so "could not tell" has to fail closed — treating an unreadable deployment
+        // as "no journal for this component" is exactly the clobber the journal exists to prevent. The blast
+        // radius is narrow because the gate is only consulted where a restorable record already exists.
+        //
+        // Presence, not parseability: an unreadable journal is precisely the ambiguous case.
+        const journaled = await (0, promises_1.lstat)(journalPath).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        if (!journaled)
+            continue;
+        // EITHER name blocks, while settlement acts only when both agree. The destructive step takes the
+        // conservative union; the corrective one takes the precise intersection, so a journal whose two
+        // attributions disagree stalls the restore instead of licensing it, and startup recovery — which
+        // keys on the journal — is what clears it. The sidecar also covers a component legitimately named
+        // `component`, whose candidate path collides with the sidecar's and makes every sidecar read fail.
+        const journalOwner = (await readActivationJournal(journalPath).catch(() => undefined))?.component;
+        if (journalOwner === componentName)
+            return deploymentDirPath;
+        const sidecarOwner = await candidateComponentName(deploymentDirPath);
+        if (sidecarOwner === componentName)
+            return deploymentDirPath;
+        // A journal nobody can attribute blocks EVERY component. It is a rare, genuinely broken state — an
+        // unparseable journal whose deployment no longer holds a tree to infer from — and the alternative is
+        // letting the restore proceed against a candidate this journal may well have committed. There is no
+        // automated way out of it, by construction: nothing on disk says which component it belongs to. The
+        // error the caller raises names the directory an operator has to resolve.
+        if (journalOwner === undefined && sidecarOwner === undefined)
+            return deploymentDirPath;
+    }
+    return undefined;
+}
+/**
+ * The components a deployment's evidence implicates, when its journal and its ownership sidecar disagree
+ * about whose it is — or `undefined` when there is no disagreement to act on.
+ *
+ * A sidecar that cannot answer is NOT disagreement: the journal names its own component and can settle it,
+ * so an unreadable sidecar must not block that. Only a sidecar that reads and names something else is the
+ * wedge, and then BOTH names are returned, sidecar first, because both are stuck — see
+ * `splitAttributionError`.
+ *
+ * Separated from either call site so the decision is testable on its own: the paths that reach it include
+ * one that requires a journal to appear between two reads under a lock, which no test can stage.
+ */
+function splitAttributionOwners(journalOwner, sidecarOwner) {
+    if (sidecarOwner === undefined || sidecarOwner === journalOwner)
+        return undefined;
+    return [sidecarOwner, journalOwner];
+}
+/**
+ * The error for a deployment its journal and its ownership sidecar attribute to different components.
+ *
+ * Both names are wedged, so both are failed: the restore gate takes the union and blocks the sidecar's
+ * component, while settlement needs the intersection and so can never clear the journal owner's. Neither
+ * component's own deploy can resolve it, which is why the message names the directory to remove.
+ */
+function splitAttributionError(deploymentDirPath, journalOwner, sidecarOwner) {
+    return new Error(`Deploy staging ${deploymentDirPath} is attributed to two different components: its journal names ` +
+        `'${journalOwner}' and its sidecar names '${sidecarOwner}'. Neither can settle it; remove that ` +
+        `directory once you have determined which tree is current.`);
+}
+/** In-progress rollback records in a component's aside directory, newest first. */
+async function inProgressAsideRecords(asideStagingDir) {
+    // ENOENT is "no aside directory yet"; anything else would report "no records" and let roll-forward
+    // remove the journal while the records it should have retired are still there and still authoritative.
+    const entries = await (0, promises_1.readdir)(asideStagingDir, { withFileTypes: true }).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    // Retired records excluded, the same rule `recoverOrCleanupStaleExtractionPaths` applies. A record whose
+    // retire succeeded but whose best-effort sweep did not is settled, not displaced — counting it would let
+    // an ordinary pre-swap state look like the "live path recreated" ambiguity and fail a healthy component
+    // closed with an operator-only exit.
+    const entryNames = new Set(entries.map((entry) => entry.name));
+    return entries
+        .filter((entry) => entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX) &&
+        !entryNames.has(`${RETIRED_ASIDE_PREFIX}${entry.name.slice(IN_PROGRESS_ASIDE_PREFIX.length)}`))
+        .map((entry) => (0, node_path_1.join)(asideStagingDir, entry.name))
+        .sort()
+        .reverse();
+}
+/**
+ * Settle journaled activations for ONE component, and bound its dormant staged builds, assuming the caller
+ * already holds its preparation lock.
+ *
+ * Exists because the journal-first rule has to hold at every entry point, not just startup. A deploy runs
+ * `recoverOrCleanupStaleExtractionPaths` first. After an activation whose retirement failed, the aside
+ * still names the DISPLACED tree, so restoring it would put the old version back over the new one. That
+ * pass refuses to restore against a surviving journal, but refusing is a stalled component; settling first
+ * is what lets the deploy proceed.
+ */
+async function settleStagingForComponent(componentsRootDirPath, componentName, pinnedDeploymentId) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const dormant = [];
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        // Ownership BEFORE parsing. Reading every journal first meant a truncated journal belonging to another
+        // component threw here — blocking the deploy of a healthy component because an unrelated one is
+        // broken. The sidecar names the owner without parsing anything, and a deployment that does not name
+        // this component is none of this deploy's business; startup recovery reports it instead.
+        //
+        // An ownership read that FAILS is the same situation, and skipping is safe here specifically because
+        // settlement is the corrective half: if that entry does turn out to be this component's, the restore
+        // gate — which takes the union and fails closed on anything it cannot attribute — is what stops the
+        // legacy pass acting on it. Failing the deploy instead lets one unreadable sibling block every
+        // neighbour's deploys, which is the outage this ordering exists to prevent.
+        let owner;
+        let ownerUnreadable = false;
+        try {
+            owner = await candidateComponentName(deploymentDirPath);
+        }
+        catch (error) {
+            ownerUnreadable = true;
+            harper_logger_ts_1.default.trace?.(`Ownership of ${deploymentDirPath} is unreadable while settling ${componentName}, falling back to ` +
+                `its journal: ${errorMessage(error)}`);
+        }
+        if (!ownerUnreadable && owner !== componentName)
+            continue;
+        const journal = await readActivationJournal((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL));
+        // A journal-less directory is what a SUCCESSFUL settlement leaves when its best-effort sweep fails, so
+        // this must not fail closed. An unattributable *activation* still does: `readActivationJournal` throws
+        // on a journal that exists but cannot be read.
+        if (!journal) {
+            if (ownerUnreadable)
+                continue;
+            try {
+                const build = await dormantBuildAt(deploymentDirPath, componentName);
+                if (build)
+                    dormant.push(build);
+            }
+            catch (error) {
+                harper_logger_ts_1.default.warn(`Leaving staged ${componentName} build ${deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+            }
+            continue;
+        }
+        // The journal decides, not the sidecar. Skipping on an unreadable sidecar alone would leave this
+        // component's own unsettled activation in place while a new deploy proceeded over it, and an
+        // activation interrupted before B1 has no rollback record for the restore gate to catch.
+        if (journal.component !== componentName)
+            continue;
+        await settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, journal);
+    }
+    const maxCount = getStagingRetentionMaxCount();
+    if (dormant.length > maxCount)
+        await pruneDormantBuilds(componentName, dormant, maxCount, pinnedDeploymentId);
+}
+/**
+ * Components that on-disk evidence says were left in a state nobody settled — determined READ-ONLY, so any
+ * thread can reach the same verdict.
+ *
+ * Recovery runs on the main thread only, but the components it could not settle still have to be failed
+ * closed on the workers that actually serve them, and a worker cannot be handed main's verdict: it boots
+ * through its own `loadRootComponents(true)`, potentially before main finished. Recovery deliberately KEEPS
+ * the evidence for anything it could not settle, so a worker can read it instead of being told.
+ *
+ * Only unambiguous evidence counts. A well-formed journal is NOT evidence — every healthy deploy has one
+ * in flight — so this reports a journal that cannot be read at all (corrupt, unknown version, or naming
+ * something other than its own deployment), which no in-flight deploy ever produces.
+ */
+async function unsettleableComponentsFromDisk(componentsRootDirPath) {
+    const unsettleable = new Map();
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return unsettleable;
+        throw error;
+    }
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        // Per deployment. `candidateComponentName` propagates every non-ENOENT error now, and this pass runs
+        // where the CALLER only warns — so one unreadable deployment escaping here would drop the verdict for
+        // every other component and let each of them load with no evidence checked at all.
+        try {
+            await verdictFor(deploymentDirPath, deployment.name, unsettleable);
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (!unsettleable.has(deployment.name))
+                unsettleable.set(deployment.name, failure);
+        }
+    }
+    return unsettleable;
+}
+/** One deployment's read-only verdict. Throws rather than guessing; the caller scopes that to this entry. */
+async function verdictFor(deploymentDirPath, deploymentName, unsettleable) {
+    // Recorded by main when it failed to settle a well-formed journal. Checked first, because that case is
+    // invisible to a worker otherwise.
+    //
+    // Only ENOENT is absence. A marker that exists but cannot be read (EIO, EACCES) must not be taken as
+    // "no verdict" — that classifies the well-formed journal beside it as a healthy in-flight deploy and
+    // lets the worker load a component main failed closed.
+    let recorded;
+    try {
+        recorded = await (0, promises_1.readFile)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            return record(unsettleable, await attribute(deploymentDirPath, deploymentName), failure);
+        }
+    }
+    if (recorded !== undefined) {
+        const component = await attribute(deploymentDirPath, deploymentName);
+        return record(unsettleable, component, new Error(recorded.trim() || `Activation of ${component} could not be settled`));
+    }
+    try {
+        await readActivationJournal((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL));
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        record(unsettleable, await attribute(deploymentDirPath, deploymentName), failure);
+    }
+}
+/**
+ * Who a deployment's evidence belongs to. Falls back to the deployment id when nothing names it: a verdict
+ * attributed to nothing is a verdict nobody acts on, and the id is at least something an operator can find
+ * on disk. A read that FAILS is not "nothing names it" — that propagates, and the caller records it against
+ * the id, so an unreadable deployment is reported rather than dropped.
+ */
+async function attribute(deploymentDirPath, deploymentName) {
+    return (await candidateComponentName(deploymentDirPath)) ?? deploymentName;
+}
+function record(unsettleable, component, failure) {
+    if (!unsettleable.has(component))
+        unsettleable.set(component, failure);
+}
+/**
+ * Settle activations a crash interrupted, before anything loads. Runs at startup on main and on every
+ * worker — a worker can be respawned mid-activation, long after main's pass.
+ *
+ * Returns failures keyed by COMPONENT so the caller can fail exactly those closed and still load every
+ * healthy sibling — a single unreadable journal must not take down the whole node, and must not let a
+ * component load over state nobody reconciled.
+ *
+ */
+async function recoverInterruptedActivations(componentsRootDirPath) {
+    const failures = new Map();
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return failures;
+        throw error;
+    }
+    const dormant = new Map();
+    const catalogue = (owner, build) => {
+        const builds = dormant.get(owner);
+        if (builds)
+            builds.push(build);
+        else
+            dormant.set(owner, [build]);
+    };
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
+        const fail = (component, error) => recordUnsettled(failures, component, error, deploymentDirPath);
+        let journal;
+        try {
+            journal = await readActivationJournal(journalPath);
+        }
+        catch (error) {
+            // The journal itself is unreadable, so its component has to be inferred from the tree it was
+            // going to activate. A deployment directory holding no component tree leaves only its id.
+            const attributed = await candidateComponentName(deploymentDirPath).catch(() => undefined);
+            await fail(attributed ?? deployment.name, error);
+            continue;
+        }
+        if (!journal) {
+            // No activation was attempted: build residue, or a candidate abandoned mid-build. The legacy
+            // in-place recovery owns any aside it left, so there is nothing to settle.
+            //
+            // Removed UNDER the component's lock, and only after re-checking that no journal appeared in the
+            // meantime. A reload cycle can run this pass while another deploy is mid-build — its candidate
+            // has no journal yet, because the journal is written after build and validation — so an unlocked
+            // delete here removes a live build out from under it.
+            let owner;
+            // Who to fail, if what went wrong under the lock turns out to concern an ACTIVATION rather than
+            // this branch's opportunistic cleanup. Left unset for a sweep that could not remove a settled
+            // directory and for a lock a live deploy is holding: neither is an unsettled activation.
+            let activationToFail;
+            // Set when the journal that appears under the lock names someone other than the sidecar owner
+            // whose lock we took. Both names are failed, exactly as on the journaled path.
+            let splitOwners;
+            const removeResidue = async () => {
+                // Re-read UNDER the lock, and do not swallow: the first scan raced a deploy that can publish a
+                // journal before releasing the lock, so a journal found now must be settled rather than deleted.
+                // Treating a read error as "no journal" would delete the evidence instead.
+                let appeared;
+                try {
+                    appeared = await readActivationJournal((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL));
+                }
+                catch (error) {
+                    // A journal published between the scan's read and this one, which then cannot be READ, is an
+                    // activation whose intent is unknowable — the one thing in this branch that has to fail
+                    // closed. Attributed to the sidecar's owner, since the journal cannot name itself.
+                    activationToFail = owner ?? deployment.name;
+                    throw error;
+                }
+                if (appeared) {
+                    // The lock held here was taken on the SIDECAR's owner. A journal naming someone else must not
+                    // be settled under it: `settleInterruptedActivation` renames and removes that other
+                    // component's trees, whose own deploy may hold its own lock and be mid-flight. It is also the
+                    // same split evidence the journaled path fails closed for both names, so it takes the same
+                    // route rather than a second opinion here.
+                    const splitNames = splitAttributionOwners(appeared.component, owner);
+                    if (splitNames) {
+                        splitOwners = splitNames;
+                        throw splitAttributionError(deploymentDirPath, appeared.component, splitNames[0]);
+                    }
+                    activationToFail = appeared.component;
+                    await settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, appeared);
+                    // Settled. Anything that fails after this — releasing the lock, say — is not this
+                    // activation's, and attributing it here would fail a correctly settled component closed.
+                    activationToFail = undefined;
+                    return;
+                }
+                // Re-classified UNDER the lock: the unlocked read that routed this here can predate the `.complete`
+                // a deploy wrote before dying, and that is a retainable build, not residue.
+                const build = await dormantBuildAt(deploymentDirPath, owner);
+                if (build) {
+                    catalogue(owner, build);
+                    return;
+                }
+                // A DESCRIBED artifact carrying a stale verdict is settled, not residue. `fail()` only ever writes
+                // `.unsettled` beside a journal it keeps, so a marker with no journal says settlement finished
+                // and only the marker's own removal was lost — which is exactly what a crash between a dormant
+                // return's two unlinks leaves, and the barrier that orders them cannot run on Windows. Deleting
+                // here would destroy a build somebody staged deliberately, whose payload may already have been
+                // reclaimed, on the strength of a verdict that no longer applies. Clearing the marker is the
+                // idempotent completion of the settlement that wrote it; an undescribed build stays disposable.
+                if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE))) {
+                    // A fault clearing the marker is not a licence to delete what it is attached to — and not a
+                    // licence to say nothing either. The marker survives, every worker fails the component closed
+                    // on it, and main reporting success is the split where main serves what every worker refuses.
+                    // Failing the component brings main to the workers' verdict instead, the rule the settled tail
+                    // follows, and leaves the artifact for the next pass to clear.
+                    try {
+                        await clearUnsettledVerdict(deploymentDirPath, owner);
+                    }
+                    catch (error) {
+                        activationToFail = owner;
+                        throw error;
+                    }
+                    const settled = await dormantBuildAt(deploymentDirPath, owner);
+                    if (settled) {
+                        harper_logger_ts_1.default.info?.(`Cleared a stale unsettled verdict from the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ` +
+                            `${owner}; its activation was already settled`);
+                        catalogue(owner, settled);
+                        return;
+                    }
+                    // Cleared, and still not a retainable build — an incomplete or treeless staged directory. That
+                    // is residue like any other, so it falls through to the removal below.
+                }
+                // Cleanup, not settlement. There was no activation here — this is most often the residue a
+                // SUCCESSFUL settlement leaves when its own sweep failed — so a sweep that fails again cannot
+                // make anything unsettled, and recording it would refuse a live component on every worker
+                // until the filesystem fault cleared.
+                await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => harper_logger_ts_1.default.warn(`Could not clean up deploy staging ${deploymentDirPath}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+            };
+            // Attribution FIRST, in its own scope, and its failure is not a verdict. A journal-less directory
+            // is what a successful settlement leaves when its best-effort sweep fails, so a `fail()` here
+            // wrote `.unsettled` keyed by the deployment id for a deployment that never held an unsettled
+            // activation — and nothing ever cleared it, because settlement never runs for a journal-less
+            // directory. If that sidecar later became readable as `web`, the stale marker was attributed to
+            // the live `web` and every worker refused it permanently. This is the same shape the deploy path
+            // skips; the two paths now agree.
+            try {
+                owner = await candidateComponentName(deploymentDirPath);
+            }
+            catch (error) {
+                harper_logger_ts_1.default.trace?.(`Leaving deploy staging ${deploymentDirPath} in place: it holds no activation journal and its ` +
+                    `ownership cannot be read: ${errorMessage(error)}`);
+                continue;
+            }
+            // Catalogued WITHOUT the lock and left alone: a retained build is never removed here, so a per-directory
+            // lock would recur on every pass and contend with sibling threads for a component nothing is deploying.
+            if (owner) {
+                let build;
+                try {
+                    build = await dormantBuildAt(deploymentDirPath, owner);
+                }
+                catch (error) {
+                    harper_logger_ts_1.default.warn(`Leaving deploy staging ${deploymentDirPath} in place; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+                    continue;
+                }
+                if (build) {
+                    catalogue(owner, build);
+                    continue;
+                }
+            }
+            // Scoped to THIS deployment, like the journaled branch below: a lock timeout or an EIO here used to
+            // abort the entire scan, leaving every later deployment unsettled and unmarked.
+            try {
+                if (owner) {
+                    await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, owner), removeResidue, {
+                        purpose: 'activation-recovery',
+                        ...RECOVERY_LOCK_WAIT,
+                        // Without this a ticket left by a CRASHED worker looks live — same pid, same process
+                        // instance — so recovery waits out the multi-hour default instead of reclaiming it.
+                        isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(lockOwner.threadId),
+                    });
+                }
+                else {
+                    // NOT removed. `buildCandidateApplication` creates the deployment directory and can then spend
+                    // minutes resolving or packing before the candidate tree and its sidecar exist, so "no owner"
+                    // includes "a live build that has not got that far yet" — and deleting it races the extraction
+                    // and fails a valid deploy. Unowned residue is left for a later pass, once an owner is knowable.
+                    harper_logger_ts_1.default.trace?.(`Leaving unowned deploy staging ${deploymentDirPath} in place: no component names it`);
+                }
+            }
+            catch (error) {
+                // A verdict only when an activation was actually involved; a directory that cannot be swept is
+                // not one. A lock TIMEOUT is still recorded, because it is the signal `componentLoader` uses
+                // to defer this component until the deploy holding that lock finishes — and it leaves nothing
+                // durable behind, since `fail()` writes no marker for a deferral.
+                if (splitOwners) {
+                    for (const name of splitOwners)
+                        await fail(name, error);
+                }
+                else if (activationToFail)
+                    await fail(activationToFail, error);
+                else if (error instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError)
+                    await fail(owner ?? deployment.name, error);
+                else
+                    harper_logger_ts_1.default.warn(`Could not settle deploy staging ${deploymentDirPath}, which holds no activation journal:`, (0, harper_logger_ts_1.errorForLog)(error instanceof Error ? error : new Error(String(error))));
+            }
+            continue;
+        }
+        try {
+            // Disagreeing attributions are the one case with no automated way out: the restore gate blocks the
+            // SIDECAR's component (it takes the union, because restoring is destructive) while settlement
+            // keys the journal, so neither name's deploy could ever clear it. Reported as unsettleable
+            // against the sidecar's name, which is the component actually stalled, instead of stalling it
+            // silently on every boot.
+            // Unreadable is not disagreement. The journal is the authority on this path — it named its
+            // component and can settle it — so a sidecar that cannot be read must not block that; only one
+            // that CAN be read and names something else is the wedge below.
+            const sidecarOwner = await candidateComponentName(deploymentDirPath).catch(() => undefined);
+            const splitNames = splitAttributionOwners(journal.component, sidecarOwner);
+            if (splitNames) {
+                const split = splitAttributionError(deploymentDirPath, journal.component, splitNames[0]);
+                for (const name of splitNames)
+                    await fail(name, split);
+                continue;
+            }
+            const settling = journal;
+            await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, settling.component), () => settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, settling), {
+                purpose: 'activation-recovery',
+                ...RECOVERY_LOCK_WAIT,
+                isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(lockOwner.threadId),
+            });
+        }
+        catch (error) {
+            // The journal named its component, so attribution is exact however the settle failed.
+            await fail(journal.component, error);
+        }
+    }
+    const maxCount = getStagingRetentionMaxCount();
+    for (const [owner, builds] of dormant) {
+        for (const [component, error] of await reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount)) {
+            if (!failures.has(component))
+                failures.set(component, error);
+        }
+    }
+    return failures;
+}
+/**
+ * Record a settlement failure against a component. A lock TIMEOUT is a deferral, not a verdict, and only
+ * verdicts go on disk: a held lock means a live deploy, which settles its own journal, and a marker written
+ * here would outlive it and have `unsettleableComponentsFromDisk` fail a healthy component closed on every
+ * worker. Everything else is written so workers reach the same verdict — a well-formed journal this pass
+ * could not settle looks exactly like a deploy in flight otherwise. Marker write is best-effort.
+ */
+async function recordUnsettled(failures, component, error, deploymentDirPath) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    if (!failures.has(component))
+        failures.set(component, failure);
+    harper_logger_ts_1.default.error(`Could not settle the interrupted activation of ${component}:`, (0, harper_logger_ts_1.errorForLog)(failure));
+    if (failure instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError)
+        return;
+    await (0, promises_1.writeFile)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), failure.message, { mode: 0o600 }).catch((markerError) => harper_logger_ts_1.default.warn(`Could not record the unsettled activation of ${component}: ${errorMessage(markerError)}`));
+}
+/**
+ * Finish one owner's catalogued dormant builds after the scan. The catalog was read without the lock, so a
+ * deploy may have published a journal into one of these directories since — and if it then died mid-swap,
+ * only settlement brings the component back. So: settle any journal that appeared, then bound what is still
+ * dormant. The lock is taken only when there is something to do; a lock a live deploy holds is the same
+ * deferral the residue branch records.
+ */
+async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount) {
+    const failures = new Map();
+    let journaled;
+    for (const build of builds) {
+        // Anything but a clean ENOENT means "read it properly, under the lock".
+        const appeared = await presentOrAbsent((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL)).then((stats) => stats !== undefined, () => true);
+        if (appeared) {
+            journaled = build;
+            break;
+        }
+    }
+    if (!journaled && builds.length <= maxCount)
+        return failures;
+    try {
+        await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, owner), async () => {
+            const stillDormant = [];
+            for (const build of builds) {
+                let journal;
+                try {
+                    journal = await readActivationJournal((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL));
+                }
+                catch (error) {
+                    await recordUnsettled(failures, owner, error, build.deploymentDirPath);
+                    continue;
+                }
+                if (!journal) {
+                    stillDormant.push(build);
+                    continue;
+                }
+                // The lock held here is the SIDECAR owner's, as in the residue branch: a journal naming someone
+                // else is not settled under it, and both names are failed.
+                const splitNames = splitAttributionOwners(journal.component, owner);
+                if (splitNames) {
+                    const split = splitAttributionError(build.deploymentDirPath, journal.component, splitNames[0]);
+                    for (const name of splitNames)
+                        await recordUnsettled(failures, name, split, build.deploymentDirPath);
+                    continue;
+                }
+                try {
+                    await settleInterruptedActivation(componentsRootDirPath, build.deploymentDirPath, journal);
+                }
+                catch (error) {
+                    await recordUnsettled(failures, journal.component, error, build.deploymentDirPath);
+                }
+            }
+            if (stillDormant.length > maxCount)
+                await pruneDormantBuilds(owner, stillDormant, maxCount);
+        }, {
+            purpose: 'activation-recovery',
+            ...RECOVERY_LOCK_WAIT,
+            isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(lockOwner.threadId),
+        });
+    }
+    catch (error) {
+        // With a journal in view this is an activation that could not be settled — recorded exactly as the
+        // scan records one it saw directly (a timeout defers, anything else is a verdict). Without one it is
+        // hygiene that could not run, unless a live deploy holds the lock, which defers as everywhere else.
+        if (journaled) {
+            await recordUnsettled(failures, owner, error, journaled.deploymentDirPath);
+            return failures;
+        }
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (failure instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError) {
+            if (!failures.has(owner))
+                failures.set(owner, failure);
+            harper_logger_ts_1.default.info?.(`Deferred pruning the dormant staged builds of ${owner}: a deploy holds its lock`);
+        }
+        else {
+            harper_logger_ts_1.default.warn(`Could not prune the dormant staged builds of ${owner}:`, (0, harper_logger_ts_1.errorForLog)(failure));
+        }
+    }
+    return failures;
+}
+/**
+ * Retire and sweep the rollback records a settled activation leaves. Retiring throws — it is what makes a
+ * record non-authoritative, so a caller that removed the journal without it re-creates the inversion the
+ * journal prevents. Sweeping the displaced tree only costs disk, so it is logged.
+ */
+async function sweepAsideRecords(records, componentName, liveDirPath, asideStagingDir) {
+    for (const record of records) {
+        // RETIRING IS CORRECTNESS, not hygiene: the retired marker is what stops the legacy pass treating this
+        // record as authoritative and restoring the displaced tree over the candidate that was just rolled
+        // forward, once the journal that would otherwise hold it back is gone. A record left un-retired while the journal is removed re-creates exactly
+        // the inversion this protocol exists to prevent, so a failure here PROPAGATES — the caller keeps the
+        // journal and the next start retries.
+        const retiredMarkerPath = await retireExtractionAside(record);
+        // Sweeping the displaced tree is hygiene: it bounds disk, and a failure costs space rather than
+        // correctness, so it is logged. The retired marker above already makes the record non-authoritative.
+        await cleanupExtractionPaths({ name: componentName, dirPath: liveDirPath, logger: harper_logger_ts_1.default }, asideStagingDir, new Set([record, retiredMarkerPath])).catch((error) => harper_logger_ts_1.default.warn(`Settled ${componentName} but could not sweep ${record}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    }
+}
+/**
+ * Clear an earlier failed recovery's verdict once this settlement has decided. Treated as CORRECTNESS, not
+ * cleanup: main would report the component settled and load it while every worker read the stale marker and
+ * failed it closed, so a failure here throws and lets main reach the same verdict. The journal outlives it
+ * either way, so the next start settles again.
+ */
+async function clearUnsettledVerdict(deploymentDirPath, componentName) {
+    try {
+        await (0, promises_1.rm)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), { force: true });
+        // Flushed here, not with whatever follows: the journal's removal must never be the one that survives
+        // a crash alone, or the verdict outlives the only thing that would settle it again.
+        await syncDirectory(deploymentDirPath);
+    }
+    catch (error) {
+        throw new Error(`Could not clear the stale unsettled marker of ${componentName} at ` +
+            `${(0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER)}; the component stays failed closed on every thread ` +
+            `until that file can be removed: ${errorMessage(error)}`, { cause: error });
+    }
+}
+/**
+ * One interrupted activation, under the component preparation lock. Ambiguity exists only while the live
+ * path is absent, and there the `complete` marker is the roll-forward authority: without it the candidate
+ * was never validated, so the committed tree in the aside wins. Every branch is idempotent, so a crash
+ * during recovery is settled by the next run.
+ */
+async function settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, journal) {
+    const liveDirPath = (0, node_path_1.join)(componentsRootDirPath, journal.component);
+    const candidateDirPath = (0, node_path_1.join)(deploymentDirPath, journal.component);
+    const asideStagingDir = extractionStagingDirectory(liveDirPath);
+    const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
+    const exists = async (path) => (0, promises_1.lstat)(path).then(() => true, (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+    const liveExists = await exists(liveDirPath);
+    const candidateExists = await exists(candidateDirPath);
+    const candidateComplete = await exists((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER));
+    const asideRecords = await inProgressAsideRecords(asideStagingDir);
+    const rollForward = async () => {
+        if (!liveExists)
+            await renameThroughTransientHolder(candidateDirPath, liveDirPath);
+        // Unconditional, not only when THIS pass performed the rename: a crash after normal activation
+        // renamed the candidate but before it repaired the links leaves live present with stale targets, and
+        // gating the repair on the rename would skip exactly that case. Idempotent when there is nothing to
+        // re-point.
+        await repairRelocatedDependencyLinks(liveDirPath, candidateDirPath);
+        await syncRenameParents(candidateDirPath, liveDirPath);
+        // Retiring PROPAGATES from here: the retired marker is what stops the legacy pass restoring the tree
+        // this roll-forward just displaced. Failing the component closed and retrying at the next start is
+        // the cheaper mistake — the journal survives, so the verdict is re-derivable. Only the disk sweep
+        // inside is best-effort.
+        await sweepAsideRecords(asideRecords, journal.component, liveDirPath, asideStagingDir);
+    };
+    const rollBack = async (restoreFrom) => {
+        if (restoreFrom) {
+            await renameThroughTransientHolder(restoreFrom, liveDirPath);
+            await syncRenameParents(restoreFrom, liveDirPath);
+        }
+        for (const record of asideRecords) {
+            try {
+                await (0, promises_1.rm)(record, { recursive: true, force: true });
+            }
+            catch (error) {
+                // A record that survives removal is still AUTHORITATIVE to the legacy pass, and settlement is
+                // about to remove the journal that holds that pass back — so it would restore this older tree
+                // over the component just rolled back. Retiring is what makes a record non-authoritative, so
+                // do that instead of logging and moving on. A retire that ALSO fails propagates: the journal
+                // then survives and the next start retries, which is the same contract roll-forward uses.
+                harper_logger_ts_1.default.warn(`Rolled ${journal.component} back but could not remove ${record}:`, (0, harper_logger_ts_1.errorForLog)(error));
+                await retireExtractionAside(record);
+            }
+        }
+    };
+    if (!liveExists) {
+        if (candidateExists && candidateComplete) {
+            await rollForward();
+        }
+        else {
+            // The tree that was moved aside is the last committed one. A `-prior-absent` record means there
+            // was nothing live to begin with, so rolling back means leaving the component absent.
+            const restorable = asideRecords.find((record) => !record.endsWith(PRIOR_ABSENT_RECORD_SUFFIX));
+            if (!restorable && !asideRecords.length) {
+                throw new Error(`Cannot settle the interrupted activation of ${journal.component}: it has neither a live tree, ` +
+                    `a complete candidate, nor a rollback record, so no version of it can be recovered`);
+            }
+            await rollBack(restorable);
+        }
+    }
+    else if (candidateExists) {
+        // Live and candidate both present normally means B1 never ran: the swap had not started, so the live
+        // tree stands and the candidate goes.
+        //
+        // Unless a rollback record says B1 DID run. Then the committed tree is the one in the aside, and
+        // whatever sits at the live path was put there afterwards — a previous-version worker recreating its
+        // own directory, the case the extraction path guards with `identifyRollbackPlaceholder`. Rolling back
+        // there deletes the committed tree AND the validated candidate and leaves that stub serving, so this
+        // fails closed instead: both trees stay on disk for an operator to choose between.
+        // NOT conditioned on the candidate being complete. `rollBack()` below removes every aside record, and
+        // with a record present that tree is the last committed one — so deleting it destroys the only
+        // surviving copy of the previous release whether or not the candidate was ever validated. What
+        // `.complete` decides is which tree we would prefer, not whether discarding the other is safe.
+        const displaced = asideRecords.find((record) => !record.endsWith(PRIOR_ABSENT_RECORD_SUFFIX));
+        if (displaced) {
+            throw new Error(`Cannot settle the interrupted activation of ${journal.component}: its previous tree was moved to ` +
+                `${displaced}, but ${liveDirPath} exists again — something recreated it after the deploy moved ` +
+                `it aside, so which tree is current cannot be determined without losing one of them. Remove ` +
+                `whichever of the two is not the release you want once you have determined which that is.`);
+        }
+        // A STAGED artifact is not a disposable build. `rollBack()` removes the whole deployment directory,
+        // which is right for an immediate deploy — the candidate came from a payload the operator still has —
+        // but wrong for one somebody staged deliberately and may have had its payload reclaimed. The
+        // descriptor is what tells the two apart, and it is on disk precisely so recovery can. Returning the
+        // artifact to dormant by removing only the journal leaves it exactly as `deployment_id` expects it.
+        if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE))) {
+            // This branch returns early and so reaches none of the settled tail below — which can be careless
+            // about both, because it removes the whole directory afterwards. This one keeps it, so the order
+            // the two unlinks REACH STORAGE decides whether the artifact survives: `.unsettled` with no
+            // journal is a verdict nothing will ever settle and the next retention pass deletes the build on.
+            // Its flush is the barrier between the two unlinks: skipping it would let the journal's removal
+            // persist alone, leaving a verdict nothing will settle again. Throwing is safe here and leaves the
+            // journal, so the next start settles again. Windows cannot fsync a directory, which is why the
+            // residue pass also refuses to read this state as disposable — see DESIGN.md.
+            await clearUnsettledVerdict(deploymentDirPath, journal.component);
+            await (0, promises_1.rm)(journalPath, { force: true });
+            // Nothing may throw past the journal removal, the rule the settled tail follows: the caller
+            // records a failure by writing `.unsettled`, which is the state this branch exists to avoid. An
+            // unflushed removal is the safe direction — a power loss resurrects a journal that settles again.
+            await syncDirectory(deploymentDirPath).catch((error) => harper_logger_ts_1.default.warn(`Returned the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ${journal.component} to dormant but ` +
+                `could not flush that to storage; a power loss could resurrect its activation journal:`, (0, harper_logger_ts_1.errorForLog)(error)));
+            harper_logger_ts_1.default.info?.(`Returned the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ${journal.component} to dormant after an ` +
+                `activation that never moved its live tree aside`);
+            return;
+        }
+        await rollBack();
+    }
+    else {
+        // The candidate is already live; only the tail of the transaction was lost.
+        await rollForward();
+    }
+    // The same ordering barrier normal activation uses, and for the same reason: the journal is the only
+    // thing left telling the legacy pass not to restore an aside. Removing it while an
+    // `.in-progress-*` record still names the displaced tree — because the retire or the sweep did not
+    // reach storage — lets that pass put the old version back over the new one at the next start. Flush the
+    // aside directory first, and leave the journal in place if that cannot be confirmed; recovery is
+    // idempotent, so the next run settles it again.
+    try {
+        await syncDirectory(asideStagingDir);
+        await syncDirectory((0, node_path_1.dirname)(asideStagingDir));
+    }
+    catch (error) {
+        harper_logger_ts_1.default.warn(`Settled the interrupted activation of ${journal.component} but could not flush its rollback record; ` +
+            `leaving the journal for the next start: ${errorMessage(error)}`);
+        return;
+    }
+    // Best-effort, matching the activation path: the activation is settled by this point, so a transient
+    // EBUSY removing staging must not throw out of the recovery pass and take the other components with it.
+    // An earlier failed recovery may have left an unsettled marker here. Cleared BEFORE the journal and
+    // treated as correctness: main would report this component settled and load it, while every worker read
+    // the stale marker and failed it closed.
+    await clearUnsettledVerdict(deploymentDirPath, journal.component);
+    await (0, promises_1.rm)(journalPath, { force: true }).catch((error) => harper_logger_ts_1.default.warn(`Settled ${journal.component} but could not remove its activation journal:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => harper_logger_ts_1.default.warn(`Settled ${journal.component} but could not clean up its staging directory:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
+}
+/** Mark a candidate build+validation complete. Idempotent, so a retried activation is not a failure. */
+/**
+ * fsync the candidate's contents before `.complete` vouches for them — otherwise the control files can
+ * outlive the tree after a power loss and recovery rolls forward onto a truncated one.
+ */
+// Codes that mean "this platform or filesystem will not fsync this handle", as opposed to "the write did
+// not reach storage". Windows raises EPERM fsyncing perfectly healthy files, and network/overlay mounts
+// return EINVAL or ENOTSUP — none of which say anything about durability, and all of which would otherwise
+// fail every deploy on those platforms.
+const UNSUPPORTED_SYNC_CODES = new Set(['EPERM', 'EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'EBADF', 'EISDIR']);
+function isUnsupportedSync(error) {
+    return UNSUPPORTED_SYNC_CODES.has(error?.code ?? '');
+}
+// How many file syncs run at once while flushing a candidate. Serial open/sync/close over a large
+// dependency tree adds seconds to every activation, all of it under the component preparation lock; a small
+// fan-out keeps the ordering guarantee (everything is synced before `.complete` is written) without paying
+// per-file latency one file at a time.
+const CANDIDATE_SYNC_CONCURRENCY = 16;
+// Directories walked at once when re-pointing dependency links after a swap; a pnpm or monorepo tree is
+// thousands of directories and a serial depth-first walk after every activation is a real cost.
+const LINK_REPAIR_CONCURRENCY = 8;
+async function syncTreeContents(rootPath, foreignTree = false) {
+    // Real durability failures propagate: the deploy fails, which is safe because the live tree is
+    // untouched. Platform "cannot fsync this handle" codes do not — treating those as durability failures
+    // fails every deploy on Windows.
+    const entries = await (0, promises_1.readdir)(rootPath, { withFileTypes: true }).catch((error) => {
+        // Same reasoning as the per-file tolerance below: a directory inside a foreign tree that this uid
+        // cannot list is not ours to make durable, and failing here fails a deploy over a directory the
+        // deploy never wrote.
+        if (foreignTree && error?.code === 'EACCES') {
+            harper_logger_ts_1.default.trace?.(`Sync of ${rootPath} unavailable: ${errorMessage(error)}`);
+            return undefined;
+        }
+        throw error;
+    });
+    if (!entries)
+        return;
+    const syncFile = async (entryPath) => {
+        let handle;
+        try {
+            handle = await (0, promises_1.open)(entryPath, 'r');
+        }
+        catch (error) {
+            // `foreignTree`: a `file:<directory>` candidate is a symlink to a tree this deploy does not own,
+            // so it can hold files the Harper uid cannot open. Those are not ours to make durable and their
+            // EACCES says nothing about whether the install output beside them reached storage — while
+            // failing here would fail an otherwise valid deploy over a file the deploy never touched. The
+            // install output itself is written as this uid, so it is readable and still fsynced.
+            //
+            // The limit of that: this cannot tell a developer's unreadable source file from an install
+            // script that deliberately made its OWN output unreadable, so `.complete` could certify output
+            // that was never synced. Only for a `file:` candidate, and only for a script that chmods its
+            // own artifacts away from the uid that has to run them.
+            if (isUnsupportedSync(error) || (foreignTree && error?.code === 'EACCES')) {
+                harper_logger_ts_1.default.trace?.(`Sync of ${entryPath} unavailable: ${errorMessage(error)}`);
+                return;
+            }
+            throw error;
+        }
+        try {
+            await handle.sync();
+        }
+        catch (error) {
+            if (!isUnsupportedSync(error))
+                throw error;
+            harper_logger_ts_1.default.trace?.(`Sync of ${entryPath} unsupported: ${errorMessage(error)}`);
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    };
+    const pending = [];
+    for (const entry of entries) {
+        const entryPath = (0, node_path_1.join)(rootPath, entry.name);
+        if (entry.isDirectory()) {
+            await syncTreeContents(entryPath, foreignTree);
+        }
+        else if (entry.isFile()) {
+            pending.push(syncFile(entryPath));
+            if (pending.length >= CANDIDATE_SYNC_CONCURRENCY) {
+                await Promise.all(pending.splice(0));
+            }
+        }
+    }
+    await Promise.all(pending);
+    await syncDirectory(rootPath);
+}
+async function markCandidateComplete(componentDirPath, deploymentId, componentName) {
+    // Contents first: `.complete` is roll-forward AUTHORITY, so it must not be durable before the tree it
+    // vouches for.
+    //
+    // A `file:<directory>` candidate IS a symlink to a tree this deploy does not own, but the dependency
+    // install writes THROUGH it — so the tree still has to be walked, or the install output `.complete`
+    // vouches for is never made durable. Only the foreign files alongside it are tolerated: see
+    // `syncTreeContents`.
+    const candidatePath = candidateApplicationPath(componentDirPath, deploymentId);
+    const candidateIsLink = await (0, promises_1.lstat)(candidatePath).then((stats) => stats.isSymbolicLink(), (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+    await syncTreeContents(candidatePath, candidateIsLink);
+    try {
+        await writeControlFileDurably(candidateComponentFilePath(componentDirPath, deploymentId), componentName);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    try {
+        await writeControlFileDurably(candidateCompleteMarkerPath(componentDirPath, deploymentId), '');
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
+/**
+ * Make the newly created ancestors of a deployment directory durable, child-first.
+ *
+ * Only a staged artifact needs this. A deploy's own candidate is transient — power loss just abandons a
+ * build nobody was told about — but a stage is ACKNOWLEDGED, and `writeControlFileDurably` flushes only the
+ * control file's immediate parent while `ensureSecureStagingDirectory` flushes none. Without this a stage
+ * can report success before the `.deploy-staging/<id>` entry exists on storage, and the automatic payload
+ * reclaim may already have dropped the tarball it could have been rebuilt from. Best-effort on Windows, like
+ * every other directory sync here.
+ */
+async function syncArtifactAncestors(deploymentDirPath) {
+    const stagingRoot = (0, node_path_1.dirname)(deploymentDirPath);
+    for (const directory of [deploymentDirPath, stagingRoot, (0, node_path_1.dirname)(stagingRoot)]) {
+        await syncDirectory(directory);
+    }
+}
+/**
+ * Make a built and validated candidate live, as one compensating transaction over two effects: the live tree
+ * moves aside, then the candidate takes its place. Root config is NOT one of them — for an immediate deploy
+ * it is still published before the build, unchanged, and making it transactional is tracked separately
+ * (#2315). A delayed activation hands its artifact's recorded entry in as `afterJournal`, which publishes it
+ * from inside the window a crash rolls forward from — see that call site.
+ *
+ * The candidate must ALREADY be certified: `markCandidateComplete` is the caller's, so a delayed activation
+ * does not re-walk and re-fsync a whole dependency tree it certified when it was built. The activation
+ * journal is still written and fsynced BEFORE the first rename, so a crash anywhere below is recoverable —
+ * see `settleInterruptedActivation` for the state matrix. The second rename is the COMMIT POINT: nothing
+ * after it may compensate, because the live path holds the candidate and renaming the aside back over it
+ * cannot succeed.
+ */
+async function activateCandidateApplication(application, deploymentId, options = {}) {
+    const liveDirPath = application.dirPath;
+    const candidateDirPath = candidateApplicationPath(liveDirPath, deploymentId);
+    const deploymentDirPath = candidateDeploymentDirPath(liveDirPath, deploymentId);
+    const asideStagingDir = extractionStagingDirectory(liveDirPath);
+    // A symlink counts: a `file:<directory>` deploy links the source rather than extracting it, and that
+    // link is what gets swapped into the live path.
+    const candidateStat = await (0, promises_1.lstat)(candidateDirPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (!candidateStat || !(candidateStat.isDirectory() || candidateStat.isSymbolicLink())) {
+        throw new Error(`Cannot activate ${application.name}: no candidate build at ${candidateDirPath}`);
+    }
+    const journalPath = activationJournalPath(liveDirPath, deploymentId);
+    // B1 — the live tree moves aside. It stays the rollback source until B4 retires it.
+    let asidePath;
+    let priorAbsentRecordPath;
+    // The swap below moves the previous tree back and forth around every wait, so a chosen aside path no
+    // longer implies the tree is at it — and compensation needs to know which.
+    let liveIsDisplaced = false;
+    const restoreLive = async () => {
+        if (liveIsDisplaced) {
+            await renameThroughTransientHolder(asidePath, liveDirPath);
+            liveIsDisplaced = false;
+        }
+        else if (priorAbsentRecordPath)
+            await (0, promises_1.rm)(priorAbsentRecordPath, { force: true });
+        // Nothing was displaced and no record was written, so there is nothing to put back and no rename to
+        // flush — the failure happened before the first effect.
+        if (asidePath || priorAbsentRecordPath) {
+            await syncRenameParents(asidePath ?? priorAbsentRecordPath, liveDirPath);
+        }
+    };
+    /**
+     * Put a compensated candidate back to DORMANT — complete, described, no journal — so it is a retryable
+     * artifact rather than one the next preparation destroys.
+     *
+     * Without this, a failure that leaves the journal in place makes `settleStagingForComponent` read
+     * live-plus-candidate as an activation that never got there and remove the whole deployment directory;
+     * for a first deploy the restored state is live-ABSENT, and it rolls the candidate forward instead,
+     * ahead of the caller's own verification. Both destroy an artifact whose whole purpose is to be
+     * activated again.
+     *
+     * The unlink needs its own barrier: syncing the aside directories persists the rollback record's
+     * disposal, not the journal's, so without this sync a power loss resurrects a journal the operator was
+     * told had been rolled back. Best-effort by necessity — failing here must not replace the activation
+     * failure the caller is reporting — so a failure says explicitly that the artifact is not retryable, and
+     * the surviving journal is exactly what startup recovery settles.
+     */
+    const returnToDormant = async () => {
+        try {
+            await (0, promises_1.rm)(journalPath, { force: true });
+        }
+        catch (error) {
+            application.logger.warn(`Restored ${application.name} after a failed activation, but its staged build ${deploymentId} still ` +
+                `carries an activation journal and is not retryable until recovery settles it:`, error);
+            return;
+        }
+        // The journal is gone in this process, so the artifact is retryable now; what is uncertain is whether
+        // its removal reached storage.
+        await syncDirectory(deploymentDirPath).catch((error) => application.logger.warn(`Restored ${application.name} and returned its staged build ${deploymentId} to a retryable state, but ` +
+            `could not flush that to storage; a power loss could resurrect its activation journal:`, error));
+    };
+    /**
+     * One pre-commit failure boundary, with the journal write inside it: every step from there to the commit
+     * rename leaves a journal behind if it only rethrows, and the next settlement then deletes a certified
+     * artifact, or (first deploy, live absent) activates it with nobody asking. Nothing below the commit
+     * rename may enter this catch — see B2.
+     */
+    let pendingEffect = 'record the activation';
+    let undoAfterJournal;
+    try {
+        try {
+            await writeControlFileDurably(journalPath, JSON.stringify({
+                v: ACTIVATION_JOURNAL_VERSION,
+                component: application.name,
+                candidateId: deploymentId,
+            }));
+        }
+        catch (error) {
+            // An existing journal is a retry of this same activation, not a conflict.
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        pendingEffect = 'prepare the component staging directory';
+        await ensureExtractionStagingDirectory(asideStagingDir);
+        pendingEffect = 'read the live component directory';
+        const liveExists = await (0, promises_1.lstat)(liveDirPath).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        application.isNewComponent = !liveExists;
+        pendingEffect = 'move the previous version aside';
+        if (liveExists) {
+            asidePath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
+            await renameThroughTransientHolder(liveDirPath, asidePath);
+            liveIsDisplaced = true;
+        }
+        else {
+            priorAbsentRecordPath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}${PRIOR_ABSENT_RECORD_SUFFIX}`);
+            await (0, promises_1.writeFile)(priorAbsentRecordPath, '', { flag: 'wx', mode: 0o600 });
+        }
+        // Letting a storage failure escape here leaves live already moved aside, and the caller reads an
+        // uncompensated throw as an ordinary build failure and discards the candidate, its `.complete` marker
+        // and its journal: the component ends up with no version at all and nothing saying how to get one back.
+        pendingEffect = 'record the displaced component directory';
+        await syncRenameParents(liveDirPath, asidePath ?? priorAbsentRecordPath);
+        // Config is published HERE — after B1, before the commit — because this is the only point where the
+        // on-disk state recovery would find rolls FORWARD to the certified artifact: live is displaced, the
+        // candidate is complete, and the rollback record exists. Publishing before B1 (with or without the
+        // journal) leaves live present and the candidate present with no rollback record, which settlement
+        // reads as an activation that never started: it deletes the deployment directory, and the next boot
+        // re-resolves the published package identifier from the registry instead — the substitution this step
+        // exists to prevent.
+        //
+        // A crash in the remaining window — after the roll-forward state exists but before this publish — is
+        // the inverse hazard: `rollForward()` renames the candidate live and publishes nothing, so the
+        // certified artifact serves under the PREVIOUS release's config. That includes its ISOLATION intent,
+        // which is a containment boundary and not just a version string: a component staged to run isolated
+        // comes back non-isolated after an ordinary crash, with nothing in the operation reporting it.
+        // Closing it needs config to be an effect of the journal itself, which is #2315 step 3.
+        pendingEffect = 'publish the root configuration';
+        undoAfterJournal = await options.afterJournal?.();
+        // B2 — the candidate becomes live. THE RENAME IS THE COMMIT POINT: nothing after it may compensate,
+        // because the live path now holds the candidate and renaming the aside back over it cannot succeed. A
+        // compensating step there fails its own rollback and reports a failure for a deploy that is live. It is
+        // the LAST statement in this block for that reason.
+        pendingEffect = 'move the candidate into place';
+        await renameThroughTransientHolder(candidateDirPath, liveDirPath, {
+            // The previous version occupies the live path through the wait rather than the component being
+            // absent for the whole budget: a read of a component file, and any concurrent scan of the
+            // components root, still finds the last committed tree. (Watchers are already paused for the
+            // deploy, so they are not what this protects.) A first-ever deploy has nothing to put back.
+            onBackoff: async (delayMs, deadline) => {
+                if (!liveIsDisplaced)
+                    return (0, promises_3.setTimeout)(delayMs);
+                await renameThroughTransientHolder(asidePath, liveDirPath, { deadline });
+                liveIsDisplaced = false;
+                await syncRenameParents(asidePath, liveDirPath);
+                await (0, promises_3.setTimeout)(delayMs);
+                await renameThroughTransientHolder(liveDirPath, asidePath, { deadline });
+                liveIsDisplaced = true;
+                await syncRenameParents(liveDirPath, asidePath);
+            },
+        });
+    }
+    catch (error) {
+        // Whether the journal can still carry this activation forward, decided BEFORE compensation removes the
+        // evidence it is read from. Only a first-ever deploy qualifies: `restoreLive` leaves the live path
+        // absent, and recovery reads absent-plus-complete-candidate as a roll forward. A component that
+        // already had a tree gets that tree back and loses its rollback record with it, so the next settle
+        // reads live-plus-candidate-with-no-record and returns the artifact to dormant whatever the journal
+        // says — keeping it there defers the same verdict to the next start and strands config until then.
+        const recoveryCanRollForward = priorAbsentRecordPath !== undefined;
+        await compensate(error, pendingEffect, restoreLive, application);
+        let configRestored = true;
+        if (undoAfterJournal) {
+            configRestored = await undoAfterJournal().then(() => true, (undoError) => {
+                application.logger.warn(`Restored ${application.name} after a failed activation but could not restore its root config, ` +
+                    `which still names deployment ${deploymentId}` +
+                    (recoveryCanRollForward
+                        ? '; keeping its activation journal so recovery can roll the certified build forward instead:'
+                        : '. The certified build stays dormant and the previous release stays live, so the two ' +
+                            'disagree until an operator republishes the component or activates it again:'), undoError);
+                return false;
+            });
+        }
+        // Kept only where it changes the outcome. Config is stranded either way for a component that already
+        // had a tree — the durable-config window #2315 step 3 closes — and a journal that recovery will only
+        // settle back to dormant buys nothing for holding it.
+        if (configRestored || !recoveryCanRollForward)
+            await returnToDormant();
+        throw error;
+    }
+    // Past the point of no return: each failure below leaves a state recovery settles forward, so they are
+    // logged, not thrown.
+    let swapDurable = true;
+    try {
+        await syncRenameParents(candidateDirPath, liveDirPath);
+    }
+    catch (error) {
+        // The rename may not have reached storage. Retiring the record and removing the journal WOULD reach
+        // it, and a power loss then leaves no live entry, no rollback record, and nothing saying to roll
+        // forward. Both are skipped so the journal carries the activation to the next start.
+        swapDurable = false;
+        application.logger.warn(`Deployed ${application.name} but could not flush the swap to storage:`, error);
+    }
+    // The tree moved, so any dependency link that named its build path is now dangling.
+    await repairRelocatedDependencyLinks(liveDirPath, candidateDirPath);
+    const settledRecord = asidePath ?? priorAbsentRecordPath;
+    let retired = false;
+    // Skipped entirely when the swap is not known to be on storage, so the journal below survives.
+    if (swapDurable) {
+        try {
+            const retiredMarkerPath = await retireExtractionAside(settledRecord);
+            // Retiring only MARKS the displaced tree disposable. Without this sweep the tree every deploy
+            // displaces stays under `.deploy-aside/<component>` forever, so the components root grows by a
+            // whole component version per deploy.
+            await cleanupExtractionPaths(application, asideStagingDir, new Set([settledRecord, retiredMarkerPath]));
+            // Before the journal goes: if the journal's removal persists but the record's does not, startup sees
+            // an in-progress aside with no journal and the legacy pass restores the old tree over the new one.
+            await syncDirectory(asideStagingDir);
+            await syncDirectory((0, node_path_1.dirname)(asideStagingDir));
+            retired = true;
+        }
+        catch (error) {
+            application.logger.warn(`Deployed ${application.name} but could not retire its rollback record:`, error);
+        }
+    }
+    // The journal goes LAST, and only once the rollback record is settled: removing it while an
+    // `.in-progress-*` record still names the displaced tree lets the legacy pass restore the old tree.
+    if (retired) {
+        await (0, promises_1.rm)(journalPath, { force: true }).catch((error) => application.logger.warn(`Deployed ${application.name} but could not remove its activation journal:`, error));
+        await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => application.logger.warn(`Deployed ${application.name} but could not clean up its staging directory:`, error));
+        await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
+    }
+}
+/**
+ * Marks a failure where compensation ITSELF failed, so the previous version is not back and the live path
+ * may be absent. The candidate, its `.complete` marker and its journal are then the only way back — recovery
+ * rolls that state forward — so they must survive, and the caller keys on this to skip discarding them.
+ */
+const COMPENSATION_INCOMPLETE = Symbol('compensationIncomplete');
+function compensationIncomplete(error) {
+    return Boolean(error?.[COMPENSATION_INCOMPLETE]);
+}
+/**
+ * Undo an activation effect, folding a compensation failure into the original error rather than replacing
+ * it — the first error is what the operator needs, the second is why the node still needs attention.
+ */
+async function compensate(error, what, undo, application) {
+    try {
+        await undo();
+    }
+    catch (undoError) {
+        // Whatever blocked the original operation plausibly blocks its undo too — a rename into a path
+        // something else holds open fails the same way twice.
+        const failure = new AggregateError([error, undoError], `Failed to ${what} for ${application.name}: ${errorMessage(error)}; ` +
+            `also failed to restore the previous version: ${errorMessage(undoError)}`);
+        failure[COMPENSATION_INCOMPLETE] = true;
+        throw failure;
+    }
+}
+/**
+ * Re-point dependency links that name the candidate's build path, now that it has become live. npm links a
+ * `file:` dependency relatively on POSIX (survives the rename) but as an ABSOLUTE junction on Windows, which
+ * then names a staging path that no longer exists. Rewriting beats `--install-links`, which would change
+ * dependency semantics on every platform to fix one.
+ */
+async function repairRelocatedDependencyLinks(liveDirPath, builtAtPath) {
+    const relinkOne = async (entryPath) => {
+        let target;
+        try {
+            target = await (0, promises_1.readlink)(entryPath);
+        }
+        catch {
+            return;
+        }
+        const normalized = stripExtendedLengthPrefix(target);
+        // Containment, not a prefix match: `startsWith` classifies `<build>-shared` as inside `<build>` and
+        // would rewrite it to an unrelated live path.
+        const within = (0, node_path_1.relative)(builtAtPath, normalized);
+        if (within.startsWith('..') || (0, node_path_1.isAbsolute)(within))
+            return;
+        const repaired = (0, node_path_1.join)(liveDirPath, within);
+        // The replacement is created BEFORE the old link is dropped, and swapped in by rename. A
+        // remove-then-create loses the dependency outright when the create fails.
+        const stagedLink = `${entryPath}.relink-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+        try {
+            await (0, promises_1.symlink)(repaired, stagedLink, 'junction');
+            try {
+                await (0, promises_1.rename)(stagedLink, entryPath);
+            }
+            catch (renameError) {
+                // Windows cannot rename over an existing junction, so the old one has to go first — and if the
+                // second rename then fails the same way, the original target is put back rather than leaving
+                // nothing behind.
+                if (process.platform !== 'win32')
+                    throw renameError;
+                await (0, promises_1.rm)(entryPath, { recursive: true, force: true });
+                try {
+                    await (0, promises_1.rename)(stagedLink, entryPath);
+                }
+                catch (secondError) {
+                    await (0, promises_1.symlink)(normalized, entryPath, 'junction').catch(() => { });
+                    throw secondError;
+                }
+            }
+        }
+        catch (error) {
+            await (0, promises_1.rm)(stagedLink, { recursive: true, force: true }).catch(() => { });
+            harper_logger_ts_1.default.warn(`Could not re-point ${entryPath} after activation: ${errorMessage(error)}`);
+        }
+    };
+    // ONE bounded pool over a shared queue, not per-directory concurrency: bounding each parent
+    // independently let every one of N workers start N more, so a deep pnpm or monorepo tree fanned out to
+    // thousands of simultaneous opens. An EMFILE there would surface as skipped subtrees and dangling links.
+    const pending = [(0, node_path_1.join)(liveDirPath, 'node_modules')];
+    let active = 0;
+    const visit = async (dirPath) => {
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(dirPath, { withFileTypes: true });
+        }
+        catch (error) {
+            // Not silent. A missing directory is ordinary — the tree has no `node_modules`, or an install
+            // removed one — but an EACCES or EMFILE here means links under it were never examined, which is
+            // exactly the state that leaves a component running against a dangling dependency.
+            if (error?.code !== 'ENOENT') {
+                harper_logger_ts_1.default.warn(`Could not scan ${dirPath} for links to re-point after activation:`, (0, harper_logger_ts_1.errorForLog)(error));
             }
-            if (gitRef) {
-                tarballPath = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath);
+            return;
+        }
+        // Every directory, not just `@scope` containers and nested `node_modules`: a dependency installed from
+        // outside the tree can be linked from deeper in.
+        for (const entry of entries) {
+            const entryPath = (0, node_path_1.join)(dirPath, entry.name);
+            if (entry.isSymbolicLink())
+                await relinkOne(entryPath);
+            else if (entry.isDirectory())
+                pending.push(entryPath);
+        }
+    };
+    const worker = async () => {
+        for (;;) {
+            const next = pending.pop();
+            if (next === undefined) {
+                // Another worker may still be about to enqueue children, so only stop once nothing is in flight.
+                if (active === 0)
+                    return;
+                await new Promise((resolve) => setImmediate(resolve));
+                continue;
             }
-            else {
-                const packArgs = ['pack', '--json', application.packageIdentifier];
-                if (!allowScripts) {
-                    packArgs.push('--ignore-scripts');
-                }
-                else if (application.gitCredentialEnv) {
-                    application.logger.warn(`Deploying ${application.name} from a git reference with install scripts enabled: the repository's ` +
-                        `prepare/build scripts and its dependencies' install scripts run on this node during the clone and ` +
-                        `can read the git credential. Unset install_allow_scripts to keep the credential out of their reach.`);
+            active++;
+            try {
+                await visit(next);
+            }
+            finally {
+                active--;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: LINK_REPAIR_CONCURRENCY }, worker));
+}
+/** Windows junction targets come back with an extended-length `\\?\` prefix that plain paths never have. */
+function stripExtendedLengthPrefix(target) {
+    return target.startsWith('\\\\?\\') ? target.slice(4) : target;
+}
+/** Remove a candidate's whole deployment directory, best-effort — it is never the last good copy. */
+async function discardCandidate(application, deploymentId) {
+    const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
+    await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => application.logger.warn(`Failed to remove the abandoned deploy candidate at ${deploymentDirPath}:`, error));
+    // And the staging root itself once nothing is in it, so an idle install leaves the components root as
+    // it found it. ENOTEMPTY just means a concurrent deploy still owns a candidate.
+    await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
+}
+/**
+ * Build a deploy candidate at `.deploy-staging/<deploymentId>/<component>`, leaving the live tree
+ * completely untouched — this is what lets the previous version keep serving through the clone, the
+ * extraction and the dependency install.
+ *
+ * Failure needs no compensation, which is the whole point: nothing about the live component was modified,
+ * so the abandoned candidate is simply removed and the error propagates.
+ */
+async function buildCandidateApplication(application, deploymentId, options = {}) {
+    const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
+    const candidateDirPath = candidateApplicationPath(application.dirPath, deploymentId);
+    await ensureSecureStagingDirectory((0, node_path_1.dirname)(deploymentDirPath));
+    await claimDeploymentDirectory(deploymentDirPath, application.name);
+    try {
+        // Replaced, not extracted into: a prior attempt on this id may have left a partial tree.
+        await (0, promises_1.rm)(candidateDirPath, { recursive: true, force: true });
+        const resolved = await resolveApplicationTarball(application);
+        if (resolved.kind === 'link' && options.rejectLinkSource) {
+            // What the operator asked for, not a server fault: the same component deploys immediately.
+            throw new hdbError_ts_1.ClientError(`Cannot stage ${application.name} from ${application.packageIdentifier}: a 'file:' directory is linked ` +
+                `rather than copied, so the bytes activated later are not the bytes this build certified`);
+        }
+        if (resolved.kind === 'link') {
+            // A `file:` directory becomes a symlink AT THE CANDIDATE PATH, so it is validated and swapped in
+            // like any other candidate instead of appearing at the live path unvalidated.
+            await (0, promises_1.symlink)(resolved.sourceDirPath, candidateDirPath, 'dir');
+        }
+        else {
+            const { tarball, tarballPath, shouldDeleteTarball } = resolved;
+            try {
+                await extractTarballInto(tarball, candidateDirPath, deploymentDirPath);
+            }
+            finally {
+                if (!tarball.destroyed)
+                    tarball.destroy();
+                if (shouldDeleteTarball && tarballPath) {
+                    await (0, promises_1.rm)(tarballPath, { force: true }).catch((error) => application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error));
                 }
-                tarballPath = await runNpmPack(application, packArgs, parentDirPath, application.gitCredentialEnv);
             }
-            shouldDeleteTarball = true;
-            tarball = (0, node_fs_1.createReadStream)(tarballPath);
         }
+        // The credential socket only has to be up for extraction — that is where npm resolves and clones a
+        // git-reference package. Closed BEFORE the install so the dependency tree's own install scripts,
+        // which are arbitrary code from the registry running as this uid, cannot ask the helper for the
+        // deployer's git token. `prepareApplication`'s finally still calls this; it is idempotent.
+        await application.cleanupGitCredentialSession();
+        await installApplication(application, candidateDirPath);
+        return candidateDirPath;
     }
-    // Replace any existing component directory atomically instead of clearing it in
-    // place. A previous version's worker can still be running and actively writing
-    // into this directory — e.g. a live Next.js app writing into `.next/cache` — and
-    // an in-place recursive rm races that writer: rm empties `.next`, then its leaf
-    // `rmdir('.next')` fails with ENOTEMPTY because the worker just re-created a cache
-    // entry. (`force: true` only suppresses ENOENT; ENOTEMPTY is not retried unless
-    // `maxRetries` is set, and a continuously-writing app would outlast retries
-    // anyway.) Renaming the old directory aside is atomic and immune to the race: the
-    // still-running worker keeps writing into the renamed inode harmlessly until it's
-    // replaced on restart, and the aside copy is removed best-effort below.
-    //
-    // The aside lives under a hidden, component-scoped staging directory inside the
-    // components root: same filesystem as the source so the rename stays atomic, the
-    // leading dot keeps loadComponentDirectories from picking it up as a phantom
-    // component, and the per-component path means a sibling component never collides
-    // with (or sweeps) another's aside.
-    const asideStagingDir = (0, node_path_1.join)((0, node_path_1.dirname)(application.dirPath), exports.ASIDE_STAGING_DIR, (0, node_path_1.basename)(application.dirPath));
-    let asidePath;
-    try {
-        await (0, promises_1.access)(application.dirPath, promises_1.constants.F_OK);
-        await (0, promises_1.mkdir)(asideStagingDir, { recursive: true });
-        const candidateAsidePath = (0, node_path_1.join)(asideStagingDir, `${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
-        await (0, promises_1.rename)(application.dirPath, candidateAsidePath);
-        asidePath = candidateAsidePath;
+    catch (error) {
+        await discardCandidate(application, deploymentId);
+        throw error;
     }
-    catch (err) {
-        // Ignore does not exist error
-        if (err.code !== 'ENOENT') {
-            throw err;
+}
+async function recoverOrCleanupStaleExtractionPaths(application, asideStagingDir) {
+    const entries = await (0, promises_1.readdir)(asideStagingDir, { withFileTypes: true });
+    const entryNames = new Set(entries.map((entry) => entry.name));
+    const paths = new Set(entries.map((entry) => (0, node_path_1.join)(asideStagingDir, entry.name)));
+    const recoveryRecords = entries
+        .filter((entry) => isExtractionRecoveryRecord(entry) &&
+        entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX) &&
+        !entryNames.has(`${RETIRED_ASIDE_PREFIX}${entry.name.slice(IN_PROGRESS_ASIDE_PREFIX.length)}`))
+        .map((entry) => ({
+        entry,
+        priorStateAbsent: isPriorAbsentRecoveryRecord(entry),
+        timestamp: extractionAsideTimestamp(entry.name),
+    }))
+        .filter(({ timestamp }) => Number.isFinite(timestamp))
+        .sort((left, right) => right.timestamp - left.timestamp);
+    const recoveryRecord = recoveryRecords.find(({ priorStateAbsent }) => !priorStateAbsent) ??
+        recoveryRecords.find(({ priorStateAbsent }) => priorStateAbsent);
+    if (recoveryRecord) {
+        // A journal outranks the record. Without this the pass restores the tree a completed activation
+        // displaced, back over the candidate it committed — the inversion the journal exists to prevent, and
+        // reachable on any thread whose settlement did not run or did not succeed. Enforced HERE, at the one
+        // place a tree is restored, so every entry point is covered by construction rather than by each
+        // caller remembering to settle first — and so a component with nothing left to restore still loads.
+        const journaled = await journaledDeploymentForComponent((0, node_path_1.dirname)(application.dirPath), application.name);
+        if (journaled) {
+            throw new Error(`Refusing to restore ${application.name} from ${recoveryRecord.entry.name}: the interrupted ` +
+                `activation in ${journaled} is not settled, and its journal is the only record of which tree ` +
+                `is current. If that journal names no component at all it cannot settle itself; remove that ` +
+                `directory once you have determined which tree is current.`);
+        }
+        const recoveryPath = (0, node_path_1.join)(asideStagingDir, recoveryRecord.entry.name);
+        // Retire the losing candidates durably; a cleanup that fails must not let a later
+        // pass adopt one of them and restore an older tree over the one recovered here.
+        for (const { entry } of recoveryRecords) {
+            if (entry === recoveryRecord.entry)
+                continue;
+            paths.add(await retireExtractionAside((0, node_path_1.join)(asideStagingDir, entry.name)));
         }
+        await rollbackExtractedDirectory(application, asideStagingDir, recoveryRecord.priorStateAbsent ? undefined : recoveryPath, paths, false);
+        application.logger.warn((recoveryRecord.priorStateAbsent
+            ? `Removed the partial ${application.name} component directory after an interrupted first deploy`
+            : `Recovered the previous ${application.name} component directory after an interrupted deploy`) +
+            (recoveryRecords.length > 1 ? `; discarded ${recoveryRecords.length - 1} older recovery candidates` : ''));
+        return;
     }
-    // A directory existed for this component name prior to this deploy, so this is a redeploy of
-    // an already-active component rather than a first-time deploy. See `isNewComponent` above.
-    if (asidePath)
-        application.isNewComponent = false;
+    await cleanupExtractionPaths(application, asideStagingDir, paths);
+}
+function isPriorAbsentRecoveryRecord(entry) {
+    return entry.isFile() && entry.name.endsWith(PRIOR_ABSENT_RECORD_SUFFIX);
+}
+function isExtractionRecoveryRecord(entry) {
+    return entry.isDirectory() || entry.isSymbolicLink() || isPriorAbsentRecoveryRecord(entry);
+}
+function extractionAsideTimestamp(name) {
+    const timestampEnd = name.indexOf('-', IN_PROGRESS_ASIDE_PREFIX.length);
+    if (timestampEnd < 0)
+        return Number.NaN;
+    return Number(name.slice(IN_PROGRESS_ASIDE_PREFIX.length, timestampEnd));
+}
+async function recoverInterruptedComponentExtractions(componentsRootDirPath) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.ASIDE_STAGING_DIR);
+    let entries;
     try {
-        await (0, promises_1.mkdir)(application.dirPath, { recursive: true });
-        await (0, promises_2.pipeline)(tarball, (0, gunzip_maybe_1.default)(), (0, tar_fs_1.extract)(application.dirPath));
-        const extracted = await (0, promises_1.readdir)(application.dirPath, { withFileTypes: true });
-        if (extracted.length === 1 && extracted[0].isDirectory()) {
-            const topLevelDirPath = (0, node_path_1.join)(application.dirPath, extracted[0].name);
-            await (0, promises_1.mkdir)(asideStagingDir, { recursive: true });
-            const tempDirPath = await (0, promises_1.mkdtemp)((0, node_path_1.join)(asideStagingDir, '.normalize-'));
-            await (0, promises_1.cp)(topLevelDirPath, tempDirPath, { recursive: true });
-            await (0, promises_1.rm)(topLevelDirPath, { recursive: true, force: true });
-            await (0, promises_1.cp)(tempDirPath, application.dirPath, { recursive: true });
-            await (0, promises_1.rm)(tempDirPath, { recursive: true, force: true });
+        const stagingStat = await (0, promises_1.lstat)(stagingRoot);
+        if (!stagingStat.isDirectory() || stagingStat.isSymbolicLink()) {
+            throw new Error(`Component deploy staging path is not a directory: ${stagingRoot}`);
         }
+        entries = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
     }
     catch (error) {
+        if (error.code === 'ENOENT')
+            return new Map();
+        throw error;
+    }
+    const failedComponents = new Map();
+    await Promise.all(entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
         try {
-            await rollbackExtractedDirectory(application, asideStagingDir, asidePath);
+            await recoverInterruptedComponentExtraction(componentsRootDirPath, entry.name, false);
         }
-        catch (rollbackError) {
-            throw new AggregateError([error, rollbackError], `Failed to extract ${application.name} and restore its previous component directory`);
+        catch (error) {
+            const recoveryError = error instanceof Error ? error : new Error(String(error));
+            failedComponents.set(entry.name, recoveryError);
+            const deferred = recoveryError instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError;
+            harper_logger_ts_1.default[deferred ? 'warn' : 'error'](`${deferred ? 'Deferring' : 'Not loading'} ${entry.name} because its interrupted component deployment ` +
+                `${deferred ? 'is still being prepared' : 'could not be recovered'}:`, (0, harper_logger_ts_1.errorForLog)(recoveryError));
+        }
+    }));
+    return failedComponents;
+}
+async function recoverInterruptedComponentExtraction(componentsRootDirPath, componentName, waitForPreparation = true, waitTimeoutMs = COMPONENT_RECOVERY_WAIT_TIMEOUT_MS) {
+    const componentDirPath = (0, node_path_1.join)(componentsRootDirPath, componentName);
+    await (0, componentPreparationLock_ts_1.withComponentPreparationLock)(componentDirPath, async () => {
+        const asideStagingDir = extractionStagingDirectory(componentDirPath);
+        try {
+            await (0, promises_1.lstat)(asideStagingDir);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
         }
+        await ensureExtractionStagingDirectory(asideStagingDir);
+        await recoverOrCleanupStaleExtractionPaths({ name: componentName, dirPath: componentDirPath, logger: harper_logger_ts_1.default }, asideStagingDir);
+    }, {
+        timeoutMs: waitForPreparation ? waitTimeoutMs : COMPONENT_RECOVERY_TRY_TIMEOUT_MS,
+        purpose: COMPONENT_RECOVERY_LOCK_PURPOSE,
+        renewTimeoutWhileOwnerAlive: waitForPreparation,
+        onWait: (owner) => {
+            harper_logger_ts_1.default.info(`Waiting to settle component deployment state for ${componentName}` +
+                (owner ? ` held by process ${owner.pid}, thread ${owner.threadId}` : ''));
+        },
+        isOwnerAlive: (owner) => owner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(owner.threadId),
+    });
+}
+async function retireComponentExtractionStaging(componentDirPath, componentName = (0, node_path_1.basename)(componentDirPath), componentLogger = harper_logger_ts_1.default) {
+    const asideStagingDir = extractionStagingDirectory(componentDirPath);
+    let entries;
+    try {
+        await (0, promises_1.lstat)(asideStagingDir);
+        await ensureExtractionStagingDirectory(asideStagingDir);
+        entries = await (0, promises_1.readdir)(asideStagingDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
         throw error;
     }
-    // Clean up the original tarball
-    if (shouldDeleteTarball && tarballPath) {
-        await (0, promises_1.rm)(tarballPath, { force: true }).catch((error) => application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error));
+    const paths = new Set(entries.map((entry) => (0, node_path_1.join)(asideStagingDir, entry.name)));
+    for (const entry of entries) {
+        if (!isExtractionRecoveryRecord(entry) || !entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX))
+            continue;
+        const markerPath = retiredMarkerForAside((0, node_path_1.join)(asideStagingDir, entry.name));
+        try {
+            await (0, promises_1.writeFile)(markerPath, '', { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        paths.add(markerPath);
     }
-    // Remove this component's aside copies. The old worker may still hold files open
-    // in the just-renamed copy (the live writer that motivated the rename), so this is
-    // best-effort: removing the whole staging subdirectory also clears leftovers from
-    // earlier deploys whose workers have since exited, and a copy that survives because
-    // its worker is still live is swept by the next deploy. The failure is expected in
-    // the live-worker case, so it's logged at trace rather than as a warning.
-    let settled = false;
-    const transaction = {
-        async commit() {
-            if (settled)
-                return;
-            settled = true;
-            await cleanupExtractionStaging(application, asideStagingDir);
-        },
-        async rollback() {
-            if (settled)
-                return;
-            settled = true;
-            await rollbackExtractedDirectory(application, asideStagingDir, asidePath);
-        },
-    };
-    if (deferCommit)
-        return transaction;
-    await transaction.commit();
+    await cleanupExtractionPaths({ name: componentName, dirPath: componentDirPath, logger: componentLogger }, asideStagingDir, paths);
 }
-async function cleanupExtractionStaging(application, asideStagingDir) {
+async function dropComponentDirectory(componentDirPath, componentName = (0, node_path_1.basename)(componentDirPath), componentLogger = harper_logger_ts_1.default) {
+    await retireComponentExtractionStaging(componentDirPath, componentName, componentLogger);
+    const asideStagingDir = extractionStagingDirectory(componentDirPath);
+    await ensureExtractionStagingDirectory(asideStagingDir);
+    const droppedPath = (0, node_path_1.join)(asideStagingDir, `.dropped-${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
+    try {
+        await (0, promises_1.rename)(componentDirPath, droppedPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await cleanupExtractionPaths({ name: componentName, dirPath: componentDirPath, logger: componentLogger }, asideStagingDir, new Set([droppedPath]));
+    // A dropped component has no next deploy to bound its dormant builds.
     try {
-        await (0, promises_1.rm)(asideStagingDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        await pruneDormantBuilds(componentName, await dormantBuildsOf((0, node_path_1.dirname)(componentDirPath), componentName), 0);
     }
     catch (error) {
-        harper_logger_ts_1.default.trace?.(`Cleanup of previous ${application.name} component directory deferred: ${error.message}`);
+        componentLogger.warn(`Dropped ${componentName} but could not reclaim its dormant staged builds:`, (0, harper_logger_ts_1.errorForLog)(error));
     }
 }
-async function rollbackExtractedDirectory(application, asideStagingDir, asidePath) {
-    await (0, promises_1.mkdir)(asideStagingDir, { recursive: true });
-    const retryableRenameCodes = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES', 'EBUSY']);
-    const displaceCurrentDirectory = async () => {
+async function cleanupExtractionPaths(application, asideStagingDir, paths) {
+    const retiredMarkers = [];
+    for (const path of paths) {
+        if ((0, node_path_1.basename)(path).startsWith(RETIRED_ASIDE_PREFIX)) {
+            retiredMarkers.push(path);
+            continue;
+        }
+        try {
+            await (0, promises_1.rm)(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        }
+        catch (error) {
+            application.logger.trace?.(`Cleanup of previous ${application.name} component directory deferred: ${errorMessage(error)}`);
+        }
+    }
+    for (const markerPath of retiredMarkers) {
+        const asidePath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${(0, node_path_1.basename)(markerPath).slice(RETIRED_ASIDE_PREFIX.length)}`);
+        try {
+            await (0, promises_1.access)(asidePath, promises_1.constants.F_OK);
+            continue;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                continue;
+        }
+        await (0, promises_1.rm)(markerPath, { force: true }).catch((error) => application.logger.trace?.(`Cleanup of previous ${application.name} component directory deferred: ${errorMessage(error)}`));
+    }
+    await (0, promises_1.rmdir)(asideStagingDir).catch((error) => {
+        if (!['ENOENT', 'ENOTEMPTY'].includes(error.code ?? '')) {
+            application.logger.trace?.(`Cleanup of ${application.name} deploy staging directory deferred: ${errorMessage(error)}`);
+        }
+    });
+}
+async function rollbackExtractedDirectory(application, asideStagingDir, asidePath, transactionPaths, retainReplacement) {
+    await ensureExtractionStagingDirectory(asideStagingDir);
+    const retryableRenameCodes = new Set(['EEXIST', 'ENOTEMPTY', 'ENOTDIR', 'EISDIR', 'EPERM', 'EACCES', 'EBUSY']);
+    const displaceCurrentDirectorySync = () => {
         const displacedPath = (0, node_path_1.join)(asideStagingDir, `.failed-${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
+        try {
+            (0, node_fs_1.renameSync)(application.dirPath, displacedPath);
+            transactionPaths.add(displacedPath);
+            return displacedPath;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    };
+    const displaceCurrentDirectory = async () => {
+        const retryDeadline = Date.now() + 5000;
         let lastError;
-        for (let attempt = 0; attempt < 100; attempt++) {
+        do {
+            const displacedPath = (0, node_path_1.join)(asideStagingDir, `.failed-${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
             try {
                 await (0, promises_1.rename)(application.dirPath, displacedPath);
-                return;
+                transactionPaths.add(displacedPath);
+                return displacedPath;
             }
             catch (error) {
                 const code = error.code;
                 if (code === 'ENOENT')
-                    return;
+                    return undefined;
                 if (!retryableRenameCodes.has(code ?? ''))
                     throw error;
                 lastError = error;
                 await (0, promises_3.setTimeout)(10);
             }
-        }
+        } while (Date.now() < retryDeadline);
         throw lastError;
     };
-    await displaceCurrentDirectory();
     if (asidePath) {
-        let restored = false;
+        const asideIsSymbolicLink = (await (0, promises_1.lstat)(asidePath)).isSymbolicLink();
         let restoreError;
-        for (let attempt = 0; attempt < 100; attempt++) {
+        let restoreRetryDeadline;
+        let fallbackDisplacedPath;
+        let placeholderIdentity = await identifyRollbackPlaceholder(application.dirPath);
+        const failRestore = async (error) => {
+            try {
+                await makeRollbackPlaceholderMovable(application.dirPath, placeholderIdentity);
+                if (retainReplacement && fallbackDisplacedPath) {
+                    const fallbackRetryDeadline = Date.now() + 5000;
+                    let fallbackRestoreError;
+                    do {
+                        let writerDisplacedPath;
+                        try {
+                            writerDisplacedPath = displaceCurrentDirectorySync();
+                            placeholderIdentity = undefined;
+                            (0, node_fs_1.renameSync)(fallbackDisplacedPath, application.dirPath);
+                            fallbackRestoreError = undefined;
+                        }
+                        catch (restoreFallbackError) {
+                            fallbackRestoreError = restoreFallbackError;
+                        }
+                        if (writerDisplacedPath) {
+                            await (0, promises_1.rm)(writerDisplacedPath, {
+                                recursive: true,
+                                force: true,
+                                maxRetries: 3,
+                                retryDelay: 100,
+                            });
+                            transactionPaths.delete(writerDisplacedPath);
+                        }
+                        if (fallbackRestoreError &&
+                            !retryableRenameCodes.has(fallbackRestoreError.code ?? '')) {
+                            throw fallbackRestoreError;
+                        }
+                        if (fallbackRestoreError) {
+                            await (0, promises_3.setTimeout)(10);
+                        }
+                        else {
+                            break;
+                        }
+                    } while (Date.now() < fallbackRetryDeadline);
+                    if (fallbackRestoreError)
+                        throw fallbackRestoreError;
+                    transactionPaths.delete(fallbackDisplacedPath);
+                    transactionPaths.add(await retireExtractionAside(asidePath));
+                }
+                if (placeholderIdentity) {
+                    try {
+                        const current = await (0, promises_1.lstat)(application.dirPath, { bigint: true });
+                        if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+                            await (0, promises_1.rm)(application.dirPath, {
+                                recursive: true,
+                                force: true,
+                                maxRetries: 3,
+                                retryDelay: 100,
+                            });
+                            placeholderIdentity = undefined;
+                        }
+                    }
+                    catch (placeholderError) {
+                        if (placeholderError.code !== 'ENOENT')
+                            throw placeholderError;
+                    }
+                }
+                const disposablePaths = new Set(transactionPaths);
+                disposablePaths.delete(asidePath);
+                await cleanupExtractionPaths(application, asideStagingDir, disposablePaths);
+            }
+            catch (fallbackError) {
+                throw new AggregateError([error, fallbackError], `Failed to restore either the previous or replacement ${application.name} component directory`);
+            }
+            throw new Error(`Failed to restore ${asidePath} to the live component directory ${application.dirPath}: ${errorMessage(error)}`, { cause: error });
+        };
+        do {
             try {
-                await (0, promises_1.rename)(asidePath, application.dirPath);
-                restored = true;
-                break;
+                if (placeholderIdentity) {
+                    const current = (0, node_fs_1.lstatSync)(application.dirPath, { bigint: true });
+                    if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+                        (0, node_fs_1.chmodSync)(application.dirPath, 0o700);
+                        (0, node_fs_1.renameSync)(asidePath, application.dirPath);
+                    }
+                    else {
+                        placeholderIdentity = undefined;
+                        await (0, promises_1.rename)(asidePath, application.dirPath);
+                    }
+                }
+                else {
+                    await (0, promises_1.rename)(asidePath, application.dirPath);
+                }
+                transactionPaths.delete(asidePath);
+                await cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+                return;
             }
             catch (error) {
                 restoreError = error;
-                if (!retryableRenameCodes.has(error.code ?? ''))
-                    break;
-                await displaceCurrentDirectory();
+                if (!retryableRenameCodes.has(error.code ?? '')) {
+                    return failRestore(error);
+                }
+                let displacedPath;
+                const displacedPlaceholderIdentity = placeholderIdentity;
+                try {
+                    await makeRollbackPlaceholderMovable(application.dirPath, placeholderIdentity);
+                    displacedPath = await displaceCurrentDirectory();
+                    placeholderIdentity = undefined;
+                    if (displacedPath && displacedPlaceholderIdentity) {
+                        try {
+                            const displaced = await (0, promises_1.lstat)(displacedPath, { bigint: true });
+                            if (displaced.dev === displacedPlaceholderIdentity.dev &&
+                                displaced.ino === displacedPlaceholderIdentity.ino) {
+                                const displacedPlaceholderPath = displacedPath;
+                                displacedPath = undefined;
+                                await (0, promises_1.rm)(displacedPlaceholderPath, {
+                                    recursive: true,
+                                    force: true,
+                                    maxRetries: 3,
+                                    retryDelay: 100,
+                                });
+                                transactionPaths.delete(displacedPlaceholderPath);
+                            }
+                        }
+                        catch (placeholderCleanupError) {
+                            application.logger.trace?.(`Cleanup of the ${application.name} rollback placeholder deferred: ${errorMessage(placeholderCleanupError)}`);
+                        }
+                    }
+                }
+                catch (displaceError) {
+                    return failRestore(new AggregateError([error, displaceError], `Failed to clear the live ${application.name} component directory for rollback`));
+                }
+                if (displacedPath) {
+                    if (fallbackDisplacedPath) {
+                        try {
+                            await (0, promises_1.rm)(displacedPath, {
+                                recursive: true,
+                                force: true,
+                                maxRetries: 3,
+                                retryDelay: 100,
+                            });
+                            transactionPaths.delete(displacedPath);
+                        }
+                        catch (cleanupError) {
+                            return failRestore(new AggregateError([error, cleanupError], `Failed to discard a displaced ${application.name} writer directory during rollback`));
+                        }
+                    }
+                    else {
+                        fallbackDisplacedPath = displacedPath;
+                    }
+                }
+                restoreRetryDeadline ??= Date.now() + 5000;
+                if (process.platform !== 'win32' && process.getuid?.() !== 0) {
+                    const stagedPlaceholderPath = (0, node_path_1.join)(asideStagingDir, `.rollback-placeholder-${process.pid}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}`);
+                    try {
+                        if (asideIsSymbolicLink) {
+                            await (0, promises_1.writeFile)(stagedPlaceholderPath, '', { flag: 'wx', mode: 0o000 });
+                        }
+                        else {
+                            await (0, promises_1.mkdir)(stagedPlaceholderPath, { mode: 0o300 });
+                        }
+                        transactionPaths.add(stagedPlaceholderPath);
+                        let placeholderPlacementError;
+                        do {
+                            let writerDisplacedPath;
+                            try {
+                                writerDisplacedPath = displaceCurrentDirectorySync();
+                                (0, node_fs_1.renameSync)(stagedPlaceholderPath, application.dirPath);
+                                if (!asideIsSymbolicLink) {
+                                    try {
+                                        (0, node_fs_1.chmodSync)(application.dirPath, 0o100);
+                                    }
+                                    catch (chmodError) {
+                                        try {
+                                            (0, node_fs_1.renameSync)(application.dirPath, stagedPlaceholderPath);
+                                        }
+                                        catch (compensationError) {
+                                            throw new AggregateError([chmodError, compensationError], `Failed to restrict and then restore the ${application.name} rollback placeholder`);
+                                        }
+                                        throw chmodError;
+                                    }
+                                }
+                                transactionPaths.delete(stagedPlaceholderPath);
+                                placeholderPlacementError = undefined;
+                            }
+                            catch (placeholderError) {
+                                placeholderPlacementError = placeholderError;
+                            }
+                            if (writerDisplacedPath) {
+                                await (0, promises_1.rm)(writerDisplacedPath, {
+                                    recursive: true,
+                                    force: true,
+                                    maxRetries: 3,
+                                    retryDelay: 100,
+                                });
+                                transactionPaths.delete(writerDisplacedPath);
+                            }
+                            if (placeholderPlacementError &&
+                                !retryableRenameCodes.has(placeholderPlacementError.code ?? '')) {
+                                throw placeholderPlacementError;
+                            }
+                            if (!placeholderPlacementError)
+                                break;
+                            await (0, promises_3.setTimeout)(10);
+                        } while (Date.now() < restoreRetryDeadline);
+                        if (transactionPaths.has(stagedPlaceholderPath)) {
+                            throw new Error(`Failed to place the ${application.name} rollback placeholder before the deadline: ${errorMessage(placeholderPlacementError)}`, { cause: placeholderPlacementError });
+                        }
+                        const placeholder = await (0, promises_1.lstat)(application.dirPath, { bigint: true });
+                        placeholderIdentity = { dev: placeholder.dev, ino: placeholder.ino };
+                    }
+                    catch (placeholderError) {
+                        return failRestore(new AggregateError([error, placeholderError], `Failed to block a live ${application.name} writer during rollback`));
+                    }
+                }
                 await (0, promises_3.setTimeout)(10);
             }
+        } while (restoreRetryDeadline !== undefined && Date.now() < restoreRetryDeadline);
+        return failRestore(restoreError);
+    }
+    try {
+        await displaceCurrentDirectory();
+    }
+    catch (displaceError) {
+        try {
+            await (0, promises_1.rm)(application.dirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            await cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+            return;
+        }
+        catch (removeError) {
+            throw new AggregateError([displaceError, removeError], `Failed to remove the partial ${application.name} component directory after extraction failed`);
         }
-        if (!restored)
-            throw restoreError;
     }
-    await cleanupExtractionStaging(application, asideStagingDir);
+    await cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+}
+/**
+ * The one definition of how Harper invokes a package manager to install dependencies; every npm
+ * entry point composes its arguments here rather than assembling its own.
+ */
+function packageManagerInstallArguments(packageManagerName, allowInstallScripts, force = false) {
+    const args = ['install'];
+    if (force)
+        args.push('--force');
+    if (packageManagerName === 'npm')
+        args.push('--omit=dev', '--no-audit', '--no-fund');
+    if (!allowInstallScripts)
+        args.push('--ignore-scripts');
+    return args;
 }
 /**
- * Install an application to its relative `application.dirPath` using either a
- * configured `application.install` command, a derived package manager from the
- * application's `package.json#devEngines`, or falling back to the default
- * package manager, `npm`.
+ * Install a component's dependencies into `buildDirPath` — the live path, or a candidate under
+ * `.deploy-staging`. Explicit rather than repointing `application.dirPath`, which is read after preparation
+ * too and would name a vanished directory if any failure path skipped the restore.
  *
- * Will return early if `node_modules` already exists within the `application.dirPath`
+ * Uses a configured `application.install` command, a package manager derived from the application's
+ * `package.json#devEngines`, or the default, `npm`. Returns early when `node_modules` already exists or
+ * when the manifest has no automatic install work. An explicitly selected non-npm manager is always
+ * allowed to inspect its own workspace configuration, even when the root manifest has no production
+ * dependencies.
  *
- * This method may be called from any Harper thread as part of a serialized preparation.
+ * May be called from any Harper thread as part of a serialized preparation.
  */
-async function installApplication(application) {
+async function installApplication(application, buildDirPath = application.dirPath) {
     let packageJSON;
     try {
-        packageJSON = JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(application.dirPath, 'package.json'), 'utf8'));
+        packageJSON = JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(buildDirPath, 'package.json'), 'utf8'));
     }
     catch (err) {
         if (err.code !== 'ENOENT')
@@ -776,7 +3430,7 @@ async function installApplication(application) {
     }
     try {
         // Does node_modules exist?
-        await (0, promises_1.access)((0, node_path_1.join)(application.dirPath, 'node_modules'), promises_1.constants.F_OK);
+        await (0, promises_1.access)((0, node_path_1.join)(buildDirPath, 'node_modules'), promises_1.constants.F_OK);
         application.logger.info(`Application ${application.name} already has node_modules; skipping install and treating the runtime as opaque for redeploy comparison`);
         application.installationIsOpaque = true;
         return;
@@ -786,13 +3440,17 @@ async function installApplication(application) {
             throw err;
         // If node_modules doesn't exist, we need to install dependencies
     }
+    const allowInstallScripts = !!application.install?.allowInstallScripts;
     // If custom install command is specified, run it
     if (application.install?.command) {
+        if (application.install.allowInstallScripts === undefined) {
+            application.logger.warn(`Application ${application.name} uses install_command without install_allow_scripts; package lifecycle scripts are disabled by default for npm and tools that honor npm_config_ignore_scripts, including npm run pre/post hooks. Set install_allow_scripts (or install.allowInstallScripts in root config) to true to opt in`);
+        }
         const [command, ...args] = application.install.command.split(' ');
         const customOnLine = application.onInstallLine
             ? (stream, line) => application.onInstallLine(command, stream, line)
             : undefined;
-        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, command, args, application.dirPath, application.install?.timeout, customOnLine, application.npmUserconfigPath);
+        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, command, args, buildDirPath, application.install?.timeout, customOnLine, application.npmUserconfigPath, undefined, !allowInstallScripts);
         // if it succeeds, return
         if (code === 0) {
             application.installationIsOpaque = true;
@@ -807,8 +3465,16 @@ async function installApplication(application) {
         // and throw a descriptive error
         throw new Error(`Failed to install dependencies for ${application.name} using custom install command: ${application.install.command}. Exit code: ${code}`);
     }
-    // Next, try package.json devEngines field
     const { packageManager } = packageJSON.devEngines || {};
+    if (dependencyFieldHasWork(packageJSON, 'devDependencies')) {
+        application.logger.warn(`Application ${application.name} declares devDependencies; automatic npm installation omits them, while explicitly selected non-npm package managers retain their own install defaults. Use install_command when deployment requires custom behavior`);
+    }
+    if (!packageHasAutomaticInstallWork(packageJSON) &&
+        !(allowInstallScripts && packageHasAllowedInstallLifecycleWork(packageJSON))) {
+        application.logger.info(`Application ${application.name} has no production package work; skipping install`);
+        return;
+    }
+    // Next, try package.json devEngines field
     // Custom package manager specified
     if (packageManager) {
         // On any given system we want to leverage the `name` to match the package manager executable
@@ -833,8 +3499,7 @@ async function installApplication(application) {
         const pmOnLine = application.onInstallLine
             ? (stream, line) => application.onInstallLine(packageManager.name, stream, line)
             : undefined;
-        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, (application.packageManagerPrefix ? application.packageManagerPrefix + ' ' : '') + packageManager.name, application.install?.allowInstallScripts ? ['install'] : ['install', '--ignore-scripts'], // All of `npm`, `yarn`, and `pnpm` support the `install` command. If we need to configure options here we may have to use some other defaults though
-        application.dirPath, application.install?.timeout, pmOnLine, application.npmUserconfigPath);
+        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, (application.packageManagerPrefix ? application.packageManagerPrefix + ' ' : '') + packageManager.name, packageManagerInstallArguments(packageManager.name, allowInstallScripts), buildDirPath, application.install?.timeout, pmOnLine, application.npmUserconfigPath);
         // if it succeeds, return
         if (code === 0) {
             if (application.install?.allowInstallScripts)
@@ -866,13 +3531,18 @@ async function installApplication(application) {
         // But then fall through to installing with npm
     }
     // Finally, default to running `npm install`
-    const npmInstallArgs = application.install?.allowInstallScripts
-        ? ['install', '--force']
-        : ['install', '--force', '--ignore-scripts'];
+    const npmInstallArgs = packageManagerInstallArguments('npm', allowInstallScripts, true);
+    // A candidate build is installed at a staging path and then RENAMED to the live path, so nothing npm
+    // writes may depend on the build location. npm links a `file:` dependency relatively on POSIX, which
+    // survives the move — but as an absolute junction on Windows, which does not, so the dependency stops
+    // resolving once the tree moves. `--install-links` copies instead of linking, leaving no path to break.
+    // win32 and candidate builds only, since it does change how `file:` dependencies behave.
+    if (process.platform === 'win32' && buildDirPath !== application.dirPath)
+        npmInstallArgs.push('--install-links');
     const npmOnLine = application.onInstallLine
         ? (stream, line) => application.onInstallLine('npm', stream, line)
         : undefined;
-    const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, (application.packageManagerPrefix ? application.packageManagerPrefix + ' ' : '') + 'npm', npmInstallArgs, application.dirPath, application.install?.timeout, npmOnLine, application.npmUserconfigPath);
+    const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, (application.packageManagerPrefix ? application.packageManagerPrefix + ' ' : '') + 'npm', npmInstallArgs, buildDirPath, application.install?.timeout, npmOnLine, application.npmUserconfigPath);
     // if it succeeds, return
     if (code === 0) {
         if (application.install?.allowInstallScripts)
@@ -893,6 +3563,7 @@ class Application {
     name;
     payload;
     packageIdentifier;
+    packLocalDirectory;
     install;
     onInstallLine;
     dirPath;
@@ -917,6 +3588,7 @@ class Application {
     constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }) {
         this.name = name;
         this.payload = payload;
+        this.packLocalDirectory = shouldPackLocalDirectory(packageIdentifier);
         this.packageIdentifier = packageIdentifier && derivePackageIdentifier(packageIdentifier);
         this.install = install;
         this.onInstallLine = onInstallLine;
@@ -1033,7 +3705,12 @@ exports.Application = Application;
  * during the installation process in order to actually resolve what the user specifies for a
  * component matching some of npm's package resolution rules.
  */
+function isBareAbsolutePackagePath(packageIdentifier) {
+    return (0, node_path_1.isAbsolute)(packageIdentifier) || node_path_1.win32.isAbsolute(packageIdentifier);
+}
 function derivePackageIdentifier(packageIdentifier) {
+    if (isBareAbsolutePackagePath(packageIdentifier))
+        return `file:${packageIdentifier}`;
     if (packageIdentifier.includes(':')) {
         return packageIdentifier;
     }
@@ -1045,59 +3722,108 @@ function derivePackageIdentifier(packageIdentifier) {
     }
     return `github:${packageIdentifier}`;
 }
-/**
- * Extract and install the specified application.
- *
- * This method may be called from any Harper thread. Same-component calls are serialized across
- * threads by the preparation lock below.
- *
- * Bracketed with `deploy:start`/`deploy:end` lifecycle broadcasts so every
- * Harper thread's file watchers can suppress restart-on-change events while
- * the component directory is being rewritten — see harper#488 and
- * `components/deployLifecycle.ts`. The broadcast is best-effort: if it fails
- * (e.g. workers haven't started yet during initial install), the deploy still
- * proceeds.
- *
- * @param application The application to prepare.
- * @returns A promise that resolves when all preparation steps complete.
- */
-async function prepareApplication(application) {
-    const deploymentId = await (0, deployLifecycle_ts_1.broadcastDeployStart)(application.name);
+function shouldPackLocalDirectory(packageIdentifier, platform = process.platform) {
+    return platform === 'win32' && !!packageIdentifier && isBareAbsolutePackagePath(packageIdentifier);
+}
+async function prepareApplication(application, options = {}) {
+    const lifecycleToken = await (0, deployLifecycle_ts_1.broadcastDeployStart)(application.name);
+    const mode = options.mode ?? 'deploy';
+    const artifactId = options.artifactId ?? lifecycleToken;
     try {
         const commandTimeoutMs = application.install?.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
         await (0, componentPreparationLock_ts_1.withComponentPreparationLock)(application.dirPath, async () => {
+            await options.beforePrepare?.();
+            const asideStagingDir = extractionStagingDirectory(application.dirPath);
+            let recoveryPending = true;
+            try {
+                await (0, promises_1.lstat)(asideStagingDir);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                recoveryPending = false;
+            }
+            // BEFORE the legacy pass. That pass refuses to restore while a journal survives, so skipping
+            // this would not lose data — it would just stall the deploy behind its own unsettled state.
+            //
+            // The id this request names is pinned against the retention this runs. An activation would
+            // otherwise have its own artifact deleted by its own preamble; and a redelivered stage would
+            // have the artifact evicted out from under the exclusive claim below, which would then rebuild
+            // different bytes under an id that already named some.
+            await settleStagingForComponent((0, node_path_1.dirname)(application.dirPath), application.name, artifactId);
+            if (recoveryPending) {
+                await ensureExtractionStagingDirectory(asideStagingDir);
+                await recoverOrCleanupStaleExtractionPaths(application, asideStagingDir);
+            }
             const previousPackageMetadata = await readInstalledPackageMetadata(application.dirPath);
-            let extraction;
+            // Determined before the swap, because both trees exist then: the runtime comparison below
+            // wants the live version and the candidate side by side.
+            application.isNewComponent = !(await (0, promises_1.lstat)(application.dirPath).then(() => true, (error) => {
+                if (error.code === 'ENOENT')
+                    return false;
+                throw error;
+            }));
+            if (mode === 'activate') {
+                await activateStagedArtifact(application, artifactId, previousPackageMetadata, options);
+                return;
+            }
             try {
-                // Materialize the per-deploy `.npmrc` before extraction so both `npm pack` (extract) and
-                // `npm install` authenticate against the private registry; always remove it afterward.
+                // Materialize the per-deploy `.npmrc` before the build so both `npm pack` and `npm install`
+                // authenticate against the private registry; always remove it afterward.
                 await application.writeTransientNpmrc();
+                let candidateDirPath;
                 try {
-                    // The git credential socket only has to be up for extraction — that is where npm resolves and
-                    // clones a git-reference package. Closing it before installApplication means the credential is
-                    // already gone by the time the component's dependency tree (and any install script it is
-                    // allowed to run) executes.
+                    // Backstop only: the builder closes the session as soon as extraction is done, so the
+                    // credential is already gone before any install script runs. This finally covers the paths
+                    // that fail before it gets there.
                     await application.startGitCredentialSession();
-                    extraction = await extractApplication(application, true);
+                    candidateDirPath = await buildCandidateApplication(application, artifactId, {
+                        rejectLinkSource: mode === 'stage',
+                    });
                 }
                 finally {
                     await application.cleanupGitCredentialSession();
                 }
-                await installApplication(application);
-                if (!application.isNewComponent) {
-                    const currentPackageMetadata = await readInstalledPackageMetadata(application.dirPath);
-                    application.packageMetadataChanged = installedRuntimeChanged(previousPackageMetadata, currentPackageMetadata, application.installationIsOpaque);
-                }
-                await extraction?.commit();
-            }
-            catch (error) {
                 try {
-                    await extraction?.rollback();
+                    // Validated while the previous version is still the one serving, so a candidate that
+                    // installs cleanly but throws at load is rejected without ever having been live.
+                    await options.validateCandidate?.(candidateDirPath);
+                    if (!application.isNewComponent) {
+                        application.packageMetadataChanged = installedRuntimeChanged(previousPackageMetadata, await readInstalledPackageMetadata(candidateDirPath), application.installationIsOpaque);
+                    }
+                    if (mode === 'stage') {
+                        await assertOwnedArtifactTree(candidateDirPath, application.name);
+                        // The descriptor goes first so `.complete` vouches for it: after this pair the artifact
+                        // is dormant, and a delayed activation reads its build's decisions from here because
+                        // nothing on disk carries them otherwise.
+                        const declared = options.describeArtifact?.() ?? { rootConfig: null, isolated: false };
+                        await writeArtifactDescriptor(application.dirPath, artifactId, {
+                            v: ARTIFACT_DESCRIPTOR_VERSION,
+                            component: application.name,
+                            rootConfig: declared.rootConfig,
+                            installationIsOpaque: application.installationIsOpaque,
+                            isolated: declared.isolated,
+                        });
+                        await markCandidateComplete(application.dirPath, artifactId, application.name);
+                        await syncArtifactAncestors(candidateDeploymentDirPath(application.dirPath, artifactId));
+                        return;
+                    }
+                    await markCandidateComplete(application.dirPath, artifactId, application.name);
+                    await activateCandidateApplication(application, artifactId);
                 }
-                catch (rollbackError) {
-                    throw new AggregateError([error, rollbackError], `Failed to prepare ${application.name} and restore its previous component directory`);
+                catch (error) {
+                    // The builder's own cleanup only covers a failed BUILD. A rejected validation, or an
+                    // activation that was cleanly compensated, would otherwise leave a whole installed
+                    // dependency tree under this deployment id — repeated rejections fill the volume.
+                    //
+                    // NOT when compensation itself failed. There the previous version is not back and the live
+                    // path may be absent, and the candidate plus its `.complete` marker and journal are exactly
+                    // what recovery needs to roll the validated deploy forward at the next start. Discarding
+                    // them there trades a bounded disk cost for a component with no version at all.
+                    if (!compensationIncomplete(error))
+                        await discardCandidate(application, artifactId);
+                    throw error;
                 }
-                throw error;
             }
             finally {
                 await application.cleanupTransientNpmrc();
@@ -1116,8 +3842,70 @@ async function prepareApplication(application) {
         });
     }
     finally {
-        (0, deployLifecycle_ts_1.broadcastDeployEnd)(application.name, deploymentId);
+        (0, deployLifecycle_ts_1.broadcastDeployEnd)(application.name, lifecycleToken);
+    }
+}
+/**
+ * Swap an already-certified artifact into the live path. Called with the component's preparation lock held
+ * and after the same recovery preamble every build runs, so the state read here is settled.
+ *
+ * Nothing is resolved, fetched or installed: the bytes were certified when they were staged, which is the
+ * whole point of addressing one by id. Verification is therefore the only gate, and it is strict — this is
+ * activation input for a build this process did not make and may not have made on this node.
+ *
+ * A rejection here must NOT discard: the artifact belongs to whoever staged it, a wrong-component request
+ * must not delete another component's build, and a retry needs what a failed attempt left behind.
+ */
+async function activateStagedArtifact(application, artifactId, previousPackageMetadata, options) {
+    const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, artifactId);
+    const candidateDirPath = candidateApplicationPath(application.dirPath, artifactId);
+    // 404 means only one thing — no artifact answers to this id here — so a caller can tell "never existed or
+    // already used" from "present, but not something this can activate", which is every other refusal below
+    // and a 409 like the rest of that family.
+    const refuse = (why, statusCode) => new hdbError_ts_1.ClientError(`Cannot deploy ${application.name} from deployment ${artifactId}: ${why}`, statusCode);
+    const missing = (why) => refuse(why, 404);
+    const unusable = (why) => refuse(why, 409);
+    const owner = await candidateComponentName(deploymentDirPath);
+    if (owner === undefined)
+        throw missing('there is no staged build with that id on this node');
+    if (owner !== application.name)
+        throw unusable(`that staged build belongs to '${owner}'`);
+    if (!(await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER)))) {
+        throw unusable('its build never completed');
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER))) {
+        throw unusable('recovery could not settle it, so it is not safe to activate');
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL))) {
+        throw unusable('an activation of it is unsettled');
+    }
+    const candidateStat = await presentOrAbsent(candidateDirPath);
+    if (!candidateStat || !candidateStat.isDirectory()) {
+        // Unlike an immediate deploy, a symlink is refused: a `file:` directory is linked rather than
+        // copied, so what it points at now is not what was certified. Staging rejects the source for the
+        // same reason; this is the other end of the same rule, for an artifact staged by an older build.
+        throw unusable('its build tree is missing or is a link rather than a copy');
     }
+    const descriptor = await readArtifactDescriptor(deploymentDirPath, application.name);
+    if (!descriptor)
+        throw unusable('it does not record what its build decided');
+    await options.admitIsolation?.(descriptor);
+    // `.complete` is a durability marker over the bytes, not a seal on them, and every check that made this
+    // artifact safe ran at stage time. The link rule especially cannot be skipped:
+    // `repairRelocatedDependencyLinks` runs past the commit point and can only warn, so a link planted while
+    // the artifact sat dormant would otherwise go live with the operation reporting success.
+    await assertOwnedArtifactTree(candidateDirPath, application.name, 'activate');
+    // Also the activation's `prepare` phase end: the deploy path emits `prepare`/`start` for every mode but
+    // only ever emitted its `done` from here.
+    await options.validateCandidate?.(candidateDirPath);
+    if (!application.isNewComponent) {
+        application.packageMetadataChanged = installedRuntimeChanged(previousPackageMetadata, await readInstalledPackageMetadata(candidateDirPath), descriptor.installationIsOpaque);
+    }
+    await activateCandidateApplication(application, artifactId, {
+        // Returns its own undo, which the swap runs inside its pre-commit boundary — see there for why it
+        // cannot be run out here.
+        afterJournal: descriptor.rootConfig ? () => options.publishRootConfig(descriptor.rootConfig) : undefined,
+    });
 }
 /**
  * Install all applications specified in the root config.
@@ -1403,19 +4191,6 @@ function buildNpmrcContent(registryCredentials) {
     }
     return lines.join('\n') + '\n';
 }
-/**
- * Execute a command (using `spawn`) with stdin ignored.
- *
- * Stdout is logged chunk-by-chunk. Stderr is buffered and then logged line-by-line.
- *
- * Rejects with an error if the command fails or times out.
- *
- * @param command The command to run.
- * @param args The arguments to pass to the command.
- * @param cwd The working directory for the command.
- * @param timeoutMs The timeout for the command in milliseconds. Defaults to 5 minutes.
- * @returns A promise that resolves when the command completes.
- */
 /**
  * Line-buffered split that emits complete `\n`-terminated lines as they
  * arrive, holding any partial trailing fragment until the next chunk or `flush()`.
@@ -1454,20 +4229,31 @@ function createLineSplitter(onLine) {
     };
 }
 /**
- * Run a command with the deploy's SSH key material materialized only for the duration of the
- * spawn. The keys are decrypted to a transient 0700 dir (see `materializeGitSSH`) and removed as
- * soon as the process settles — on success, failure, and timeout alike.
+ * Execute a command (using `spawn`) with stdin ignored, with the deploy's SSH key material
+ * materialized only for the duration of the spawn. The keys are decrypted to a transient 0700 dir
+ * (see `materializeGitSSH`) and removed as soon as the process settles — on success, failure, and
+ * timeout alike.
+ *
+ * Stdout is logged chunk-by-chunk. Stderr is buffered and then logged line-by-line.
+ *
+ * Rejects with an error if the command fails or times out.
+ *
+ * @param command The command to run.
+ * @param args The arguments to pass to the command.
+ * @param cwd The working directory for the command.
+ * @param timeoutMs The timeout for the command in milliseconds. Defaults to DEFAULT_COMMAND_TIMEOUT_MS.
+ * @returns A promise that resolves when the command completes.
  */
-async function nonInteractiveSpawn(applicationName, command, args, cwd, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS, onLine, npmUserconfigPath, gitCredentialEnv) {
+async function nonInteractiveSpawn(applicationName, command, args, cwd, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS, onLine, npmUserconfigPath, gitCredentialEnv, ignoreNpmScripts = false) {
     const gitSSH = await materializeGitSSH();
     try {
-        return await spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSH?.command, gitCredentialEnv);
+        return await spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSH?.command, gitCredentialEnv, ignoreNpmScripts);
     }
     finally {
         await gitSSH?.cleanup();
     }
 }
-function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSHCommand, gitCredentialEnv) {
+function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSHCommand, gitCredentialEnv, ignoreNpmScripts) {
     return new Promise((resolve, reject) => {
         harper_logger_ts_1.default
             .loggerWithTag(`${applicationName}:spawn:${command}`)
@@ -1500,9 +4286,17 @@ function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, np
             }
             env.npm_config_userconfig = npmUserconfigPath;
         }
+        if (ignoreNpmScripts) {
+            for (const key of Object.keys(env)) {
+                if (key.toLowerCase() === 'npm_config_ignore_scripts')
+                    delete env[key];
+            }
+            env.npm_config_ignore_scripts = 'true';
+        }
         if (process.platform === 'win32' && command === 'npm') {
             command = 'npm.cmd';
         }
+        const spawnLogger = harper_logger_ts_1.default.loggerWithTag(`${applicationName}:spawn:${command}`);
         const childProcess = (0, node_child_process_1.spawn)(command, args, {
             shell: true,
             cwd,
@@ -1591,7 +4385,19 @@ function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, np
                 reject(error);
             }
         });
-        childProcess.on('close', async (code) => {
+        childProcess.on('exit', (code, signal) => {
+            spawnLogger.debug?.(`Direct child exited with code ${code}, signal ${signal}; awaiting stdio close`);
+        });
+        childProcess.on('close', async (code, signal) => {
+            if (didTimeout) {
+                spawnLogger.debug?.(`Child stdio closed with code ${code}, signal ${signal}; timeout path owns process-tree confirmation`);
+            }
+            else if (trackedProcessId) {
+                spawnLogger.debug?.(`Child stdio closed with code ${code}, signal ${signal}; confirming process-tree termination`);
+            }
+            else {
+                spawnLogger.debug?.(`Child stdio closed with code ${code}, signal ${signal}; no process tree was tracked`);
+            }
             resolveClose();
             clearTimeout(timeout);
             // A successful direct-child exit does not prove the process group is empty: a custom
@@ -1613,6 +4419,7 @@ function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, np
                     }
                     return;
                 }
+                spawnLogger.debug?.(`Process tree termination confirmed after command close with code ${code}`);
                 untrackProcessGroup();
             }
             // When didTimeout is true, the timeout path's own terminateProcessTree(...).then(...) owns
@@ -1624,7 +4431,6 @@ function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, np
             if (stderr) {
                 printStd(applicationName, command, stderr, 'stderr');
             }
-            harper_logger_ts_1.default.loggerWithTag(`${applicationName}:spawn:${command}`).debug?.(`Process exited with code ${code}`);
             if (didTimeout || didSettle)
                 return;
             didSettle = true;
@@ -1647,13 +4453,7 @@ class CommandTimeoutError extends Error {
     }
 }
 function processGroupIsAlive(processGroupId) {
-    try {
-        process.kill(-processGroupId, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === 'EPERM';
-    }
+    return (0, manageThreads_js_1.isProcessGroupAlive)(processGroupId);
 }
 async function waitForProcessGroupExit(processGroupId, timeoutMs) {
     const deadline = performance.now() + timeoutMs;