sealkeep 0.5.0

package/dist/src/disk.d.ts

@@ -0,0 +1,110 @@
+/**
+ * How much room archiving needs, and whether there is any.
+ *
+ * Archiving costs disk before it saves any. A transcript is gzipped to a
+ * scratch file and then sealed into a second one, while the original is still
+ * sitting there — so free space dips by roughly twice the compressed size
+ * before the source is eligible to be reclaimed, and it is only ever reclaimed
+ * later, by a separate decision.
+ *
+ * That matters because of who this is for. The people who install this have
+ * nearly full disks; that is the problem it exists to solve. A background
+ * process that fills the last few gigabytes while trying to free some is not a
+ * degraded experience, it is the failure the user was already afraid of.
+ */
+/**
+ * Bytes to leave alone whatever happens, so the machine keeps working.
+ *
+ * 2 GB is the ceiling, not the rule. A flat 2 GB floor cut off exactly the
+ * people this exists for — someone with 1.5 GB free could not seal a 10 MB
+ * session that needed 7 MB. The reserve scales with the disk instead: 2% of
+ * the volume, never below 400 MB (where operating systems themselves start
+ * failing), never above 2 GB (where more head-room stops buying safety). A
+ * person who knows their machine can override it in Settings, down to the
+ * 200 MB hard floor.
+ */
+export declare const DISK_RESERVE_BYTES: number;
+export declare const MIN_RESERVE_BYTES: number;
+/** The automatic reserve for a volume of `totalBytes`. Unknown → the old 2 GB. */
+export declare function scaledReserve(totalBytes?: number): number;
+/**
+ * The reserve this vault actually runs with: the Settings override when a
+ * person set one (clamped to the hard floor), the scaled automatic otherwise.
+ * Reads local-settings.json directly — a three-line JSON peek is not worth an
+ * import cycle with the API module that owns the file.
+ */
+export declare function resolveReserveBytes(dataDir: string): Promise<number>;
+/**
+ * The measured ratio, not the hoped-for one.
+ *
+ * `vault.ts` assumed agent transcripts compress about 2x. Measured on a real
+ * 1.6 GB Codex rollout it is 1.5x — the sealed copy is 68.8% of the source —
+ * because these files carry a lot of base64 and tool output that has already
+ * been compressed once. Planning space against 2x would under-reserve on every
+ * real file, so the number here is the one that was observed, rounded against
+ * our own favour.
+ */
+export declare const OBSERVED_COMPRESSION = 0.7;
+/**
+ * What one archive of this size needs before it is safe to start.
+ *
+ * The gzip scratch and the sealed object both exist at once, so it is two
+ * compressed copies, plus the reserve. Incompressible input is the worst case
+ * and it is not rare enough to ignore, so the ratio is capped at 1: a file that
+ * does not shrink is planned for as if it will not.
+ */
+export declare function spaceNeededFor(sourceBytes: number, reserveBytes?: number): number;
+/** Free bytes on the volume holding `path`, or undefined where that cannot be asked. */
+export declare function freeBytes(path: string): Promise<number | undefined>;
+/**
+ * Space that in-flight seals have claimed but not yet turned into files.
+ *
+ * `statfs` answers what is free *now*, and a seal spends its space over the next
+ * seconds or minutes. Two seals that each ask "is there room?" in that window
+ * both hear yes and jointly overfill — which fired live: a seal and a test
+ * suite ate the same headroom to literally 0 bytes free. The ledger closes the
+ * window inside one process: a seal claims its bytes before asking, and the
+ * verdict counts everyone else's claims against the measured free space.
+ *
+ * Per-process on purpose. Cross-process seals still race exactly as they did,
+ * but every concurrent seal this codebase runs — the daemon's parallel drain,
+ * the local API's drain — shares one process, so the process ledger covers the
+ * collisions that actually happened.
+ */
+export declare class Reservations {
+    private readonly held;
+    /** Claims `bytes` for `jobId`. Reserving again replaces the earlier claim. */
+    reserve(jobId: string, bytes: number): void;
+    release(jobId: string): void;
+    /** Everything currently claimed, in bytes. */
+    get total(): number;
+    /**
+     * What everyone *else* has claimed. A seal asking about its own job must not
+     * have its own claim counted against it, or reserving first would make every
+     * verdict a refusal.
+     */
+    otherThan(jobId?: string): number;
+    get size(): number;
+}
+/** The one ledger every seal in this process coordinates through by default. */
+export declare const sealReservations: Reservations;
+export type SpaceVerdict = {
+    ok: boolean;
+    free?: number;
+    needed: number;
+    detail: string;
+};
+/**
+ * Whether there is room to archive this file right now.
+ *
+ * An unanswerable `statfs` is treated as room. That is deliberate and it is the
+ * less obvious direction: refusing to work because the free space could not be
+ * measured would turn an unusual filesystem into a silent stoppage, and the
+ * archive path already fails loudly and safely on ENOSPC. Guessing wrong here
+ * costs a failed archive; guessing wrong the other way costs every archive.
+ *
+ * With a `reservations` ledger, the verdict is taken against the free space
+ * that will remain once every *other* in-flight seal lands: measured free minus
+ * the ledger's claims other than `jobId`'s own.
+ */
+export declare function roomToArchive(dataDir: string, sourceBytes: number, reserveBytes?: number, reservations?: Reservations, jobId?: string): Promise<SpaceVerdict>;

