@harperfast/harper 5.3.0-beta.4 → 5.3.0

package/dist/components/Application.js

@@ -95,6 +95,7 @@ const manageThreads_js_1 = require("../server/threads/manageThreads.js");
 const gitCredentialServer_ts_1 = require("./gitCredentialServer.js");
 const secretDecryptor_ts_1 = require("../resources/secretDecryptor.js");
 const envFile_ts_1 = require("../utility/envFile.js");
+const deploymentProvenance_ts_1 = require("./deploymentProvenance.js");
 const node_path_1 = require("node:path");
 const promises_1 = require("node:fs/promises");
 const node_child_process_1 = require("node:child_process");
@@ -951,6 +952,11 @@ const ACTIVATION_JOURNAL_VERSION = 2;
 const LEGACY_ACTIVATION_JOURNAL_VERSION = 1;
 const ARTIFACT_DESCRIPTOR_VERSION = 1;
 const DEFAULT_STAGING_RETENTION_MAX_COUNT = 5;
+// A digest of the component, not its name, follows the uuid in a claim's name: a long name would pass the filename
+// limit.
+const CLAIMING_PREFIX = '.claiming-';
+const CLAIMING_UUID_LENGTH = 36;
+const CLAIM_OWNER_DIGEST_LENGTH = 16;
 /** `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);
@@ -961,6 +967,9 @@ function getStagingRetentionMaxCount() {
     const parsed = Number(configured);
     return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : DEFAULT_STAGING_RETENTION_MAX_COUNT;
 }
+function isDeploymentDirectoryEntry(entry) {
+    return entry.isDirectory() && !entry.name.startsWith('.');
+}
 async function presentOrAbsent(path) {
     return (0, promises_1.lstat)(path).catch((error) => {
         if (error?.code === 'ENOENT')
@@ -991,15 +1000,20 @@ async function dormantBuildAt(deploymentDirPath, owner) {
  * 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.
+ * A `pinned` id 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` — and a settlement's pins keep the releases it just put back. Pins are applied after the kept set is
+ * chosen, so each pinned build in the eviction tail leaves one more than `maxCount` on disk until a pass that does
+ * not pin it.
  */
