sealkeep 0.8.1 → 0.11.0

package/dist/src/offload.js

@@ -1,12 +1,56 @@
-import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { link as hardLink, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { openForFlush } from "./flush.js";
+import { constants as fsConstants } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fail } from "./errors.js";
+import { basename, dirname, join, resolve } from "node:path";
+import { fail, SealkeepError } from "./errors.js";
 import { recordAudit } from "./audit.js";
 import { isV2 } from "./types.js";
-import { listArchives, readConfig, writeRecord } from "./vault.js";
+import { listArchives, mutateArchiveRecord, readConfig, resolveDeltaChain } from "./vault.js";
 import { createActiveLease, uploadClientFromStore } from "./providers/index.js";
-import { sha256 } from "./crypto.js";
+import { archiveCopies, verifiedCopyDestinationKey } from "./archive-copies.js";
+import { byteStreamWithIdleTimeout, digestChunks, LEGACY_BUFFER_LIMIT_BYTES, oneChunk, writeChunksToFile } from "./byte-stream.js";
+import { classifyDaemonProcessGeneration, daemonProcessIdentity } from "./daemon-lease.js";
+import { acquireDurableTicketLock } from "./durable-ticket-lock.js";
+import { paceBackgroundByteStream } from "./background-bandwidth.js";
+import { validateNoFollowPath } from "./reclaim-transaction.js";
+/** Resolve the immutable location recorded on a copy back to its account target. */
+async function configuredTargetForRemote(dataDir, remote) {
+    const config = await readConfig(dataDir);
+    const { remoteCopyMatchesTarget, resolveTargets } = await import("./storage-targets.js");
+    const targets = await resolveTargets(dataDir);
+    const byId = remote.targetId ? targets.find((candidate) => candidate.id === remote.targetId) : undefined;
+    if (byId && await remoteCopyMatchesTarget(dataDir, byId, remote))
+        return byId;
+    for (const candidate of targets) {
+        if (candidate === byId)
+            continue;
+        if (await remoteCopyMatchesTarget(dataDir, candidate, remote))
+            return candidate;
+    }
+    if (config.remoteStorage) {
+        const primary = { id: "primary", ...config.remoteStorage };
+        if (await remoteCopyMatchesTarget(dataDir, primary, remote))
+            return primary;
+    }
+    return fail("storage_not_configured", `The exact ${remote.provider} destination holding this copy is no longer configured on this machine. A reused target id or matching bucket name is not enough; restore the original endpoint/account route.`);
+}
+async function ownBucketConnection(dataDir, target, legacyOverrides = {}) {
+    const { credentialConfigIdForTarget, endpointOverridesForResolvedTarget } = await import("./storage-targets.js");
+    const credentialId = await credentialConfigIdForTarget(dataDir, target);
+    if (!credentialId)
+        fail("signer_not_configured", `Storage target "${target.id}" is not connected on this machine.`);
+    const ownOverrides = await endpointOverridesForResolvedTarget(dataDir, target);
+    return {
+        credentialId,
+        // Callers may still provide the setup wizard's old endpoint override, but
+        // it is valid only for the synthesized legacy primary.
+        overrides: Object.keys(ownOverrides).length > 0
+            ? ownOverrides
+            : target.id === "primary" ? legacyOverrides : {},
+    };
+}
 /** Providers this build can fetch back from. GCS uploads but has no download client. */
 // Every provider with a proven read-back path. "vaultline" reads back through
 // the account (pullCiphertext, hash-checked); "gcs" through a signed GET on
@@ -15,31 +59,145 @@ import { sha256 } from "./crypto.js";
 // gdrive joined when its client grew download() — the live Drive drill hit
 // this stale gate first: uploads landed, the local copy could never leave.
 const FETCHABLE = new Set(["s3", "r2", "b2", "gcs", "gdrive", "vaultline"]);