package/dist/src/disk.js

@@ -0,0 +1,169 @@
+import { statfs } from "node:fs/promises";
+/**
+ * How much room archiving needs, and whether there is any.
+ *
+ * Archiving costs disk before it saves any. A transcript is gzipped to a
+ * scratch file and then sealed into a second one, while the original is still
+ * sitting there — so free space dips by roughly twice the compressed size
+ * before the source is eligible to be reclaimed, and it is only ever reclaimed
+ * later, by a separate decision.
+ *
+ * That matters because of who this is for. The people who install this have
+ * nearly full disks; that is the problem it exists to solve. A background
+ * process that fills the last few gigabytes while trying to free some is not a
+ * degraded experience, it is the failure the user was already afraid of.
+ */
+/**
+ * Bytes to leave alone whatever happens, so the machine keeps working.
+ *
+ * 2 GB is the ceiling, not the rule. A flat 2 GB floor cut off exactly the
+ * people this exists for — someone with 1.5 GB free could not seal a 10 MB
+ * session that needed 7 MB. The reserve scales with the disk instead: 2% of
+ * the volume, never below 400 MB (where operating systems themselves start
+ * failing), never above 2 GB (where more head-room stops buying safety). A
+ * person who knows their machine can override it in Settings, down to the
+ * 200 MB hard floor.
+ */
+export const DISK_RESERVE_BYTES = 2 * 1024 ** 3;
+export const MIN_RESERVE_BYTES = 200 * 1024 ** 2;
+/** The automatic reserve for a volume of `totalBytes`. Unknown → the old 2 GB. */
+export function scaledReserve(totalBytes) {
+    if (!Number.isFinite(totalBytes) || !totalBytes || totalBytes <= 0)
+        return DISK_RESERVE_BYTES;
+    return Math.min(DISK_RESERVE_BYTES, Math.max(400 * 1024 ** 2, Math.ceil(totalBytes * 0.02)));
+}
+/**
+ * The reserve this vault actually runs with: the Settings override when a
+ * person set one (clamped to the hard floor), the scaled automatic otherwise.
+ * Reads local-settings.json directly — a three-line JSON peek is not worth an
+ * import cycle with the API module that owns the file.
+ */
+export async function resolveReserveBytes(dataDir) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        const { join } = await import("node:path");
+        const saved = JSON.parse(await readFile(join(dataDir, "local-settings.json"), "utf8"));
+        const mb = saved?.diskReserveMb;
+        if (typeof mb === "number" && Number.isFinite(mb))
+            return Math.max(MIN_RESERVE_BYTES, Math.round(mb * 1024 ** 2));
+    }
+    catch { /* no settings file, or no override: automatic */ }
+    try {
+        const info = await statfs(dataDir);
+        return scaledReserve(Number(info.blocks) * Number(info.bsize));
+    }
+    catch {
+        return DISK_RESERVE_BYTES;
+    }
+}
+/**
+ * The measured ratio, not the hoped-for one.
+ *
+ * `vault.ts` assumed agent transcripts compress about 2x. Measured on a real
+ * 1.6 GB Codex rollout it is 1.5x — the sealed copy is 68.8% of the source —
+ * because these files carry a lot of base64 and tool output that has already
+ * been compressed once. Planning space against 2x would under-reserve on every
+ * real file, so the number here is the one that was observed, rounded against
+ * our own favour.
+ */
+export const OBSERVED_COMPRESSION = 0.7;
+/**
+ * What one archive of this size needs before it is safe to start.
+ *
+ * The gzip scratch and the sealed object both exist at once, so it is two
+ * compressed copies, plus the reserve. Incompressible input is the worst case
+ * and it is not rare enough to ignore, so the ratio is capped at 1: a file that
+ * does not shrink is planned for as if it will not.
+ */
+export function spaceNeededFor(sourceBytes, reserveBytes = DISK_RESERVE_BYTES) {
+    // One ciphertext, roughly the compressed size, plus the standing reserve.
+    // The ×2 that used to live here paid for the legacy layout's staged gzip
+    // body coexisting with the ciphertext; gzip-chunk seals in a single pass
+    // and the staging is gone. A 5 GB session now asks for ~5.5 GB free, not 9.
+    return Math.ceil(sourceBytes * Math.min(1, OBSERVED_COMPRESSION)) + reserveBytes;
+}
+/** Free bytes on the volume holding `path`, or undefined where that cannot be asked. */
+export async function freeBytes(path) {
+    try {
+        const info = await statfs(path);
+        return Number(info.bavail) * Number(info.bsize);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Space that in-flight seals have claimed but not yet turned into files.
+ *
+ * `statfs` answers what is free *now*, and a seal spends its space over the next
+ * seconds or minutes. Two seals that each ask "is there room?" in that window
+ * both hear yes and jointly overfill — which fired live: a seal and a test
+ * suite ate the same headroom to literally 0 bytes free. The ledger closes the
+ * window inside one process: a seal claims its bytes before asking, and the
+ * verdict counts everyone else's claims against the measured free space.
+ *
+ * Per-process on purpose. Cross-process seals still race exactly as they did,
+ * but every concurrent seal this codebase runs — the daemon's parallel drain,
+ * the local API's drain — shares one process, so the process ledger covers the
+ * collisions that actually happened.
+ */
+export class Reservations {
+    held = new Map();
+    /** Claims `bytes` for `jobId`. Reserving again replaces the earlier claim. */
+    reserve(jobId, bytes) {
+        this.held.set(jobId, Math.max(0, Math.ceil(bytes)));
+    }
+    release(jobId) {
+        this.held.delete(jobId);
+    }
+    /** Everything currently claimed, in bytes. */
+    get total() {
+        return this.otherThan();
+    }
+    /**
+     * What everyone *else* has claimed. A seal asking about its own job must not
+     * have its own claim counted against it, or reserving first would make every
+     * verdict a refusal.
+     */
+    otherThan(jobId) {
+        let total = 0;
+        for (const [id, bytes] of this.held)
+            if (id !== jobId)
+                total += bytes;
+        return total;
+    }
+    get size() {
+        return this.held.size;
+    }
+}
+/** The one ledger every seal in this process coordinates through by default. */
+export const sealReservations = new Reservations();
+/**
+ * Whether there is room to archive this file right now.
+ *
+ * An unanswerable `statfs` is treated as room. That is deliberate and it is the
+ * less obvious direction: refusing to work because the free space could not be
+ * measured would turn an unusual filesystem into a silent stoppage, and the
+ * archive path already fails loudly and safely on ENOSPC. Guessing wrong here
+ * costs a failed archive; guessing wrong the other way costs every archive.
+ *
+ * With a `reservations` ledger, the verdict is taken against the free space
+ * that will remain once every *other* in-flight seal lands: measured free minus
+ * the ledger's claims other than `jobId`'s own.
+ */
+export async function roomToArchive(dataDir, sourceBytes, reserveBytes, reservations, jobId) {
+    const reserve = reserveBytes ?? await resolveReserveBytes(dataDir);
+    const needed = spaceNeededFor(sourceBytes, reserve);
+    const measured = await freeBytes(dataDir);
+    if (measured === undefined)
+        return { ok: true, needed, detail: "free space could not be measured, so this was allowed to proceed" };
+    const held = reservations?.otherThan(jobId) ?? 0;
+    const free = Math.max(0, measured - held);
+    const gb = (value) => `${(value / 1024 ** 3).toFixed(1)} GB`;
+    if (free >= needed)
+        return { ok: true, free, needed, detail: `${gb(free)} free, ${gb(needed)} needed` };
+    return {
+        ok: false, free, needed,
+        detail: `needs about ${gb(needed)} free to seal safely (${gb(reserve)} of that is the reserve that keeps this machine itself alive — adjustable in Settings) and there is ${gb(free)}${held > 0 ? ` after ${gb(held)} already claimed by seals in flight` : ""}; left queued rather than filling the disk`
+    };
+}

package/dist/src/doctor.d.ts

@@ -0,0 +1,11 @@
+export type CheckStatus = "pass" | "warn" | "fail";
+export type Check = {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+};
+export type DoctorReport = {
+    ok: boolean;
+    checks: Check[];
+};
+export declare function runDoctor(dataDir: string, env?: NodeJS.ProcessEnv): Promise<DoctorReport>;

package/dist/src/doctor.js

@@ -0,0 +1,198 @@
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { detectAgents } from "./adapters.js";
+import { isVaultlineError } from "./errors.js";
+import { localApiTokenPath } from "./paths.js";
+import { ArchiveQueue } from "./queue.js";
+import { signerEnabled } from "./control-plane.js";
+import { quotaMessage, quotaState } from "./packages.js";
+import { loadProviderCredentials, resolveRecoveryPhrase } from "./secrets.js";
+import { ENVELOPE_VERSION, SUITES } from "../packages/vaultline-crypto/src/index.js";
+import { readConfig } from "./vault.js";
+async function writable(directory) {
+    const probe = join(directory, `.vaultline-write-probe-${randomUUID()}`);
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(probe, "");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await rm(probe, { force: true });
+    }
+}
+/**
+ * A read-mostly environment report. It writes only a probe file it removes, and
+ * it never reads transcript contents, prints a recovery phrase, or shows the API token.
+ */
+/** Whether this machine is signed in to managed storage, without failing if it is not. */
+async function managedAccount(dataDir) {
+    try {
+        const { accountStatus } = await import("./cloud.js");
+        const account = await accountStatus(dataDir);
+        return account?.email ? { email: account.email, plan: account.plan, quotaBytes: account.quota_bytes ?? 0, usedBytes: account.used_bytes ?? 0 } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A customer who fills their quota used to find out from a bare 402 on their
+ * next upload — no warning here, no number anywhere. `quota_bytes` and
+ * `used_bytes` were sitting on the account the whole time; this is doctor's
+ * side of surfacing them, sharing its wording with `cloud status`, `status`,
+ * and the rewritten 402 so all four agree.
+ */
+function quotaCheck(managed) {
+    const state = quotaState(managed.usedBytes, managed.quotaBytes);
+    const status = state.level === "over" ? "fail" : state.level === "ok" ? "pass" : "warn";
+    return { name: "quota", status, detail: quotaMessage(state) };
+}
+/**
+ * The panel warns that losing this machine loses every archive on it unless a
+ * sealed copy of the key is stored. Nothing on the machine ever checked, so the
+ * warning and the reality could disagree indefinitely.
+ */
+async function sealedCopyCheck(dataDir, signedIn) {
+    if (!signedIn)
+        return { name: "sealed-key-copy", status: "warn", detail: "Not signed in, so no sealed copy of your key is stored" };
+    try {
+        const { hasSealedCopy } = await import("./cloud.js");
+        return await hasSealedCopy(dataDir)
+            ? { name: "sealed-key-copy", status: "pass", detail: "A sealed copy of your key is stored with your account" }
+            : { name: "sealed-key-copy", status: "warn", detail: "Your key has no sealed backup yet. If this machine is lost, the archives on it cannot be opened by anyone, including us. Store one from the account panel." };
+    }
+    catch (error) {
+        return { name: "sealed-key-copy", status: "warn", detail: `Could not check for a sealed copy: ${error instanceof Error ? error.message.split("\n")[0] : "unknown"}` };
+    }
+}
+export async function runDoctor(dataDir, env = process.env) {
+    const checks = [];
+    const config = await readConfig(dataDir).catch((error) => {
+        // This renders in the Health tab, where a raw "config_unsupported_version:"
+        // slug or a bare "unreadable" reads, to someone told there is no reset, as
+        // "your vault is gone." Say what is and is not affected, and never a code.
+        const detail = isVaultlineError(error) && error.code === "vault_not_initialized"
+            ? "No vault has been set up on this machine yet. Open Sealkeep's setup page to create one."
+            : "Sealkeep can't read this vault's settings file. Your sealed archives are separate files and are not affected — don't create a new vault; restore this machine's vault folder from a backup, or contact support.";
+        checks.push({ name: "config", status: "fail", detail });
+        return null;
+    });
+    if (config) {
+        checks.push({ name: "config", status: "pass", detail: `Vault ${config.vaultId} (config v${config.version})` });
+        // A standing warning, like the crypto row: nothing about a healthy plain
+        // vault makes this go away, because the exposure is the choice itself.
+        if (config.storageMode === "plain") {
+            checks.push({ name: "storage-mode", status: "warn", detail: "Archives in this vault are stored unencrypted, by your choice at setup. Anyone who can read the storage can read the sessions." });
+        }
+        checks.push(await writable(config.storage.root)
+            ? { name: "archive-store", status: "pass", detail: `Writable: ${config.storage.root}` }
+            : { name: "archive-store", status: "fail", detail: `Not writable: ${config.storage.root}` });
+        // A machine on the managed tier has no remoteStorage of its own — the
+        // bucket is ours. Reporting "archives stay on this device" to someone who
+        // has been pushing to managed storage all week is worse than saying
+        // nothing: it is a health check telling them a comforting falsehood.
+        if (config.remoteStorage) {
+            checks.push({ name: "remote-storage", status: "pass", detail: `Target ${config.remoteStorage.provider}://${config.remoteStorage.bucket}/${config.remoteStorage.prefix}` });
+        }
+        else {
+            const managed = await managedAccount(dataDir);
+            checks.push(managed
+                // The cloud token lives in this machine's keychain, not in the vault,
+                // so being signed in says archives from here *can* go to managed
+                // storage — not that any have. Say the weaker, true thing.
+                ? { name: "remote-storage", status: "pass", detail: `Signed in to managed storage as ${managed.email} (${managed.plan})` }
+                : { name: "remote-storage", status: "warn", detail: "No remote target configured; archives stay on this device" });
+            checks.push(await sealedCopyCheck(dataDir, managed !== null));
+            // A zero quota is a plan with no managed entitlement at all — nothing to warn about.
+            if (managed && managed.quotaBytes > 0)
+                checks.push(quotaCheck(managed));
+        }
+    }
+    const stats = await new ArchiveQueue(dataDir).stats();
+    checks.push(stats.failed > 0
+        ? { name: "queue", status: "warn", detail: `${stats.failed} session${stats.failed === 1 ? "" : "s"} could not be archived. See the Queue tab for why, and retry from there.` }
+        : { name: "queue", status: "pass", detail: `${stats.ready} ready, ${stats.leased} in flight, ${stats.done} archived` });
+    const agents = await detectAgents();
+    const detected = agents.filter((agent) => agent.detected).map((agent) => agent.agent);
+    checks.push(detected.length > 0
+        ? { name: "agents", status: "pass", detail: `Detected: ${detected.join(", ")}` }
+        : { name: "agents", status: "warn", detail: "No supported agent directory found on this machine" });
+    // The failure Paul hit in the wild: an agent's own catalog still points at
+    // a session file that is gone — reclaimed by us, or deleted by anything —
+    // and "resume" breaks with no hint that the bytes are one command away.
+    // This check counts archived sessions whose source file is missing and
+    // hands over the exact command that puts each back where resume expects it.
+    try {
+        const { stat } = await import("node:fs/promises");
+        const { listArchives } = await import("./vault.js");
+        const records = (await listArchives(dataDir)).filter((record) => record.version === 2);
+        const missing = [];
+        for (const record of records) {
+            const there = await stat(record.source.path).then((entry) => entry.isFile()).catch(() => false);
+            if (!there)
+                missing.push(record.source.path.split("/").pop() ?? record.id);
+        }
+        if (missing.length > 0) {
+            checks.push({
+                name: "resumable-history", status: "pass",
+                detail: `${missing.length} archived session${missing.length === 1 ? " file is" : " files are"} no longer on disk (reclaimed or removed). An agent trying to resume one will say the file is missing — \`sealkeep recover <that filename>\` puts it back exactly where resume expects it. First: ${missing[0]}`
+            });
+        }
+        else if (records.length > 0) {
+            checks.push({ name: "resumable-history", status: "pass", detail: "Every archived session's file is still on disk; agent resume needs nothing from us" });
+        }
+    }
+    catch { /* an unreadable archive store already failed its own check above */ }
+    // What search can and cannot see, without opening anything: the coverage
+    // sidecar lists indexed archive ids, and the difference against the record
+    // set is precisely the work `sealkeep index build` would do. Paul's ask,
+    // verbatim: "i hope we are tracking whats tracked and indexed".
+    try {
+        const { indexCoverage } = await import("./search.js");
+        const coverage = await indexCoverage(dataDir);
+        if (coverage.total === 0) {
+            // nothing archived yet — nothing to say
+        }
+        else if (coverage.missing.length === 0) {
+            checks.push({ name: "search-index", status: "pass", detail: `All ${coverage.total} archives are in the content search index${coverage.builtAt ? ` (updated ${coverage.builtAt.slice(0, 10)})` : ""}.` });
+        }
+        else {
+            checks.push({
+                name: "search-index", status: "pass",
+                detail: `${coverage.indexed} of ${coverage.total} archives are searchable; ${coverage.missing.length} not yet indexed (new seals index themselves — \`sealkeep index build\` adds the rest). First missing: ${coverage.missing[0].path.split("/").pop() ?? coverage.missing[0].id}`
+            });
+        }
+    }
+    catch { /* coverage is advisory; a broken sidecar must not fail doctor */ }
+    // Where the daemon actually looks: an explicit env var, or the phrase the
+    // wizard put in this machine's keystore. This used to test only the env var,
+    // so a machine set up correctly through the window — phrase in the keystore,
+    // sealing away happily — was told on its Health tab that its phrase was
+    // missing and named an environment variable as the cure.
+    const phraseAvailable = config
+        ? await resolveRecoveryPhrase(dataDir, config.vaultId, undefined, env).then((phrase) => Boolean(phrase)).catch(() => false)
+        : Boolean(env.VAULTLINE_RECOVERY_PHRASE);
+    checks.push(phraseAvailable
+        ? { name: "recovery-phrase", status: "pass", detail: "This machine can unlock the vault on its own, so archiving runs unattended." }
+        : { name: "recovery-phrase", status: "warn", detail: "This machine doesn't hold your recovery phrase, so it can't archive on its own. Add it under Settings › Unlocking to let archiving run unattended. Your vault and archives are unaffected." });
+    const tokenMode = await stat(localApiTokenPath(dataDir)).then((info) => info.mode & 0o777).catch(() => null);
+    checks.push(tokenMode === null
+        ? { name: "local-api-token", status: "warn", detail: "No local API token yet; it is created when `sealkeep api` first starts" }
+        : tokenMode === 0o600
+            ? { name: "local-api-token", status: "pass", detail: "Local API token is owner-only" }
+            : { name: "local-api-token", status: "fail", detail: `Local API token mode is ${tokenMode.toString(8)}; it must be 600` });
+    const signerOn = signerEnabled(env);
+    const credentials = config ? await loadProviderCredentials(dataDir, config.vaultId).then(() => true).catch(() => false) : false;
+    checks.push(!signerOn
+        ? { name: "signer", status: "warn", detail: "New archives aren't being uploaded from this machine right now. Anything already shown as verified in your storage is safely there. Turn on automatic archiving in Settings to resume uploads." }
+        : credentials
+            ? { name: "signer", status: "pass", detail: "Signer enabled and provider credentials are available from the secret store" }
+            : { name: "signer", status: "warn", detail: "Uploads are on, but this machine has no key for the bucket. Add the bucket's credentials on the storage step of setup." });
+    // Deliberately a standing warning: the envelope is unaudited, and no local check can change that.
+    checks.push({ name: "crypto", status: "warn", detail: `Archive envelope v${ENVELOPE_VERSION} (${SUITES[0]}); implemented against published primitives and not independently audited` });
+    return { ok: checks.every((check) => check.status !== "fail"), checks };
+}

package/dist/src/enroll.d.ts

@@ -0,0 +1,27 @@
+import { type SyncRules } from "./sync-rules.js";
+import { type RetentionSettings } from "./retention.js";
+export type EnrollOptions = {
+    /** The short-lived code shown in the account panel under Devices > Add device. */
+    code: string;
+    /** How this machine will show up in the device list. */
+    label: string;
+    /** Injectable so enrollment is testable without a live server; defaults to the global fetch. */
+    transport?: typeof fetch;
+};
+export type EnrollResult = {
+    deviceId: string;
+    account: {
+        plan: string;
+        quotaBytes: number;
+        usedBytes: number;
+    };
+    /** The rules just cached locally, so a caller can report what is now enforced offline. */
+    settings: {
+        sync: SyncRules;
+        retention: RetentionSettings;
+    };
+    /** False when enrollment itself succeeded but saving the settings locally did not; see cacheWarning. */
+    settingsCached: boolean;
+    cacheWarning?: string;
+};
+export declare function enroll(dataDir: string, options: EnrollOptions): Promise<EnrollResult>;

package/dist/src/enroll.js

@@ -0,0 +1,136 @@
+import { fail } from "./errors.js";
+import { chooseBackend } from "./secrets.js";
+import { readConfig } from "./vault.js";
+import { DEFAULT_CLOUD_URL, tokenRefFor } from "./cloud.js";
+import { cacheSyncRules, cachedSyncRules, DEFAULT_SYNC_RULES } from "./sync-rules.js";
+import { setRetentionPolicy, retentionSettings, DEFAULT_RETENTION } from "./retention.js";
+/**
+ * Device enrollment: the client half of `sealkeep enroll ABCD-1234`.
+ *
+ * Today's setup is three separate commands — create a vault, sign in to
+ * Cloud, configure storage — each a place to stop half-configured. This
+ * collapses it to one: trade a short-lived code (minted in the account
+ * panel) for a device token, and pull down the account's sync and
+ * retention settings in the same round trip so they are enforceable
+ * offline before the first archive is ever queued.
+ *
+ * The server side of this contract does not exist yet, so `transport` is
+ * injectable — this module has to be testable against a fake today and
+ * work unchanged against the real thing later.
+ */
+const cloudUrl = (env = process.env) => (env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+/**
+ * The token location comes from cloud.ts rather than being restated here.
+ *
+ * It has to match exactly: `cloudToken()` and everything built on it —
+ * `accountStatus`, `pushArchive`, `resolveSyncRules` — look the token up by
+ * that key, so a divergence would make `enroll` report success while every
+ * call after it said "Not signed in to Sealkeep Cloud". A second copy that
+ * merely *looked* right is how `access_key_id` survived the rename to `akid`
+ * in two vending scripts and both tests.
+ */
+const tokenRef = tokenRefFor;
+const safeJson = (text) => { try {
+    return JSON.parse(text);
+}
+catch {
+    return { error: text.slice(0, 200) };
+} };
+/** What the account panel shows as this machine's platform. */
+function platformLabel() {
+    switch (process.platform) {
+        case "darwin": return "macOS";
+        case "win32": return "Windows";
+        case "linux": return "Linux";
+        default: return process.platform;
+    }
+}
+/**
+ * The backend for this endpoint doesn't exist yet, so the exact status for
+ * "the code didn't work" isn't settled. Whichever of these a bad, expired,
+ * or already-redeemed code comes back as, the client's answer is the
+ * same — the code is the problem, not the connection or the vault — so
+ * every one of them is treated identically and the server's own message
+ * carries the specifics.
+ */
+const CODE_REJECTED_STATUSES = new Set([400, 401, 404, 409, 410]);
+export async function enroll(dataDir, options) {
+    const code = options.code?.trim() ?? "";
+    const label = options.label?.trim() ?? "";
+    if (!code)
+        fail("invalid_argument", "An enrollment code is required. Find it in the account panel under Devices > Add device.");
+    if (!label)
+        fail("invalid_argument", `A device label is required, e.g. --label "work-laptop", so devices can be told apart later.`);
+    // No vault means nowhere to keep the token or the settings it unlocks,
+    // and the code is single-use — better to fail before spending it than
+    // after. readConfig's own "vault_not_initialized" message already names
+    // the fix, so it is left to propagate rather than rewritten here.
+    const { vaultId } = await readConfig(dataDir);
+    const backend = await chooseBackend(dataDir);
+    const ref = tokenRef(vaultId);
+    if (await backend.get(ref)) {
+        fail("forbidden", "This vault is already enrolled with Sealkeep Cloud. Run `sealkeep cloud logout` first if you want to enroll a different account or device.");
+    }
+    const transport = options.transport ?? fetch;
+    let response;
+    try {
+        response = await transport(`${cloudUrl()}/v1/cloud/devices/enroll`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ code, label, platform: platformLabel() })
+        });
+    }
+    catch (error) {
+        fail("internal", `Sealkeep Cloud is unreachable: ${error instanceof Error ? error.message : "network error"}. Check your connection and run \`sealkeep enroll ${code}\` again.`);
+    }
+    const text = await response.text();
+    const body = text ? safeJson(text) : null;
+    if (!response.ok) {
+        const message = body?.error ?? `${response.status} ${response.statusText}`;
+        if (CODE_REJECTED_STATUSES.has(response.status)) {
+            fail("unauthorized", `Sealkeep Cloud rejected code ${code}: ${message}. Get a fresh code from the account panel (Devices > Add device) and run \`sealkeep enroll <code>\` again.`);
+        }
+        fail("internal", `Sealkeep Cloud returned ${response.status} while enrolling: ${message}`);
+    }
+    const parsed = body;
+    if (!parsed || !parsed.device_id || !parsed.token) {
+        fail("internal", `Sealkeep Cloud accepted code ${code} but did not return a device token. Nothing was stored; run \`sealkeep enroll ${code}\` again.`);
+    }
+    const enrolled = parsed;
+    // Store the token before anything else. It is the one part of this that
+    // cannot be recomputed locally, and every later cloud.ts call —
+    // accountStatus, pushArchive, resolveSyncRules — reads it back from
+    // exactly this service/account pair.
+    await backend.set(ref, enrolled.token);
+    let settingsCached = true;
+    let cacheWarning;
+    let sync;
+    let retention;
+    try {
+        sync = await cacheSyncRules(dataDir, enrolled.settings ?? {});
+        const retentionIn = enrolled.settings?.retention;
+        const nextConfig = await setRetentionPolicy(dataDir, {
+            ...(retentionIn?.policy ? { policy: retentionIn.policy } : {}),
+            ...(retentionIn?.older_than_days !== undefined ? { olderThanDays: retentionIn.older_than_days } : {}),
+            ...(retentionIn?.grace_days !== undefined ? { graceDays: retentionIn.grace_days } : {})
+        });
+        retention = retentionSettings(nextConfig);
+    }
+    catch (error) {
+        // The device is enrolled either way: the token above is already
+        // stored, and retrying enroll() would now (correctly) report
+        // "already enrolled" rather than fix this. So a bad settings payload
+        // degrades to a warning instead of unwinding the enrollment.
+        settingsCached = false;
+        cacheWarning = `Enrolled, but could not save the account's sync and retention settings locally: ${error instanceof Error ? error.message : "unknown error"}. Offline runs use the last cached or default rules until this is retried — run \`sealkeep cloud status\` to fetch them again.`;
+        sync = (await cachedSyncRules(dataDir)) ?? DEFAULT_SYNC_RULES;
+        retention = DEFAULT_RETENTION;
+    }
+    return {
+        deviceId: enrolled.device_id,
+        account: { plan: enrolled.account.plan, quotaBytes: enrolled.account.quota_bytes, usedBytes: enrolled.account.used_bytes },
+        settings: { sync, retention },
+        settingsCached,
+        ...(cacheWarning ? { cacheWarning } : {})
+    };
+}