@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.2

package/dist/components/Application.js

@@ -38,6 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Application = exports.GIT_CREDENTIAL_HELPER_PATH = exports.DEPLOY_STAGING_DIR = exports.ASIDE_STAGING_DIR = exports.InvalidCredentialEntryError = exports.InvalidBranchedDatabasesError = exports.InvalidCredentialsPropertyError = exports.InvalidInstallTimeoutError = exports.InvalidInstallCommandError = exports.InvalidInstallPropertyError = exports.InvalidPackageIdentifierError = void 0;
 exports.assertApplicationConfig = assertApplicationConfig;
+exports.assertIsolationConfig = assertIsolationConfig;
 exports.assertBranchedDatabases = assertBranchedDatabases;
 exports.isSSHAuthFailure = isSSHAuthFailure;
 exports.parseGitReference = parseGitReference;
@@ -47,11 +48,15 @@ exports.readInstalledPackageMetadata = readInstalledPackageMetadata;
 exports.installedPackageMetadataEqual = installedPackageMetadataEqual;
 exports.installedRuntimeChanged = installedRuntimeChanged;
 exports.extractApplication = extractApplication;
+exports.getStagingRetentionMaxCount = getStagingRetentionMaxCount;
+exports.pruneDormantBuilds = pruneDormantBuilds;
 exports.candidateApplicationPath = candidateApplicationPath;
 exports.makeRollbackPlaceholderMovable = makeRollbackPlaceholderMovable;
+exports.publishClaimOwnership = publishClaimOwnership;
 exports.splitAttributionOwners = splitAttributionOwners;
 exports.unsettleableComponentsFromDisk = unsettleableComponentsFromDisk;
 exports.recoverInterruptedActivations = recoverInterruptedActivations;
+exports.reconcileDormantBuilds = reconcileDormantBuilds;
 exports.markCandidateComplete = markCandidateComplete;
 exports.activateCandidateApplication = activateCandidateApplication;
 exports.buildCandidateApplication = buildCandidateApplication;
@@ -76,6 +81,7 @@ exports.terminateProcessTree = terminateProcessTree;
 exports.getEnvBuiltInComponents = getEnvBuiltInComponents;
 const configUtils_ts_1 = require("../config/configUtils.js");
 const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const hdbError_ts_1 = require("../utility/errors/hdbError.js");
 const harper_logger_ts_1 = __importStar(require("../utility/logging/harper_logger.js"));
 const deployLifecycle_ts_1 = require("./deployLifecycle.js");
 const componentPreparationLock_ts_1 = require("./componentPreparationLock.js");
@@ -195,6 +201,12 @@ function assertApplicationConfig(applicationName, applicationConfig) {
         }
     }
     assertBranchedDatabases(applicationName, applicationConfig.branchedDatabases);
