@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/components/Application.ts

@@ -1,10 +1,16 @@
 import { type Logger } from '../utility/logging/logger.ts';
 import { getConfigObj, getConfigValue, getConfigPath } from '../config/configUtils.ts';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import { ClientError } from '../utility/errors/hdbError.ts';
 import logger, { errorForLog } from '../utility/logging/harper_logger.ts';
 import { broadcastDeployStart, broadcastDeployEnd } from './deployLifecycle.ts';
-import { withComponentPreparationLock } from './componentPreparationLock.ts';
-import { isThreadRunning, registerProcessGroup, unregisterProcessGroup } from '../server/threads/manageThreads.js';
+import { ComponentPreparationLockTimeoutError, withComponentPreparationLock } from './componentPreparationLock.ts';
+import {
+	isThreadRunning,
+	isProcessGroupAlive,
+	registerProcessGroup,
+	unregisterProcessGroup,
+} from '../server/threads/manageThreads.js';
 import type { CredentialReference, ResolvedCredential, ResolvedRegistryCredential } from './secretOperations.ts';
 import {
 	GIT_CREDENTIAL_SOCKET_ENV,
@@ -15,16 +21,22 @@ import {
 import { getSecretDecryptor } from '../resources/secretDecryptor.ts';
 import { ENV_ENCRYPTED_PREFIX } from '../utility/envFile.ts';
 
-import { basename, dirname, extname, join } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, sep, win32 } from 'node:path';
 import {
 	access,
+	chmod,
 	constants,
-	cp,
+	lstat,
 	mkdir,
+	link,
 	mkdtemp,
+	open,
 	readdir,
 	readFile,
+	readlink,
+	realpath,
 	rename,
+	rmdir,
 	rm,
 	stat,
 	symlink,
@@ -33,7 +45,7 @@ import {
 import { spawn, type ChildProcess } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { createReadStream, existsSync } from 'node:fs';
+import { chmodSync, createReadStream, existsSync, lstatSync, renameSync } from 'node:fs';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { StringDecoder } from 'node:string_decoder';
@@ -55,6 +67,27 @@ interface ApplicationConfig {
 	// Recorded by deploy_component so every (cold) install — reboot, new peer, rollback — re-resolves
 	// the credential from the store rather than needing it re-supplied.
 	credentials?: CredentialReference[];
+	/**
+	 * Databases this application gets a private fork of (harper#642), declared HERE — on the
+	 * application's root-config entry, alongside `host` and `urlPath` — because which databases an
+	 * application forks is a deployment decision, not something the application checks in. Declaring
+	 * it in the application's own config.yaml is refused rather than ignored.
+	 *
+	 * `true` forks every database on the instance except `system` -- a snapshot of what exists when
+	 * this application loads, not a standing subscription: a database created afterward is not
+	 * retroactively branched.
+	 *
+	 * The fork is durable: it lives at a path derived from the application and database names, is
+	 * adopted again on restart, and is invisible to other applications.
+	 *
+	 * The application must reach its data through `import { databases } from 'harper'`. The bare
+	 * `databases`/`tables` globals are shared process-wide by the default `vm-current-context` loader
+	 * and cannot be scoped, so an application that uses them reads and writes the BASE — silently.
+	 * Per-application globals are a property of thread-level isolation, not of branching.
+	 */
+	branchedDatabases?: string[] | true;
+	/** Run in a worker thread of its own that loads no other application. */
+	isolated?: boolean;
 	// an application config can have other arbitrary properties
 	[key: string]: unknown;
 }
@@ -99,6 +132,12 @@ export class InvalidCredentialsPropertyError extends TypeError {
 	}
 }
 
+export class InvalidBranchedDatabasesError extends TypeError {
+	constructor(applicationName: string, detail: string) {
+		super(`Invalid 'branchedDatabases' for application ${applicationName}: ${detail}`);
+	}
+}
+
 export class InvalidCredentialEntryError extends TypeError {
 	constructor(applicationName: string) {
 		super(
@@ -112,6 +151,18 @@ export function assertApplicationConfig(
 	applicationName: string,
 	applicationConfig: Record<'package', unknown> & Record<string, unknown>
 ): asserts applicationConfig is 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);
 	}
@@ -170,6 +221,47 @@ export function assertApplicationConfig(
 			}
 		}
 	}
+	assertBranchedDatabases(applicationName, applicationConfig.branchedDatabases);
+	assertIsolationConfig(applicationName, applicationConfig.isolated);
+}
+
+export function assertIsolationConfig(applicationName: string, isolated: unknown): void {
+	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.
+ */
+export function assertBranchedDatabases(applicationName: string, value: unknown): void {
+	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<string>();
+	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);
+	}
 }
 
 /**
@@ -478,16 +570,51 @@ async function runNpmPack(
 // during a deploy swap (see extractApplication). The leading dot keeps
 // loadComponentDirectories from loading its contents as components.
 export const 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.
+export const 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'] as const;
+const INSTALL_LIFECYCLE_SCRIPTS = new Set([
+	'preinstall',
+	'install',
+	'postinstall',
+	'prepublish',
+	'preprepare',
+	'prepare',
+	'postprepare',
+	'dependencies',
+]);
 
 type ExtractionTransaction = {
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
 };
 
+type ExtractionContext = Pick<Application, 'name' | 'dirPath' | 'logger'>;
+
 // 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.
 export const GIT_CREDENTIAL_HELPER_PATH = join(__dirname, 'gitCredentialHelper.js');
@@ -508,6 +635,42 @@ type InstalledPackageMetadata = {
 	hasInstallableDependencies: boolean;
 };
 
+function dependencyFieldHasWork(packageJSON: any, field: string): boolean {
+	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;
+}
+
+export function packageHasProductionInstallWork(packageJSON: any): boolean {
+	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: any): boolean {
+	const packageManager = packageJSON?.devEngines?.packageManager;
+	return !!packageManager && packageManager.name !== 'npm';
+}
+
+export function packageHasAutomaticInstallWork(packageJSON: any): boolean {
+	return packageHasProductionInstallWork(packageJSON) || packageHasExplicitNonNpmManager(packageJSON);
+}
+
+function packageHasAllowedInstallLifecycleWork(packageJSON: any): boolean {
+	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;
+	});
+}
+
 export async function readInstalledPackageMetadata(directory: string): Promise<InstalledPackageMetadata> {
 	const files = new Map<string, Buffer>();
 	let readable = true;
@@ -538,17 +701,7 @@ export async function readInstalledPackageMetadata(directory: string): Promise<I
 		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),
 	};
 }
 
@@ -584,30 +737,17 @@ function canonicalizeJSON(value: any): any {
 }
 
 /**
- * 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.
+ * Either a tarball to extract, or — for `file:<directory>` — an instruction to link that directory. The link
+ * case is a RESULT rather than an action so the caller decides where it lands: a candidate build must link
+ * at the candidate path, or the deploy is published without validation.
  */