-async function pruneDormantBuilds(componentName, builds, maxCount, pinnedDeploymentId) {
+async function pruneDormantBuilds(componentName, builds, maxCount, pinned) {
+    const pins = new Set(typeof pinned === 'string' ? [pinned] : (pinned ?? []));
     const current = [];
+    const seen = new Set();
     for (const build of builds) {
+        if (seen.has(build.deploymentDirPath))
+            continue;
+        seen.add(build.deploymentDirPath);
         try {
             const fresh = await dormantBuildAt(build.deploymentDirPath, componentName);
             if (fresh && !(await presentOrAbsent((0, node_path_1.join)(build.deploymentDirPath, ACTIVATION_JOURNAL))))
@@ -1013,7 +1027,7 @@ async function pruneDormantBuilds(componentName, builds, maxCount, pinnedDeploym
         .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);
+        .filter((build) => !pins.has(build.deploymentId));
     for (const build of evictions) {
         try {
             await (0, promises_1.rm)(build.deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
@@ -1039,7 +1053,7 @@ async function dormantBuildsOf(componentsRootDirPath, componentName) {
     }
     const builds = [];
     for (const deployment of deployments) {
-        if (!deployment.isDirectory())
+        if (!isDeploymentDirectoryEntry(deployment))
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         try {
@@ -1327,6 +1341,142 @@ async function writeArtifactDescriptor(componentDirPath, deploymentId, descripto
             throw error;
     }
 }
+async function writeDeploymentProvenance(candidateDirPath, componentName, deploymentId) {
+    const markerPath = (0, node_path_1.join)(candidateDirPath, deploymentProvenance_ts_1.DEPLOYMENT_PROVENANCE_FILE);
+    await (0, promises_1.rm)(markerPath, { recursive: true, force: true });
+    await writeControlFileDurably(markerPath, (0, deploymentProvenance_ts_1.formatDeploymentProvenance)(componentName, deploymentId));
+}
+/**
+ * A link carries no provenance, whatever its target holds. A read that fails propagates rather than reading as
+ * absent.
+ */
+async function readDeploymentProvenance(treePath, componentName) {
+    const tree = await presentOrAbsent(treePath);
+    if (!tree?.isDirectory())
+        return undefined;
+    const raw = await (0, promises_1.readFile)((0, node_path_1.join)(treePath, deploymentProvenance_ts_1.DEPLOYMENT_PROVENANCE_FILE), 'utf8').catch((error) => {
+        if (error?.code === 'ENOENT' || error?.code === 'EISDIR')
+            return undefined;
+        throw error;
+    });
+    return raw === undefined ? undefined : (0, deploymentProvenance_ts_1.parseDeploymentProvenance)(raw, componentName);
+}
+async function isDeploymentRecord(deploymentDirPath, componentName) {
+    if ((await candidateComponentName(deploymentDirPath)) !== componentName)
+        return false;
+    if (!(await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER))))
+        return false;
+    for (const unexpected of [ACTIVATION_JOURNAL, UNSETTLED_MARKER, componentName]) {
+        if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, unexpected)))
+            return false;
+    }
+    try {
+        return (await readArtifactDescriptor(deploymentDirPath, componentName)) !== undefined;
+    }
+    catch (error) {
+        if (error instanceof hdbError_ts_1.ClientError)
+            return false;
+        throw error;
+    }
+}
+/**
+ * "Not live" does not make a record stale: a crash between the commit and the re-home leaves the displaced tree in
+ * `.deploy-aside`, retired or not, and a scan can reach the record before the journal that re-homes into it.
+ */
+async function deploymentRecordIsReferenced(componentsRootDirPath, componentName, deploymentId) {
+    const liveDirPath = (0, node_path_1.join)(componentsRootDirPath, componentName);
+    if ((await readDeploymentProvenance(liveDirPath, componentName)) === deploymentId)
+        return true;
+    const asideStagingDir = extractionStagingDirectory(liveDirPath);
+    const entries = await (0, promises_1.readdir)(asideStagingDir, { withFileTypes: true }).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX))
+            continue;
+        if ((await readDeploymentProvenance((0, node_path_1.join)(asideStagingDir, entry.name), componentName)) === deploymentId) {
+            return true;
+        }
+    }
+    return false;
+}
+async function isReferencedDeploymentRecord(componentsRootDirPath, deploymentDirPath, owner) {
+    for (const expected of [CANDIDATE_COMPLETE_MARKER, CANDIDATE_ARTIFACT_FILE]) {
+        if (!(await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, expected))))
+            return false;
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, owner)))
+        return false;
+    return deploymentRecordIsReferenced(componentsRootDirPath, owner, (0, node_path_1.basename)(deploymentDirPath));
+}
+/** A failed read keeps the directory: a leftover record costs a few bytes, a lost one costs the release. */
+async function keepsDeploymentRecord(deploymentDirPath) {
+    return presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_ARTIFACT_FILE)).then(Boolean, () => true);
+}
+/** Retention orders by `.complete`'s mtime, and a kept release has to outrank stages nobody activated. */
+async function refreshCompletedAt(deploymentDirPath, componentName, deploymentId) {
+    for (let attempt = 1;; attempt++) {
+        const now = new Date();
+        try {
+            await (0, promises_1.utimes)((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER), now, now);
+            return;
+        }
+        catch (error) {
+            if (attempt >= 3) {
+                harper_logger_ts_1.default.warn(`Kept deployment ${deploymentId} of ${componentName}, but retention may evict it ahead of older ` +
+                    `builds: ${errorMessage(error)}`);
+                return;
+            }
+            await (0, promises_3.setTimeout)(100 * attempt);
+        }
+    }
+}
+/**
+ * Only an explicit retention decision deletes a displaced tree: `failed` leaves it for the next preparation to retry.
+ * A failure after the rename propagates, as the aside syncs around it do.
+ */
+async function retainDisplacedRelease(componentsRootDirPath, componentName, displacedTreePath) {
+    const keepNone = getStagingRetentionMaxCount() === 0;
+    let record;
+    try {
+        const deploymentId = await readDeploymentProvenance(displacedTreePath, componentName);
+        if (deploymentId !== undefined) {
+            const recordDirPath = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR, deploymentId);
+            if (await isDeploymentRecord(recordDirPath, componentName))
+                record = { deploymentId, recordDirPath };
+        }
+    }
+    catch (error) {
+        if (keepNone)
+            return { verdict: 'ineligible' };
+        harper_logger_ts_1.default.warn(`Could not tell whether the previous release of ${componentName} at ${displacedTreePath} can be kept; ` +
+            `leaving it for its next deploy:`, (0, harper_logger_ts_1.errorForLog)(error));
+        return { verdict: 'failed' };
+    }
+    if (!record)
+        return { verdict: 'ineligible' };
+    const { deploymentId, recordDirPath } = record;
+    if (keepNone) {
+        // Nothing will ever put the tree back into its record, so the record goes with it.
+        await (0, promises_1.rm)(recordDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => harper_logger_ts_1.default.warn(`Could not remove the record of deployment ${deploymentId} of ${componentName}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+        return { verdict: 'ineligible' };
+    }
+    const keptTreePath = (0, node_path_1.join)(recordDirPath, componentName);
+    try {
+        await renameThroughTransientHolder(displacedTreePath, keptTreePath);
+    }
+    catch (error) {
+        harper_logger_ts_1.default.warn(`Could not keep the previous release of ${componentName} as deployment ${deploymentId}; leaving it for ` +
+            `its next deploy:`, (0, harper_logger_ts_1.errorForLog)(error));
+        return { verdict: 'failed' };
+    }
+    await syncRenameParents(displacedTreePath, keptTreePath);
+    await refreshCompletedAt(recordDirPath, componentName, deploymentId);
+    harper_logger_ts_1.default.trace?.(`Kept the previous release of ${componentName} as dormant deployment ${deploymentId}`);
+    return { verdict: 'kept', deploymentId };
+}
 /**
  * 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
@@ -1491,88 +1641,107 @@ async function ensureSecureStagingDirectory(stagingDir) {
     }
 }
 /**
- * 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.
+ * Exclusive, because an operator can repeat a public id; built aside and renamed onto it, so it never appears
+ * unattributed. The caller's preparation lock is what makes the verdicts on an existing directory sound.
  */
 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);
+    const claimDirPath = (0, node_path_1.join)((0, node_path_1.dirname)(deploymentDirPath), `${CLAIMING_PREFIX}${(0, node_crypto_1.randomUUID)()}-${claimOwnerDigest(componentName)}`);
+    await (0, promises_1.mkdir)(claimDirPath, { mode: 0o700 });
     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`);
-            });
+        const claimed = await (0, promises_1.lstat)(claimDirPath);
+        if (!claimed.isDirectory() || claimed.isSymbolicLink()) {
+            throw new Error(`Component deploy staging path is not a directory: ${claimDirPath}`);
         }