+    assertIsolationConfig(applicationName, applicationConfig.isolated);
+}
+function assertIsolationConfig(applicationName, isolated) {
+    if (isolated !== undefined && typeof isolated !== 'boolean') {
+        throw new TypeError(`Invalid 'isolated' for application ${applicationName}: expected a boolean, got ${typeof isolated}`);
+    }
 }
 /**
  * A branch that cannot be honoured fails the application's load: falling back would hand it the
@@ -909,7 +921,120 @@ const CANDIDATE_COMPONENT_FILE = '.component';
 // well-formed. Workers cannot infer that case: a well-formed journal is indistinguishable from one belonging
 // to a deploy in flight, so without a record they would treat an unsettled component as healthy and load it.
 const UNSETTLED_MARKER = '.unsettled';
+// Everything the build decided that a later activation cannot re-derive: the root-config entry to publish,
+// whether the installation is opaque to metadata comparison, and the isolation intent that was admitted.
+// Written before `.complete`, so the marker vouches for it. An OPTIONAL record would not do: it could not
+// distinguish a payload build, which owns no root config, from a package build whose record was lost.
+const CANDIDATE_ARTIFACT_FILE = '.artifact.json';
 const ACTIVATION_JOURNAL_VERSION = 1;
+const ARTIFACT_DESCRIPTOR_VERSION = 1;
+const DEFAULT_STAGING_RETENTION_MAX_COUNT = 5;
+/** `deployment_stagingRetention_maxCount`; 0 keeps none. Only a number or numeric string counts, so `true`/`[]`/blank cannot become "keep nothing". */
+function getStagingRetentionMaxCount() {
+    const configured = (0, configUtils_ts_1.getConfigValue)(hdbTerms_ts_1.CONFIG_PARAMS.DEPLOYMENT_STAGINGRETENTION_MAXCOUNT);
+    if (typeof configured !== 'number' && typeof configured !== 'string')
+        return DEFAULT_STAGING_RETENTION_MAX_COUNT;
+    if (typeof configured === 'string' && configured.trim() === '')
+        return DEFAULT_STAGING_RETENTION_MAX_COUNT;
+    const parsed = Number(configured);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : DEFAULT_STAGING_RETENTION_MAX_COUNT;
+}
+async function presentOrAbsent(path) {
+    return (0, promises_1.lstat)(path).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+}
+/**
+ * A dormant build: complete, tree present, no journal. Activation writes `.complete` moments before its
+ * journal under the owner's preparation lock, so only a read under that lock is a verdict. A stale
+ * `.unsettled` makes it residue instead, since only removing the directory clears that marker for workers.
+ * Only ENOENT is absence; any other read error propagates so the caller preserves the entry.
+ */
+async function dormantBuildAt(deploymentDirPath, owner) {
+    const complete = await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER));
+    if (!complete)
+        return undefined;
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER)))
+        return undefined;
+    const tree = await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, owner));
+    if (!tree || !(tree.isDirectory() || tree.isSymbolicLink()))
+        return undefined;
+    return { deploymentDirPath, deploymentId: (0, node_path_1.basename)(deploymentDirPath), completedAt: complete.mtimeMs };
+}
+/**
+ * Remove the oldest dormant builds beyond `maxCount`. The caller must hold the component's preparation lock;
+ * every catalogued build is re-derived under it before the kept set is chosen, so a catalog read unlocked
+ * cannot hold or miss a slot. Never throws: a failure must neither fail a component closed nor replace a
+ * deploy's own error.
+ *
+ * `pinnedDeploymentId` is never evicted. A delayed activation runs this preamble under the same lock it is
+ * about to activate under, so without the pin retention would delete the artifact the request named —
+ * immediately, when the knob is `0`. The pin is applied after the kept set is chosen, so a pinned build in
+ * the eviction tail leaves `maxCount + 1` on disk for the life of the request; the next preamble that does
+ * not pin it brings the count back down.
+ */
+async function pruneDormantBuilds(componentName, builds, maxCount, pinnedDeploymentId) {
+    const current = [];
+    for (const build of builds) {
+        try {
+            const fresh = await dormantBuildAt(build.deploymentDirPath, componentName);
+            if (fresh && !(await presentOrAbsent((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL))))
+                current.push(fresh);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Leaving deploy staging ${build.deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+    const evictions = current
+        .sort((left, right) => right.completedAt - left.completedAt ||
+        (left.deploymentId < right.deploymentId ? -1 : left.deploymentId > right.deploymentId ? 1 : 0))
+        .slice(Math.max(0, maxCount))
+        .filter((build) => build.deploymentId !== pinnedDeploymentId);
+    for (const build of evictions) {
+        try {
+            await (0, promises_1.rm)(build.deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            harper_logger_ts_1.default.debug?.(`Pruned dormant staged build ${build.deploymentId} of ${componentName} beyond deployment_stagingRetention_maxCount=${maxCount}`);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Could not prune dormant staged build ${build.deploymentDirPath} of ${componentName}; it remains beyond ` +
+                `deployment_stagingRetention_maxCount=${maxCount}:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+}
+/** Every dormant build a component owns; an unreadable directory is left out and logged. */
+async function dormantBuildsOf(componentsRootDirPath, componentName) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    let deployments;
+    try {
+        deployments = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const builds = [];
+    for (const deployment of deployments) {
+        if (!deployment.isDirectory())
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
+        try {
+            if ((await candidateComponentName(deploymentDirPath)) !== componentName)
+                continue;
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL)))
+                continue;
+            const build = await dormantBuildAt(deploymentDirPath, componentName);
+            if (build)
+                builds.push(build);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Leaving deploy staging ${deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+    return builds;
+}
 /**
  * Best-effort fsync of a directory. Best-effort by necessity — Node cannot fsync a directory on Windows —
  * which is why roll-forward requires journal + candidate + complete marker to all be observable: a lost
@@ -953,6 +1078,54 @@ async function syncRenameParents(fromPath, toPath) {
     for (const parent of parents)
         await syncDirectory(parent);
 }
+// Deliberately NOT `EEXIST`/`ENOTEMPTY`/`ENOTDIR`/`EISDIR`: those say the destination exists, which
+// nothing here clears between attempts, so waiting on them would only delay reporting a tree something
+// recreated — the case `settleInterruptedActivation` fails closed rather than guessing.
+// `rollbackExtractedDirectory` does retry them, because its placeholder logic repairs the destination.
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const RENAME_RETRY_BUDGET_MS = 5000;
+const RENAME_RETRY_INITIAL_DELAY_MS = 10;
+const RENAME_RETRY_MAX_DELAY_MS = 500;
+/**
+ * Rename, waiting out a holder that has not let go yet — on Windows a rename is refused outright while
+ * anything still has a handle in the source tree.
+ *
+ * `onBackoff` replaces the sleep between attempts; `deadline` lets a rename it performs share this
+ * call's budget instead of opening its own.
+ */
+async function renameThroughTransientHolder(fromPath, toPath, options = {}) {
+    const deadline = options.deadline ?? performance.now() + RENAME_RETRY_BUDGET_MS;
+    let delayMs = RENAME_RETRY_INITIAL_DELAY_MS;
+    for (let attempts = 1;; attempts++) {
+        try {
+            await (0, promises_1.rename)(fromPath, toPath);
+            if (attempts > 1) {
+                harper_logger_ts_1.default.warn(`Renamed ${fromPath} to ${toPath} only on attempt ${attempts}; something was holding it`);
+            }
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (!TRANSIENT_RENAME_CODES.has(code))
+                throw error;
+            if (performance.now() >= deadline) {
+                // Which side was still there separates a holder on the source from a destination something
+                // recreated, and neither survives on the rethrown error. A failed probe reports its own code:
+                // an `EPERM` reading the destination is itself evidence, and calling it absent would send the
+                // next investigation the wrong way.
+                const state = async (path) => (0, promises_1.lstat)(path).then(() => 'present', (probeError) => probeError?.code ?? 'unreadable');
+                harper_logger_ts_1.default.warn(`Could not rename ${fromPath} to ${toPath}: ${code} after ${attempts} attempts ` +
+                    `(source ${await state(fromPath)}, destination ${await state(toPath)})`);
+                throw error;
+            }
+            if (options.onBackoff)
+                await options.onBackoff(delayMs, deadline);
+            else
+                await (0, promises_3.setTimeout)(delayMs);
+            delayMs = Math.min(delayMs * 2, RENAME_RETRY_MAX_DELAY_MS);
+        }
+    }
+}
 /**
  * Write a control file so its final name NEVER exists with partial contents. Opening the final path with
  * `wx` publishes the directory entry before anything is written, so a crash in between leaves a zero-byte
@@ -988,6 +1161,150 @@ function candidateComponentFilePath(componentDirPath, deploymentId) {
 function activationJournalPath(componentDirPath, deploymentId) {
     return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), ACTIVATION_JOURNAL);
 }
+function candidateArtifactFilePath(componentDirPath, deploymentId) {
+    return (0, node_path_1.join)(candidateDeploymentDirPath(componentDirPath, deploymentId), CANDIDATE_ARTIFACT_FILE);
+}
+/**
+ * Read and fully validate a staged artifact's descriptor. Every field is checked, not just the ones the
+ * caller happens to use: a descriptor is activation input for a build this process did not make, possibly
+ * not even on this node, so a partially-checked one is a way to activate under someone else's intent.
+ * Absence is `undefined`; anything present but unusable throws, because a staged artifact that cannot
+ * describe itself must be refused rather than activated under defaults.
+ */
+async function readArtifactDescriptor(deploymentDirPath, componentName) {
+    const descriptorPath = (0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE);
+    // The artifact the caller named exists and is theirs, but does not describe a build this can activate —
+    // a conflict with what is on disk, not a server fault.
+    const unusable = (message) => new hdbError_ts_1.ClientError(message, 409);
+    const raw = await (0, promises_1.readFile)(descriptorPath, 'utf8').catch((error) => {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw unusable(`Artifact descriptor ${descriptorPath} is not readable JSON: ${errorMessage(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.v !== ARTIFACT_DESCRIPTOR_VERSION) {
+        throw unusable(`Artifact descriptor ${descriptorPath} is version ${parsed?.v}, which this build cannot activate`);
+    }
+    if (!isJoinableComponentName(parsed.component) || parsed.component !== componentName) {
+        throw unusable(`Artifact descriptor ${descriptorPath} names component '${parsed.component}', not '${componentName}'`);
+    }
+    if (typeof parsed.installationIsOpaque !== 'boolean' || typeof parsed.isolated !== 'boolean') {
+        throw unusable(`Artifact descriptor ${descriptorPath} does not record its build's runtime decisions`);
+    }
+    if (parsed.rootConfig !== null && (typeof parsed.rootConfig !== 'object' || Array.isArray(parsed.rootConfig))) {
+        throw unusable(`Artifact descriptor ${descriptorPath} does not record a root-config entry or its absence`);
+    }
+    // Admission reads one field and publication writes the other, so two authorities that disagree would
+    // admit one isolation and then publish the opposite.
+    if (parsed.rootConfig && Boolean(parsed.rootConfig.isolated) !== parsed.isolated) {
+        throw unusable(`Artifact descriptor ${descriptorPath} admits isolated=${parsed.isolated} but publishes ` +
+            `isolated=${Boolean(parsed.rootConfig.isolated)}`);
+    }
+    return parsed;
+}
+const SEPARATORS_IN_LINK_TARGETS = process.platform === 'win32' ? /[\\/]/ : /\//;
+// `node_modules/harper` and `node_modules/harperdb` are links the LOADER owns: it points them at the
+// running install on every non-root component load and repairs them when they are missing or stale. They
+// are outside the artifact by construction and by design, so they are the one external link a staged
+// artifact may carry.
+const LOADER_OWNED_LINKS = new Set(['harper', 'harperdb']);
+/**
+ * Reject a staged artifact that reaches outside itself.
+ *
+ * Certification fsyncs the tree but follows no links, and the post-swap relocation repair deliberately
+ * leaves external targets alone — so a symlink into a directory this artifact does not own is a hole in
+ * "activate exactly the bytes that were certified": the target can be edited, or replaced wholesale,
+ * between the stage and the activation. An immediate deploy is not exposed to this, because certification
+ * and activation happen within one call; the delay is what makes it reachable.
+ *
+ */
+async function assertOwnedArtifactTree(candidateDirPath, componentName, action = 'stage') {
+    // The operator supplied a component that cannot be staged (400); or the artifact they named exists and is
+    // theirs but is no longer what was certified (409). Neither is a server fault, and both reached the
+    // operations handler as a bare 500 until a live run showed what that looks like to a caller.
+    const refuse = (message) => new hdbError_ts_1.ClientError(message, action === 'stage' ? 400 : 409);
+    const ownedRoot = await (0, promises_1.realpath)(candidateDirPath);
+    // The loader repairs the component's OWN `node_modules/harper`, not a copy nested inside a dependency,
+    // so only that one path is exempt. Matching the name at any depth would let `dep/node_modules/harper`
+    // point anywhere and still pass.
+    const loaderOwnedDir = (0, node_path_1.join)(candidateDirPath, 'node_modules');
+    const walk = async (dirPath) => {
+        const entries = await (0, promises_1.readdir)(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = (0, node_path_1.join)(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+                continue;
+            }
+            // Junctions report as symbolic links here, which is what makes this cover Windows.
+            if (!entry.isSymbolicLink())
+                continue;
+            if (LOADER_OWNED_LINKS.has(entry.name) && dirPath === loaderOwnedDir)
+                continue;
+            // An unresolvable link is rejected for the same reason a foreign one is: nothing certified what
+            // it will resolve to by the time somebody activates it.
+            const target = await (0, promises_1.realpath)(entryPath).catch(() => undefined);
+            if (target === undefined || (target !== ownedRoot && !target.startsWith(ownedRoot + node_path_1.sep))) {
+                throw refuse(`Cannot ${action} ${componentName}: ${entryPath} links outside the build to ${target ?? 'a missing target'}, ` +
+                    `so the bytes activated later would not be the bytes this build certified`);
+            }
+            // `repairRelocatedDependencyLinks` re-points links after the swap, but it runs PAST THE COMMIT
+            // POINT and can only warn — it logs and continues on a failed re-point, and skips a whole subtree
+            // on EACCES/EMFILE — so a component could go live holding a link to a path that no longer exists
+            // while the operation reports success. Staging fails closed instead. The cost: npm writes absolute
+            // junctions under `node_modules` on Windows for a `file:`/workspace dependency, so such a component
+            // deploys immediately but cannot be staged until its links are relative.
+            const linkTarget = await (0, promises_1.readlink)(entryPath);
+            if ((0, node_path_1.isAbsolute)(linkTarget)) {
+                throw refuse(`Cannot ${action} ${componentName}: ${entryPath} names its target inside the build by absolute path ` +
+                    `(${linkTarget}), which activation moves. Re-link it relatively — on Windows, npm ` +
+                    `writes absolute junctions for 'file:' and workspace dependencies, so those have to be relative ` +
+                    `before the component can be staged.`);
+            }
+            // Where the link ENDS UP is not enough: a target that leaves the candidate and comes back resolves
+            // inside it today and somewhere else once activation renames the tree, because the same relative
+            // expression is then evaluated from `components/<component>/…`. Counting `..` segments does not
+            // catch it either, since an intermediate symlink (`up -> ..`) reduces depth without spelling it.
+            // So every PREFIX of the walk is resolved, with symlinks followed as the filesystem will follow
+            // them, and each one has to still be inside the candidate.
+            let prefix = (0, node_path_1.dirname)(entryPath);
+            // Only Windows treats a backslash as a separator. On POSIX it is an ordinary filename character, so
+            // splitting on it there turns a link to the single legal entry `..\asset` — which resolves inside
+            // the candidate and keeps resolving there after relocation — into `..` plus `asset`, and refuses a
+            // component that never left its own tree.
+            for (const segment of linkTarget.split(SEPARATORS_IN_LINK_TARGETS)) {
+                if (segment === '' || segment === '.')
+                    continue;
+                prefix = await (0, promises_1.realpath)((0, node_path_1.join)(prefix, segment)).catch(() => (0, node_path_1.join)(prefix, segment));
+                if (prefix !== ownedRoot && !prefix.startsWith(ownedRoot + node_path_1.sep)) {
+                    throw refuse(`Cannot ${action} ${componentName}: ${entryPath} reaches ${prefix} on its way to ${linkTarget}, ` +
+                        `leaving the build — after activation moves the tree that path resolves somewhere else`);
+                }
+            }
+        }
+    };
+    await walk(candidateDirPath);
+}
+/** Record the build's decisions beside the candidate. Called before `.complete`, which vouches for it. */
+async function writeArtifactDescriptor(componentDirPath, deploymentId, descriptor) {
+    try {
+        await writeControlFileDurably(candidateArtifactFilePath(componentDirPath, deploymentId), JSON.stringify(descriptor));
+    }
+    catch (error) {
+        // An existing descriptor belongs to this same artifact — the id is claimed exclusively, so nothing
+        // else can have written one — which makes this a retry of its own stage rather than a conflict.
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
 /**
  * A component name safe to join onto the components root: no separator, no traversal, not dot-prefixed.
  * Applied to EVERY source of the name — the journal and the sidecar — because validating one and trusting
@@ -1037,8 +1354,23 @@ async function readActivationJournal(journalPath) {
     }
     return parsed;
 }
-/** The deployment directory holding one candidate build: `<root>/.deploy-staging/<deploymentId>`. */
+/**
+ * The deployment directory holding one candidate build: `<root>/.deploy-staging/<deploymentId>`.
+ *
+ * The id is asserted here rather than only at the request boundary because every caller funnels through
+ * this one join, and the id is now operator-supplied (`deployment_id`) or replication-supplied
+ * (`_deploymentId`). A traversal-bearing id would otherwise direct both the build and its removal outside
+ * `.deploy-staging`.
+ */
 function candidateDeploymentDirPath(componentDirPath, deploymentId) {
+    if (typeof deploymentId !== 'string' ||
+        deploymentId.length === 0 ||
+        deploymentId !== (0, node_path_1.basename)(deploymentId) ||
+        // `basename` returns these unchanged, so the comparison above admits both.
+        deploymentId === '.' ||
+        deploymentId === '..') {
+        throw new Error(`Deployment id '${deploymentId}' is not a single path segment`);
+    }
     return (0, node_path_1.join)((0, node_path_1.dirname)(componentDirPath), exports.DEPLOY_STAGING_DIR, deploymentId);
 }
 /** Where a candidate build lives: `<root>/.deploy-staging/<deploymentId>/<component>`. */
@@ -1113,6 +1445,92 @@ async function ensureSecureStagingDirectory(stagingDir) {
         await (0, promises_1.chmod)(stagingDir, 0o700).catch((error) => harper_logger_ts_1.default.warn(`Could not restrict component deploy staging permissions for ${stagingDir}:`, (0, harper_logger_ts_1.errorForLog)(error)));
     }
 }
+/**
+ * Claim a deployment directory for this build, EXCLUSIVELY. The id is the public deployment id, which an
+ * operator can repeat and a redelivered replication can repeat for them, so tolerating an existing
+ * directory would let a replayed stage rewrite the bytes under an existing `.complete` and descriptor —
+ * and a crash mid-rebuild would leave a partial tree that still reads as certified.
+ *
+ * The caller holds the component's preparation lock, which is what makes the EEXIST verdicts sound: no
+ * other preparation of THIS component is running, and a directory belonging to another component is not
+ * this lock's to touch.
+ */
+async function claimDeploymentDirectory(deploymentDirPath, componentName) {
+    // Every refusal below is a conflict over an id that already exists, which is the caller's to resolve by
+    // naming a different one — not a server fault, and not the 500 a bare Error reaches the caller as.
+    const taken = (message) => new hdbError_ts_1.ClientError(message, 409);
+    try {
+        await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const owner = await candidateComponentName(deploymentDirPath);
+        if (owner !== undefined && owner !== componentName) {
+            throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} already holds a build of '${owner}'; a deployment id ` +
+                `names one artifact for its lifetime`);
+        }
+        // Ownership has to be POSITIVE to reclaim, and EMPTINESS IS NOT A VERDICT. The sidecar below is
+        // written as part of the claim, so a directory naming nobody is another component between its own
+        // mkdir and that write, and a deploy can hold a nearly empty one for minutes while it resolves and
+        // packs. Nothing on disk separates that from a claim that got no further, and the lock that
+        // serializes it is not this one, so only the exclusive create may conclude the id is free: the
+        // directory can also have been discarded by a failed build between the first mkdir and this read,
+        // and another component can claim it in that same gap.
+        if (owner === undefined) {
+            await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 }).catch((retry) => {
+                if (retry?.code !== 'EEXIST')
+                    throw retry;
+                throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} is already claimed by a build that has not named its ` +
+                    `component yet. If no deploy of any component is in flight, that directory is abandoned and has ` +
+                    `to be removed by hand; deploying again without a deployment_id mints a fresh id`);
+            });
+        }
+        else {
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER))) {
+                throw taken(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} already holds a completed build of '${componentName}'; ` +
+                    `deploy it with deployment_id, or deploy again to build a new one`);
+            }
+            // This component's own preparation lock serializes the claim and nothing certified it, so nothing
+            // is lost by rebuilding over it.
+            await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            await (0, promises_1.mkdir)(deploymentDirPath, { mode: 0o700 });
+        }
+    }
+    const claimed = await (0, promises_1.lstat)(deploymentDirPath);
+    if (!claimed.isDirectory() || claimed.isSymbolicLink()) {
+        throw new Error(`Component deploy staging path is not a directory: ${deploymentDirPath}`);
+    }
+    if (process.platform !== 'win32' && (claimed.mode & 0o777) !== 0o700) {
+        await (0, promises_1.chmod)(deploymentDirPath, 0o700).catch((error) => harper_logger_ts_1.default.warn(`Could not restrict component deploy staging permissions for ${deploymentDirPath}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    }
+    await publishClaimOwnership(deploymentDirPath, componentName);
+}
+/**
+ * Name the component that owns a deployment directory THIS CALL created, and take the directory back if that
+ * cannot be recorded.
+ *
+ * Ownership is published as part of the claim rather than at certification, because resolving and packing can
+ * take minutes and until a tree exists to infer an owner from, a directory answering to nobody is one another
+ * component will take for abandoned. Unattributed is a permanent refusal, though, so a failure here — a full
+ * disk, an EIO on the temp write or its sync — would burn this deployment id for good, every retry refused by
+ * its own wreckage. The removal is scoped to the directory this invocation made, and deliberately not
+ * broadened to one found by EEXIST: that directory may be another claimant's, and removing it is the race the
+ * refusal exists to prevent. Best-effort, because the claim failure is what the caller needs to see.
+ *
+ * `write` is a parameter so the failure is testable without a filesystem that can be made to fail on exactly
+ * this write and nothing else.
+ */
+async function publishClaimOwnership(deploymentDirPath, componentName, write = writeControlFileDurably) {
+    try {
+        await write((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPONENT_FILE), componentName);
+    }
+    catch (error) {
+        await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true }).catch((cleanupError) => harper_logger_ts_1.default.warn(`Could not remove the deployment directory ${deploymentDirPath} after failing to publish its ` +
+            `ownership; the id stays unusable until it is removed:`, (0, harper_logger_ts_1.errorForLog)(cleanupError)));
+        throw error;
+    }
+}
 async function ensureExtractionStagingDirectory(asideStagingDir) {
     for (const stagingDir of [(0, node_path_1.dirname)(asideStagingDir), asideStagingDir]) {
         await ensureSecureStagingDirectory(stagingDir);
@@ -1258,7 +1676,8 @@ async function inProgressAsideRecords(asideStagingDir) {
         .reverse();
 }
 /**
- * Settle journaled activations for ONE component, assuming the caller already holds its preparation lock.
+ * 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
@@ -1266,7 +1685,7 @@ async function inProgressAsideRecords(asideStagingDir) {
  * pass refuses to restore against a surviving journal, but refusing is a stalled component; settling first
  * is what lets the deploy proceed.
  */
-async function settleJournaledActivationsForComponent(componentsRootDirPath, componentName) {
+async function settleStagingForComponent(componentsRootDirPath, componentName, pinnedDeploymentId) {
     const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
     let deployments;
     try {
@@ -1277,6 +1696,7 @@ async function settleJournaledActivationsForComponent(componentsRootDirPath, com
             return;
         throw error;
     }
+    const dormant = [];
     for (const deployment of deployments) {
         if (!deployment.isDirectory())
             continue;
@@ -1307,8 +1727,19 @@ async function settleJournaledActivationsForComponent(componentsRootDirPath, com
         // 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 (!journal) {
+            if (ownerUnreadable)
+                continue;
+            try {
+                const build = await dormantBuildAt(deploymentDirPath, componentName);
+                if (build)
+                    dormant.push(build);
+            }
+            catch (error) {
+                harper_logger_ts_1.default.warn(`Leaving staged ${componentName} build ${deploymentDirPath} out of retention; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+            }
             continue;
+        }
         // The journal decides, not the sidecar. Skipping on an unreadable sidecar alone would leave this
         // component's own unsettled activation in place while a new deploy proceeded over it, and an
         // activation interrupted before B1 has no rollback record for the restore gate to catch.
@@ -1316,6 +1747,9 @@ async function settleJournaledActivationsForComponent(componentsRootDirPath, com
             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
@@ -1424,29 +1858,20 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
             return failures;
         throw error;
     }
+    const dormant = new Map();
+    const catalogue = (owner, build) => {
+        const builds = dormant.get(owner);
+        if (builds)
+            builds.push(build);
+        else
+            dormant.set(owner, [build]);
+    };
     for (const deployment of deployments) {
         if (!deployment.isDirectory())
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
-        const fail = async (component, error) => {
-            const failure = error instanceof Error ? error : new Error(String(error));
-            if (!failures.has(component))
-                failures.set(component, failure);
-            harper_logger_ts_1.default.error(`Could not settle the interrupted activation of ${component}:`, (0, harper_logger_ts_1.errorForLog)(failure));
-            // A DEFERRAL is not a verdict, and only verdicts go on disk. A held lock means a live deploy, which
-            // settles its own journal; a marker written here would outlive that deploy and have
-            // `unsettleableComponentsFromDisk` read it as an authoritative "cannot be settled", failing a
-            // healthy component closed on every worker. The failure is already recorded above, so this thread
-            // still defers — it just leaves nothing behind.
-            if (failure instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError)
-                return;
-            // Everything else IS a verdict, recorded so workers reach the same one. An unreadable journal is
-            // self-evident, but a well-formed journal this pass could not settle looks exactly like a deploy
-            // in flight, and a worker would otherwise load the component over state nobody reconciled.
-            // Best-effort: the alternative to a missing marker is today's behavior, not a worse one.
-            await (0, promises_1.writeFile)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), failure.message, { mode: 0o600 }).catch((markerError) => harper_logger_ts_1.default.warn(`Could not record the unsettled activation of ${component}: ${errorMessage(markerError)}`));
-        };
+        const fail = (component, error) => recordUnsettled(failures, component, error, deploymentDirPath);
         let journal;
         try {
             journal = await readActivationJournal(journalPath);
@@ -1507,6 +1932,43 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                     activationToFail = undefined;
                     return;
                 }
+                // Re-classified UNDER the lock: the unlocked read that routed this here can predate the `.complete`
+                // a deploy wrote before dying, and that is a retainable build, not residue.
+                const build = await dormantBuildAt(deploymentDirPath, owner);
+                if (build) {
+                    catalogue(owner, build);
+                    return;
+                }
+                // A DESCRIBED artifact carrying a stale verdict is settled, not residue. `fail()` only ever writes
+                // `.unsettled` beside a journal it keeps, so a marker with no journal says settlement finished
+                // and only the marker's own removal was lost — which is exactly what a crash between a dormant
+                // return's two unlinks leaves, and the barrier that orders them cannot run on Windows. Deleting
+                // here would destroy a build somebody staged deliberately, whose payload may already have been
+                // reclaimed, on the strength of a verdict that no longer applies. Clearing the marker is the
+                // idempotent completion of the settlement that wrote it; an undescribed build stays disposable.
+                if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE))) {
+                    // A fault clearing the marker is not a licence to delete what it is attached to — and not a
+                    // licence to say nothing either. The marker survives, every worker fails the component closed
+                    // on it, and main reporting success is the split where main serves what every worker refuses.
+                    // Failing the component brings main to the workers' verdict instead, the rule the settled tail
+                    // follows, and leaves the artifact for the next pass to clear.
+                    try {
+                        await clearUnsettledVerdict(deploymentDirPath, owner);
+                    }
+                    catch (error) {
+                        activationToFail = owner;
+                        throw error;
+                    }
+                    const settled = await dormantBuildAt(deploymentDirPath, owner);
+                    if (settled) {
+                        harper_logger_ts_1.default.info?.(`Cleared a stale unsettled verdict from the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ` +
+                            `${owner}; its activation was already settled`);
+                        catalogue(owner, settled);
+                        return;
+                    }
+                    // Cleared, and still not a retainable build — an incomplete or treeless staged directory. That
+                    // is residue like any other, so it falls through to the removal below.
+                }
                 // Cleanup, not settlement. There was no activation here — this is most often the residue a
                 // SUCCESSFUL settlement leaves when its own sweep failed — so a sweep that fails again cannot
                 // make anything unsettled, and recording it would refuse a live component on every worker
@@ -1528,6 +1990,22 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                     `ownership cannot be read: ${errorMessage(error)}`);
                 continue;
             }
+            // Catalogued WITHOUT the lock and left alone: a retained build is never removed here, so a per-directory
+            // lock would recur on every pass and contend with sibling threads for a component nothing is deploying.
+            if (owner) {
+                let build;
+                try {
+                    build = await dormantBuildAt(deploymentDirPath, owner);
+                }
+                catch (error) {
+                    harper_logger_ts_1.default.warn(`Leaving deploy staging ${deploymentDirPath} in place; it could not be read:`, (0, harper_logger_ts_1.errorForLog)(error));
+                    continue;
+                }
+                if (build) {
+                    catalogue(owner, build);
+                    continue;
+                }
+            }
             // Scoped to THIS deployment, like the journaled branch below: a lock timeout or an EIO here used to
             // abort the entire scan, leaving every later deployment unsettled and unmarked.
             try {
@@ -1595,6 +2073,109 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
             await fail(journal.component, error);
         }
     }
+    const maxCount = getStagingRetentionMaxCount();
+    for (const [owner, builds] of dormant) {
+        for (const [component, error] of await reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount)) {
+            if (!failures.has(component))
+                failures.set(component, error);
+        }
+    }
+    return failures;
+}
+/**
+ * Record a settlement failure against a component. A lock TIMEOUT is a deferral, not a verdict, and only
+ * verdicts go on disk: a held lock means a live deploy, which settles its own journal, and a marker written
+ * here would outlive it and have `unsettleableComponentsFromDisk` fail a healthy component closed on every
+ * worker. Everything else is written so workers reach the same verdict — a well-formed journal this pass
+ * could not settle looks exactly like a deploy in flight otherwise. Marker write is best-effort.
+ */
+async function recordUnsettled(failures, component, error, deploymentDirPath) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    if (!failures.has(component))
+        failures.set(component, failure);
+    harper_logger_ts_1.default.error(`Could not settle the interrupted activation of ${component}:`, (0, harper_logger_ts_1.errorForLog)(failure));
+    if (failure instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError)
+        return;
+    await (0, promises_1.writeFile)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), failure.message, { mode: 0o600 }).catch((markerError) => harper_logger_ts_1.default.warn(`Could not record the unsettled activation of ${component}: ${errorMessage(markerError)}`));
+}
+/**
+ * Finish one owner's catalogued dormant builds after the scan. The catalog was read without the lock, so a
+ * deploy may have published a journal into one of these directories since — and if it then died mid-swap,
+ * only settlement brings the component back. So: settle any journal that appeared, then bound what is still
+ * dormant. The lock is taken only when there is something to do; a lock a live deploy holds is the same
+ * deferral the residue branch records.
+ */
+async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount) {
+    const failures = new Map();
+    let journaled;
+    for (const build of builds) {
+        // Anything but a clean ENOENT means "read it properly, under the lock".
+        const appeared = await presentOrAbsent((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL)).then((stats) => stats !== undefined, () => true);
+        if (appeared) {
+            journaled = build;
+            break;
+        }
+    }
+    if (!journaled && builds.length <= maxCount)
+        return failures;
+    try {
+        await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, owner), async () => {
+            const stillDormant = [];
+            for (const build of builds) {
+                let journal;
+                try {
+                    journal = await readActivationJournal((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL));
+                }
+                catch (error) {
+                    await recordUnsettled(failures, owner, error, build.deploymentDirPath);
+                    continue;
+                }
+                if (!journal) {
+                    stillDormant.push(build);
+                    continue;
+                }
+                // The lock held here is the SIDECAR owner's, as in the residue branch: a journal naming someone
+                // else is not settled under it, and both names are failed.
+                const splitNames = splitAttributionOwners(journal.component, owner);
+                if (splitNames) {
+                    const split = splitAttributionError(build.deploymentDirPath, journal.component, splitNames[0]);
+                    for (const name of splitNames)
+                        await recordUnsettled(failures, name, split, build.deploymentDirPath);
+                    continue;
+                }
+                try {
+                    await settleInterruptedActivation(componentsRootDirPath, build.deploymentDirPath, journal);
+                }
+                catch (error) {
+                    await recordUnsettled(failures, journal.component, error, build.deploymentDirPath);
+                }
+            }
+            if (stillDormant.length > maxCount)
+                await pruneDormantBuilds(owner, stillDormant, maxCount);
+        }, {
+            purpose: 'activation-recovery',
+            ...RECOVERY_LOCK_WAIT,
+            isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(lockOwner.threadId),
+        });
+    }
+    catch (error) {
+        // With a journal in view this is an activation that could not be settled — recorded exactly as the
+        // scan records one it saw directly (a timeout defers, anything else is a verdict). Without one it is
+        // hygiene that could not run, unless a live deploy holds the lock, which defers as everywhere else.
+        if (journaled) {
+            await recordUnsettled(failures, owner, error, journaled.deploymentDirPath);
+            return failures;
+        }
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (failure instanceof componentPreparationLock_ts_1.ComponentPreparationLockTimeoutError) {
+            if (!failures.has(owner))
+                failures.set(owner, failure);
+            harper_logger_ts_1.default.info?.(`Deferred pruning the dormant staged builds of ${owner}: a deploy holds its lock`);
+        }
+        else {
+            harper_logger_ts_1.default.warn(`Could not prune the dormant staged builds of ${owner}:`, (0, harper_logger_ts_1.errorForLog)(failure));
+        }
+    }
     return failures;
 }
 /**
@@ -1615,6 +2196,25 @@ async function sweepAsideRecords(records, componentName, liveDirPath, asideStagi
         await cleanupExtractionPaths({ name: componentName, dirPath: liveDirPath, logger: harper_logger_ts_1.default }, asideStagingDir, new Set([record, retiredMarkerPath])).catch((error) => harper_logger_ts_1.default.warn(`Settled ${componentName} but could not sweep ${record}:`, (0, harper_logger_ts_1.errorForLog)(error)));
     }
 }
+/**
+ * Clear an earlier failed recovery's verdict once this settlement has decided. Treated as CORRECTNESS, not
+ * cleanup: main would report the component settled and load it while every worker read the stale marker and
+ * failed it closed, so a failure here throws and lets main reach the same verdict. The journal outlives it
+ * either way, so the next start settles again.
+ */
+async function clearUnsettledVerdict(deploymentDirPath, componentName) {
+    try {
+        await (0, promises_1.rm)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), { force: true });
+        // Flushed here, not with whatever follows: the journal's removal must never be the one that survives
+        // a crash alone, or the verdict outlives the only thing that would settle it again.
+        await syncDirectory(deploymentDirPath);
+    }
+    catch (error) {
+        throw new Error(`Could not clear the stale unsettled marker of ${componentName} at ` +
+            `${(0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER)}; the component stays failed closed on every thread ` +
+            `until that file can be removed: ${errorMessage(error)}`, { cause: error });
+    }
+}
 /**
  * One interrupted activation, under the component preparation lock. Ambiguity exists only while the live
  * path is absent, and there the `complete` marker is the roll-forward authority: without it the candidate
@@ -1637,7 +2237,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     const asideRecords = await inProgressAsideRecords(asideStagingDir);
     const rollForward = async () => {
         if (!liveExists)
-            await (0, promises_1.rename)(candidateDirPath, liveDirPath);
+            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
@@ -1652,7 +2252,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     };
     const rollBack = async (restoreFrom) => {
         if (restoreFrom) {
-            await (0, promises_1.rename)(restoreFrom, liveDirPath);
+            await renameThroughTransientHolder(restoreFrom, liveDirPath);
             await syncRenameParents(restoreFrom, liveDirPath);
         }
         for (const record of asideRecords) {
@@ -1705,6 +2305,31 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
                 `it aside, so which tree is current cannot be determined without losing one of them. Remove ` +
                 `whichever of the two is not the release you want once you have determined which that is.`);
         }
+        // A STAGED artifact is not a disposable build. `rollBack()` removes the whole deployment directory,
+        // which is right for an immediate deploy — the candidate came from a payload the operator still has —
+        // but wrong for one somebody staged deliberately and may have had its payload reclaimed. The
+        // descriptor is what tells the two apart, and it is on disk precisely so recovery can. Returning the
+        // artifact to dormant by removing only the journal leaves it exactly as `deployment_id` expects it.
+        if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE))) {
+            // This branch returns early and so reaches none of the settled tail below — which can be careless
+            // about both, because it removes the whole directory afterwards. This one keeps it, so the order
+            // the two unlinks REACH STORAGE decides whether the artifact survives: `.unsettled` with no
+            // journal is a verdict nothing will ever settle and the next retention pass deletes the build on.
+            // Its flush is the barrier between the two unlinks: skipping it would let the journal's removal
+            // persist alone, leaving a verdict nothing will settle again. Throwing is safe here and leaves the
+            // journal, so the next start settles again. Windows cannot fsync a directory, which is why the
+            // residue pass also refuses to read this state as disposable — see DESIGN.md.
+            await clearUnsettledVerdict(deploymentDirPath, journal.component);
+            await (0, promises_1.rm)(journalPath, { force: true });
+            // Nothing may throw past the journal removal, the rule the settled tail follows: the caller
+            // records a failure by writing `.unsettled`, which is the state this branch exists to avoid. An
+            // unflushed removal is the safe direction — a power loss resurrects a journal that settles again.
+            await syncDirectory(deploymentDirPath).catch((error) => harper_logger_ts_1.default.warn(`Returned the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ${journal.component} to dormant but ` +
+                `could not flush that to storage; a power loss could resurrect its activation journal:`, (0, harper_logger_ts_1.errorForLog)(error)));
+            harper_logger_ts_1.default.info?.(`Returned the staged build ${(0, node_path_1.basename)(deploymentDirPath)} of ${journal.component} to dormant after an ` +
+                `activation that never moved its live tree aside`);
+            return;
+        }
         await rollBack();
     }
     else {
@@ -1731,18 +2356,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     // 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.
-    try {
-        await (0, promises_1.rm)((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER), { force: true });
-    }
-    catch (error) {
-        // The tree decision is applied, but the marker still says otherwise and every worker reads it and
-        // fails the component closed. Thrown rather than returned so MAIN reaches that same verdict instead
-        // of reporting the component settled — a split where main serves what every worker refuses is worse
-        // than both refusing. The journal survives, so the next start settles again.
-        throw new Error(`Settled the interrupted activation of ${journal.component} but could not clear its unsettled ` +
-            `marker at ${(0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER)}; the component stays failed closed on ` +
-            `every thread until that file can be removed: ${errorMessage(error)}`, { cause: error });
-    }
+    await clearUnsettledVerdict(deploymentDirPath, journal.component);
     await (0, promises_1.rm)(journalPath, { force: true }).catch((error) => harper_logger_ts_1.default.warn(`Settled ${journal.component} but could not remove its activation journal:`, (0, harper_logger_ts_1.errorForLog)(error)));
     await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => harper_logger_ts_1.default.warn(`Settled ${journal.component} but could not clean up its staging directory:`, (0, harper_logger_ts_1.errorForLog)(error)));
     await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
@@ -1864,17 +2478,37 @@ async function markCandidateComplete(componentDirPath, deploymentId, componentNa
             throw error;
     }
 }
+/**
+ * Make the newly created ancestors of a deployment directory durable, child-first.
+ *
+ * Only a staged artifact needs this. A deploy's own candidate is transient — power loss just abandons a
+ * build nobody was told about — but a stage is ACKNOWLEDGED, and `writeControlFileDurably` flushes only the
+ * control file's immediate parent while `ensureSecureStagingDirectory` flushes none. Without this a stage
+ * can report success before the `.deploy-staging/<id>` entry exists on storage, and the automatic payload
+ * reclaim may already have dropped the tarball it could have been rebuilt from. Best-effort on Windows, like
+ * every other directory sync here.
+ */
+async function syncArtifactAncestors(deploymentDirPath) {
+    const stagingRoot = (0, node_path_1.dirname)(deploymentDirPath);
+    for (const directory of [deploymentDirPath, stagingRoot, (0, node_path_1.dirname)(stagingRoot)]) {
+        await syncDirectory(directory);
+    }
+}
 /**
  * Make a built and validated candidate live, as one compensating transaction over two effects: the live tree
- * moves aside, then the candidate takes its place. Root config is NOT one of them — it is still published
- * before the build, unchanged, and making it transactional is tracked separately (#2315).
+ * 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 `complete` marker and the activation journal are 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.
+ * The candidate must ALREADY be certified: `markCandidateComplete` is the caller's, so a delayed activation
+ * does not re-walk and re-fsync a whole dependency tree it certified when it was built. The activation
+ * journal is still written and fsynced BEFORE the first rename, so a crash anywhere below is recoverable —
+ * see `settleInterruptedActivation` for the state matrix. The second rename is the COMMIT POINT: nothing
+ * after it may compensate, because the live path holds the candidate and renaming the aside back over it
+ * cannot succeed.
  */
-async function activateCandidateApplication(application, deploymentId) {
+async function activateCandidateApplication(application, deploymentId, options = {}) {
     const liveDirPath = application.dirPath;
     const candidateDirPath = candidateApplicationPath(liveDirPath, deploymentId);
     const deploymentDirPath = candidateDeploymentDirPath(liveDirPath, deploymentId);
@@ -1889,64 +2523,166 @@ async function activateCandidateApplication(application, deploymentId) {
     if (!candidateStat || !(candidateStat.isDirectory() || candidateStat.isSymbolicLink())) {
         throw new Error(`Cannot activate ${application.name}: no candidate build at ${candidateDirPath}`);
     }
-    await markCandidateComplete(liveDirPath, deploymentId, application.name);
     const journalPath = activationJournalPath(liveDirPath, deploymentId);
-    try {
-        await writeControlFileDurably(journalPath, JSON.stringify({
-            v: ACTIVATION_JOURNAL_VERSION,
-            component: application.name,
-            candidateId: deploymentId,
-        }));
-    }
-    catch (error) {
-        // An existing journal is a retry of this same activation, not a conflict.
-        if (error.code !== 'EEXIST')
-            throw error;
-    }
-    await ensureExtractionStagingDirectory(asideStagingDir);
-    const liveExists = await (0, promises_1.lstat)(liveDirPath).then(() => true, (error) => {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    });
-    application.isNewComponent = !liveExists;
     // B1 — the live tree moves aside. It stays the rollback source until B4 retires it.
     let asidePath;
     let priorAbsentRecordPath;
-    if (liveExists) {
-        asidePath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
-        await (0, promises_1.rename)(liveDirPath, asidePath);
-    }
-    else {
-        priorAbsentRecordPath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}${PRIOR_ABSENT_RECORD_SUFFIX}`);
-        await (0, promises_1.writeFile)(priorAbsentRecordPath, '', { flag: 'wx', mode: 0o600 });
-    }
+    // 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 (asidePath)
-            await (0, promises_1.rename)(asidePath, liveDirPath);
+        if (liveIsDisplaced) {
+            await renameThroughTransientHolder(asidePath, liveDirPath);
+            liveIsDisplaced = false;
+        }
         else if (priorAbsentRecordPath)
             await (0, promises_1.rm)(priorAbsentRecordPath, { force: true });
-        await syncRenameParents(asidePath ?? priorAbsentRecordPath, liveDirPath);
+        // Nothing was displaced and no record was written, so there is nothing to put back and no rename to
+        // flush — the failure happened before the first effect.
+        if (asidePath || priorAbsentRecordPath) {
+            await syncRenameParents(asidePath ?? priorAbsentRecordPath, liveDirPath);
+        }
+    };
+    /**
+     * Put a compensated candidate back to DORMANT — complete, described, no journal — so it is a retryable
+     * artifact rather than one the next preparation destroys.
+     *
+     * Without this, a failure that leaves the journal in place makes `settleStagingForComponent` read
+     * live-plus-candidate as an activation that never got there and remove the whole deployment directory;
+     * for a first deploy the restored state is live-ABSENT, and it rolls the candidate forward instead,
+     * ahead of the caller's own verification. Both destroy an artifact whose whole purpose is to be
+     * activated again.
+     *
+     * The unlink needs its own barrier: syncing the aside directories persists the rollback record's
+     * disposal, not the journal's, so without this sync a power loss resurrects a journal the operator was
+     * told had been rolled back. Best-effort by necessity — failing here must not replace the activation
+     * failure the caller is reporting — so a failure says explicitly that the artifact is not retryable, and
+     * the surviving journal is exactly what startup recovery settles.
+     */
+    const returnToDormant = async () => {
+        try {
+            await (0, promises_1.rm)(journalPath, { force: true });
+        }
+        catch (error) {
+            application.logger.warn(`Restored ${application.name} after a failed activation, but its staged build ${deploymentId} still ` +
+                `carries an activation journal and is not retryable until recovery settles it:`, error);
+            return;
+        }
+        // The journal is gone in this process, so the artifact is retryable now; what is uncertain is whether
+        // its removal reached storage.
+        await syncDirectory(deploymentDirPath).catch((error) => application.logger.warn(`Restored ${application.name} and returned its staged build ${deploymentId} to a retryable state, but ` +
+            `could not flush that to storage; a power loss could resurrect its activation journal:`, error));
     };
-    // Still BEFORE the commit point, so this is compensable — and must be compensated. 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.
+    /**
+     * One pre-commit failure boundary, with the journal write inside it: every step from there to the commit
+     * rename leaves a journal behind if it only rethrows, and the next settlement then deletes a certified
+     * artifact, or (first deploy, live absent) activates it with nobody asking. Nothing below the commit
+     * rename may enter this catch — see B2.
+     */
+    let pendingEffect = 'record the activation';
+    let undoAfterJournal;
     try {
+        try {
+            await writeControlFileDurably(journalPath, JSON.stringify({
+                v: ACTIVATION_JOURNAL_VERSION,
+                component: application.name,
+                candidateId: deploymentId,
+            }));
+        }
+        catch (error) {
+            // An existing journal is a retry of this same activation, not a conflict.
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        pendingEffect = 'prepare the component staging directory';
+        await ensureExtractionStagingDirectory(asideStagingDir);
+        pendingEffect = 'read the live component directory';
+        const liveExists = await (0, promises_1.lstat)(liveDirPath).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        application.isNewComponent = !liveExists;
+        pendingEffect = 'move the previous version aside';
+        if (liveExists) {
+            asidePath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
+            await renameThroughTransientHolder(liveDirPath, asidePath);
+            liveIsDisplaced = true;
+        }
+        else {
+            priorAbsentRecordPath = (0, node_path_1.join)(asideStagingDir, `${IN_PROGRESS_ASIDE_PREFIX}${Date.now()}-${process.pid}-${(0, node_crypto_1.randomUUID)()}${PRIOR_ABSENT_RECORD_SUFFIX}`);
+            await (0, promises_1.writeFile)(priorAbsentRecordPath, '', { flag: 'wx', mode: 0o600 });
+        }
+        // Letting a storage failure escape here leaves live already moved aside, and the caller reads an
+        // uncompensated throw as an ordinary build failure and discards the candidate, its `.complete` marker
+        // and its journal: the component ends up with no version at all and nothing saying how to get one back.
+        pendingEffect = 'record the displaced component directory';
         await syncRenameParents(liveDirPath, asidePath ?? priorAbsentRecordPath);
+        // Config is published HERE — after B1, before the commit — because this is the only point where the
+        // on-disk state recovery would find rolls FORWARD to the certified artifact: live is displaced, the
+        // candidate is complete, and the rollback record exists. Publishing before B1 (with or without the
+        // journal) leaves live present and the candidate present with no rollback record, which settlement
+        // reads as an activation that never started: it deletes the deployment directory, and the next boot
+        // re-resolves the published package identifier from the registry instead — the substitution this step
+        // exists to prevent.
+        //
+        // A crash in the remaining window — after the roll-forward state exists but before this publish — is
+        // the inverse hazard: `rollForward()` renames the candidate live and publishes nothing, so the
+        // certified artifact serves under the PREVIOUS release's config. That includes its ISOLATION intent,
+        // which is a containment boundary and not just a version string: a component staged to run isolated
+        // comes back non-isolated after an ordinary crash, with nothing in the operation reporting it.
+        // Closing it needs config to be an effect of the journal itself, which is #2315 step 3.
+        pendingEffect = 'publish the root configuration';
+        undoAfterJournal = await options.afterJournal?.();
+        // B2 — the candidate becomes live. THE RENAME IS THE COMMIT POINT: nothing after it may compensate,
+        // because the live path now holds the candidate and renaming the aside back over it cannot succeed. A
+        // compensating step there fails its own rollback and reports a failure for a deploy that is live. It is
+        // the LAST statement in this block for that reason.
+        pendingEffect = 'move the candidate into place';
+        await renameThroughTransientHolder(candidateDirPath, liveDirPath, {
+            // The previous version occupies the live path through the wait rather than the component being
+            // absent for the whole budget: a read of a component file, and any concurrent scan of the
+            // components root, still finds the last committed tree. (Watchers are already paused for the
+            // deploy, so they are not what this protects.) A first-ever deploy has nothing to put back.
+            onBackoff: async (delayMs, deadline) => {
+                if (!liveIsDisplaced)
+                    return (0, promises_3.setTimeout)(delayMs);
+                await renameThroughTransientHolder(asidePath, liveDirPath, { deadline });
+                liveIsDisplaced = false;
+                await syncRenameParents(asidePath, liveDirPath);
+                await (0, promises_3.setTimeout)(delayMs);
+                await renameThroughTransientHolder(liveDirPath, asidePath, { deadline });
+                liveIsDisplaced = true;
+                await syncRenameParents(liveDirPath, asidePath);
+            },
+        });
     }
     catch (error) {
-        await compensate(error, 'record the displaced component directory', restoreLive, application);
-        throw error;
-    }
-    // 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.
-    try {
-        await (0, promises_1.rename)(candidateDirPath, liveDirPath);
-    }
-    catch (error) {
-        await compensate(error, 'move the candidate into place', restoreLive, application);
+        // 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
@@ -2139,15 +2875,20 @@ async function discardCandidate(application, deploymentId) {
  * Failure needs no compensation, which is the whole point: nothing about the live component was modified,
  * so the abandoned candidate is simply removed and the error propagates.
  */
-async function buildCandidateApplication(application, deploymentId) {
+async function buildCandidateApplication(application, deploymentId, options = {}) {
     const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
     const candidateDirPath = candidateApplicationPath(application.dirPath, deploymentId);
     await ensureSecureStagingDirectory((0, node_path_1.dirname)(deploymentDirPath));
-    await ensureSecureStagingDirectory(deploymentDirPath);
+    await claimDeploymentDirectory(deploymentDirPath, application.name);
     try {
         // Replaced, not extracted into: a prior attempt on this id may have left a partial tree.
         await (0, promises_1.rm)(candidateDirPath, { recursive: true, force: true });
         const resolved = await resolveApplicationTarball(application);
+        if (resolved.kind === 'link' && options.rejectLinkSource) {
+            // What the operator asked for, not a server fault: the same component deploys immediately.
+            throw new hdbError_ts_1.ClientError(`Cannot stage ${application.name} from ${application.packageIdentifier}: a 'file:' directory is linked ` +
+                `rather than copied, so the bytes activated later are not the bytes this build certified`);
+        }
         if (resolved.kind === 'link') {
             // A `file:` directory becomes a symlink AT THE CANDIDATE PATH, so it is validated and swapped in
             // like any other candidate instead of appearing at the live path unvalidated.
@@ -2337,6 +3078,13 @@ async function dropComponentDirectory(componentDirPath, componentName = (0, node
             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 pruneDormantBuilds(componentName, await dormantBuildsOf((0, node_path_1.dirname)(componentDirPath), componentName), 0);
+    }
+    catch (error) {
+        componentLogger.warn(`Dropped ${componentName} but could not reclaim its dormant staged builds:`, (0, harper_logger_ts_1.errorForLog)(error));
+    }
 }
 async function cleanupExtractionPaths(application, asideStagingDir, paths) {
     const retiredMarkers = [];
@@ -2692,13 +3440,17 @@ async function installApplication(application, buildDirPath = application.dirPat
             throw err;
         // If node_modules doesn't exist, we need to install dependencies
     }
+    const allowInstallScripts = !!application.install?.allowInstallScripts;
     // If custom install command is specified, run it
     if (application.install?.command) {
+        if (application.install.allowInstallScripts === undefined) {
+            application.logger.warn(`Application ${application.name} uses install_command without install_allow_scripts; package lifecycle scripts are disabled by default for npm and tools that honor npm_config_ignore_scripts, including npm run pre/post hooks. Set install_allow_scripts (or install.allowInstallScripts in root config) to true to opt in`);
+        }
         const [command, ...args] = application.install.command.split(' ');
         const customOnLine = application.onInstallLine
             ? (stream, line) => application.onInstallLine(command, stream, line)
             : undefined;
-        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, command, args, buildDirPath, application.install?.timeout, customOnLine, application.npmUserconfigPath);
+        const { stdout, stderr, code } = await nonInteractiveSpawn(application.name, command, args, buildDirPath, application.install?.timeout, customOnLine, application.npmUserconfigPath, undefined, !allowInstallScripts);
         // if it succeeds, return
         if (code === 0) {
             application.installationIsOpaque = true;
@@ -2713,7 +3465,6 @@ async function installApplication(application, buildDirPath = application.dirPat
         // and throw a descriptive error
         throw new Error(`Failed to install dependencies for ${application.name} using custom install command: ${application.install.command}. Exit code: ${code}`);
     }
-    const allowInstallScripts = !!application.install?.allowInstallScripts;
     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`);
@@ -2975,10 +3726,13 @@ function shouldPackLocalDirectory(packageIdentifier, platform = process.platform
     return platform === 'win32' && !!packageIdentifier && isBareAbsolutePackagePath(packageIdentifier);
 }
 async function prepareApplication(application, options = {}) {
-    const deploymentId = await (0, deployLifecycle_ts_1.broadcastDeployStart)(application.name);
+    const lifecycleToken = await (0, deployLifecycle_ts_1.broadcastDeployStart)(application.name);
+    const mode = options.mode ?? 'deploy';
+    const artifactId = options.artifactId ?? lifecycleToken;
     try {
         const commandTimeoutMs = application.install?.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
         await (0, componentPreparationLock_ts_1.withComponentPreparationLock)(application.dirPath, async () => {
+            await options.beforePrepare?.();
             const asideStagingDir = extractionStagingDirectory(application.dirPath);
             let recoveryPending = true;
             try {
@@ -2991,7 +3745,12 @@ async function prepareApplication(application, options = {}) {
             }
             // 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.
-            await settleJournaledActivationsForComponent((0, node_path_1.dirname)(application.dirPath), application.name);
+            //
+            // The id this request names is pinned against the retention this runs. An activation would
+            // otherwise have its own artifact deleted by its own preamble; and a redelivered stage would
+            // have the artifact evicted out from under the exclusive claim below, which would then rebuild
+            // different bytes under an id that already named some.
+            await settleStagingForComponent((0, node_path_1.dirname)(application.dirPath), application.name, artifactId);
             if (recoveryPending) {
                 await ensureExtractionStagingDirectory(asideStagingDir);
                 await recoverOrCleanupStaleExtractionPaths(application, asideStagingDir);
@@ -3004,6 +3763,10 @@ async function prepareApplication(application, options = {}) {
                     return false;
                 throw error;
             }));
+            if (mode === 'activate') {
+                await activateStagedArtifact(application, artifactId, previousPackageMetadata, options);
+                return;
+            }
             try {
                 // Materialize the per-deploy `.npmrc` before the build so both `npm pack` and `npm install`
                 // authenticate against the private registry; always remove it afterward.
@@ -3014,7 +3777,9 @@ async function prepareApplication(application, options = {}) {
                     // credential is already gone before any install script runs. This finally covers the paths
                     // that fail before it gets there.
                     await application.startGitCredentialSession();
-                    candidateDirPath = await buildCandidateApplication(application, deploymentId);
+                    candidateDirPath = await buildCandidateApplication(application, artifactId, {
+                        rejectLinkSource: mode === 'stage',
+                    });
                 }
                 finally {
                     await application.cleanupGitCredentialSession();
@@ -3026,7 +3791,25 @@ async function prepareApplication(application, options = {}) {
                     if (!application.isNewComponent) {
                         application.packageMetadataChanged = installedRuntimeChanged(previousPackageMetadata, await readInstalledPackageMetadata(candidateDirPath), application.installationIsOpaque);
                     }
-                    await activateCandidateApplication(application, deploymentId);
+                    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
@@ -3038,7 +3821,7 @@ async function prepareApplication(application, options = {}) {
                     // 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, deploymentId);
+                        await discardCandidate(application, artifactId);
                     throw error;
                 }
             }
@@ -3059,9 +3842,71 @@ async function prepareApplication(application, options = {}) {
         });
     }
     finally {
-        (0, deployLifecycle_ts_1.broadcastDeployEnd)(application.name, deploymentId);
+        (0, deployLifecycle_ts_1.broadcastDeployEnd)(application.name, lifecycleToken);
     }
 }
+/**
+ * Swap an already-certified artifact into the live path. Called with the component's preparation lock held
+ * and after the same recovery preamble every build runs, so the state read here is settled.
+ *
+ * Nothing is resolved, fetched or installed: the bytes were certified when they were staged, which is the
+ * whole point of addressing one by id. Verification is therefore the only gate, and it is strict — this is
+ * activation input for a build this process did not make and may not have made on this node.
+ *
+ * A rejection here must NOT discard: the artifact belongs to whoever staged it, a wrong-component request
+ * must not delete another component's build, and a retry needs what a failed attempt left behind.
+ */
+async function activateStagedArtifact(application, artifactId, previousPackageMetadata, options) {
+    const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, artifactId);
+    const candidateDirPath = candidateApplicationPath(application.dirPath, artifactId);
+    // 404 means only one thing — no artifact answers to this id here — so a caller can tell "never existed or
+    // already used" from "present, but not something this can activate", which is every other refusal below
+    // and a 409 like the rest of that family.
+    const refuse = (why, statusCode) => new hdbError_ts_1.ClientError(`Cannot deploy ${application.name} from deployment ${artifactId}: ${why}`, statusCode);
+    const missing = (why) => refuse(why, 404);
+    const unusable = (why) => refuse(why, 409);
+    const owner = await candidateComponentName(deploymentDirPath);
+    if (owner === undefined)
+        throw missing('there is no staged build with that id on this node');
+    if (owner !== application.name)
+        throw unusable(`that staged build belongs to '${owner}'`);
+    if (!(await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER)))) {
+        throw unusable('its build never completed');
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER))) {
+        throw unusable('recovery could not settle it, so it is not safe to activate');
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL))) {
+        throw unusable('an activation of it is unsettled');
+    }
+    const candidateStat = await presentOrAbsent(candidateDirPath);
+    if (!candidateStat || !candidateStat.isDirectory()) {
+        // Unlike an immediate deploy, a symlink is refused: a `file:` directory is linked rather than
+        // copied, so what it points at now is not what was certified. Staging rejects the source for the
+        // same reason; this is the other end of the same rule, for an artifact staged by an older build.
+        throw unusable('its build tree is missing or is a link rather than a copy');
+    }
+    const descriptor = await readArtifactDescriptor(deploymentDirPath, application.name);
+    if (!descriptor)
+        throw unusable('it does not record what its build decided');
+    await options.admitIsolation?.(descriptor);
+    // `.complete` is a durability marker over the bytes, not a seal on them, and every check that made this
+    // artifact safe ran at stage time. The link rule especially cannot be skipped:
+    // `repairRelocatedDependencyLinks` runs past the commit point and can only warn, so a link planted while
+    // the artifact sat dormant would otherwise go live with the operation reporting success.
+    await assertOwnedArtifactTree(candidateDirPath, application.name, 'activate');
+    // Also the activation's `prepare` phase end: the deploy path emits `prepare`/`start` for every mode but
+    // only ever emitted its `done` from here.
+    await options.validateCandidate?.(candidateDirPath);
+    if (!application.isNewComponent) {
+        application.packageMetadataChanged = installedRuntimeChanged(previousPackageMetadata, await readInstalledPackageMetadata(candidateDirPath), descriptor.installationIsOpaque);
+    }
+    await activateCandidateApplication(application, artifactId, {
+        // Returns its own undo, which the swap runs inside its pre-commit boundary — see there for why it
+        // cannot be run out here.
+        afterJournal: descriptor.rootConfig ? () => options.publishRootConfig(descriptor.rootConfig) : undefined,
+    });
+}
 /**
  * Install all applications specified in the root config.
  *
@@ -3399,16 +4244,16 @@ function createLineSplitter(onLine) {
  * @param timeoutMs The timeout for the command in milliseconds. Defaults to DEFAULT_COMMAND_TIMEOUT_MS.
  * @returns A promise that resolves when the command completes.
  */
-async function nonInteractiveSpawn(applicationName, command, args, cwd, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS, onLine, npmUserconfigPath, gitCredentialEnv) {
+async function nonInteractiveSpawn(applicationName, command, args, cwd, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS, onLine, npmUserconfigPath, gitCredentialEnv, ignoreNpmScripts = false) {
     const gitSSH = await materializeGitSSH();
     try {
-        return await spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSH?.command, gitCredentialEnv);
+        return await spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSH?.command, gitCredentialEnv, ignoreNpmScripts);
     }
     finally {
         await gitSSH?.cleanup();
     }
 }
-function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSHCommand, gitCredentialEnv) {
+function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, npmUserconfigPath, gitSSHCommand, gitCredentialEnv, ignoreNpmScripts) {
     return new Promise((resolve, reject) => {
         harper_logger_ts_1.default
             .loggerWithTag(`${applicationName}:spawn:${command}`)
@@ -3441,6 +4286,13 @@ function spawnWithEnv(applicationName, command, args, cwd, timeoutMs, onLine, np
             }
             env.npm_config_userconfig = npmUserconfigPath;
         }
+        if (ignoreNpmScripts) {
+            for (const key of Object.keys(env)) {
+                if (key.toLowerCase() === 'npm_config_ignore_scripts')
+                    delete env[key];
+            }
+            env.npm_config_ignore_scripts = 'true';
+        }
         if (process.platform === 'win32' && command === 'npm') {
             command = 'npm.cmd';
         }