-export async function extractApplication(
-	application: Application,
-	deferCommit = false
-): Promise<ExtractionTransaction | undefined> {
-	// Can't specify neither
-	if (!application.payload && !application.packageIdentifier) {
-		throw new Error('Either payload or package must be provided');
-	}
+type ResolvedTarball =
+	| { kind: 'tarball'; tarball: Readable; tarballPath?: string; shouldDeleteTarball: boolean }
+	| { kind: 'link'; sourceDirPath: string };
 
-	// 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
-	let tarballPath: string;
+/** Resolve `payload` or `package` into a tarball stream. Touches neither the live tree nor staging. */
+async function resolveApplicationTarball(application: Application): Promise<ResolvedTarball> {
+	let tarballPath: string | undefined;
 	let tarball: Readable;
 	let shouldDeleteTarball = false;
 
@@ -626,6 +766,8 @@ export async function extractApplication(
 	} else {
 		// Given a package, there are a a couple options
 		const parentDirPath = 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:')) {
@@ -635,22 +777,29 @@ export async function extractApplication(
 				const stats = await stat(packagePath);
 
 				if (stats.isDirectory()) {
-					// If its a directory, symlink
-					await 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');
+				} else {
+					if (!stats.isFile()) {
+						throw new Error(`File path specified in package identifier is not a file or directory: ${packagePath}`);
+					}
 
-				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 = 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 = createReadStream(tarballPath);
 			} catch (err) {
 				if (err.code === 'ENOENT') {
 					throw new Error(`File path specified in package identifier does not exist: ${packagePath}`);
@@ -658,7 +807,8 @@ export async function extractApplication(
 					throw err;
 				}
 			}
-		} 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.
@@ -680,195 +830,3013 @@ export async function extractApplication(
 			// 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);
+			const gitRef = allowScripts ? null : parseGitReference(packageIdentifierForPack);
 
-			if (!allowScripts && !gitRef && looksLikeGitReference(application.packageIdentifier)) {
+			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.`
+					`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 = 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: Readable,
+	targetDirPath: string,
+	scratchDirPath: string
+): Promise<string | undefined> {
+	await mkdir(targetDirPath, { recursive: true });
+	await pipeline(tarball, gunzip(), extract(targetDirPath));
+
+	const extracted = await readdir(targetDirPath, { withFileTypes: true });
+	if (extracted.length === 1 && extracted[0].isDirectory()) {
+		const topLevelDirPath = join(targetDirPath, extracted[0].name);
+		if (process.platform === 'win32') {
+			for (const childName of await readdir(topLevelDirPath)) {
+				await rename(join(topLevelDirPath, childName), join(targetDirPath, childName));
+			}
+			await rmdir(topLevelDirPath);
+		} else {
+			const tempDirPath = join(scratchDirPath, `.normalize-${process.pid}-${Date.now()}-${randomUUID()}`);
+			await rename(topLevelDirPath, tempDirPath);
+			await rmdir(targetDirPath);
+			await 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.
+ */
+export async function extractApplication(
+	application: Application,
+	deferCommit = false
+): Promise<ExtractionTransaction | undefined> {
+	// 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 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<string>();
+	let asidePath: string | undefined;
+	let recoveryRecordPath: string;
+	try {
+		await ensureExtractionStagingDirectory(asideStagingDir);
+		await recoverOrCleanupStaleExtractionPaths(application, asideStagingDir);
+		let componentExists = true;
+		try {
+			await lstat(application.dirPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+			componentExists = false;
+		}
+		if (componentExists) {
+			await ensureExtractionStagingDirectory(asideStagingDir);
+			asidePath = join(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${randomUUID()}`);
+			await rename(application.dirPath, asidePath);
+			transactionPaths.add(asidePath);
+			recoveryRecordPath = asidePath;
+		} else {
+			await ensureExtractionStagingDirectory(asideStagingDir);
+			recoveryRecordPath = join(
+				asideStagingDir,
+				`${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${randomUUID()}${PRIOR_ABSENT_RECORD_SUFFIX}`
+			);
+			await 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 rm(tarballPath, { force: true }).catch((error) =>
+				application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error)
+			);
+		}
+	}
+
+	let settled = false;
+	const transaction: ExtractionTransaction = {
+		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". */
+export function getStagingRetentionMaxCount(): number {
+	const configured = getConfigValue(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;
+}
+
+type DormantBuild = {
+	deploymentDirPath: string;
+	deploymentId: string;
+	completedAt: number;
+};
+
+async function presentOrAbsent(path: string): Promise<import('node:fs').Stats | undefined> {
+	return lstat(path).catch((error: NodeJS.ErrnoException) => {
+		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: string, owner: string): Promise<DormantBuild | undefined> {
+	const complete = await presentOrAbsent(join(deploymentDirPath, CANDIDATE_COMPLETE_MARKER));
+	if (!complete) return undefined;
+	if (await presentOrAbsent(join(deploymentDirPath, UNSETTLED_MARKER))) return undefined;
+	const tree = await presentOrAbsent(join(deploymentDirPath, owner));
+	if (!tree || !(tree.isDirectory() || tree.isSymbolicLink())) return undefined;
+	return { deploymentDirPath, deploymentId: 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.
+ */
+export async function pruneDormantBuilds(
+	componentName: string,
+	builds: DormantBuild[],
+	maxCount: number,
+	pinnedDeploymentId?: string
+): Promise<void> {
+	const current: DormantBuild[] = [];
+	for (const build of builds) {
+		try {
+			const fresh = await dormantBuildAt(build.deploymentDirPath, componentName);
+			if (fresh && !(await presentOrAbsent(join(build.deploymentDirPath, ACTIVATION_JOURNAL)))) current.push(fresh);
+		} catch (error) {
+			logger.warn(
+				`Leaving deploy staging ${build.deploymentDirPath} out of retention; it could not be read:`,
+				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 rm(build.deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+			logger.debug?.(
+				`Pruned dormant staged build ${build.deploymentId} of ${componentName} beyond deployment_stagingRetention_maxCount=${maxCount}`
+			);
+		} catch (error) {
+			logger.warn(
+				`Could not prune dormant staged build ${build.deploymentDirPath} of ${componentName}; it remains beyond ` +
+					`deployment_stagingRetention_maxCount=${maxCount}:`,
+				errorForLog(error)
+			);
+		}
+	}
+}
+
+/** Every dormant build a component owns; an unreadable directory is left out and logged. */
+async function dormantBuildsOf(componentsRootDirPath: string, componentName: string): Promise<DormantBuild[]> {
+	const stagingRoot = join(componentsRootDirPath, DEPLOY_STAGING_DIR);
+	let deployments;
+	try {
+		deployments = await readdir(stagingRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+		throw error;
+	}
+	const builds: DormantBuild[] = [];
+	for (const deployment of deployments) {
+		if (!deployment.isDirectory()) continue;
+		const deploymentDirPath = join(stagingRoot, deployment.name);
+		try {
+			if ((await candidateComponentName(deploymentDirPath)) !== componentName) continue;
+			if (await presentOrAbsent(join(deploymentDirPath, ACTIVATION_JOURNAL))) continue;
+			const build = await dormantBuildAt(deploymentDirPath, componentName);
+			if (build) builds.push(build);
+		} catch (error) {
+			logger.warn(
+				`Leaving deploy staging ${deploymentDirPath} out of retention; it could not be read:`,
+				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: string): Promise<void> {
+	let handle;
+	try {
+		handle = await 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 as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;
+		logger.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;
+		logger.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) => logger.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: string, toPath: string): Promise<void> {
+	const parents = new Set([dirname(fromPath), 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: string,
+	toPath: string,
+	options: { onBackoff?: (delayMs: number, deadline: number) => Promise<void>; deadline?: number } = {}
+): Promise<void> {
+	const deadline = options.deadline ?? performance.now() + RENAME_RETRY_BUDGET_MS;
+	let delayMs = RENAME_RETRY_INITIAL_DELAY_MS;
+	for (let attempts = 1; ; attempts++) {
+		try {
+			await rename(fromPath, toPath);
+			if (attempts > 1) {
+				logger.warn(`Renamed ${fromPath} to ${toPath} only on attempt ${attempts}; something was holding it`);
+			}
+			return;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).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: string) =>
+					lstat(path).then(
+						() => 'present',
+						(probeError) => (probeError as NodeJS.ErrnoException)?.code ?? 'unreadable'
+					);
+				logger.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 delay(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: string, contents: string): Promise<void> {
+	const tempPath = `${filePath}.partial-${process.pid}-${randomUUID()}`;
+	const handle = await 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 link(tempPath, filePath);
+	} finally {
+		await rm(tempPath, { force: true });
+	}
+	await syncDirectory(dirname(filePath));
+}
+
+type ActivationJournal = {
+	v: number;
+	component: string;
+	candidateId: string;
+};
+
+function candidateCompleteMarkerPath(componentDirPath: string, deploymentId: string): string {
+	return join(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_COMPLETE_MARKER);
+}
+
+function candidateComponentFilePath(componentDirPath: string, deploymentId: string): string {
+	return join(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_COMPONENT_FILE);
+}
+
+function activationJournalPath(componentDirPath: string, deploymentId: string): string {
+	return join(candidateDeploymentDirPath(componentDirPath, deploymentId), ACTIVATION_JOURNAL);
+}
+
+function candidateArtifactFilePath(componentDirPath: string, deploymentId: string): string {
+	return join(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_ARTIFACT_FILE);
+}
+
+export type ArtifactDescriptor = {
+	v: number;
+	component: string;
+	/** The root-config entry to publish with the activation; `null` for a payload build, which owns none. */
+	rootConfig: Record<string, unknown> | null;
+	installationIsOpaque: boolean;
+	isolated: boolean;
+};
+
+/**
+ * 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: string,
+	componentName: string
+): Promise<ArtifactDescriptor | undefined> {
+	const descriptorPath = 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: string) => new ClientError(message, 409);
+	const raw = await readFile(descriptorPath, 'utf8').catch((error: NodeJS.ErrnoException) => {
+		if (error?.code === 'ENOENT') return undefined;
+		throw error;
+	});
+	if (raw === undefined) return undefined;
+	let parsed: any;
+	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 as ArtifactDescriptor;
+}
+
+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: string,
+	componentName: string,
+	action: 'stage' | 'activate' = 'stage'
+): Promise<void> {
+	// 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: string) => new ClientError(message, action === 'stage' ? 400 : 409);
+	const ownedRoot = await 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 = join(candidateDirPath, 'node_modules');
+	const walk = async (dirPath: string): Promise<void> => {
+		const entries = await readdir(dirPath, { withFileTypes: true });
+		for (const entry of entries) {
+			const entryPath = 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 realpath(entryPath).catch(() => undefined);
+			if (target === undefined || (target !== ownedRoot && !target.startsWith(ownedRoot + 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 readlink(entryPath);
+			if (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 = 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 realpath(join(prefix, segment)).catch(() => join(prefix, segment));
+				if (prefix !== ownedRoot && !prefix.startsWith(ownedRoot + 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: string,
+	deploymentId: string,
+	descriptor: ArtifactDescriptor
+): Promise<void> {
+	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 as NodeJS.ErrnoException).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: unknown): name is string {
+	return (
+		typeof name === 'string' &&
+		name.length > 0 &&
+		name === 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: string): Promise<ActivationJournal | undefined> {
+	let raw: string;
+	try {
+		raw = await readFile(journalPath, 'utf8');
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+		throw error;
+	}
+	let parsed: any;
+	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 !== basename(dirname(journalPath))) {
+		throw new Error(
+			`Activation journal ${journalPath} names candidate '${parsed.candidateId}', which is not its own deployment`
+		);
+	}
+	return parsed as ActivationJournal;
+}
+
+/**
+ * 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: string, deploymentId: string): string {
+	if (
+		typeof deploymentId !== 'string' ||
+		deploymentId.length === 0 ||
+		deploymentId !== 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 join(dirname(componentDirPath), DEPLOY_STAGING_DIR, deploymentId);
+}
+
+/** Where a candidate build lives: `<root>/.deploy-staging/<deploymentId>/<component>`. */
+export function candidateApplicationPath(componentDirPath: string, deploymentId: string): string {
+	return join(candidateDeploymentDirPath(componentDirPath, deploymentId), basename(componentDirPath));
+}
+
+function extractionStagingDirectory(componentDirPath: string): string {
+	return join(dirname(componentDirPath), ASIDE_STAGING_DIR, basename(componentDirPath));
+}
+
+function retiredMarkerForAside(asidePath: string): string {
+	return join(
+		dirname(asidePath),
+		`${RETIRED_ASIDE_PREFIX}${basename(asidePath).slice(IN_PROGRESS_ASIDE_PREFIX.length)}`
+	);
+}
+
+async function retireExtractionAside(asidePath: string): Promise<string> {
+	const retiredMarkerPath = retiredMarkerForAside(asidePath);
+	try {
+		await writeFile(retiredMarkerPath, '', { flag: 'wx', mode: 0o600 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+	}
+	return retiredMarkerPath;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export async function makeRollbackPlaceholderMovable(
+	applicationDirPath: string,
+	placeholderIdentity: { dev: bigint; ino: bigint } | undefined
+): Promise<void> {
+	if (!placeholderIdentity) return;
+	try {
+		const current = await lstat(applicationDirPath, { bigint: true });
+		if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+			await chmod(applicationDirPath, 0o700);
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+	}
+}
+
+async function identifyRollbackPlaceholder(
+	applicationDirPath: string
+): Promise<{ dev: bigint; ino: bigint } | undefined> {
+	const userId = process.getuid?.();
+	if (process.platform === 'win32' || userId === undefined || userId === 0) return undefined;
+	try {
+		const current = await 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 as NodeJS.ErrnoException).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: string): Promise<void> {
+	await mkdir(stagingDir, { recursive: true, mode: 0o700 });
+	const stagingStat = await 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 chmod(stagingDir, 0o700).catch((error) =>
+			logger.warn(`Could not restrict component deploy staging permissions for ${stagingDir}:`, 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: string, componentName: string): Promise<void> {
+	// 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: string) => new ClientError(message, 409);
+	try {
+		await mkdir(deploymentDirPath, { mode: 0o700 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+		const owner = await candidateComponentName(deploymentDirPath);
+		if (owner !== undefined && owner !== componentName) {
+			throw taken(
+				`Deployment id ${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 mkdir(deploymentDirPath, { mode: 0o700 }).catch((retry: NodeJS.ErrnoException) => {
+				if (retry?.code !== 'EEXIST') throw retry;
+				throw taken(
+					`Deployment id ${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(join(deploymentDirPath, CANDIDATE_COMPLETE_MARKER))) {
+				throw taken(
+					`Deployment id ${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 rm(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+			await mkdir(deploymentDirPath, { mode: 0o700 });
+		}
+	}
+	const claimed = await 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 chmod(deploymentDirPath, 0o700).catch((error) =>
+			logger.warn(
+				`Could not restrict component deploy staging permissions for ${deploymentDirPath}:`,
+				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.
+ */
+export async function publishClaimOwnership(
+	deploymentDirPath: string,
+	componentName: string,
+	write: (filePath: string, contents: string) => Promise<void> = writeControlFileDurably
+): Promise<void> {
+	try {
+		await write(join(deploymentDirPath, CANDIDATE_COMPONENT_FILE), componentName);
+	} catch (error) {
+		await rm(deploymentDirPath, { recursive: true, force: true }).catch((cleanupError) =>
+			logger.warn(
+				`Could not remove the deployment directory ${deploymentDirPath} after failing to publish its ` +
+					`ownership; the id stays unusable until it is removed:`,
+				errorForLog(cleanupError)
+			)
+		);
+		throw error;
+	}
+}
+
+async function ensureExtractionStagingDirectory(asideStagingDir: string): Promise<void> {
+	for (const stagingDir of [dirname(asideStagingDir), asideStagingDir]) {
+		await ensureSecureStagingDirectory(stagingDir);
+	}
+}
+
+/** The single component directory inside a candidate deployment directory, when there is exactly one. */
+async function candidateComponentName(deploymentDirPath: string): Promise<string | undefined> {
+	// 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 readFile(join(deploymentDirPath, CANDIDATE_COMPONENT_FILE), 'utf8').catch(
+		(error: NodeJS.ErrnoException) => {
+			if (error?.code === 'ENOENT') return '';
+			throw error;
+		}
+	);
+	const named = recorded.trim();
+	if (isJoinableComponentName(named)) return named;
+	const entries = await readdir(deploymentDirPath, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+		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: string,
+	componentName: string
+): Promise<string | undefined> {
+	const stagingRoot = join(componentsRootDirPath, DEPLOY_STAGING_DIR);
+	let deployments;
+	try {
+		deployments = await readdir(stagingRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+		throw error;
+	}
+	for (const deployment of deployments) {
+		if (!deployment.isDirectory()) continue;
+		const deploymentDirPath = join(stagingRoot, deployment.name);
+		const journalPath = 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 lstat(journalPath).then(
+			() => true,
+			(error) => {
+				if ((error as NodeJS.ErrnoException).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.
+ */
+export function splitAttributionOwners(
+	journalOwner: string,
+	sidecarOwner: string | undefined
+): [string, string] | undefined {
+	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: string, journalOwner: string, sidecarOwner: string): Error {
+	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: string): Promise<string[]> {
+	// 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 readdir(asideStagingDir, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+		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) => 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: string,
+	componentName: string,
+	pinnedDeploymentId?: string
+): Promise<void> {
+	const stagingRoot = join(componentsRootDirPath, DEPLOY_STAGING_DIR);
+	let deployments;
+	try {
+		deployments = await readdir(stagingRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+		throw error;
+	}
+	const dormant: DormantBuild[] = [];
+	for (const deployment of deployments) {
+		if (!deployment.isDirectory()) continue;
+		const deploymentDirPath = 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: string | undefined;
+		let ownerUnreadable = false;
+		try {
+			owner = await candidateComponentName(deploymentDirPath);
+		} catch (error) {
+			ownerUnreadable = true;
+			logger.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(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) {
+				logger.warn(
+					`Leaving staged ${componentName} build ${deploymentDirPath} out of retention; it could not be read:`,
+					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.
+ */
+export async function unsettleableComponentsFromDisk(componentsRootDirPath: string): Promise<Map<string, Error>> {
+	const unsettleable = new Map<string, Error>();
+	const stagingRoot = join(componentsRootDirPath, DEPLOY_STAGING_DIR);
+	let deployments;
+	try {
+		deployments = await readdir(stagingRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return unsettleable;
+		throw error;
+	}
+	for (const deployment of deployments) {
+		if (!deployment.isDirectory()) continue;
+		const deploymentDirPath = 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: string,
+	deploymentName: string,
+	unsettleable: Map<string, Error>
+): Promise<void> {
+	// 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: string | undefined;
+	try {
+		recorded = await readFile(join(deploymentDirPath, UNSETTLED_MARKER), 'utf8');
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).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(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: string, deploymentName: string): Promise<string> {
+	return (await candidateComponentName(deploymentDirPath)) ?? deploymentName;
+}
+
+function record(unsettleable: Map<string, Error>, component: string, failure: Error): void {
+	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.
+ *
+ */
+export async function recoverInterruptedActivations(componentsRootDirPath: string): Promise<Map<string, Error>> {
+	const failures = new Map<string, Error>();
+	const stagingRoot = join(componentsRootDirPath, DEPLOY_STAGING_DIR);
+	let deployments;
+	try {
+		deployments = await readdir(stagingRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return failures;
+		throw error;
+	}
+	const dormant = new Map<string, DormantBuild[]>();
+	const catalogue = (owner: string, build: DormantBuild) => {
+		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 = join(stagingRoot, deployment.name);
+		const journalPath = join(deploymentDirPath, ACTIVATION_JOURNAL);
+		const fail = (component: string, error: unknown) => recordUnsettled(failures, component, error, deploymentDirPath);
+
+		let journal: ActivationJournal | undefined;
+		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: string | undefined;
+			// 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: string | undefined;
+			// 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: [string, string] | undefined;
+			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(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(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) {
+						logger.info?.(
+							`Cleared a stale unsettled verdict from the staged build ${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 rm(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) =>
+					logger.warn(`Could not clean up deploy staging ${deploymentDirPath}:`, 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) {
+				logger.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: DormantBuild | undefined;
+				try {
+					build = await dormantBuildAt(deploymentDirPath, owner);
+				} catch (error) {
+					logger.warn(
+						`Leaving deploy staging ${deploymentDirPath} in place; it could not be read:`,
+						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 withComponentPreparationLock(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 || 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.
+					logger.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 ComponentPreparationLockTimeoutError) await fail(owner ?? deployment.name, error);
+				else
+					logger.warn(
+						`Could not settle deploy staging ${deploymentDirPath}, which holds no activation journal:`,
+						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 withComponentPreparationLock(
+				join(componentsRootDirPath, settling.component),
+				() => settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, settling),
+				{
+					purpose: 'activation-recovery',
+					...RECOVERY_LOCK_WAIT,
+					isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || 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: Map<string, Error>,
+	component: string,
+	error: unknown,
+	deploymentDirPath: string
+): Promise<void> {
+	const failure = error instanceof Error ? error : new Error(String(error));
+	if (!failures.has(component)) failures.set(component, failure);
+	logger.error(`Could not settle the interrupted activation of ${component}:`, errorForLog(failure));
+	if (failure instanceof ComponentPreparationLockTimeoutError) return;
+	await writeFile(join(deploymentDirPath, UNSETTLED_MARKER), failure.message, { mode: 0o600 }).catch((markerError) =>
+		logger.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.
+ */
+export async function reconcileDormantBuilds(
+	componentsRootDirPath: string,
+	owner: string,
+	builds: DormantBuild[],
+	maxCount: number
+): Promise<Map<string, Error>> {
+	const failures = new Map<string, Error>();
+	let journaled: DormantBuild | undefined;
+	for (const build of builds) {
+		// Anything but a clean ENOENT means "read it properly, under the lock".
+		const appeared = await presentOrAbsent(join(build.deploymentDirPath, ACTIVATION_JOURNAL)).then(
+			(stats) => stats !== undefined,
+			() => true
+		);
+		if (appeared) {
+			journaled = build;
+			break;
+		}
+	}
+	if (!journaled && builds.length <= maxCount) return failures;
+	try {
+		await withComponentPreparationLock(
+			join(componentsRootDirPath, owner),
+			async () => {
+				const stillDormant: DormantBuild[] = [];
+				for (const build of builds) {
+					let journal: ActivationJournal | undefined;
+					try {
+						journal = await readActivationJournal(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 || 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 ComponentPreparationLockTimeoutError) {
+			if (!failures.has(owner)) failures.set(owner, failure);
+			logger.info?.(`Deferred pruning the dormant staged builds of ${owner}: a deploy holds its lock`);
+		} else {
+			logger.warn(`Could not prune the dormant staged builds of ${owner}:`, 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: string[],
+	componentName: string,
+	liveDirPath: string,
+	asideStagingDir: string
+): Promise<void> {
+	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 },
+			asideStagingDir,
+			new Set([record, retiredMarkerPath])
+		).catch((error) => logger.warn(`Settled ${componentName} but could not sweep ${record}:`, 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: string, componentName: string): Promise<void> {
+	try {
+		await rm(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 ` +
+				`${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: string,
+	deploymentDirPath: string,
+	journal: ActivationJournal
+): Promise<void> {
+	const liveDirPath = join(componentsRootDirPath, journal.component);
+	const candidateDirPath = join(deploymentDirPath, journal.component);
+	const asideStagingDir = extractionStagingDirectory(liveDirPath);
+	const journalPath = join(deploymentDirPath, ACTIVATION_JOURNAL);
+
+	const exists = async (path: string) =>
+		lstat(path).then(
+			() => true,
+			(error) => {
+				if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+				throw error;
+			}
+		);
+	const liveExists = await exists(liveDirPath);
+	const candidateExists = await exists(candidateDirPath);
+	const candidateComplete = await exists(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?: string) => {
+		if (restoreFrom) {
+			await renameThroughTransientHolder(restoreFrom, liveDirPath);
+			await syncRenameParents(restoreFrom, liveDirPath);
+		}
+		for (const record of asideRecords) {
+			try {
+				await 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.
+				logger.warn(`Rolled ${journal.component} back but could not remove ${record}:`, 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(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 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) =>
+				logger.warn(
+					`Returned the staged build ${basename(deploymentDirPath)} of ${journal.component} to dormant but ` +
+						`could not flush that to storage; a power loss could resurrect its activation journal:`,
+					errorForLog(error)
+				)
+			);
+			logger.info?.(
+				`Returned the staged build ${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(dirname(asideStagingDir));
+	} catch (error) {
+		logger.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 rm(journalPath, { force: true }).catch((error) =>
+		logger.warn(`Settled ${journal.component} but could not remove its activation journal:`, errorForLog(error))
+	);
+	await rm(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) =>
+		logger.warn(`Settled ${journal.component} but could not clean up its staging directory:`, errorForLog(error))
+	);
+	await rmdir(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: unknown): boolean {
+	return UNSUPPORTED_SYNC_CODES.has((error as NodeJS.ErrnoException)?.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: string, foreignTree = false): Promise<void> {
+	// 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 readdir(rootPath, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+		// 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') {
+			logger.trace?.(`Sync of ${rootPath} unavailable: ${errorMessage(error)}`);
+			return undefined;
+		}
+		throw error;
+	});
+	if (!entries) return;
+	const syncFile = async (entryPath: string) => {
+		let handle;
+		try {
+			handle = await 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 as NodeJS.ErrnoException)?.code === 'EACCES')) {
+				logger.trace?.(`Sync of ${entryPath} unavailable: ${errorMessage(error)}`);
+				return;
+			}
+			throw error;
+		}
+		try {
+			await handle.sync();
+		} catch (error) {
+			if (!isUnsupportedSync(error)) throw error;
+			logger.trace?.(`Sync of ${entryPath} unsupported: ${errorMessage(error)}`);
+		} finally {
+			await handle.close().catch(() => {});
+		}
+	};
+	const pending: Promise<void>[] = [];
+	for (const entry of entries) {
+		const entryPath = 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);
+}
+
+export async function markCandidateComplete(
+	componentDirPath: string,
+	deploymentId: string,
+	componentName: string
+): Promise<void> {
+	// 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 lstat(candidatePath).then(
+		(stats) => stats.isSymbolicLink(),
+		(error) => {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+			throw error;
+		}
+	);
+	await syncTreeContents(candidatePath, candidateIsLink);
+	try {
+		await writeControlFileDurably(candidateComponentFilePath(componentDirPath, deploymentId), componentName);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+	}
+	try {
+		await writeControlFileDurably(candidateCompleteMarkerPath(componentDirPath, deploymentId), '');
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).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: string): Promise<void> {
+	const stagingRoot = dirname(deploymentDirPath);
+	for (const directory of [deploymentDirPath, stagingRoot, 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.
+ */
+export async function activateCandidateApplication(
+	application: Application,
+	deploymentId: string,
+	options: { afterJournal?: () => Promise<(() => Promise<void>) | void> } = {}
+): Promise<void> {
+	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 lstat(candidateDirPath).catch((error) => {
+		if ((error as NodeJS.ErrnoException).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: string | undefined;
+	let priorAbsentRecordPath: string | undefined;
+	// 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 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 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: (() => Promise<void>) | void;
+	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 as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+		}
+
+		pendingEffect = 'prepare the component staging directory';
+		await ensureExtractionStagingDirectory(asideStagingDir);
+		pendingEffect = 'read the live component directory';
+		const liveExists = await lstat(liveDirPath).then(
+			() => true,
+			(error) => {
+				if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+				throw error;
+			}
+		);
+		application.isNewComponent = !liveExists;
+
+		pendingEffect = 'move the previous version aside';
+		if (liveExists) {
+			asidePath = join(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${randomUUID()}`);
+			await renameThroughTransientHolder(liveDirPath, asidePath);
+			liveIsDisplaced = true;
+		} else {
+			priorAbsentRecordPath = join(
+				asideStagingDir,
+				`${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${randomUUID()}${PRIOR_ABSENT_RECORD_SUFFIX}`
+			);
+			await 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 delay(delayMs);
+				await renameThroughTransientHolder(asidePath!, liveDirPath, { deadline });
+				liveIsDisplaced = false;
+				await syncRenameParents(asidePath!, liveDirPath);
+				await delay(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(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 rm(journalPath, { force: true }).catch((error) =>
+			application.logger.warn(`Deployed ${application.name} but could not remove its activation journal:`, error)
+		);
+		await 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 rmdir(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: unknown): boolean {
+	return Boolean((error as any)?.[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: unknown,
+	what: string,
+	undo: () => Promise<void>,
+	application: Application
+): Promise<void> {
+	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 as any)[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: string, builtAtPath: string): Promise<void> {
+	const relinkOne = async (entryPath: string) => {
+		let target: string;
+		try {
+			target = await 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 = relative(builtAtPath, normalized);
+		if (within.startsWith('..') || isAbsolute(within)) return;
+		const repaired = 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}-${randomUUID()}`;
+		try {
+			await symlink(repaired, stagedLink, 'junction');
+			try {
+				await 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 rm(entryPath, { recursive: true, force: true });
+				try {
+					await rename(stagedLink, entryPath);
+				} catch (secondError) {
+					await symlink(normalized, entryPath, 'junction').catch(() => {});
+					throw secondError;
+				}
+			}
+		} catch (error) {
+			await rm(stagedLink, { recursive: true, force: true }).catch(() => {});
+			logger.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: string[] = [join(liveDirPath, 'node_modules')];
+	let active = 0;
+	const visit = async (dirPath: string): Promise<void> => {
+		let entries;
+		try {
+			entries = await 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 as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+				logger.warn(`Could not scan ${dirPath} for links to re-point after activation:`, errorForLog(error));
+			}
+			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 = join(dirPath, entry.name);
+			if (entry.isSymbolicLink()) await relinkOne(entryPath);
+			else if (entry.isDirectory()) pending.push(entryPath);
+		}
+	};
+	const worker = async (): Promise<void> => {
+		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;
+			}
+			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: string): string {
+	return target.startsWith('\\\\?\\') ? target.slice(4) : target;
+}
 
-			if (gitRef) {
-				tarballPath = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath);
-			} 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.`
+/** Remove a candidate's whole deployment directory, best-effort — it is never the last good copy. */
+async function discardCandidate(application: Application, deploymentId: string): Promise<void> {
+	const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
+	await 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 rmdir(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.
+ */
+export async function buildCandidateApplication(
+	application: Application,
+	deploymentId: string,
+	options: { rejectLinkSource?: boolean } = {}
+): Promise<string> {
+	const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
+	const candidateDirPath = candidateApplicationPath(application.dirPath, deploymentId);
+	await ensureSecureStagingDirectory(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 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 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 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 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 = 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;
+	} catch (error) {
+		await discardCandidate(application, deploymentId);
+		throw error;
 	}
+}
 
-	// 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 = join(dirname(application.dirPath), ASIDE_STAGING_DIR, basename(application.dirPath));
-	let asidePath: string | undefined;
-	try {
-		await access(application.dirPath, constants.F_OK);
-		await mkdir(asideStagingDir, { recursive: true });
-		const candidateAsidePath = join(asideStagingDir, `${process.pid}-${Date.now()}-${randomUUID()}`);
-		await rename(application.dirPath, candidateAsidePath);
-		asidePath = candidateAsidePath;
-	} catch (err) {
-		// Ignore does not exist error
-		if (err.code !== 'ENOENT') {
-			throw err;
+async function recoverOrCleanupStaleExtractionPaths(
+	application: ExtractionContext,
+	asideStagingDir: string
+): Promise<void> {
+	const entries = await readdir(asideStagingDir, { withFileTypes: true });
+	const entryNames = new Set(entries.map((entry) => entry.name));
+	const paths = new Set<string>(entries.map((entry) => 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(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 = 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(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: { isFile(): boolean; name: string }): boolean {
+	return entry.isFile() && entry.name.endsWith(PRIOR_ABSENT_RECORD_SUFFIX);
+}
+
+function isExtractionRecoveryRecord(entry: {
+	isDirectory(): boolean;
+	isFile(): boolean;
+	isSymbolicLink(): boolean;
+	name: string;
+}): boolean {
+	return entry.isDirectory() || entry.isSymbolicLink() || isPriorAbsentRecoveryRecord(entry);
+}
+
+function extractionAsideTimestamp(name: string): number {
+	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));
+}
+
+export async function recoverInterruptedComponentExtractions(
+	componentsRootDirPath: string
+): Promise<Map<string, Error>> {
+	const stagingRoot = join(componentsRootDirPath, ASIDE_STAGING_DIR);
+	let entries;
 	try {
-		await mkdir(application.dirPath, { recursive: true });
-		await pipeline(tarball, gunzip(), extract(application.dirPath));
-
-		const extracted = await readdir(application.dirPath, { withFileTypes: true });
-		if (extracted.length === 1 && extracted[0].isDirectory()) {
-			const topLevelDirPath = join(application.dirPath, extracted[0].name);
-			await mkdir(asideStagingDir, { recursive: true });
-			const tempDirPath = await mkdtemp(join(asideStagingDir, '.normalize-'));
-			await cp(topLevelDirPath, tempDirPath, { recursive: true });
-			await rm(topLevelDirPath, { recursive: true, force: true });
-			await cp(tempDirPath, application.dirPath, { recursive: true });
-			await rm(tempDirPath, { recursive: true, force: true });
+		const stagingStat = await lstat(stagingRoot);
+		if (!stagingStat.isDirectory() || stagingStat.isSymbolicLink()) {
+			throw new Error(`Component deploy staging path is not a directory: ${stagingRoot}`);
 		}
+		entries = await readdir(stagingRoot, { withFileTypes: true });
 	} catch (error) {
-		try {
-			await rollbackExtractedDirectory(application, asideStagingDir, asidePath);
-		} catch (rollbackError) {
-			throw new AggregateError(
-				[error, rollbackError],
-				`Failed to extract ${application.name} and restore its previous component directory`
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return new Map();
+		throw error;
+	}
+	const failedComponents = new Map<string, Error>();
+	await Promise.all(
+		entries
+			.filter((entry) => entry.isDirectory())
+			.map(async (entry) => {
+				try {
+					await recoverInterruptedComponentExtraction(componentsRootDirPath, entry.name, false);
+				} catch (error) {
+					const recoveryError = error instanceof Error ? error : new Error(String(error));
+					failedComponents.set(entry.name, recoveryError);
+					const deferred = recoveryError instanceof ComponentPreparationLockTimeoutError;
+					logger[deferred ? 'warn' : 'error'](
+						`${deferred ? 'Deferring' : 'Not loading'} ${entry.name} because its interrupted component deployment ` +
+							`${deferred ? 'is still being prepared' : 'could not be recovered'}:`,
+						errorForLog(recoveryError)
+					);
+				}
+			})
+	);
+	return failedComponents;
+}
+
+export async function recoverInterruptedComponentExtraction(
+	componentsRootDirPath: string,
+	componentName: string,
+	waitForPreparation = true,
+	waitTimeoutMs = COMPONENT_RECOVERY_WAIT_TIMEOUT_MS
+): Promise<void> {
+	const componentDirPath = join(componentsRootDirPath, componentName);
+	await withComponentPreparationLock(
+		componentDirPath,
+		async () => {
+			const asideStagingDir = extractionStagingDirectory(componentDirPath);
+			try {
+				await lstat(asideStagingDir);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+				throw error;
+			}
+			await ensureExtractionStagingDirectory(asideStagingDir);
+			await recoverOrCleanupStaleExtractionPaths(
+				{ name: componentName, dirPath: componentDirPath, logger },
+				asideStagingDir
 			);
+		},
+		{
+			timeoutMs: waitForPreparation ? waitTimeoutMs : COMPONENT_RECOVERY_TRY_TIMEOUT_MS,
+			purpose: COMPONENT_RECOVERY_LOCK_PURPOSE,
+			renewTimeoutWhileOwnerAlive: waitForPreparation,
+			onWait: (owner) => {
+				logger.info(
+					`Waiting to settle component deployment state for ${componentName}` +
+						(owner ? ` held by process ${owner.pid}, thread ${owner.threadId}` : '')
+				);
+			},
+			isOwnerAlive: (owner) => owner.pid !== process.pid || isThreadRunning(owner.threadId),
 		}
+	);
+}
+
+export async function retireComponentExtractionStaging(
+	componentDirPath: string,
+	componentName = basename(componentDirPath),
+	componentLogger: Logger = logger
+): Promise<void> {
+	const asideStagingDir = extractionStagingDirectory(componentDirPath);
+	let entries;
+	try {
+		await lstat(asideStagingDir);
+		await ensureExtractionStagingDirectory(asideStagingDir);
+		entries = await readdir(asideStagingDir, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
 		throw error;
 	}
-	// Clean up the original tarball
-	if (shouldDeleteTarball && tarballPath) {
-		await rm(tarballPath, { force: true }).catch((error) =>
-			application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error)
-		);
+	const paths = new Set<string>(entries.map((entry) => join(asideStagingDir, entry.name)));
+	for (const entry of entries) {
+		if (!isExtractionRecoveryRecord(entry) || !entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX)) continue;
+		const markerPath = retiredMarkerForAside(join(asideStagingDir, entry.name));
+		try {
+			await writeFile(markerPath, '', { flag: 'wx', mode: 0o600 });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).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: ExtractionTransaction = {
-		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: Application, asideStagingDir: string): Promise<void> {
+export async function dropComponentDirectory(
+	componentDirPath: string,
+	componentName = basename(componentDirPath),
+	componentLogger: Logger = logger
+): Promise<void> {
+	await retireComponentExtractionStaging(componentDirPath, componentName, componentLogger);
+	const asideStagingDir = extractionStagingDirectory(componentDirPath);
+	await ensureExtractionStagingDirectory(asideStagingDir);
+	const droppedPath = join(asideStagingDir, `.dropped-${process.pid}-${Date.now()}-${randomUUID()}`);
+	try {
+		await rename(componentDirPath, droppedPath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).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 rm(asideStagingDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+		await pruneDormantBuilds(componentName, await dormantBuildsOf(dirname(componentDirPath), componentName), 0);
 	} catch (error) {
-		logger.trace?.(`Cleanup of previous ${application.name} component directory deferred: ${error.message}`);
+		componentLogger.warn(
+			`Dropped ${componentName} but could not reclaim its dormant staged builds:`,
+			errorForLog(error)
+		);
+	}
+}
+
+async function cleanupExtractionPaths(
+	application: ExtractionContext,
+	asideStagingDir: string,
+	paths: Set<string>
+): Promise<void> {
+	const retiredMarkers: string[] = [];
+	for (const path of paths) {
+		if (basename(path).startsWith(RETIRED_ASIDE_PREFIX)) {
+			retiredMarkers.push(path);
+			continue;
+		}
+		try {
+			await 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 = join(
+			asideStagingDir,
+			`${IN_PROGRESS_ASIDE_PREFIX}${basename(markerPath).slice(RETIRED_ASIDE_PREFIX.length)}`
+		);
+		try {
+			await access(asidePath, constants.F_OK);
+			continue;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') continue;
+		}
+		await rm(markerPath, { force: true }).catch((error) =>
+			application.logger.trace?.(
+				`Cleanup of previous ${application.name} component directory deferred: ${errorMessage(error)}`
+			)
+		);
 	}
+	await rmdir(asideStagingDir).catch((error) => {
+		if (!['ENOENT', 'ENOTEMPTY'].includes((error as NodeJS.ErrnoException).code ?? '')) {
+			application.logger.trace?.(
+				`Cleanup of ${application.name} deploy staging directory deferred: ${errorMessage(error)}`
+			);
+		}
+	});
 }
 
 async function rollbackExtractedDirectory(
-	application: Application,
+	application: ExtractionContext,
 	asideStagingDir: string,
-	asidePath: string | undefined
+	asidePath: string | undefined,
+	transactionPaths: Set<string>,
+	retainReplacement: boolean
 ): Promise<void> {
-	await mkdir(asideStagingDir, { recursive: true });
-	const retryableRenameCodes = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES', 'EBUSY']);
-	const displaceCurrentDirectory = async () => {
+	await ensureExtractionStagingDirectory(asideStagingDir);
+	const retryableRenameCodes = new Set(['EEXIST', 'ENOTEMPTY', 'ENOTDIR', 'EISDIR', 'EPERM', 'EACCES', 'EBUSY']);
+	const displaceCurrentDirectorySync = (): string | undefined => {
 		const displacedPath = join(asideStagingDir, `.failed-${process.pid}-${Date.now()}-${randomUUID()}`);
+		try {
+			renameSync(application.dirPath, displacedPath);
+			transactionPaths.add(displacedPath);
+			return displacedPath;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+			throw error;
+		}
+	};
+	const displaceCurrentDirectory = async (): Promise<string | undefined> => {
+		const retryDeadline = Date.now() + 5000;
 		let lastError: unknown;
-		for (let attempt = 0; attempt < 100; attempt++) {
+		do {
+			const displacedPath = join(asideStagingDir, `.failed-${process.pid}-${Date.now()}-${randomUUID()}`);
 			try {
 				await rename(application.dirPath, displacedPath);
-				return;
+				transactionPaths.add(displacedPath);
+				return displacedPath;
 			} catch (error) {
 				const code = (error as NodeJS.ErrnoException).code;
-				if (code === 'ENOENT') return;
+				if (code === 'ENOENT') return undefined;
 				if (!retryableRenameCodes.has(code ?? '')) throw error;
 				lastError = error;
 				await delay(10);
 			}
-		}
+		} while (Date.now() < retryDeadline);
 		throw lastError;
 	};
 
-	await displaceCurrentDirectory();
 	if (asidePath) {
-		let restored = false;
+		const asideIsSymbolicLink = (await lstat(asidePath)).isSymbolicLink();
 		let restoreError: unknown;
-		for (let attempt = 0; attempt < 100; attempt++) {
+		let restoreRetryDeadline: number | undefined;
+		let fallbackDisplacedPath: string | undefined;
+		let placeholderIdentity = await identifyRollbackPlaceholder(application.dirPath);
+		const failRestore = async (error: unknown): Promise<never> => {
+			try {
+				await makeRollbackPlaceholderMovable(application.dirPath, placeholderIdentity);
+				if (retainReplacement && fallbackDisplacedPath) {
+					const fallbackRetryDeadline = Date.now() + 5000;
+					let fallbackRestoreError: unknown;
+					do {
+						let writerDisplacedPath: string | undefined;
+						try {
+							writerDisplacedPath = displaceCurrentDirectorySync();
+							placeholderIdentity = undefined;
+							renameSync(fallbackDisplacedPath, application.dirPath);
+							fallbackRestoreError = undefined;
+						} catch (restoreFallbackError) {
+							fallbackRestoreError = restoreFallbackError;
+						}
+						if (writerDisplacedPath) {
+							await rm(writerDisplacedPath, {
+								recursive: true,
+								force: true,
+								maxRetries: 3,
+								retryDelay: 100,
+							});
+							transactionPaths.delete(writerDisplacedPath);
+						}
+						if (
+							fallbackRestoreError &&
+							!retryableRenameCodes.has((fallbackRestoreError as NodeJS.ErrnoException).code ?? '')
+						) {
+							throw fallbackRestoreError;
+						}
+						if (fallbackRestoreError) {
+							await delay(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 lstat(application.dirPath, { bigint: true });
+						if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+							await rm(application.dirPath, {
+								recursive: true,
+								force: true,
+								maxRetries: 3,
+								retryDelay: 100,
+							});
+							placeholderIdentity = undefined;
+						}
+					} catch (placeholderError) {
+						if ((placeholderError as NodeJS.ErrnoException).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 rename(asidePath, application.dirPath);
-				restored = true;
-				break;
+				if (placeholderIdentity) {
+					const current = lstatSync(application.dirPath, { bigint: true });
+					if (current.dev === placeholderIdentity.dev && current.ino === placeholderIdentity.ino) {
+						chmodSync(application.dirPath, 0o700);
+						renameSync(asidePath, application.dirPath);
+					} else {
+						placeholderIdentity = undefined;
+						await rename(asidePath, application.dirPath);
+					}
+				} else {
+					await rename(asidePath, application.dirPath);
+				}
+				transactionPaths.delete(asidePath);
+				await cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+				return;
 			} catch (error) {
 				restoreError = error;
-				if (!retryableRenameCodes.has((error as NodeJS.ErrnoException).code ?? '')) break;
-				await displaceCurrentDirectory();
+				if (!retryableRenameCodes.has((error as NodeJS.ErrnoException).code ?? '')) {
+					return failRestore(error);
+				}
+				let displacedPath: string | undefined;
+				const displacedPlaceholderIdentity = placeholderIdentity;
+				try {
+					await makeRollbackPlaceholderMovable(application.dirPath, placeholderIdentity);
+					displacedPath = await displaceCurrentDirectory();
+					placeholderIdentity = undefined;
+					if (displacedPath && displacedPlaceholderIdentity) {
+						try {
+							const displaced = await lstat(displacedPath, { bigint: true });
+							if (
+								displaced.dev === displacedPlaceholderIdentity.dev &&
+								displaced.ino === displacedPlaceholderIdentity.ino
+							) {
+								const displacedPlaceholderPath = displacedPath;
+								displacedPath = undefined;
+								await 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 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 = join(
+						asideStagingDir,
+						`.rollback-placeholder-${process.pid}-${Date.now()}-${randomUUID()}`
+					);
+					try {
+						if (asideIsSymbolicLink) {
+							await writeFile(stagedPlaceholderPath, '', { flag: 'wx', mode: 0o000 });
+						} else {
+							await mkdir(stagedPlaceholderPath, { mode: 0o300 });
+						}
+						transactionPaths.add(stagedPlaceholderPath);
+						let placeholderPlacementError: unknown;
+						do {
+							let writerDisplacedPath: string | undefined;
+							try {
+								writerDisplacedPath = displaceCurrentDirectorySync();
+								renameSync(stagedPlaceholderPath, application.dirPath);
+								if (!asideIsSymbolicLink) {
+									try {
+										chmodSync(application.dirPath, 0o100);
+									} catch (chmodError) {
+										try {
+											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 rm(writerDisplacedPath, {
+									recursive: true,
+									force: true,
+									maxRetries: 3,
+									retryDelay: 100,
+								});
+								transactionPaths.delete(writerDisplacedPath);
+							}
+							if (
+								placeholderPlacementError &&
+								!retryableRenameCodes.has((placeholderPlacementError as NodeJS.ErrnoException).code ?? '')
+							) {
+								throw placeholderPlacementError;
+							}
+							if (!placeholderPlacementError) break;
+							await delay(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 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 delay(10);
 			}
+		} while (restoreRetryDeadline !== undefined && Date.now() < restoreRetryDeadline);
+		return failRestore(restoreError);
+	}
+	try {
+		await displaceCurrentDirectory();
+	} catch (displaceError) {
+		try {
+			await 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 cleanupExtractionPaths(application, asideStagingDir, transactionPaths);
+}
 
-	await cleanupExtractionStaging(application, asideStagingDir);
+/**
+ * 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.
+ */
+export function packageManagerInstallArguments(
+	packageManagerName: string,
+	allowInstallScripts: boolean,
+	force = false
+): string[] {
+	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.
  */
-export async function installApplication(application: Application) {
+export async function installApplication(application: Application, buildDirPath = application.dirPath) {
 	let packageJSON: any;
 	try {
-		packageJSON = JSON.parse(await readFile(join(application.dirPath, 'package.json'), 'utf8'));
+		packageJSON = JSON.parse(await readFile(join(buildDirPath, 'package.json'), 'utf8'));
 	} catch (err) {
 		if (err.code !== 'ENOENT') throw err;
 		// If no package.json, nothing to install
@@ -877,7 +3845,7 @@ export async function installApplication(application: Application) {
 	}
 	try {
 		// Does node_modules exist?
-		await access(join(application.dirPath, 'node_modules'), constants.F_OK);
+		await access(join(buildDirPath, 'node_modules'), constants.F_OK);
 		application.logger.info(
 			`Application ${application.name} already has node_modules; skipping install and treating the runtime as opaque for redeploy comparison`
 		);
@@ -888,8 +3856,15 @@ export async function installApplication(application: Application) {
 		// 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: 'stdout' | 'stderr', line: string) => application.onInstallLine!(command, stream, line)
@@ -898,10 +3873,12 @@ export async function installApplication(application: Application) {
 			application.name,
 			command,
 			args,
-			application.dirPath,
+			buildDirPath,
 			application.install?.timeout,
 			customOnLine,
-			application.npmUserconfigPath
+			application.npmUserconfigPath,
+			undefined,
+			!allowInstallScripts
 		);
 		// if it succeeds, return
 		if (code === 0) {
@@ -921,9 +3898,21 @@ export async function installApplication(application: Application) {
 		);
 	}
 
-	// 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
@@ -959,8 +3948,8 @@ export async function installApplication(application: Application) {
 		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,
+			packageManagerInstallArguments(packageManager.name, allowInstallScripts),
+			buildDirPath,
 			application.install?.timeout,
 			pmOnLine,
 			application.npmUserconfigPath
@@ -1008,9 +3997,13 @@ export async function installApplication(application: Application) {
 	}
 
 	// 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: 'stdout' | 'stderr', line: string) => application.onInstallLine!('npm', stream, line)
 		: undefined;
@@ -1018,7 +4011,7 @@ export async function installApplication(application: Application) {
 		application.name,
 		(application.packageManagerPrefix ? application.packageManagerPrefix + ' ' : '') + 'npm',
 		npmInstallArgs,
-		application.dirPath,
+		buildDirPath,
 		application.install?.timeout,
 		npmOnLine,
 		application.npmUserconfigPath
@@ -1067,6 +4060,7 @@ export class Application {
 	name: string;
 	payload?: Buffer | string | Readable;
 	packageIdentifier?: string;
+	readonly packLocalDirectory: boolean;
 	install?: { command?: string; timeout?: number; allowInstallScripts?: boolean };
 	onInstallLine?: OnInstallLine;
 	dirPath: string;
@@ -1092,6 +4086,7 @@ export class Application {
 	constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions) {
 		this.name = name;
 		this.payload = payload;
+		this.packLocalDirectory = shouldPackLocalDirectory(packageIdentifier);
 		this.packageIdentifier = packageIdentifier && derivePackageIdentifier(packageIdentifier);
 		this.install = install;
 		this.onInstallLine = onInstallLine;
@@ -1202,7 +4197,12 @@ export class 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: string) {
+	return isAbsolute(packageIdentifier) || win32.isAbsolute(packageIdentifier);
+}
+
 export function derivePackageIdentifier(packageIdentifier: string) {
+	if (isBareAbsolutePackagePath(packageIdentifier)) return `file:${packageIdentifier}`;
 	if (packageIdentifier.includes(':')) {
 		return packageIdentifier;
 	}
@@ -1216,6 +4216,10 @@ export function derivePackageIdentifier(packageIdentifier: string) {
 	return `github:${packageIdentifier}`;
 }
 
+export function shouldPackLocalDirectory(packageIdentifier: string | undefined, platform = process.platform) {
+	return platform === 'win32' && !!packageIdentifier && isBareAbsolutePackagePath(packageIdentifier);
+}
+
 /**
  * Extract and install the specified application.
  *
@@ -1232,49 +4236,147 @@ export function derivePackageIdentifier(packageIdentifier: string) {
  * @param application The application to prepare.
  * @returns A promise that resolves when all preparation steps complete.
  */
-export async function prepareApplication(application: Application) {
-	const deploymentId = await broadcastDeployStart(application.name);
+export type PrepareApplicationOptions = {
+	beforePrepare?: () => Promise<void>;
+	/**
+	 * Runs against the built candidate while the live version is still serving, and BEFORE the swap. A
+	 * throw here means the candidate never goes live — which is the whole difference from the previous
+	 * behavior, where the swap committed first and a load failure was reported over an already-live
+	 * broken release.
+	 */
+	validateCandidate?: (candidateDirPath: string) => Promise<void>;
+	/**
+	 * Names `.deploy-staging/<artifactId>`, and is not the deploy-lifecycle token: that token de-duplicates
+	 * overlapping deploys of one component and is released by the first matching end, so two activations of
+	 * one artifact sharing it would resume watchers while the second is still swapping. Defaults to the
+	 * lifecycle token, which is unique per invocation.
+	 */
+	artifactId?: string;
+	/**
+	 * `deploy` builds, certifies and activates. `stage` builds and certifies, then stops, leaving an
+	 * artifact a later `activate` can address by `artifactId`. `activate` verifies an existing artifact
+	 * and swaps it in, doing no resolution, no install and no network work at all.
+	 */
+	mode?: 'deploy' | 'stage' | 'activate';
+	/**
+	 * `stage` only: the build's declared intent, recorded with the artifact for whoever activates it.
+	 * A callback rather than a value because `beforePrepare` is what determines it, and that runs after
+	 * these options have been constructed.
+	 */
+	describeArtifact?: () => { rootConfig: Record<string, unknown> | null; isolated: boolean };
+	/**
+	 * `activate` only: publish the artifact's recorded root-config entry, immediately before the swap. May
+	 * return an undo, run if the activation then fails before it commits — otherwise a failed activation
+	 * leaves config naming a release that is not live, which the next boot install would resolve and build
+	 * from scratch over a component whose certified artifact is sitting beside it.
+	 */
+	publishRootConfig?: (entry: Record<string, unknown>) => Promise<(() => Promise<void>) | void>;
+	/** `activate` only: admit the artifact's isolation intent under the preparation lock, before the swap. */
+	admitIsolation?: (descriptor: ArtifactDescriptor) => Promise<void>;
+};
+
+export async function prepareApplication(application: Application, options: PrepareApplicationOptions = {}) {
+	const lifecycleToken = await broadcastDeployStart(application.name);
+	const mode = options.mode ?? 'deploy';
+	const artifactId = options.artifactId ?? lifecycleToken;
 	try {
 		const commandTimeoutMs = application.install?.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
 		await withComponentPreparationLock(
 			application.dirPath,
 			async () => {
+				await options.beforePrepare?.();
+				const asideStagingDir = extractionStagingDirectory(application.dirPath);
+				let recoveryPending = true;
+				try {
+					await lstat(asideStagingDir);
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).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(dirname(application.dirPath), application.name, artifactId);
+				if (recoveryPending) {
+					await ensureExtractionStagingDirectory(asideStagingDir);
+					await recoverOrCleanupStaleExtractionPaths(application, asideStagingDir);
+				}
 				const previousPackageMetadata = await readInstalledPackageMetadata(application.dirPath);
-				let extraction: ExtractionTransaction | undefined;
+				// 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 lstat(application.dirPath).then(
+					() => true,
+					(error) => {
+						if ((error as NodeJS.ErrnoException).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: string;
 					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();
-					} catch (rollbackError) {
-						throw new AggregateError(
-							[error, rollbackError],
-							`Failed to prepare ${application.name} and restore its previous component directory`
-						);
+						// 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 (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();
 				}
@@ -1301,10 +4403,84 @@ export async function prepareApplication(application: Application) {
 			}
 		);
 	} finally {
-		broadcastDeployEnd(application.name, deploymentId);
+		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: Application,
+	artifactId: string,
+	previousPackageMetadata: InstalledPackageMetadata,
+	options: PrepareApplicationOptions
+): Promise<void> {
+	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: string, statusCode: number) =>
+		new ClientError(`Cannot deploy ${application.name} from deployment ${artifactId}: ${why}`, statusCode);
+	const missing = (why: string) => refuse(why, 404);
+	const unusable = (why: string) => 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(join(deploymentDirPath, CANDIDATE_COMPLETE_MARKER)))) {
+		throw unusable('its build never completed');
+	}
+	if (await presentOrAbsent(join(deploymentDirPath, UNSETTLED_MARKER))) {
+		throw unusable('recovery could not settle it, so it is not safe to activate');
+	}
+	if (await presentOrAbsent(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.
  *
@@ -1629,19 +4805,6 @@ export function buildNpmrcContent(registryCredentials: ResolvedRegistryCredentia
 	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()`.
@@ -1683,9 +4846,20 @@ function createLineSplitter(onLine: (line: string) => void): {
 }
 
 /**
- * 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.
  */
 export async function nonInteractiveSpawn(
 	applicationName: string,
@@ -1695,7 +4869,8 @@ export async function nonInteractiveSpawn(
 	timeoutMs: number = DEFAULT_COMMAND_TIMEOUT_MS,
 	onLine?: (stream: 'stdout' | 'stderr', line: string) => void,
 	npmUserconfigPath?: string,
-	gitCredentialEnv?: Record<string, string>
+	gitCredentialEnv?: Record<string, string>,
+	ignoreNpmScripts = false
 ): Promise<{ stdout: string; stderr: string; code: number }> {
 	const gitSSH = await materializeGitSSH();
 	try {
@@ -1708,7 +4883,8 @@ export async function nonInteractiveSpawn(
 			onLine,
 			npmUserconfigPath,
 			gitSSH?.command,
-			gitCredentialEnv
+			gitCredentialEnv,
+			ignoreNpmScripts
 		);
 	} finally {
 		await gitSSH?.cleanup();
@@ -1724,7 +4900,8 @@ function spawnWithEnv(
 	onLine: ((stream: 'stdout' | 'stderr', line: string) => void) | undefined,
 	npmUserconfigPath: string | undefined,
 	gitSSHCommand: string | undefined,
-	gitCredentialEnv: Record<string, string> | undefined
+	gitCredentialEnv: Record<string, string> | undefined,
+	ignoreNpmScripts: boolean
 ): Promise<{ stdout: string; stderr: string; code: number }> {
 	return new Promise((resolve, reject) => {
 		logger
@@ -1760,10 +4937,17 @@ function spawnWithEnv(
 			}
 			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 = logger.loggerWithTag(`${applicationName}:spawn:${command}`);
 
 		const childProcess = spawn(command, args, {
 			shell: true,
@@ -1857,7 +5041,22 @@ function spawnWithEnv(
 			}
 		});
 
-		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
@@ -1878,6 +5077,7 @@ function spawnWithEnv(
 					}
 					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
@@ -1889,7 +5089,6 @@ function spawnWithEnv(
 			if (stderr) {
 				printStd(applicationName, command, stderr, 'stderr');
 			}
-			logger.loggerWithTag(`${applicationName}:spawn:${command}`).debug?.(`Process exited with code ${code}`);
 			if (didTimeout || didSettle) return;
 			didSettle = true;
 			resolve({
@@ -1914,12 +5113,7 @@ class CommandTimeoutError extends Error {
 }
 
 function processGroupIsAlive(processGroupId: number): boolean {
-	try {
-		process.kill(-processGroupId, 0);
-		return true;
-	} catch (error: any) {
-		return error.code === 'EPERM';
-	}
+	return isProcessGroupAlive(processGroupId);
 }
 
 async function waitForProcessGroupExit(processGroupId: number, timeoutMs: number): Promise<boolean> {