-export async function offloadable(dataDir) {
+/**
+ * The local-cache clock starts only after both facts are true: the archive
+ * exists and an off-machine copy has been verified. An old archive uploaded
+ * today therefore receives the same complete cache period as a new one.
+ */
+export function archiveCacheReferenceTime(record) {
+    const created = Date.parse(record.createdAt);
+    const verified = isV2(record)
+        ? archiveCopies(record)
+            .filter((copy) => FETCHABLE.has(copy.provider))
+            .map((copy) => Date.parse(copy.verifiedAt))
+            .filter(Number.isFinite)
+        : [];
+    return Math.max(Number.isFinite(created) ? created : Number.NEGATIVE_INFINITY, ...verified);
+}
+function passesAgeScope(record, options) {
+    if (options.olderThanDays === undefined)
+        return true;
+    if (!Number.isFinite(options.olderThanDays) || options.olderThanDays < 0)
+        return false;
+    const reference = archiveCacheReferenceTime(record);
+    return Number.isFinite(reference)
+        && reference <= (options.now ?? Date.now()) - options.olderThanDays * 86_400_000;
+}
+function passesOffloadScope(record, options) {
+    return (!options.only || options.only.has(record.id)) && passesAgeScope(record, options);
+}
+function physicalBytesOf(info) {
+    if (typeof info.nlink === "number" && info.nlink > 1)
+        return 0;
+    if (typeof info.blocks === "number" && Number.isSafeInteger(info.blocks) && info.blocks >= 0) {
+        return info.blocks * 512;
+    }
+    // Node does not expose st_blocks on every platform. Logical size is the
+    // least misleading fallback there; POSIX callers always take the branch
+    // above, including sparse files whose physical allocation is genuinely 0.
+    return info.size;
+}
+/**
+ * Returns one destination shared by every link in a delta chain, but only when
+ * every link at that destination is readable by this build. A verified copy
+ * on each link is not enough: split A/B copies cannot restore the session.
+ */
+function commonReadableDestination(chain) {
+    if (chain.length === 1) {
+        return archiveCopies(chain[0]).some((copy) => Number.isFinite(Date.parse(copy.verifiedAt)) && FETCHABLE.has(copy.provider))
+            ? "self-contained"
+            : null;
+    }
+    let common = null;
+    for (const record of chain) {
+        const destinations = new Set(archiveCopies(record)
+            .filter((copy) => Number.isFinite(Date.parse(copy.verifiedAt)) && FETCHABLE.has(copy.provider))
+            .map(verifiedCopyDestinationKey)
+            .filter((key) => Boolean(key)));
+        if (common === null)
+            common = destinations;
+        else {
+            const previous = common;
+            common = new Set([...previous].filter((key) => destinations.has(key)));
+        }
+        if (common.size === 0)
+            return null;
+    }
+    return [...(common ?? [])][0] ?? null;
+}
+export async function offloadable(dataDir, options = {}) {
     const archives = await listArchives(dataDir);
     const candidates = [];
     const blocked = [];
+    // Resolve the graph once so an incomplete chain blocks every local
+    // dependency, and an age-limited sweep never removes an old base still
+    // needed by a recent retained head.
+    const chainsById = new Map();
+    const unsafeDependencyIds = new Set();
+    const retainedByRecentHead = new Set();
+    for (const item of archives) {
+        if (!isV2(item))
+            continue;
+        let chain;
+        try {
+            const resolved = resolveDeltaChain(archives, item);
+            if (!resolved.every(isV2))
+                continue;
+            chain = resolved;
+        }
+        catch {
+            continue;
+        }
+        chainsById.set(item.id, chain);
+        if (chain.length > 1 && !commonReadableDestination(chain)) {
+            for (const link of chain)
+                unsafeDependencyIds.add(link.id);
+        }
+        if (options.olderThanDays !== undefined && !passesAgeScope(item, options) && chain.length > 1) {
+            for (const link of chain)
+                retainedByRecentHead.add(link.id);
+        }
+    }
     for (const record of archives) {
+        if (!passesOffloadScope(record, options))
+            continue;
         if (!isV2(record)) {
             blocked.push({ id: record.id, reason: "archive uses format v1; run `sealkeep migrate` first" });
             continue;
         }
         if (record.offloaded)
             continue;
-        const remote = record.remote;
-        if (!remote?.verifiedAt) {
-            blocked.push({ id: record.id, reason: "no verified remote copy, so the local one is the only copy" });
-            continue;
-        }
-        if (!FETCHABLE.has(remote.provider)) {
-            blocked.push({ id: record.id, reason: `${remote.provider} can be uploaded to but not read back by this build, so the local copy has to stay` });
+        if (retainedByRecentHead.has(record.id))
             continue;
-        }
         const local = await stat(record.objectPath).catch(() => null);
         if (!local) {
             blocked.push({ id: record.id, reason: "no local archive file to remove" });
             continue;
         }
+        const chain = chainsById.get(record.id);
+        if (!chain) {
+            blocked.push({ id: record.id, reason: "the archive's delta dependency chain is incomplete, so no safe offload proof exists" });
+            continue;
+        }
+        if (unsafeDependencyIds.has(record.id)) {
+            blocked.push({ id: record.id, reason: "verified copies for this delta chain are split or not readable at one destination, so the local copy stays" });
+            continue;
+        }
+        const verified = archiveCopies(record).filter((copy) => Number.isFinite(Date.parse(copy.verifiedAt)));
+        if (verified.length === 0) {
+            blocked.push({ id: record.id, reason: "no verified remote copy, so the local archive is the only copy" });
+            continue;
+        }
+        const readable = verified.filter((copy) => FETCHABLE.has(copy.provider));
+        if (readable.length === 0) {
+            blocked.push({ id: record.id, reason: `${verified.map((copy) => copy.provider).join(", ")} cannot be read back by this build, so the local copy has to stay` });
+            continue;
+        }
+        const commonDestination = commonReadableDestination(chain);
+        if (!commonDestination) {
+            blocked.push({ id: record.id, reason: "verified copies for this delta chain are split or not readable at one destination, so the local copy stays" });
+            continue;
+        }
         // The remote is only a copy if the sizes agree. For a provider that stores
         // the raw ciphertext that means equality; a managed object carries the
         // self-opening envelope frame around the same ciphertext, so it is larger
@@ -47,17 +205,678 @@ export async function offloadable(dataDir) {
         // demanding it silently blocked every managed offload. The frame only
         // adds, so smaller-than-local is still the same corruption signal, and
         // the true proof either way is the fetch-and-hash below.
-        const sameSize = remote.provider === "vaultline" ? remote.bytes >= local.size : remote.bytes === local.size;
-        if (!sameSize) {
-            blocked.push({ id: record.id, reason: `the remote object is ${remote.bytes} bytes and the local one is ${local.size}; they are not the same archive` });
+        const remote = readable.find((copy) => (chain.length === 1 || verifiedCopyDestinationKey(copy) === commonDestination)
+            && (copy.provider === "vaultline" ? copy.bytes >= local.size : copy.bytes === local.size));
+        if (!remote) {
+            blocked.push({ id: record.id, reason: `none of the ${readable.length} readable stored copies has the expected ${local.size} bytes` });
             continue;
         }
         candidates.push({
             id: record.id, agent: record.source.agent, path: record.source.path,
-            localBytes: local.size, provider: remote.provider, bucket: remote.bucket, objectKey: remote.objectKey
+            localBytes: local.size, allocatedBytes: physicalBytesOf(local),
+            provider: remote.provider, bucket: remote.bucket, objectKey: remote.objectKey,
+            copyId: remote.copyId
         });
     }
-    return { candidates, blocked, freeableBytes: candidates.reduce((total, item) => total + item.localBytes, 0) };
+    return { candidates, blocked, freeableBytes: candidates.reduce((total, item) => total + item.allocatedBytes, 0) };
+}
+const OFFLOAD_STAGES = new Set(["prepared", "linked", "remote-verified", "metadata-committed", "source-unlinked", "purge-authorized"]);
+const OFFLOAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function offloadJournalDirectory(dataDir) {
+    return join(resolve(dataDir), "offload-transactions");
+}
+export function offloadJournalPath(dataDir, id) {
+    if (!OFFLOAD_ID.test(id))
+        throw new Error("Invalid offload transaction id");
+    return join(offloadJournalDirectory(dataDir), `${id}.json`);
+}
+function offloadStagingPath(objectPath, id) {
+    return join(dirname(resolve(objectPath)), `.${basename(objectPath)}.sealkeep-offload-${id}.staged`);
+}
+async function syncOffloadDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function canonicalNonSymlinkDirectory(path, label) {
+    const lexical = resolve(path);
+    const info = await lstat(lexical);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error(`${label} is not a non-symlink directory: ${lexical}`);
+    const canonical = await realpath(lexical);
+    const canonicalInfo = await lstat(canonical);
+    if (!canonicalInfo.isDirectory() || canonicalInfo.isSymbolicLink())
+        throw new Error(`${label} does not resolve to a trusted directory: ${lexical}`);
+    return canonical;
+}
+async function trustedChildDirectory(parent, name, create) {
+    const path = join(parent, name);
+    let created = false;
+    if (create) {
+        try {
+            await mkdir(path, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    const info = await lstat(path).catch((error) => {
+        if (error.code === "ENOENT" && !create)
+            return null;
+        throw error;
+    });
+    if (!info)
+        return null;
+    if (!info.isDirectory() || info.isSymbolicLink() || await realpath(path) !== path) {
+        throw new Error(`Offload transaction directory is not a canonical non-symlink directory: ${path}`);
+    }
+    if (created) {
+        await syncOffloadDirectory(parent);
+        await syncOffloadDirectory(path);
+    }
+    return path;
+}
+async function trustedOffloadJournalDirectory(dataDir, create) {
+    const canonicalDataDir = await canonicalNonSymlinkDirectory(dataDir, "Sealkeep data directory");
+    return trustedChildDirectory(canonicalDataDir, "offload-transactions", create);
+}
+async function trustedOffloadLockPath(dataDir, key) {
+    const journalDirectory = await trustedOffloadJournalDirectory(dataDir, true);
+    if (!journalDirectory)
+        throw new Error("Could not create the offload transaction directory");
+    const lockDirectory = await trustedChildDirectory(journalDirectory, ".locks", true);
+    if (!lockDirectory)
+        throw new Error("Could not create the offload lock directory");
+    const queueDirectory = await trustedChildDirectory(lockDirectory, key, true);
+    if (!queueDirectory)
+        throw new Error("Could not create the archive offload lock queue");
+    return queueDirectory;
+}
+async function assertNoFollowJournal(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error(`Offload journal is not a non-symlink regular file: ${path}`);
+}
+async function readJournalNoFollow(path) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await open(path, fsConstants.O_RDONLY | noFollow);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            throw new Error(`Offload journal is not a regular file: ${path}`);
+        const raw = await handle.readFile("utf8");
+        const after = await handle.stat({ bigint: true });
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+            || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+            throw new Error(`Offload journal changed while it was being read: ${path}`);
+        }
+        return raw;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeOffloadJournal(transaction, exclusive = false) {
+    const directory = await trustedOffloadJournalDirectory(transactionDataDir(transaction), true);
+    if (!directory)
+        throw new Error("Could not create the offload transaction directory");
+    const path = join(directory, `${transaction.id}.json`);
+    const temporary = join(directory, `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(transaction)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (exclusive)
+            await hardLink(temporary, path);
+        else {
+            await assertNoFollowJournal(path);
+            await rename(temporary, path);
+        }
+        await syncOffloadDirectory(directory);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function removeOffloadJournal(dataDir, id) {
+    const directory = await trustedOffloadJournalDirectory(dataDir, false);
+    if (!directory)
+        throw new Error("Offload transaction directory disappeared before journal cleanup");
+    const path = join(directory, `${id}.json`);
+    await assertNoFollowJournal(path);
+    await unlink(path);
+    await syncOffloadDirectory(directory);
+}
+function transactionDataDir(transaction) {
+    const value = transaction.dataDir;
+    if (!value)
+        throw new Error("Offload transaction has no owning data directory");
+    return value;
+}
+function liveOffloadTransaction(dataDir, value) {
+    Object.defineProperty(value, "dataDir", { value: resolve(dataDir), enumerable: false, configurable: false, writable: false });
+    return value;
+}
+async function replaceOffloadJournal(transaction, stage, patch = {}) {
+    const next = liveOffloadTransaction(transaction.dataDir, {
+        ...transaction,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+        stage,
+    });
+    await writeOffloadJournal(next);
+    return next;
+}
+async function removeOffloadPathDurably(path) {
+    await unlink(path);
+    await syncOffloadDirectory(dirname(path));
+}
+async function localArchiveIdentity(path) {
+    const info = await lstat(path, { bigint: true });
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error(`Local archive is not a regular non-symlink file: ${path}`);
+    if (info.size > BigInt(Number.MAX_SAFE_INTEGER) || info.blocks * 512n > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`Local archive is too large to measure safely: ${path}`);
+    }
+    return {
+        bytes: Number(info.size),
+        allocatedBytes: Number(info.blocks * 512n),
+        links: Number(info.nlink),
+        dev: info.dev.toString(),
+        ino: info.ino.toString(),
+    };
+}
+async function localArchiveIdentityOrNull(path) {
+    try {
+        return await localArchiveIdentity(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function sameOffloadInode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameOffloadFile(left, right) {
+    return sameOffloadInode(left, right) && left.bytes === right.bytes;
+}
+function sameOffloadSnapshot(left, right) {
+    return sameOffloadFile(left, right)
+        && left.allocatedBytes === right.allocatedBytes
+        && left.links === right.links;
+}
+function parseOffloadJournal(dataDir, name, raw) {
+    const value = JSON.parse(raw);
+    const original = value.original;
+    if (value.version !== 1
+        || typeof value.id !== "string" || !OFFLOAD_ID.test(value.id) || name !== `${value.id}.json`
+        || typeof value.archiveId !== "string" || !OFFLOAD_ID.test(value.archiveId)
+        || typeof value.objectPath !== "string" || value.objectPath !== resolve(value.objectPath)
+        || typeof value.stagingPath !== "string" || value.stagingPath !== offloadStagingPath(value.objectPath, value.id)
+        || typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))
+        || typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))
+        || !value.stage || !OFFLOAD_STAGES.has(value.stage)
+        || !original || !Number.isSafeInteger(original.bytes) || (original.bytes ?? -1) < 0
+        || !Number.isSafeInteger(original.allocatedBytes) || (original.allocatedBytes ?? -1) < 0
+        || !Number.isSafeInteger(original.links) || (original.links ?? 0) < 1
+        || typeof original.dev !== "string" || typeof original.ino !== "string"
+        || (value.purgeSnapshot !== undefined && (!Number.isSafeInteger(value.purgeSnapshot.bytes) || value.purgeSnapshot.bytes < 0
+            || !Number.isSafeInteger(value.purgeSnapshot.allocatedBytes) || value.purgeSnapshot.allocatedBytes < 0
+            || !Number.isSafeInteger(value.purgeSnapshot.links) || value.purgeSnapshot.links < 1
+            || typeof value.purgeSnapshot.dev !== "string" || typeof value.purgeSnapshot.ino !== "string"))
+        || !value.remote || typeof value.remote.provider !== "string" || typeof value.remote.bucket !== "string" || typeof value.remote.objectKey !== "string"
+        || (value.remote.copyId !== undefined && typeof value.remote.copyId !== "string")
+        || (value.remote.destinationKey !== undefined && typeof value.remote.destinationKey !== "string")) {
+        throw new Error(`Invalid offload transaction journal: ${join(offloadJournalDirectory(dataDir), name)}`);
+    }
+    return liveOffloadTransaction(dataDir, value);
+}
+async function readOffloadJournals(dataDir) {
+    const directory = await trustedOffloadJournalDirectory(dataDir, false);
+    if (!directory)
+        return [];
+    const names = await readdir(directory);
+    const journals = [];
+    for (const name of names.filter((item) => item.endsWith(".json")).sort()) {
+        const path = join(directory, name);
+        await assertNoFollowJournal(path);
+        journals.push(parseOffloadJournal(dataDir, name, await readJournalNoFollow(path)));
+    }
+    return journals;
+}
+async function beginOffloadTransaction(dataDir, candidate, record) {
+    const original = await localArchiveIdentity(record.objectPath);
+    if (original.bytes !== record.cipher.storedBytes || original.bytes !== candidate.localBytes) {
+        throw new Error("the local encrypted archive changed while offload was starting; local copy kept");
+    }
+    const now = new Date().toISOString();
+    const id = randomUUID();
+    const selected = archiveCopies(record).find((copy) => copy.copyId === candidate.copyId);
+    if (!selected)
+        throw new Error("the selected verified copy changed before offload could start; local copy kept");
+    const destinationKey = verifiedCopyDestinationKey(selected);
+    const transaction = liveOffloadTransaction(dataDir, {
+        version: 1,
+        id,
+        archiveId: record.id,
+        objectPath: resolve(record.objectPath),
+        stagingPath: offloadStagingPath(record.objectPath, id),
+        createdAt: now,
+        updatedAt: now,
+        stage: "prepared",
+        original,
+        remote: {
+            ...(candidate.copyId ? { copyId: candidate.copyId } : {}),
+            ...(destinationKey ? { destinationKey } : {}),
+            provider: candidate.provider,
+            bucket: candidate.bucket,
+            objectKey: candidate.objectKey,
+        },
+    });
+    await assertOffloadRecordOwnsPath(dataDir, transaction);
+    await writeOffloadJournal(transaction, true);
+    return transaction;
+}
+async function linkOffloadStaging(transaction) {
+    const before = await localArchiveIdentity(transaction.objectPath);
+    if (!sameOffloadFile(before, transaction.original)) {
+        throw new Error("the local encrypted archive changed before it could be staged; local copy kept");
+    }
+    await hardLink(transaction.objectPath, transaction.stagingPath);
+    const [source, staged] = await Promise.all([
+        localArchiveIdentity(transaction.objectPath),
+        localArchiveIdentity(transaction.stagingPath),
+    ]);
+    if (!sameOffloadFile(source, staged) || !sameOffloadFile(source, transaction.original)) {
+        throw new Error("the encrypted archive staging link does not identify the original inode; both paths were kept");
+    }
+    const { handle: stagedHandle } = await openForFlush(transaction.stagingPath);
+    try {
+        await stagedHandle.sync();
+    }
+    finally {
+        await stagedHandle.close();
+    }
+    await syncOffloadDirectory(dirname(transaction.stagingPath));
+    return replaceOffloadJournal(transaction, "linked");
+}
+function selectedOffloadCopy(record, transaction) {
+    return archiveCopies(record).find((copy) => transaction.remote.copyId
+        ? copy.copyId === transaction.remote.copyId
+        : copy.provider === transaction.remote.provider
+            && copy.bucket === transaction.remote.bucket
+            && copy.objectKey === transaction.remote.objectKey) ?? null;
+}
+function offloadMetadataMatches(record, transaction) {
+    return record.offloaded?.transactionId === transaction.id
+        && record.offloaded.provider === transaction.remote.provider
+        && record.offloaded.bucket === transaction.remote.bucket
+        && record.offloaded.objectKey === transaction.remote.objectKey;
+}
+function offloadMetadataFinalized(record, transaction) {
+    const offloaded = record.offloaded;
+    return Boolean(offloaded
+        && offloaded.transactionId === undefined
+        && offloaded.provider === transaction.remote.provider
+        && offloaded.bucket === transaction.remote.bucket
+        && offloaded.objectKey === transaction.remote.objectKey
+        && offloaded.localBytes === transaction.original.bytes
+        && Number.isSafeInteger(offloaded.freedBytes)
+        && (offloaded.freedBytes ?? -1) >= 0);
+}
+async function verifyOffloadRemoteChain(dataDir, record, transaction, options) {
+    const selected = selectedOffloadCopy(record, transaction);
+    if (!selected)
+        throw new Error("the verified restore copy changed while offload was being checked; local copy kept");
+    if (!Number.isFinite(Date.parse(selected.verifiedAt)) || !FETCHABLE.has(selected.provider)) {
+        throw new Error("the selected restore copy is no longer verified and readable; local copy kept");
+    }
+    const archives = await listArchives(dataDir);
+    const liveRecord = archives.find((item) => item.id === record.id && isV2(item));
+    if (!liveRecord)
+        throw new Error("the archive disappeared while its remote dependency chain was being checked; local copy kept");
+    const resolved = resolveDeltaChain(archives, liveRecord);
+    if (!resolved.every(isV2))
+        throw new Error("the archive's remote dependency chain is incomplete; local copy kept");
+    const chain = resolved;
+    const selectedDestination = transaction.remote.destinationKey ?? verifiedCopyDestinationKey(selected);
+    if (chain.length > 1 && !selectedDestination) {
+        throw new Error("the archive's remote dependency chain has no stable common destination; local copy kept");
+    }
+    for (const link of chain) {
+        const copy = link.id === liveRecord.id
+            ? selectedOffloadCopy(link, transaction)
+            : archiveCopies(link).find((candidate) => Number.isFinite(Date.parse(candidate.verifiedAt))
+                && FETCHABLE.has(candidate.provider)
+                && verifiedCopyDestinationKey(candidate) === selectedDestination) ?? null;
+        if (!copy || !Number.isFinite(Date.parse(copy.verifiedAt)) || !FETCHABLE.has(copy.provider)
+            || (chain.length > 1 && verifiedCopyDestinationKey(copy) !== selectedDestination)) {
+            throw new Error(`the complete remote delta chain is no longer readable at one destination (${link.id}); local copy kept`);
+        }
+        let stream = await fetchCiphertextStream(dataDir, link, options.client, copy, options.overrides, options.signal);
+        if (options.maxBytesPerSecond !== undefined) {
+            stream = paceBackgroundByteStream(dataDir, stream, options.maxBytesPerSecond, { signal: options.signal });
+        }
+        const fetched = await digestChunks(stream);
+        if (fetched.sha256Hex !== link.cipher.ciphertextSha256 || fetched.bytes !== link.cipher.storedBytes) {
+            throw new Error(`what the bucket returned is not this archive (${link.id}) in the required delta chain; local copy kept`);
+        }
+    }
+}
+async function markOffloadMetadata(dataDir, transaction) {
+    const config = await readConfig(dataDir);
+    await mutateArchiveRecord(config.storage.root, transaction.archiveId, (current) => {
+        if (!isV2(current) || resolve(current.objectPath) !== transaction.objectPath || !selectedOffloadCopy(current, transaction)) {
+            throw new Error("archive metadata changed while offload was being committed; local copy kept");
+        }
+        if (current.offloaded && !offloadMetadataMatches(current, transaction)) {
+            throw new Error("another offload already changed this archive record; local copy kept");
+        }
+        return {
+            ...current,
+            offloaded: {
+                at: current.offloaded?.at ?? new Date().toISOString(),
+                provider: transaction.remote.provider,
+                bucket: transaction.remote.bucket,
+                objectKey: transaction.remote.objectKey,
+                transactionId: transaction.id,
+                localBytes: transaction.original.bytes,
+                freedBytes: 0,
+            },
+        };
+    });
+    return replaceOffloadJournal(transaction, "metadata-committed");
+}
+async function unlinkOffloadSource(transaction) {
+    const [source, staged] = await Promise.all([
+        localArchiveIdentity(transaction.objectPath),
+        localArchiveIdentity(transaction.stagingPath),
+    ]);
+    if (!sameOffloadFile(source, staged) || !sameOffloadFile(source, transaction.original)) {
+        throw new Error("the local archive path changed before offload could remove it; every file was kept");
+    }
+    await removeOffloadPathDurably(transaction.objectPath);
+    return replaceOffloadJournal(transaction, "source-unlinked");
+}
+async function finalizeOffloadMetadata(dataDir, transaction, freedBytes) {
+    const config = await readConfig(dataDir);
+    await mutateArchiveRecord(config.storage.root, transaction.archiveId, (current) => {
+        if (!isV2(current) || !offloadMetadataMatches(current, transaction)) {
+            throw new Error("offload completed but its archive record changed; the recovery journal was retained");
+        }
+        const { transactionId: _transactionId, ...offloaded } = current.offloaded;
+        return { ...current, offloaded: { ...offloaded, freedBytes, localBytes: transaction.original.bytes } };
+    });
+    await removeOffloadJournal(dataDir, transaction.id);
+    return freedBytes;
+}
+async function clearOwnedOffloadMetadata(dataDir, transaction) {
+    const config = await readConfig(dataDir);
+    await mutateArchiveRecord(config.storage.root, transaction.archiveId, (current) => {
+        if (!isV2(current) || !offloadMetadataMatches(current, transaction))
+            return current;
+        const { offloaded: _offloaded, ...rest } = current;
+        return rest;
+    });
+}
+async function assertOffloadRecordOwnsPath(dataDir, transaction) {
+    const config = await readConfig(dataDir);
+    const record = (await listArchives(dataDir)).find((item) => item.id === transaction.archiveId && isV2(item));
+    const lexicalRoot = resolve(config.storage.root);
+    const expectedObject = join(lexicalRoot, `${transaction.archiveId}.skarchive`);
+    if (!record || resolve(record.objectPath) !== transaction.objectPath
+        || transaction.objectPath !== expectedObject
+        || dirname(transaction.stagingPath) !== lexicalRoot
+        || transaction.stagingPath !== offloadStagingPath(transaction.objectPath, transaction.id)) {
+        throw new Error("archive record no longer owns the path named by its offload journal; every path and the journal were kept");
+    }
+    // Resolve only the trusted configured root, then validate each descendant
+    // one component at a time. This permits platform aliases such as macOS
+    // /var -> /private/var without trusting a symlink inserted inside archives/.
+    const canonicalRoot = await realpath(lexicalRoot);
+    const canonicalObject = join(canonicalRoot, basename(transaction.objectPath));
+    const canonicalStaging = join(canonicalRoot, basename(transaction.stagingPath));
+    await validateNoFollowPath(canonicalObject, [canonicalRoot], { leaf: "missing-or-file" });
+    await validateNoFollowPath(canonicalStaging, [canonicalRoot], { leaf: "missing-or-file" });
+    return record;
+}
+async function rollbackOffloadTransaction(dataDir, transaction) {
+    await assertOffloadRecordOwnsPath(dataDir, transaction);
+    const source = await localArchiveIdentityOrNull(transaction.objectPath);
+    const staged = await localArchiveIdentityOrNull(transaction.stagingPath);
+    if (source && staged) {
+        if (!sameOffloadFile(source, transaction.original)
+            || !sameOffloadFile(staged, transaction.original)
+            || !sameOffloadFile(source, staged)) {
+            throw new Error(`Offload conflict kept both ${transaction.objectPath} and ${transaction.stagingPath}`);
+        }
+        await removeOffloadPathDurably(transaction.stagingPath);
+    }
+    else if (!source && staged) {
+        if (!sameOffloadFile(staged, transaction.original)) {
+            throw new Error(`Offload staging conflict kept ${transaction.stagingPath}`);
+        }
+        await hardLink(transaction.stagingPath, transaction.objectPath);
+        await syncOffloadDirectory(dirname(transaction.objectPath));
+        const restored = await localArchiveIdentity(transaction.objectPath);
+        if (!sameOffloadFile(restored, transaction.original)) {
+            throw new Error(`Offload rollback could not prove the restored inode at ${transaction.objectPath}; both names were kept`);
+        }
+        await removeOffloadPathDurably(transaction.stagingPath);
+    }
+    else if (source && !staged) {
+        if (!sameOffloadFile(source, transaction.original)) {
+            throw new Error(`Offload source conflict kept ${transaction.objectPath} and its transaction journal`);
+        }
+    }
+    else if (!source && !staged) {
+        throw new Error("Offload transaction lost both local names before authorization");
+    }
+    const surviving = await localArchiveIdentityOrNull(transaction.objectPath);
+    if (!surviving || !sameOffloadFile(surviving, transaction.original)) {
+        throw new Error(`Offload rollback did not retain the exact source inode at ${transaction.objectPath}; metadata and journal were kept`);
+    }
+    await clearOwnedOffloadMetadata(dataDir, transaction);
+    await removeOffloadJournal(dataDir, transaction.id);
+}
+/**
+ * Remove the final Sealkeep name while holding the exact inode open. The
+ * post-unlink fstat is the truthful answer to "were blocks actually freed?":
+ * any pre-existing or concurrently added hard link makes that answer zero.
+ */
+async function purgeOffloadStaging(transaction, beforeUnlink) {
+    const expected = transaction.purgeSnapshot;
+    if (!expected)
+        throw new Error("offload purge was not authorised with a final inode snapshot");
+    const handle = await open(transaction.stagingPath, "r");
+    try {
+        const beforeInfo = await handle.stat({ bigint: true });
+        if (!beforeInfo.isFile() || beforeInfo.size > BigInt(Number.MAX_SAFE_INTEGER)
+            || beforeInfo.blocks * 512n > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error("offload staging is not a measurable regular file at the purge boundary");
+        }
+        const before = {
+            bytes: Number(beforeInfo.size), allocatedBytes: Number(beforeInfo.blocks * 512n), links: Number(beforeInfo.nlink),
+            dev: beforeInfo.dev.toString(), ino: beforeInfo.ino.toString(),
+        };
+        const named = await localArchiveIdentity(transaction.stagingPath);
+        if (!sameOffloadSnapshot(before, expected) || !sameOffloadSnapshot(named, expected)) {
+            throw new Error("offload staging changed after purge authorization; it was retained");
+        }
+        await beforeUnlink?.(transaction);
+        await unlink(transaction.stagingPath);
+        await syncOffloadDirectory(dirname(transaction.stagingPath));
+        const afterInfo = await handle.stat({ bigint: true });
+        if (afterInfo.dev.toString() !== expected.dev || afterInfo.ino.toString() !== expected.ino
+            || afterInfo.size !== BigInt(expected.bytes)) {
+            throw new Error("offload lost identity of the staged inode while removing its name");
+        }
+        const remainingLinks = Number(afterInfo.nlink);
+        return remainingLinks === 0 ? Number(afterInfo.blocks * 512n) : 0;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function completeOffloadTransaction(dataDir, transaction, options) {
+    let current = transaction;
+    let record = await assertOffloadRecordOwnsPath(dataDir, current);
+    let source = await localArchiveIdentityOrNull(current.objectPath);
+    let staged = await localArchiveIdentityOrNull(current.stagingPath);
+    if (!staged && source && current.stage === "prepared") {
+        current = await linkOffloadStaging(current);
+        await options.operations?.afterLinked?.(current);
+        source = await localArchiveIdentityOrNull(current.objectPath);
+        staged = await localArchiveIdentityOrNull(current.stagingPath);
+    }
+    if (!staged || (source && !sameOffloadFile(source, staged)) || !sameOffloadFile(staged, current.original)) {
+        throw new Error("offload staging no longer identifies the exact local archive; every surviving path was kept");
+    }
+    const refreshedRecord = (await listArchives(dataDir)).find((item) => item.id === current.archiveId && isV2(item));
+    if (!refreshedRecord)
+        throw new Error("archive record disappeared while offload was proving its remote copy");
+    record = refreshedRecord;
+    if (!offloadMetadataMatches(record, current))
+        current = await markOffloadMetadata(dataDir, current);
+    else if (current.stage !== "metadata-committed" && current.stage !== "source-unlinked" && current.stage !== "purge-authorized") {
+        current = await replaceOffloadJournal(current, "metadata-committed");
+    }
+    await options.operations?.afterMetadata?.(current);
+    source = await localArchiveIdentityOrNull(current.objectPath);
+    staged = await localArchiveIdentityOrNull(current.stagingPath);
+    if (source) {
+        if (!staged || !sameOffloadFile(source, staged) || !sameOffloadFile(source, current.original))
+            throw new Error("local archive path was replaced during offload; both files were kept");
+        current = await unlinkOffloadSource(current);
+    }
+    else if (current.stage !== "source-unlinked" && current.stage !== "purge-authorized") {
+        current = await replaceOffloadJournal(current, "source-unlinked");
+    }
+    await options.operations?.afterSourceUnlinked?.(current);
+    // The irreversible boundary is removal of the staging name below. Re-read
+    // and hash EVERY remote dependency at the frozen common destination here,
+    // after all potentially slow local metadata work. In an uninterrupted
+    // attempt this is exactly one full streamed read per chain link.
+    await verifyOffloadRemoteChain(dataDir, record, current, options);
+    current = await replaceOffloadJournal(current, "remote-verified");
+    await options.operations?.afterRemoteVerified?.(current);
+    const finalStaged = await localArchiveIdentity(current.stagingPath);
+    if (!sameOffloadFile(finalStaged, current.original)) {
+        throw new Error("offload staging changed at the final purge boundary; it was retained");
+    }
+    await recordAudit(dataDir, "archive.offload", "allowed", {
+        archiveId: current.archiveId,
+        transactionId: current.id,
+        bytes: current.original.bytes,
+        authorizedPhysicalBytes: finalStaged.links === 1 ? finalStaged.allocatedBytes : 0,
+        finalLinkCount: finalStaged.links,
+        bucket: current.remote.bucket,
+    });
+    current = await replaceOffloadJournal(current, "purge-authorized", { purgeSnapshot: finalStaged });
+    await options.operations?.afterPurgeAuthorized?.(current);
+    const freedBytes = await purgeOffloadStaging(current, options.operations?.beforeStagingUnlink);
+    await options.operations?.afterStagingPurged?.(current);
+    await finalizeOffloadMetadata(dataDir, current, freedBytes);
+    const candidate = {
+        id: current.archiveId,
+        agent: record.source.agent,
+        path: record.source.path,
+        localBytes: current.original.bytes,
+        allocatedBytes: freedBytes,
+        provider: current.remote.provider,
+        bucket: current.remote.bucket,
+        objectKey: current.remote.objectKey,
+        ...(current.remote.copyId ? { copyId: current.remote.copyId } : {}),
+    };
+    return { candidate, freedBytes };
+}
+export async function reconcileOffloadTransactions(dataDir, options = {}) {
+    const completed = [];
+    const failed = [];
+    let freedBytes = 0;
+    for (let transaction of await readOffloadJournals(dataDir)) {
+        const lockKey = createHash("sha256").update(transaction.archiveId).digest("hex");
+        const lock = await acquireDurableTicketLock(await trustedOffloadLockPath(dataDir, lockKey), `archive offload ${transaction.archiveId}`, { timeoutMs: 30_000, signal: options.signal });
+        try {
+            const record = (await listArchives(dataDir)).find((item) => item.id === transaction.archiveId && isV2(item));
+            await assertOffloadRecordOwnsPath(dataDir, transaction);
+            const source = await localArchiveIdentityOrNull(transaction.objectPath);
+            const staged = await localArchiveIdentityOrNull(transaction.stagingPath);
+            const ownsMetadata = Boolean(record && offloadMetadataMatches(record, transaction));
+            // The record update can reach disk before journal cleanup. That is a
+            // completed transaction, not a rollback candidate; both local names
+            // must already be gone before this stale journal is retired.
+            if (record && offloadMetadataFinalized(record, transaction)) {
+                if (source || staged)
+                    throw new Error("finalized offload metadata conflicts with a surviving local transaction path");
+                const released = record.offloaded?.freedBytes ?? 0;
+                await removeOffloadJournal(dataDir, transaction.id);
+                freedBytes += released;
+                completed.push({
+                    id: transaction.archiveId, agent: record.source.agent, path: record.source.path,
+                    localBytes: transaction.original.bytes, allocatedBytes: released,
+                    provider: transaction.remote.provider, bucket: transaction.remote.bucket, objectKey: transaction.remote.objectKey,
+                    ...(transaction.remote.copyId ? { copyId: transaction.remote.copyId } : {}),
+                });
+                continue;
+            }
+            if (!ownsMetadata) {
+                await rollbackOffloadTransaction(dataDir, transaction);
+                continue;
+            }
+            if (!source && !staged) {
+                if (transaction.stage !== "purge-authorized") {
+                    throw new Error("both local names disappeared before a durable purge authorization; transaction retained for repair");
+                }
+                // The process died before its post-unlink fstat result reached durable
+                // metadata. A hard link may have appeared in the syscall-sized gap,
+                // so the only honest recovery metric is the conservative lower bound.
+                const released = 0;
+                await finalizeOffloadMetadata(dataDir, transaction, released);
+                freedBytes += released;
+                completed.push({
+                    id: transaction.archiveId, agent: record.source.agent, path: record.source.path,
+                    localBytes: transaction.original.bytes, allocatedBytes: released,
+                    provider: transaction.remote.provider, bucket: transaction.remote.bucket, objectKey: transaction.remote.objectKey,
+                    ...(transaction.remote.copyId ? { copyId: transaction.remote.copyId } : {}),
+                });
+                continue;
+            }
+            const outcome = await completeOffloadTransaction(dataDir, transaction, options);
+            completed.push(outcome.candidate);
+            freedBytes += outcome.freedBytes;
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            try {
+                await rollbackOffloadTransaction(dataDir, transaction);
+            }
+            catch { /* Every surviving name and the journal remain for a later repair. */ }
+            failed.push({ id: transaction.archiveId, error: error instanceof Error ? error.message : "could not reconcile offload" });
+        }
+        finally {
+            await lock.release().catch(() => undefined);
+        }
+    }
+    return { completed, failed, freedBytes };
 }
 /**
  * Removes local archives that a bucket has a verified copy of.
@@ -67,51 +886,50 @@ export async function offloadable(dataDir) {
  * the deletion of something that has since become the only copy.
  */
 export async function offloadArchives(dataDir, options = {}) {
-    const all = await offloadable(dataDir);
-    // `only` narrows the sweep — the upload run offloads each archive as its
-    // verify lands rather than re-walking the whole vault per item.
-    const candidates = options.only ? all.candidates.filter((candidate) => options.only.has(candidate.id)) : all.candidates;
+    const recovered = options.confirm
+        ? await reconcileOffloadTransactions(dataDir, options)
+        : { completed: [], failed: [], freedBytes: 0 };
+    const all = await offloadable(dataDir, options);
+    const recoveryFailures = new Set(recovered.failed.map((item) => item.id));
+    const candidates = all.candidates.filter((candidate) => !recoveryFailures.has(candidate.id));
     const blocked = all.blocked;
-    const freeableBytes = candidates.reduce((total, item) => total + item.localBytes, 0);
+    const freeableBytes = candidates.reduce((total, item) => total + item.allocatedBytes, 0);
     if (!options.confirm)
         return { mode: "preview", wouldOffload: candidates, blocked, freedBytes: freeableBytes };
-    const archives = new Map((await listArchives(dataDir)).map((record) => [record.id, record]));
-    const offloaded = [];
-    const failed = [];
-    const config = await readConfig(dataDir);
+    const offloaded = [...recovered.completed];
+    const failed = [...recovered.failed];
+    let freedBytes = recovered.freedBytes;
     for (const candidate of candidates) {
-        const record = archives.get(candidate.id);
-        if (!record || !isV2(record))
-            continue;
+        options.signal?.throwIfAborted();
+        const lockKey = createHash("sha256").update(candidate.id).digest("hex");
+        const lock = await acquireDurableTicketLock(await trustedOffloadLockPath(dataDir, lockKey), `archive offload ${candidate.id}`, { timeoutMs: 30_000, signal: options.signal });
+        let transaction = null;
         try {
-            // Prove the bytes are really there, now, before removing the local ones.
-            // The verifiedAt stamp says they were there once; this asks again, because
-            // between then and now is exactly where a bucket lifecycle rule lives.
-            // The one honest exception: an archive whose verify landed seconds ago in
-            // the same run — between then and now is milliseconds, and re-downloading
-            // a gigabyte to re-prove it would double the egress of every push.
-            if (!options.freshlyVerified?.has(candidate.id)) {
-                const fetched = await fetchCiphertext(dataDir, record, options.client);
-                if (sha256(fetched) !== record.cipher.ciphertextSha256) {
-                    failed.push({ id: candidate.id, error: "what the bucket returned is not this archive; local copy kept" });
-                    continue;
-                }
-            }
-            await rm(record.objectPath, { force: true });
-            const next = {
-                ...record,
-                offloaded: { at: new Date().toISOString(), provider: candidate.provider, bucket: candidate.bucket, objectKey: candidate.objectKey }
-            };
-            await writeRecord(config.storage.root, next);
-            await recordAudit(dataDir, "archive.offload", "allowed", { archiveId: candidate.id, bytes: candidate.localBytes, bucket: candidate.bucket });
-            offloaded.push(candidate);
+            const record = (await listArchives(dataDir)).find((item) => item.id === candidate.id && isV2(item));
+            if (!record || record.offloaded)
+                continue;
+            transaction = await beginOffloadTransaction(dataDir, candidate, record);
+            await options.operations?.afterJournal?.(transaction);
+            const outcome = await completeOffloadTransaction(dataDir, transaction, options);
+            offloaded.push(outcome.candidate);
+            freedBytes += outcome.freedBytes;
         }
         catch (error) {
-            await recordAudit(dataDir, "archive.offload", "denied", { archiveId: candidate.id });
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            if (transaction)
+                await rollbackOffloadTransaction(dataDir, transaction).catch(() => undefined);
+            await recordAudit(dataDir, "archive.offload", "denied", {
+                archiveId: candidate.id,
+                ...(transaction ? { transactionId: transaction.id } : {}),
+            });
             failed.push({ id: candidate.id, error: error instanceof Error ? error.message : "could not offload" });
         }
+        finally {
+            await lock.release().catch(() => undefined);
+        }
     }
-    return { mode: "apply", offloaded, failed, blocked, freedBytes: offloaded.reduce((total, item) => total + item.localBytes, 0) };
+    return { mode: "apply", offloaded, failed, blocked, freedBytes };
 }
 /**
  * Downloads an archive's ciphertext from the bucket it was offloaded to.
@@ -122,103 +940,115 @@ export async function offloadArchives(dataDir, options = {}) {
  * not be recovered by the person who owns it — which would turn a space-saving
  * feature into data loss. The flag is set for this call only.
  */
-async function fetchCiphertext(dataDir, record, client) {
-    const config = await readConfig(dataDir);
-    const remote = record.remote ?? record.offloaded;
+export async function fetchCiphertextStream(dataDir, record, client, selectedCopy, overrides = {}, signal, idleMs, maxBytesPerSecond) {
+    return byteStreamWithIdleTimeout(async (readSignal) => {
+        const remote = selectedCopy ?? archiveCopies(record)[0] ?? record.offloaded;
+        const managedFrame = remote?.provider === "vaultline" && !client && remote.layout?.kind !== "chunks";
+        const stream = await openCiphertextStream(dataDir, record, client, selectedCopy, overrides, readSignal, maxBytesPerSecond);
+        // Managed frames are paced before their metadata is stripped. Other
+        // providers expose raw ciphertext, which is paced exactly once here.
+        return maxBytesPerSecond === undefined || managedFrame ? stream
+            : paceBackgroundByteStream(dataDir, stream, maxBytesPerSecond, { signal: readSignal });
+    }, { signal, idleMs });
+}
+async function openCiphertextStream(dataDir, record, client, selectedCopy, overrides, signal, maxBytesPerSecond) {
+    const remote = selectedCopy ?? archiveCopies(record)[0] ?? record.offloaded;
     if (!remote)
         fail("archive_not_found", `Archive ${record.id} has no remote copy to fetch`, { archiveId: record.id });
     // A managed copy reads back through the account, not a provider credential:
     // pullCiphertext hash-checks what it downloads before returning it. Branch
     // on the record's own provider — a vault can hold managed history alongside
     // a later own-bucket configuration, and each copy fetches its own way.
-    if (remote.provider === "vaultline" && !client && record.remote?.layout?.kind !== "chunks") {
-        const { pullCiphertext, unframeObject } = await import("./cloud.js");
-        const { ciphertext: blob } = await pullCiphertext(dataDir, record.id);
+    if (remote.provider === "vaultline" && !client && remote.layout?.kind !== "chunks") {
+        const { pullCiphertextStream } = await import("./cloud.js");
         // A managed object is envelope-framed — the self-carrying wrapper push
         // added so a bare object can be opened anywhere. What the local record
         // hashes is the ciphertext INSIDE the frame, so that is what this must
         // return; handing back the framed bytes made every integrity check
         // compare an apple to the crate it shipped in. A plain-mode object has
         // no frame and IS the stored bytes.
-        const { envelope, ciphertext } = unframeObject(blob);
-        return envelope ? ciphertext : blob;
+        return pullCiphertextStream(dataDir, record.id, undefined, { unframe: true, signal, maxBytesPerSecond });
     }
     // Chunk-folder remotes fetch object by object, each hash-checked against
     // the envelope's own chunk headers — the layout was made for exactly this.
     // A managed folder reads back through the account's download leases; an own
     // bucket reads through the provider's object verbs.
-    if (record.remote?.layout?.kind === "chunks") {
-        const { fetchChunkFolder } = await import("./chunk-store.js");
+    if (remote.layout?.kind === "chunks") {
+        const { fetchChunkFolderStream } = await import("./chunk-store.js");
         let folderClient;
         if (client)
             folderClient = client;
-        else if (record.remote.provider === "vaultline") {
+        else if (remote.provider === "vaultline") {
             folderClient = (await import("./managed-chunks.js")).managedChunkClient(dataDir);
         }
         else {
-            const target = config.remoteStorage ?? fail("storage_not_configured", "This vault has no storage configured, so an offloaded archive cannot be fetched back");
-            folderClient = await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
+            const named = await configuredTargetForRemote(dataDir, remote);
+            if (named.provider === "vaultline" || !named.bucket)
+                fail("storage_not_configured", "This chunk copy has no usable bucket target on this machine");
+            const target = { provider: named.provider, bucket: named.bucket, prefix: named.prefix ?? "sealkeep", ...(named.region ? { region: named.region } : {}) };
+            const connection = await ownBucketConnection(dataDir, named, overrides);
+            folderClient = await uploadClientFromStore(dataDir, connection.credentialId, target, connection.overrides, undefined);
         }
         if (typeof folderClient.getObject !== "function")
-            fail("provider_unsupported", `${record.remote.provider} cannot fetch chunk folders with this build`);
-        return fetchChunkFolder(folderClient, record.remote, record.envelope);
+            fail("provider_unsupported", `${remote.provider} cannot fetch chunk folders with this build`);
+        return fetchChunkFolderStream(folderClient, remote, record.envelope, { signal });
     }
     // The record routes its own read: provider and bucket come from the copy
     // itself, the prefix from its object key, and a configured target (matched
     // by targetId, then by provider+bucket) fills in the rest. config.remoteStorage
     // is only the last resort — a multi-target vault has none.
-    const target = await (async () => {
-        if (config.remoteStorage && config.remoteStorage.provider === remote.provider && config.remoteStorage.bucket === remote.bucket)
-            return config.remoteStorage;
-        try {
-            const { resolveTargets } = await import("./storage-targets.js");
-            const targets = await resolveTargets(dataDir);
-            const stampedId = remote.targetId;
-            const match = (stampedId ? targets.find((candidate) => candidate.id === stampedId) : undefined)
-                ?? targets.find((candidate) => candidate.provider === remote.provider && candidate.bucket === remote.bucket);
-            if (match) {
-                const derivedPrefix = remote.objectKey.split("/").slice(0, -1).join("/");
-                return { provider: match.provider, bucket: match.bucket ?? remote.bucket, prefix: match.prefix ?? (derivedPrefix || "vaultline"), region: match.region };
-            }
-        }
-        catch { /* fall through */ }
-        if (config.remoteStorage)
-            return config.remoteStorage;
-        return fail("storage_not_configured", "This vault has no storage configured, so an offloaded archive cannot be fetched back");
-    })();
-    if (target.provider === "vaultline")
+    const named = await configuredTargetForRemote(dataDir, remote);
+    if (named.provider === "vaultline" || !named.bucket)
         fail("storage_not_configured", "This managed copy should have taken the managed read path");
-    const resolved = client ?? await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
-    const lease = createActiveLease(target, {
-        archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
-    }, { ...process.env, SEALKEEP_ENABLE_SIGNER: "1" });
+    const derivedPrefix = remote.objectKey.split("/").slice(0, -1).join("/");
+    const target = {
+        provider: named.provider,
+        bucket: named.bucket,
+        prefix: named.prefix ?? (derivedPrefix || "sealkeep"),
+        ...(named.region ? { region: named.region } : {}),
+    };
+    const connection = client ? null : await ownBucketConnection(dataDir, named, overrides);
+    const resolved = client ?? await uploadClientFromStore(dataDir, connection.credentialId, target, connection.overrides, undefined);
+    const lease = { ...createActiveLease(target, {
+            archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
+        }, { ...process.env, SEALKEEP_ENABLE_SIGNER: "1" }), objectKey: remote.objectKey };
     const readable = resolved;
+    if (typeof readable.downloadStream === "function")
+        return readable.downloadStream(lease, { signal });
     if (typeof readable.download !== "function") {
         fail("provider_unsupported", `${target.provider} cannot be read back by this build, so this archive cannot be fetched`);
     }
-    return readable.download(lease);
+    // Small injected/test clients predate the stream contract. Never invoke a
+    // whole-Buffer client for a large archive: fail before it can allocate.
+    if (record.cipher.storedBytes > LEGACY_BUFFER_LIMIT_BYTES) {
+        fail("provider_unsupported", `${target.provider} cannot stream this ${record.cipher.storedBytes}-byte archive with the installed client`, { archiveId: record.id });
+    }
+    const buffered = await readable.download(lease, { signal });
+    if (buffered.length > LEGACY_BUFFER_LIMIT_BYTES) {
+        fail("provider_unsupported", `${target.provider} returned more than the bounded compatibility limit`, { archiveId: record.id });
+    }
+    return oneChunk(buffered);
 }
 /**
  * One managed record checked against the account's rows. A single-object copy
  * is one row at the recorded size; a chunk-folder copy is its whole family —
  * every chunk row present, the envelope sidecar present, and the chunk bytes
  * summing to the verified total. The proof standard does not soften because
- * the object count went up: any missing member is "do not trash the original".
+ * the object count went up: any missing member is "do not reclaim the original".
  */
-async function managedCopyCheck(dataDir, record, rows, checkedAt) {
-    const remote = record.remote;
+async function managedCopyCheck(dataDir, record, remote, rows, checkedAt) {
     if (remote.layout?.kind === "chunks") {
         const { managedChunkRefs } = await import("./managed-chunks.js");
         const refs = managedChunkRefs(record.id, remote.layout.chunkCount);
         const missing = refs.chunks.filter((ref) => !rows.has(ref)).length + (rows.has(refs.envelope) ? 0 : 1);
         if (missing > 0) {
             await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "absent", missing });
-            return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: `Your managed storage is missing ${missing} of this archive's ${refs.chunks.length + 1} objects. Do not trash the original — this disk may hold the only complete copy.` };
+            return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: `Your managed storage is missing ${missing} of this archive's ${refs.chunks.length + 1} objects. Do not reclaim the original — this disk may hold the only complete copy.` };
         }
         const bytes = refs.chunks.reduce((sum, ref) => sum + (rows.get(ref) ?? 0), 0);
         if (bytes !== remote.bytes) {
             await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "size", stored: bytes });
-            return { ok: false, provider: remote.provider, bytes, checkedAt, detail: `Your storage reports ${bytes} chunk bytes; ${remote.bytes} were verified. Do not trash the original.` };
+            return { ok: false, provider: remote.provider, bytes, checkedAt, detail: `Your storage reports ${bytes} chunk bytes; ${remote.bytes} were verified. Do not reclaim the original.` };
         }
         await recordAudit(dataDir, "remote.check", "allowed", { archiveId: record.id, bytes, chunks: refs.chunks.length });
         return { ok: true, provider: remote.provider, bytes, checkedAt, detail: `Your managed storage confirmed all ${refs.chunks.length} chunks and the sidecar at the recorded size, just now.` };
@@ -226,49 +1056,98 @@ async function managedCopyCheck(dataDir, record, rows, checkedAt) {
     const stored = rows.get(record.id);
     if (stored === undefined) {
         await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "absent" });
-        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "Your managed storage no longer lists this archive. Do not trash the original — this disk may hold the only copy." };
+        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "Your managed storage no longer lists this archive. Do not reclaim the original — this disk may hold the only copy." };
     }
     if (stored !== remote.bytes) {
         await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "size", stored });
