sealkeep 0.9.0 → 0.11.0

package/dist/src/cloud.js

@@ -1,12 +1,17 @@
-import { createHash } from "node:crypto";
-import { readFile, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { chooseBackend } from "./secrets.js";
-import { encryptArchive as sealEnvelope, decryptArchive as openEnvelope, x25519PrivateKeyFromRaw, x25519PublicKeyFromRaw } from "../packages/vaultline-crypto/src/index.js";
+import { encryptArchive as sealEnvelope, decryptArchive as openEnvelope, x25519PrivateKeyFromRaw, x25519PublicKeyFromRaw } from "../packages/sealkeep-crypto/src/index.js";
 import { canonicalPhrase } from "./mnemonic.js";
-import { fail, isVaultlineError, VaultlineError } from "./errors.js";
+import { fail, isSealkeepError, SealkeepError } from "./errors.js";
 import { sha256 } from "./crypto.js";
-import { listArchives, readConfig, writeRecord } from "./vault.js";
+import { listArchives, mutateArchiveRecord, readConfig } from "./vault.js";
 import { envVar } from "./env.js";
+import { appendArchiveCopy } from "./archive-copies.js";
+import { collectChunks, bufferChunks, concatStreams, digestChunks, fileChunks, fileHandleChunks, LEGACY_BUFFER_LIMIT_BYTES, MAX_FRAME_METADATA_BYTES, oneChunk, requestBody, responseBodyChunks, tapDigest, unframeChunks, } from "./byte-stream.js";
+import { paceBackgroundByteStream } from "./background-bandwidth.js";
+import { readTeamIndexCache, writeTeamIndexCache } from "./team-index-cache.js";
 /**
  * Sealkeep Cloud: the managed tier.
  *
@@ -17,7 +22,300 @@ import { envVar } from "./env.js";
  * control plane is never sent a key that opens it.
  */
 export const DEFAULT_CLOUD_URL = "https://shared.spala.ai/p04946/api";
-const cloudUrl = (env = process.env) => (envVar("CLOUD_URL", env) ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+export const cloudUrl = (env = process.env) => (envVar("CLOUD_URL", env) ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+const authGenerationPath = (dataDir) => join(dataDir, "runtime", "cloud-auth-generation");
+const AUTH_TRANSITION_PREFIX = "transition:";
+const cloudAuthMutationTails = new Map();
+const AUTH_LOCK_WAIT_MS = 30_000;
+const AUTH_LOCK_OWNER_GRACE_MS = 2_000;
+const authLockPath = (dataDir) => join(dataDir, "runtime", "cloud-auth-transition.lock");
+const authLockOwnerPath = (lockPath) => join(lockPath, "owner.json");
+const abortReason = (signal, fallback) => {
+    if (signal.reason !== undefined)
+        return signal.reason;
+    const error = new Error(fallback);
+    error.name = "AbortError";
+    return error;
+};
+const pause = async (milliseconds, signal) => {
+    if (!signal)
+        return new Promise((resolvePause) => setTimeout(resolvePause, milliseconds));
+    const activeSignal = signal;
+    activeSignal.throwIfAborted();
+    await new Promise((resolvePause, rejectPause) => {
+        const timer = setTimeout(done, milliseconds);
+        const aborted = () => {
+            clearTimeout(timer);
+            activeSignal.removeEventListener("abort", aborted);
+            rejectPause(abortReason(activeSignal, "The Sealkeep Cloud request was cancelled"));
+        };
+        function done() {
+            activeSignal.removeEventListener("abort", aborted);
+            resolvePause();
+        }
+        activeSignal.addEventListener("abort", aborted, { once: true });
+    });
+};
+/**
+ * Share a control-plane mutation without making one caller's timeout cancel
+ * siblings which are still waiting for it. When every waiter has left, the
+ * underlying fetch is aborted too, so a dead request cannot poison the
+ * single-flight slot forever.
+ */
+async function awaitSharedAbortable(entry, signal) {
+    signal?.throwIfAborted();
+    entry.waiters += 1;
+    let onAbort;
+    const cancelled = signal
+        ? new Promise((_resolve, reject) => {
+            onAbort = () => reject(abortReason(signal, "The Sealkeep Cloud request was cancelled"));
+            signal.addEventListener("abort", onAbort, { once: true });
+        })
+        : null;
+    try {
+        return await (cancelled ? Promise.race([entry.promise, cancelled]) : entry.promise);
+    }
+    finally {
+        if (signal && onAbort)
+            signal.removeEventListener("abort", onAbort);
+        entry.waiters -= 1;
+        if (!entry.settled && entry.waiters === 0 && !entry.controller.signal.aborted) {
+            const error = new Error("The Sealkeep Cloud request no longer has an active caller");
+            error.name = "AbortError";
+            entry.controller.abort(error);
+        }
+    }
+}
+async function readCloudAuthLockOwner(lockPath) {
+    try {
+        const parsed = JSON.parse(await readFile(authLockOwnerPath(lockPath), "utf8"));
+        if (parsed.version !== 1 || !Number.isSafeInteger(parsed.pid) || Number(parsed.pid) < 1
+            || typeof parsed.nonce !== "string" || !parsed.nonce || typeof parsed.acquiredAt !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM proves the process exists even though this user cannot signal it.
+        return error.code === "EPERM";
+    }
+}
+async function retireStaleCloudAuthLock(lockPath) {
+    const [owner, info] = await Promise.all([
+        readCloudAuthLockOwner(lockPath),
+        stat(lockPath).catch(() => null),
+    ]);
+    // mkdir is atomic but owner.json is a second write. Give the winning process
+    // time to publish it before treating an ownerless directory as abandoned.
+    if (!owner && info && Date.now() - info.mtimeMs < AUTH_LOCK_OWNER_GRACE_MS)
+        return false;
+    if (owner && processIsAlive(owner.pid))
+        return false;
+    const retired = `${lockPath}.${randomUUID()}.stale`;
+    try {
+        await rename(lockPath, retired);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        return false;
+    }
+    // The rename already released the well-known lock. Cleanup is deliberately
+    // narrow: never recursively remove an unexpected directory in a vault.
+    await unlink(authLockOwnerPath(retired)).catch(() => undefined);
+    await rmdir(retired).catch(() => undefined);
+    return true;
+}
+async function acquireCloudAuthLock(dataDir) {
+    const lockPath = authLockPath(dataDir);
+    await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + AUTH_LOCK_WAIT_MS;
+    const owner = {
+        version: 1,
+        pid: process.pid,
+        nonce: randomUUID(),
+        acquiredAt: new Date().toISOString(),
+    };
+    while (true) {
+        try {
+            await mkdir(lockPath, { mode: 0o700 });
+            try {
+                await writeFile(authLockOwnerPath(lockPath), JSON.stringify(owner) + "\n", { flag: "wx", mode: 0o600 });
+            }
+            catch (error) {
+                await rmdir(lockPath).catch(() => undefined);
+                throw error;
+            }
+            return async () => {
+                const current = await readCloudAuthLockOwner(lockPath);
+                if (current?.nonce !== owner.nonce)
+                    return;
+                await unlink(authLockOwnerPath(lockPath)).catch(() => undefined);
+                await rmdir(lockPath).catch(() => undefined);
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (await retireStaleCloudAuthLock(lockPath))
+                continue;
+            if (Date.now() >= deadline) {
+                fail("cloud_account_unavailable", "Another Sealkeep process is still changing this machine's Cloud sign-in. Retry in a moment.");
+            }
+            await pause(25 + Math.floor(Math.random() * 50));
+        }
+    }
+}
+async function writeCloudAuthGeneration(dataDir, value) {
+    // Drop process-held credentials before publishing either edge of a
+    // transition. Cross-process readers observe the generation file; readers in
+    // this process additionally release their old secret references immediately.
+    invalidateCloudAuthReadCache(dataDir);
+    const path = authGenerationPath(dataDir);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, value + "\n", { mode: 0o600 });
+    await rename(temporary, path);
+}
+async function serializeCloudAuthMutation(dataDir, work) {
+    const key = resolve(dataDir);
+    const previous = cloudAuthMutationTails.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolveGate) => { release = resolveGate; });
+    const tail = previous.catch(() => undefined).then(() => gate);
+    cloudAuthMutationTails.set(key, tail);
+    await previous.catch(() => undefined);
+    let releaseCrossProcess;
+    try {
+        releaseCrossProcess = await acquireCloudAuthLock(dataDir);
+        return await work();
+    }
+    finally {
+        await releaseCrossProcess?.();
+        release();
+        if (cloudAuthMutationTails.get(key) === tail)
+            cloudAuthMutationTails.delete(key);
+    }
+}
+export async function signalCloudAuthChange(dataDir) {
+    await serializeCloudAuthMutation(dataDir, () => writeCloudAuthGeneration(dataDir, randomUUID()));
+}
+/** Cheap generation probe used by long-running services; contains no token. */
+export async function cloudAuthGeneration(dataDir) {
+    try {
+        return (await readFile(authGenerationPath(dataDir), "utf8")).trim() || null;
+    }
+    catch (error) {
+        // Missing is the legacy, pre-generation state. Permission, I/O and corrupt
+        // path failures are not equivalent: treating those as the reusable null
+        // generation could let a process cache survive a credential transition it
+        // was unable to observe.
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+const sameSecretRef = (left, right) => (left.service === right.service && left.account === right.account);
+async function settleCredential(backend, mutation) {
+    if (mutation.value === null)
+        await backend.delete(mutation.ref);
+    else
+        await backend.set(mutation.ref, mutation.value);
+    const settled = await backend.get(mutation.ref);
+    if (settled !== mutation.value) {
+        throw new Error(`The ${mutation.ref.service} credential change did not settle in the native secret backend`);
+    }
+}
+/**
+ * Changes account credentials without ever publishing them under an old cache
+ * scope. The transition marker is durable and written before the first secret:
+ * readers refuse it. A second atomic write publishes the new stable scope only
+ * after every secret has been read back successfully.
+ *
+ * If a secret or the final generation write fails, every old secret is restored
+ * and a fresh rollback scope is published. If even that last write cannot land
+ * (for example a completely full disk), the transition marker deliberately
+ * remains: Cloud reads stay closed instead of guessing which account owns the
+ * credentials. A later successful login/logout can replace that marker.
+ */
+export async function commitCloudAuthCredentials(dataDir, backend, requested, dependencies = {}) {
+    const mutations = [];
+    for (const mutation of requested) {
+        const at = mutations.findIndex((existing) => sameSecretRef(existing.ref, mutation.ref));
+        if (at >= 0)
+            mutations[at] = mutation;
+        else
+            mutations.push(mutation);
+    }
+    if (!mutations.length)
+        return;
+    await serializeCloudAuthMutation(dataDir, async () => {
+        const writeGeneration = dependencies.writeGeneration ?? writeCloudAuthGeneration;
+        if (Object.hasOwn(dependencies, "expectedAuthGeneration")) {
+            const observed = await cloudAuthGeneration(dataDir);
+            if (authTransitionInProgress(observed) || observed !== dependencies.expectedAuthGeneration) {
+                fail("cloud_account_unavailable", "Sealkeep Cloud sign-in changed while this credential update was in flight. The older update was discarded.");
+            }
+        }
+        invalidateCloudAuthReadCache(dataDir);
+        const previous = await Promise.all(mutations.map(async ({ ref }) => ({ ref, value: await backend.get(ref) })));
+        const transitionId = randomUUID();
+        // This is the transaction's prepare record. If it cannot be made durable,
+        // no credential is touched — important on a nearly full machine.
+        await writeGeneration(dataDir, `${AUTH_TRANSITION_PREFIX}${transitionId}`);
+        try {
+            for (const mutation of mutations)
+                await settleCredential(backend, mutation);
+            await writeGeneration(dataDir, transitionId);
+        }
+        catch (error) {
+            let rollbackFailed = false;
+            for (const old of [...previous].reverse()) {
+                try {
+                    await settleCredential(backend, old);
+                }
+                catch {
+                    rollbackFailed = true;
+                }
+            }
+            if (!rollbackFailed) {
+                // Never restore the generation from before the transaction: a reader
+                // may have observed a transient secret. A new scope invalidates it.
+                await writeGeneration(dataDir, randomUUID()).catch(() => undefined);
+            }
+            throw error;
+        }
+    });
+}
+function authTransitionInProgress(generation) {
+    return generation?.startsWith(AUTH_TRANSITION_PREFIX) ?? false;
+}
+/**
+ * Seqlock for credential readers. A reader which overlaps either edge of an
+ * auth transaction must retry; otherwise an old token can be paired with the
+ * new generation (or the reverse) even though both individual writes are
+ * atomic. Exported as a narrow test seam so the overlap is deterministic.
+ */
+export async function readCloudAuthSnapshot(dataDir, read) {
+    const before = await cloudAuthGeneration(dataDir);
+    if (authTransitionInProgress(before)) {
+        fail("cloud_account_unavailable", "Sealkeep Cloud sign-in is changing on this machine. Retry in a moment.");
+    }
+    const value = await read();
+    const after = await cloudAuthGeneration(dataDir);
+    if (authTransitionInProgress(after) || after !== before) {
+        fail("cloud_account_unavailable", "Sealkeep Cloud sign-in changed while this request was starting. Retry the request.");
+    }
+    return value;
+}
 /**
  * Where this vault's cloud token lives in the keystore.
  *
@@ -35,41 +333,740 @@ const cloudUrl = (env = process.env) => (envVar("CLOUD_URL", env) ?? DEFAULT_CLO
  * definition, imported, so a change here cannot leave the other behind.
  */
 export function tokenRefFor(vaultId, env = process.env) {
-    return { service: "vaultline-cloud", account: `${vaultId}@${cloudUrl(env)}` };
+    return { service: "sealkeep-cloud", account: `${vaultId}@${cloudUrl(env)}` };
+}
+/**
+ * A fresh install has no vault id yet. Its Cloud pairing therefore waits in
+ * the native secret backend under a data-directory-scoped bootstrap key until
+ * this machine either creates a new vault or adopts an approved existing one.
+ * The hash prevents two independent SealKeep homes on the same OS account from
+ * inheriting one another's login without putting the local path in keychain UI.
+ */
+export function bootstrapTokenRefFor(dataDir, env = process.env) {
+    const scope = createHash("sha256").update(resolve(dataDir)).digest("hex");
+    return { service: "sealkeep-cloud-bootstrap", account: `${scope}@${cloudUrl(env)}` };
 }
 async function tokenRef(dataDir) {
     const { readConfig } = await import("./vault.js");
-    const { vaultId } = await readConfig(dataDir);
-    return tokenRefFor(vaultId);
+    const config = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    return config ? tokenRefFor(config.vaultId) : bootstrapTokenRefFor(dataDir);
+}
+/**
+ * Where this machine's own credential lives, beside the account token.
+ *
+ * The account token says *which account* is calling and nothing more — every
+ * laptop paired to a company account presents an identical one. That is fine
+ * for reading and for adding, and wrong for destroying: without a second fact
+ * the control plane cannot tell one machine's delete from another's, so any
+ * laptop could erase a colleague's sealed history and the audit row would name
+ * only the account. The machine key is that second fact. It is minted once at
+ * pairing, the server keeps only a bcrypt of it, and it rides in the request
+ * body rather than a header because this control plane strips request headers
+ * before endpoint logic ever sees them — proven, not assumed.
+ */
+export function machineRefFor(vaultId, env = process.env) {
+    return { service: "sealkeep-machine", account: `${vaultId}@${cloudUrl(env)}` };
+}
+export function bootstrapMachineRefFor(dataDir, env = process.env) {
+    const scope = createHash("sha256").update(resolve(dataDir)).digest("hex");
+    return { service: "sealkeep-machine-bootstrap", account: `${scope}@${cloudUrl(env)}` };
+}
+async function cloudCredentialRefs(dataDir) {
+    const config = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    return {
+        vaultId: config?.vaultId ?? null,
+        token: config ? tokenRefFor(config.vaultId) : bootstrapTokenRefFor(dataDir),
+        bootstrapToken: bootstrapTokenRefFor(dataDir),
+        machine: config ? machineRefFor(config.vaultId) : bootstrapMachineRefFor(dataDir),
+        bootstrapMachine: bootstrapMachineRefFor(dataDir),
+    };
+}
+// A daemon asks for the same two secrets from several independent lanes. Keep
+// the successful values for long enough to remove native-process churn, but
+// periodically re-probe backend availability. A missing or malformed value is
+// only a short backoff because native helpers cannot always distinguish a
+// locked store from an absent item.
+const CLOUD_AUTH_POSITIVE_CACHE_MS = 60_000;
+const CLOUD_AUTH_NEGATIVE_CACHE_MS = 2_000;
+const CLOUD_AUTH_CACHE_MAX_SCOPES = 64;
+// A completed generation change discards the first snapshot and gets one fresh
+// attempt. This keeps a machine-registration publish from spuriously failing
+// sibling daemon lanes. Transitional and unreadable generations throw from
+// stableCloudAuthGeneration and are never converted into a retryable mismatch.
+const CLOUD_AUTH_SNAPSHOT_ATTEMPTS = 2;
+const cloudAuthReadCache = new Map();
+function sameCloudCredentialRefs(left, right) {
+    return left.vaultId === right.vaultId
+        && sameSecretRef(left.token, right.token)
+        && sameSecretRef(left.bootstrapToken, right.bootstrapToken)
+        && sameSecretRef(left.machine, right.machine)
+        && sameSecretRef(left.bootstrapMachine, right.bootstrapMachine);
+}
+function invalidateCloudAuthReadCache(dataDir) {
+    if (dataDir === undefined) {
+        cloudAuthReadCache.clear();
+        return;
+    }
+    const canonical = resolve(dataDir);
+    for (const [key, scope] of cloudAuthReadCache) {
+        if (scope.dataDir === canonical)
+            cloudAuthReadCache.delete(key);
+    }
+}
+async function stableCloudAuthGeneration(dataDir) {
+    const key = resolve(dataDir);
+    for (;;) {
+        const localMutation = cloudAuthMutationTails.get(key);
+        if (localMutation)
+            await localMutation.catch(() => undefined);
+        const generation = await cloudAuthGeneration(dataDir);
+        if (!authTransitionInProgress(generation))
+            return generation;
+        // A mutation can begin after the first tail lookup and publish its
+        // transition marker before the generation read. Join that known local
+        // writer, then probe again. An unowned marker is cross-process (or
+        // abandoned), so it must remain fail-closed instead of being waited out.
+        const transitionOwner = cloudAuthMutationTails.get(key);
+        if (!transitionOwner) {
+            fail("cloud_account_unavailable", "Sealkeep Cloud sign-in is changing on this machine. Retry in a moment.");
+        }
+        await transitionOwner.catch(() => undefined);
+    }
+}
+function cloudAuthScopeKey(dataDir, generation, backendSelector, refs) {
+    // No credential value is ever part of this key. The exact native refs carry
+    // the vault and Cloud URL; the generation carries the account session.
+    return JSON.stringify([
+        dataDir, generation, backendSelector,
+        refs.token.service, refs.token.account,
+        refs.machine.service, refs.machine.account,
+    ]);
+}
+function boundedCloudAuthCacheInsert(scope) {
+    while (cloudAuthReadCache.size >= CLOUD_AUTH_CACHE_MAX_SCOPES) {
+        const oldest = cloudAuthReadCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cloudAuthReadCache.delete(oldest);
+    }
+    cloudAuthReadCache.set(scope.key, scope);
+}
+async function cloudAuthCacheScope(dataDir, preferred) {
+    const canonical = resolve(dataDir);
+    const generation = await stableCloudAuthGeneration(dataDir);
+    const refs = await cloudCredentialRefs(dataDir);
+    const backendSelector = preferred ?? envVar("SECRET_BACKEND") ?? "<automatic>";
+    const key = cloudAuthScopeKey(canonical, generation, backendSelector, refs);
+    const now = Date.now();
+    let scope = cloudAuthReadCache.get(key);
+    if (scope && scope.hardExpiresAt <= now) {
+        cloudAuthReadCache.delete(key);
+        scope = undefined;
+    }
+    if (!scope) {
+        const backend = chooseBackend(dataDir, preferred);
+        scope = {
+            key, dataDir: canonical, generation, backendSelector, refs, backend,
+            hardExpiresAt: now + CLOUD_AUTH_POSITIVE_CACHE_MS,
+        };
+        const owned = scope;
+        void backend.catch(() => { if (cloudAuthReadCache.get(key) === owned)
+            cloudAuthReadCache.delete(key); });
+        // A stable generation supersedes every older account scope for this data
+        // directory. Other backend selectors for the same generation stay isolated.
+        for (const [oldKey, old] of cloudAuthReadCache) {
+            if (old.dataDir === canonical && old.generation !== generation)
+                cloudAuthReadCache.delete(oldKey);
+        }
+        boundedCloudAuthCacheInsert(scope);
+    }
+    else {
+        // Touch for bounded LRU eviction without allocating another entry.
+        cloudAuthReadCache.delete(key);
+        cloudAuthReadCache.set(key, scope);
+    }
+    return { scope, generation, refs };
+}
+async function validateCloudAuthCacheRead(dataDir, scope, generation, refs) {
+    const refsAfter = await cloudCredentialRefs(dataDir);
+    const generationAfter = await stableCloudAuthGeneration(dataDir);
+    if (generationAfter !== generation || !sameCloudCredentialRefs(refsAfter, refs)) {
+        if (cloudAuthReadCache.get(scope.key) === scope)
+            cloudAuthReadCache.delete(scope.key);
+        return false;
+    }
+    return true;
+}
+async function cachedCloudTokenRead(dataDir, preferred) {
+    for (let attempt = 0; attempt < CLOUD_AUTH_SNAPSHOT_ATTEMPTS; attempt += 1) {
+        const { scope, generation, refs } = await cloudAuthCacheScope(dataDir, preferred);
+        const now = Date.now();
+        let cached = scope.token;
+        if (!cached || cached.expiresAt <= now) {
+            const promise = (async () => {
+                const backend = await scope.backend;
+                let found = await backend.get(refs.token);
+                if (!found && refs.token.account !== refs.bootstrapToken.account) {
+                    // As before, the token alias is read-only here. Moving it can overwrite
+                    // another process's newly selected account.
+                    found = await backend.get(refs.bootstrapToken);
+                }
+                return found || null;
+            })();
+            cached = { promise, expiresAt: Number.POSITIVE_INFINITY };
+            scope.token = cached;
+            const owned = cached;
+            void promise.then((value) => { owned.expiresAt = Date.now() + (value ? CLOUD_AUTH_POSITIVE_CACHE_MS : CLOUD_AUTH_NEGATIVE_CACHE_MS); }, () => { if (scope.token === owned)
+                scope.token = undefined; });
+        }
+        const token = await cached.promise;
+        const backend = await scope.backend;
+        if (await validateCloudAuthCacheRead(dataDir, scope, generation, refs)) {
+            return { token, generation, refs, backend };
+        }
+    }
+    return fail("cloud_account_unavailable", "Sealkeep Cloud sign-in or vault identity kept changing while this request was starting. Retry the request.");
+}
+function parseMachineCredential(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.device_id !== "number" || typeof parsed.machine_key !== "string")
+            return null;
+        return { device_id: parsed.device_id, machine_key: parsed.machine_key };
+    }
+    catch {
+        return null;
+    }
+}
+async function cachedMachineCredentialRead(dataDir, preferred) {
+    for (let attempt = 0; attempt < CLOUD_AUTH_SNAPSHOT_ATTEMPTS; attempt += 1) {
+        const { scope, generation, refs } = await cloudAuthCacheScope(dataDir, preferred);
+        const now = Date.now();
+        let cached = scope.machine;
+        if (!cached || cached.expiresAt <= now) {
+            const promise = (async () => {
+                const backend = await scope.backend;
+                let raw = await backend.get(refs.machine);
+                let fromBootstrap = false;
+                if (!raw && refs.machine.account !== refs.bootstrapMachine.account) {
+                    raw = await backend.get(refs.bootstrapMachine);
+                    fromBootstrap = Boolean(raw);
+                }
+                return { credential: parseMachineCredential(raw), raw, fromBootstrap };
+            })();
+            cached = { promise, expiresAt: Number.POSITIVE_INFINITY };
+            scope.machine = cached;
+            const owned = cached;
+            void promise.then((value) => { owned.expiresAt = Date.now() + (value.credential ? CLOUD_AUTH_POSITIVE_CACHE_MS : CLOUD_AUTH_NEGATIVE_CACHE_MS); }, () => { if (scope.machine === owned)
+                scope.machine = undefined; });
+        }
+        const read = await cached.promise;
+        const backend = await scope.backend;
+        if (await validateCloudAuthCacheRead(dataDir, scope, generation, refs)) {
+            return { read, generation, refs, backend };
+        }
+    }
+    return fail("cloud_account_unavailable", "Sealkeep Cloud sign-in or vault identity kept changing while this request was starting. Retry the request.");
+}
+async function machineRef(dataDir) {
+    return (await cloudCredentialRefs(dataDir)).machine;
+}
+/**
+ * This machine's credential, claiming one if it does not have it yet.
+ *
+ * Machines that paired before machine keys existed hold only an account token.
+ * Left alone they would keep sealing archives nothing can attribute, and the
+ * protection would silently never switch on for them — the worst kind of
+ * security change, the sort that upgrades cleanly and does nothing. So the
+ * first call that needs an identity claims one. `claim` is false on paths
+ * where a network round trip would be a surprise.
+ */
+export async function machineIdentity(dataDir, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    const existing = await machineCredential(dataDir, preferred);
+    if (existing)
+        return existing;
+    try {
+        const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+        return await registerMachine(dataDir, token, preferred, options);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw abortReason(options.signal, "Machine registration was cancelled");
+        return null;
+    }
+}
+/** This machine's credential, or null when it paired before machine keys existed. */
+export async function machineCredential(dataDir, preferred) {
+    try {
+        const snapshot = await cachedMachineCredentialRead(dataDir, preferred);
+        if (snapshot.read.fromBootstrap && snapshot.read.raw) {
+            // Alias healing is a credential mutation too. Publish it through the same
+            // generation transaction so another process never retains the old slot.
+            await commitCloudAuthCredentials(dataDir, snapshot.backend, [
+                { ref: snapshot.refs.machine, value: snapshot.read.raw },
+                { ref: snapshot.refs.bootstrapMachine, value: null },
+            ], { expectedAuthGeneration: snapshot.generation });
+        }
+        return snapshot.read.credential;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * This machine's credential as a read-only snapshot. Unlike
+ * `machineCredential`, this never migrates a pre-vault bootstrap alias and
+ * therefore cannot advance the Cloud auth generation. Advisory telemetry uses
+ * this path; operations which need a durable machine identity keep the normal
+ * healing behaviour above.
+ */
+export async function peekMachineCredential(dataDir, preferred) {
+    try {
+        return (await cachedMachineCredentialRead(dataDir, preferred)).read.credential;
+    }
+    catch {
+        return null;
+    }
+}
+const cloudMachineRegistrations = new Map();
+async function rememberMachine(dataDir, credential, backend, ref, expectedAuthGeneration) {
+    await commitCloudAuthCredentials(dataDir, backend, [{ ref, value: JSON.stringify(credential) }], { expectedAuthGeneration });
+}
+/**
+ * Announce this machine and keep the key it is handed.
+ *
+ * Best-effort on purpose: a machine that cannot register is still signed in and
+ * still archives. It is merely anonymous to the control plane, which is exactly
+ * what every machine was before this existed — so failing here must never fail
+ * a sign-in.
+ */
+export async function registerMachine(dataDir, token, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    try {
+        // Bind the network result to the exact locally stored login that authorized
+        // it. A slow registration from account A must not install A's machine key
+        // after logout or a later login selected account B.
+        const account = await cachedCloudTokenRead(dataDir, preferred);
+        if (account.token !== token)
+            return null;
+        const key = JSON.stringify([
+            resolve(dataDir), account.generation, account.backend.name,
+            account.refs.machine.service, account.refs.machine.account,
+            createHash("sha256").update(token).digest("hex"),
+        ]);
+        let running = cloudMachineRegistrations.get(key);
+        if (running?.controller.signal.aborted) {
+            cloudMachineRegistrations.delete(key);
+            running = undefined;
+        }
+        if (!running) {
+            const controller = new AbortController();
+            const entry = {
+                controller,
+                promise: Promise.resolve(null),
+                waiters: 0,
+                settled: false,
+            };
+            entry.promise = (async () => {
+                const { hostname } = await import("node:os");
+                const result = await call("/v1/cloud/devices/register", {
+                    method: "POST", token, body: JSON.stringify({ label: hostname() }), signal: controller.signal,
+                });
+                if (typeof result?.device_id !== "number" || typeof result?.machine_key !== "string")
+                    return null;
+                controller.signal.throwIfAborted();
+                const credential = { device_id: result.device_id, machine_key: result.machine_key };
+                await rememberMachine(dataDir, credential, account.backend, account.refs.machine, account.generation);
+                return credential;
+            })().finally(() => {
+                entry.settled = true;
+                if (cloudMachineRegistrations.get(key) === entry)
+                    cloudMachineRegistrations.delete(key);
+            });
+            cloudMachineRegistrations.set(key, entry);
+            running = entry;
+        }
+        return await awaitSharedAbortable(running, options.signal);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw abortReason(options.signal, "Machine registration was cancelled");
+        return null;
+    }
+}
+export async function createCloudDeviceEnrollment(dataDir, input, preferred) {
+    const machine = await machineCredential(dataDir, preferred);
+    if (!machine)
+        fail("forbidden", "This machine must have an active Cloud device identity before it can request preserved memory");
+    return call("/v1/cloud/device-enrollments", {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({
+            label: input.label,
+            public_key: input.publicKey,
+            request_secret: input.requestSecret,
+            target_device_id: machine.device_id,
+            machine_key: machine.machine_key,
+        }),
+    });
+}
+export async function listPendingCloudDeviceEnrollments(dataDir, preferred) {
+    const answer = await call("/v1/cloud/device-enrollments", {
+        token: await cloudToken(dataDir, preferred),
+    });
+    return Array.isArray(answer) ? answer : answer.requests ?? [];
+}
+export async function approveCloudDeviceEnrollment(dataDir, requestId, bundle, preferred) {
+    const machine = await machineCredential(dataDir, preferred);
+    if (!machine)
+        fail("forbidden", "This machine has no active Cloud device identity and cannot approve another machine");
+    return call(`/v1/cloud/device-enrollments/${encodeURIComponent(requestId)}/approve`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({
+            device_id: machine.device_id,
+            machine_key: machine.machine_key,
+            envelope: JSON.stringify(bundle.envelope),
+            sealed: bundle.sealed,
+        }),
+    });
+}
+export async function claimCloudDeviceEnrollment(dataDir, requestId, requestSecret, preferred) {
+    const machine = await machineCredential(dataDir, preferred);
+    if (!machine)
+        fail("forbidden", "This machine no longer has the active device identity that requested enrollment");
+    return call(`/v1/cloud/device-enrollments/${encodeURIComponent(requestId)}/claim`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ request_secret: requestSecret, target_device_id: machine.device_id, machine_key: machine.machine_key }),
+    });
+}
+export async function completeCloudDeviceEnrollment(dataDir, requestId, requestSecret, preferred) {
+    const machine = await machineCredential(dataDir, preferred);
+    if (!machine)
+        fail("forbidden", "This machine no longer has the active device identity that requested enrollment");
+    return call(`/v1/cloud/device-enrollments/${encodeURIComponent(requestId)}/complete`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ request_secret: requestSecret, target_device_id: machine.device_id, machine_key: machine.machine_key }),
+    });
+}
+export async function startCloudDeviceAuthorization(input) {
+    return call("/v1/cloud/device-authorizations", {
+        method: "POST",
+        body: JSON.stringify({
+            challenge: input.challenge,
+            label: input.label,
+            os_family: input.osFamily,
+            agents: input.agents,
+            public_key: input.publicKey,
+        }),
+    });
+}
+export async function claimCloudDeviceAuthorization(input) {
+    return call(`/v1/cloud/device-authorizations/${encodeURIComponent(input.requestId)}/claim`, {
+        method: "POST",
+        body: JSON.stringify({ verifier: input.verifier }),
+    });
+}
+/**
+ * Commits an approved hosted authorization to the same native secret backend
+ * used by ordinary Cloud login. Neither credential is ever written to config,
+ * returned to the browser, or put in a URL. If the second write fails, the
+ * first is rolled back so setup never reports a half-paired machine.
+ */
+export async function rememberCloudDeviceAuthorization(dataDir, input, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const accountRef = await tokenRef(dataDir);
+    const deviceRef = await machineRef(dataDir);
+    await commitCloudAuthCredentials(dataDir, backend, [
+        { ref: accountRef, value: input.accountToken },
+        { ref: deviceRef, value: JSON.stringify(input.machine) },
+    ]);
+    await bootstrapTeamIdentity(dataDir, preferred);
+}
+async function bootstrapTeamIdentity(dataDir, preferred) {
+    try {
+        const { readConfig } = await import("./vault.js");
+        const { recallRecoveryPhrase } = await import("./secrets.js");
+        const config = await readConfig(dataDir);
+        const phrase = await recallRecoveryPhrase(dataDir, config.vaultId, preferred);
+        if (!phrase)
+            return;
+        const { ensureTeamIdentity } = await import("./team-presence.js");
+        await ensureTeamIdentity(dataDir, phrase, preferred);
+    }
+    catch { /* sign-in succeeds even when team bootstrap is offline/rate-limited */ }
+}
+const processBackoff = new Map();
+const processBackoffObserved = new Map();
+const cloudBackoffAcknowledgement = (dataDir) => join(dataDir, 'runtime', 'cloud-backoff-rechecked.json');
+async function backoffRecheckedBefore(dataDir) {
+    try {
+        const value = JSON.parse(await readFile(cloudBackoffAcknowledgement(dataDir), 'utf8'));
+        return Number(value.before) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+const cloudBackoffPath = (dataDir) => join(dataDir, "runtime", "cloud-backoff.json");
+const CLOUD_BACKOFF_MARKER_RE = /^cloud-backoff-until-([0-9]{13})\.marker$/;
+async function readCloudBackoff(dataDir) {
+    try {
+        const row = JSON.parse(await readFile(cloudBackoffPath(dataDir), "utf8"));
+        if (row.version !== 1 || typeof row.until !== "number" || typeof row.retryAfterMs !== "number")
+            return null;
+        return row;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCloudBackoff(dataDir, until) {
+    const state = {
+        version: 1,
+        until,
+        retryAfterMs: Math.max(0, until - Date.now()),
+        updatedAt: new Date().toISOString(),
+        scope: "control-plane",
+    };
+    const path = cloudBackoffPath(dataDir);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+    await rename(temporary, path);
+    return state;
+}
+async function durableCloudBackoffUntil(dataDir) {
+    const receipt = await readCloudBackoff(dataDir);
+    const recheckedBefore = await backoffRecheckedBefore(dataDir);
+    const dir = dirname(cloudBackoffPath(dataDir));
+    const entries = await readdir(dir).catch(() => []);
+    const now = Date.now();
+    let markerUntil = 0;
+    const expired = [];
+    for (const name of entries) {
+        const match = CLOUD_BACKOFF_MARKER_RE.exec(name);
+        if (!match)
+            continue;
+        const until = Number(match[1]);
+        if (recheckedBefore && ((await stat(join(dir, name)).catch(() => null))?.mtimeMs ?? Infinity) < recheckedBefore)
+            continue;
+        if (until <= now)
+            expired.push(join(dir, name));
+        else
+            markerUntil = Math.max(markerUntil, until);
+    }
+    void Promise.all(expired.map((path) => unlink(path).catch(() => undefined)));
+    return Math.max(receipt && Date.parse(receipt.updatedAt) >= recheckedBefore ? receipt.until : 0, markerUntil);
+}
+/**
+ * One cooldown shared by every transport that reaches the control plane.
+ *
+ * REST learns it from Retry-After, while the realtime listener may learn the
+ * same fact during a Socket.IO handshake. Keeping the high-water timestamp in
+ * one package-owned receipt prevents either transport (and a freshly started
+ * daemon) from bypassing the other one's server-requested quiet period.
+ */
+export async function cloudBackoffUntil(dataDir, env = process.env) {
+    const base = cloudUrl(env);
+    const recheckedBefore = await backoffRecheckedBefore(dataDir);
+    if ((processBackoffObserved.get(base) ?? 0) < recheckedBefore)
+        processBackoff.delete(base);
+    return Math.max(processBackoff.get(base) ?? 0, await durableCloudBackoffUntil(dataDir));
+}
+export async function rememberCloudBackoff(dataDir, retryAfterMs, env = process.env) {
+    const delay = Number.isFinite(retryAfterMs) ? Math.max(1_000, Math.ceil(retryAfterMs)) : 60_000;
+    const base = cloudUrl(env);
+    const proposedUntil = Date.now() + delay;
+    // This assignment happens before the first await so another listener in the
+    // same process cannot enter the handshake window while the receipt is being
+    // persisted.
+    processBackoff.set(base, Math.max(processBackoff.get(base) ?? 0, proposedUntil));
+    processBackoffObserved.set(base, Date.now());
+    const dir = dirname(cloudBackoffPath(dataDir));
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const mark = async (until) => {
+        try {
+            await (await open(join(dir, `cloud-backoff-until-${String(Math.ceil(until)).padStart(13, "0")}.marker`), "wx", 0o600)).close();
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    };
+    // Publish this observation before reading any older receipt. A racing process
+    // can now see at least the proposed deadline instead of entering one more
+    // handshake while this process performs its high-water merge.
+    await mark(proposedUntil);
+    const until = Math.max(proposedUntil, processBackoff.get(base) ?? 0, await durableCloudBackoffUntil(dataDir));
+    processBackoff.set(base, until);
+    // An older pre-marker receipt can carry the longer deadline; promote it to a
+    // marker too so future concurrent writers cannot shorten it.
+    await mark(until);
+    return writeCloudBackoff(dataDir, until);
+}
+function retryDelay(response, body) {
+    const retry = response.headers.get("retry-after");
+    if (retry) {
+        const seconds = Number(retry);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.max(1_000, Math.ceil(seconds * 1_000));
+        const at = Date.parse(retry);
+        if (Number.isFinite(at))
+            return Math.max(1_000, at - Date.now());
+    }
+    const error = body && typeof body === "object" ? body.error : null;
+    const bodyMs = Number(error?.retryAfterMs ?? body?.retryAfterMs);
+    if (Number.isFinite(bodyMs) && bodyMs >= 0)
+        return Math.max(1_000, bodyMs);
+    const bodySeconds = Number(error?.retryAfterSeconds ?? body?.retryAfterSeconds ?? error?.retryAfter ?? body?.retryAfter);
+    if (Number.isFinite(bodySeconds) && bodySeconds >= 0)
+        return Math.max(1_000, bodySeconds * 1_000);
+    const resetAt = error?.resetAt ?? body?.resetAt;
+    const resetTime = typeof resetAt === "string" ? Date.parse(resetAt) : Number(resetAt);
+    return Number.isFinite(resetTime) && resetTime > Date.now() ? Math.max(1_000, resetTime - Date.now()) : 60_000;
+}
+function rateLimitDetails(response, retryAfterMs) {
+    const details = { retryAfterMs, retryAt: new Date(Date.now() + retryAfterMs).toISOString() };
+    const limit = response.headers.get("ratelimit-limit");
+    const reset = response.headers.get("ratelimit-reset");
+    if (limit)
+        details.limit = Number.isFinite(Number(limit)) ? Number(limit) : limit;
+    if (reset)
+        details.resetAt = Number.isFinite(Number(reset)) ? new Date(Number(reset) * 1_000).toISOString() : reset;
+    return details;
+}
+async function assertCloudBackoff(base, dataDir) {
+    if (dataDir && (processBackoffObserved.get(base) ?? 0) < await backoffRecheckedBefore(dataDir))
+        processBackoff.delete(base);
+    const until = Math.max(processBackoff.get(base) ?? 0, dataDir ? await durableCloudBackoffUntil(dataDir) : 0);
+    if (until <= Date.now())
+        return;
+    const retryAfterMs = until - Date.now();
+    throw new SealkeepError("rate_limited", `Sealkeep Cloud requests are paused until ${new Date(until).toISOString()} after a service limit. This includes reconnection. Your local vault remains available.`, {
+        retryAfterMs,
+        retryAt: new Date(until).toISOString(),
+    });
 }
 /** A failed cloud call should say what the service said, not just "request failed". */
 async function call(path, init = {}, env = process.env) {
-    const { token, ...rest } = init;
+    const { token, backoffDataDir, maxResponseBytes, manualSessionRetry, ...rest } = init;
+    const base = cloudUrl(env);
+    // A deliberate reconnect may recheck a stale quota deadline once. This is
+    // restricted to session renewal; server-side limits remain authoritative.
+    if (!(manualSessionRetry && path === '/v1/cloud/devices/session'))
+        await assertCloudBackoff(base, backoffDataDir);
     const headers = new Headers(rest.headers);
     if (rest.body)
         headers.set("content-type", "application/json");
     if (token)
         headers.set("authorization", `Bearer ${token}`);
     let response;
-    try {
-        response = await fetch(`${cloudUrl(env)}${path}`, { ...rest, headers });
+    let networkError;
+    // Reads are safe to replay and are the first calls ordinary machines make
+    // after a hosted rollout or brief edge reconnect. Absorb that short window
+    // internally; a person should not need to repeat a join or restart an agent.
+    const method = String(rest.method ?? "GET").toUpperCase();
+    const requestSignal = rest.signal ?? undefined;
+    const attempts = method === "GET" || method === "HEAD" ? 3 : 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            response = await fetch(`${base}${path}`, { ...rest, headers });
+            break;
+        }
+        catch (error) {
+            networkError = error;
+            // A caller-supplied deadline is authoritative. Retrying an already
+            // aborted request only burns the dashboard's entire latency budget (and
+            // creates two more fetches which can never succeed).
+            if (requestSignal?.aborted)
+                break;
+            if (attempt + 1 < attempts) {
+                await pause(100 * (attempt + 1), requestSignal);
+            }
+        }
     }
-    catch (error) {
-        return fail("internal", `Sealkeep Cloud is unreachable: ${error instanceof Error ? error.message : "network error"}`);
+    if (!response) {
+        if (requestSignal?.aborted)
+            throw abortReason(requestSignal, "The Sealkeep Cloud request was cancelled");
+        return fail("internal", `Sealkeep Cloud is unreachable: ${networkError instanceof Error ? networkError.message : "network error"}`);
     }
-    const text = await response.text();
+    const text = maxResponseBytes === undefined ? await response.text()
+        : (await collectChunks(responseBodyChunks(response), maxResponseBytes)).toString("utf8");
     const body = text ? safeJson(text) : null;
     if (!response.ok) {
-        const message = body?.error ?? `${response.status} ${response.statusText}`;
+        // The control plane prefixes a refused precondition with the name of the
+        // step that refused it — "Error at step Precondition: ...". That is the
+        // plane's internal shape, not something a person can act on, and it buries
+        // the sentence that actually tells them what to do. The panel already
+        // strips it; so does the CLI, so both surfaces say the same thing.
+        const errorBody = body && typeof body === "object" ? body.error : null;
+        const remoteCode = typeof errorBody?.code === "string" ? errorBody.code.toUpperCase() : "";
+        const raw = typeof errorBody === "string"
+            ? errorBody
+            : typeof errorBody?.message === "string"
+                ? errorBody.message
+                : typeof body?.message === "string"
+                    ? body.message
+                    : `${response.status} ${response.statusText}`;
+        const message = raw.replace(/^Error at step [^:]*:\s*/i, "");
+        if (response.status === 429) {
+            const retryAfterMs = retryDelay(response, body);
+            processBackoffObserved.set(base, Date.now());
+            if (backoffDataDir)
+                await rememberCloudBackoff(backoffDataDir, retryAfterMs, env).catch(() => {
+                    processBackoff.set(base, Math.max(processBackoff.get(base) ?? 0, Date.now() + retryAfterMs));
+                });
+            else
+                processBackoff.set(base, Math.max(processBackoff.get(base) ?? 0, Date.now() + retryAfterMs));
+            throw new SealkeepError("rate_limited", `Sealkeep Cloud rate limit reached: ${message}`, rateLimitDetails(response, retryAfterMs));
+        }
         if (response.status === 401)
             fail("unauthorized", `Sealkeep Cloud rejected the credentials: ${message}`);
         if (response.status === 402)
-            fail("forbidden", message);
+            fail("payment_required", message);
+        if (response.status === 403 && remoteCode === "TEAM_MEMBERSHIP_REVOKED") {
+            fail("team_membership_revoked", message);
+        }
         if (response.status === 403)
             fail("forbidden", message);
+        // Exact compatibility with the native precondition, not a substring or a
+        // general 409/lease-expiry rule. Only this authenticated personal GET says
+        // there is an existing row whose upload has not completed.
+        if (response.status === 409 && method === "GET" && /^\/v1\/cloud\/archives\/[^/?]+\/download$/.test(path)
+            && (remoteCode === "UPLOAD_INCOMPLETE" || (!remoteCode && message === "That archive never finished uploading, so there is nothing to fetch"))) {
+            fail("upload_incomplete", message, { httpStatus: 409, remoteCode });
+        }
+        const plainTeamStateConflict = path.startsWith("/v1/cloud/team/") && (/\bteam (?:key|membership|state) changed\b/i.test(message)
+            || /member encryption identity changed/i.test(message)
+            || /remaining member needs one current wrapped key/i.test(message)
+            || /owner key wrap is missing/i.test(message));
+        if (response.status === 409 && (remoteCode === "TEAM_STATE_CHANGED" || plainTeamStateConflict)) {
+            const current = Number(errorBody?.current_key_version ?? body?.current_key_version);
+            const currentMembership = Number(errorBody?.current_membership_version ?? body?.current_membership_version);
+            const details = {};
+            if (Number.isSafeInteger(current) && current > 0)
+                details.currentKeyVersion = current;
+            if (Number.isSafeInteger(currentMembership) && currentMembership > 0)
+                details.currentMembershipVersion = currentMembership;
+            fail("team_state_changed", message, Object.keys(details).length ? details : undefined);
+        }
         if (response.status === 409)
-            fail("lease_expired", message);
-        fail("internal", `Sealkeep Cloud returned ${response.status}: ${message}`);
+            fail("lease_expired", message, { httpStatus: response.status, remoteCode });
+        fail("internal", `Sealkeep Cloud returned ${response.status}: ${message}`, { httpStatus: response.status, remoteCode });
     }
     return body;
 }
@@ -87,9 +1084,18 @@ export async function register(dataDir, input, preferred) {
 }
 /** The token lives in the OS keychain, never in a config file on disk. */
 export async function login(dataDir, input, preferred) {
-    const result = await call("/login", { method: "POST", body: JSON.stringify(input) });
     const backend = await chooseBackend(dataDir, preferred);
-    await backend.set(await tokenRef(dataDir), result.token);
+    const refs = await cloudCredentialRefs(dataDir);
+    const expectedAuthGeneration = await stableCloudAuthGeneration(dataDir);
+    const result = await call("/login", { method: "POST", body: JSON.stringify(input) });
+    await commitCloudAuthCredentials(dataDir, backend, [
+        { ref: refs.token, value: result.token },
+        ...(sameSecretRef(refs.bootstrapToken, refs.token) ? [] : [{ ref: refs.bootstrapToken, value: null }]),
+        { ref: refs.machine, value: null },
+        ...(sameSecretRef(refs.bootstrapMachine, refs.machine) ? [] : [{ ref: refs.bootstrapMachine, value: null }]),
+    ], { expectedAuthGeneration });
+    await registerMachine(dataDir, result.token, preferred);
+    await bootstrapTeamIdentity(dataDir, preferred);
     return result.user;
 }
 /**
@@ -106,35 +1112,618 @@ export async function loginWithCode(dataDir, input, preferred) {
     // used to burn the code on the way to a "no vault" error — the person then
     // stood at a panel whose displayed code was already dead, with no hint why.
     const backend = await chooseBackend(dataDir, preferred);
-    const ref = await tokenRef(dataDir);
+    const refs = await cloudCredentialRefs(dataDir);
+    const expectedAuthGeneration = await stableCloudAuthGeneration(dataDir);
     const result = await call("/cli/exchange", { method: "POST", body: JSON.stringify(input) });
-    await backend.set(ref, result.token);
+    await commitCloudAuthCredentials(dataDir, backend, [
+        { ref: refs.token, value: result.token },
+        ...(sameSecretRef(refs.bootstrapToken, refs.token) ? [] : [{ ref: refs.bootstrapToken, value: null }]),
+        { ref: refs.machine, value: null },
+        ...(sameSecretRef(refs.bootstrapMachine, refs.machine) ? [] : [{ ref: refs.bootstrapMachine, value: null }]),
+    ], { expectedAuthGeneration });
     // Announce this machine to the account, so the panel's device list shows it
     // and Revoke has a row to act on. The exchange endpoint itself cannot write
     // the row (it is public; the control plane only accepts tenant writes from an
     // authenticated caller), so the freshly minted token does it. Best-effort: a
     // machine that fails to register is still signed in — it is merely invisible,
     // which was previously true of every machine.
-    try {
-        const { hostname } = await import("node:os");
-        await call("/v1/cloud/devices/register", { method: "POST", token: result.token, body: JSON.stringify({ label: hostname() }) });
-    }
-    catch { /* visibility is not worth failing a successful sign-in over */ }
+    await registerMachine(dataDir, result.token, preferred);
+    await bootstrapTeamIdentity(dataDir, preferred);
     return result.user;
 }
 export async function logout(dataDir, preferred) {
     const backend = await chooseBackend(dataDir, preferred);
-    await backend.delete(await tokenRef(dataDir));
+    const refs = await cloudCredentialRefs(dataDir);
+    await commitCloudAuthCredentials(dataDir, backend, [
+        { ref: refs.token, value: null },
+        ...(sameSecretRef(refs.bootstrapToken, refs.token) ? [] : [{ ref: refs.bootstrapToken, value: null }]),
+        { ref: refs.machine, value: null },
+        ...(sameSecretRef(refs.bootstrapMachine, refs.machine) ? [] : [{ ref: refs.bootstrapMachine, value: null }]),
+    ]);
 }
-export async function cloudToken(dataDir, preferred) {
-    const backend = await chooseBackend(dataDir, preferred);
-    const token = await backend.get(await tokenRef(dataDir));
+/**
+ * Read only the expiry claim from our own stored JWT. This is scheduling, not
+ * trust: the server still verifies every token and the machine credential used
+ * to renew it. An opaque/self-hosted token simply keeps its existing behavior.
+ */
+function tokenNeedsRenewal(token, withinSeconds = 300) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return false;
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return typeof payload.exp === "number" && payload.exp * 1000 <= Date.now() + withinSeconds * 1000;
+    }
+    catch {
+        return false;
+    }
+}
+const cloudRenewals = new Map();
+async function renewCloudSession(dataDir, backend, ref, token, authGeneration, preferred, signal, explicit = false) {
+    const key = JSON.stringify([
+        resolve(dataDir), authGeneration, backend.name, ref.service, ref.account,
+        createHash("sha256").update(token).digest("hex"),
+        explicit,
+    ]);
+    let running = cloudRenewals.get(key);
+    if (running?.controller.signal.aborted) {
+        cloudRenewals.delete(key);
+        running = undefined;
+    }
+    if (!running) {
+        const controller = new AbortController();
+        const entry = {
+            controller,
+            promise: Promise.resolve(null),
+            waiters: 0,
+            settled: false,
+        };
+        entry.promise = (async () => {
+            const machine = await machineCredential(dataDir, preferred);
+            if (!machine)
+                return null;
+            let fresh;
+            try {
+                fresh = await call("/v1/cloud/devices/session", {
+                    manualSessionRetry: explicit,
+                    method: "POST",
+                    body: JSON.stringify({ device_id: machine.device_id, machine_key: machine.machine_key }),
+                    signal: controller.signal,
+                    backoffDataDir: dataDir,
+                });
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    throw abortReason(controller.signal, "Sealkeep Cloud session renewal was cancelled");
+                // Older/self-hosted planes may not have renewal yet. Preserve their
+                // existing response path so the caller receives the real auth failure.
+                if (explicit)
+                    throw error;
+                return null;
+            }
+            if (typeof fresh.token !== "string" || !fresh.token) {
+                if (explicit)
+                    fail("internal", "Sealkeep Cloud returned no renewed session; this machine was not re-registered.");
+                return null;
+            }
+            controller.signal.throwIfAborted();
+            // Local commit failures are deliberately outside the compatibility catch:
+            // returning the old token after a failed generation write would conceal a
+            // credential transition the cache boundary could not publish safely.
+            await commitCloudAuthCredentials(dataDir, backend, [{ ref, value: fresh.token }], { expectedAuthGeneration: authGeneration });
+            return fresh.token;
+        })().finally(() => {
+            entry.settled = true;
+            if (cloudRenewals.get(key) === entry)
+                cloudRenewals.delete(key);
+        });
+        cloudRenewals.set(key, entry);
+        running = entry;
+    }
+    return awaitSharedAbortable(running, signal);
+}
+export async function cloudToken(dataDir, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    const snapshot = await cachedCloudTokenRead(dataDir, preferred);
+    options.signal?.throwIfAborted();
+    let token = snapshot.token;
     if (!token)
         fail("unauthorized", "Not signed in to Sealkeep Cloud. Run: sealkeep cloud login");
+    // Display-only reads deliberately use the stored token as a snapshot. They
+    // must never be the caller which starts a shared network renewal and leaves
+    // an action waiting behind a hung control plane. The server still validates
+    // the token; a stale snapshot simply fails closed and the UI keeps its last
+    // authenticated local facts.
+    if (options.renew !== false && tokenNeedsRenewal(token)) {
+        const renewed = await renewCloudSession(dataDir, snapshot.backend, snapshot.refs.token, token, snapshot.generation, preferred, options.signal);
+        if (renewed)
+            token = renewed;
+        else if (await stableCloudAuthGeneration(dataDir) !== snapshot.generation) {
+            // A compatibility/no-machine renewal may return null. Do not fall back
+            // to the old token if logout or another login completed while that
+            // attempt was in flight.
+            fail("cloud_account_unavailable", "Sealkeep Cloud sign-in changed while the session renewal was in flight. Retry the request.");
+        }
+    }
     return token;
 }
-export async function accountStatus(dataDir, preferred) {
-    return call("/me", { token: await cloudToken(dataDir, preferred) });
+export async function accountStatus(dataDir, preferred, options = {}) {
+    return call("/me", {
+        token: await cloudToken(dataDir, preferred, { renew: options.renewToken !== false, signal: options.signal }),
+        signal: options.signal,
+        backoffDataDir: dataDir,
+    });
+}
+/** Explicit user reconnection reuses the existing device, never a new seat. */
+export async function reconnectCloudSession(dataDir, preferred) {
+    const before = Date.now();
+    const snapshot = await cachedCloudTokenRead(dataDir, preferred);
+    if (!await machineCredential(dataDir, preferred))
+        return { reconnected: false };
+    const renewed = await renewCloudSession(dataDir, snapshot.backend, snapshot.refs.token, snapshot.token || "", snapshot.generation, preferred, undefined, true);
+    if (renewed) {
+        const target = cloudBackoffAcknowledgement(dataDir);
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        const temporary = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temporary, JSON.stringify({ before, checkedAt: new Date().toISOString() }), { mode: 0o600 });
+        await rename(temporary, target);
+    }
+    return { reconnected: Boolean(renewed) };
+}
+function rowsOf(value, keys = []) {
+    if (Array.isArray(value))
+        return value;
+    if (!value || typeof value !== "object")
+        return [];
+    for (const key of keys) {
+        const nested = value[key];
+        if (Array.isArray(nested))
+            return nested;
+        if (nested && typeof nested === "object")
+            return [nested];
+    }
+    return [value];
+}
+function teamCall(dataDir, path, token, init = {}) {
+    return call(path, { ...init, token, backoffDataDir: dataDir });
+}
+export async function getTeamIdentity(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/identity", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["identity", "items", "data"])[0] ?? null;
+}
+export async function putTeamIdentity(dataDir, identity, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/identity", await cloudToken(dataDir, preferred), {
+        method: "PUT", body: JSON.stringify(identity),
+    });
+    return rowsOf(answer, ["identity", "item", "data"])[0] ?? identity;
+}
+export async function createTeamSpace(dataDir, input, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/spaces", await cloudToken(dataDir, preferred), {
+        method: "POST", body: JSON.stringify(input),
+    });
+    return rowsOf(answer, ["space", "membership", "item", "data"])[0] ?? { space_key: input.space_key, key_version: 1 };
+}
+export async function listTeamSpaces(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/spaces", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["spaces", "memberships", "items", "data"]);
+}
+/** Cloud-owned intent; a connected machine creates and seals the project key. */
+export async function listTeamProjectRequests(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/project-requests", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["requests", "items", "data"]);
+}
+/** Create cloud-owned project intent; key creation still happens on a connected machine. */
+export async function createTeamProjectRequest(dataDir, projectName, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/project-requests", await cloudToken(dataDir, preferred), {
+        method: "POST", body: JSON.stringify({ project_name: projectName }),
+    });
+    const request = rowsOf(answer, ["request", "item", "data"])[0];
+    if (!request)
+        return fail("internal", "Sealkeep Cloud created the project request but returned no request");
+    return request;
+}
+/** Closes a project intent only after this account owns the prepared space. */
+export async function completeTeamProjectRequest(dataDir, requestId, spaceKey, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/project-requests/${encodeURIComponent(String(requestId))}/complete`, await cloudToken(dataDir, preferred), {
+        method: "POST", body: JSON.stringify({ space_key: spaceKey }),
+    });
+    const request = rowsOf(answer, ["request", "item", "data"])[0];
+    if (!request)
+        return fail("internal", "Sealkeep Cloud completed the project request but returned no request");
+    return request;
+}
+export async function getTeamMembership(dataDir, spaceKey, preferred) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/membership`, await cloudToken(dataDir, preferred));
+        return rowsOf(answer, ["membership", "member", "item", "data"])[0] ?? null;
+    }
+    catch (error) {
+        // This endpoint has exactly one authorization boundary after sign-in:
+        // current membership. Older hosted workflows return a plain 403 instead
+        // of the newer structured TEAM_MEMBERSHIP_REVOKED code.
+        if (isSealkeepError(error) && error.code === "forbidden")
+            return null;
+        throw error;
+    }
+}
+function rethrowTeamMembership(error) {
+    if (isSealkeepError(error) && error.code === "forbidden") {
+        return fail("team_membership_revoked", "This account is no longer a member of that team space");
+    }
+    throw error;
+}
+export async function resolveTeamInvitee(dataDir, spaceKey, email, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/invitee?email=${encodeURIComponent(email)}`, await cloudToken(dataDir, preferred));
+    const found = rowsOf(answer, ["invitee", "account", "item", "data"])[0];
+    if (!found || typeof found.account_id !== "number" || typeof found.public_key !== "string") {
+        return fail("archive_not_found", `No team identity is ready for ${email}. They need to sign in to Sealkeep on one machine first.`);
+    }
+    return found;
+}
+export async function addTeamMember(dataDir, spaceKey, input, preferred) {
+    void dataDir;
+    void spaceKey;
+    void input;
+    void preferred;
+    return fail("invalid_argument", "Direct team membership is disabled; create an invitation and let the teammate accept it");
+}
+/** Creates a pending invitation; membership is not granted until acceptance. */
+export async function createTeamInvitation(dataDir, spaceKey, input, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/invitations`, await cloudToken(dataDir, preferred), {
+        method: "POST", body: JSON.stringify({ email: input.email }),
+    });
+    const invitation = rowsOf(answer, ["invitation", "item", "data"])[0];
+    if (!invitation || !Number.isSafeInteger(Number(invitation.id)))
+        return fail("internal", "Sealkeep Cloud created the invitation but returned no invitation id");
+    if (input.wrapped_key && input.expected_key_version) {
+        if (!Number.isSafeInteger(input.expected_membership_version) || !Number.isSafeInteger(input.expected_index_revision)
+            || typeof input.expected_archive_refs !== "string") {
+            fail("invalid_argument", "Encrypted invitations require a captured team history fence");
+        }
+        return prepareTeamInvitation(dataDir, invitation.id, {
+            wrapped_key: input.wrapped_key,
+            expected_key_version: input.expected_key_version,
+            expected_membership_version: input.expected_membership_version,
+            expected_index_revision: input.expected_index_revision,
+            expected_archive_refs: input.expected_archive_refs,
+        }, preferred);
+    }
+    // Pending is represented by the row's existence on the hosted plane. Keep
+    // the wire status explicit for the dashboard and compatibility join path;
+    // accepting or declining removes the row atomically.
+    return { ...invitation, status: "pending" };
+}
+/** Invitations created in the hosted account that this signed-in account owns. */
+export async function listOutgoingTeamInvitations(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/invitations/outgoing", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["invitations", "items", "data"]).map((invitation) => ({
+        ...invitation,
+        status: "pending",
+        state: invitation.wrapped_key ? "ready" : invitation.state ?? "preparing",
+    }));
+}
+/** Submit ciphertext produced by the installed owner machine; plaintext keys never reach the browser. */
+export async function prepareTeamInvitation(dataDir, invitationId, input, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/invitations/${encodeURIComponent(String(invitationId))}/prepare`, await cloudToken(dataDir, preferred), {
+        method: "POST", body: JSON.stringify(input),
+    });
+    const invitation = rowsOf(answer, ["invitation", "item", "data"])[0];
+    if (!invitation)
+        return fail("internal", "Sealkeep Cloud prepared the invitation but returned no invitation");
+    if (invitation.history_fenced !== true
+        || Number(invitation.history_membership_version) !== input.expected_membership_version
+        || Number(invitation.history_index_revision) !== input.expected_index_revision
+        || invitation.history_archive_refs !== input.expected_archive_refs) {
+        fail("provider_unsupported", "This backend did not attest the invitation's complete history fence");
+    }
+    return { ...invitation, status: "pending", state: "ready" };
+}
+export async function listTeamInvitations(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/invitations", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["invitations", "items", "data"]).map((invitation) => ({
+        ...invitation,
+        status: "pending",
+        state: invitation.wrapped_key ? "ready" : invitation.state ?? "preparing",
+    }));
+}
+export async function acceptTeamInvitation(dataDir, invitationId, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/invitations/${encodeURIComponent(String(invitationId))}/accept`, await cloudToken(dataDir, preferred), { method: "POST", body: "{}" });
+    if (!isRecord(answer) || answer.history_fenced !== true) {
+        fail("provider_unsupported", "This backend did not attest the accepted invitation's history fence");
+    }
+    const member = rowsOf(answer, ["membership", "member", "item", "data"])[0];
+    if (!member)
+        return fail("internal", "Sealkeep Cloud accepted the invitation but returned no membership");
+    return member;
+}
+export async function declineTeamInvitation(dataDir, invitationId, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/invitations/${encodeURIComponent(String(invitationId))}/decline`, await cloudToken(dataDir, preferred), { method: "POST", body: "{}" });
+    return rowsOf(answer, ["invitation", "item", "data"])[0] ?? { id: invitationId, status: "declined" };
+}
+export async function listTeamMembers(dataDir, spaceKey, preferred) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/members`, await cloudToken(dataDir, preferred));
+        return rowsOf(answer, ["members", "memberships", "items", "data"]);
+    }
+    catch (error) {
+        return rethrowTeamMembership(error);
+    }
+}
+/** One server-consistent roster snapshot for CAS-sensitive sharing work. */
+export async function getTeamRoster(dataDir, spaceKey, preferred, options = {}) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/members`, await cloudToken(dataDir, preferred, { renew: options.renewToken !== false, signal: options.signal }), { signal: options.signal });
+        const top = answer && typeof answer === "object" && !Array.isArray(answer) ? answer : null;
+        const nested = top?.data && typeof top.data === "object" && !Array.isArray(top.data) ? top.data : top;
+        const members = Array.isArray(nested?.members) ? nested.members : [];
+        const membershipVersion = Number(nested?.membership_version);
+        const keyVersion = Number(nested?.key_version);
+        const accountIds = new Set();
+        const publicKeys = new Set();
+        const validMembers = members.every((member) => {
+            const raw = typeof member.public_key === "string" ? Buffer.from(member.public_key, "base64") : Buffer.alloc(0);
+            if (!Number.isSafeInteger(member.account_id) || member.account_id <= 0
+                || typeof member.public_key !== "string" || raw.length !== 32
+                || !Number.isSafeInteger(member.key_version) || member.key_version <= 0
+                || typeof member.role !== "string" || !member.role)
+                return false;
+            accountIds.add(member.account_id);
+            publicKeys.add(member.public_key);
+            return true;
+        });
+        if (!members.length || !validMembers || accountIds.size !== members.length || publicKeys.size !== members.length
+            || !Number.isSafeInteger(membershipVersion) || membershipVersion <= 0) {
+            return fail("internal", "Sealkeep Cloud did not return a versioned team roster; archive sharing was withheld");
+        }
+        return {
+            members,
+            membership_version: membershipVersion,
+            ...(Number.isSafeInteger(keyVersion) && keyVersion > 0 ? { key_version: keyVersion } : {}),
+        };
+    }
+    catch (error) {
+        return rethrowTeamMembership(error);
+    }
+}
+/** Cloud-owned intent; a connected owner machine performs the key rotation. */
+export async function createTeamRemovalRequest(dataDir, spaceKey, targetAccountId, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/members/${encodeURIComponent(String(targetAccountId))}/removal-requests`, await cloudToken(dataDir, preferred), {
+        method: "POST", body: "{}",
+    });
+    const request = rowsOf(answer, ["request", "item", "data"])[0];
+    if (!request)
+        return fail("internal", "Sealkeep Cloud created the removal request but returned no request");
+    return request;
+}
+export async function listOutgoingTeamAccessRequests(dataDir, preferred) {
+    const answer = await teamCall(dataDir, "/v1/cloud/team/access-requests/outgoing", await cloudToken(dataDir, preferred));
+    return rowsOf(answer, ["requests", "items", "data"]);
+}
+export async function completeTeamAccessRequest(dataDir, requestId, preferred) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/access-requests/${encodeURIComponent(String(requestId))}/complete`, await cloudToken(dataDir, preferred), {
+        method: "POST", body: "{}",
+    });
+    const request = rowsOf(answer, ["request", "item", "data"])[0];
+    if (!request)
+        return fail("internal", "Sealkeep Cloud completed the access request but returned no request");
+    return request;
+}
+export async function registerTeamArchive(dataDir, spaceKey, vaultRef, expectedMembershipVersion, preferred, options = {}) {
+    if (!Number.isSafeInteger(expectedMembershipVersion) || expectedMembershipVersion <= 0) {
+        return fail("invalid_argument", "A current team membership version is required before an archive can be shared");
+    }
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/archives`, await cloudToken(dataDir, preferred, { signal: options.signal }), {
+        method: "POST",
+        body: JSON.stringify({ vault_ref: vaultRef, expected_membership_version: expectedMembershipVersion }),
+        signal: options.signal,
+    });
+    const top = answer && typeof answer === "object" && !Array.isArray(answer) ? answer : null;
+    const receiptVersion = Number(top?.membership_version);
+    const row = rowsOf(answer, ["archive", "item", "data"])[0];
+    if (!row)
+        return fail("internal", "Sealkeep Cloud registered the archive but returned no archive row");
+    if (receiptVersion !== expectedMembershipVersion || row.membership_version !== expectedMembershipVersion) {
+        return fail("team_state_changed", "Sealkeep Cloud did not attest the membership version used for this archive grant");
+    }
+    return row;
+}
+export async function unregisterTeamArchive(dataDir, spaceKey, vaultRef, expectedMembershipVersion, preferred, options = {}) {
+    if (!Number.isSafeInteger(expectedMembershipVersion) || expectedMembershipVersion <= 0) {
+        return fail("invalid_argument", "A current team membership version is required before an archive grant can be removed");
+    }
+    await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/archives/${encodeURIComponent(vaultRef)}`, await cloudToken(dataDir, preferred, { signal: options.signal }), {
+        method: "DELETE",
+        body: JSON.stringify({ expected_membership_version: expectedMembershipVersion }),
+        signal: options.signal,
+    });
+}
+export async function listTeamArchives(dataDir, spaceKey, preferred, options = {}) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/archives`, await cloudToken(dataDir, preferred, { renew: options.renewToken !== false, signal: options.signal }), { signal: options.signal });
+    return rowsOf(answer, ["archives", "items", "data"]);
+}
+export async function teamArchiveDownload(dataDir, spaceKey, vaultRef, preferred, options = {}) {
+    return teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/archives/${encodeURIComponent(vaultRef)}/download`, await cloudToken(dataDir, preferred, options), options);
+}
+const teamReadGuardBindings = new WeakMap();
+/** Pins local account identity while rechecking live membership and every exact grant.
+ * This guard carries no reusable permission: each assertion calls the Team plane. */
+export async function createTeamReadGuard(dataDir, spaceKey, refs, membershipVersion, options = {}) {
+    if (!Number.isSafeInteger(membershipVersion) || membershipVersion <= 0) {
+        fail("invalid_argument", "A Team read requires the exact membership version");
+    }
+    const origin = cloudUrl();
+    const token = await cloudToken(dataDir, options.preferred, { signal: options.signal });
+    const account = await cachedCloudTokenRead(dataDir, options.preferred);
+    if (account.token !== token)
+        fail("unauthorized", "The account changed before the Team read");
+    const required = new Set(refs);
+    const assertIdentity = async () => {
+        options.signal?.throwIfAborted();
+        const current = await cachedCloudTokenRead(dataDir, options.preferred);
+        if (origin !== cloudUrl() || current.token !== token || current.generation !== account.generation
+            || !sameCloudCredentialRefs(current.refs, account.refs)) {
+            fail("unauthorized", "The account changed during the Team read");
+        }
+    };
+    const guard = {
+        async assertCurrent(additionalRefs = []) {
+            for (const ref of additionalRefs)
+                required.add(ref);
+            await assertIdentity();
+            const [roster, grants] = await Promise.all([
+                getTeamRoster(dataDir, spaceKey, options.preferred, { signal: options.signal, renewToken: false }),
+                listTeamArchives(dataDir, spaceKey, options.preferred, { signal: options.signal, renewToken: false }),
+            ]);
+            await assertIdentity();
+            if (roster.membership_version !== membershipVersion) {
+                fail("team_membership_revoked", "Team membership changed during the read");
+            }
+            const allowed = new Set(grants.filter((grant) => grant.membership_version === membershipVersion).map((grant) => grant.vault_ref));
+            if ([...required].some((ref) => !allowed.has(ref))) {
+                fail("forbidden", "The exact archive is no longer granted to this Team membership");
+            }
+        },
+    };
+    teamReadGuardBindings.set(guard, { dataDir: resolve(dataDir), spaceKey, membershipVersion, refs: required, assertIdentity });
+    await guard.assertCurrent();
+    return guard;
+}
+/** Strict framed-object range transport. Integrity of a slice additionally
+ * requires the caller's authenticated envelope and per-chunk AEAD checks. */
+export async function pullTeamCiphertextRange(dataDir, spaceKey, vaultRef, storedOffset, storedLength, preferred, options = {}) {
+    const maxBytes = options.maxBytes ?? 8 * 1024 * 1024;
+    if (!Number.isSafeInteger(storedOffset) || storedOffset < 0
+        || !Number.isSafeInteger(storedLength) || storedLength <= 0
+        || !Number.isSafeInteger(storedOffset + storedLength)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || storedLength > maxBytes) {
+        fail("invalid_argument", "The Team range must fit its bounded byte limit");
+    }
+    const binding = options.readGuard ? teamReadGuardBindings.get(options.readGuard) : undefined;
+    if (options.readGuard && (!binding || binding.dataDir !== resolve(dataDir) || binding.spaceKey !== spaceKey
+        || (options.expectedMembershipVersion !== undefined && binding.membershipVersion !== options.expectedMembershipVersion))) {
+        fail("invalid_argument", "The Team range guard belongs to a different read scope");
+    }
+    const epoch = binding?.membershipVersion ?? options.expectedMembershipVersion
+        ?? (await getTeamRoster(dataDir, spaceKey, preferred, { signal: options.signal })).membership_version;
+    const guard = options.readGuard ?? await createTeamReadGuard(dataDir, spaceKey, [vaultRef], epoch, { preferred, signal: options.signal });
+    // The fresh exact-ref lease below still authorizes each network request.
+    // A shared guard accumulates every dependency for its final live grant proof.
+    binding?.refs.add(vaultRef);
+    await binding?.assertIdentity();
+    const lease = await teamArchiveDownload(dataDir, spaceKey, vaultRef, preferred, options);
+    const total = Number(lease.bytes);
+    if (lease.vault_ref !== vaultRef || !Number.isSafeInteger(total) || total <= 0 || storedOffset + storedLength > total
+        || !/^[a-f0-9]{64}$/i.test(lease.ciphertext_sha256 ?? "")) {
+        fail("ciphertext_integrity_failed", "The Team range has no valid object descriptor");
+    }
+    if (!lease.download?.url || (lease.download.method && lease.download.method.toUpperCase() !== "GET")) {
+        fail("provider_unsupported", "This Team archive has no bounded range download transport");
+    }
+    const end = storedOffset + storedLength - 1;
+    const headers = new Headers(lease.download.headers);
+    headers.set("range", `bytes=${storedOffset}-${end}`);
+    const response = await fetch(lease.download.url, { method: "GET", headers, signal: options.signal });
+    const contentLength = response.headers.get("content-length");
+    if (response.status !== 206 || response.headers.get("content-range") !== `bytes ${storedOffset}-${end}/${total}`
+        || (contentLength !== null && Number(contentLength) !== storedLength)
+        || (response.headers.get("content-encoding") && response.headers.get("content-encoding") !== "identity")) {
+        await response.body?.cancel().catch(() => undefined);
+        fail("ciphertext_integrity_failed", "Storage did not return the exact requested Team byte range");
+    }
+    const body = await collectChunks(responseBodyChunks(response), storedLength);
+    if (body.length !== storedLength)
+        fail("ciphertext_integrity_failed", "The Team byte range was truncated");
+    if (binding)
+        await binding.assertIdentity();
+    else
+        await guard.assertCurrent();
+    return body;
+}
+/** Streaming, integrity-checked read through the current project membership gate.
+ * Consumers must exhaust the stream before publishing any downloaded bytes. */
+export async function pullTeamCiphertextStream(dataDir, spaceKey, vaultRef, preferred, options = {}) {
+    const lease = await teamArchiveDownload(dataDir, spaceKey, vaultRef, preferred, options);
+    if (!/^[a-f0-9]{64}$/i.test(lease.ciphertext_sha256 ?? "")
+        || !Number.isSafeInteger(Number(lease.bytes)) || Number(lease.bytes) < 0) {
+        return fail("ciphertext_integrity_failed", "Shared archive download has no valid integrity proof");
+    }
+    if (options.maxBytes !== undefined
+        && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
+        return fail("invalid_argument", "The shared archive read limit must be a non-negative safe integer");
+    }
+    if (options.maxBytes !== undefined && Number(lease.bytes) > options.maxBytes) {
+        return fail("provider_unsupported", "The shared archive exceeds this bounded read's byte limit");
+    }
+    const source = await fetchLeasedObjectStream(lease, options);
+    const checked = (async function* () {
+        const hash = createHash("sha256");
+        let bytes = 0;
+        for await (const chunk of source) {
+            options.signal?.throwIfAborted();
+            bytes += chunk.length;
+            if (bytes > Number(lease.bytes))
+                fail("ciphertext_integrity_failed", "Shared archive exceeds its recorded size");
+            hash.update(chunk);
+            yield chunk;
+        }
+        if (bytes !== Number(lease.bytes) || hash.digest("hex") !== lease.ciphertext_sha256) {
+            fail("ciphertext_integrity_failed", "Downloaded shared archive does not match its recorded integrity proof");
+        }
+    })();
+    return options.unframe ? unframeChunks(checked, OBJECT_MAGIC) : checked;
+}
+/** Download and verify a shared archive through the current membership gate. */
+export async function pullTeamCiphertext(dataDir, spaceKey, vaultRef, preferred) {
+    const lease = await teamArchiveDownload(dataDir, spaceKey, vaultRef, preferred);
+    const ciphertext = await fetchLeasedObject(lease);
+    const digest = createHash("sha256").update(ciphertext).digest("hex");
+    if (lease.ciphertext_sha256 && digest !== lease.ciphertext_sha256) {
+        fail("ciphertext_integrity_failed", "Downloaded team archive does not match the hash recorded at upload; refusing it");
+    }
+    return { ciphertext, bytes: ciphertext.length };
+}
+/**
+ * One owner-authorized, compare-and-swap epoch transition. The server removes
+ * the target, replaces every remaining wrap, advances the room capability and
+ * appends the encrypted discovery marker as one transaction.
+ */
+export async function removeTeamMemberAndRotate(dataDir, spaceKey, targetAccountId, input, preferred, options = {}) {
+    const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/members/${encodeURIComponent(String(targetAccountId))}/remove`, await cloudToken(dataDir, preferred, { signal: options.signal }), { method: "POST", body: JSON.stringify(input), signal: options.signal });
+    const value = rowsOf(answer, ["rotation", "space", "item", "data"])[0];
+    if (!value || !Number.isSafeInteger(Number(value.key_version)) || typeof value.realtime_key !== "string") {
+        return fail("internal", "Sealkeep Cloud rotated the team space but returned no epoch receipt");
+    }
+    return value;
+}
+export async function publishTeamPresence(dataDir, spaceKey, input, preferred) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/presence`, await cloudToken(dataDir, preferred), {
+            method: "POST", body: JSON.stringify(input),
+        });
+        const row = rowsOf(answer, ["event", "presence", "item", "data"])[0];
+        return row ?? { id: 0, ...input };
+    }
+    catch (error) {
+        return rethrowTeamMembership(error);
+    }
+}
+export async function pollTeamPresence(dataDir, spaceKey, after, preferred) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/presence?after=${Math.max(0, Math.trunc(after))}`, await cloudToken(dataDir, preferred));
+        return rowsOf(answer, ["events", "presence", "items", "data"]);
+    }
+    catch (error) {
+        return rethrowTeamMembership(error);
+    }
+}
+export async function recentTeamPresence(dataDir, spaceKey, preferred) {
+    try {
+        const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/presence/recent`, await cloudToken(dataDir, preferred));
+        return rowsOf(answer, ["events", "presence", "items", "data"]);
+    }
+    catch (error) {
+        return rethrowTeamMembership(error);
+    }
 }
 /**
  * Refuses an escrow password that is also the account password.
@@ -181,7 +1770,7 @@ export function sealEscrow(secretMaterial, rawPhrase, also = []) {
             recipients.push({ kind: "x25519", publicKey: x25519PublicKeyFromRaw(raw) });
         }
     }
-    return sealEnvelope(Buffer.from(JSON.stringify(secretMaterial)), { recipients, adapter: { agent: "vaultline-escrow", version: "1" } });
+    return sealEnvelope(Buffer.from(JSON.stringify(secretMaterial)), { recipients, adapter: { agent: "sealkeep-escrow", version: "1" } });
 }
 export function openEscrow(envelope, ciphertext, rawPhrase) {
     const phrase = canonicalPhrase(rawPhrase);
@@ -224,6 +1813,15 @@ export function openEscrowWithKey(envelope, ciphertext, privateKeyRaw) {
         return fail("recovery_phrase_mismatch", "That key does not open this escrow blob");
     }
 }
+/** Upload an already-sealed escrow envelope without ever reconstructing it server-side. */
+export async function pushEscrowBlob(dataDir, envelope, ciphertext, preferred) {
+    await call("/v1/cloud/escrow", {
+        method: "PUT",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ envelope: JSON.stringify(envelope), sealed: ciphertext.toString("base64") })
+    });
+    return { stored: true };
+}
 /**
  * Hand the sealed blob to the control plane.
  *
@@ -233,18 +1831,90 @@ export function openEscrowWithKey(envelope, ciphertext, privateKeyRaw) {
  */
 export async function pushEscrow(dataDir, secretMaterial, rawPhrase, preferred, also = []) {
     const { envelope, ciphertext } = sealEscrow(secretMaterial, rawPhrase, also);
-    await call("/v1/cloud/escrow", {
+    return pushEscrowBlob(dataDir, envelope, ciphertext, preferred);
+}
+/** Fetch and open the escrow blob. Requires the phrase; nothing else will do. */
+/** Whether a sealed copy exists, without needing the phrase to find out. */
+export async function hasSealedCopy(dataDir, preferred) {
+    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
+    return (Array.isArray(answer) ? answer : answer ? [answer] : []).some((row) => Boolean(row?.sealed));
+}
+/** Latest append-only escrow revision; still ciphertext to every server involved. */
+export async function pullEscrowBlob(dataDir, preferred) {
+    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
+    const rows = (Array.isArray(answer) ? answer : answer ? [answer] : []).filter((row) => row?.sealed);
+    return rows.sort((a, b) => String(b.created_at ?? "").localeCompare(String(a.created_at ?? "")) || Number(b.id ?? 0) - Number(a.id ?? 0))[0] ?? null;
+}
+/**
+ * Atomically replaces the phrase-only escrow copy and all one-time recovery
+ * capsules. Each capsule contains one opaque key wrap; Cloud never receives a
+ * code or phrase and normal escrow reads never expose a code-decryptable wrap.
+ */
+export async function replaceCloudRecoveryKit(dataDir, master, capsules, preferred) {
+    if (capsules.length !== 5)
+        fail("invalid_argument", "A Recovery Kit needs exactly five encrypted capsules");
+    return call("/v1/cloud/recovery-kit", {
         method: "PUT",
         token: await cloudToken(dataDir, preferred),
-        body: JSON.stringify({ envelope: JSON.stringify(envelope), sealed: ciphertext.toString("base64") })
+        body: JSON.stringify({
+            envelope: JSON.stringify(master.envelope),
+            sealed: master.ciphertext.toString("base64"),
+            capsules: capsules.map((capsule) => ({
+                recipient_id: capsule.recipient_id,
+                envelope: typeof capsule.envelope === "string" ? capsule.envelope : JSON.stringify(capsule.envelope),
+                sealed: capsule.sealed,
+            })),
+        }),
+    });
+}
+export async function cloudRecoveryKitStatus(dataDir, preferred) {
+    return call("/v1/cloud/recovery-kit/status", {
+        token: await cloudToken(dataDir, preferred),
+    });
+}
+/**
+ * Atomically awards exactly one encrypted capsule to one random machine claim.
+ * A retry with the same claim is idempotent; a different claim gets no capsule.
+ */
+export async function redeemCloudRecoveryCode(dataDir, recipientId, claimId, preferred) {
+    if (!/^[a-f0-9]{32}$/.test(recipientId))
+        fail("invalid_argument", "That Recovery Kit recipient is malformed");
+    if (!/^[a-f0-9]{32}$/.test(claimId))
+        fail("invalid_argument", "That Recovery Kit claim is malformed");
+    return call(`/v1/cloud/recovery-codes/${encodeURIComponent(recipientId)}/redeem`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ claim_id: claimId }),
+    });
+}
+/** Atomically spends one recovery recipient for this account. The code never crosses the wire. */
+export async function consumeCloudRecoveryCode(dataDir, recipientId, claimId, preferred) {
+    if (!/^[a-f0-9]{32}$/.test(recipientId))
+        fail("invalid_argument", "That Recovery Kit recipient is malformed");
+    if (!/^[a-f0-9]{32}$/.test(claimId))
+        fail("invalid_argument", "That Recovery Kit claim is malformed");
+    return call(`/v1/cloud/recovery-codes/${encodeURIComponent(recipientId)}/consume`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ claim_id: claimId }),
+    });
+}
+/**
+ * Resolves an ambiguous consume response without making a spent code reusable.
+ * Only the same random claim made by this machine is acknowledged.
+ */
+export async function cloudRecoveryCodeClaimStatus(dataDir, recipientId, claimId, preferred) {
+    if (!/^[a-f0-9]{32}$/.test(recipientId))
+        fail("invalid_argument", "That Recovery Kit recipient is malformed");
+    if (!/^[a-f0-9]{32}$/.test(claimId))
+        fail("invalid_argument", "That Recovery Kit claim is malformed");
+    return call(`/v1/cloud/recovery-codes/${encodeURIComponent(recipientId)}/claims/${encodeURIComponent(claimId)}`, {
+        token: await cloudToken(dataDir, preferred),
     });
-    return { stored: true };
 }
-/** Fetch and open the escrow blob. Requires the phrase; nothing else will do. */
-/** Whether a sealed copy exists, without needing the phrase to find out. */
-export async function hasSealedCopy(dataDir, preferred) {
-    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
-    return (Array.isArray(answer) ? answer : answer ? [answer] : []).some((row) => Boolean(row?.sealed));
+/** Returns the awarded capsule only to the exact claim that spent the code. */
+export async function claimCloudRecoveryCodeCapsule(dataDir, recipientId, claimId, preferred) {
+    return cloudRecoveryCodeClaimStatus(dataDir, recipientId, claimId, preferred);
 }
 export async function pullEscrow(dataDir, rawPhrase, preferred) {
     // The control plane answers with a list, even though sealing replaces rather
@@ -252,22 +1922,121 @@ export async function pullEscrow(dataDir, rawPhrase, preferred) {
     // list itself, which is always undefined, so the escrow was unreadable no
     // matter what had been stored — the paid tier's whole safety net.
     // Newest-first is belt and braces in case replacement ever becomes an append.
-    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
-    const rows = (Array.isArray(answer) ? answer : answer ? [answer] : []).filter((row) => row?.sealed);
-    const blob = rows.sort((a, b) => String(b.created_at ?? "").localeCompare(String(a.created_at ?? "")) || Number(b.id ?? 0) - Number(a.id ?? 0))[0];
+    const blob = await pullEscrowBlob(dataDir, preferred);
     if (!blob?.sealed)
         fail("archive_not_found", "No sealed copy is stored for this account. Store one with `sealkeep recovery seal`.");
     const envelope = typeof blob.envelope === "string" ? JSON.parse(blob.envelope) : blob.envelope;
     return openEscrow(envelope, Buffer.from(blob.sealed, "base64"), rawPhrase);
 }
-/* ------------------------------------------------------------------ uploads */
+const incompleteUploads = new WeakMap();
+function incompleteUploadBinding(receipt, dataDir, vaultRef) {
+    const binding = incompleteUploads.get(receipt);
+    if (!binding || binding.dataDir !== resolve(dataDir) || binding.vaultRef !== vaultRef) {
+        fail("invalid_argument", "An incomplete upload retry requires its original account-scoped native receipt");
+    }
+    return binding;
+}
+async function pendingUploadDescriptor(binding, input, signal) {
+    await binding.assertCurrent();
+    // Do not use the listing's legacy fallback: an auth/outage failure is not
+    // permission to write. Walk bounded, monotonic pages and stop at the exact
+    // row. The server scopes every page to the same pinned account token.
+    let before;
+    for (let page = 0; page < 500; page++) {
+        signal?.throwIfAborted();
+        const rows = await call(`/v1/cloud/archives/page${before === undefined ? "" : `?before=${before}`}`, {
+            token: binding.token, signal, maxResponseBytes: 1024 * 1024,
+        });
+        await binding.assertCurrent();
+        if (!Array.isArray(rows) || rows.length > 200)
+            fail("ciphertext_integrity_failed", "The pending archive inventory is malformed");
+        let cursor = before ?? Number.MAX_SAFE_INTEGER;
+        for (const row of rows) {
+            if (!row || !Number.isSafeInteger(row.id) || row.id <= 0 || row.id >= cursor) {
+                fail("ciphertext_integrity_failed", "The pending archive inventory has an invalid cursor");
+            }
+            cursor = row.id;
+        }
+        const matches = rows.filter((row) => row.vault_ref === input.vaultRef);
+        if (matches.length > 1)
+            fail("ciphertext_integrity_failed", "The pending archive ref is ambiguous");
+        if (matches.length === 1) {
+            const row = matches[0];
+            if (row.state !== "pending")
+                fail("lease_expired", "The incomplete archive changed state; retry its current storage proof before uploading");
+            if (!Number.isSafeInteger(input.bytes) || input.bytes <= 0 || row.bytes !== input.bytes
+                || typeof row.ciphertext_sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(row.ciphertext_sha256)
+                || row.ciphertext_sha256.toLowerCase() !== input.ciphertextSha256.toLowerCase()
+                || typeof row.object_key !== "string" || !row.object_key || row.object_key.length > 4096) {
+                fail("ciphertext_integrity_failed", "The incomplete archive does not describe this exact immutable frame");
+            }
+            return { objectKey: row.object_key };
+        }
+        if (rows.length < 200)
+            break;
+        before = cursor;
+    }
+    fail("archive_not_found", "The incomplete archive's exact pending descriptor could not be verified; no upload was attempted");
+}
 /** Asks for permission to write exactly one object. The key is chosen server-side. */
-export async function requestUpload(dataDir, input, preferred) {
-    return call("/v1/cloud/uploads", {
+export async function requestUpload(dataDir, input, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    const resumed = options.incompleteUpload && incompleteUploadBinding(options.incompleteUpload, dataDir, input.vaultRef);
+    if (resumed && (typeof input.ciphertextSha256 !== "string" || !/^[a-f0-9]{64}$/i.test(input.ciphertextSha256)
+        || !Number.isSafeInteger(input.bytes) || input.bytes <= 0)) {
+        fail("invalid_argument", "An incomplete archive retry requires an exact positive size and SHA-256 digest");
+    }
+    if (resumed)
+        await resumed.assertCurrent();
+    // Deliberately `machineCredential` and NOT `machineIdentity`: this must not
+    // claim a fresh identity. A machine the account holder revoked would
+    // otherwise answer its own refusal by enrolling again under a new id, and
+    // Revoke would mean nothing. A machine that has never had a key sends none
+    // and is served as before.
+    const machine = await machineCredential(dataDir, preferred);
+    const pending = resumed && await pendingUploadDescriptor(resumed, input, options.signal);
+    const token = resumed?.token ?? await cloudToken(dataDir, preferred, { signal: options.signal });
+    if (resumed)
+        await resumed.assertCurrent();
+    const lease = await call("/v1/cloud/uploads", {
         method: "POST",
-        token: await cloudToken(dataDir, preferred),
-        body: JSON.stringify({ vault_ref: input.vaultRef, ciphertext_sha256: input.ciphertextSha256, bytes: input.bytes })
+        token,
+        body: JSON.stringify({ vault_ref: input.vaultRef, ciphertext_sha256: input.ciphertextSha256, bytes: input.bytes, ...(machine ?? {}) }),
+        signal: options.signal,
     });
+    if (resumed && pending) {
+        await resumed.assertCurrent();
+        if (lease.vault_ref !== input.vaultRef || lease.object_key !== pending.objectKey
+            || !Number.isSafeInteger(lease.lease_id) || lease.lease_id <= 0
+            || typeof lease.expires_at !== "string" || !Number.isFinite(Date.parse(lease.expires_at)) || Date.parse(lease.expires_at) <= Date.now()) {
+            fail("ciphertext_integrity_failed", "The retry lease does not bind the original pending archive");
+        }
+        // A concurrently completed object must not be overwritten, even with the
+        // same bytes. Unsupported delegations fail closed on this resume path.
+        const upload = lease.upload_url;
+        const method = upload?.method === undefined ? "PUT" : upload.method;
+        let validUrl = false;
+        if (upload && typeof upload === "object" && typeof upload.url === "string") {
+            try {
+                const parsed = new URL(upload.url);
+                validUrl = ["http:", "https:"].includes(parsed.protocol) && !parsed.username && !parsed.password && !parsed.hash;
+            }
+            catch { /* A malformed URL is not a supported native delegation. */ }
+        }
+        // The native signed-upload action returns {url} (no method or headers).
+        // Only omission gets the existing PUT default; explicit unknown values
+        // are not silently reinterpreted as an immutable write delegation.
+        if (lease.vended || !upload || !validUrl || method !== "PUT") {
+            fail("provider_unsupported", "An incomplete archive retry requires a create-only signed PUT");
+        }
+        const headers = new Headers(upload.headers);
+        if (headers.has("if-none-match") && headers.get("if-none-match") !== "*") {
+            fail("provider_unsupported", "The retry lease conflicts with create-only storage");
+        }
+        headers.set("if-none-match", "*");
+        lease.upload_url = { ...upload, method: "PUT", headers: Object.fromEntries(headers) };
+    }
+    return lease;
 }
 /**
  * What this build can actually honor, checked at run time because a lease
@@ -314,18 +2083,15 @@ function assertVendedSignable(v) {
  * rather than two. A lease naming a delegation this build does not know is
  * refused before a single byte or signature leaves the machine.
  */
-export async function putCiphertext(lease, ciphertext, signal) {
+export async function putCiphertextStream(lease, chunks, bytes, signal) {
     if (lease.vended) {
         assertVendedSignable(lease.vended);
         assertVendedFresh(lease.vended, lease);
         const { S3UploadClient } = await import("./providers/s3.js");
         const v = lease.vended;
         const client = new S3UploadClient(v.provider, { provider: v.provider, region: v.region, bucket: v.bucket, host: v.host, port: v.port, protocol: v.protocol }, { accessKeyId: v.akid, secretAccessKey: v.secret_access_key, sessionToken: v.session_token });
-        await client.upload({
-            archiveId: lease.vault_ref, provider: v.provider, objectKey: lease.object_key, expiresAt: lease.expires_at,
-            method: "MULTIPART", uploadUrl: "", requiredHeaders: {}, status: "active", uploadable: true
-        }, ciphertext);
-        return;
+        const uploaded = await client.uploadStream(lease.object_key, chunks, { ...(signal ? { signal } : {}) });
+        return { bytes: uploaded.bytes, remoteChecksum: uploaded.remoteChecksum };
     }
     if (!lease.upload_url?.url)
         fail("internal", "Sealkeep Cloud returned a lease with nowhere to upload to");
@@ -336,9 +2102,53 @@ export async function putCiphertext(lease, ciphertext, signal) {
     if (!/^https?:\/\//i.test(url)) {
         fail("internal", "Sealkeep Cloud returned an upload address that is not an http(s) URL; refusing to send the archive anywhere else.");
     }
-    const response = await fetch(url, { method: method || "PUT", headers, body: new Uint8Array(ciphertext), ...(signal ? { signal } : {}) });
+    const streamedHeaders = { ...headers };
+    if (!Object.keys(streamedHeaders).some((name) => name.toLowerCase() === "content-length")) {
+        streamedHeaders["content-length"] = String(bytes);
+    }
+    const body = requestBody(chunks);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: method || "PUT",
+            headers: streamedHeaders,
+            body: body,
+            duplex: "half",
+            ...(signal ? { signal } : {}),
+        });
+    }
+    finally {
+        body.destroy();
+    }
     if (!response.ok)
         fail("internal", `Storage rejected the upload: ${response.status} ${(await response.text()).slice(0, 200)}`);
+    return { bytes, remoteChecksum: null };
+}
+/** Small-object compatibility (managed chunks/index); archives use the stream door. */
+export async function putCiphertext(lease, ciphertext, signal) {
+    await putCiphertextStream(lease, oneChunk(ciphertext), ciphertext.length, signal);
+}
+/** Background-only opt-in; foreground reads retain their existing behavior.
+ * Pace before consumption and checkpoint after the consumer hashes/stages the
+ * chunk, so large framed metadata and payloads share the same wire budget. */
+function backgroundObjectReadStream(dataDir, source, options) {
+    if (!options.maxBytesPerSecond && !options.onProgress && !options.onYield)
+        return source;
+    const paced = options.maxBytesPerSecond
+        ? paceBackgroundByteStream(dataDir, source, options.maxBytesPerSecond, {
+            signal: options.signal, now: options.paceNow, sleep: options.paceSleep,
+        }) : source;
+    return (async function* () {
+        let bytes = 0;
+        for await (const chunk of paced) {
+            options.signal?.throwIfAborted();
+            yield chunk;
+            bytes += chunk.length;
+            options.onProgress?.(bytes);
+            await options.onYield?.();
+            options.signal?.throwIfAborted();
+        }
+    })();
 }
 /**
  * Proves managed storage is holding the bytes we sent, before we tell retention
@@ -353,7 +2163,35 @@ export async function putCiphertext(lease, ciphertext, signal) {
  * customer could push to storage that kept nothing and then have retention
  * trash the only copy.
  */
-async function verifyStored(dataDir, lease, object, digest, preferred) {
+async function verifyStored(dataDir, lease, object, preferred, options = {}) {
+    // Read-back is part of the same background transfer, including retry
+    // adoption. A paced PUT must not be followed by an unpaced full GET.
+    const readback = (chunks) => backgroundObjectReadStream(dataDir, chunks, options);
+    if (options.incompleteUpload) {
+        const binding = incompleteUploadBinding(options.incompleteUpload, dataDir, lease.vault_ref);
+        await binding.assertCurrent();
+        const descriptor = await call(`/v1/cloud/archives/${encodeURIComponent(lease.vault_ref)}/download`, {
+            token: binding.token, signal: options.signal, maxResponseBytes: 64 * 1024,
+        });
+        await binding.assertCurrent();
+        if (descriptor.vault_ref !== lease.vault_ref || descriptor.object_key !== lease.object_key
+            || descriptor.bytes !== object.bytes || descriptor.ciphertext_sha256 !== object.digest) {
+            fail("ciphertext_integrity_failed", "The completed retry does not describe the original immutable frame");
+        }
+        const hash = createHash("sha256");
+        let bytes = 0;
+        for await (const chunk of readback(await fetchLeasedObjectStream(descriptor, { signal: options.signal }))) {
+            bytes += chunk.length;
+            if (bytes > object.bytes)
+                fail("ciphertext_integrity_failed", "The resumed archive read-back exceeded its immutable size");
+            hash.update(chunk);
+        }
+        await binding.assertCurrent();
+        if (bytes !== object.bytes || hash.digest("hex") !== object.digest) {
+            fail("ciphertext_integrity_failed", "The resumed archive read-back does not match its immutable size and digest");
+        }
+        return null;
+    }
     if (lease.vended) {
         assertVendedSignable(lease.vended);
         assertVendedFresh(lease.vended, lease);
@@ -368,26 +2206,35 @@ async function verifyStored(dataDir, lease, object, digest, preferred) {
         });
         if (!head.exists)
             return "the provider does not report the object as present";
-        if (head.bytes !== object.length)
-            return `the provider stored ${head.bytes} bytes; ${object.length} were sent`;
+        if (head.bytes !== object.bytes)
+            return `the provider stored ${head.bytes} bytes; ${object.bytes} were sent`;
+        if (object.remoteChecksum && head.checksum !== object.remoteChecksum) {
+            return `the provider reported checksum ${head.checksum ?? "none"}; the upload reported ${object.remoteChecksum}`;
+        }
         return null;
     }
     // A presigned PUT URL cannot be reused for a HEAD, so the only proof
     // available on this path is reading the object back and hashing it. That
     // costs egress on every push, which is a real reason to finish moving
     // managed storage onto a provider that vends credentials instead.
-    const roundTrip = await pullCiphertext(dataDir, lease.vault_ref, preferred);
-    if (roundTrip.bytes !== object.length)
-        return `storage returned ${roundTrip.bytes} bytes; ${object.length} were sent`;
-    if (sha256(roundTrip.ciphertext) !== digest)
+    const roundTrip = await digestChunks(readback(await pullCiphertextStream(dataDir, lease.vault_ref, preferred, { signal: options.signal })));
+    if (roundTrip.bytes !== object.bytes)
+        return `storage returned ${roundTrip.bytes} bytes; ${object.bytes} were sent`;
+    if (roundTrip.sha256Hex !== object.digest)
         return "the bytes read back do not match what was uploaded";
     return null;
 }
-export async function completeUpload(dataDir, leaseId, bytes, preferred) {
+export async function completeUpload(dataDir, leaseId, bytes, preferred, options = {}) {
+    // The machine key is what stamps this archive as ours. Sending it here is the
+    // whole reason a later delete can be refused to anybody else: attribution has
+    // to happen at the moment of writing, because afterwards nothing in the row
+    // remembers who put it there.
+    const machine = await machineIdentity(dataDir, preferred, options);
     return call(`/v1/cloud/uploads/${leaseId}/complete`, {
         method: "POST",
-        token: await cloudToken(dataDir, preferred),
-        body: JSON.stringify({ bytes })
+        token: await cloudToken(dataDir, preferred, { signal: options.signal }),
+        body: JSON.stringify({ bytes, ...(machine ?? {}) }),
+        signal: options.signal,
     });
 }
 /** What managed storage is holding for this account. The ref is what `sealkeep open` takes. */
@@ -420,147 +2267,815 @@ export async function gdriveRefresh(dataDir, refreshToken, preferred) {
         method: "POST", token: await cloudToken(dataDir, preferred),
         body: JSON.stringify({ refresh_token: refreshToken })
     });
-    return { accessToken: fresh.access_token, expiresIn: fresh.expires_in ?? 3600 };
+    return { accessToken: fresh.access_token, expiresIn: fresh.expires_in ?? 3600 };
+}
+export async function gdriveClaim(dataDir, state, preferred) {
+    try {
+        return await call(`/v1/cloud/gdrive/claim`, {
+            method: "POST", token: await cloudToken(dataDir, preferred),
+            body: JSON.stringify({ state })
+        });
+    }
+    catch (error) {
+        if (isSealkeepError(error) && /returned 404|No pending/i.test(error.message))
+            return null;
+        throw error;
+    }
+}
+/**
+ * The consent flow for the shared client. Two shapes, decided by the server's
+ * registered redirect: a REMOTE https callback (the plane exchanges and parks
+ * the tokens; this machine polls its one-time state — works even when the
+ * browser lives on another device), or a loopback listener that catches the
+ * code here and exchanges through the authed endpoint.
+ */
+export async function connectGdriveViaCloud(dataDir, options = {}) {
+    const { createServer } = await import("node:http");
+    const { randomBytes } = await import("node:crypto");
+    const config = await gdriveOauthConfig(dataDir, options.preferred);
+    const redirect = new URL(config.redirect_uri);
+    const state = randomBytes(16).toString("base64url");
+    const resolveAccountId = options.accountIdResolver
+        ?? (async (accessToken) => (await import("./providers/gdrive.js")).gdriveAccountId(accessToken));
+    if (redirect.protocol === "https:") {
+        const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+        consent.searchParams.set("client_id", config.client_id);
+        consent.searchParams.set("redirect_uri", config.redirect_uri);
+        consent.searchParams.set("response_type", "code");
+        consent.searchParams.set("scope", config.scope);
+        consent.searchParams.set("access_type", "offline");
+        consent.searchParams.set("prompt", "consent");
+        consent.searchParams.set("state", state);
+        options.onConsentUrl?.(consent.toString());
+        const { launchBrowser } = await import("./providers/gdrive.js");
+        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
+        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+        while (Date.now() < deadline) {
+            const parcel = await gdriveClaim(dataDir, state, options.preferred);
+            if (parcel) {
+                const accountId = await resolveAccountId(parcel.access_token);
+                return { kind: "gdrive", refreshToken: parcel.refresh_token, clientId: config.client_id, exchange: "cloud", accountId };
+            }
+            await new Promise((rest) => setTimeout(rest, options.pollMs ?? 2000));
+        }
+        throw new SealkeepError("unauthorized", "No consent arrived in time. Run the connect again.");
+    }
+    const server = createServer();
+    await new Promise((ready, refuse) => { server.once("error", refuse); server.listen(Number(redirect.port), "127.0.0.1", ready); });
+    let timer;
+    const code = new Promise((resolve, reject) => {
+        timer = setTimeout(() => reject(new SealkeepError("unauthorized", "No response from the browser in time. Run the connect again.")), options.timeoutMs ?? 300_000);
+        server.on("request", (request, response) => {
+            const url = new URL(request.url ?? "/", config.redirect_uri);
+            if (url.pathname !== redirect.pathname) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            const deny = (message) => {
+                response.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                response.end("<p>Sealkeep could not finish connecting. Return to the terminal.</p>");
+                reject(new SealkeepError("unauthorized", message));
+            };
+            if (url.searchParams.get("error"))
+                return deny(`Google reported: ${url.searchParams.get("error")}`);
+            if (url.searchParams.get("state") !== state)
+                return deny("The browser reply did not match this connection attempt (state mismatch)");
+            const received = url.searchParams.get("code");
+            if (!received)
+                return deny("The browser reply carried no authorization code");
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            response.end("<p>Sealkeep is connected to Google Drive. You can close this tab.</p>");
+            resolve(received);
+        });
+    });
+    code.catch(() => { });
+    const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+    consent.searchParams.set("client_id", config.client_id);
+    consent.searchParams.set("redirect_uri", config.redirect_uri);
+    consent.searchParams.set("response_type", "code");
+    consent.searchParams.set("scope", config.scope);
+    consent.searchParams.set("access_type", "offline");
+    consent.searchParams.set("prompt", "consent");
+    consent.searchParams.set("state", state);
+    try {
+        options.onConsentUrl?.(consent.toString());
+        const { launchBrowser } = await import("./providers/gdrive.js");
+        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
+        const authorizationCode = await code;
+        const tokens = await gdriveExchange(dataDir, { code: authorizationCode, redirectUri: config.redirect_uri }, options.preferred);
+        const accountId = await resolveAccountId(tokens.access_token);
+        return { kind: "gdrive", refreshToken: tokens.refresh_token, clientId: config.client_id, exchange: "cloud", accountId };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        server.close();
+    }
+}
+export async function pushIndexObject(dataDir, kind, body, preferred, options = {}) {
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const lease = await call(`/v1/cloud/index/upload`, { method: "POST", body: JSON.stringify({ kind, bytes: body.length }), token, signal: options.signal });
+    const target = lease.upload_url ?? fail("internal", "The control plane vended no upload URL for the index slot");
+    const stream = requestBody(options.maxBytesPerSecond
+        ? paceBackgroundByteStream(dataDir, bufferChunks(body), options.maxBytesPerSecond, { signal: options.signal, onProgress: options.onProgress })
+        : bufferChunks(body));
+    const headers = { ...(target.headers ?? {}) };
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === "content-length"))
+        headers["content-length"] = String(body.length);
+    let response;
+    try {
+        response = await fetch(target.url, { method: target.method || "PUT", headers, body: stream, duplex: "half", signal: options.signal });
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!response.ok)
+        fail("internal", `The index ${kind} upload was refused: ${response.status} ${response.statusText}`);
+}
+/** Publishes a large sealed index without reading the whole ciphertext back
+ * into the JS heap. The caller has already atomically committed this file. */
+export async function pushIndexFile(dataDir, kind, path, preferred, options = {}) {
+    const bytes = (await stat(path)).size;
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const lease = await call(`/v1/cloud/index/upload`, { method: "POST", body: JSON.stringify({ kind, bytes }), token, signal: options.signal });
+    const target = lease.upload_url ?? fail("internal", "The control plane vended no upload URL for the index slot");
+    const chunks = fileChunks(path, { signal: options.signal });
+    const stream = requestBody(options.maxBytesPerSecond
+        ? paceBackgroundByteStream(dataDir, chunks, options.maxBytesPerSecond, { signal: options.signal, onProgress: options.onProgress })
+        : chunks);
+    const headers = { ...(target.headers ?? {}) };
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === "content-length"))
+        headers["content-length"] = String(bytes);
+    let response;
+    try {
+        response = await fetch(target.url, { method: target.method || "PUT", headers, body: stream, duplex: "half", signal: options.signal });
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!response.ok)
+        fail("internal", `The index ${kind} upload was refused: ${response.status} ${response.statusText}`);
+}
+export async function pullIndexObject(dataDir, kind, preferred, options = {}) {
+    const token = await cloudToken(dataDir, preferred, { renew: options.renewToken !== false, signal: options.signal });
+    const lease = await call(`/v1/cloud/index/download?kind=${kind}`, { token, signal: options.signal }).catch((error) => {
+        if (isSealkeepError(error) && /not.*found|no index/i.test(error.message))
+            return null;
+        throw error;
+    });
+    if (!lease?.download?.url)
+        return null;
+    const response = await fetch(lease.download.url, { signal: options.signal });
+    if (response.status === 404)
+        return null;
+    if (!response.ok)
+        fail("internal", `The index ${kind} download was refused: ${response.status} ${response.statusText}`);
+    const body = responseBodyChunks(response);
+    return collectChunks(options.maxBytesPerSecond ? paceBackgroundByteStream(dataDir, body, options.maxBytesPerSecond, { signal: options.signal, onProgress: options.onProgress }) : body, Number.MAX_SAFE_INTEGER);
+}
+export async function pushTeamIndexObject(dataDir, spaceKey, kind, body, preferred, options = {}) {
+    const lease = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/index/upload`, await cloudToken(dataDir, preferred, { signal: options.signal }), { method: "POST", body: JSON.stringify({ kind, bytes: body.length }), signal: options.signal });
+    const target = lease.upload_url ?? fail("internal", "The control plane vended no upload URL for the team index slot");
+    const stream = requestBody(options.maxBytesPerSecond
+        ? paceBackgroundByteStream(dataDir, bufferChunks(body), options.maxBytesPerSecond, { signal: options.signal, onProgress: options.onProgress })
+        : bufferChunks(body));
+    const headers = { ...(target.headers ?? {}) };
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === "content-length"))
+        headers["content-length"] = String(body.length);
+    let response;
+    try {
+        response = await fetch(target.url, { method: target.method ?? "PUT", headers, body: stream, duplex: "half", signal: options.signal });
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!response.ok)
+        fail("internal", `The team index ${kind} upload was refused: ${response.status} ${response.statusText}`);
+}
+export async function pullTeamIndexObject(dataDir, spaceKey, kind, preferred, options = {}) {
+    const lease = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(spaceKey)}/index/download?kind=${kind}`, await cloudToken(dataDir, preferred, { signal: options.signal }), { signal: options.signal }).catch((error) => {
+        if (isSealkeepError(error) && /not.*found|no index/i.test(error.message))
+            return null;
+        throw error;
+    });
+    if (!lease?.download?.url)
+        return null;
+    const response = await fetch(lease.download.url, { method: lease.download.method ?? "GET", headers: lease.download.headers, signal: options.signal });
+    if (response.status === 404)
+        return null;
+    if (!response.ok)
+        fail("internal", `The team index ${kind} download was refused: ${response.status} ${response.statusText}`);
+    const body = responseBodyChunks(response);
+    return collectChunks(options.maxBytesPerSecond ? paceBackgroundByteStream(dataDir, body, options.maxBytesPerSecond, { signal: options.signal, onProgress: options.onProgress }) : body, Number.MAX_SAFE_INTEGER);
+}
+const teamSnapshotCacheIdentities = new WeakMap();
+/** Only native current-head snapshots can identify a derived source-facts cache.
+ * The identity contains no lease or permission and is independently copied. */
+export function teamSnapshotCacheIdentity(snapshot) {
+    const identity = teamSnapshotCacheIdentities.get(snapshot);
+    return identity ? structuredClone(identity) : undefined;
+}
+const V2_UNSUPPORTED = {
+    status: "unsupported",
+    reason: "endpoint_unsupported",
+};
+export const INDEX_REVISION_CONFLICT_REMOTE_CODE = "INDEX_REVISION_CONFLICT";
+/** The hosted v2 finalizer currently uses one S3 CopyObject (<5 GiB). */
+export const MAX_MANAGED_INDEX_V2_BLOB_BYTES = 4 * 1024 * 1024 * 1024;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function v2EndpointUnsupported(error) {
+    if (!isSealkeepError(error))
+        return false;
+    const status = Number(error.details.httpStatus);
+    const remoteCode = String(error.details.remoteCode ?? "").toUpperCase();
+    return status === 404 || status === 405 || status === 501
+        || remoteCode === "ENDPOINT_UNSUPPORTED" || remoteCode === "NOT_IMPLEMENTED";
+}
+function v2HeadAbsent(error) {
+    return isSealkeepError(error)
+        && Number(error.details.httpStatus) === 404
+        && /no (?:v2 )?(?:team )?(?:search )?index (?:has been )?published/i.test(error.message);
+}
+function indexV2Base(scope) {
+    return scope.kind === "account"
+        ? "/v1/cloud/index/v2"
+        : `/v1/cloud/team/spaces/${encodeURIComponent(scope.spaceKey)}/index/v2`;
+}
+function canonicalCoverage(input) {
+    if (!isRecord(input))
+        fail("invalid_argument", "Index coverage must be an archive-to-entry-digest map");
+    const result = {};
+    for (const archiveRef of Object.keys(input).sort()) {
+        const digest = input[archiveRef];
+        if (!archiveRef || typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest)) {
+            fail("invalid_argument", "Index coverage contains an invalid archive reference or entry digest");
+        }
+        result[archiveRef] = digest;
+    }
+    return result;
+}
+function wireCoverage(value) {
+    let parsed = value;
+    if (typeof parsed === "string") {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            fail("internal", "Sealkeep Cloud returned malformed index coverage");
+        }
+    }
+    if (!isRecord(parsed))
+        fail("internal", "Sealkeep Cloud returned no committed index coverage");
+    const result = {};
+    for (const archiveRef of Object.keys(parsed).sort()) {
+        const digest = parsed[archiveRef];
+        if (!archiveRef || typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest)) {
+            fail("internal", "Sealkeep Cloud returned invalid committed index coverage");
+        }
+        result[archiveRef] = digest;
+    }
+    return result;
+}
+function wireNumber(value, label, minimum = 0) {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number) || number < minimum)
+        fail("internal", `Sealkeep Cloud returned an invalid ${label}`);
+    return number;
+}
+function wireText(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        fail("internal", `Sealkeep Cloud returned no ${label}`);
+    return value;
+}
+function wireDownload(value, label) {
+    if (!isRecord(value) || typeof value.url !== "string" || !value.url) {
+        fail("internal", `Sealkeep Cloud returned no ${label} download URL for the committed index generation`);
+    }
+    const headers = isRecord(value.headers)
+        ? Object.fromEntries(Object.entries(value.headers).map(([name, header]) => [name, String(header)]))
+        : undefined;
+    return {
+        url: value.url,
+        ...(typeof value.method === "string" && value.method ? { method: value.method } : {}),
+        ...(headers ? { headers } : {}),
+    };
+}
+function wireObject(raw, kind) {
+    const nested = isRecord(raw[kind]) ? raw[kind] : {};
+    const downloads = isRecord(raw.downloads) ? raw.downloads : {};
+    const objectKey = nested.object_key ?? nested.objectKey ?? raw[`${kind}_object_key`] ?? raw[`${kind}ObjectKey`];
+    const bytes = nested.bytes ?? raw[`${kind}_bytes`] ?? raw[`${kind}Bytes`];
+    const hash = nested.sha256 ?? nested.ciphertext_sha256 ?? raw[`${kind}_sha256`] ?? raw[`${kind}Sha256`];
+    const sha = wireText(hash, `${kind} SHA-256`).toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(sha))
+        fail("internal", `Sealkeep Cloud returned an invalid ${kind} SHA-256`);
+    const download = nested.download ?? downloads[kind] ?? raw[`${kind}_download`] ?? raw[`${kind}Download`];
+    return {
+        receipt: {
+            objectKey: wireText(objectKey, `${kind} object key`),
+            bytes: wireNumber(bytes, `${kind} byte count`),
+            sha256: sha,
+        },
+        download: wireDownload(download, kind),
+    };
+}
+function wireHead(answer) {
+    if (!isRecord(answer))
+        fail("internal", "Sealkeep Cloud returned a malformed index head");
+    const value = Object.hasOwn(answer, "head") ? answer.head : answer;
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        fail("internal", "Sealkeep Cloud returned a malformed index head");
+    const blob = wireObject(value, "blob");
+    const meta = wireObject(value, "meta");
+    const membership = value.membership_version ?? value.membershipVersion;
+    const receipt = {
+        revision: wireNumber(value.revision, "index revision", 1),
+        generationId: wireText(value.generation_id ?? value.generationId, "index generation id"),
+        blob: blob.receipt,
+        meta: meta.receipt,
+        coverageJson: wireCoverage(value.coverage_json ?? value.coverageJson),
+        ...(membership === undefined || membership === null
+            ? {}
+            : { membershipVersion: wireNumber(membership, "index membership version", 1) }),
+        committedAt: wireText(value.committed_at ?? value.committedAt, "index commit time"),
+    };
+    return { receipt, downloads: { blob: blob.download, meta: meta.download } };
+}
+async function indexV2HeadWithToken(dataDir, scope, token, signal) {
+    try {
+        const answer = await call(`${indexV2Base(scope)}/head`, {
+            token,
+            signal,
+            backoffDataDir: dataDir,
+        });
+        return { status: "ok", head: wireHead(answer) };
+    }
+    catch (error) {
+        if (v2HeadAbsent(error))
+            return { status: "ok", head: null };
+        if (v2EndpointUnsupported(error))
+            return V2_UNSUPPORTED;
+        throw error;
+    }
+}
+async function indexV2Head(dataDir, scope, preferred, options = {}) {
+    const token = await cloudToken(dataDir, preferred, {
+        renew: options.renewToken !== false,
+        signal: options.signal,
+    });
+    return indexV2HeadWithToken(dataDir, scope, token, options.signal);
+}
+export function headIndexGenerationV2(dataDir, preferred, options = {}) {
+    return indexV2Head(dataDir, { kind: "account" }, preferred, options);
+}
+export function headTeamIndexGenerationV2(dataDir, spaceKey, preferred, options = {}) {
+    return indexV2Head(dataDir, { kind: "team", spaceKey }, preferred, options);
+}
+function bodyChunks(body, signal) {
+    return Buffer.isBuffer(body) ? bufferChunks(body) : fileChunks(body.path, { signal });
+}
+async function bodyDigest(body, signal, onProgress) {
+    if (Buffer.isBuffer(body)) {
+        return {
+            bytes: body.length,
+            sha256: createHash("sha256").update(body).digest("hex"),
+            md5: createHash("md5").update(body).digest("hex"),
+        };
+    }
+    const sha256 = createHash("sha256");
+    const md5 = createHash("md5");
+    let bytes = 0;
+    for await (const chunk of fileChunks(body.path, { signal })) {
+        sha256.update(chunk);
+        md5.update(chunk);
+        bytes += chunk.length;
+        onProgress?.(chunk.length);
+    }
+    return { bytes, sha256: sha256.digest("hex"), md5: md5.digest("hex") };
+}
+async function putIndexGenerationObject(dataDir, target, body, expected, options) {
+    const sentHash = createHash("sha256");
+    let sentBytes = 0;
+    let chunks = tapDigest(bodyChunks(body, options.signal), sentHash, (bytes) => {
+        sentBytes += bytes;
+        options.onProgress?.(bytes);
+    });
+    if (options.maxBytesPerSecond) {
+        chunks = paceBackgroundByteStream(dataDir, chunks, options.maxBytesPerSecond, {
+            signal: options.signal,
+        });
+    }
+    const stream = requestBody(chunks);
+    const headers = { ...(target.headers ?? {}) };
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === "content-length")) {
+        headers["content-length"] = String(expected.bytes);
+    }
+    let response;
+    try {
+        response = await fetch(target.url, {
+            method: target.method ?? "PUT",
+            headers,
+            body: stream,
+            duplex: "half",
+            signal: options.signal,
+        });
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!response.ok)
+        fail("internal", `The index generation upload was refused: ${response.status} ${response.statusText}`);
+    if (sentBytes !== expected.bytes || sentHash.digest("hex") !== expected.sha256) {
+        fail("ciphertext_integrity_failed", "The sealed index changed while its immutable generation was being uploaded");
+    }
+}
+async function prepareIndexGenerationObject(dataDir, scope, context, generationId, kind, bytes, expectedMembershipVersion, signal) {
+    try {
+        const answer = await call(`${indexV2Base(scope)}/generations`, {
+            method: "POST",
+            token: context.token,
+            backoffDataDir: dataDir,
+            signal,
+            body: JSON.stringify({
+                kind,
+                generation_id: generationId,
+                bytes,
+                device_id: context.machine.device_id,
+                machine_key: context.machine.machine_key,
+                ...(scope.kind === "team" ? { expected_membership_version: expectedMembershipVersion } : {}),
+            }),
+        });
+        return answer.upload_url ?? answer.upload
+            ?? fail("internal", "The control plane vended no upload URL for the index generation");
+    }
+    catch (error) {
+        if (v2EndpointUnsupported(error))
+            return V2_UNSUPPORTED;
+        throw error;
+    }
+}
+async function readHeadObject(dataDir, kind, descriptor, lease, options, collect) {
+    const collectLimit = kind === "meta"
+        ? Math.min(MAX_FRAME_METADATA_BYTES, options.maxBytes ?? Number.MAX_SAFE_INTEGER)
+        : options.maxBytes ?? Number.MAX_SAFE_INTEGER;
+    if (collect && descriptor.bytes > collectLimit) {
+        fail("provider_unsupported", `The committed index ${kind} is larger than this buffered read permits`);
+    }
+    const response = await fetch(lease.url, {
+        method: lease.method ?? "GET",
+        headers: lease.headers,
+        signal: options.signal,
+    });
+    if (!response.ok)
+        fail("internal", `The committed index ${kind} read-back was refused: ${response.status} ${response.statusText}`);
+    const hash = createHash("sha256");
+    let bytes = 0;
+    let chunks = responseBodyChunks(response);
+    if (options.maxBytesPerSecond) {
+        chunks = paceBackgroundByteStream(dataDir, chunks, options.maxBytesPerSecond, {
+            signal: options.signal,
+            onProgress: options.onProgress,
+        });
+    }
+    chunks = tapDigest(chunks, hash, (count) => {
+        bytes += count;
+        if (!options.maxBytesPerSecond)
+            options.onProgress?.(count);
+    });
+    let body = null;
+    if (collect)
+        body = await collectChunks(chunks, collectLimit);
+    else
+        for await (const _chunk of chunks) { /* hash-checked without retaining the blob */ }
+    const actual = hash.digest("hex");
+    if (bytes !== descriptor.bytes || actual !== descriptor.sha256) {
+        fail("ciphertext_integrity_failed", `The committed index ${kind} did not match its generation receipt`, {
+            expectedBytes: descriptor.bytes,
+            actualBytes: bytes,
+        });
+    }
+    return body;
 }
-export async function gdriveClaim(dataDir, state, preferred) {
+async function verifiedHead(dataDir, head, options) {
+    const meta = await readHeadObject(dataDir, "meta", head.receipt.meta, head.downloads.meta, options, true);
+    await readHeadObject(dataDir, "blob", head.receipt.blob, head.downloads.blob, options, false);
     try {
-        return await call(`/v1/cloud/gdrive/claim`, {
-            method: "POST", token: await cloudToken(dataDir, preferred),
-            body: JSON.stringify({ state })
+        return JSON.parse(meta.toString("utf8"));
+    }
+    catch {
+        return fail("ciphertext_integrity_failed", "The committed index metadata is not a valid sealed envelope");
+    }
+}
+async function publishIndexV2(dataDir, scope, input, preferred, options = {}) {
+    if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+        fail("invalid_argument", "The expected index revision must be zero or a positive integer");
+    }
+    if (scope.kind === "team" && (!Number.isSafeInteger(input.expectedMembershipVersion) || Number(input.expectedMembershipVersion) < 1)) {
+        fail("invalid_argument", "A team index publication requires the exact current membership version");
+    }
+    const coverage = canonicalCoverage(input.coverageJson);
+    const meta = Buffer.from(JSON.stringify(input.envelope), "utf8");
+    if (meta.length > MAX_FRAME_METADATA_BYTES)
+        fail("invalid_argument", "The sealed index envelope is too large to publish");
+    const declaredBlobBytes = Buffer.isBuffer(input.ciphertext)
+        ? input.ciphertext.length
+        : (await stat(input.ciphertext.path)).size;
+    if (declaredBlobBytes < 1 || declaredBlobBytes > MAX_MANAGED_INDEX_V2_BLOB_BYTES) {
+        fail("provider_unsupported", `The managed search index is ${declaredBlobBytes} bytes; immutable v2 generations currently support at most ${MAX_MANAGED_INDEX_V2_BLOB_BYTES} bytes`);
+    }
+    const [blobDigest, metaDigest] = await Promise.all([
+        bodyDigest(input.ciphertext, options.signal, options.onProgress),
+        bodyDigest(meta, options.signal),
+    ]);
+    if (blobDigest.bytes !== declaredBlobBytes) {
+        fail("ciphertext_integrity_failed", "The sealed index size changed while its immutable generation was being prepared");
+    }
+    const generationId = randomUUID();
+    const context = await managedDeleteContext(dataDir, preferred, { signal: options.signal });
+    if (!context.machine)
+        fail("forbidden", "This machine needs an active Sealkeep Cloud device identity before it can publish the search index");
+    const bound = context;
+    const blobTarget = await prepareIndexGenerationObject(dataDir, scope, bound, generationId, "blob", blobDigest.bytes, input.expectedMembershipVersion, options.signal);
+    if ("status" in blobTarget)
+        return blobTarget;
+    await putIndexGenerationObject(dataDir, blobTarget, input.ciphertext, blobDigest, options);
+    const metaTarget = await prepareIndexGenerationObject(dataDir, scope, bound, generationId, "meta", metaDigest.bytes, input.expectedMembershipVersion, options.signal);
+    if ("status" in metaTarget)
+        return metaTarget;
+    await putIndexGenerationObject(dataDir, metaTarget, meta, metaDigest, options);
+    if (await stableCloudAuthGeneration(dataDir) !== context.authGeneration) {
+        fail("unauthorized", "The Sealkeep Cloud account changed while the index generation was being prepared. The uncommitted objects were left unreachable.");
+    }
+    try {
+        const commit = await call(`${indexV2Base(scope)}/generations/${encodeURIComponent(generationId)}/commit`, {
+            method: "POST",
+            token: context.token,
+            backoffDataDir: dataDir,
+            signal: options.signal,
+            body: JSON.stringify({
+                generation_id: generationId,
+                expected_revision: input.expectedRevision,
+                coverage_json: coverage,
+                blob_bytes: blobDigest.bytes,
+                blob_sha256: blobDigest.sha256,
+                blob_md5: blobDigest.md5,
+                meta_bytes: metaDigest.bytes,
+                meta_sha256: metaDigest.sha256,
+                meta_md5: metaDigest.md5,
+                device_id: bound.machine.device_id,
+                machine_key: bound.machine.machine_key,
+                ...(scope.kind === "team" ? { expected_membership_version: input.expectedMembershipVersion } : {}),
+            }),
         });
+        if (commit?.status === "conflict") {
+            const current = await indexV2HeadWithToken(dataDir, scope, context.token, options.signal);
+            if (current.status === "unsupported")
+                return current;
+            return { status: "conflict", head: current.head };
+        }
     }
     catch (error) {
-        if (isVaultlineError(error) && /returned 404|No pending/i.test(error.message))
-            return null;
+        if (v2EndpointUnsupported(error))
+            return V2_UNSUPPORTED;
+        if (isSealkeepError(error)
+            && error.code === "lease_expired"
+            && String(error.details.remoteCode ?? "").toUpperCase() === INDEX_REVISION_CONFLICT_REMOTE_CODE) {
+            const current = await indexV2HeadWithToken(dataDir, scope, context.token, options.signal);
+            if (current.status === "unsupported")
+                return current;
+            return { status: "conflict", head: current.head };
+        }
         throw error;
     }
+    const observed = await indexV2HeadWithToken(dataDir, scope, context.token, options.signal);
+    if (observed.status === "unsupported")
+        return observed;
+    const head = observed.head;
+    if (!head || head.receipt.generationId !== generationId) {
+        // Our CAS committed, then another writer advanced the head before the
+        // read-back.  That is convergence work, not corruption: expose the new
+        // head so the caller can pull, merge and retry.
+        return { status: "conflict", head };
+    }
+    if (head.receipt.revision !== input.expectedRevision + 1
+        || head.receipt.blob.bytes !== blobDigest.bytes
+        || head.receipt.blob.sha256 !== blobDigest.sha256
+        || head.receipt.meta.bytes !== metaDigest.bytes
+        || head.receipt.meta.sha256 !== metaDigest.sha256
+        || JSON.stringify(head.receipt.coverageJson) !== JSON.stringify(coverage)
+        || (scope.kind === "team" && head.receipt.membershipVersion !== input.expectedMembershipVersion)) {
+        fail("ciphertext_integrity_failed", "Sealkeep Cloud did not expose the exact committed index generation");
+    }
+    const envelope = await verifiedHead(dataDir, head, options);
+    if (await stableCloudAuthGeneration(dataDir) !== context.authGeneration) {
+        fail("unauthorized", "The Sealkeep Cloud account changed during index read-back. The committed generation was not recorded locally.");
+    }
+    return { status: "committed", receipt: head.receipt, head, verifiedReadBack: true, envelope };
 }
-/**
- * The consent flow for the shared client. Two shapes, decided by the server's
- * registered redirect: a REMOTE https callback (the plane exchanges and parks
- * the tokens; this machine polls its one-time state — works even when the
- * browser lives on another device), or a loopback listener that catches the
- * code here and exchanges through the authed endpoint.
- */
-export async function connectGdriveViaCloud(dataDir, options = {}) {
-    const { createServer } = await import("node:http");
-    const { randomBytes } = await import("node:crypto");
-    const config = await gdriveOauthConfig(dataDir, options.preferred);
-    const redirect = new URL(config.redirect_uri);
-    const state = randomBytes(16).toString("base64url");
-    if (redirect.protocol === "https:") {
-        const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
-        consent.searchParams.set("client_id", config.client_id);
-        consent.searchParams.set("redirect_uri", config.redirect_uri);
-        consent.searchParams.set("response_type", "code");
-        consent.searchParams.set("scope", config.scope);
-        consent.searchParams.set("access_type", "offline");
-        consent.searchParams.set("prompt", "consent");
-        consent.searchParams.set("state", state);
-        options.onConsentUrl?.(consent.toString());
-        const { launchBrowser } = await import("./providers/gdrive.js");
-        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
-        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
-        while (Date.now() < deadline) {
-            const parcel = await gdriveClaim(dataDir, state, options.preferred);
-            if (parcel)
-                return { kind: "gdrive", refreshToken: parcel.refresh_token, clientId: config.client_id, exchange: "cloud" };
-            await new Promise((rest) => setTimeout(rest, options.pollMs ?? 2000));
-        }
-        throw new VaultlineError("unauthorized", "No consent arrived in time. Run the connect again.");
+export function publishIndexGenerationV2(dataDir, input, preferred, options = {}) {
+    return publishIndexV2(dataDir, { kind: "account" }, input, preferred, options);
+}
+export function publishTeamIndexGenerationV2(dataDir, spaceKey, input, preferred, options = {}) {
+    return publishIndexV2(dataDir, { kind: "team", spaceKey }, input, preferred, options);
+}
+async function pullIndexV2Snapshot(dataDir, scope, preferred, options = {}) {
+    const origin = cloudUrl();
+    const token = await cloudToken(dataDir, preferred, {
+        renew: options.renewToken !== false,
+        signal: options.signal,
+    });
+    const authGeneration = await stableCloudAuthGeneration(dataDir);
+    const account = await cachedCloudTokenRead(dataDir, preferred);
+    if (account.token !== token || account.generation !== authGeneration) {
+        fail("unauthorized", "The Sealkeep Cloud account changed before the index snapshot could be read");
     }
-    const server = createServer();
-    await new Promise((ready, refuse) => { server.once("error", refuse); server.listen(Number(redirect.port), "127.0.0.1", ready); });
-    let timer;
-    const code = new Promise((resolve, reject) => {
-        timer = setTimeout(() => reject(new VaultlineError("unauthorized", "No response from the browser in time. Run the connect again.")), options.timeoutMs ?? 300_000);
-        server.on("request", (request, response) => {
-            const url = new URL(request.url ?? "/", config.redirect_uri);
-            if (url.pathname !== redirect.pathname) {
-                response.writeHead(404);
-                response.end();
-                return;
+    const current = await indexV2HeadWithToken(dataDir, scope, token, options.signal);
+    if (current.status === "unsupported")
+        return current;
+    if (!current.head)
+        return { status: "ok", snapshot: null };
+    const receipt = current.head.receipt;
+    const metaLimit = Math.min(MAX_FRAME_METADATA_BYTES, options.maxBytes ?? Number.MAX_SAFE_INTEGER);
+    const snapshotBytes = receipt.meta.bytes + receipt.blob.bytes;
+    if (!Number.isSafeInteger(snapshotBytes) || receipt.meta.bytes > metaLimit
+        || snapshotBytes > (options.maxBytes ?? Number.MAX_SAFE_INTEGER)) {
+        fail("provider_unsupported", "The committed index exceeds this buffered read's byte limit");
+    }
+    let cacheIdentity;
+    if (scope.kind === "team") {
+        // The head is always fetched with current credentials. This separate live
+        // membership row supplies the authoritative account id for disk isolation;
+        // neither that row nor its permission is stored in the ciphertext cache.
+        try {
+            const answer = await teamCall(dataDir, `/v1/cloud/team/spaces/${encodeURIComponent(scope.spaceKey)}/membership`, token, { signal: options.signal });
+            const member = rowsOf(answer, ["membership", "member", "item", "data"])[0];
+            if (!member || !Number.isSafeInteger(member.account_id) || member.account_id <= 0) {
+                fail("team_membership_revoked", "The current Team member could not be verified");
             }
-            const deny = (message) => {
-                response.writeHead(400, { "content-type": "text/html; charset=utf-8" });
-                response.end("<p>Sealkeep could not finish connecting. Return to the terminal.</p>");
-                reject(new VaultlineError("unauthorized", message));
-            };
-            if (url.searchParams.get("error"))
-                return deny(`Google reported: ${url.searchParams.get("error")}`);
-            if (url.searchParams.get("state") !== state)
-                return deny("The browser reply did not match this connection attempt (state mismatch)");
-            const received = url.searchParams.get("code");
-            if (!received)
-                return deny("The browser reply carried no authorization code");
-            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-            response.end("<p>Sealkeep is connected to Google Drive. You can close this tab.</p>");
-            resolve(received);
-        });
-    });
-    code.catch(() => { });
-    const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
-    consent.searchParams.set("client_id", config.client_id);
-    consent.searchParams.set("redirect_uri", config.redirect_uri);
-    consent.searchParams.set("response_type", "code");
-    consent.searchParams.set("scope", config.scope);
-    consent.searchParams.set("access_type", "offline");
-    consent.searchParams.set("prompt", "consent");
-    consent.searchParams.set("state", state);
+            if (account.refs.vaultId && Number.isSafeInteger(receipt.membershipVersion) && Number(receipt.membershipVersion) > 0) {
+                cacheIdentity = { origin, accountId: member.account_id, vaultId: account.refs.vaultId, spaceKey: scope.spaceKey, receipt };
+            }
+        }
+        catch (error) {
+            // Older compatible planes may authorize the immutable head without this
+            // account-id endpoint. They retain the existing uncached transport; a
+            // denied membership or any other failure must never read the cache.
+            if (!v2EndpointUnsupported(error))
+                throw error;
+        }
+    }
+    const cached = cacheIdentity ? await readTeamIndexCache(dataDir, cacheIdentity) : null;
+    const meta = cached?.meta ?? await readHeadObject(dataDir, "meta", receipt.meta, current.head.downloads.meta, options, true);
+    const ciphertext = cached?.ciphertext ?? await readHeadObject(dataDir, "blob", receipt.blob, current.head.downloads.blob, options, true);
+    let envelope;
     try {
-        options.onConsentUrl?.(consent.toString());
-        const { launchBrowser } = await import("./providers/gdrive.js");
-        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
-        const authorizationCode = await code;
-        const tokens = await gdriveExchange(dataDir, { code: authorizationCode, redirectUri: config.redirect_uri }, options.preferred);
-        return { kind: "gdrive", refreshToken: tokens.refresh_token, clientId: config.client_id, exchange: "cloud" };
+        envelope = JSON.parse(meta.toString("utf8"));
     }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-        server.close();
+    catch {
+        return fail("ciphertext_integrity_failed", "The committed index metadata is not a valid sealed envelope");
     }
+    const assertAccount = async () => {
+        options.signal?.throwIfAborted();
+        const after = await cachedCloudTokenRead(dataDir, preferred);
+        if (origin !== cloudUrl() || after.generation !== authGeneration || after.token !== token
+            || !sameCloudCredentialRefs(after.refs, account.refs)) {
+            fail("unauthorized", "The Sealkeep Cloud account changed during index download. The snapshot was not installed.");
+        }
+    };
+    await assertAccount();
+    if (cacheIdentity && !cached)
+        await writeTeamIndexCache(dataDir, cacheIdentity, meta, ciphertext);
+    await assertAccount();
+    const snapshot = { receipt: current.head.receipt, head: current.head, envelope, ciphertext: ciphertext };
+    if (cacheIdentity)
+        teamSnapshotCacheIdentities.set(snapshot, structuredClone(cacheIdentity));
+    return { status: "ok", snapshot };
 }
-export async function pushIndexObject(dataDir, kind, body, preferred) {
-    const token = await cloudToken(dataDir, preferred);
-    const lease = await call(`/v1/cloud/index/upload`, { method: "POST", body: JSON.stringify({ kind, bytes: body.length }), token });
-    const target = lease.upload_url ?? fail("internal", "The control plane vended no upload URL for the index slot");
-    const response = await fetch(target.url, { method: target.method || "PUT", headers: target.headers ?? {}, body: new Uint8Array(body) });
-    if (!response.ok)
-        fail("internal", `The index ${kind} upload was refused: ${response.status} ${response.statusText}`);
+export function pullIndexGenerationV2(dataDir, preferred, options = {}) {
+    return pullIndexV2Snapshot(dataDir, { kind: "account" }, preferred, options);
 }
-export async function pullIndexObject(dataDir, kind, preferred) {
-    const token = await cloudToken(dataDir, preferred);
-    const lease = await call(`/v1/cloud/index/download?kind=${kind}`, { token }).catch((error) => {
-        if (isVaultlineError(error) && /not.*found|no index/i.test(error.message))
-            return null;
-        throw error;
-    });
-    if (!lease?.download?.url)
-        return null;
-    const response = await fetch(lease.download.url);
-    if (response.status === 404)
-        return null;
-    if (!response.ok)
-        fail("internal", `The index ${kind} download was refused: ${response.status} ${response.statusText}`);
-    return Buffer.from(await response.arrayBuffer());
+export function pullTeamIndexGenerationV2(dataDir, spaceKey, preferred, options = {}) {
+    return pullIndexV2Snapshot(dataDir, { kind: "team", spaceKey }, preferred, options);
 }
-export async function listCloudArchives(dataDir, preferred) {
-    const token = await cloudToken(dataDir, preferred);
-    const rows = await call("/v1/cloud/archives", { token });
-    return Array.isArray(rows) ? rows : [];
+export async function listCloudArchives(dataDir, preferred, options = {}) {
+    const token = options.token ?? await cloudToken(dataDir, preferred, { renew: options.renewToken !== false });
+    // The flat listing returns only the newest 200 rows — on a real vault that
+    // silently hid five sixths of the account from every "is there a copy?"
+    // check. The paged companion walks id-cursor pages until a short one; a
+    // plane without it falls back to the flat call, so an older control plane
+    // keeps the behaviour it always had. A mid-walk failure is different: once
+    // one page succeeded, a capped flat fallback would be a false complete list.
+    const PAGE = 200;
+    const rows = [];
+    try {
+        let before = null;
+        for (let pages = 0; pages < 500; pages++) {
+            const batch = await call(`/v1/cloud/archives/page${before !== null ? `?before=${before}` : ""}`, { token, signal: options.signal });
+            if (!Array.isArray(batch))
+                throw new Error("paged listing answered with a non-array");
+            rows.push(...batch);
+            if (batch.length < PAGE)
+                return rows;
+            const cursor = batch[batch.length - 1]?.id;
+            if (typeof cursor !== "number")
+                throw new Error("paged listing rows carry no id cursor");
+            before = cursor;
+        }
+        return rows;
+    }
+    catch (error) {
+        // A failure before the first page can mean an older plane has no cursor
+        // route, so its capped flat listing is the only compatible answer. Once a
+        // page has succeeded, however, the route demonstrably exists: falling
+        // back after page two fails would return only the newest 200 rows and
+        // falsely present that truncation as the complete account catalog.
+        if (options.signal?.aborted || rows.length > 0)
+            throw error;
+    }
+    const flat = await call("/v1/cloud/archives", { token, signal: options.signal });
+    if (!Array.isArray(flat))
+        return [];
+    // A short capped response is necessarily the whole catalog; exactly PAGE
+    // rows is ambiguous on a legacy plane and must not be cached as complete.
+    Object.defineProperty(flat, "complete", { value: flat.length < PAGE, enumerable: false });
+    return flat;
 }
 /**
- * Really deletes one stored object from managed storage.
- *
- * Goes through the control plane rather than storage directly, because it is
- * the same call the account panel's Archives section makes — one delete path,
- * so the product and the panel cannot come to mean different things by
- * "deleted". The control plane removes the object and its row, and billing
- * follows the row.
+ * Cheap first-run question: does this signed-in account already preserve any
+ * archive? It deliberately fetches only the first cursor page instead of using
+ * `listCloudArchives`, because setup needs a branch, not a thousand-row index.
+ * Older control planes fall back to their capped flat listing.
  */
-export async function deleteCloudArchive(dataDir, vaultRef, preferred) {
-    await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}`, { method: "DELETE", token: await cloudToken(dataDir, preferred) });
+export async function hasCloudArchives(dataDir, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    try {
+        const rows = await call("/v1/cloud/archives/page", { token });
+        if (Array.isArray(rows))
+            return rows.length > 0;
+    }
+    catch { /* older plane: use its original listing */ }
+    const rows = await call("/v1/cloud/archives", { token });
+    return Array.isArray(rows) && rows.length > 0;
+}
+export async function managedDeleteContext(dataDir, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    // cloudToken can legitimately renew and advance the generation. Sample the
+    // generation after obtaining it, then bind the device identity to that exact
+    // token instead of asking the keychain for a token a second time.
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const generationBeforeMachine = await stableCloudAuthGeneration(dataDir);
+    if (Object.hasOwn(options, "expectedAuthGeneration") && options.expectedAuthGeneration !== generationBeforeMachine) {
+        fail("unauthorized", "The Sealkeep Cloud account changed before the delete began. Nothing was deleted; retry for the current account.");
+    }
+    let machine = await machineCredential(dataDir, preferred);
+    if (!machine) {
+        machine = await registerMachine(dataDir, token, preferred, { signal: options.signal });
+    }
+    // Lazy registration, including one won by a sibling lane, legitimately
+    // publishes a new generation. Rebind only after proving both credentials
+    // came from one stable scope and the exact account token is unchanged. A
+    // sibling can finish registration between these two reads, so discard that
+    // pair and retry once just like the individual cache snapshots do.
+    for (let attempt = 0; attempt < CLOUD_AUTH_SNAPSHOT_ATTEMPTS; attempt += 1) {
+        options.signal?.throwIfAborted();
+        const accountAfterMachine = await cachedCloudTokenRead(dataDir, preferred);
+        if (accountAfterMachine.token !== token) {
+            fail("unauthorized", "The Sealkeep Cloud account changed while the delete was being prepared. Nothing was deleted; retry for the current account.");
+        }
+        const machineAfter = await cachedMachineCredentialRead(dataDir, preferred);
+        if (machineAfter.generation !== accountAfterMachine.generation)
+            continue;
+        if (await stableCloudAuthGeneration(dataDir) !== accountAfterMachine.generation)
+            continue;
+        return {
+            authGeneration: accountAfterMachine.generation,
+            token,
+            machine: machineAfter.read.credential,
+        };
+    }
+    return fail("unauthorized", "The Sealkeep Cloud account changed while the delete was being prepared. Nothing was deleted; retry for the current account.");
+}
+export async function deleteCloudArchive(dataDir, vaultRef, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    // Proving which machine is asking lets the plane refuse a machine that did
+    // not seal this archive. Every member of a chunk-family delete receives the
+    // same context, so a mid-operation login change cannot redirect later
+    // DELETEs into a different account with a coincidentally identical ref.
+    const context = options.context ?? await managedDeleteContext(dataDir, preferred);
+    if (await stableCloudAuthGeneration(dataDir) !== context.authGeneration) {
+        fail("unauthorized", "The Sealkeep Cloud account changed during the delete. Remaining objects were left recorded for a safe retry.");
+    }
+    await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}`, {
+        method: "DELETE",
+        token: context.token,
+        body: JSON.stringify(context.machine ?? {}),
+        signal: options.signal,
+    });
 }
 /**
  * Fetches the ciphertext, whichever way the control plane delegated.
@@ -569,7 +3084,7 @@ export async function deleteCloudArchive(dataDir, vaultRef, preferred) {
  * vended credential is signed here. Providers that Spala cannot presign for —
  * anything S3-compatible — arrive as the vended shape.
  */
-async function fetchLeasedObject(lease) {
+async function fetchLeasedObjectStream(lease, options = {}) {
     if (lease.vended) {
         assertVendedSignable(lease.vended);
         assertVendedFresh(lease.vended, {});
@@ -578,41 +3093,98 @@ async function fetchLeasedObject(lease) {
         if (!lease.object_key)
             fail("internal", "Sealkeep Cloud vended a credential but no object key");
         const client = new S3UploadClient(v.provider, { provider: v.provider, region: v.region, bucket: v.bucket, host: v.host, port: v.port, protocol: v.protocol }, { accessKeyId: v.akid, secretAccessKey: v.secret_access_key, sessionToken: v.session_token });
-        return client.download({
+        return client.downloadStream({
             archiveId: lease.vault_ref, provider: v.provider, objectKey: lease.object_key, expiresAt: new Date(Date.now() + 9e5).toISOString(),
             method: "MULTIPART", uploadUrl: "", requiredHeaders: {}, status: "active", uploadable: true
-        });
+        }, { signal: options.signal });
     }
     if (!lease.download?.url)
         fail("internal", "Sealkeep Cloud returned a lease with nowhere to download from");
-    const response = await fetch(lease.download.url, { method: lease.download.method ?? "GET", headers: lease.download.headers });
+    const response = await fetch(lease.download.url, { method: lease.download.method ?? "GET", headers: lease.download.headers, signal: options.signal });
     if (!response.ok)
         fail("internal", `Storage refused the download: ${response.status} ${response.statusText}`);
-    return Buffer.from(await response.arrayBuffer());
+    return responseBodyChunks(response);
+}
+/** Compatibility for APIs that explicitly return a Buffer (chunk reads/open). */
+async function fetchLeasedObject(lease, options = {}) {
+    return collectChunks(await fetchLeasedObjectStream(lease, options), Number.MAX_SAFE_INTEGER);
 }
 /**
  * A byte range of a stored object, for chunk-granular reads. The whole-object
  * hash cannot be checked on a slice — that is the point of a slice — so the
  * caller's integrity comes from the per-chunk hashes and AEAD tags inside
- * (see vaultline-crypto/chunk-access). Only the presigned-URL lease shape
- * supports ranges today; a vended-credential lease falls back to whole-object.
+ * (see sealkeep-crypto/chunk-access). Only the presigned-URL lease shape
+ * supports ranges today. A range request never falls back to a whole object:
+ * neither an unsupported lease nor a storage server's 200 can spend an
+ * unbounded amount of memory/bandwidth on a small search or metadata read.
  */
-export async function pullCiphertextRange(dataDir, vaultRef, storedOffset, storedLength, preferred) {
-    const token = await cloudToken(dataDir, preferred);
-    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
-    if (!lease.download?.url) {
-        const whole = await fetchLeasedObject(lease);
-        return whole.subarray(storedOffset, storedOffset + storedLength);
+export async function pullCiphertextRange(dataDir, vaultRef, storedOffset, storedLength, preferred, options = {}) {
+    const maxBytes = options.maxBytes ?? 8 * 1024 * 1024;
+    if (!Number.isSafeInteger(storedOffset) || storedOffset < 0
+        || !Number.isSafeInteger(storedLength) || storedLength <= 0
+        || !Number.isSafeInteger(storedOffset + storedLength)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > LEGACY_BUFFER_LIMIT_BYTES
+        || storedLength > maxBytes) {
+        fail("invalid_argument", "The archive range must fit its bounded byte limit");
+    }
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token, signal: options.signal });
+    const result = await checkedLeasedRange(dataDir, lease, vaultRef, storedOffset, storedLength, options);
+    return result.body;
+}
+/** The same genuine-storage proof is used by range consumers and presence
+ * probes. Descriptor metadata alone is never evidence that an object exists. */
+async function checkedLeasedRange(dataDir, lease, vaultRef, storedOffset, storedLength, options) {
+    if (!lease || typeof lease !== "object")
+        fail("ciphertext_integrity_failed", "The archive range has no valid object descriptor");
+    const total = lease.bytes;
+    if (lease.vault_ref !== vaultRef || !Number.isSafeInteger(total) || total <= 0
+        || storedOffset + storedLength > total || typeof lease.ciphertext_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/i.test(lease.ciphertext_sha256)) {
+        fail("ciphertext_integrity_failed", "The archive range has no valid object descriptor");
+    }
+    if (typeof lease.download?.url !== "string" || !lease.download.url || lease.download.url.trim() !== lease.download.url
+        || (lease.download.method !== undefined && (typeof lease.download.method !== "string" || lease.download.method.toUpperCase() !== "GET"))) {
+        fail("provider_unsupported", "This archive has no bounded range download transport");
+    }
+    try {
+        const destination = new URL(lease.download.url);
+        if (!["http:", "https:"].includes(destination.protocol) || destination.username || destination.password || destination.hash) {
+            fail("provider_unsupported", "This archive has no bounded range download transport");
+        }
+    }
+    catch {
+        fail("provider_unsupported", "This archive has no bounded range download transport");
+    }
+    const end = storedOffset + storedLength - 1;
+    let headers;
+    try {
+        headers = new Headers(lease.download.headers);
+    }
+    catch {
+        return fail("provider_unsupported", "The archive range has invalid signed transport headers");
+    }
+    headers.set("range", `bytes=${storedOffset}-${end}`);
+    await options.onDescriptor?.(Object.freeze({ vaultRef, bytes: total, ciphertextSha256: lease.ciphertext_sha256.toLowerCase() }));
+    options.signal?.throwIfAborted();
+    const response = await fetch(lease.download.url, {
+        method: "GET", headers, redirect: "error", signal: options.signal,
+    });
+    if (response.status === 404 && options.missingIsAbsent) {
+        await response.body?.cancel().catch(() => undefined);
+        return { body: null, total: 0 };
     }
-    const response = await fetch(lease.download.url, { headers: { range: `bytes=${storedOffset}-${storedOffset + storedLength - 1}` } });
-    if (response.status === 206)
-        return Buffer.from(await response.arrayBuffer());
-    if (response.ok) {
-        // A store that ignores Range answers 200 with everything; take the slice
-        // rather than failing a read that can still be served.
-        return Buffer.from(await response.arrayBuffer()).subarray(storedOffset, storedOffset + storedLength);
+    const contentLength = response.headers.get("content-length");
+    if (response.status !== 206 || response.headers.get("content-range") !== `bytes ${storedOffset}-${end}/${total}`
+        || (contentLength !== null && contentLength !== String(storedLength))
+        || (response.headers.get("content-encoding") && response.headers.get("content-encoding") !== "identity")) {
+        await response.body?.cancel().catch(() => undefined);
+        fail("ciphertext_integrity_failed", "Storage did not return the exact requested archive byte range");
     }
-    return fail("internal", `Storage refused the ranged read: ${response.status} ${response.statusText}`);
+    const body = await collectChunks(backgroundObjectReadStream(dataDir, responseBodyChunks(response), options), storedLength);
+    if (body.length !== storedLength)
+        fail("ciphertext_integrity_failed", "The archive byte range was truncated");
+    return { body, total };
 }
 /**
  * Existence and stored size of a managed object, proven against STORAGE, not
@@ -622,39 +3194,86 @@ export async function pullCiphertextRange(dataDir, vaultRef, storedOffset, store
  * count. This is what lets chunk-folder verification and resume treat managed
  * storage with exactly the discipline `verifyStored` demands of it.
  */
-export async function statCiphertext(dataDir, vaultRef, preferred) {
-    const token = await cloudToken(dataDir, preferred);
+export async function statCiphertext(dataDir, vaultRef, preferred, options = {}) {
+    const origin = cloudUrl();
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const account = await cachedCloudTokenRead(dataDir, preferred);
+    if (account.token !== token)
+        fail("unauthorized", "The account changed before the archive storage check");
+    const assertCurrent = async () => {
+        options.signal?.throwIfAborted();
+        const current = await cachedCloudTokenRead(dataDir, preferred);
+        if (origin !== cloudUrl() || current.token !== token || current.generation !== account.generation
+            || !sameCloudCredentialRefs(current.refs, account.refs)) {
+            fail("unauthorized", "The account changed during the archive storage check or incomplete upload retry");
+        }
+    };
     let lease;
     try {
-        lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
+        lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token, signal: options.signal });
     }
     catch (error) {
-        if (isVaultlineError(error) && (error.code === "archive_not_found" || /returned 404|not[ _-]?found/i.test(error.message))) {
+        await assertCurrent();
+        if (options.allowIncomplete === true && isSealkeepError(error) && error.code === "upload_incomplete") {
+            const incompleteUpload = Object.freeze({ status: "upload_incomplete" });
+            incompleteUploads.set(incompleteUpload, { dataDir: resolve(dataDir), vaultRef, token, assertCurrent });
+            return { exists: false, bytes: 0, incompleteUpload };
+        }
+        if (isSealkeepError(error) && (error.code === "archive_not_found" || error.details?.httpStatus === 404)) {
             return { exists: false, bytes: 0 };
         }
         throw error;
     }
-    if (!lease.download?.url)
-        return { exists: true, bytes: lease.bytes };
-    const response = await fetch(lease.download.url, { headers: { range: "bytes=0-0" } });
-    if (response.status === 404)
+    const checked = await checkedLeasedRange(dataDir, lease, vaultRef, 0, 1, { signal: options.signal, missingIsAbsent: true });
+    await assertCurrent();
+    if (!checked.body)
         return { exists: false, bytes: 0 };
-    if (response.status === 206) {
-        const total = Number((response.headers.get("content-range") ?? "").split("/").pop());
-        await response.arrayBuffer().catch(() => undefined);
-        return { exists: true, bytes: Number.isFinite(total) && total > 0 ? total : lease.bytes };
+    checked.body.fill(0);
+    return { exists: true, bytes: checked.total };
+}
+export async function pullCiphertextStream(dataDir, vaultRef, preferred, options = {}) {
+    options.signal?.throwIfAborted();
+    if (options.maxBytes !== undefined && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
+        fail("invalid_argument", "The archive read limit must be a non-negative safe integer");
     }
-    if (response.ok)
-        return { exists: true, bytes: Buffer.from(await response.arrayBuffer()).length };
-    return fail("internal", `Storage refused the presence check: ${response.status} ${response.statusText}`);
+    const token = await cloudToken(dataDir, preferred, { signal: options.signal });
+    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token, signal: options.signal });
+    if (lease.vault_ref !== vaultRef || !Number.isSafeInteger(lease.bytes) || lease.bytes <= 0
+        || !/^[a-f0-9]{64}$/i.test(lease.ciphertext_sha256 ?? "")) {
+        fail("ciphertext_integrity_failed", "Archive download has no valid object integrity descriptor");
+    }
+    if (options.maxBytes !== undefined && lease.bytes > options.maxBytes) {
+        fail("provider_unsupported", "The archive exceeds this bounded read's byte limit");
+    }
+    const source = await fetchLeasedObjectStream(lease, { signal: options.signal });
+    const checked = (async function* () {
+        const hash = createHash("sha256");
+        let bytes = 0;
+        for await (const value of source) {
+            options.signal?.throwIfAborted();
+            const chunk = value;
+            bytes += chunk.length;
+            // Throwing closes the underlying iterator (and cancels fetch's body),
+            // without yielding the chunk which crossed the declared/budgeted size.
+            if (bytes > lease.bytes || (options.maxBytes !== undefined && bytes > options.maxBytes)) {
+                fail("ciphertext_integrity_failed", "Downloaded ciphertext exceeds its recorded size or bounded read limit");
+            }
+            hash.update(chunk);
+            yield chunk;
+        }
+        const digest = hash.digest("hex");
+        if (digest !== lease.ciphertext_sha256) {
+            fail("internal", "Downloaded ciphertext does not match the hash recorded at upload; refusing it");
+        }
+        if (bytes !== lease.bytes) {
+            fail("internal", `Downloaded ciphertext is ${bytes} bytes; the upload record says ${lease.bytes}`);
+        }
+    })();
+    const background = backgroundObjectReadStream(dataDir, checked, options);
+    return options.unframe ? unframeChunks(background, OBJECT_MAGIC) : background;
 }
-export async function pullCiphertext(dataDir, vaultRef, preferred) {
-    const token = await cloudToken(dataDir, preferred);
-    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
-    const ciphertext = await fetchLeasedObject(lease);
-    const digest = createHash("sha256").update(ciphertext).digest("hex");
-    if (digest !== lease.ciphertext_sha256)
-        fail("internal", "Downloaded ciphertext does not match the hash recorded at upload; refusing it");
+export async function pullCiphertext(dataDir, vaultRef, preferred, options = {}) {
+    const ciphertext = await collectChunks(await pullCiphertextStream(dataDir, vaultRef, preferred, options), Number.MAX_SAFE_INTEGER);
     return { ciphertext, bytes: ciphertext.length };
 }
 /**
@@ -673,11 +3292,17 @@ export async function pullCiphertext(dataDir, vaultRef, preferred) {
  * keeps them restorable from the machine that made them.
  */
 const OBJECT_MAGIC = Buffer.from("VLA1", "ascii");
-export function frameObject(envelope, ciphertext) {
+export function frameObjectHeader(envelope) {
     const meta = Buffer.from(JSON.stringify(envelope), "utf8");
+    if (meta.length > MAX_FRAME_METADATA_BYTES) {
+        fail("invalid_argument", `Archive envelope metadata is ${meta.length} bytes; the safe limit is ${MAX_FRAME_METADATA_BYTES}`);
+    }
     const length = Buffer.allocUnsafe(4);
     length.writeUInt32BE(meta.length, 0);
-    return Buffer.concat([OBJECT_MAGIC, length, meta, ciphertext]);
+    return Buffer.concat([OBJECT_MAGIC, length, meta]);
+}
+export function frameObject(envelope, ciphertext) {
+    return Buffer.concat([frameObjectHeader(envelope), ciphertext]);
 }
 export function unframeObject(blob) {
     if (blob.length < OBJECT_MAGIC.length + 4 || !blob.subarray(0, OBJECT_MAGIC.length).equals(OBJECT_MAGIC))
@@ -702,9 +3327,86 @@ export function unframeObject(blob) {
  * hash recorded at seal time is checked inside decryptArchive, after the AEAD
  * has authenticated every chunk.
  */
-export async function openFromCloud(dataDir, vaultRef, destination, rawPhrase, preferred) {
-    const { ciphertext: blob } = await pullCiphertext(dataDir, vaultRef, preferred);
-    const { envelope, ciphertext } = unframeObject(blob);
+/**
+ * One archive's bytes out of managed storage, in whichever layout it was
+ * stored — because the caller of `open` is precisely the machine that has no
+ * local record to consult.
+ *
+ * A buffered archive is one object at its own reference. A STREAMED archive is
+ * not: it is a folder of chunks plus a sealed sidecar, addressed
+ * `<id>.chunk-NNNNNN` and `<id>.envelope.skmeta`, with nothing at `<id>` at
+ * all. `open` used to fetch the reference and only the reference, so every
+ * streamed archive answered 404 — and streaming is what large sessions and
+ * nearly-full disks fall back to, so the archives most worth reading back were
+ * the ones that could not be. On a company account that is the whole
+ * shared-memory story failing: a colleague's biggest session is the one you
+ * cannot open.
+ *
+ * The single object is tried first, so an ordinary archive still costs one
+ * round trip and the old path is untouched.
+ */
+async function pullArchiveBody(dataDir, vaultRef, preferred) {
+    const single = await statCiphertext(dataDir, vaultRef, preferred);
+    if (single.exists) {
+        const { ciphertext: blob } = await pullCiphertext(dataDir, vaultRef, preferred);
+        const { envelope, ciphertext } = unframeObject(blob);
+        return { envelope, ciphertext, blob, chunked: false };
+    }
+    const { managedRefForKey } = await import("./managed-chunks.js");
+    const { ENVELOPE_OBJECT, chunkObjectName } = await import("./chunk-store.js");
+    const sidecarRef = managedRefForKey(`${vaultRef}/${ENVELOPE_OBJECT}`);
+    if (!(await statCiphertext(dataDir, sidecarRef, preferred)).exists) {
+        fail("archive_not_found", `Managed storage holds nothing under ${vaultRef}. Check the reference with \`sealkeep cloud archives\`.`);
+    }
+    const { ciphertext: sidecarBlob } = await pullCiphertext(dataDir, sidecarRef, preferred);
+    const { envelope } = unframeObject(sidecarBlob);
+    if (!envelope)
+        fail("archive_not_found", `The sidecar for ${vaultRef} carries no envelope, so its chunks cannot be reassembled.`);
+    // The envelope names every chunk and its hash, so the folder is walked from
+    // the record rather than from a listing: no ordering to trust, no extra
+    // object to be fooled by, and a truncated folder is caught here rather than
+    // as a decryption failure nobody can act on.
+    const headers = Array.isArray(envelope.chunks) ? envelope.chunks : [];
+    if (headers.length === 0)
+        fail("archive_not_found", `The envelope for ${vaultRef} lists no chunks.`);
+    const parts = [];
+    for (let index = 0; index < headers.length; index += 1) {
+        const ref = managedRefForKey(`${vaultRef}/${chunkObjectName(index)}`);
+        const { ciphertext: body } = await pullCiphertext(dataDir, ref, preferred);
+        const expected = headers[index]?.sha256;
+        if (expected && sha256(body) !== expected) {
+            fail("ciphertext_integrity_failed", `Chunk ${index} of ${vaultRef} does not match the hash its envelope recorded`, { vaultRef });
+        }
+        parts.push(body);
+    }
+    return { envelope, ciphertext: Buffer.concat(parts), blob: sidecarBlob, chunked: true };
+}
+/** Every managed reference `vaultRef` occupies, so a caller can pull the raw parts. */
+export async function managedArchiveParts(dataDir, vaultRef, preferred) {
+    if ((await statCiphertext(dataDir, vaultRef, preferred)).exists)
+        return { chunked: false, refs: [vaultRef] };
+    const { managedRefForKey } = await import("./managed-chunks.js");
+    const { ENVELOPE_OBJECT, chunkObjectName } = await import("./chunk-store.js");
+    const sidecarRef = managedRefForKey(`${vaultRef}/${ENVELOPE_OBJECT}`);
+    if (!(await statCiphertext(dataDir, sidecarRef, preferred)).exists) {
+        fail("archive_not_found", `Managed storage holds nothing under ${vaultRef}. Check the reference with \`sealkeep cloud archives\`.`);
+    }
+    const { ciphertext: sidecarBlob } = await pullCiphertext(dataDir, sidecarRef, preferred);
+    const { envelope } = unframeObject(sidecarBlob);
+    const headers = Array.isArray(envelope?.chunks) ? envelope.chunks : [];
+    return {
+        chunked: true,
+        refs: [...headers.map((_, index) => managedRefForKey(`${vaultRef}/${chunkObjectName(index)}`)), sidecarRef]
+    };
+}
+/**
+ * `unlock` is a phrase, or a recipient's private key — the second is how an
+ * organisation reads what a colleague sealed without anybody sharing a vault
+ * phrase, which is the only workable shape for a team.
+ */
+export async function openFromCloud(dataDir, vaultRef, destination, unlock, preferred) {
+    const withKey = typeof unlock === "object";
+    const { envelope, ciphertext, blob } = await pullArchiveBody(dataDir, vaultRef, preferred);
     if (!envelope) {
         // Two very different objects arrive with no envelope: a plain-mode
         // archive (readable by its owner's explicit choice at setup — bare gzip,
@@ -720,16 +3422,108 @@ export async function openFromCloud(dataDir, vaultRef, destination, rawPhrase, p
         }
         fail("archive_not_found", `${vaultRef} was stored before archives carried their own envelope. Restore it with \`sealkeep recover ${vaultRef} <destination>\` on the machine that archived it, then push it again.`);
     }
+    // The keygen prints raw 32 bytes as base64; the crypto wants a key object,
+    // whose string form is PEM. Accept either, so a member can paste what they
+    // were handed rather than convert it first.
+    const opener = withKey
+        ? { privateKey: /BEGIN [A-Z ]*PRIVATE KEY/.test(unlock.privateKey)
+                ? unlock.privateKey
+                : x25519PrivateKeyFromRaw(Buffer.from(unlock.privateKey, "base64")) }
+        : { phrase: canonicalPhrase(unlock) };
     let plaintext;
     try {
-        plaintext = openEnvelope(envelope, ciphertext, { phrase: canonicalPhrase(rawPhrase) });
+        plaintext = openEnvelope(envelope, ciphertext, opener);
     }
     catch (error) {
-        fail("recovery_phrase_mismatch", `Unable to open ${vaultRef}: ${error instanceof Error ? error.message : "decryption failed"}`);
+        const detail = error instanceof Error ? error.message : "decryption failed";
+        // Naming the recovery phrase when no phrase was offered sent people to
+        // their recovery kit for a problem the kit cannot fix. The two ways in
+        // fail for different reasons and deserve different sentences.
+        if (withKey) {
+            fail("recipient_key_mismatch", `Unable to open ${vaultRef} with that key: ${detail}. This archive is not wrapped for it — check the archive was rewrapped for your key (\`sealkeep rewrap\`), or open it with the recovery phrase.`);
+        }
+        fail("recovery_phrase_mismatch", `Unable to open ${vaultRef}: ${detail}`);
     }
     await writeFile(destination, plaintext, { mode: 0o600 });
     return { output: destination, bytes: plaintext.length };
 }