-        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`);
+        if (process.platform !== 'win32' && (claimed.mode & 0o777) !== 0o700) {
+            await (0, promises_1.chmod)(claimDirPath, 0o700).catch((error) => harper_logger_ts_1.default.warn(`Could not restrict component deploy staging permissions for ${claimDirPath}:`, (0, harper_logger_ts_1.errorForLog)(error)));
+        }
+        await publishClaimOwnership(claimDirPath, componentName);
+        for (let attempt = 1;; attempt++) {
+            // Checked first: Windows refuses a rename onto an existing directory with a transient holder's EPERM.
+            if (!(await presentOrAbsent(deploymentDirPath))) {
+                try {
+                    await renameThroughTransientHolder(claimDirPath, deploymentDirPath);
+                    return;
+                }
+                catch (error) {
+                    // Only this component's lock can remove the claim, so a vanished source means the rename landed.
+                    if (!(await presentOrAbsent(claimDirPath)))
+                        return;
+                    if (!(await presentOrAbsent(deploymentDirPath)))
+                        throw error;
+                }
             }
-            // 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 });
+            if (attempt >= MAX_CLAIM_ATTEMPTS) {
+                throw new hdbError_ts_1.ClientError(`Deployment id ${(0, node_path_1.basename)(deploymentDirPath)} was claimed again each time it was freed; deploying ` +
+                    `again without a deployment_id mints a fresh id`, 409);
+            }
+            await makeRoomForClaim(deploymentDirPath, componentName);
         }
     }
-    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}`);
+    finally {
+        // A claim that did not land names no id, so it is nobody else's.
+        await (0, promises_1.rm)(claimDirPath, { recursive: true, force: true }).catch(() => { });
     }
