sealkeep 0.9.0 → 0.11.0

package/dist/src/vault.js

@@ -1,42 +1,413 @@
-import { mkdir, readFile, writeFile, rename, access, rm, stat } from "node:fs/promises";
-import { constants, createReadStream, createWriteStream, existsSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { mkdir, open, readFile, writeFile, rename, access, rm, stat } from "node:fs/promises";
+import { constants, createReadStream, createWriteStream, existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { createGzip, createGunzip, gunzipSync } from "node:zlib";
 import { pipeline } from "node:stream/promises";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { decryptLegacyArchive, equalHex, isLegacyPhraseCheck, phraseCheck, sha256, upgradeLegacyPhraseCheck } from "./crypto.js";
 import { canonicalPhrase, generateRecoveryPhrase } from "./mnemonic.js";
-import { decryptArchive as openEnvelope, hashFilePrefixes, hashFileRange, keyRecipientId, openArchiveToFile, sealArchiveToFile, unwrapArchiveKey, x25519PublicKeyFromRaw, x25519PrivateKeyFromRaw, zeroize } from "../packages/vaultline-crypto/src/index.js";
-import { fail, VaultlineError } from "./errors.js";
+import { decryptArchive as openEnvelope, hashFilePrefixes, hashFileRange, keyRecipientId, openArchiveToFile, sealArchiveToFile, unwrapArchiveKey, x25519PublicKeyFromRaw, x25519PrivateKeyFromRaw, rawPublicKey, zeroize } from "../packages/sealkeep-crypto/src/index.js";
+import { fail, SealkeepError } from "./errors.js";
 import { recordAudit } from "./audit.js";
-import { isV2 } from "./types.js";
+import { isV2, teamCustodyRecordIsValid } from "./types.js";
 import { envVar } from "./env.js";
-/** Bumped when the adapter's preservation behaviour changes, recorded in every envelope. */
+import { hasCompleteVerifiedCopyChain, hasVerifiedCopy } from "./archive-copies.js";
+import { acquireDurableTicketLock } from "./durable-ticket-lock.js";
+// Agent hook stdout/stderr is a protocol boundary. A damaged historical
+// sidecar must remain visible in Doctor/Health, but the low-level warning that
+// `listArchives` emits for an interactive process must not make an otherwise
+// successful SessionStart look noisy or malformed. AsyncLocalStorage keeps the
+// exception scoped to the hook operation even when search imports and awaits
+// several layers below it; unrelated work in the same process still warns.
+const archiveWarningSilence = new AsyncLocalStorage();
+const warnedArchiveDamage = new Map();
+export function withoutArchiveRecordWarnings(operation) {
+    return archiveWarningSilence.run(true, operation);
+}
+async function syncRegularFile(path) {
+    // Write access, not read: Windows refuses FlushFileBuffers on a read-only
+    // handle with EPERM, so every record write failed there. POSIX is happy
+    // either way. A file that cannot be opened for writing (a restored archive
+    // made read-only) still gets its flush attempt through the read handle.
+    const handle = await open(path, "r+").catch(async (error) => {
+        if (error.code === "EACCES" || error.code === "EPERM" || error.code === "EROFS")
+            return open(path, "r");
+        throw error;
+    });
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error(`Archive record temporary path is not a regular file: ${path}`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncRecordDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        // Windows does not support opening a directory for fsync. The temporary
+        // file itself is still synced before rename, which is the strongest
+        // durability primitive Node exposes on that platform.
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
 /**
  * Writes one archive record atomically.
  *
- * Written to a temporary file beside the target and renamed into place, so a
- * crash never leaves a half-written record that would strand an archive. This
- * lived as three byte-identical private copies in upload, migrate and
- * retention; a fourth was about to be added for the managed push path.
+ * The complete temporary file is fsynced before rename, then the archive
+ * directory is fsynced after rename. Atomic visibility alone is not enough for
+ * source reclaim: the purge journal must never become more durable than the
+ * record saying where the recoverable archive lives.
  */
-export async function writeRecord(root, record) {
+export async function writeRecord(root, record, operations = {}) {
     const path = join(root, `${record.id}.json`);
     const temp = `${path}.${randomUUID()}.tmp`;
-    await writeFile(temp, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
-    await rename(temp, path);
+    const syncFile = operations.syncFile ?? syncRegularFile;
+    const renameRecord = operations.rename ?? rename;
+    const syncDirectory = operations.syncDirectory ?? syncRecordDirectory;
+    try {
+        await writeFile(temp, JSON.stringify(record, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+        await syncFile(temp);
+        await renameRecord(temp, path);
+        await syncDirectory(root);
+    }
+    finally {
+        // Before rename this clears an unpublished temporary; after rename it is a
+        // no-op. Never remove the target to disguise an fsync error.
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+const ARCHIVE_RECORD_LOCK_WAIT_MS = 30_000;
+/**
+ * Serialize a read/modify/write of one archive record across the daemon, CLI,
+ * dashboard and hooks. Atomic rename prevents torn JSON, but by itself it
+ * still lets two valid stale documents overwrite one another (for example an
+ * upload adding a remote copy while retention marks the source reclaimed).
+ */
+export async function mutateArchiveRecord(root, archiveId, change, options = {}) {
+    const lockDir = join(root, ".record-locks");
+    const lockKey = createHash("sha256").update(archiveId).digest("hex");
+    const legacyLockPath = join(lockDir, `${lockKey}.lock`);
+    const ticketQueuePath = join(lockDir, `${lockKey}.claims`);
+    await mkdir(lockDir, { recursive: true, mode: 0o700 });
+    // Never compare-then-unlink a stale legacy lock: another process could
+    // publish a new owner in that gap. Old-format leftovers require deliberate
+    // singleton maintenance; current processes use immutable FIFO tickets.
+    if (await stat(legacyLockPath).then(() => true, (error) => {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    })) {
+        return fail("internal", `Archive ${archiveId} has a legacy update lock. Stop Sealkeep services and repair that lock before retrying; no record was changed.`);
+    }
+    const recordLock = await acquireDurableTicketLock(ticketQueuePath, `archive record ${archiveId}`, {
+        timeoutMs: ARCHIVE_RECORD_LOCK_WAIT_MS,
+        pollMs: 25,
+    }).catch((error) => {
+        if (error.code === "DURABLE_LOCK_TIMEOUT") {
+            return fail("internal", `Timed out waiting for another Sealkeep process to finish updating archive ${archiveId}`);
+        }
+        throw error;
+    });
+    try {
+        const path = join(root, `${archiveId}.json`);
+        let current;
+        try {
+            current = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch (error) {
+            // Streamed seals do not have a record until the provider has verified
+            // the bytes. Let their first verified write use this same lock rather
+            // than falling back to a check-then-create race. Never treat malformed
+            // existing JSON as absent: `initial` is only safe for a true ENOENT.
+            if (error.code === "ENOENT" && options.initial)
+                current = options.initial;
+            else
+                return fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+        }
+        if (current.id !== archiveId)
+            fail("invalid_argument", "An initial archive record must use the requested id", { archiveId, currentId: current.id });
+        const next = await change(current);
+        if (next.id !== archiveId)
+            fail("invalid_argument", "An archive record update cannot change its id", { archiveId, nextId: next.id });
+        await writeRecord(root, next);
+        return next;
+    }
+    finally {
+        await recordLock.release();
+    }
 }
 export const ADAPTER_VERSION = "1";
 export const CONFIG_VERSION = 1;
+const MAX_INTEGRATION_CONFIG_BYTES = 4 * 1024 * 1024;
+function ownedByCurrentUid(info) {
+    return typeof process.getuid !== "function" || info.uid === process.getuid();
+}
+function smallTextFile(path) {
+    try {
+        // These files are treated as durable statements made by this user's own
+        // setup. Following another user's file (including through a symlink) would
+        // turn a readable system/shared config into authority to choose our vault.
+        if (!ownedByCurrentUid(lstatSync(path)))
+            return null;
+        const info = statSync(path);
+        if (!ownedByCurrentUid(info) || !info.isFile() || info.size > MAX_INTEGRATION_CONFIG_BYTES)
+            return null;
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function normalizedAbsoluteDataDir(value, home) {
+    const expanded = value === "~" ? home : value.startsWith("~/") || value.startsWith("~\\") ? join(home, value.slice(2)) : value;
+    if (!expanded || expanded.includes("\0") || !isAbsolute(expanded))
+        return null;
+    return resolve(expanded);
+}
+function jsonString(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "string" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function codexMcpDataDirs(text) {
+    const values = [];
+    const headers = [...text.matchAll(/^\s*\[([^\]\r\n]+)\]\s*$/gm)];
+    for (let index = 0; index < headers.length; index += 1) {
+        const match = headers[index];
+        if (!/^mcp_servers\.(?:sealkeep|vaultline)\.env$/i.test(match[1]))
+            continue;
+        const start = match.index + match[0].length;
+        const end = headers[index + 1]?.index ?? text.length;
+        const body = text.slice(start, end);
+        const assignment = body.match(/^\s*SEALKEEP_DATA_DIR\s*=\s*("(?:\\.|[^"\\])*"|'[^']*')\s*(?:#.*)?$/mi)
+            ?? body.match(/^\s*VAULTLINE_DATA_DIR\s*=\s*("(?:\\.|[^"\\])*"|'[^']*')\s*(?:#.*)?$/mi);
+        if (!assignment)
+            continue;
+        const literal = assignment[1];
+        const value = literal.startsWith('"') ? jsonString(literal) : literal.slice(1, -1);
+        if (value)
+            values.push(value);
+    }
+    return values;
+}
+function shellDataDirs(command) {
+    // Sealkeep writes a single-quoted argument. Double-quoted and unquoted forms
+    // are accepted for older owned units, but only beside Sealkeep's own command
+    // and `--data-dir` marker.
+    if (!/(?:^|[\s/])(?:sealkeep|vaultline)(?:[\s'"/]|$)/i.test(command))
+        return [];
+    const values = [];
+    const argument = /(?:^|\s)["']?--data-dir["']?(?:=|\s+)(?:'((?:[^']|'"'"')*)'|"((?:\\.|[^"\\])*)"|([^\s<]+))/gi;
+    for (const match of command.matchAll(argument)) {
+        if (match[1] !== undefined)
+            values.push(match[1].replaceAll(`'"'"'`, "'"));
+        else if (match[2] !== undefined)
+            values.push(jsonString(`"${match[2]}"`) ?? match[2]);
+        else if (match[3] !== undefined)
+            values.push(match[3]);
+    }
+    return values;
+}
+function parsedJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function jsonMcpDataDirs(text) {
+    const document = parsedJson(text);
+    if (document === null)
+        return [];
+    const found = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        const record = value;
+        const servers = record.mcpServers;
+        if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+            for (const name of ["sealkeep", "vaultline"]) {
+                const server = servers[name];
+                if (!server || typeof server !== "object" || Array.isArray(server))
+                    continue;
+                const env = server.env;
+                const dataDir = env && typeof env === "object" && !Array.isArray(env)
+                    ? env.SEALKEEP_DATA_DIR ?? env.VAULTLINE_DATA_DIR
+                    : undefined;
+                if (typeof dataDir === "string")
+                    found.push(dataDir);
+            }
+        }
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(document);
+    return found;
+}
+function jsonHookDataDirs(text) {
+    const document = parsedJson(text);
+    if (!document || typeof document !== "object" || Array.isArray(document))
+        return [];
+    const hooks = document.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    const found = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        const record = value;
+        if (typeof record.command === "string")
+            found.push(...shellDataDirs(record.command));
+        for (const [name, child] of Object.entries(record))
+            if (name !== "command")
+                visit(child);
+    };
+    visit(hooks);
+    return found;
+}
+function recognizableVaultConfig(text) {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document))
+        return false;
+    const config = document;
+    const recovery = config.recovery;
+    const storage = config.storage;
+    return Number.isSafeInteger(config.version) && Number(config.version) > 0
+        && typeof config.vaultId === "string" && config.vaultId.trim().length > 0
+        && !!recovery && typeof recovery === "object" && !Array.isArray(recovery)
+        && typeof recovery.phraseCheck === "string"
+        && recovery.phraseCheck.length > 0
+        && !!storage && typeof storage === "object" && !Array.isArray(storage)
+        && typeof storage.provider === "string"
+        && typeof storage.root === "string";
+}
+function xmlText(value) {
+    return value.replaceAll("&quot;", '"').replaceAll("&apos;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+}
+function serviceDataDirs(text) {
+    const decoded = xmlText(text);
+    const values = shellDataDirs(decoded);
+    const plist = /<string>--data-dir<\/string>\s*<string>([^<]+)<\/string>/gi;
+    for (const match of decoded.matchAll(plist))
+        if (match[1])
+            values.push(match[1]);
+    return values;
+}
+function ownedDataDirReferences(home, xdgConfigHome) {
+    // XDG_CONFIG_HOME is authoritative only for a normal process-wide lookup.
+    // An explicit `home` supplied by a caller/test must remain a complete
+    // boundary and never inherit a service unit from an unrelated real account.
+    const systemdConfigHome = xdgConfigHome && isAbsolute(xdgConfigHome) ? resolve(xdgConfigHome) : join(home, ".config");
+    const files = [
+        { path: join(home, ".codex", "config.toml"), source: "Codex MCP", extract: codexMcpDataDirs },
+        { path: join(home, ".codex", "hooks.json"), source: "Codex hooks", extract: jsonHookDataDirs },
+        { path: join(home, ".claude", "settings.json"), source: "Claude hooks", extract: jsonHookDataDirs },
+        { path: join(home, ".claude.json"), source: "Claude MCP", extract: jsonMcpDataDirs },
+        { path: join(home, "Library", "LaunchAgents", "ai.sealkeep.agent.plist"), source: "Sealkeep background service", extract: serviceDataDirs },
+        { path: join(home, "Library", "LaunchAgents", "ai.vaultline.agent.plist"), source: "legacy background service", extract: serviceDataDirs },
+        { path: join(systemdConfigHome, "systemd", "user", "sealkeep.service"), source: "Sealkeep background service", extract: serviceDataDirs },
+        { path: join(systemdConfigHome, "systemd", "user", "vaultline.service"), source: "legacy background service", extract: serviceDataDirs },
+    ];
+    const references = [];
+    for (const file of files) {
+        const text = smallTextFile(file.path);
+        if (text === null)
+            continue;
+        for (const value of file.extract(text)) {
+            const dataDir = normalizedAbsoluteDataDir(value, home);
+            if (dataDir)
+                references.push({ dataDir, source: file.source });
+        }
+    }
+    return references;
+}
+function initializedVaultIdentity(path) {
+    const config = smallTextFile(join(path, "config.json"));
+    if (config === null || !recognizableVaultConfig(config))
+        return null;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function existingOwnedDirectory(path) {
+    try {
+        const info = statSync(path);
+        return ownedByCurrentUid(lstatSync(path)) && ownedByCurrentUid(info) && info.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * ~/.sealkeep for new vaults; an existing ~/.Sealkeep keeps working forever —
- * the rebrand must never strand a vault that predates it.
+ * ~/.sealkeep for new vaults; an existing ~/.vaultline keeps working forever.
+ * A unique initialized vault named by owned integrations is the same vault a
+ * bare CLI/UI/MCP process must use. Multiple initialized candidates are never
+ * guessed between: explicit `--data-dir` is then required.
  */
-export const defaultDataDir = () => {
-    const home = process.env.HOME ?? ".";
-    const legacy = join(home, ".vaultline");
-    const current = join(home, ".sealkeep");
-    if (!existsSync(current) && existsSync(legacy))
+export const defaultDataDir = (home, environment = process.env) => {
+    const resolvedHome = resolve(home ?? environment.HOME ?? environment.USERPROFILE ?? ".");
+    const legacy = resolve(join(resolvedHome, ".vaultline"));
+    const current = resolve(join(resolvedHome, ".sealkeep"));
+    const byPath = new Map();
+    const add = (dataDir, source) => {
+        const identity = initializedVaultIdentity(dataDir);
+        if (identity === null)
+            return;
+        const candidate = byPath.get(identity) ?? { dataDir, sources: new Set() };
+        candidate.sources.add(source);
+        byPath.set(identity, candidate);
+    };
+    add(current, "~/.sealkeep");
+    add(legacy, "~/.vaultline");
+    for (const reference of ownedDataDirReferences(resolvedHome, home === undefined ? environment.XDG_CONFIG_HOME : undefined))
+        add(reference.dataDir, reference.source);
+    if (byPath.size === 1)
+        return byPath.values().next().value.dataDir;
+    if (byPath.size > 1) {
+        const candidates = [...byPath.values()].map(({ dataDir, sources }) => ({ dataDir, sources: [...sources].sort() }));
+        fail("invalid_argument", `Sealkeep found more than one initialized vault on this machine and will not guess which is current: ${candidates.map((candidate) => candidate.dataDir).join(", ")}. Re-run with --data-dir <path>.`, { candidates });
+    }
+    // Preserve the historical empty-directory fallback too: an unfinished old
+    // install should continue in ~/.vaultline, while a genuinely fresh machine
+    // starts in ~/.sealkeep.
+    if (!existsSync(current) && existingOwnedDirectory(legacy))
         return legacy;
     return current;
 };
@@ -49,12 +420,82 @@ async function exists(path) { try {
 catch {
     return false;
 } }
-async function writeJson(path, value) { await mkdir(dirname(path), { recursive: true }); await writeFile(path, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 }); }
 /**
- * Reads and version-gates the vault config. A config written by a newer build is
- * refused rather than silently reinterpreted; migrations attach here when v2 lands.
+ * Config updates that move a team binding and its sharing mode must land as
+ * one file replacement. A crash may leave the old config or the new config,
+ * never a half-written JSON document or a team binding without its mode.
  */
-export async function readConfig(dataDir) {
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+const configMutationQueues = new Map();
+const CONFIG_LOCK_STALE_MS = 10 * 60_000;
+const CONFIG_LOCK_WAIT_MS = 30_000;
+function processIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Serialize config read/modify/write cycles across the daemon, CLI, local API,
+ * and agent-hook processes. Atomic rename prevents torn JSON; this lock also
+ * prevents a perfectly valid but stale whole document from winning later and
+ * resurrecting a revoked team binding.
+ */
+async function withConfigLock(dataDir, work) {
+    const lockDir = join(dataDir, "locks");
+    const lockPath = join(lockDir, "config.lock");
+    await mkdir(lockDir, { recursive: true, mode: 0o700 });
+    const started = Date.now();
+    for (;;) {
+        try {
+            const { open } = await import("node:fs/promises");
+            const handle = await open(lockPath, "wx", 0o600);
+            await handle.writeFile(`${process.pid} ${new Date().toISOString()}\n`);
+            await handle.close();
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const [held, owner] = await Promise.all([
+                stat(lockPath).catch(() => null),
+                readFile(lockPath, "utf8").catch(() => ""),
+            ]);
+            const pid = Number(owner.trim().split(/\s+/, 1)[0]);
+            if (held && Date.now() - held.mtimeMs > CONFIG_LOCK_STALE_MS && !processIsAlive(pid)) {
+                await rm(lockPath, { force: true });
+                continue;
+            }
+            if (Date.now() - started >= CONFIG_LOCK_WAIT_MS) {
+                return fail("internal", "Timed out waiting for another Sealkeep process to finish updating the vault configuration");
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+}
+async function readConfigFile(dataDir) {
     let raw;
     try {
         raw = await readFile(configPath(dataDir), "utf8");
@@ -65,6 +506,38 @@ export async function readConfig(dataDir) {
     const config = JSON.parse(raw);
     if (config.version !== CONFIG_VERSION)
         fail("config_unsupported_version", `Vault config version ${String(config.version)} is not supported by this build (expected ${CONFIG_VERSION})`, { found: config.version, expected: CONFIG_VERSION });
+    return config;
+}
+function withCurrentPhraseCheck(config) {
+    if (!isLegacyPhraseCheck(config.recovery.phraseCheck))
+        return config;
+    return { ...config, recovery: { ...config.recovery, phraseCheck: upgradeLegacyPhraseCheck(config.recovery.phraseCheck) } };
+}
+/** Serialize every config mutation around a cross-process atomic replace. */
+async function mutateConfigAtomically(dataDir, change) {
+    const path = configPath(dataDir);
+    const prior = configMutationQueues.get(path) ?? Promise.resolve();
+    const operation = prior.catch(() => undefined).then(() => withConfigLock(dataDir, async () => {
+        const stored = await readConfigFile(dataDir);
+        const current = withCurrentPhraseCheck(stored);
+        const next = change(current);
+        if (next !== stored)
+            await writeJsonAtomic(path, next);
+        return next;
+    }));
+    const tracked = operation.then(() => undefined, () => undefined).finally(() => {
+        if (configMutationQueues.get(path) === tracked)
+            configMutationQueues.delete(path);
+    });
+    configMutationQueues.set(path, tracked);
+    return operation;
+}
+/**
+ * Reads and version-gates the vault config. A config written by a newer build is
+ * refused rather than silently reinterpreted; migrations attach here when v2 lands.
+ */
+export async function readConfig(dataDir) {
+    const config = await readConfigFile(dataDir);
     // Defect #49: builds before this one stored `recovery.phraseCheck` as a
     // bare, unsalted SHA-256 -- a cheap offline oracle. upgradeLegacyPhraseCheck
     // re-derives the cost-matched value from that stored digest alone, with no
@@ -72,34 +545,121 @@ export async function readConfig(dataDir) {
     // first time anything reads its config -- nobody has to run a migration or
     // even unlock the vault first for this to happen.
     if (isLegacyPhraseCheck(config.recovery.phraseCheck)) {
-        config.recovery = { ...config.recovery, phraseCheck: upgradeLegacyPhraseCheck(config.recovery.phraseCheck) };
+        const upgraded = withCurrentPhraseCheck(config);
         // Best effort: an unwritable dataDir still gets the upgraded value for
         // this call (below), and simply repeats the upgrade on its next read.
-        await writeJson(configPath(dataDir), config).catch(() => { });
+        return withConfigLock(dataDir, async () => {
+            const latest = await readConfigFile(dataDir);
+            const settled = withCurrentPhraseCheck(latest);
+            if (settled !== latest)
+                await writeJsonAtomic(configPath(dataDir), settled);
+            return settled;
+        }).catch(() => upgraded);
     }
     return config;
 }
 export async function vaultStatus(dataDir) {
     const config = await readConfig(dataDir);
     const archives = await listArchives(dataDir);
+    const byId = new Map(archives.map((archive) => [archive.id, archive]));
+    // A delta is a storage link, not another agent session. Its `source.bytes`
+    // describes the whole transcript so the next append can prove its prefix;
+    // summing that value for every link would count the base again at every
+    // snapshot (100 + 120 + 130 instead of 130). Only trust a delta as a link
+    // when its direct base is present and has the promised length. A damaged or
+    // orphaned pointer remains visible as a standalone record rather than making
+    // history silently disappear from Overview.
+    const logicalDelta = (archive) => {
+        const delta = deltaOf(archive);
+        if (!delta || delta.baseBytes >= archive.source.bytes)
+            return null;
+        return byId.get(delta.baseArchiveId)?.source.bytes === delta.baseBytes ? delta : null;
+    };
+    const logicalArchives = archives.filter((archive) => !logicalDelta(archive));
+    // `archiveCount` remains the logical sealed-object count for compatibility:
+    // two whole snapshots of one transcript are still two archive roots. The UI
+    // folds every snapshot/delta carrying the same exact source path into one
+    // session row, so expose that user-facing count separately instead of
+    // labelling archive roots as sessions.
+    const sessionCount = new Set(archives.map((archive) => archive.source.path || archive.id)).size;
+    const archivedBytes = archives.reduce((total, archive) => {
+        const delta = logicalDelta(archive);
+        return total + (delta ? archive.source.bytes - delta.baseBytes : archive.source.bytes);
+    }, 0);
+    // Physical encrypted/compressed bytes are a different fact from the amount
+    // of logical source history represented above. Keeping both prevents every
+    // dashboard consumer from calling (for example) 130 GB of source history
+    // "130 GB sealed" when the actual archive objects occupy about 10 GB.
+    const sealedBytes = archives.reduce((total, archive) => total + ("storedBytes" in archive.cipher ? archive.cipher.storedBytes : archive.source.bytes), 0);
+    // "Off this machine" is a logical-session count too. A delta-backed session
+    // is restorable away from this Mac only when every object in its chain has a
+    // verified copy; counting each verified link would otherwise display e.g.
+    // "3 of 1" for one three-link session.
+    const rootOf = (archive) => {
+        let cursor = archive;
+        const seen = new Set();
+        for (;;) {
+            const delta = logicalDelta(cursor);
+            if (!delta || seen.has(cursor.id))
+                return cursor.id;
+            seen.add(cursor.id);
+            cursor = byId.get(delta.baseArchiveId);
+        }
+    };
+    const groups = new Map();
+    for (const archive of archives) {
+        const root = rootOf(archive);
+        const chain = groups.get(root);
+        if (chain)
+            chain.push(archive);
+        else
+            groups.set(root, [archive]);
+    }
+    const cloudArchiveCount = [...groups.values()].filter((chain) => {
+        if (!chain.every(isV2))
+            return false;
+        return hasCompleteVerifiedCopyChain(chain);
+    }).length;
+    // A chain with individually verified links is still pending until one
+    // destination contains every link. Otherwise split copies (base on Drive,
+    // delta on Cloud) made the Queue read empty while no remote restore existed.
+    // Count every physical link in such a chain conservatively: the uploader may
+    // choose any one eligible common destination, so the status must not claim
+    // less work than the chain can require.
+    const incompleteChains = [...groups.values()].filter((chain) => !chain.every(isV2) || !hasCompleteVerifiedCopyChain(chain));
+    const incompleteIds = new Set(incompleteChains.flatMap((chain) => chain.map((archive) => archive.id)));
+    // V1 cannot be uploaded by the current provider path, but hiding it here
+    // made an old local-only archive look durable. Keep it visible as blocked
+    // pending work; callers can present the required migration separately.
+    const pendingUploads = archives.filter((archive) => !isV2(archive) || incompleteIds.has(archive.id) || !hasVerifiedCopy(archive));
+    const blockedUploadCount = archives.filter((archive) => !isV2(archive)).length;
     // Resolved to "sealed" rather than passed through raw, so no consumer ever
     // has to know that absence and sealed are the same thing.
-    return { vaultId: config.vaultId, provider: config.storage.provider, storageMode: config.storageMode ?? "sealed", remoteStorage: config.remoteStorage, archiveCount: archives.length, archivedBytes: archives.reduce((total, archive) => total + archive.source.bytes, 0) };
+    return {
+        vaultId: config.vaultId,
+        provider: config.storage.provider,
+        storageMode: config.storageMode ?? "sealed",
+        remoteStorage: config.remoteStorage,
+        archiveCount: logicalArchives.length,
+        sessionCount,
+        archivedBytes,
+        sealedBytes,
+        cloudArchiveCount,
+        incompleteChainCount: incompleteChains.filter((chain) => chain.every(isV2)).length,
+        blockedUploadCount,
+        pendingUploadCount: pendingUploads.length,
+        pendingUploadBytes: pendingUploads.reduce((total, archive) => total + ("storedBytes" in archive.cipher ? archive.cipher.storedBytes : archive.source.bytes), 0)
+    };
 }
 export async function configureRemoteStorage(dataDir, remoteStorage) {
     if (!remoteStorage.bucket.trim() || !remoteStorage.prefix.trim())
         fail("invalid_argument", "--bucket and --prefix are required");
-    const config = await readConfig(dataDir);
     const normalized = { ...remoteStorage, bucket: remoteStorage.bucket.trim(), prefix: remoteStorage.prefix.replace(/^\/+|\/+$/g, "") };
     if (!normalized.prefix)
         fail("invalid_argument", "--prefix cannot be empty");
-    const next = { ...config, remoteStorage: normalized };
-    await writeJson(configPath(dataDir), next);
-    return next;
+    return mutateConfigAtomically(dataDir, (config) => ({ ...config, remoteStorage: normalized }));
 }
 export async function initialize(dataDir, providedPhrase, opts = {}) {
-    if (await exists(configPath(dataDir)))
-        fail("vault_already_initialized", `Vault already initialized at ${dataDir}`, { dataDir });
     const phrase = canonicalPhrase(providedPhrase ?? generateRecoveryPhrase());
     // Defect #49: `??` only falls back to a generated phrase on null/undefined,
     // so `setup --recovery-phrase ""` sailed through with an empty phrase and no
@@ -118,7 +678,11 @@ export async function initialize(dataDir, providedPhrase, opts = {}) {
         ...(opts.storageMode === "plain" ? { storageMode: "plain" } : {}),
         recovery: { phraseCheck: phraseCheck(phrase) }
     };
-    await writeJson(configPath(dataDir), config);
+    await withConfigLock(dataDir, async () => {
+        if (await exists(configPath(dataDir)))
+            fail("vault_already_initialized", `Vault already initialized at ${dataDir}`, { dataDir });
+        await writeJsonAtomic(configPath(dataDir), config);
+    });
     await mkdir(config.storage.root, { recursive: true });
     return { config, phrase };
 }
@@ -154,13 +718,13 @@ function assertArchivable(absolute, size) {
  * 3 MB reports the 3 MB archive. Nothing is returned when the file was
  * rewritten, truncated, or has never been archived.
  */
-export async function provenAppendOffset(archives, sourcePath, currentBytes) {
+export async function provenAppendOffset(archives, sourcePath, currentBytes, onActivity, signal, onYield) {
     const candidates = archives
         .filter((record) => record.source.path === sourcePath && record.source.bytes > 0 && record.source.bytes <= currentBytes)
         .sort((a, b) => b.source.bytes - a.source.bytes);
     if (candidates.length === 0)
         return null;
-    const digests = await hashFilePrefixes(sourcePath, candidates.map((record) => record.source.bytes));
+    const digests = await hashFilePrefixes(sourcePath, candidates.map((record) => record.source.bytes), onActivity, signal, onYield);
     for (const record of candidates) {
         const prefix = digests.get(record.source.bytes);
         if (prefix && equalHex(prefix, record.source.sha256))
@@ -168,6 +732,9 @@ export async function provenAppendOffset(archives, sourcePath, currentBytes) {
     }
     return null;
 }
+/** Bound replay work for an agent that appends forever. The next snapshot
+ * after this many physical links is sealed whole and becomes a new base. */
+export const MAX_DELTA_CHAIN_LINKS = 16;
 /**
  * The delta pointer on a record, when the record is a delta archive.
  *
@@ -194,26 +761,39 @@ export function deltaOf(record) {
  * is removed for the same reason sealArchiveToFile removes its destination — a
  * crash must never leave a .partial that could be mistaken for an archive.
  */
-async function writePlainArchive(sourcePath, staged, onProgress) {
+async function writePlainArchive(sourcePath, staged, snapshotBytes, onProgress, signal) {
     const originalHash = createHash("sha256");
     const storedHash = createHash("sha256");
     let originalBytes = 0;
     let storedBytes = 0;
     try {
-        await pipeline(createReadStream(sourcePath), async function* (chunks) {
+        await pipeline(
+        // A transcript may still be receiving turns while the background worker
+        // archives it. Read exactly the size captured before the source lock was
+        // entered, just like the sealed path does. `end` is inclusive; for an
+        // empty snapshot we let the stream open/read at most byte zero and drop
+        // it below, preserving both source-error reporting and a real empty gzip.
+        createReadStream(sourcePath, { start: 0, end: Math.max(0, snapshotBytes - 1), signal }), async function* (chunks) {
+            let remaining = snapshotBytes;
             for await (const piece of chunks) {
-                originalHash.update(piece);
-                originalBytes += piece.length;
+                signal?.throwIfAborted();
+                if (remaining <= 0)
+                    continue;
+                const slice = piece.subarray(0, remaining);
+                originalHash.update(slice);
+                originalBytes += slice.length;
+                remaining -= slice.length;
                 onProgress?.(originalBytes);
-                yield piece;
+                yield slice;
             }
         }, createGzip({ level: 6 }), async function* (chunks) {
             for await (const piece of chunks) {
+                signal?.throwIfAborted();
                 storedHash.update(piece);
                 storedBytes += piece.length;
                 yield piece;
             }
-        }, createWriteStream(staged, { mode: 0o600 }));
+        }, createWriteStream(staged, { mode: 0o600, signal }), { signal });
     }
     catch (error) {
         await rm(staged, { force: true });
@@ -235,70 +815,290 @@ async function writePlainArchive(sourcePath, staged, onProgress) {
  * queue worker turns it on, because re-sealing a growing session whole on
  * every snapshot is exactly how 4 GB of transcript became 40 GB of storage.
  */
+/**
+ * One seal of a given source at a time, across processes.
+ *
+ * Deduplication is a check followed by an act: look for an archive of these
+ * exact bytes, and seal one if there is none. Two callers arriving together
+ * both looked, both found nothing, and both sealed — two archives of one file,
+ * two records, twice the bytes. Not hypothetical: the daemon and a hand-run
+ * `sealkeep archive` reach for the same session constantly, and the queue runs
+ * seals in parallel by design.
+ *
+ * A lock file rather than an in-process mutex, because the racing callers are
+ * usually different processes. A dead owner's lock is reclaimed immediately;
+ * a malformed legacy lock has no PID to prove dead, so it is reclaimed only
+ * after the staleness window. Age alone never overrides a live owner: sealing a
+ * multi-gigabyte transcript can legitimately take longer than either window.
+ */
+const SEAL_LOCK_STALE_MS = 30 * 60_000;
+function cancellationError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error("The seal was cancelled");
+    error.name = "AbortError";
+    return error;
+}
+async function cancellablePause(milliseconds, signal) {
+    if (!signal) {
+        await new Promise((resolvePause) => setTimeout(resolvePause, milliseconds));
+        return;
+    }
+    if (signal.aborted)
+        throw cancellationError(signal);
+    await new Promise((resolvePause, reject) => {
+        const timer = setTimeout(done, milliseconds);
+        const cancel = () => { clearTimeout(timer); cleanup(); reject(cancellationError(signal)); };
+        function cleanup() { signal.removeEventListener("abort", cancel); }
+        function done() { cleanup(); resolvePause(); }
+        signal.addEventListener("abort", cancel, { once: true });
+    });
+}
+async function withSourceLock(dataDir, absolute, work, signal) {
+    const { mkdir: makeDir, rm: remove, stat: statFile, open } = await import("node:fs/promises");
+    const dir = join(dataDir, "locks");
+    await makeDir(dir, { recursive: true, mode: 0o700 });
+    const lock = join(dir, `${createHash("sha256").update(absolute).digest("hex").slice(0, 32)}.lock`);
+    const ownership = `${process.pid} ${randomUUID()} ${new Date().toISOString()}\n`;
+    const abandoned = (held, owner) => {
+        const pid = Number(owner.trim().split(/\s+/, 1)[0]);
+        const hasPid = Number.isSafeInteger(pid) && pid > 0;
+        return (hasPid && !processIsAlive(pid))
+            || (!hasPid && held !== null && Date.now() - Number(held.mtimeMs) > SEAL_LOCK_STALE_MS);
+    };
+    /**
+     * Only one waiter may remove an abandoned source lock at a time. Without this
+     * small recovery guard, two processes can both observe the same dead PID;
+     * the slower one's `rm` can then delete the faster one's newly acquired live
+     * lock and both proceed to seal. The guard is held through the second
+     * read/check/remove, never through the seal itself.
+     */
+    const recoverAbandonedLock = async () => {
+        const recoveryLock = `${lock}.recovery`;
+        const recoveryOwnership = `${process.pid} ${randomUUID()} ${new Date().toISOString()}\n`;
+        for (;;) {
+            signal?.throwIfAborted();
+            try {
+                const handle = await open(recoveryLock, "wx", 0o600);
+                try {
+                    await handle.writeFile(recoveryOwnership);
+                }
+                catch (error) {
+                    await remove(recoveryLock, { force: true }).catch(() => undefined);
+                    throw error;
+                }
+                finally {
+                    await handle.close().catch(() => undefined);
+                }
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const [held, owner] = await Promise.all([
+                    statFile(recoveryLock).catch(() => null),
+                    readFile(recoveryLock, "utf8").catch(() => ""),
+                ]);
+                if (abandoned(held, owner)) {
+                    // A token check prevents a delayed dead-guard observer from deleting
+                    // a successor guard that appeared at the same path meanwhile.
+                    const current = await readFile(recoveryLock, "utf8").catch(() => null);
+                    if (current === owner)
+                        await remove(recoveryLock, { force: true }).catch(() => undefined);
+                    continue;
+                }
+                await cancellablePause(100, signal);
+            }
+        }
+        try {
+            const [held, owner] = await Promise.all([
+                statFile(lock).catch(() => null),
+                readFile(lock, "utf8").catch(() => ""),
+            ]);
+            if (abandoned(held, owner))
+                await remove(lock, { force: true });
+        }
+        finally {
+            const current = await readFile(recoveryLock, "utf8").catch(() => null);
+            if (current === recoveryOwnership)
+                await remove(recoveryLock, { force: true }).catch(() => undefined);
+        }
+    };
+    for (;;) {
+        signal?.throwIfAborted();
+        try {
+            const handle = await open(lock, "wx", 0o600);
+            try {
+                await handle.writeFile(ownership);
+            }
+            catch (error) {
+                await remove(lock, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const [held, owner] = await Promise.all([
+                statFile(lock).catch(() => null),
+                readFile(lock, "utf8").catch(() => ""),
+            ]);
+            if (abandoned(held, owner)) {
+                await recoverAbandonedLock();
+                continue;
+            }
+            await cancellablePause(100, signal);
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        // Never unlink a successor's lock. This matters after stale-lock recovery:
+        // an unusually delayed former owner can still reach its `finally` after a
+        // new process has acquired the same path.
+        const current = await readFile(lock, "utf8").catch(() => null);
+        if (current === ownership)
+            await remove(lock, { force: true }).catch(() => undefined);
+    }
+}
 export async function archiveFile(dataDir, sourcePath, rawPhrase, agent = "custom", hooks = {}) {
+    hooks.signal?.throwIfAborted();
     const phrase = canonicalPhrase(rawPhrase);
     const config = await readConfig(dataDir);
+    const projectScope = teamSpaceOf(config, hooks.project, hooks.projectKey)?.spaceKey;
     if (!equalHex(config.recovery.phraseCheck, phraseCheck(phrase)))
         fail("recovery_phrase_mismatch", "Recovery phrase does not match this vault");
-    // The crypto has always taken a chunk size and nothing above it could set
-    // one, so exercising a multi-chunk archive meant writing tens of megabytes.
-    // A caller — or SEALKEEP_CHUNK_BYTES — can span chunks with kilobytes now.
-    const chunkBytes = hooks.chunkBytes ?? (() => {
-        const override = Number(envVar("CHUNK_BYTES"));
-        return Number.isInteger(override) && override > 0 ? override : undefined;
-    })();
+    // The typed seam lets deterministic tests exercise boundaries without a
+    // hidden environment variable changing production archive layout.
+    const chunkBytes = hooks.chunkBytes;
     const absolute = resolve(sourcePath);
     const source = await stat(absolute).catch(() => null);
     if (!source?.isFile())
         return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
     assertArchivable(absolute, source.size);
-    // Hashing the source to answer "have I already archived exactly this?" is a
-    // whole extra read of a file that may be gigabytes, so it is only worth doing
-    // when some archive of this path already claims the same length. Anything of
-    // a different length has certainly changed.
-    const archives = await listArchives(dataDir);
-    const sameLength = archives.filter((item) => item.source.path === absolute && item.source.bytes === source.size);
-    if (sameLength.length > 0) {
-        const { sha256: digest } = await hashFileRange(absolute);
-        const existing = sameLength.find((item) => equalHex(item.source.sha256, digest));
-        if (existing)
-            return { ...existing, deduplicated: true };
-    }
-    // What this snapshot adds to the newest one that is still a prefix of the
-    // file. Recorded, not acted on: the archive below is a complete, standalone
-    // archive of the whole transcript. See the note on `supersedes` in types.ts.
-    const base = await provenAppendOffset(archives, absolute, source.size);
-    // The delta path: the caller asked for it, the prefix is proven, and there
-    // is genuinely a tail to seal. Plain vaults are excluded — a bare gzip has
-    // no ranged layout, and "portable, readable memory" should stay whole files.
-    // (base.bytes === size never reaches here: the dedupe above already returned
-    // that archive.)
-    if (hooks.delta === true && config.storageMode !== "plain" && base && base.bytes < source.size) {
-        return sealDeltaArchive(dataDir, config, absolute, agent, phrase, source.size, base, hooks);
-    }
-    const id = randomUUID();
-    const objectPath = join(config.storage.root, `${id}.vlarchive`);
-    const staged = `${objectPath}.${randomUUID()}.partial`;
-    if (config.storageMode === "plain") {
-        const plain = await writePlainArchive(absolute, staged, hooks.onProgress).catch((error) => {
+    // Everything from here — the "have I already got this?" question and the seal
+    // that answers it — happens under one lock per source, so two callers cannot
+    // both decide the answer is no.
+    return withSourceLock(dataDir, absolute, async () => {
+        hooks.signal?.throwIfAborted();
+        // Hashing the source to answer "have I already archived exactly this?" is a
+        // whole extra read of a file that may be gigabytes, so it is only worth doing
+        // when some archive of this path already claims the same length. Anything of
+        // a different length has certainly changed.
+        const archives = await listArchives(dataDir);
+        const sameLength = archives.filter((item) => item.source.path === absolute && item.source.bytes === source.size);
+        if (sameLength.length > 0) {
+            // The source may be a live transcript. Hash the size captured above,
+            // which is also the range the seal records; an unbounded read can chase an
+            // appending agent indefinitely and can never equal a same-length archive.
+            const { sha256: digest } = await hashFileRange(absolute, 0, source.size, hooks.onActivity, hooks.signal, hooks.onYield);
+            const existing = sameLength.find((item) => equalHex(item.source.sha256, digest));
+            if (existing)
+                return { ...existing, deduplicated: true };
+        }
+        // What this snapshot adds to the newest one that is still a prefix of the
+        // file. Recorded, not acted on: the archive below is a complete, standalone
+        // archive of the whole transcript. See the note on `supersedes` in types.ts.
+        const base = await provenAppendOffset(archives, absolute, source.size, hooks.onActivity, hooks.signal, hooks.onYield);
+        // The delta path: the caller asked for it, the prefix is proven, and there
+        // is genuinely a tail to seal. Plain vaults are excluded — a bare gzip has
+        // no ranged layout, and "portable, readable memory" should stay whole files.
+        // (base.bytes === size never reaches here: the dedupe above already returned
+        // that archive.)
+        if (hooks.delta === true && config.storageMode !== "plain" && base && base.bytes < source.size) {
+            // `provenAppendOffset` deliberately keeps its public result small, but the
+            // delta writer also needs the hash it just proved. Re-checking that hash
+            // after the tail is sealed closes the window where an in-place rewrite of
+            // the prefix could otherwise publish a chain that can never restore.
+            const baseRecord = archives.find((record) => record.id === base.archiveId);
+            if (!baseRecord)
+                return fail("internal", `The proven base archive disappeared before ${absolute} could be sealed`, { archiveId: base.archiveId, sourcePath: absolute });
+            // Replaying an unbounded append chain on every incremental index pass is
+            // quadratic over a long-running session. Once the chain reaches the fixed
+            // limit, fall through to the ordinary full-snapshot writer. That snapshot
+            // is independently restorable, and later appends start a short new chain.
+            if (resolveDeltaChain(archives, baseRecord).length < MAX_DELTA_CHAIN_LINKS) {
+                return sealDeltaArchive(dataDir, config, absolute, agent, phrase, source.size, { ...base, sha256: baseRecord.source.sha256 }, hooks);
+            }
+        }
+        const id = randomUUID();
+        const objectPath = join(config.storage.root, `${id}.skarchive`);
+        const staged = `${objectPath}.${randomUUID()}.partial`;
+        if (config.storageMode === "plain") {
+            const plain = await writePlainArchive(absolute, staged, source.size, hooks.onProgress, hooks.signal).catch((error) => {
+                const code = error.code;
+                if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
+                    return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+                throw error;
+            });
+            // The record keeps the sealed shape minus the envelope, because everything
+            // downstream — dedupe, verify, offload, push — reads `cipher` as "the
+            // stored object's summary" and never as proof of encryption. In particular
+            // `ciphertextSha256` keeps its name: it has always meant "hash of the
+            // bytes on disk", which here is the gzip, and renaming it would fork every
+            // consumer into two field names for one meaning. No envelope is written
+            // because inventing one would claim key wrapping that never happened.
+            const record = {
+                version: 2, id, createdAt: new Date().toISOString(),
+                // Stored, not re-derived: a project was knowable only by parsing the source
+                // path, which works for an agent's own directories and nowhere else. Extending
+                // a project's membership needs the answer the seal already had.
+                source: { path: absolute, agent, bytes: plain.originalBytes, sha256: plain.originalSha256, ...(hooks.project ? { project: hooks.project } : {}), ...(hooks.projectKey ? { projectKey: hooks.projectKey } : {}), ...(projectScope ? { projectScope } : {}) },
+                cipher: { algorithm: "none", ciphertextSha256: plain.storedSha256, storedBytes: plain.storedBytes, chunks: 0 },
+                objectPath, ...(base ? { supersedes: base } : {})
+            };
+            try {
+                await rename(staged, objectPath);
+            }
+            catch (error) {
+                await rm(staged, { force: true });
+                throw error;
+            }
+            await writeRecord(config.storage.root, record);
+            await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: plain.originalBytes, recipients: 0, supersedes: base?.archiveId ?? null });
+            return { ...record, deduplicated: false };
+        }
+        // Compression happens before the seal because ciphertext is incompressible
+        // by construction. How much it buys was assumed here to be about 2x; measured
+        // on a real 1.6 GB Codex rollout it is 1.5x, because these files carry a lot
+        // of base64 and tool output that has already been compressed once. The
+        // difference describes expected storage, not safe admission: the disk guard
+        // uses the codec's incompressible upper bound before these bytes are seen.
+        const tokenCollector = await inlineIndexWanted(dataDir, hooks, source.size)
+            ? (await import("./search.js")).createSealTokenCollector(source.size)
+            : null;
+        const sealed = await sealArchiveToFile({ path: absolute, end: source.size }, staged, {
+            ...(tokenCollector ? { onPlaintext: tokenCollector.onPlaintext } : {}),
+            // gzip-chunk: compression lives inside each chunk, so sealing is a single
+            // pass with no staged body — the ×2 disk window is gone — and every chunk
+            // can later be fetched and opened alone. Archives sealed under the legacy
+            // whole-body layout stay readable forever; this changes what is WRITTEN.
+            // Members of this project are wrapped in; members of other projects are not.
+            recipients: mergeRecipients(configuredRecipients(config, phrase, { project: hooks.project ?? undefined, projectKey: hooks.projectKey ?? undefined }), hooks.teamRecipients ?? []), archiveId: id, compression: hooks.compression ?? "gzip-chunk",
+            adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
+            ...(chunkBytes ? { chunkBytes } : {}),
+            ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {}),
+            ...(hooks.onYield ? { onYield: hooks.onYield } : {}),
+            ...(hooks.signal ? { signal: hooks.signal } : {}),
+        }).catch((error) => {
             const code = error.code;
             if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
                 return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
             throw error;
         });
-        // The record keeps the sealed shape minus the envelope, because everything
-        // downstream — dedupe, verify, offload, push — reads `cipher` as "the
-        // stored object's summary" and never as proof of encryption. In particular
-        // `ciphertextSha256` keeps its name: it has always meant "hash of the
-        // bytes on disk", which here is the gzip, and renaming it would fork every
-        // consumer into two field names for one meaning. No envelope is written
-        // because inventing one would claim key wrapping that never happened.
         const record = {
-            version: 2, id, createdAt: new Date().toISOString(),
-            source: { path: absolute, agent, bytes: plain.originalBytes, sha256: plain.originalSha256 },
-            cipher: { algorithm: "none", ciphertextSha256: plain.storedSha256, storedBytes: plain.storedBytes, chunks: 0 },
-            objectPath, ...(base ? { supersedes: base } : {})
+            version: 2, id, createdAt: sealed.envelope.manifest.createdAt,
+            source: { path: absolute, agent, bytes: sealed.originalBytes, sha256: sealed.originalSha256, ...(hooks.project ? { project: hooks.project } : {}), ...(hooks.projectKey ? { projectKey: hooks.projectKey } : {}), ...(projectScope ? { projectScope } : {}) },
+            cipher: { algorithm: sealed.envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: sealed.envelope.chunks.length },
+            envelope: sealed.envelope, objectPath, ...(base ? { supersedes: base } : {})
         };
+        // The object only becomes an archive once it is whole: the manifest hashes are
+        // proved by the last chunk, so a crash mid-seal leaves a .partial nobody reads.
         try {
             await rename(staged, objectPath);
         }
@@ -306,50 +1106,57 @@ export async function archiveFile(dataDir, sourcePath, rawPhrase, agent = "custo
             await rm(staged, { force: true });
             throw error;
         }
-        await writeJson(join(config.storage.root, `${id}.json`), record);
-        await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: plain.originalBytes, recipients: 0, supersedes: base?.archiveId ?? null });
+        await writeRecord(config.storage.root, record);
+        await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: sealed.originalBytes, recipients: sealed.envelope.wrappedKeys.length, supersedes: base?.archiveId ?? null });
+        if (tokenCollector)
+            await indexSealInline(dataDir, phrase, record, tokenCollector.finish(sealed.envelope.chunks.length), hooks.signal);
         return { ...record, deduplicated: false };
-    }
-    // Compression happens before the seal because ciphertext is incompressible
-    // by construction. How much it buys was assumed here to be about 2x; measured
-    // on a real 1.6 GB Codex rollout it is 1.5x, because these files carry a lot
-    // of base64 and tool output that has already been compressed once. The
-    // difference matters wherever space is planned rather than merely hoped for —
-    // see spaceNeededFor in src/disk.ts, which uses the measured figure.
-    const sealed = await sealArchiveToFile({ path: absolute, end: source.size }, staged, {
-        // gzip-chunk: compression lives inside each chunk, so sealing is a single
-        // pass with no staged body — the ×2 disk window is gone — and every chunk
-        // can later be fetched and opened alone. Archives sealed under the legacy
-        // whole-body layout stay readable forever; this changes what is WRITTEN.
-        // Members of this project are wrapped in; members of other projects are not.
-        recipients: configuredRecipients(config, phrase, { project: hooks.project ?? undefined }), archiveId: id, compression: "gzip-chunk",
-        adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
-        ...(chunkBytes ? { chunkBytes } : {}),
-        ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
-    }).catch((error) => {
-        const code = error.code;
-        if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
-            return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
-        throw error;
-    });
-    const record = {
-        version: 2, id, createdAt: sealed.envelope.manifest.createdAt,
-        source: { path: absolute, agent, bytes: sealed.originalBytes, sha256: sealed.originalSha256 },
-        cipher: { algorithm: sealed.envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: sealed.envelope.chunks.length },
-        envelope: sealed.envelope, objectPath, ...(base ? { supersedes: base } : {})
-    };
-    // The object only becomes an archive once it is whole: the manifest hashes are
-    // proved by the last chunk, so a crash mid-seal leaves a .partial nobody reads.
+    }, hooks.signal);
+}
+/** Above this a seal is a whale: the catch-up indexes it last, deliberately, and the seal itself must not carry that cost. */
+const INLINE_INDEX_MAX_BYTES = 256 * 1024 * 1024;
+/** A blob index is merged whole, in this process, on every inline seal: fine while it is small, an out-of-memory crash inside the daemon once it is not. */
+const INLINE_INDEX_MAX_BLOB_ARCHIVES = 2000;
+async function inlineIndexWanted(dataDir, hooks, sourceBytes) {
+    if (!hooks.indexInline || (hooks.compression ?? "gzip-chunk") === "zstd" || sourceBytes > INLINE_INDEX_MAX_BYTES)
+        return false;
+    const { segmentsEnabled } = await import("./index-store.js");
+    // Segments append one small sealed file per seal, whatever the vault's size,
+    // under the manifest lock — safe beside a running catch-up.
+    if (await segmentsEnabled(dataDir))
+        return true;
+    // The blob has one writer at a time, and while the catch-up is building it
+    // is that writer: a merge from here would race its checkpoint and one of
+    // the two would be lost (the test "cannot bypass the migration guard").
+    const lane = await readFile(join(dataDir, "daemon-state.json"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    if (lane?.indexing?.state === "building")
+        return false;
+    // Past this the whole-index merge belongs to the catch-up lane (or to a
+    // migration: `sealkeep index migrate` gives a big vault seal-time indexing).
+    const coverage = await readFile(join(dataDir, "index", "coverage.json"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    return (coverage?.indexed?.length ?? 0) <= INLINE_INDEX_MAX_BLOB_ARCHIVES;
+}
+/**
+ * The seal is durable before this runs and stays durable if this fails: an
+ * index entry that cannot be written is named (warning + audit) and the next
+ * catch-up pass indexes the archive from its sealed bytes — the contract the
+ * cloud seal path keeps in chunk-store.ts.
+ */
+async function indexSealInline(dataDir, phrase, record, tokensByChunk, signal) {
     try {
-        await rename(staged, objectPath);
+        const { indexArchiveTokens } = await import("./search.js");
+        await indexArchiveTokens(dataDir, phrase, record, tokensByChunk, { ...(signal ? { signal } : {}) });
     }
     catch (error) {
-        await rm(staged, { force: true });
-        throw error;
+        const code = error?.code;
+        const named = typeof code === "string" ? code : error instanceof Error ? error.message.split("\n")[0] : String(error);
+        process.emitWarning(`index merge deferred for ${record.id.slice(0, 8)}: ${named} — the next index pass indexes it from the sealed bytes`, "SealkeepIndexDeferred");
+        await recordAudit(dataDir, "index.merge", "denied", { archiveId: record.id, reason: named, preserved: false }).catch(() => undefined);
     }
-    await writeJson(join(config.storage.root, `${id}.json`), record);
-    await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: sealed.originalBytes, recipients: sealed.envelope.wrappedKeys.length, supersedes: base?.archiveId ?? null });
-    return { ...record, deduplicated: false };
 }
 /**
  * Seals only what an appended transcript added since its proven base archive.
@@ -370,33 +1177,97 @@ export async function archiveFile(dataDir, sourcePath, rawPhrase, agent = "custo
  * *needs* it — so writing `supersedes` here would offer the base for pruning
  * and turn a storage saving into data loss.
  */
+async function hashDeltaSnapshot(sourcePath, size, prefixBytes, onActivity, signal, onYield) {
+    const whole = createHash("sha256");
+    const prefix = createHash("sha256");
+    const tail = createHash("sha256");
+    let bytes = 0;
+    let nextYield = 16 * 1024 * 1024;
+    // One bounded pass is important here. Three independent reads could each
+    // describe a different instant of a live transcript; hashing all three
+    // views from the same chunks proves that `whole` is exactly base + sealed
+    // tail whenever both component hashes match.
+    for await (const chunk of createReadStream(sourcePath, { start: 0, end: size - 1, signal })) {
+        signal?.throwIfAborted();
+        const piece = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        whole.update(piece);
+        const prefixRemaining = Math.max(0, prefixBytes - bytes);
+        const split = Math.min(prefixRemaining, piece.length);
+        if (split > 0)
+            prefix.update(piece.subarray(0, split));
+        if (split < piece.length)
+            tail.update(piece.subarray(split));
+        bytes += piece.length;
+        onActivity?.(bytes);
+        if (bytes >= nextYield) {
+            nextYield = bytes + 16 * 1024 * 1024;
+            if (onYield)
+                await onYield();
+            else
+                await yieldToEventLoop();
+        }
+    }
+    return {
+        bytes,
+        wholeSha256: whole.digest("hex"),
+        prefixSha256: prefix.digest("hex"),
+        tailSha256: tail.digest("hex")
+    };
+}
 async function sealDeltaArchive(dataDir, config, absolute, agent, phrase, size, base, hooks) {
     const id = randomUUID();
-    const objectPath = join(config.storage.root, `${id}.vlarchive`);
+    const objectPath = join(config.storage.root, `${id}.skarchive`);
     const staged = `${objectPath}.${randomUUID()}.partial`;
+    const projectScope = teamSpaceOf(config, hooks.project, hooks.projectKey)?.spaceKey;
+    // Same inline-indexing gate a full seal uses, sized to what THIS seal
+    // actually covers: the delta's own appended range, not the whole
+    // transcript. That range is exactly what the delta's own chunk numbers
+    // describe, which is what lets a later query ranged-read this object
+    // directly instead of decrypting the whole chain for one quote.
+    const appendedBytes = size - base.bytes;
+    const tokenCollector = await inlineIndexWanted(dataDir, hooks, appendedBytes)
+        ? (await import("./search.js")).createSealTokenCollector(appendedBytes)
+        : null;
     const sealed = await sealArchiveToFile({ path: absolute, start: base.bytes, end: size }, staged, {
-        recipients: configuredRecipients(config, phrase, { project: hooks.project ?? undefined }), archiveId: id, compression: "gzip-chunk",
+        recipients: mergeRecipients(configuredRecipients(config, phrase, { project: hooks.project ?? undefined, projectKey: hooks.projectKey ?? undefined }), hooks.teamRecipients ?? []), archiveId: id, compression: "gzip-chunk",
         adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
-        ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
+        ...(tokenCollector ? { onPlaintext: tokenCollector.onPlaintext } : {}),
+        ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {}),
+        ...(hooks.onYield ? { onYield: hooks.onYield } : {}),
+        ...(hooks.signal ? { signal: hooks.signal } : {}),
     }).catch((error) => {
         const code = error.code;
         if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
             return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
         throw error;
     });
-    // The whole-file identity this record answers for. Hashed after the seal so
-    // a file that grew meanwhile is still described exactly as sealed: the range
-    // ends at `size` either way. A file that *shrank* mid-seal is not an append
-    // at all — refuse rather than record a chain that cannot reproduce anything;
-    // the queued retry re-proves the prefix and archives it whole.
-    const whole = await hashFileRange(absolute, 0, size);
-    if (sealed.originalBytes !== size - base.bytes || whole.bytes !== size) {
+    // Validate the source snapshot after sealing and before publishing. Length
+    // alone is not proof: an agent (or editor) can rewrite already-proved bytes
+    // in place without changing the file size. The prefix must still be the base
+    // archive and the tail must still be the bytes in the staged delta. The
+    // queued retry will re-prove the source and choose a whole archive if either
+    // component changed.
+    let snapshot;
+    try {
+        snapshot = await hashDeltaSnapshot(absolute, size, base.bytes, hooks.onActivity, hooks.signal, hooks.onYield);
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        const code = error.code;
+        if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
+            return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+        throw error;
+    }
+    if (sealed.originalBytes !== size - base.bytes ||
+        snapshot.bytes !== size ||
+        !equalHex(snapshot.prefixSha256, base.sha256) ||
+        !equalHex(snapshot.tailSha256, sealed.originalSha256)) {
         await rm(staged, { force: true });
         fail("source_unreadable", `${absolute} changed while its append was being sealed; it will re-archive whole on the next pass`, { sourcePath: absolute, bytes: size });
     }
     const record = {
         version: 2, id, createdAt: sealed.envelope.manifest.createdAt,
-        source: { path: absolute, agent, bytes: size, sha256: whole.sha256 },
+        source: { path: absolute, agent, bytes: size, sha256: snapshot.wholeSha256, ...(hooks.project ? { project: hooks.project } : {}), ...(hooks.projectKey ? { projectKey: hooks.projectKey } : {}), ...(projectScope ? { projectScope } : {}) },
         cipher: { algorithm: sealed.envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: sealed.envelope.chunks.length },
         envelope: sealed.envelope, objectPath,
         delta: { baseArchiveId: base.archiveId, baseBytes: base.bytes }
@@ -408,8 +1279,12 @@ async function sealDeltaArchive(dataDir, config, absolute, agent, phrase, size,
         await rm(staged, { force: true });
         throw error;
     }
-    await writeJson(join(config.storage.root, `${id}.json`), record);
+    await writeRecord(config.storage.root, record);
     await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: size, appendedBytes: sealed.originalBytes, recipients: sealed.envelope.wrappedKeys.length, supersedes: null, deltaBase: base.archiveId });
+    // The seal is durable either way; indexing it is advisory (see
+    // indexSealInline) and, unlike a full seal, covers only the appended range.
+    if (tokenCollector)
+        await indexSealInline(dataDir, phrase, record, tokenCollector.finish(sealed.envelope.chunks.length), hooks.signal);
     return { ...record, deduplicated: false };
 }
 /**
@@ -431,21 +1306,653 @@ export function configuredRecipients(config, rawPhrase, scope) {
     const asked = typeof scope === "string" ? { group: scope } : (scope ?? {});
     const keys = (config.recipients ?? [])
         .filter((recipient) => (asked.group ? recipient.group === asked.group : true))
-        .filter((recipient) => !recipient.project || recipient.project === asked.project)
+        .filter((recipient) => {
+        if (!recipient.project && !recipient.projectKey)
+            return true;
+        // Once a stable key is known, a display label is never sufficient proof
+        // of scope. This is the fail-closed boundary that keeps org-a/api from
+        // receiving org-b/api's memory.
+        if (asked.projectKey)
+            return recipient.projectKey === asked.projectKey;
+        if (recipient.projectKey)
+            return false;
+        return recipient.project === asked.project;
+    })
         .map((recipient) => ({ kind: "x25519", publicKey: x25519PublicKeyFromRaw(Buffer.from(recipient.publicKey, "base64")) }));
     return [{ kind: "phrase", phrase }, ...keys];
 }
+/** Accepted managed team members that should open future project archives. */
+export async function teamRecipientsForProject(dataDir, project, projectKey) {
+    if (!project && !projectKey)
+        return [];
+    const config = await readConfig(dataDir);
+    const binding = teamSpaceOf(config, project, projectKey);
+    if (!binding)
+        return [];
+    try {
+        const { listTeamMembers } = await import("./cloud.js");
+        return (await listTeamMembers(dataDir, binding.spaceKey)).filter((member) => typeof member.public_key === "string").map((member) => ({ kind: "x25519", publicKey: x25519PublicKeyFromRaw(Buffer.from(member.public_key, "base64")) }));
+    }
+    catch {
+        // A transient control-plane outage must not prevent local preservation; the
+        // normal recovery phrase recipient still seals the archive safely.
+        return [];
+    }
+}
+function mergeRecipients(base, extra) {
+    const identity = (item) => item.kind === "phrase"
+        ? `phrase:${item.phrase.normalize("NFKD")}`
+        : `x25519:${keyRecipientId(Buffer.isBuffer(item.publicKey) ? item.publicKey : rawPublicKey(item.publicKey))}`;
+    const seen = new Set(base.map(identity));
+    return [...base, ...extra.filter((item) => {
+            const key = identity(item);
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        })];
+}
+/**
+ * Every archive this vault knows about.
+ *
+ * One unreadable record used to take the whole list with it: `JSON.parse`
+ * threw inside a `Promise.all`, so a single truncated file — a crash mid-write,
+ * a disk that filled between `open` and `close` — made `status`, `search`,
+ * `retention` and every other command that lists archives fail outright. A
+ * vault of two hundred good records became a vault of none, over one bad byte.
+ *
+ * A record that will not parse is skipped and NAMED, not swallowed: it may be
+ * the only trace of an archive, and quietly dropping it would turn a loud
+ * problem into a missing one. The archives that do parse still answer.
+ */
 export async function listArchives(dataDir) {
     const config = await readConfig(dataDir);
+    const scan = await currentArchiveLedgerScan(config.storage.root);
+    reportUnreadableArchiveRecords(config.storage.root, scan.unreadable);
+    // Each caller owns the collection it receives even when several concurrent
+    // dashboard requests shared the underlying filesystem scan.
+    return scan.records.slice();
+}
+// The dashboard loads several archive-derived endpoints together. A per-call
+// batch bound alone still multiplied 32 opens by every endpoint. Share both an
+// in-flight scan and a completed, generation-validated scan. Archive record
+// writers publish with atomic rename, which changes the root generation. A
+// malformed file is the exception: a person may repair it in place, so its own
+// stat fingerprint is revalidated before the completed scan can be reused.
+const inFlightArchiveLedgerScans = new Map();
+const completedArchiveLedgerScans = new Map();
+const MAX_COMPLETED_ARCHIVE_LEDGER_SCANS = 32;
+async function archiveDirectoryGeneration(storageRoot) {
+    try {
+        const value = await stat(storageRoot, { bigint: true });
+        return [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].join(":");
+    }
+    catch {
+        return null;
+    }
+}
+async function archiveSidecarFingerprint(path) {
+    try {
+        const value = await stat(path, { bigint: true });
+        return [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].join(":");
+    }
+    catch {
+        return null;
+    }
+}
+async function completedArchiveLedgerScanIsCurrent(storageRoot, scan) {
+    if (!scan.cacheable || !scan.directoryGeneration
+        || await archiveDirectoryGeneration(storageRoot) !== scan.directoryGeneration)
+        return false;
+    for (const [file, fingerprint] of scan.damaged) {
+        if (await archiveSidecarFingerprint(join(storageRoot, file)) !== fingerprint)
+            return false;
+    }
+    return true;
+}
+function rememberCompletedArchiveLedgerScan(storageRoot, scan) {
+    completedArchiveLedgerScans.delete(storageRoot);
+    completedArchiveLedgerScans.set(storageRoot, scan);
+    if (completedArchiveLedgerScans.size <= MAX_COMPLETED_ARCHIVE_LEDGER_SCANS)
+        return;
+    const oldest = completedArchiveLedgerScans.keys().next().value;
+    if (oldest !== undefined)
+        completedArchiveLedgerScans.delete(oldest);
+}
+async function currentArchiveLedgerScan(storageRoot) {
+    const key = resolve(storageRoot);
+    const cached = completedArchiveLedgerScans.get(key);
+    if (cached) {
+        if (await completedArchiveLedgerScanIsCurrent(storageRoot, cached)) {
+            // Refresh insertion order so the small process-wide map behaves as an LRU.
+            completedArchiveLedgerScans.delete(key);
+            completedArchiveLedgerScans.set(key, cached);
+            return cached;
+        }
+        if (completedArchiveLedgerScans.get(key) === cached)
+            completedArchiveLedgerScans.delete(key);
+    }
+    // Another caller may have started the replacement scan while this caller
+    // awaited generation/fingerprint validation above.
+    const existing = inFlightArchiveLedgerScans.get(key);
+    if (existing)
+        return existing;
+    let tracked;
+    tracked = scanArchiveLedger(storageRoot).then((scan) => {
+        if (scan.cacheable)
+            rememberCompletedArchiveLedgerScan(key, scan);
+        else
+            completedArchiveLedgerScans.delete(key);
+        return scan;
+    }).finally(() => {
+        if (inFlightArchiveLedgerScans.get(key) === tracked)
+            inFlightArchiveLedgerScans.delete(key);
+    });
+    inFlightArchiveLedgerScans.set(key, tracked);
+    return tracked;
+}
+function objectValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function requiredString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function nonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function archiveSourceIsValid(value) {
+    const source = objectValue(value);
+    return source !== null
+        && requiredString(source.path)
+        && requiredString(source.agent)
+        && nonNegativeNumber(source.bytes)
+        && typeof source.sha256 === "string";
+}
+function legacyCipherIsValid(value) {
+    const cipher = objectValue(value);
+    return cipher !== null
+        && cipher.algorithm === "aes-256-gcm"
+        && requiredString(cipher.nonce)
+        && requiredString(cipher.authTag)
+        && typeof cipher.ciphertextSha256 === "string"
+        && cipher.compression === "none";
+}
+function legacyWrappedKeyIsValid(value) {
+    const wrapped = objectValue(value);
+    return wrapped !== null
+        && wrapped.algorithm === "scrypt-aes-256-gcm"
+        && requiredString(wrapped.salt)
+        && requiredString(wrapped.nonce)
+        && requiredString(wrapped.authTag)
+        && requiredString(wrapped.ciphertext);
+}
+function currentCipherIsValid(value) {
+    const cipher = objectValue(value);
+    return cipher !== null
+        && (cipher.algorithm === "none" || cipher.algorithm === "aes-256-gcm" || cipher.algorithm === "chacha20-poly1305")
+        && typeof cipher.ciphertextSha256 === "string"
+        && nonNegativeNumber(cipher.storedBytes)
+        && nonNegativeNumber(cipher.chunks)
+        && Number.isInteger(cipher.chunks);
+}
+function currentEnvelopeIsValid(value, archiveId, suite) {
+    const envelope = objectValue(value);
+    const manifest = objectValue(envelope?.manifest);
+    return envelope !== null
+        && envelope.version === 2
+        && envelope.archiveId === archiveId
+        && envelope.suite === suite
+        && nonNegativeNumber(envelope.chunkBytes)
+        && Array.isArray(envelope.chunks)
+        && manifest !== null
+        && typeof manifest.plaintextSha256 === "string"
+        && nonNegativeNumber(manifest.plaintextBytes)
+        && requiredString(manifest.createdAt)
+        && Array.isArray(envelope.wrappedKeys);
+}
+function archiveRecordIsValid(value) {
+    const record = objectValue(value);
+    if (record === null
+        || !requiredString(record.id)
+        || !requiredString(record.createdAt)
+        || !archiveSourceIsValid(record.source)
+        || !requiredString(record.objectPath))
+        return false;
+    if (record.version === 1) {
+        return record.teamCustody === undefined && legacyCipherIsValid(record.cipher) && legacyWrappedKeyIsValid(record.wrappedKey);
+    }
+    if (record.version !== 2 || !currentCipherIsValid(record.cipher))
+        return false;
+    let sealedIdentity = record.id;
+    if (record.teamCustody !== undefined) {
+        if (!teamCustodyRecordIsValid(record))
+            return false;
+        sealedIdentity = record.teamCustody.envelopeArchiveId;
+    }
+    // Plain archives deliberately have no encryption envelope. Every encrypted
+    // V2 archive must carry the envelope facts needed to interpret its cipher.
+    return record.cipher.algorithm === "none"
+        ? record.envelope === undefined
+        : currentEnvelopeIsValid(record.envelope, sealedIdentity, record.cipher.algorithm);
+}
+function parseArchiveSidecar(raw) {
+    try {
+        const record = JSON.parse(raw);
+        return archiveRecordIsValid(record) ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readArchiveSidecar(storageRoot, file) {
+    const path = join(storageRoot, file);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return { kind: "transient", file };
+    }
+    const record = parseArchiveSidecar(raw);
+    if (record)
+        return { kind: "record", file, record };
+    // A malformed sidecar is safe to remember only after proving the exact file
+    // stayed unchanged across a second read. This closes the race where an
+    // in-place repair lands between the failed parse and the fingerprint stat.
+    const before = await archiveSidecarFingerprint(path);
+    if (!before)
+        return { kind: "transient", file };
+    let confirmedRaw;
+    try {
+        confirmedRaw = await readFile(path, "utf8");
+    }
+    catch {
+        return { kind: "transient", file };
+    }
+    const after = await archiveSidecarFingerprint(path);
+    if (!after || before !== after)
+        return { kind: "transient", file };
+    const repaired = parseArchiveSidecar(confirmedRaw);
+    return repaired
+        ? { kind: "record", file, record: repaired }
+        : { kind: "damaged", file, fingerprint: after };
+}
+async function scanArchiveLedger(storageRoot) {
     const { readdir } = await import("node:fs/promises");
-    const files = await readdir(config.storage.root);
-    const records = await Promise.all(files.filter((file) => file.endsWith(".json")).map(async (file) => JSON.parse(await readFile(join(config.storage.root, file), "utf8"))));
-    return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const before = await archiveDirectoryGeneration(storageRoot);
+    const files = (await readdir(storageRoot)).filter((file) => file.endsWith(".json"));
+    const records = [];
+    const unreadable = [];
+    const damaged = new Map();
+    let transientFailure = before === null;
+    // A real long-lived vault has thousands of sidecars, and the dashboard asks
+    // several archive-derived questions at once. Opening every file in one
+    // Promise.all submitted thousands of filesystem requests per caller, then
+    // ran all of their JSON.parse continuations in one dense microtask wave. The
+    // bytes were small, but the shared local API event loop stopped answering
+    // lightweight health/UI requests while that wave drained. Bound both the fd
+    // fan-out and the synchronous parse burst, and explicitly return to the event
+    // loop between batches. The completed cache above is guarded by the root's
+    // durable generation, so a later request cannot miss a record another
+    // Sealkeep process atomically replaced.
+    const batchSize = 32;
+    for (let offset = 0; offset < files.length; offset += batchSize) {
+        const batch = await Promise.all(files.slice(offset, offset + batchSize)
+            .map((file) => readArchiveSidecar(storageRoot, file)));
+        for (const result of batch) {
+            if (result.kind === "record")
+                records.push(result.record);
+            else {
+                unreadable.push(result.file);
+                if (result.kind === "damaged")
+                    damaged.set(result.file, result.fingerprint);
+                else
+                    transientFailure = true;
+            }
+        }
+        if (offset + batchSize < files.length)
+            await yieldToEventLoop();
+    }
+    const after = await archiveDirectoryGeneration(storageRoot);
+    const stable = before !== null && before === after;
+    return {
+        records: records.sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
+        unreadable,
+        directoryGeneration: stable ? after : null,
+        damaged,
+        cacheable: stable && !transientFailure,
+    };
+}
+function reportUnreadableArchiveRecords(storageRoot, unreadable) {
+    if (!archiveWarningSilence.getStore()) {
+        // Sorting a copy keeps the shared scan immutable for concurrent callers.
+        const named = [...unreadable].sort();
+        if (named.length === 0) {
+            // If an operator repairs the metadata and damage later recurs, that is a
+            // new incident and deserves a new warning.
+            warnedArchiveDamage.delete(storageRoot);
+        }
+        else {
+            const fingerprint = named.join("\0");
+            if (warnedArchiveDamage.get(storageRoot) !== fingerprint) {
+                warnedArchiveDamage.set(storageRoot, fingerprint);
+                process.emitWarning(`${named.length} archive record${named.length === 1 ? "" : "s"} could not be read and were skipped: ${named.slice(0, 5).join(", ")}${named.length > 5 ? " …" : ""}`, "SealkeepDamagedRecord");
+            }
+        }
+    }
 }
 /**
  * Registers an X25519 public key that may open future archives. Only the public
  * key is stored; the matching private key stays on its own device.
  */
+export function projectSharingOf(config, project, projectKey) {
+    const lookup = projectKey || project;
+    if (!lookup)
+        return "passive";
+    return config.projectSharing?.[lookup] ?? "passive";
+}
+export async function setProjectSharing(dataDir, project, mode, projectKey) {
+    if (projectKey && !PROJECT_KEY_RE.test(projectKey))
+        fail("invalid_argument", "A stable project key is malformed");
+    let resolvedProjectKey = projectKey ?? null;
+    if (!resolvedProjectKey) {
+        const { projectIdentityOfRecord } = await import("./adapters.js");
+        const keys = new Set();
+        for (const record of await listArchives(dataDir)) {
+            const identity = await projectIdentityOfRecord(record).catch(() => null);
+            if (identity?.project === project && identity.projectKey)
+                keys.add(identity.projectKey);
+        }
+        if (keys.size > 1) {
+            fail("invalid_argument", `More than one stable project is named ${project}; choose the exact folder so sharing cannot cross repositories`);
+        }
+        resolvedProjectKey = [...keys][0] ?? null;
+    }
+    const bindingKey = resolvedProjectKey || project;
+    const next = await mutateConfigAtomically(dataDir, (config) => ({
+        ...config, projectSharing: { ...(config.projectSharing ?? {}), [bindingKey]: mode },
+    }));
+    await recordAudit(dataDir, "project.sharing", "allowed", { project, ...(resolvedProjectKey ? { projectKey: resolvedProjectKey } : {}), mode });
+    return next;
+}
+const TEAM_SPACE_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+const PROJECT_KEY_RE = /^(?:g1|p1):[a-f0-9]{64}$/;
+function assertTeamBinding(binding) {
+    if (!TEAM_SPACE_KEY_RE.test(binding.spaceKey))
+        fail("invalid_argument", "A team space key must be a 43-character base64url value");
+    if (binding.realtimeKey !== undefined && !TEAM_SPACE_KEY_RE.test(binding.realtimeKey)) {
+        fail("invalid_argument", "A team realtime key must be a 43-character base64url value");
+    }
+    if (binding.keyVersion !== undefined && (!Number.isSafeInteger(binding.keyVersion) || binding.keyVersion <= 0)) {
+        fail("invalid_argument", "A team key version must be a positive integer");
+    }
+    if (binding.role !== undefined && binding.role !== "owner" && binding.role !== "member") {
+        fail("invalid_argument", "A team role must be owner or member");
+    }
+}
+export function teamSpaceOf(config, project, projectKey) {
+    // A caller that knows the stable key has supplied all the identity evidence
+    // available. Falling back to a same-named legacy entry would reintroduce the
+    // collision this key exists to prevent, so a miss is deliberately final.
+    const lookup = projectKey || project;
+    if (!lookup)
+        return null;
+    const value = config.teamSpaces?.[lookup];
+    return value && typeof value.spaceKey === "string" ? value : null;
+}
+/**
+ * Adds keyed aliases for old label-keyed bindings only when local discovery
+ * proves that label names exactly one stable project. The legacy entry stays
+ * in place for older Sealkeep builds; duplicate labels stay untouched and are
+ * therefore invisible to new exact-key access decisions.
+ */
+export async function migrateLegacyTeamSpaceBindings(dataDir, identities) {
+    const keysByLabel = new Map();
+    for (const identity of identities) {
+        if (!identity.project || !identity.projectKey || !PROJECT_KEY_RE.test(identity.projectKey))
+            continue;
+        const set = keysByLabel.get(identity.project) ?? new Set();
+        set.add(identity.projectKey);
+        keysByLabel.set(identity.project, set);
+    }
+    const initial = await readConfig(dataDir);
+    const canMigrate = (legacyLabel, target) => {
+        if (PROJECT_KEY_RE.test(legacyLabel))
+            return false;
+        const matches = [...(keysByLabel.get(legacyLabel) ?? [])];
+        return matches.length === 1 && !target?.[matches[0]];
+    };
+    const needsMigration = Object.keys(initial.teamSpaces ?? {}).some((legacyLabel) => canMigrate(legacyLabel, initial.teamSpaces))
+        || Object.keys(initial.projectSharing ?? {}).some((legacyLabel) => canMigrate(legacyLabel, initial.projectSharing));
+    if (!needsMigration)
+        return initial;
+    return mutateConfigAtomically(dataDir, (config) => {
+        const teamSpaces = { ...(config.teamSpaces ?? {}) };
+        const projectSharing = { ...(config.projectSharing ?? {}) };
+        let changed = false;
+        for (const [legacyLabel, binding] of Object.entries(config.teamSpaces ?? {})) {
+            if (PROJECT_KEY_RE.test(legacyLabel))
+                continue;
+            const matches = [...(keysByLabel.get(legacyLabel) ?? [])];
+            if (matches.length !== 1 || teamSpaces[matches[0]])
+                continue;
+            teamSpaces[matches[0]] = { ...binding, localProject: legacyLabel };
+            if (config.projectSharing?.[legacyLabel])
+                projectSharing[matches[0]] = config.projectSharing[legacyLabel];
+            changed = true;
+        }
+        // Sharing mode existed before stable project identity and may have no team
+        // binding at all. Copy it independently, but only when local discovery
+        // proves the display label names exactly one key. Ambiguous labels remain
+        // legacy-only and are invisible to keyed callers.
+        for (const [legacyLabel, mode] of Object.entries(config.projectSharing ?? {})) {
+            if (PROJECT_KEY_RE.test(legacyLabel))
+                continue;
+            const matches = [...(keysByLabel.get(legacyLabel) ?? [])];
+            if (matches.length !== 1 || projectSharing[matches[0]])
+                continue;
+            projectSharing[matches[0]] = mode;
+            changed = true;
+        }
+        return changed ? { ...config, teamSpaces, projectSharing } : config;
+    });
+}
+/**
+ * Records the dashboard-visible choice that this checkout participates in a
+ * team space. It stores only the opaque space id; encryption keys never enter
+ * config.json. Binding also enables the automatic live lane for that project.
+ */
+export async function bindTeamSpace(dataDir, project, binding, projectKey) {
+    if (!project.trim())
+        fail("invalid_argument", "A project is required to join a team space");
+    if (projectKey && !PROJECT_KEY_RE.test(projectKey))
+        fail("invalid_argument", "A stable project key is malformed");
+    assertTeamBinding(binding);
+    const bindingKey = projectKey || project;
+    const storedBinding = projectKey ? { ...binding, localProject: project } : { ...binding };
+    const next = await mutateConfigAtomically(dataDir, (config) => ({
+        ...config,
+        // An explicit folder selection is also an explicit reconnect on this
+        // machine, so it clears any earlier local disconnect tombstone.
+        teamSpaceOptOuts: (config.teamSpaceOptOuts ?? []).filter((spaceKey) => spaceKey !== binding.spaceKey),
+        projectSharing: { ...(config.projectSharing ?? {}), [bindingKey]: "active" },
+        teamSpaces: { ...(config.teamSpaces ?? {}), [bindingKey]: storedBinding },
+        // A folder can be a doorway into only one logical project. Once it has a
+        // verified binding it is no longer pending in any project-creation draft.
+        teamProjectDrafts: (config.teamProjectDrafts ?? [])
+            .map((draft) => {
+            if (projectKey && draft.projectSelections) {
+                const projectSelections = draft.projectSelections.filter((item) => item.projectKey !== projectKey);
+                return { ...draft, projectSelections, projects: [...new Set(projectSelections.map((item) => item.project))] };
+            }
+            return { ...draft, projects: draft.projects.filter((name) => name !== project) };
+        })
+            .filter((draft) => draft.projectSelections ? draft.projectSelections.length > 0 : draft.projects.length > 0),
+    }));
+    await recordAudit(dataDir, "project.sharing", "allowed", {
+        project,
+        ...(projectKey ? { projectKey } : {}),
+        mode: "active",
+        teamSpace: createHash("sha256").update(binding.spaceKey).digest("hex").slice(0, 12),
+    });
+    return next;
+}
+/**
+ * Remember which detected local folders should become one logical project.
+ * No path or project label is sent to the hosted plane here. The account page
+ * creates the logical project, then normal daemon reconciliation consumes this
+ * local draft when the matching project appears.
+ */
+export async function stageTeamProjectDraft(dataDir, projectName, projects) {
+    const name = projectName.trim();
+    const keyed = projects.length > 0 && typeof projects[0] !== "string";
+    const projectSelections = keyed
+        ? [...new Map(projects.map((item) => [item.projectKey, { projectKey: item.projectKey.trim(), project: item.project.trim() }])).values()]
+        : undefined;
+    const localProjects = projectSelections
+        ? [...new Set(projectSelections.map((item) => item.project).filter(Boolean))]
+        : [...new Set(projects.map((project) => project.trim()).filter(Boolean))];
+    if (!name || name.length > 120)
+        fail("invalid_argument", "A project name between 1 and 120 characters is required");
+    if (!localProjects.length || localProjects.length > 50 || localProjects.some((project) => project.length > 240)
+        || projectSelections?.some((item) => !item.project || !PROJECT_KEY_RE.test(item.projectKey))) {
+        fail("invalid_argument", "Choose between 1 and 50 detected folders for this project");
+    }
+    const draft = {
+        projectName: name,
+        projects: localProjects,
+        ...(projectSelections ? { projectSelections } : {}),
+        createdAt: new Date().toISOString(),
+    };
+    await mutateConfigAtomically(dataDir, (config) => {
+        const selected = new Set(localProjects);
+        const selectedKeys = new Set(projectSelections?.map((item) => item.projectKey) ?? []);
+        const sameName = name.toLocaleLowerCase();
+        // Selecting a folder for a new logical project moves it out of any older
+        // unfinished draft. It never creates two copies or two access scopes.
+        const retained = (config.teamProjectDrafts ?? [])
+            .filter((item) => item.projectName.trim().toLocaleLowerCase() !== sameName)
+            .map((item) => {
+            if (selectedKeys.size > 0 && item.projectSelections) {
+                const remaining = item.projectSelections.filter((selection) => !selectedKeys.has(selection.projectKey));
+                return { ...item, projectSelections: remaining, projects: [...new Set(remaining.map((selection) => selection.project))] };
+            }
+            if (!projectSelections)
+                return { ...item, projects: item.projects.filter((project) => !selected.has(project)) };
+            return item;
+        })
+            .filter((item) => item.projectSelections ? item.projectSelections.length > 0 : item.projects.length > 0);
+        return { ...config, teamProjectDrafts: [...retained, draft] };
+    });
+    await recordAudit(dataDir, "project.draft", "allowed", { projectName: name, folders: localProjects.length });
+    return draft;
+}
+export async function removeTeamProjectDraft(dataDir, projectName) {
+    const wanted = projectName.trim().toLocaleLowerCase();
+    const next = await mutateConfigAtomically(dataDir, (config) => ({
+        ...config,
+        teamProjectDrafts: (config.teamProjectDrafts ?? []).filter((draft) => draft.projectName.trim().toLocaleLowerCase() !== wanted),
+    }));
+    await recordAudit(dataDir, "project.draft", "allowed", { projectName: projectName.trim(), cancelled: true });
+    return next;
+}
+export async function unbindTeamSpace(dataDir, project, projectKey) {
+    const bindingKey = projectKey || project;
+    const next = await mutateConfigAtomically(dataDir, (config) => {
+        const teamSpaces = Object.fromEntries(Object.entries(config.teamSpaces ?? {}).filter(([name]) => name !== bindingKey));
+        return { ...config, teamSpaces, projectSharing: { ...(config.projectSharing ?? {}), [bindingKey]: "passive" } };
+    });
+    await recordAudit(dataDir, "project.sharing", "allowed", { project, ...(projectKey ? { projectKey } : {}), mode: "passive", teamSpace: null });
+    return next;
+}
+/**
+ * Disconnect one hosted project from this machine without changing cloud
+ * membership. The tombstone is deliberate: daemon reconciliation must not
+ * silently recreate a binding the person just removed.
+ */
+export async function disconnectTeamSpaceOnMachine(dataDir, spaceKey) {
+    if (!TEAM_SPACE_KEY_RE.test(spaceKey))
+        fail("invalid_argument", "A team space key must be a 43-character base64url value");
+    let disconnected = [];
+    const next = await mutateConfigAtomically(dataDir, (config) => {
+        disconnected = Object.entries(config.teamSpaces ?? {})
+            .filter(([, binding]) => binding.spaceKey === spaceKey)
+            .map(([key, binding]) => ({ key, project: binding.localProject ?? key }));
+        const removed = new Set(disconnected.map((item) => item.key));
+        const teamSpaces = Object.fromEntries(Object.entries(config.teamSpaces ?? {}).filter(([key]) => !removed.has(key)));
+        const projectSharing = { ...(config.projectSharing ?? {}) };
+        for (const item of disconnected)
+            projectSharing[item.key] = "passive";
+        const teamSpaceOptOuts = [...new Set([...(config.teamSpaceOptOuts ?? []), spaceKey])];
+        return { ...config, teamSpaces, projectSharing, teamSpaceOptOuts };
+    });
+    await Promise.all(disconnected.map(({ key, project }) => recordAudit(dataDir, "project.sharing", "allowed", {
+        project,
+        ...(key === project ? {} : { projectKey: key }),
+        mode: "passive",
+        teamSpace: null,
+        reason: "machine-disconnected",
+    })));
+    return next;
+}
+/**
+ * Apply a hosted key/version/route update to every local checkout bound to one
+ * logical space. `undefined` patch members are ignored so an older hosted
+ * response cannot erase a newer route already learned by this machine.
+ */
+export async function updateTeamSpaceBindings(dataDir, spaceKey, patch) {
+    if (!TEAM_SPACE_KEY_RE.test(spaceKey))
+        fail("invalid_argument", "A team space key must be a 43-character base64url value");
+    const defined = {
+        ...(patch.role !== undefined ? { role: patch.role } : {}),
+        ...(patch.keyVersion !== undefined ? { keyVersion: patch.keyVersion } : {}),
+        ...(patch.realtimeKey !== undefined ? { realtimeKey: patch.realtimeKey } : {}),
+    };
+    assertTeamBinding({ spaceKey, ...defined });
+    return mutateConfigAtomically(dataDir, (config) => {
+        let changed = false;
+        const teamSpaces = Object.fromEntries(Object.entries(config.teamSpaces ?? {}).map(([project, binding]) => {
+            if (binding.spaceKey !== spaceKey)
+                return [project, binding];
+            const nextBinding = { ...binding, ...defined };
+            if (nextBinding.role !== binding.role
+                || nextBinding.keyVersion !== binding.keyVersion
+                || nextBinding.realtimeKey !== binding.realtimeKey)
+                changed = true;
+            return [project, nextBinding];
+        }));
+        return changed ? { ...config, teamSpaces } : config;
+    });
+}
+/**
+ * Revoke every checkout bound to a removed hosted membership in one atomic
+ * config replacement. The logical space disappears and all affected projects
+ * become passive together; encrypted archives and project files are untouched.
+ */
+export async function revokeTeamSpaceBindings(dataDir, spaceKey) {
+    if (!TEAM_SPACE_KEY_RE.test(spaceKey))
+        fail("invalid_argument", "A team space key must be a 43-character base64url value");
+    let revokedProjects = [];
+    const next = await mutateConfigAtomically(dataDir, (config) => {
+        revokedProjects = Object.entries(config.teamSpaces ?? {})
+            .filter(([, binding]) => binding.spaceKey === spaceKey)
+            .map(([project]) => project);
+        if (!revokedProjects.length)
+            return config;
+        const revoked = new Set(revokedProjects);
+        const teamSpaces = Object.fromEntries(Object.entries(config.teamSpaces ?? {}).filter(([project]) => !revoked.has(project)));
+        const projectSharing = { ...(config.projectSharing ?? {}) };
+        for (const project of revokedProjects)
+            projectSharing[project] = "passive";
+        return { ...config, teamSpaces, projectSharing };
+    });
+    await Promise.all(revokedProjects.map((project) => recordAudit(dataDir, "project.sharing", "allowed", {
+        project, mode: "passive", teamSpace: null, reason: "membership-revoked",
+    })));
+    return next;
+}
 export async function addRecipient(dataDir, label, publicKeyBase64, group, 
 /**
  * Tie this key to one project and it becomes a member of that project only:
@@ -453,36 +1960,100 @@ export async function addRecipient(dataDir, label, publicKeyBase64, group,
  * seals. A colleague on `checkout-rewrite` never receives the rest of your
  * work, which is the difference between sharing a folder and handing over a
  * drive.
- */
-project) {
+*/
+project, projectKey) {
     if (!label.trim())
         fail("invalid_argument", "A recipient label is required");
     const raw = Buffer.from(publicKeyBase64, "base64");
     if (raw.length !== 32)
         fail("invalid_argument", "An X25519 public key must be 32 bytes, base64 encoded");
-    const config = await readConfig(dataDir);
+    if (projectKey && !PROJECT_KEY_RE.test(projectKey))
+        fail("invalid_argument", "A stable project key is malformed");
     const id = keyRecipientId(raw);
-    const recipients = (config.recipients ?? []).filter((recipient) => recipient.id !== id);
-    recipients.push({ id, label: label.trim(), publicKey: raw.toString("base64"), addedAt: new Date().toISOString(), ...(group ? { group } : {}), ...(project ? { project } : {}) });
-    const next = { ...config, recipients };
-    await writeJson(configPath(dataDir), next);
-    await recordAudit(dataDir, "recipient.add", "allowed", { recipientId: id, label: label.trim(), group: group ?? null, project: project ?? null });
+    const recipient = { id, label: label.trim(), publicKey: raw.toString("base64"), addedAt: new Date().toISOString(), ...(group ? { group } : {}), ...(project ? { project } : {}), ...(projectKey ? { projectKey } : {}) };
+    const next = await mutateConfigAtomically(dataDir, (config) => ({
+        ...config,
+        recipients: [...(config.recipients ?? []).filter((value) => value.id !== id), recipient],
+    }));
+    await recordAudit(dataDir, "recipient.add", "allowed", { recipientId: id, label: label.trim(), group: group ?? null, project: project ?? null, projectKey: projectKey ?? null });
     return next;
 }
 /** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
 export async function removeRecipient(dataDir, id) {
-    const config = await readConfig(dataDir);
-    const recipients = (config.recipients ?? []).filter((recipient) => recipient.id !== id);
-    if (recipients.length === (config.recipients ?? []).length)
-        fail("invalid_argument", `No recipient with id ${id}`, { recipientId: id });
-    const next = { ...config, recipients };
-    await writeJson(configPath(dataDir), next);
+    const next = await mutateConfigAtomically(dataDir, (config) => {
+        const recipients = (config.recipients ?? []).filter((recipient) => recipient.id !== id);
+        if (recipients.length === (config.recipients ?? []).length)
+            fail("invalid_argument", `No recipient with id ${id}`, { recipientId: id });
+        return { ...config, recipients };
+    });
+    // The search index is sealed per project to the members that project had at
+    // build time. Removing someone here without touching those shards left the
+    // revoked key able to open one indefinitely — the documented flow
+    // (`recipients remove` then `rewrap`) rebuilds archives, never the index. So
+    // revocation drops the shards outright; the next `index build` writes fresh
+    // ones for whoever remains.
+    const { invalidateScopedShards } = await import("./search.js");
+    await invalidateScopedShards(dataDir);
     await recordAudit(dataDir, "recipient.remove", "allowed", { recipientId: id });
     return next;
 }
-/** Persists a full config document after validation by the caller. */
+/**
+ * Persists a full config document after validation by the caller. Team state
+ * is deliberately retained from the lock-protected current file: bindings and
+ * revocations are changed only through their dedicated atomic helpers.
+ */
 export async function writeConfig(dataDir, config) {
-    await writeJson(configPath(dataDir), config);
+    await mutateConfigAtomically(dataDir, (current) => ({
+        ...config,
+        teamSpaces: current.teamSpaces,
+        projectSharing: current.projectSharing,
+    }));
+}
+/**
+ * Installs a vault identity that was authenticated and decrypted by a transfer
+ * protocol before this call. Unlike `initialize`, this must not mint a new id
+ * or phrase; unlike `writeConfig`, it must work before config.json exists.
+ * The storage root is always local to this data directory, regardless of what
+ * the sending machine used, and the same cross-process lock/refusal protects
+ * against replacing a vault that appeared while approval was in flight.
+ */
+export async function initializeTransferredVault(dataDir, transferred) {
+    if (transferred.version !== CONFIG_VERSION || !transferred.vaultId || !transferred.recovery?.phraseCheck) {
+        return fail("invalid_argument", "The transferred vault identity is not supported by this SealKeep build");
+    }
+    const config = {
+        ...transferred,
+        version: CONFIG_VERSION,
+        storage: { provider: "local", root: archiveDir(dataDir) },
+    };
+    await mkdir(config.storage.root, { recursive: true });
+    await withConfigLock(dataDir, async () => {
+        if (await exists(configPath(dataDir)))
+            fail("vault_already_initialized", `Vault already initialized at ${dataDir}`, { dataDir });
+        await writeJsonAtomic(configPath(dataDir), config);
+    });
+    return config;
+}
+/** Merge a top-level patch into the latest lock-protected config document. */
+export async function updateConfigFields(dataDir, patch) {
+    return mutateConfigAtomically(dataDir, (current) => ({ ...current, ...patch }));
+}
+/**
+ * Compare and update top-level config fields while holding the same
+ * cross-process lock as every other supported config mutation. This is the
+ * config-file equivalent of compare-and-set: callers which obtained a value
+ * before an asynchronous network read can refuse to replace a newer local
+ * choice which landed while that read was in flight.
+ */
+export async function updateConfigFieldsIf(dataDir, predicate, patch) {
+    let matched = false;
+    const config = await mutateConfigAtomically(dataDir, (current) => {
+        if (!predicate(current))
+            return current;
+        matched = true;
+        return { ...current, ...patch };
+    });
+    return { matched, config };
 }
 /** A non-mutating preview. Policy evaluation lives in `src/retention.ts`. */
 export async function previewRetention(dataDir, olderThanDays = 30) {
@@ -540,21 +2111,21 @@ export function assertPhraseOpens(config, record, rawPhrase) {
  */
 function openFailure(archiveId, error) {
     if (!(error instanceof Error))
-        return new VaultlineError("internal", `Unable to open archive ${archiveId}`, { archiveId });
+        return new SealkeepError("internal", `Unable to open archive ${archiveId}`, { archiveId });
     const code = error.code;
     const detail = { archiveId };
     switch (code) {
         case "destination_write_failed":
-            return new VaultlineError("destination_unwritable", error.message, detail);
+            return new SealkeepError("destination_unwritable", error.message, detail);
         case "chunk_auth_failed":
         case "chunk_hash_mismatch":
         case "envelope_malformed":
-            return new VaultlineError("ciphertext_integrity_failed", `Archive ${archiveId} is damaged: ${error.message}`, detail);
+            return new SealkeepError("ciphertext_integrity_failed", `Archive ${archiveId} is damaged: ${error.message}`, detail);
         case "plaintext_hash_mismatch":
         case "plaintext_length_mismatch":
-            return new VaultlineError("plaintext_integrity_failed", `Archive ${archiveId} did not reproduce the bytes it recorded: ${error.message}`, detail);
+            return new SealkeepError("plaintext_integrity_failed", `Archive ${archiveId} did not reproduce the bytes it recorded: ${error.message}`, detail);
         default:
-            return new VaultlineError("recovery_phrase_mismatch", `Unable to open archive ${archiveId}: ${error.message}`, detail);
+            return new SealkeepError("recovery_phrase_mismatch", `Unable to open archive ${archiveId}: ${error.message}`, detail);
     }
 }
 /**
@@ -573,7 +2144,14 @@ export async function restoreRecordToFile(dataDir, record,
  * shared for it to work. Until this existed, a registered recipient could be
  * wrapped in and still had no way to decrypt anything.
  */
-rawPhrase, destination, 
+rawPhrase, 
+/**
+ * A path, or a Writable to stream the plaintext into. The stream form exists
+ * so an archive can be PROVED to decrypt without spending its own size in
+ * free disk; the delta and plain-mode paths below still need a real file and
+ * say so rather than silently writing somewhere unexpected.
+ */
+destination, 
 /** Injectable so the offloaded-archive path can be proved without a bucket. */
 options = {}) {
     const withKey = typeof rawPhrase === "object";
@@ -597,15 +2175,22 @@ options = {}) {
     if (deltaOf(record)) {
         if (withKey)
             fail("invalid_argument", "This archive is an append onto an earlier one, and the chain is opened with the phrase. Restore it with --recovery-phrase.");
+        if (typeof destination !== "string")
+            fail("invalid_argument", "A delta chain is rebuilt through files and cannot stream to a sink");
         const { bytes } = await restoreDeltaChainToFile(dataDir, record, phrase, destination, options);
         return { bytes };
     }
-    if (config.storageMode === "plain")
+    if (config.storageMode === "plain") {
+        if (typeof destination !== "string")
+            fail("invalid_argument", "A plain-mode vault restores through files and cannot stream to a sink");
         return restorePlainRecordToFile(dataDir, config, record, phrase, destination, options);
+    }
     if (!isV2(record)) {
         // v1 predates chunking: there is one AEAD frame over the whole archive, so
         // there is nothing to stream and nothing to gain by pretending otherwise.
         const { plaintext } = await decryptRecord(dataDir, record.id, phrase);
+        if (typeof destination !== "string")
+            fail("invalid_argument", "This archive restores through a file and cannot stream to a sink");
         await writeFile(destination, plaintext, { mode: 0o600 });
         return { bytes: plaintext.length };
     }
@@ -615,7 +2200,10 @@ options = {}) {
     // the space saving real. An archive that was never offloaded resolves to its
     // own path and releases to nothing.
     const { materialiseArchive } = await import("./offload.js");
-    const source = await materialiseArchive(dataDir, record, options.client);
+    const source = await materialiseArchive(dataDir, record, options.client, {
+        signal: options.signal,
+        scratchWaitMs: options.scratchWaitMs,
+    });
     try {
         const { sha256: stored } = await hashFileRange(source.path);
         if (!equalHex(stored, record.cipher.ciphertextSha256))
@@ -646,8 +2234,16 @@ options = {}) {
  * base whose recorded length is not what the delta sealed from is refused
  * here, before any restore starts writing.
  */
-export function resolveDeltaChain(archives, target) {
-    const byId = new Map(archives.map((record) => [record.id, record]));
+export function resolveDeltaChain(archives, target, 
+/**
+ * Callers resolving many heads from one ledger may supply its shared index.
+ * Rebuilding the same thousands-entry map once per visible session turned a
+ * linear dashboard question into quadratic work. The optional argument does
+ * not change resolution semantics; it only lets that immutable lookup be
+ * built once for the batch.
+ */
+archiveIndex) {
+    const byId = archiveIndex ?? new Map(archives.map((record) => [record.id, record]));
     const chain = [target];
     const seen = new Set([target.id]);
     let cursor = target;
@@ -770,24 +2366,12 @@ async function restorePlainRecordToFile(dataDir, config, record, phrase, destina
         await source.release();
     }
 }
-/**
- * Verifies then decrypts one archive in memory. Ciphertext integrity is checked
- * before the key touches it, and plaintext integrity after.
- *
- * This holds the whole transcript at once; `restoreRecordToFile` is the
- * constant-memory path and is what restoring uses. Callers that genuinely need
- * the bytes in hand — indexing, the v1 migration — still come through here.
- */
-/**
- * The sealed bytes of a record, wherever they live. A local blob reads
- * straight from disk; an OFFLOADED archive — sealed copy in the cloud, local
- * blob reclaimed — is fetched hash-checked and held only for the read. Found
- * by the live value drill: `sealkeep index build` died with ENOENT on the
- * first offloaded legacy archive it met, because this read assumed the blob.
- */
-async function readSealedObject(dataDir, record) {
+async function readSealedObject(dataDir, record, options = {}) {
     const { materialiseArchive } = await import("./offload.js");
-    const materialised = await materialiseArchive(dataDir, record);
+    const materialised = await materialiseArchive(dataDir, record, options.client, {
+        signal: options.signal,
+        scratchWaitMs: options.scratchWaitMs,
+    });
     try {
         return await readFile(materialised.path);
     }
@@ -795,7 +2379,7 @@ async function readSealedObject(dataDir, record) {
         await materialised.release();
     }
 }
-export async function decryptRecord(dataDir, id, rawPhrase) {
+export async function decryptRecord(dataDir, id, rawPhrase, options = {}) {
     const phrase = canonicalPhrase(rawPhrase);
     const config = await readConfig(dataDir);
     const record = await findArchive(dataDir, id);
@@ -805,11 +2389,11 @@ export async function decryptRecord(dataDir, id, rawPhrase) {
     // decrypt a tail and correctly refuse it as not matching the record.
     if (deltaOf(record) && config.storageMode !== "plain") {
         const chain = resolveDeltaChain(await listArchives(dataDir), record);
-        const pieces = [(await decryptRecord(dataDir, chain[0].id, phrase)).plaintext];
+        const pieces = [(await decryptRecord(dataDir, chain[0].id, phrase, options)).plaintext];
         for (const link of chain.slice(1)) {
             if (!isV2(link))
                 fail("ciphertext_integrity_failed", `Delta ${link.id} is not a v2 archive and cannot hold a sealed range`, { archiveId: link.id });
-            const sealedRange = await readSealedObject(dataDir, link);
+            const sealedRange = await readSealedObject(dataDir, link, options);
             if (!equalHex(sha256(sealedRange), link.cipher.ciphertextSha256))
                 fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: link.id });
             try {
@@ -824,7 +2408,7 @@ export async function decryptRecord(dataDir, id, rawPhrase) {
             fail("plaintext_integrity_failed", "Plaintext integrity check failed after decryption", { archiveId: id });
         return { record, plaintext: assembled };
     }
-    const ciphertext = await readSealedObject(dataDir, record);
+    const ciphertext = await readSealedObject(dataDir, record, options);
     if (!equalHex(sha256(ciphertext), record.cipher.ciphertextSha256))
         fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: id });
     // In a plain vault the stored object is a gzip, so "decrypt" is gunzip — but