-        return { ok: false, provider: remote.provider, bytes: stored, checkedAt, detail: `Your storage reports ${stored} bytes; ${remote.bytes} were verified. Do not trash the original.` };
+        return { ok: false, provider: remote.provider, bytes: stored, checkedAt, detail: `Your storage reports ${stored} bytes; ${remote.bytes} were verified. Do not reclaim the original.` };
     }
     await recordAudit(dataDir, "remote.check", "allowed", { archiveId: record.id, bytes: stored });
     return { ok: true, provider: remote.provider, bytes: stored, checkedAt, detail: "Your managed storage confirmed it holds this archive at the recorded size, just now." };
 }
-export async function checkRemoteCopy(dataDir, archiveId, client) {
+export async function checkRemoteCopy(dataDir, archiveId, client, copyId) {
     const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
     if (!record)
         fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
     if (!isV2(record))
         fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
-    const remote = record.remote;
+    const remote = copyId
+        ? archiveCopies(record).find((copy) => copy.copyId === copyId)
+        : archiveCopies(record).find((copy) => copy.verifiedAt);
     if (!remote?.verifiedAt)
         fail("invalid_argument", "This archive has no verified cloud copy to check — upload it first.", { archiveId });
     const checkedAt = new Date().toISOString();
     if (remote.provider === "vaultline" && !client) {
         const { listCloudArchives } = await import("./cloud.js");
         const rows = new Map((await listCloudArchives(dataDir)).map((row) => [row.vault_ref, Number(row.bytes) || 0]));
-        return managedCopyCheck(dataDir, record, rows, checkedAt);
+        return managedCopyCheck(dataDir, record, remote, rows, checkedAt);
     }
-    const config = await readConfig(dataDir);
-    const target = config.remoteStorage;
-    if (!target)
-        fail("storage_not_configured", "This vault has no storage configured, so the copy cannot be checked");
-    const resolved = client ?? await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
-    const lease = createActiveLease(target, {
-        archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
-    }, { ...process.env, SEALKEEP_ENABLE_SIGNER: "1" });
+    const named = await configuredTargetForRemote(dataDir, remote);
+    if (named.provider === "vaultline" || !named.bucket) {
+        fail("storage_not_configured", `The ${remote.provider} destination holding this copy is not connected on this machine, so it cannot be checked.`);
+    }
+    const derivedPrefix = remote.objectKey.split("/").slice(0, -1).join("/");
+    const target = {
+        provider: named.provider,
+        bucket: named.bucket,
+        prefix: named.prefix ?? (derivedPrefix || "sealkeep"),
+        ...(named.region ? { region: named.region } : {}),
+    };
+    const connection = client ? null : await ownBucketConnection(dataDir, named);
+    const resolved = client ?? await uploadClientFromStore(dataDir, connection.credentialId, target, connection.overrides, undefined);
+    if (remote.layout?.kind === "chunks") {
+        const probing = resolved;
+        if (typeof probing.headObject !== "function")
+            fail("provider_unsupported", `${remote.provider} cannot probe chunk folders with this build`);
+        if (remote.layout.chunkCount !== record.envelope.chunks.length) {
+            return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: `The record names ${record.envelope.chunks.length} chunks but this copy claims ${remote.layout.chunkCount}. Do not reclaim the original.` };
+        }
+        let bytes = 0;
+        const problems = [];
+        const { chunkObjectName, ENVELOPE_OBJECT } = await import("./chunk-store.js");
+        for (let index = 0; index < record.envelope.chunks.length; index += 1) {
+            const expected = record.envelope.chunks[index].storedBytes;
+            const head = await probing.headObject(`${remote.objectKey}/${chunkObjectName(index)}`);
+            if (!head.exists)
+                problems.push(`chunk ${index} is missing`);
+            else {
+                bytes += head.bytes;
+                if (head.bytes !== expected)
+                    problems.push(`chunk ${index} is ${head.bytes} bytes; ${expected} were verified`);
+            }
+            if (problems.length >= 3)
+                break;
+        }
+        if (problems.length < 3) {
+            const sidecar = await probing.headObject(`${remote.objectKey}/${ENVELOPE_OBJECT}`);
+            if (!sidecar.exists)
+                problems.push("the envelope sidecar is missing");
+            else if (sidecar.bytes <= 0)
+                problems.push("the envelope sidecar is empty");
+        }
+        if (bytes !== remote.bytes)
+            problems.push(`the chunks total ${bytes} bytes; ${remote.bytes} were verified`);
+        if (problems.length > 0) {
+            await recordAudit(dataDir, "remote.check", "denied", { archiveId, reason: "chunk-folder", problems: problems.length, stored: bytes });
+            return { ok: false, provider: remote.provider, bytes, checkedAt, detail: `${problems.join("; ")}. Do not reclaim the original — this disk may hold the only complete copy.` };
+        }
+        await recordAudit(dataDir, "remote.check", "allowed", { archiveId, bytes, chunks: remote.layout.chunkCount, sidecar: true });
+        return { ok: true, provider: remote.provider, bytes, checkedAt, detail: `The bucket confirmed all ${remote.layout.chunkCount} chunks and the envelope sidecar at the recorded sizes, just now.` };
+    }
+    const lease = { ...createActiveLease(target, {
+            archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
+        }, { ...process.env, SEALKEEP_ENABLE_SIGNER: "1" }), objectKey: remote.objectKey };
     const probing = resolved;
     if (typeof probing.head !== "function")
-        fail("provider_unsupported", `${target.provider} cannot be probed by this build`);
+        fail("provider_unsupported", `${remote.provider} cannot be probed by this build`);
     const head = await probing.head(lease);
     if (!head.exists) {
         await recordAudit(dataDir, "remote.check", "denied", { archiveId, reason: "absent" });
-        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "The bucket no longer holds this object. Do not trash the original — this disk may hold the only copy." };
+        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "The bucket no longer holds this object. Do not reclaim the original — this disk may hold the only copy." };
     }
     if (head.bytes !== remote.bytes) {
         await recordAudit(dataDir, "remote.check", "denied", { archiveId, reason: "size", stored: head.bytes });
-        return { ok: false, provider: remote.provider, bytes: head.bytes, checkedAt, detail: `The bucket holds ${head.bytes} bytes; ${remote.bytes} were verified. Do not trash the original.` };
+        return { ok: false, provider: remote.provider, bytes: head.bytes, checkedAt, detail: `The bucket holds ${head.bytes} bytes; ${remote.bytes} were verified. Do not reclaim the original.` };
     }
     await recordAudit(dataDir, "remote.check", "allowed", { archiveId, bytes: head.bytes });
     return { ok: true, provider: remote.provider, bytes: head.bytes, checkedAt, detail: "The bucket answered just now and holds this archive at the recorded size." };