-    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)));
+}
+const MAX_CLAIM_ATTEMPTS = 3;
+/** Every refusal is a conflict the caller resolves by naming another id: a 409, not a server fault. */
+async function makeRoomForClaim(deploymentDirPath, componentName) {
+    const taken = (message) => new hdbError_ts_1.ClientError(message, 409);
+    const deploymentId = (0, node_path_1.basename)(deploymentDirPath);
+    const owner = await candidateComponentName(deploymentDirPath);
+    if (owner !== undefined && owner !== componentName) {
+        throw taken(`Deployment id ${deploymentId} already holds a build of '${owner}'; a deployment id names one artifact for ` +
+            `its lifetime`);
+    }
+    if (owner === undefined) {
+        // Claims appear already attributed, so an EMPTY directory is only ever one a build created before naming it,
+        // abandoned; `rmdir` removes nothing else.
+        try {
+            await (0, promises_1.rmdir)(deploymentDirPath);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                return;
+            if (code !== 'ENOTEMPTY' && code !== 'EEXIST')
+                throw error;
+        }
+        throw taken(`Deployment id ${deploymentId} is held by a directory that names no component. Remove it once you have ` +
+            `determined it holds nothing you need; deploying again without a deployment_id mints a fresh id`);
+    }
+    if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER))) {
+        throw taken(`Deployment id ${deploymentId} already holds a completed build of '${componentName}'; deploy it with ` +
+            `deployment_id, or deploy again to build a new one`);
+    }
+    // Nothing certified it, and this component's lock serializes its claims.
+    await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+}
+function claimOwnerDigest(componentName) {
+    return (0, node_crypto_1.createHash)('sha256').update(componentName).digest('hex').slice(0, CLAIM_OWNER_DIGEST_LENGTH);
+}
+function isClaimOf(entryName, componentName) {
+    return (entryName.startsWith(CLAIMING_PREFIX) &&
+        entryName.slice(CLAIMING_PREFIX.length + CLAIMING_UUID_LENGTH + 1) === claimOwnerDigest(componentName));
+}
+/** The caller holds the component's preparation lock, so none of its claims is in flight. */
+async function sweepAbandonedClaims(stagingRoot, entries, componentName) {
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isClaimOf(entry.name, componentName))
+            continue;
+        await (0, promises_1.rm)((0, node_path_1.join)(stagingRoot, entry.name), { recursive: true, force: true }).catch((error) => harper_logger_ts_1.default.warn(`Could not remove the abandoned deploy claim ${entry.name}:`, (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.
+ * The claim names no id yet, so a failure burns nothing. `write` is a parameter so the failure is testable without a
+ * filesystem that can be made to fail on exactly this write.
  */
-async function publishClaimOwnership(deploymentDirPath, componentName, write = writeControlFileDurably) {
+async function publishClaimOwnership(claimDirPath, componentName, write = writeControlFileDurably) {
     try {
-        await write((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPONENT_FILE), componentName);
+        await write((0, node_path_1.join)(claimDirPath, 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)));
+        await (0, promises_1.rm)(claimDirPath, { recursive: true, force: true }).catch((cleanupError) => harper_logger_ts_1.default.warn(`Could not remove the unfinished deploy claim ${claimDirPath}:`, (0, harper_logger_ts_1.errorForLog)(cleanupError)));
         throw error;
     }
 }
@@ -1632,7 +1801,7 @@ async function journaledDeploymentForComponent(componentsRootDirPath, componentN
         throw error;
     }
     for (const deployment of deployments) {
-        if (!deployment.isDirectory())
+        if (!isDeploymentDirectoryEntry(deployment))
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
@@ -1741,9 +1910,11 @@ async function settleStagingForComponent(componentsRootDirPath, componentName, p
             return;
         throw error;
     }
+    await sweepAbandonedClaims(stagingRoot, deployments, componentName);
     const dormant = [];
+    const kept = [];
     for (const deployment of deployments) {
-        if (!deployment.isDirectory())
+        if (!isDeploymentDirectoryEntry(deployment))
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         // Ownership BEFORE parsing. Reading every journal first meant a truncated journal belonging to another
@@ -1790,11 +1961,27 @@ async function settleStagingForComponent(componentsRootDirPath, componentName, p
         // activation interrupted before B1 has no rollback record for the restore gate to catch.
         if (journal.component !== componentName)
             continue;
-        await settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, journal);
+        kept.push(...(await settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, journal)));
     }
+    await catalogueKeptReleases(stagingRoot, componentName, kept, dormant);
     const maxCount = getStagingRetentionMaxCount();
-    if (dormant.length > maxCount)
-        await pruneDormantBuilds(componentName, dormant, maxCount, pinnedDeploymentId);
+    if (dormant.length > maxCount) {
+        await pruneDormantBuilds(componentName, dormant, maxCount, [
+            ...kept,
+            ...(pinnedDeploymentId ? [pinnedDeploymentId] : []),
+        ]);
+    }
+}
+/** Counted and pinned, or the pass a settlement ran inside can miss what it kept, or evict it after a failed refresh. */
+async function catalogueKeptReleases(stagingRoot, componentName, kept, into) {
+    const present = new Set(into.map((build) => build.deploymentDirPath));
+    for (const deploymentId of kept) {
+        const build = await dormantBuildAt((0, node_path_1.join)(stagingRoot, deploymentId), componentName).catch(() => undefined);
+        if (build && !present.has(build.deploymentDirPath)) {
+            present.add(build.deploymentDirPath);
+            into.push(build);
+        }
+    }
 }
 /**
  * Components that on-disk evidence says were left in a state nobody settled — determined READ-ONLY, so any
@@ -1822,7 +2009,7 @@ async function unsettleableComponentsFromDisk(componentsRootDirPath) {
         throw error;
     }
     for (const deployment of deployments) {
-        if (!deployment.isDirectory())
+        if (!isDeploymentDirectoryEntry(deployment))
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         // Per deployment. `candidateComponentName` propagates every non-ENOENT error now, and this pass runs
@@ -1906,13 +2093,23 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
     const dormant = new Map();
     const catalogue = (owner, build) => {
         const builds = dormant.get(owner);
-        if (builds)
-            builds.push(build);
-        else
+        if (!builds)
             dormant.set(owner, [build]);
+        else if (!builds.some((existing) => existing.deploymentDirPath === build.deploymentDirPath))
+            builds.push(build);
+    };
+    const keptBy = new Map();
+    const keptDuring = async (owner, kept) => {
+        if (kept.length === 0)
+            return;
+        keptBy.set(owner, [...(keptBy.get(owner) ?? []), ...kept]);
+        const builds = [];
+        await catalogueKeptReleases(stagingRoot, owner, kept, builds);
+        for (const build of builds)
+            catalogue(owner, build);
     };
     for (const deployment of deployments) {
-        if (!deployment.isDirectory())
+        if (!isDeploymentDirectoryEntry(deployment))
             continue;
         const deploymentDirPath = (0, node_path_1.join)(stagingRoot, deployment.name);
         const journalPath = (0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL);
@@ -1971,7 +2168,7 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                         throw splitAttributionError(deploymentDirPath, appeared.component, splitNames[0]);
                     }
                     activationToFail = appeared.component;
-                    await settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, appeared);
+                    await keptDuring(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;
@@ -2014,6 +2211,9 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                     // 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.
                 }
+                // Re-derived under the lock too: the release may have been re-homed, or displaced, since the scan.
+                if (await isReferencedDeploymentRecord(componentsRootDirPath, deploymentDirPath, owner))
+                    return;
                 // 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
@@ -2050,6 +2250,18 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                     catalogue(owner, build);
                     continue;
                 }
+                // The record of a release that is live, or displaced and not yet put back, is left alone without the
+                // lock for the same reason. A read that fails leaves it in place: deleting it is the irreversible side.
+                try {
+                    if (!(await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, UNSETTLED_MARKER))) &&
+                        (await isReferencedDeploymentRecord(componentsRootDirPath, deploymentDirPath, owner))) {
+                        continue;
+                    }
+                }
+                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;
+                }
             }
             // 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.
@@ -2107,11 +2319,12 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
                 continue;
             }
             const settling = journal;
-            await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, settling.component), () => settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, settling), {
+            const kept = await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, settling.component), () => settleInterruptedActivation(componentsRootDirPath, deploymentDirPath, settling), {
                 purpose: 'activation-recovery',
                 ...RECOVERY_LOCK_WAIT,
                 isOwnerAlive: (lockOwner) => lockOwner.pid !== process.pid || (0, manageThreads_js_1.isThreadRunning)(lockOwner.threadId),
             });
+            await keptDuring(settling.component, kept);
         }
         catch (error) {
             // The journal named its component, so attribution is exact however the settle failed.
@@ -2120,7 +2333,8 @@ async function recoverInterruptedActivations(componentsRootDirPath) {
     }
     const maxCount = getStagingRetentionMaxCount();
     for (const [owner, builds] of dormant) {
-        for (const [component, error] of await reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount)) {
+        const pinned = keptBy.get(owner) ?? [];
+        for (const [component, error] of await reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount, pinned)) {
             if (!failures.has(component))
                 failures.set(component, error);
         }
@@ -2150,7 +2364,7 @@ async function recordUnsettled(failures, component, error, deploymentDirPath) {
  * 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) {
+async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxCount, pinned = []) {
     const failures = new Map();
     let journaled;
     for (const build of builds) {
@@ -2166,6 +2380,7 @@ async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxC
     try {
         await (0, componentPreparationLock_ts_1.withComponentPreparationLock)((0, node_path_1.join)(componentsRootDirPath, owner), async () => {
             const stillDormant = [];
+            const keptHere = [];
             for (const build of builds) {
                 let journal;
                 try {
@@ -2189,14 +2404,17 @@ async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxC
                     continue;
                 }
                 try {
-                    await settleInterruptedActivation(componentsRootDirPath, build.deploymentDirPath, journal);
+                    const kept = await settleInterruptedActivation(componentsRootDirPath, build.deploymentDirPath, journal);
+                    keptHere.push(...kept);
+                    await catalogueKeptReleases((0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR), owner, kept, stillDormant);
                 }
                 catch (error) {
                     await recordUnsettled(failures, journal.component, error, build.deploymentDirPath);
                 }
             }
-            if (stillDormant.length > maxCount)
-                await pruneDormantBuilds(owner, stillDormant, maxCount);
+            if (stillDormant.length > maxCount) {
+                await pruneDormantBuilds(owner, stillDormant, maxCount, [...pinned, ...keptHere]);
+            }
         }, {
             purpose: 'activation-recovery',
             ...RECOVERY_LOCK_WAIT,
@@ -2229,6 +2447,7 @@ async function reconcileDormantBuilds(componentsRootDirPath, owner, builds, maxC
  * journal prevents. Sweeping the displaced tree only costs disk, so it is logged.
  */
 async function sweepAsideRecords(records, componentName, liveDirPath, asideStagingDir) {
+    const kept = [];
     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
@@ -2236,10 +2455,18 @@ async function sweepAsideRecords(records, componentName, liveDirPath, asideStagi
         // 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);
+        // No prune here: settlement can run inside another request's preamble, whose pin it cannot see. A tree that
+        // could not be kept stays retired in the aside for the legacy pass to retry.
+        const retention = await retainDisplacedRelease((0, node_path_1.dirname)(liveDirPath), componentName, record);
+        if (retention.verdict === 'kept')
+            kept.push(retention.deploymentId);
+        if (retention.verdict === 'failed')
+            continue;
         // Sweeping the displaced tree is hygiene: it bounds disk, and a failure costs space rather than
         // correctness, so it is logged. The retired marker above already makes the record non-authoritative.
         await cleanupExtractionPaths({ name: componentName, dirPath: liveDirPath, logger: harper_logger_ts_1.default }, asideStagingDir, new Set([record, retiredMarkerPath])).catch((error) => harper_logger_ts_1.default.warn(`Settled ${componentName} but could not sweep ${record}:`, (0, harper_logger_ts_1.errorForLog)(error)));
     }
+    return kept;
 }
 /**
  * Clear an earlier failed recovery's verdict once this settlement has decided. Treated as CORRECTNESS, not
@@ -2280,7 +2507,10 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     const candidateExists = await exists(candidateDirPath);
     const candidateComplete = await exists((0, node_path_1.join)(deploymentDirPath, CANDIDATE_COMPLETE_MARKER));
     const asideRecords = await inProgressAsideRecords(asideStagingDir);
+    let rolledForward = false;
+    let kept = [];
     const rollForward = async () => {
+        rolledForward = true;
         if (!liveExists)
             await renameThroughTransientHolder(candidateDirPath, liveDirPath);
         // Unconditional, not only when THIS pass performed the rename: a crash after normal activation
@@ -2296,7 +2526,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
         // 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);
+        kept = await sweepAsideRecords(asideRecords, journal.component, liveDirPath, asideStagingDir);
     };
     const rollBack = async (restoreFrom) => {
         if (restoreFrom) {
@@ -2376,7 +2606,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
                 `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;
+            return kept;
         }
         await rollBack();
     }
@@ -2397,7 +2627,7 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     catch (error) {
         harper_logger_ts_1.default.warn(`Settled the interrupted activation of ${journal.component} but could not flush its rollback record; ` +
             `leaving the journal for the next start: ${errorMessage(error)}`);
-        return;
+        return kept;
     }
     // 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.
@@ -2406,8 +2636,11 @@ async function settleInterruptedActivation(componentsRootDirPath, deploymentDirP
     // the stale marker and failed it closed.
     await clearUnsettledVerdict(deploymentDirPath, journal.component);
     await (0, promises_1.rm)(journalPath, { force: true }).catch((error) => harper_logger_ts_1.default.warn(`Settled ${journal.component} but could not remove its activation journal:`, (0, harper_logger_ts_1.errorForLog)(error)));
+    if (rolledForward && (await keepsDeploymentRecord(deploymentDirPath)))
+        return kept;
     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(() => { });
+    return kept;
 }
 /** Mark a candidate build+validation complete. Idempotent, so a retried activation is not a failure. */
 /**
@@ -2725,14 +2958,21 @@ async function activateCandidateApplication(application, deploymentId, options =
     }
     const settledRecord = asidePath ?? priorAbsentRecordPath;
     let retired = false;
+    let keptDeploymentId;
     // 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]));
+            // A tree nothing can keep is swept, or the components root grows by a component version per deploy; one
+            // whose keep FAILED stays retired here for a retry.
+            const retention = asidePath
+                ? await retainDisplacedRelease((0, node_path_1.dirname)(liveDirPath), application.name, asidePath)
+                : { verdict: 'ineligible' };
+            if (retention.verdict === 'kept')
+                keptDeploymentId = retention.deploymentId;
+            if (retention.verdict !== 'failed') {
+                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);
@@ -2747,8 +2987,23 @@ async function activateCandidateApplication(application, deploymentId, options =
     // `.in-progress-*` record still names the displaced tree lets the legacy pass restore the old tree.
     if (retired) {
         await (0, promises_1.rm)(journalPath, { force: true }).catch((error) => application.logger.warn(`Deployed ${application.name} but could not remove its activation journal:`, error));
-        await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => application.logger.warn(`Deployed ${application.name} but could not clean up its staging directory:`, error));
-        await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
+        if (!(await keepsDeploymentRecord(deploymentDirPath))) {
+            await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((error) => application.logger.warn(`Deployed ${application.name} but could not clean up its staging directory:`, error));
+            await (0, promises_1.rmdir)((0, node_path_1.dirname)(deploymentDirPath)).catch(() => { });
+        }
+    }
+    // Only here, where the request's own artifact is already live: a prune inside settlement could evict the
+    // artifact a request's preamble pinned. Best-effort, like every prune.
+    if (keptDeploymentId !== undefined) {
+        const maxCount = getStagingRetentionMaxCount();
+        try {
+            const builds = await dormantBuildsOf((0, node_path_1.dirname)(liveDirPath), application.name);
+            if (builds.length > maxCount)
+                await pruneDormantBuilds(application.name, builds, maxCount, keptDeploymentId);
+        }
+        catch (error) {
+            application.logger.warn(`Deployed ${application.name} but could not bound its kept releases:`, error);
+        }
     }
 }
 /**
@@ -2944,6 +3199,10 @@ async function buildCandidateApplication(application, deploymentId, options = {}
         // deployer's git token. `prepareApplication`'s finally still calls this; it is idempotent.
         await application.cleanupGitCredentialSession();
         await installApplication(application, candidateDirPath);
+        // After the install, which can rewrite the tree; never through a link, whose target is not the deploy's to write.
+        if (resolved.kind !== 'link') {
+            await writeDeploymentProvenance(candidateDirPath, application.name, deploymentId);
+        }
         return candidateDirPath;
     }
     catch (error) {
@@ -2996,6 +3255,21 @@ async function recoverOrCleanupStaleExtractionPaths(application, asideStagingDir
             (recoveryRecords.length > 1 ? `; discarded ${recoveryRecords.length - 1} older recovery candidates` : ''));
         return;
     }
+    // Each retired tree left here is a displaced release: kept if it can be — the retry of a keep that failed — and
+    // swept only when it cannot.
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(IN_PROGRESS_ASIDE_PREFIX))
+            continue;
+        const treePath = (0, node_path_1.join)(asideStagingDir, entry.name);
+        const retention = await retainDisplacedRelease((0, node_path_1.dirname)(application.dirPath), application.name, treePath).catch((error) => {
+            application.logger.warn(`Could not keep the previous release at ${treePath}; leaving it in place:`, error);
+            return { verdict: 'failed' };
+        });
+        if (retention.verdict === 'failed') {
+            paths.delete(treePath);
+            paths.delete(retiredMarkerForAside(treePath));
+        }
+    }
     await cleanupExtractionPaths(application, asideStagingDir, paths);
 }
 function isPriorAbsentRecoveryRecord(entry) {
@@ -3163,9 +3437,11 @@ async function retireComponentDirectory(componentDirPath, componentName = (0, no
         },
         async discard() {
             await cleanupExtractionPaths({ name: componentName, dirPath: componentDirPath, logger: componentLogger }, asideStagingDir, new Set([droppedPath]));
-            // A dropped component has no next deploy to bound its dormant builds.
+            // A dropped component has no next deploy to bound its dormant builds, and nothing left for its records to
+            // describe.
             try {
                 await pruneDormantBuilds(componentName, await dormantBuildsOf((0, node_path_1.dirname)(componentDirPath), componentName), 0);
+                await reclaimDeploymentRecordsOf((0, node_path_1.dirname)(componentDirPath), componentName);
             }
             catch (error) {
                 componentLogger.warn(`Dropped ${componentName} but could not reclaim its dormant staged builds:`, (0, harper_logger_ts_1.errorForLog)(error));
@@ -3173,6 +3449,33 @@ async function retireComponentDirectory(componentDirPath, componentName = (0, no
         },
     };
 }
+/** Journaled directories stay: an activation nobody settled is evidence, not litter. */
+async function reclaimDeploymentRecordsOf(componentsRootDirPath, componentName) {
+    const stagingRoot = (0, node_path_1.join)(componentsRootDirPath, exports.DEPLOY_STAGING_DIR);
+    const entries = await (0, promises_1.readdir)(stagingRoot, { withFileTypes: true }).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    await sweepAbandonedClaims(stagingRoot, entries, componentName);
+    for (const entry of entries) {
+        if (!isDeploymentDirectoryEntry(entry))
+            continue;
+        const deploymentDirPath = (0, node_path_1.join)(stagingRoot, entry.name);
+        try {
+            if ((await candidateComponentName(deploymentDirPath)) !== componentName)
+                continue;
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, ACTIVATION_JOURNAL)))
+                continue;
+            if (await presentOrAbsent((0, node_path_1.join)(deploymentDirPath, componentName)))
+                continue;
+            await (0, promises_1.rm)(deploymentDirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        }
+        catch (error) {
+            harper_logger_ts_1.default.warn(`Could not reclaim the deployment record ${deploymentDirPath} of ${componentName}:`, (0, harper_logger_ts_1.errorForLog)(error));
+        }
+    }
+}
 async function cleanupExtractionPaths(application, asideStagingDir, paths) {
     const retiredMarkers = [];
     for (const path of paths) {
@@ -3672,6 +3975,7 @@ class Application {
     isNewComponent = true;
     packageMetadataChanged = false;
     installationIsOpaque = false;
+    alreadyActive = false;
     constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }) {
         this.name = name;
         this.payload = payload;
@@ -3852,6 +4156,15 @@ async function prepareApplication(application, options = {}) {
                 throw error;
             }));
             if (mode === 'activate') {
+                // A retry of an activation that swapped here and failed later or elsewhere: answered without a swap so
+                // it can go on to the nodes still holding the artifact. Nothing can tell whether the running workers
+                // loaded it, hence the restart request.
+                if ((await readDeploymentProvenance(application.dirPath, application.name)) === artifactId) {
+                    application.alreadyActive = true;
+                    application.packageMetadataChanged = true;
+                    application.logger.debug?.(`Deployment ${artifactId} is already live; nothing to swap`);
+                    return;
+                }
                 await activateStagedArtifact(application, artifactId, previousPackageMetadata, options);
                 return;
             }