+/**
+ * Tells the account's security feed what the local scanner found.
+ *
+ * The scan itself happens on this machine, on the plaintext, because this is
+ * the only place the plaintext exists — the plane holds ciphertext and could
+ * not scan it if it wanted to. What travels is the rule that matched, how
+ * often, this machine, and the archive: never the matched text, never the
+ * surrounding line, never the project name. A leak report that repeated the
+ * leak would be a second leak, and one sent to a server that was designed
+ * never to see the first would be worse than that.
+ *
+ * Best-effort by construction. An account that is not on a team plan answers
+ * 402 and we say nothing; a network failure loses a report, not a seal. The
+ * one thing this must never do is prevent an archive from being sealed.
+ */
+export async function reportSecurityFindings(dataDir, input, preferred) {
+    if (input.findings.length === 0)
+        return { reported: 0 };
+    // One row per rule, not per match: a session that pasted the same key forty
+    // times is one problem, and forty rows would bury the other thirty-nine
+    // findings under it.
+    const byKind = new Map();
+    for (const finding of input.findings) {
+        const seen = byKind.get(finding.kind);
+        if (seen) {
+            seen.occurrences += 1;
+            if (finding.severity === "high")
+                seen.severity = "high";
+        }
+        else
+            byKind.set(finding.kind, { kind: finding.kind, severity: finding.severity, occurrences: 1 });
+    }
+    const token = await cloudToken(dataDir, preferred).catch(() => null);
+    if (!token)
+        return { reported: 0 };
+    const machine = await machineCredential(dataDir, preferred).catch(() => null);
+    let reported = 0;
+    for (const row of byKind.values()) {
+        try {
+            await call("/v1/cloud/security/findings", {
+                method: "POST",
+                token,
+                body: JSON.stringify({
+                    vault_ref: input.vaultRef,
+                    device_id: machine?.device_id,
+                    kind: row.kind,
+                    severity: row.severity,
+                    occurrences: row.occurrences
+                })
+            });
+            reported += 1;
+        }
+        catch (error) {
+            // 402 means this account does not buy org monitoring, which is a
+            // perfectly ordinary answer and not worth a word. Anything else is a
+            // lost report, and a lost report must still not cost anyone a seal.
+            if (isSealkeepError(error) && error.code === "payment_required")
+                return { reported };
+            return { reported };
+        }
+    }
+    return { reported };
+}
+/** What the company's own rules say, for machines to apply before sealing. */
+export async function securityPolicy(dataDir, preferred) {
+    const token = await cloudToken(dataDir, preferred).catch(() => null);
+    if (!token)
+        return null;
+    try {
+        const body = await call("/v1/cloud/security/policy", { token });
+        const rules = body.rules_json ? JSON.parse(body.rules_json) : [];
+        return { blockOnHigh: body.block_on_high === true, rules: Array.isArray(rules) ? rules : [] };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The judgement, kept separate from the fetching so it can be tested honestly.
  *
@@ -800,53 +3594,178 @@ export async function verifyArchives(dataDir, options = {}, preferred) {
 /** Writes the verified marker for an archive this machine holds locally. */
 async function recordVerified(dataDir, vaultRef, bytes) {
     const record = (await listArchives(dataDir)).find((item) => item.id === vaultRef);
-    if (!record || record.version !== 2 || record.remote?.verifiedAt)
+    if (!record || record.version !== 2)
         return;
     const stored = {
         provider: "vaultline", bucket: "vaultline-managed", objectKey: vaultRef,
         bytes, checksum: record.cipher.ciphertextSha256, verifiedAt: new Date().toISOString()
     };
-    await writeRecord((await readConfig(dataDir)).storage.root, { ...record, remote: stored });
+    await mutateArchiveRecord((await readConfig(dataDir)).storage.root, vaultRef, (current) => current.version === 2 ? appendArchiveCopy(current, stored) : current);
 }
-export async function pushArchive(dataDir, archiveId, preferred, options = {}) {
+/**
+ * Store one already-sealed archive under an explicit managed-storage ref.
+ *
+ * Unlike `pushArchive`, this deliberately does not update a vault record.  It
+ * is the narrow primitive used by the team-history backfill: the original
+ * private record and every one of its copies remain untouched while a second,
+ * membership-wrapped object is uploaded, read back, and hash verified.  The
+ * caller may publish a team grant only after `durable` is true.
+ */
+export async function pushFramedArchive(dataDir, input, preferred, options = {}) {
     await readConfig(dataDir);
-    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
-    if (!record)
-        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
-    const ciphertext = await readFile(record.objectPath);
-    if (sha256(ciphertext) !== record.cipher.ciphertextSha256)
-        fail("ciphertext_integrity_failed", "Ciphertext changed on disk since it was archived", { archiveId });
-    // What we store is the envelope plus the ciphertext, so the archive can be
-    // opened by anyone holding the recovery phrase and nothing else.
-    const object = record.envelope ? frameObject(record.envelope, ciphertext) : ciphertext;
-    const digest = sha256(object);
-    const lease = await requestUpload(dataDir, { vaultRef: record.id, ciphertextSha256: digest, bytes: object.length }, preferred);
-    await putCiphertext(lease, object, options.signal);
-    try {
-        await completeUpload(dataDir, lease.lease_id, object.length, preferred);
-        // Retention reads remote.verifiedAt to decide whether a source may be
-        // reclaimed, so this is the field that authorises deleting a customer's
-        // only local copy. It is written only once storage has been made to prove
-        // it holds these exact bytes — the same discipline the bring-your-own-bucket
-        // path follows.
-        const problem = await verifyStored(dataDir, lease, object, digest, preferred);
-        if (problem) {
+    const resumed = options.incompleteUpload && incompleteUploadBinding(options.incompleteUpload, dataDir, input.vaultRef);
+    if (resumed)
+        await resumed.assertCurrent();
+    const handle = await open(input.ciphertextPath, "r").catch(() => fail("archive_not_found", `Archive ciphertext is not readable: ${input.ciphertextPath}`, {
+        archiveId: input.vaultRef,
+        path: input.ciphertextPath,
+    }));
+    try {
+        // Hash the immutable descriptor and the ciphertext through the same open
+        // file descriptor.  A pathname replacement between measure and upload can
+        // therefore never substitute another archive.
+        const header = frameObjectHeader(input.envelope);
+        const ciphertextHash = createHash("sha256");
+        const objectHash = createHash("sha256").update(header);
+        let ciphertextBytes = 0;
+        for await (const chunk of fileHandleChunks(handle, { signal: options.signal })) {
+            ciphertextHash.update(chunk);
+            objectHash.update(chunk);
+            ciphertextBytes += chunk.length;
+            options.onProgress?.(ciphertextBytes);
+            await options.onYield?.();
+        }
+        if (ciphertextHash.digest("hex") !== input.ciphertextSha256 || ciphertextBytes !== input.ciphertextBytes) {
+            fail("ciphertext_integrity_failed", "Ciphertext changed on disk since it was archived", { archiveId: input.vaultRef });
+        }
+        const objectBytes = header.length + ciphertextBytes;
+        const digest = objectHash.digest("hex");
+        const lease = await requestUpload(dataDir, {
+            vaultRef: input.vaultRef,
+            ciphertextSha256: digest,
+            bytes: objectBytes,
+        }, preferred, { signal: options.signal, incompleteUpload: options.incompleteUpload });
+        if (resumed) {
+            // Issuing the lease must not have changed the pending row, and another
+            // writer may have completed it while we were obtaining the signed URL.
+            const current = await pendingUploadDescriptor(resumed, {
+                vaultRef: input.vaultRef, ciphertextSha256: digest, bytes: objectBytes,
+            }, options.signal);
+            if (current.objectKey !== lease.object_key)
+                fail("ciphertext_integrity_failed", "The pending archive object key changed before retry");
+            await resumed.assertCurrent();
+        }
+        let uploaded;
+        let uploadCompleted = false;
+        try {
+            const sentHash = createHash("sha256");
+            let sentBytes = 0;
+            const measuredBody = backgroundObjectReadStream(dataDir, tapDigest(concatStreams([oneChunk(header), fileHandleChunks(handle, { signal: options.signal })]), sentHash, (bytes) => {
+                sentBytes += bytes;
+                options.onProgress?.(ciphertextBytes + sentBytes);
+            }), { signal: options.signal, onYield: options.onYield });
+            const body = options.maxBytesPerSecond
+                ? paceBackgroundByteStream(dataDir, measuredBody, options.maxBytesPerSecond, {
+                    signal: options.signal,
+                    now: options.paceNow,
+                    sleep: options.paceSleep,
+                })
+                : measuredBody;
+            uploaded = await putCiphertextStream(lease, body, objectBytes, options.signal);
+            uploadCompleted = true;
+            if (sentBytes !== objectBytes || sentHash.digest("hex") !== digest) {
+                fail("ciphertext_integrity_failed", "Ciphertext changed while it was being uploaded; the remote object was not marked durable", {
+                    archiveId: input.vaultRef,
+                });
+            }
+        }
+        catch (error) {
+            // A create-only object may already have landed before a crash.  Complete
+            // the new lease and prove the existing bytes rather than writing again.
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/\b412\b|PreconditionFailed/.test(message))
+                throw error;
+        }
+        try {
+            if (resumed) {
+                const machine = await machineCredential(dataDir, preferred);
+                await resumed.assertCurrent();
+                const completion = await call(`/v1/cloud/uploads/${lease.lease_id}/complete`, {
+                    method: "POST", token: resumed.token, signal: options.signal,
+                    body: JSON.stringify({ bytes: objectBytes, ...(machine ?? {}) }), maxResponseBytes: 64 * 1024,
+                });
+                await resumed.assertCurrent();
+                if (completion?.vault_ref !== input.vaultRef || completion.object_key !== lease.object_key
+                    || typeof completion.durable_at !== "string" || !Number.isFinite(Date.parse(completion.durable_at))) {
+                    fail("ciphertext_integrity_failed", "The completion receipt does not bind this exact resumed archive");
+                }
+            }
+            else {
+                await completeUpload(dataDir, lease.lease_id, objectBytes, preferred, { signal: options.signal });
+            }
+            const problem = await verifyStored(dataDir, lease, {
+                bytes: objectBytes,
+                digest,
+                ...(uploadCompleted ? { remoteChecksum: uploaded?.remoteChecksum } : {}),
+            }, preferred, {
+                signal: options.signal, incompleteUpload: options.incompleteUpload,
+                maxBytesPerSecond: options.maxBytesPerSecond, paceNow: options.paceNow, paceSleep: options.paceSleep,
+                onYield: options.onYield,
+                onProgress: options.onProgress ? (bytes) => options.onProgress(ciphertextBytes + objectBytes + bytes) : undefined,
+            });
+            if (problem) {
+                return {
+                    archiveId: input.vaultRef,
+                    objectKey: lease.object_key,
+                    bytes: objectBytes,
+                    durable: false,
+                    checksum: digest,
+                    note: `Uploaded, but managed storage could not be proven to hold it: ${problem}. The private copy is untouched.`,
+                };
+            }
+            return { archiveId: input.vaultRef, objectKey: lease.object_key, bytes: objectBytes, checksum: digest, durable: true };
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
             return {
-                archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: false,
-                note: `Uploaded, but managed storage could not be proven to hold it: ${problem}. The local copy is untouched.`
+                archiveId: input.vaultRef,
+                objectKey: lease.object_key,
+                bytes: objectBytes,
+                durable: false,
+                checksum: digest,
+                note: `Uploaded, but the control plane did not record it: ${error instanceof Error ? error.message : "unknown error"}`,
             };
         }
-        const stored = {
-            provider: "vaultline", bucket: "vaultline-managed", objectKey: lease.object_key,
-            bytes: object.length, checksum: digest, verifiedAt: new Date().toISOString()
-        };
-        await writeRecord((await readConfig(dataDir)).storage.root, { ...record, remote: stored });
-        return { archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: true };
     }
-    catch (error) {
-        return {
-            archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: false,
-            note: `Uploaded, but the control plane did not record it: ${error instanceof Error ? error.message : "unknown error"}`
-        };
+    finally {
+        await handle.close();
     }
 }
+export async function pushArchive(dataDir, archiveId, preferred, options = {}) {
+    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 (record.version !== 2)
+        fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
+    const ciphertextPath = options.ciphertextPath ?? record.objectPath;
+    const pushed = await pushFramedArchive(dataDir, {
+        vaultRef: record.id,
+        envelope: record.envelope,
+        ciphertextPath,
+        ciphertextSha256: record.cipher.ciphertextSha256,
+        ciphertextBytes: record.cipher.storedBytes,
+    }, preferred, options);
+    if (!pushed.durable)
+        return pushed;
+    // Retention reads verified copies to decide whether a source may be
+    // reclaimed.  The generic primitive above intentionally knows nothing about
+    // records; the ordinary private upload path records durability here.
+    const stored = {
+        provider: "vaultline", bucket: "vaultline-managed", objectKey: pushed.objectKey,
+        bytes: pushed.bytes, checksum: pushed.checksum ?? "", verifiedAt: new Date().toISOString(),
+    };
+    await mutateArchiveRecord((await readConfig(dataDir)).storage.root, record.id, (current) => current.version === 2 ? appendArchiveCopy(current, stored) : current);
+    return pushed;
+}