@@ -283,7 +1162,7 @@ export async function checkRemoteCopyMany(dataDir, ids, client) {
     const wanted = ids.map((id) => archives.find((item) => item.id === id));
     const checkedAt = new Date().toISOString();
     const results = [];
-    const managedIds = wanted.filter((record) => !!record && isV2(record) && record.remote?.provider === "vaultline").map((record) => record.id);
+    const managedIds = wanted.filter((record) => !!record && isV2(record) && archiveCopies(record).some((copy) => copy.verifiedAt && copy.provider === "vaultline")).map((record) => record.id);
     let managedRows = null;
     if (managedIds.length > 0 && !client) {
         const { listCloudArchives } = await import("./cloud.js");
@@ -291,22 +1170,718 @@ export async function checkRemoteCopyMany(dataDir, ids, client) {
     }
     for (const id of ids) {
         const record = archives.find((item) => item.id === id);
-        if (!record || !isV2(record) || !record.remote?.verifiedAt) {
+        if (!record || !isV2(record)) {
             results.push({ ok: false, provider: "none", bytes: 0, checkedAt, detail: "No verified cloud copy on record for this archive." });
             continue;
         }
-        if (record.remote.provider === "vaultline" && managedRows) {
-            results.push(await managedCopyCheck(dataDir, record, managedRows, checkedAt));
+        const copies = archiveCopies(record).filter((copy) => copy.verifiedAt);
+        if (copies.length === 0) {
+            results.push({ ok: false, provider: "none", bytes: 0, checkedAt, detail: "No verified cloud copy on record for this archive." });
             continue;
         }
+        const checks = [];
+        for (const copy of copies) {
+            try {
+                if (copy.provider === "vaultline" && managedRows && !client) {
+                    checks.push(await managedCopyCheck(dataDir, record, copy, managedRows, checkedAt));
+                }
+                else {
+                    checks.push(await checkRemoteCopy(dataDir, id, client, copy.copyId));
+                }
+            }
+            catch (error) {
+                checks.push({ ok: false, provider: copy.provider, bytes: 0, checkedAt, detail: error instanceof Error ? error.message : "the check itself failed" });
+            }
+        }
+        const failed = checks.find((check) => !check.ok);
+        results.push(failed ?? {
+            ok: true,
+            provider: checks.length === 1 ? checks[0].provider : "multiple",
+            bytes: checks.reduce((sum, check) => sum + check.bytes, 0),
+            checkedAt,
+            detail: checks.length === 1 ? checks[0].detail : `All ${checks.length} stored copies answered at their recorded sizes, just now.`,
+        });
+    }
+    return results;
+}
+function cancellationError(signal) {
+    if (signal?.reason instanceof Error)
+        return signal.reason;
+    const error = new Error("The archive materialisation was cancelled");
+    error.name = "AbortError";
+    return error;
+}
+const DEFAULT_SCRATCH_WAIT_MS = 5_000;
+function scratchBusyError(waitMs) {
+    return new SealkeepError("scratch_space_busy", `Another archive operation is using this disk's temporary workspace. Sealkeep waited ${Math.max(0, Math.round(waitMs / 100) / 10)} seconds without taking extra space; try again after that operation finishes.`, { retryable: true, waitedMs: waitMs });
+}
+function waitForScratchLease(signal, delayMs) {
+    if (signal?.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const finish = () => {
+            if (signal)
+                signal.removeEventListener("abort", abort);
+            resolve();
+        };
+        const timer = setTimeout(finish, Math.max(1, delayMs));
+        const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(cancellationError(signal));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+/**
+ * Cleanup is secondary to the operation that made cleanup necessary. Preserve
+ * the original Error object (and therefore a SealkeepError's code/details or
+ * an AbortSignal's exact reason) while making a failed scratch release visible
+ * to logs and callers. Frozen/non-Error throwables fall back to AggregateError,
+ * which still retains both original values in order.
+ */
+function withScratchReleaseFailure(primary, releaseError) {
+    const releaseMessage = releaseError instanceof Error ? releaseError.message : "unknown scratch release failure";
+    const detail = `releasing the archive scratch reservation also failed (${releaseMessage})`;
+    if (primary instanceof Error) {
+        try {
+            Object.defineProperty(primary, "scratchReleaseError", {
+                value: releaseError,
+                configurable: true,
+                enumerable: false,
+            });
+            primary.message = `${primary.message}; ${detail}`;
+            return primary;
+        }
+        catch { /* a frozen/custom Error is represented by the aggregate below */ }
+    }
+    const primaryMessage = primary instanceof Error ? primary.message : String(primary);
+    return new AggregateError([primary, releaseError], `${primaryMessage}; ${detail}`, { cause: primary });
+}
+/**
+ * One complete fetched archive at a time in this process.
+ *
+ * Historical indexing now consumes chunk-independent archives directly from
+ * their authenticated provider stream and never enters this gate. Operations
+ * that genuinely require a complete file (restore, share, or provider bridge)
+ * may still overlap across local servers. The permit is held until the verified
+ * temporary file is released, not merely until the download ends: measured free
+ * space therefore reflects the previous archive's deletion before the next
+ * check. Local archives never enter this gate and retain their parallel path.
+ */
+class ScratchMaterialisationGate {
+    active = false;
+    waiting = [];
+    acquire(signal, deadline, waitMs) {
+        if (signal?.aborted)
+            return Promise.reject(cancellationError(signal));
+        if (Date.now() >= deadline)
+            return Promise.reject(scratchBusyError(waitMs));
+        return new Promise((grant, reject) => {
+            const waiter = { signal, grant, reject };
+            const withdraw = (error) => {
+                const at = this.waiting.indexOf(waiter);
+                if (at >= 0)
+                    this.waiting.splice(at, 1);
+                if (waiter.timer)
+                    clearTimeout(waiter.timer);
+                signal?.removeEventListener("abort", waiter.onAbort);
+                reject(error);
+            };
+            if (signal) {
+                waiter.onAbort = () => withdraw(cancellationError(signal));
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            waiter.timer = setTimeout(() => withdraw(scratchBusyError(waitMs)), Math.max(1, deadline - Date.now()));
+            if (!this.active)
+                this.activate(waiter);
+            else
+                this.waiting.push(waiter);
+        });
+    }
+    activate(waiter) {
+        if (waiter.signal?.aborted) {
+            waiter.onAbort?.();
+            this.advance();
+            return;
+        }
+        this.active = true;
+        if (waiter.timer)
+            clearTimeout(waiter.timer);
+        if (waiter.signal && waiter.onAbort)
+            waiter.signal.removeEventListener("abort", waiter.onAbort);
+        let released = false;
+        waiter.grant(() => {
+            if (released)
+                return;
+            released = true;
+            this.active = false;
+            this.advance();
+        });
+    }
+    advance() {
+        if (this.active)
+            return;
+        const next = this.waiting.shift();
+        if (next)
+            this.activate(next);
+    }
+}
+const scratchMaterialisations = new ScratchMaterialisationGate();
+const SCRATCH_LEASE_STALE_MS = 30 * 60_000;
+const scratchLeaseOwnerPath = (leasePath) => join(leasePath, "owner.json");
+/**
+ * Processes from different vaults can still spend the same filesystem's free
+ * bytes. Key the well-known lease by the scratch directory's device id in a
+ * per-user temp namespace; fall back to this vault's trusted runtime directory
+ * only on platforms where that identity cannot be established.
+ */
+export async function ensurePrivateScratchCoordination(baseDir, user, expectedUid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+    const namespace = join(baseDir, `sealkeep-${user}`);
+    const coordination = join(namespace, "scratch-volume-leases");
+    for (const path of [namespace, coordination]) {
         try {
-            results.push(await checkRemoteCopy(dataDir, id, client));
+            await mkdir(path, { mode: 0o700 });
         }
         catch (error) {
-            results.push({ ok: false, provider: record.remote.provider, bytes: 0, checkedAt, detail: error instanceof Error ? error.message : "the check itself failed" });
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink() || !entry.isDirectory()) {
+            return fail("internal", `Sealkeep refused an unsafe archive scratch coordination path (${path} is not a real directory).`);
+        }
+        if (expectedUid !== undefined && entry.uid !== expectedUid) {
+            return fail("internal", `Sealkeep refused an archive scratch coordination directory not owned by this user (${path}).`);
+        }
+        if ((entry.mode & 0o777) !== 0o700) {
+            return fail("internal", `Sealkeep refused an archive scratch coordination directory without private 0700 permissions (${path}).`);
         }
     }
-    return results;
+    return coordination;
+}
+async function scratchLeasePath(dataDir, spaceRoot) {
+    try {
+        const device = (await stat(spaceRoot)).dev;
+        const user = typeof process.getuid === "function" ? String(process.getuid()) : "user";
+        // Never let a predictable /tmp pathname be redirected through a symlink
+        // or pre-created by another local account. Each component below the OS
+        // temp root is a real, current-user-owned 0700 directory before a ticket
+        // or lease token is written into it.
+        const coordination = await ensurePrivateScratchCoordination(tmpdir(), user);
+        return join(coordination, `device-${device}.lock`);
+    }
+    catch (error) {
+        // A per-vault fallback is not safe: two vaults on the same nearly-full
+        // volume would each believe they exclusively reserved the remaining disk.
+        // Fail closed when the shared volume identity/coordination directory is
+        // unavailable; the original provider bytes remain untouched.
+        return fail("internal", `Sealkeep could not reserve this volume's shared archive workspace: ${error instanceof Error ? error.message : "coordination unavailable"}`, { dataDir });
+    }
+}
+function parseScratchLeaseOwner(raw) {
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || !Number.isSafeInteger(value.pid) || Number(value.pid) < 1
+            || typeof value.processIdentity !== "string" || value.processIdentity.length < 1 || value.processIdentity.length > 512
+            || typeof value.nonce !== "string" || !/^[0-9a-f-]{36}$/i.test(value.nonce)
+            || typeof value.acquiredAt !== "string")
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Separate local servers can perform share/restore/transfer work at once, and
+ * an older index child may still own the v1 lease during an upgrade. The
+ * in-memory gate above cannot make their `statfs` checks atomic. This volume
+ * lease spans download plus consumer use across processes; a dead process
+ * generation is reclaimable, while an unidentifiable live owner fails closed
+ * and keeps its possible scratch bytes reserved.
+ */
+async function acquireCrossProcessScratchLease(dataDir, spaceRoot, signal, deadline, waitMs) {
+    if (signal?.aborted)
+        throw cancellationError(signal);
+    const identityBeforeDeadline = async (pid) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw scratchBusyError(waitMs);
+        let timer;
+        try {
+            return await Promise.race([
+                daemonProcessIdentity(pid),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve({ state: "unknown" }), remaining);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    const self = await identityBeforeDeadline(process.pid);
+    if (self.state !== "identified") {
+        return fail("internal", "Sealkeep could not verify this process generation before reserving archive scratch space");
+    }
+    const leasePath = await scratchLeasePath(dataDir, spaceRoot);
+    const runtimeDir = dirname(leasePath);
+    await mkdir(runtimeDir, { recursive: true, mode: 0o700 });
+    const owner = {
+        version: 1,
+        pid: process.pid,
+        processIdentity: self.identity,
+        nonce: randomUUID(),
+        acquiredAt: new Date().toISOString(),
+    };
+    const token = `${JSON.stringify(owner)}\n`;
+    let acquired;
+    // A tiny FIFO ticket stays outside the long-held lease. Unlike repeated
+    // rename races, lexicographic admission cannot indefinitely starve one
+    // process behind newer contenders. The content carries the same process-
+    // generation proof as the lease, so a crashed waiter can be removed safely.
+    const ticketPrefix = `${basename(leasePath)}.ticket-`;
+    const ticketName = `${ticketPrefix}${String(Date.now()).padStart(16, "0")}-${String(process.pid).padStart(10, "0")}-${owner.nonce}.json`;
+    const ticketPath = join(runtimeDir, ticketName);
+    const ticketPending = `${ticketPath}.pending`;
+    try {
+        await writeFile(ticketPending, token, { flag: "wx", mode: 0o600 });
+        await rename(ticketPending, ticketPath);
+    }
+    catch (error) {
+        await unlink(ticketPending).catch(() => undefined);
+        throw error;
+    }
+    const liveTickets = async () => {
+        // Tickets after ours cannot delay us. Avoid process-generation probes for
+        // those newer waiters, and stop the stale-ticket scan at the same deadline
+        // as acquisition so directory litter cannot stretch a five-second bound.
+        const names = (await readdir(runtimeDir))
+            .filter((name) => name.startsWith(ticketPrefix) && name.endsWith(".json") && name <= ticketName)
+            .sort();
+        const live = [];
+        for (const name of names) {
+            if (Date.now() >= deadline)
+                throw scratchBusyError(waitMs);
+            const path = join(runtimeDir, name);
+            const [raw, entry] = await Promise.all([
+                readFile(path, "utf8").catch(() => null),
+                stat(path).catch(() => null),
+            ]);
+            if (!entry)
+                continue;
+            if (name === ticketName && raw === token) {
+                live.push(name);
+                continue;
+            }
+            const ticketOwner = parseScratchLeaseOwner(raw);
+            let abandoned = false;
+            if (ticketOwner) {
+                const generation = await identityBeforeDeadline(ticketOwner.pid);
+                abandoned = classifyDaemonProcessGeneration(generation, ticketOwner.processIdentity) === "stale";
+            }
+            else if (Date.now() - entry.mtimeMs > SCRATCH_LEASE_STALE_MS) {
+                abandoned = true;
+            }
+            if (abandoned) {
+                // The user-private coordination directory prevents hostile replacement,
+                // but still compare the complete token so two legitimate rescuers never
+                // unlink a newer ticket that reused the same pathname.
+                if (await readFile(path, "utf8").then((current) => current === raw).catch(() => false)) {
+                    await unlink(path).catch(() => undefined);
+                }
+                continue;
+            }
+            live.push(name);
+        }
+        return live;
+    };
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                throw cancellationError(signal);
+            if (Date.now() >= deadline)
+                throw scratchBusyError(waitMs);
+            const tickets = await liveTickets();
+            if (tickets[0] !== ticketName) {
+                await waitForScratchLease(signal, Math.min(50, Math.max(1, deadline - Date.now())));
+                continue;
+            }
+            const staging = `${leasePath}.${owner.nonce}.pending`;
+            try {
+                await mkdir(staging, { mode: 0o700 });
+                await writeFile(scratchLeaseOwnerPath(staging), token, { flag: "wx", mode: 0o600 });
+                const candidate = await stat(staging);
+                await rename(staging, leasePath);
+                acquired = { dev: candidate.dev, ino: candidate.ino, birthtimeMs: candidate.birthtimeMs };
+                break;
+            }
+            catch (error) {
+                await unlink(scratchLeaseOwnerPath(staging)).catch(() => undefined);
+                await rmdir(staging).catch(() => undefined);
+                const code = error.code;
+                const leaseExists = await stat(leasePath).then((entry) => entry.isDirectory()).catch(() => false);
+                // A legitimate owner can release between our failed publish and this
+                // observation. Its now-absent directory is a retry opportunity, not an
+                // archive-transfer error. Never infer the same from a permission error.
+                if (!leaseExists && (code === "EEXIST" || code === "ENOTEMPTY"))
+                    continue;
+                if (!leaseExists || (code !== "EEXIST" && code !== "ENOTEMPTY" && code !== "EPERM"))
+                    throw error;
+                const [held, raw] = await Promise.all([
+                    stat(leasePath).catch(() => null),
+                    readFile(scratchLeaseOwnerPath(leasePath), "utf8").catch(() => null),
+                ]);
+                const currentOwner = parseScratchLeaseOwner(raw);
+                let abandoned = false;
+                if (currentOwner) {
+                    const generation = await identityBeforeDeadline(currentOwner.pid);
+                    abandoned = classifyDaemonProcessGeneration(generation, currentOwner.processIdentity) === "stale";
+                }
+                else if (held && Date.now() - held.mtimeMs > SCRATCH_LEASE_STALE_MS) {
+                    // Complete lock directories are published by rename, so malformed
+                    // content is never a normal acquisition window. Keep it for a generous
+                    // transition period before treating old/corrupt state as abandoned.
+                    abandoned = true;
+                }
+                if (abandoned && held) {
+                    const fingerprint = createHash("sha256")
+                        .update(`${held.dev}:${held.ino}:${held.birthtimeMs}:${raw ?? ""}`)
+                        .digest("hex")
+                        .slice(0, 20);
+                    const quarantine = `${leasePath}.stale-${fingerprint}`;
+                    const [again, currentRaw] = await Promise.all([
+                        stat(leasePath).catch(() => null),
+                        readFile(scratchLeaseOwnerPath(leasePath), "utf8").catch(() => null),
+                    ]);
+                    const same = !!again && again.dev === held.dev && again.ino === held.ino
+                        && again.birthtimeMs === held.birthtimeMs && currentRaw === raw;
+                    if (same) {
+                        try {
+                            await rename(leasePath, quarantine);
+                        }
+                        catch (moveError) {
+                            const moveCode = moveError.code;
+                            if (moveCode !== "ENOENT" && moveCode !== "EEXIST" && moveCode !== "ENOTEMPTY" && moveCode !== "EPERM")
+                                throw moveError;
+                        }
+                    }
+                    // Deliberately retain the non-empty quarantine. If two rescuers saw
+                    // this dead directory, the first can move it and a new owner can then
+                    // acquire the public name before the second reaches rename(). The
+                    // deterministic occupied destination makes that delayed rename fail
+                    // instead of moving the successor's live lease out of the way.
+                    continue;
+                }
+                await waitForScratchLease(signal, Math.min(50, Math.max(1, deadline - Date.now())));
+            }
+        }
+    }
+    finally {
+        await unlink(ticketPath).catch(() => undefined);
+        await unlink(ticketPending).catch(() => undefined);
+    }
+    if (!acquired)
+        return fail("internal", "Sealkeep lost its archive scratch reservation while acquiring it");
+    return async () => {
+        const absentOnly = async (operation) => {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+        };
+        const [held, raw] = await Promise.all([
+            absentOnly(() => stat(leasePath)),
+            absentOnly(() => readFile(scratchLeaseOwnerPath(leasePath), "utf8")),
+        ]);
+        if (!held || held.dev !== acquired.dev || held.ino !== acquired.ino
+            || held.birthtimeMs !== acquired.birthtimeMs || raw !== token)
+            return;
+        const released = `${leasePath}.released-${owner.nonce}`;
+        try {
+            await rename(leasePath, released);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        await unlink(scratchLeaseOwnerPath(released)).catch(() => undefined);
+        await rmdir(released).catch(() => undefined);
+    };
+}
+async function acquireScratchMaterialisationPermit(dataDir, spaceRoot, signal, scratchWaitMs = DEFAULT_SCRATCH_WAIT_MS) {
+    const waitMs = Math.max(1, Math.min(5 * 60_000, Math.ceil(scratchWaitMs)));
+    const deadline = Date.now() + waitMs;
+    const releaseLocal = await scratchMaterialisations.acquire(signal, deadline, waitMs);
+    try {
+        const releaseCrossProcess = await acquireCrossProcessScratchLease(dataDir, spaceRoot, signal, deadline, waitMs);
+        let localReleased = false;
+        let releaseComplete = false;
+        let releaseInFlight;
+        return () => {
+            if (releaseComplete)
+                return Promise.resolve();
+            if (releaseInFlight)
+                return releaseInFlight;
+            const attempt = (async () => {
+                try {
+                    await releaseCrossProcess();
+                    releaseComplete = true;
+                }
+                finally {
+                    // A failed cross-process rename must not monopolise this process's
+                    // FIFO lane. Its exact-owner callback remains retryable, while this
+                    // local release happens once and only once.
+                    if (!localReleased) {
+                        localReleased = true;
+                        releaseLocal();
+                    }
+                }
+            })();
+            releaseInFlight = attempt;
+            attempt.then(() => { if (releaseInFlight === attempt)
+                releaseInFlight = undefined; }, () => { if (releaseInFlight === attempt)
+                releaseInFlight = undefined; });
+            return attempt;
+        };
+    }
+    catch (error) {
+        releaseLocal();
+        throw error;
+    }
+}
+/**
+ * Restores the sealed archive blob itself to this machine without decrypting
+ * the session. This is the safe first half of a remote-to-remote move: once a
+ * verified local blob exists, the ordinary target upload can copy it anywhere
+ * without buffering two providers through the browser or risking the source.
+ */
+export async function restoreArchiveLocal(dataDir, archiveId, options = {}) {
+    const config = await readConfig(dataDir);
+    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+    if (!isV2(record))
+        fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
+    const present = await stat(record.objectPath).then((entry) => entry.isFile()).catch(() => false);
+    if (present) {
+        const { hashFileRange } = await import("../packages/sealkeep-crypto/src/index.js");
+        const measured = await hashFileRange(record.objectPath, 0, undefined, options.onProgress, options.signal);
+        if (measured.sha256 !== record.cipher.ciphertextSha256) {
+            fail("ciphertext_integrity_failed", `A file already exists at ${record.objectPath}, but it is not archive ${archiveId}. It was left untouched.`, { archiveId, path: record.objectPath });
+        }
+        if (record.offloaded) {
+            await mutateArchiveRecord(config.storage.root, archiveId, (current) => {
+                if (!isV2(current))
+                    return current;
+                const { offloaded: _offloaded, ...withLocalCopy } = current;
+                return withLocalCopy;
+            });
+        }
+        const bytes = measured.bytes;
+        return { restored: false, alreadyPresent: true, bytes, path: record.objectPath };
+    }
+    const copies = archiveCopies(record);
+    const chosen = options.copyId
+        ? copies.find((copy) => copy.copyId === options.copyId)
+        : copies.find((copy) => copy.verifiedAt);
+    if (!chosen) {
+        fail("archive_not_found", options.copyId
+            ? `Archive ${archiveId} has no stored copy ${options.copyId}`
+            : `Archive ${archiveId} has no verified stored copy to restore`, { archiveId, copyId: options.copyId });
+    }
+    const { freeBytes, resolveReserveBytes } = await import("./disk.js");
+    const [free, reserve] = await Promise.all([
+        freeBytes(dirname(record.objectPath)),
+        resolveReserveBytes(dataDir),
+    ]);
+    const needed = record.cipher.storedBytes;
+    if (free !== undefined && free < needed + reserve) {
+        const gb = (value) => `${(value / 1024 ** 3).toFixed(1)} GB`;
+        fail("insufficient_disk_space", `Restoring archive ${archiveId.slice(0, 8)} needs about ${gb(needed)} plus ${gb(reserve)} of working room; this disk has ${gb(free)} free. Nothing was downloaded.`, { archiveId, free, needed, reserve });
+    }
+    await mkdir(dirname(record.objectPath), { recursive: true, mode: 0o700 });
+    const temporary = `${record.objectPath}.${randomUUID()}.restore`;
+    let writtenBytes = 0;
+    try {
+        // Provider bytes land directly in a private temporary file. Hashing is in
+        // the same write loop, so no complete archive exists in memory and an
+        // invalid response never reaches the canonical pathname.
+        const measured = await writeChunksToFile(temporary, await fetchCiphertextStream(dataDir, record, options.client, chosen, options.overrides, options.signal), { mode: 0o600, expectedBytes: record.cipher.storedBytes, signal: options.signal, onProgress: options.onProgress });
+        if (measured.sha256Hex !== record.cipher.ciphertextSha256 || measured.bytes !== record.cipher.storedBytes) {
+            fail("ciphertext_integrity_failed", `Stored copy ${chosen.copyId} is not archive ${archiveId}; nothing was written`, { archiveId, copyId: chosen.copyId });
+        }
+        writtenBytes = measured.bytes;
+        await rename(temporary, record.objectPath);
+        await mutateArchiveRecord(config.storage.root, archiveId, (current) => {
+            if (!isV2(current))
+                return current;
+            const { offloaded: _offloaded, ...withLocalCopy } = current;
+            return withLocalCopy;
+        });
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    await recordAudit(dataDir, "archive.restore_local", "allowed", { archiveId, copyId: chosen.copyId ?? null, bytes: writtenBytes }).catch(() => undefined);
+    return { restored: true, alreadyPresent: false, bytes: writtenBytes, path: record.objectPath };
+}
+/**
+ * Restore one logical session's complete encrypted delta chain.
+ *
+ * Every missing link is downloaded into a private sibling temporary file and
+ * checked against its authenticated ciphertext length and digest first. Only
+ * after the *whole* chain passes are the files hard-linked into their canonical
+ * paths. A hard link gives us an exclusive publish operation: another process
+ * cannot race this restore into overwriting an existing archive. If any publish
+ * fails, every path published by this call is removed again, while all remote
+ * copies and archive records remain untouched.
+ *
+ * Metadata is changed only after every required local file exists. A metadata
+ * write failure deliberately keeps the complete verified local chain as an
+ * extra safe copy and leaves all remote copies in place; it can never expose a
+ * head without its base or authorize a provider delete.
+ */
+export async function restoreArchiveChainLocal(dataDir, archiveId, options = {}) {
+    const config = await readConfig(dataDir);
+    const archives = await listArchives(dataDir);
+    const record = archives.find((item) => item.id === archiveId);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+    if (!isV2(record))
+        fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
+    const chain = resolveDeltaChain(archives, record);
+    const alreadyPresent = [];
+    const missing = [];
+    // Refuse conflicting local paths before making a provider request. A
+    // same-name file is not evidence that a chain dependency is present.
+    for (const item of chain) {
+        if (!isV2(item))
+            fail("invalid_argument", `Archive ${item.id} uses format v1. Run: sealkeep migrate`, { archiveId: item.id });
+        const present = await stat(item.objectPath).then((entry) => entry.isFile()).catch(() => false);
+        if (present) {
+            const { hashFileRange } = await import("../packages/sealkeep-crypto/src/index.js");
+            const measured = await hashFileRange(item.objectPath);
+            if (measured.bytes !== item.cipher.storedBytes || measured.sha256 !== item.cipher.ciphertextSha256) {
+                fail("ciphertext_integrity_failed", `A file already exists at ${item.objectPath}, but it is not archive ${item.id}. It was left untouched.`, {
+                    archiveId: item.id,
+                    path: item.objectPath,
+                    deltaDependency: item.id !== archiveId,
+                });
+            }
+            alreadyPresent.push(item);
+            continue;
+        }
+        const requestedCopyId = options.copyIds?.[item.id]
+            ?? (item.id === archiveId ? options.copyId : undefined);
+        const copies = archiveCopies(item);
+        const chosen = requestedCopyId
+            ? copies.find((copy) => copy.copyId === requestedCopyId && copy.verifiedAt)
+            : copies.find((copy) => copy.verifiedAt);
+        if (!chosen) {
+            fail("archive_not_found", requestedCopyId
+                ? `Archive ${item.id} no longer has verified stored copy ${requestedCopyId}; no local chain was published.`
+                : `Archive ${item.id} has no verified stored copy; no local chain was published.`, {
+                archiveId: item.id,
+                copyId: requestedCopyId,
+                deltaDependency: item.id !== archiveId,
+            });
+        }
+        missing.push({
+            record: item,
+            copy: chosen,
+            temporary: `${item.objectPath}.${randomUUID()}.restore`,
+        });
+    }
+    const needed = missing.reduce((sum, item) => sum + item.record.cipher.storedBytes, 0);
+    if (needed > 0) {
+        const { freeBytes, resolveReserveBytes } = await import("./disk.js");
+        const [free, reserve] = await Promise.all([
+            freeBytes(dirname(record.objectPath)),
+            resolveReserveBytes(dataDir),
+        ]);
+        if (free !== undefined && free < needed + reserve) {
+            const gb = (value) => `${(value / 1024 ** 3).toFixed(1)} GB`;
+            fail("insufficient_disk_space", `Restoring this ${chain.length}-link session chain needs about ${gb(needed)} plus ${gb(reserve)} of working room; this disk has ${gb(free)} free. Nothing was downloaded.`, { archiveId, chain: chain.map((item) => item.id), free, needed, reserve });
+        }
+    }
+    const staged = [];
+    const published = [];
+    try {
+        // Stage and prove every byte before publishing even the oldest base.
+        for (const item of missing) {
+            await mkdir(dirname(item.record.objectPath), { recursive: true, mode: 0o700 });
+            const measured = await writeChunksToFile(item.temporary, await fetchCiphertextStream(dataDir, item.record, options.client, item.copy, options.overrides), { mode: 0o600, expectedBytes: item.record.cipher.storedBytes });
+            if (measured.sha256Hex !== item.record.cipher.ciphertextSha256
+                || measured.bytes !== item.record.cipher.storedBytes) {
+                fail("ciphertext_integrity_failed", `Stored copy ${item.copy.copyId} is not archive ${item.record.id}; no local chain was published.`, {
+                    archiveId: item.record.id,
+                    copyId: item.copy.copyId,
+                    deltaDependency: item.record.id !== archiveId,
+                });
+            }
+            staged.push(item);
+        }
+        // Hard-link publication is exclusive and cannot overwrite a path that
+        // appeared after the preflight. All links live beside their destinations,
+        // so this never crosses a filesystem boundary.
+        for (const item of staged) {
+            await hardLink(item.temporary, item.record.objectPath);
+            published.push(item);
+        }
+    }
+    catch (error) {
+        for (const item of published.reverse())
+            await rm(item.record.objectPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        for (const item of missing)
+            await rm(item.temporary, { force: true }).catch(() => undefined);
+    }
+    // Every link is now physically present and verified. Clear stale
+    // remote-only locators without forgetting any durable remote copy.
+    for (const item of chain) {
+        if (!isV2(item) || !item.offloaded)
+            continue;
+        await mutateArchiveRecord(config.storage.root, item.id, (current) => {
+            if (!isV2(current))
+                return current;
+            const { offloaded: _offloaded, ...withLocalCopy } = current;
+            return withLocalCopy;
+        });
+    }
+    const restoredArchiveIds = missing.map((item) => item.record.id);
+    const alreadyPresentArchiveIds = alreadyPresent.map((item) => item.id);
+    const totalBytes = chain.reduce((sum, item) => sum + (isV2(item) ? item.cipher.storedBytes : 0), 0);
+    const restoredBytes = missing.reduce((sum, item) => sum + item.record.cipher.storedBytes, 0);
+    await recordAudit(dataDir, "archive.restore_local", "allowed", {
+        archiveId,
+        chainLength: chain.length,
+        restoredCount: restoredArchiveIds.length,
+        alreadyPresentCount: alreadyPresentArchiveIds.length,
+        bytes: restoredBytes,
+    }).catch(() => undefined);
+    return {
+        restored: missing.length > 0,
+        alreadyPresent: missing.length === 0,
+        bytes: totalBytes,
+        restoredBytes,
+        path: record.objectPath,
+        chain: chain.map((item) => item.id),
+        restoredArchiveIds,
+        alreadyPresentArchiveIds,
+    };
 }
 /**
  * Gives back a local path holding this archive's ciphertext, fetching it first
@@ -317,28 +1892,161 @@ export async function checkRemoteCopyMany(dataDir, ids, client) {
  * one and removed afterwards, which keeps the disk saving intact: the bytes are
  * on this machine only for as long as the restore takes.
  */
-export async function materialiseArchive(dataDir, record, client) {
-    if (!isV2(record) || !record.offloaded)
+export async function materialiseArchive(dataDir, record, client, options = {}) {
+    if (!isV2(record) || (!record.offloaded && !options.copyId))
         return { path: record.objectPath, release: async () => { } };
+    const selected = options.copyId
+        ? archiveCopies(record).find((copy) => copy.copyId === options.copyId)
+        : archiveCopies(record).find((copy) => copy.provider === record.offloaded?.provider
+            && copy.bucket === record.offloaded.bucket
+            && copy.objectKey === record.offloaded.objectKey);
+    if (!selected) {
+        fail("archive_not_found", options.copyId
+            ? `Archive ${record.id} has no stored copy ${options.copyId}`
+            : `Archive ${record.id} has no stored copy matching its offloaded locator`, { archiveId: record.id, copyId: options.copyId });
+    }
+    const ownedPath = options.path;
+    if (ownedPath) {
+        const existing = await stat(ownedPath).then((entry) => entry.isFile()).catch(() => false);
+        if (existing) {
+            const { hashFileRange } = await import("../packages/sealkeep-crypto/src/index.js");
+            const measured = await hashFileRange(ownedPath, 0, undefined, options.onProgress, options.signal);
+            if (measured.sha256 !== record.cipher.ciphertextSha256) {
+                fail("ciphertext_integrity_failed", `The transfer staging file for archive ${record.id} is not the recorded ciphertext. It was left untouched.`, { archiveId: record.id, path: ownedPath });
+            }
+            return {
+                path: ownedPath,
+                release: async () => {
+                    await rm(ownedPath, { force: true });
+                    await rm(`${ownedPath}.partial`, { force: true });
+                },
+            };
+        }
+    }
+    const spaceRoot = ownedPath ? dirname(ownedPath) : options.scratchRoot ?? tmpdir();
+    if (ownedPath)
+        await mkdir(spaceRoot, { recursive: true, mode: 0o700 });
+    // Claim the shared scratch lane BEFORE measuring free space. Holding this
+    // permit through `release()` makes the measurement and the archive-sized
+    // lifetime one atomic decision with respect to parent and child processes.
+    const releaseScratchPermit = await acquireScratchMaterialisationPermit(dataDir, spaceRoot, options.signal, options.scratchWaitMs);
+    let permitReleaseComplete = false;
+    let permitReleaseInFlight;
+    const relinquishPermit = () => {
+        if (permitReleaseComplete)
+            return Promise.resolve();
+        if (permitReleaseInFlight)
+            return permitReleaseInFlight;
+        const attempt = (async () => { await releaseScratchPermit(); })();
+        permitReleaseInFlight = attempt;
+        attempt.then(() => {
+            permitReleaseComplete = true;
+            if (permitReleaseInFlight === attempt)
+                permitReleaseInFlight = undefined;
+        }, () => { if (permitReleaseInFlight === attempt)
+            permitReleaseInFlight = undefined; });
+        return attempt;
+    };
     // Reading an offloaded archive means writing it back to disk in full, and
     // this runs in a loop during an index build. On a machine that offloaded
     // BECAUSE it was short of space, that filled the disk and died on ENOSPC
     // mid-build — the exact failure this product exists to prevent. Ask first,
     // and refuse in words that name the archive and the shortfall.
-    const { freeBytes } = await import("./disk.js");
-    const free = await freeBytes(tmpdir());
-    const needed = record.cipher.storedBytes ?? record.remote?.bytes ?? 0;
-    const RESERVE = 512 * 1024 * 1024;
-    if (free !== undefined && needed > 0 && free < needed + RESERVE) {
-        const gb = (n) => `${(n / 1024 ** 3).toFixed(1)} GB`;
-        fail("insufficient_disk_space", `Reading archive ${record.id.slice(0, 8)} needs about ${gb(needed)} of temporary space and this machine has ${gb(free)} free. Nothing was written. Free some space, or reclaim what is already archived, and try again.`, { archiveId: record.id, free, needed });
-    }
-    const ciphertext = await fetchCiphertext(dataDir, record, client);
-    if (sha256(ciphertext) !== record.cipher.ciphertextSha256) {
-        fail("ciphertext_integrity_failed", `The copy of archive ${record.id} in ${record.offloaded.bucket} is not the archive that was stored there`, { archiveId: record.id });
-    }
-    const scratch = await mkdtemp(join(tmpdir(), "vaultline-fetch-"));
-    const path = join(scratch, `${record.id}.vlarchive`);
-    await writeFile(path, ciphertext, { mode: 0o600 });
-    return { path, release: async () => { await rm(scratch, { recursive: true, force: true }); } };
+    let scratch;
+    let path = ownedPath ?? "";
+    let partial = "";
+    let cleanFiles;
+    try {
+        if (options.signal?.aborted)
+            throw cancellationError(options.signal);
+        const { freeBytes, resolveReserveBytes } = await import("./disk.js");
+        const [free, reserve] = await Promise.all([freeBytes(spaceRoot), resolveReserveBytes(dataDir)]);
+        const needed = record.cipher.storedBytes ?? record.remote?.bytes ?? 0;
+        if (free !== undefined && needed > 0 && free < needed + reserve) {
+            const gb = (n) => `${(n / 1024 ** 3).toFixed(1)} GB`;
+            fail("insufficient_disk_space", `Reading archive ${record.id.slice(0, 8)} needs about ${gb(needed)} of temporary space plus ${gb(reserve)} kept free for this machine; only ${gb(free)} is available. Nothing was written. Free space before trying this operation again.`, { archiveId: record.id, free, needed, reserve });
+        }
+        scratch = ownedPath ? undefined : await mkdtemp(join(spaceRoot, "sealkeep-fetch-"));
+        path = ownedPath ?? join(scratch, `${record.id}.skarchive`);
+        partial = `${path}.partial`;
+        cleanFiles = ownedPath
+            ? async () => {
+                await rm(path, { force: true });
+                await rm(partial, { force: true });
+            }
+            : async () => { await rm(scratch, { recursive: true, force: true }); };
+        // A deterministic partial belongs to the same journaled owner as `path`.
+        // A crash may leave it behind; the next attempt removes exactly that file
+        // before writing, and a successful rename never exposes partial bytes.
+        await rm(partial, { force: true });
+        const downloaded = await fetchCiphertextStream(dataDir, record, client, selected, options.overrides, options.signal, undefined, options.maxBytesPerSecond);
+        const cooperative = (async function* () {
+            for await (const chunk of downloaded) {
+                yield chunk;
+                await options.onYield?.();
+            }
+        })();
+        const measured = await writeChunksToFile(partial, cooperative, { mode: 0o600, signal: options.signal, expectedBytes: record.cipher.storedBytes, onProgress: options.onProgress });
+        if (measured.sha256Hex !== record.cipher.ciphertextSha256 || measured.bytes !== record.cipher.storedBytes) {
+            fail("ciphertext_integrity_failed", `The copy of archive ${record.id} in ${selected.bucket} is not the archive that was stored there`, { archiveId: record.id, copyId: selected.copyId });
+        }
+        await rename(partial, path);
+        let releaseComplete = false;
+        let releaseInFlight;
+        return {
+            path,
+            release: () => {
+                if (releaseComplete)
+                    return Promise.resolve();
+                if (releaseInFlight)
+                    return releaseInFlight;
+                const attempt = (async () => {
+                    // Deleting the bytes is the admission boundary. If cleanup fails,
+                    // retain both the in-process lane and cross-process lease so another
+                    // archive cannot be admitted on top of space that still exists. The
+                    // idempotent release handle lets its owner retry the exact cleanup.
+                    await cleanFiles();
+                    await relinquishPermit();
+                })();
+                releaseInFlight = attempt;
+                attempt.then(() => {
+                    releaseComplete = true;
+                    if (releaseInFlight === attempt)
+                        releaseInFlight = undefined;
+                }, () => { if (releaseInFlight === attempt)
+                    releaseInFlight = undefined; });
+                return attempt;
+            },
+        };
+    }
+    catch (error) {
+        let cleanupError;
+        try {
+            if (cleanFiles)
+                await cleanFiles();
+            else {
+                if (partial)
+                    await rm(partial, { force: true });
+                if (scratch)
+                    await rm(scratch, { recursive: true, force: true });
+            }
+        }
+        catch (cleanupFailure) {
+            cleanupError = cleanupFailure;
+        }
+        if (cleanupError) {
+            // There is no materialised handle to return on a failed fetch, so fail
+            // visibly and keep the reservation for the lifetime of this process.
+            // Releasing it while unknown scratch bytes remain would violate the disk
+            // reserve; a service restart makes the exact-generation lease reclaimable.
+            throw withScratchReleaseFailure(error, cleanupError);
+        }
+        try {
+            await relinquishPermit();
+        }
+        catch (releaseError) {
+            throw withScratchReleaseFailure(error, releaseError);
+        }
+        throw error;
+    }
 }