@@ -3896,8 +4209,23 @@ async function prepareApplication(application, options = {}) {
                         await syncArtifactAncestors(candidateDeploymentDirPath(application.dirPath, artifactId));
                         return;
                     }
-                    await markCandidateComplete(application.dirPath, artifactId, application.name);
                     const declared = options.describeArtifact?.();
+                    // The directory outlives the swap as the record a later displacement puts this release back into;
+                    // a link has no bytes of its own to put back.
+                    const described = declared && !(await (0, promises_1.lstat)(candidateDirPath)).isSymbolicLink() ? declared : undefined;
+                    if (described) {
+                        await writeArtifactDescriptor(application.dirPath, artifactId, {
+                            v: ARTIFACT_DESCRIPTOR_VERSION,
+                            component: application.name,
+                            rootConfig: described.rootConfig,
+                            installationIsOpaque: application.installationIsOpaque,
+                            isolated: described.isolated,
+                        });
+                    }
+                    await markCandidateComplete(application.dirPath, artifactId, application.name);
+                    // The record is meant to outlive the swap, so its own entry has to be on storage, as a stage's is.
+                    if (described)
+                        await syncArtifactAncestors(candidateDeploymentDirPath(application.dirPath, artifactId));
                     await activateCandidateApplication(application, artifactId, {
                         rootConfig: declared ? (0, rootConfigPublication_ts_1.rootConfigEffectFromDeclaration)(declared.rootConfig) : { kind: 'keep' },
                     });
@@ -3969,11 +4297,14 @@ async function activateStagedArtifact(application, artifactId, previousPackageMe
         throw unusable('an activation of it is unsettled');
     }
     const candidateStat = await presentOrAbsent(candidateDirPath);
-    if (!candidateStat || !candidateStat.isDirectory()) {
+    // The record of a release that is neither live nor kept here: nothing on this node answers to the id.
+    if (!candidateStat)
+        throw missing('that release is no longer on this node');
+    if (!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');
+        throw unusable('its build tree is a link rather than a copy');
     }
     const descriptor = await readArtifactDescriptor(deploymentDirPath, application.name);
     if (!descriptor)