sealkeep 0.5.0

package/dist/src/recovery.js

@@ -0,0 +1,132 @@
+import { createInterface } from "node:readline/promises";
+import { matchesPhraseCheck } from "./crypto.js";
+import { canonicalPhrase, inspectPhrase, isMnemonic, PHRASE_WORDS } from "./mnemonic.js";
+import { readConfig } from "./vault.js";
+/**
+ * The recovery kit.
+ *
+ * Everything a person needs to get their archives back, except the one thing that
+ * must never be stored: the phrase itself. The sheet leaves numbered blanks for it,
+ * because the point of a written kit is that it lives on paper, in a drawer, far
+ * from the machine it unlocks.
+ */
+/**
+ * The sheet someone reads during an actual disaster.
+ *
+ * `managed` says this vault pushes to Sealkeep Cloud. Without it the kit told
+ * a paying customer "Storage: this machine only" and left the cloud steps out
+ * of the restore instructions — so the one document they reach for after
+ * losing the laptop would tell them their archives went with it.
+ */
+export function recoveryKit(config, options = {}) {
+    const when = (options.now ?? new Date()).toISOString().slice(0, 10);
+    const blanks = Array.from({ length: PHRASE_WORDS }, (_, index) => `  ${String(index + 1).padStart(2, " ")}. ______________`);
+    // Column-major, `rows` apart — the same layout the on-screen grid uses. The
+    // offsets were once +6/+12, hard-wired for a 12-word phrase; at 24 words that
+    // printed words 7, 8, 13 and 14 twice and left 21-24 with no blank at all, so
+    // anyone writing their phrase onto this sheet recorded it wrong. Deriving the
+    // stride from PHRASE_WORDS keeps the sheet correct if the length ever changes.
+    const rows = Math.ceil(PHRASE_WORDS / 3);
+    const columns = [];
+    for (let row = 0; row < rows; row += 1) {
+        columns.push([blanks[row], blanks[row + rows], blanks[row + rows * 2]].filter(Boolean).join("   "));
+    }
+    return `VAULTLINE RECOVERY KIT
+${"=".repeat(58)}
+
+Vault        ${config.vaultId}
+Created      ${when}
+Storage      ${config.remoteStorage
+        ? `${config.remoteStorage.provider}://${config.remoteStorage.bucket}/${config.remoteStorage.prefix}`
+        : options.managed
+            ? `Sealkeep Cloud, account ${options.managed.email}`
+            : "this machine only"}
+Devices      ${(config.recipients ?? []).length} registered key(s) besides the phrase
+${config.storageMode === "plain" ? `
+THIS VAULT IS NOT ENCRYPTED
+${"-".repeat(58)}
+This vault stores archives UNENCRYPTED — the phrase identifies it
+but protects nothing. Anyone who can read the storage can read the
+sessions. You chose this at setup; the phrase below still matters,
+because it is how a new machine proves it is restoring YOUR vault.
+` : ""}
+YOUR RECOVERY PHRASE
+${"-".repeat(58)}
+Write the ${PHRASE_WORDS} words here, in order. Do not photograph this sheet, and do
+not store it on the computer it unlocks.
+
+${columns.join("\n")}
+
+TO RESTORE ON A NEW MACHINE
+${"-".repeat(58)}
+  1. Install Sealkeep.
+  2. Run:  sealkeep setup --recovery-phrase "<the words above>"
+${config.remoteStorage ? `  3. Point it at your storage:
+       sealkeep storage configure --provider ${config.remoteStorage.provider} \\
+         --bucket ${config.remoteStorage.bucket} --prefix ${config.remoteStorage.prefix}
+  4. Restore a session:  sealkeep recover <archive-id> ./restored.jsonl`
+        : options.managed ? `  3. Sign in:  sealkeep cloud login --email ${options.managed.email}
+  4. See what is stored:  sealkeep cloud archives
+  5. Read one back:  sealkeep open <ref> ./restored.jsonl --recovery-phrase "<the words above>"
+
+     Every archive carries what is needed to open it, so this works on a
+     machine that has never seen your vault. The phrase is the only thing
+     you must bring.`
+            : "  3. Restore a session:  sealkeep recover <archive-id> ./restored.jsonl"}
+
+IF YOU LOSE THIS
+${"-".repeat(58)}
+Any device key you registered can also open your archives. If you lose the phrase
+and every registered device, the archives cannot be opened — not by you, not by
+support, not by whoever is holding the storage bucket. That is the design.
+
+Verify your copy any time with:  sealkeep recovery verify
+`;
+}
+/** Checks a typed phrase for shape, checksum, and whether it opens this vault. */
+export function verifyPhrase(config, typed) {
+    const inspection = inspectPhrase(typed);
+    // matchesPhraseCheck reads the format of the stored value itself (defect
+    // #49), so this is correct whether or not `config` already went through
+    // readConfig's legacy-upgrade path.
+    const matchesVault = matchesPhraseCheck(config.recovery.phraseCheck, canonicalPhrase(typed));
+    const problems = [...inspection.problems];
+    // A pre-word-list vault holds a free-text phrase, so only the vault check applies.
+    if (!inspection.valid && matchesVault) {
+        return { valid: true, matchesVault: true, problems: ["This vault predates word phrases, so only the vault check applies."] };
+    }
+    if (inspection.valid && !matchesVault) {
+        problems.push("These are valid recovery words, but they do not open this vault. Check you are reading the right kit.");
+    }
+    return { valid: inspection.valid && matchesVault, matchesVault, problems };
+}
+/**
+ * Asks the person to type their phrase back, the way a wallet does.
+ *
+ * Input is read without echo so it does not end up in a screenshot or a scrollback
+ * buffer, and it is never written anywhere.
+ */
+export async function promptForPhrase(prompt = "Type your recovery phrase: ") {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const output = process.stdout;
+    let muted = false;
+    const write = output.write.bind(output);
+    output.write = (chunk) => (muted ? true : write(chunk));
+    try {
+        const answer = rl.question(prompt);
+        muted = true;
+        const typed = await answer;
+        muted = false;
+        write("\n");
+        return typed;
+    }
+    finally {
+        muted = false;
+        output.write = write;
+        rl.close();
+    }
+}
+export async function verifyAgainstVault(dataDir, typed) {
+    return verifyPhrase(await readConfig(dataDir), typed);
+}
+export { isMnemonic, PHRASE_WORDS };

package/dist/src/rehydrate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Rehydration: the transparent answer to "resume is bound to a file we moved".
+ *
+ * The failure class this exists for is structural. Agents keep a catalog that
+ * binds a session id to a transcript path; Sealkeep's whole point is that the
+ * file can leave the disk once a sealed copy is safe. Those two facts collide
+ * the moment someone resumes an old session — unless the file comes BACK
+ * before the agent reads it. So: the agent's own SessionStart hook calls this,
+ * and when the path is missing but the vault holds it, the newest archive of
+ * that session is restored natively — exact path, exact bytes, delta chains
+ * resolved, chunks fetched from the bucket if the local blob was offloaded.
+ * The resume proceeds as if the file had never been away — paging, not loss.
+ *
+ * Contract with the agent: NEVER break the session. Every outcome — including
+ * "this vault has no phrase available" and "that session was never archived" —
+ * is a calm JSON line and exit 0. A hook that can fail a session start would
+ * be worse than the problem it solves.
+ */
+export type RehydrateOutcome = {
+    rehydrated: true;
+    archiveId: string;
+    output: string;
+    bytes: number;
+} | {
+    rehydrated: false;
+    reason: "already-present" | "no-target" | "not-archived" | "no-phrase" | "restore-failed";
+    note?: string;
+};
+export declare function rehydrateSession(dataDir: string, target: {
+    path?: string;
+    sessionId?: string;
+}, phrase: string | undefined, options?: {
+    home?: string;
+}): Promise<RehydrateOutcome>;
+/**
+ * Lenient hook-payload reading, distinct from `hookEventFromStdin` on purpose:
+ * that parser refuses when the transcript is unreadable, and an ABSENT
+ * transcript is this feature's entire subject.
+ */
+export declare function rehydrateTargetFromPayload(stdin: string): {
+    path?: string;
+    sessionId?: string;
+};

package/dist/src/rehydrate.js

@@ -0,0 +1,66 @@
+import { access, constants } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { listArchives } from "./vault.js";
+import { restoreArchive } from "./restore.js";
+import { recordAudit } from "./audit.js";
+export async function rehydrateSession(dataDir, target, phrase, options = {}) {
+    const wanted = target.path ? resolve(target.path) : null;
+    if (!wanted && !target.sessionId)
+        return { rehydrated: false, reason: "no-target" };
+    if (wanted) {
+        const present = await access(wanted, constants.R_OK).then(() => true, () => false);
+        if (present)
+            return { rehydrated: false, reason: "already-present" };
+    }
+    const records = (await listArchives(dataDir)).filter((record) => record.version === 2);
+    const byPath = wanted ? records.filter((record) => record.source.path === wanted) : [];
+    const byName = byPath.length > 0 ? byPath
+        : wanted ? records.filter((record) => basename(record.source.path) === basename(wanted)) : [];
+    const bySession = byName.length > 0 ? byName
+        : target.sessionId ? records.filter((record) => basename(record.source.path).includes(target.sessionId)) : [];
+    if (bySession.length === 0)
+        return { rehydrated: false, reason: "not-archived" };
+    const newest = bySession.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))[0];
+    // If the match came by name and the file exists at ITS recorded path, the
+    // catalog and the disk already agree — nothing to do.
+    if (!wanted || newest.source.path !== wanted) {
+        const there = await access(newest.source.path, constants.R_OK).then(() => true, () => false);
+        if (there)
+            return { rehydrated: false, reason: "already-present" };
+    }
+    if (!phrase)
+        return { rehydrated: false, reason: "no-phrase", note: "No recovery phrase is available to this machine (keystore or VAULTLINE_RECOVERY_PHRASE), so the sealed copy stays sealed." };
+    try {
+        const outcome = await restoreArchive(dataDir, newest.id, phrase, { native: true, overwrite: "refuse", home: options.home });
+        await recordAudit(dataDir, "archive.restore", "allowed", { archiveId: newest.id, path: outcome.output, rehydrated: true });
+        return { rehydrated: true, archiveId: newest.id, output: outcome.output, bytes: outcome.bytes };
+    }
+    catch (error) {
+        return { rehydrated: false, reason: "restore-failed", note: error instanceof Error ? error.message.split("\n")[0] : "restore failed" };
+    }
+}
+/**
+ * Lenient hook-payload reading, distinct from `hookEventFromStdin` on purpose:
+ * that parser refuses when the transcript is unreadable, and an ABSENT
+ * transcript is this feature's entire subject.
+ */
+export function rehydrateTargetFromPayload(stdin) {
+    try {
+        const payload = JSON.parse(stdin);
+        const pick = (keys) => {
+            for (const key of keys) {
+                const value = payload[key];
+                if (typeof value === "string" && value.trim())
+                    return value.trim();
+            }
+            return undefined;
+        };
+        return {
+            path: pick(["transcript_path", "transcriptPath", "rollout_path", "rolloutPath"]),
+            sessionId: pick(["session_id", "sessionId", "conversation_id", "thread_id"])
+        };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/restore.d.ts

@@ -0,0 +1,34 @@
+import type { AgentId } from "./adapters.js";
+import type { ArchiveRecord } from "./types.js";
+export type OverwritePolicy = "refuse" | "backup" | "replace";
+export type RestoreOptions = {
+    destination?: string;
+    native?: boolean;
+    overwrite?: OverwritePolicy;
+    home?: string;
+};
+export type RestoreOutcome = {
+    record: ArchiveRecord;
+    output: string;
+    bytes: number;
+    native: boolean;
+    backupPath?: string;
+};
+/**
+ * Where each adapter's transcripts legitimately live. Restoring "natively" means
+ * putting bytes back at the recorded original path, and only if that path is still
+ * inside the agent's own root — never anywhere else on the filesystem.
+ */
+export declare const NATIVE_ROOTS: Record<AgentId, (home: string) => string[]>;
+/** Resolves the adapter-native destination, refusing anything outside the agent's roots. */
+export declare function nativeRestoreTarget(record: ArchiveRecord, home?: string): string;
+/**
+ * Restores one archive atomically.
+ *
+ * The plaintext is streamed to a temporary file beside the destination and renamed
+ * into place, so a crash never leaves a half-written transcript — and a transcript
+ * of any size is restored without ever holding it in memory. An existing file
+ * is refused by default; `backup` preserves it beside the restored copy and
+ * `replace` is the only policy that discards it.
+ */
+export declare function restoreArchive(dataDir: string, id: string, phrase: string, options?: RestoreOptions): Promise<RestoreOutcome>;

package/dist/src/restore.js

@@ -0,0 +1,80 @@
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { assertPhraseOpens, findArchive, readConfig, restoreRecordToFile } from "./vault.js";
+/**
+ * Where each adapter's transcripts legitimately live. Restoring "natively" means
+ * putting bytes back at the recorded original path, and only if that path is still
+ * inside the agent's own root — never anywhere else on the filesystem.
+ */
+export const NATIVE_ROOTS = {
+    codex: (home) => [join(home, ".codex", "sessions"), join(home, ".codex", "archived_sessions")],
+    claude: (home) => [join(home, ".claude", "projects")]
+};
+function within(candidate, root) {
+    const target = resolve(candidate);
+    const base = resolve(root);
+    return target === base || target.startsWith(base.endsWith(sep) ? base : base + sep);
+}
+/** Resolves the adapter-native destination, refusing anything outside the agent's roots. */
+export function nativeRestoreTarget(record, home = homedir()) {
+    const agent = record.source.agent;
+    if (agent !== "codex" && agent !== "claude") {
+        fail("native_restore_unavailable", `No native restore path is defined for agent "${agent}"; pass an explicit destination`, { agent });
+    }
+    const roots = NATIVE_ROOTS[agent](home);
+    const original = resolve(record.source.path);
+    if (!roots.some((root) => within(original, root))) {
+        fail("path_not_permitted", `Recorded source ${original} is not inside a ${agent} transcript root; pass an explicit destination`, { agent, roots });
+    }
+    return original;
+}
+/**
+ * Restores one archive atomically.
+ *
+ * The plaintext is streamed to a temporary file beside the destination and renamed
+ * into place, so a crash never leaves a half-written transcript — and a transcript
+ * of any size is restored without ever holding it in memory. An existing file
+ * is refused by default; `backup` preserves it beside the restored copy and
+ * `replace` is the only policy that discards it.
+ */
+export async function restoreArchive(dataDir, id, phrase, options = {}) {
+    const record = await findArchive(dataDir, id);
+    const native = options.native === true;
+    if (native && options.destination)
+        fail("invalid_argument", "Choose either --native or an explicit destination, not both");
+    if (!native && !options.destination)
+        fail("invalid_argument", "A destination is required unless --native is used");
+    const output = native ? nativeRestoreTarget(record, options.home ?? homedir()) : resolve(options.destination);
+    const policy = options.overwrite ?? "refuse";
+    const existing = await stat(output).then(() => true).catch(() => false);
+    if (existing && policy === "refuse") {
+        fail("destination_exists", `${output} already exists. Re-run with --overwrite backup to keep it, or --overwrite replace to discard it.`, { destination: output });
+    }
+    // Proved before anything is created, because the restore itself writes as it
+    // decrypts: a wrong phrase must not leave a directory or a partial file
+    // behind. The config decides what "proved" means — unwrapping for a sealed
+    // vault, the identity check for a plain one.
+    assertPhraseOpens(await readConfig(dataDir), record, phrase);
+    await mkdir(dirname(output), { recursive: true });
+    const temp = join(dirname(output), `.${basename(output)}.${randomUUID()}.partial`);
+    let backupPath;
+    let bytes;
+    try {
+        ({ bytes } = await restoreRecordToFile(dataDir, record, phrase, temp));
+        if (existing && policy === "backup") {
+            backupPath = `${output}.vaultline-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+            await rename(output, backupPath);
+        }
+        await rename(temp, output);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+    await recordAudit(dataDir, "archive.restore", "allowed", { archiveId: id, output, bytes, native, backedUp: Boolean(backupPath) });
+    return { record, output, bytes, native, backupPath };
+}

package/dist/src/retention.d.ts

@@ -0,0 +1,251 @@
+import { type ActivityOptions } from "./activity.js";
+import { type TrashResult } from "./trash.js";
+import { type VaultConfig } from "./types.js";
+export type RetentionPolicy = "local-only" | "sync-only" | "archive-and-reclaim" | "manual-approval";
+export type RetentionSettings = {
+    policy: RetentionPolicy;
+    olderThanDays: number;
+    graceDays: number;
+    /**
+     * How long an *archive* is kept before it may be deleted from storage.
+     * `null` means never — and that is the default, because the surprising
+     * outcome for an archive tool is losing an archive, not keeping one.
+     */
+    deleteAfterDays: number | null;
+    /**
+     * How long a *session* must have gone untouched before its bytes are taken.
+     *
+     * `olderThanDays` above measures the archive, which answers "how long has
+     * this been safely backed up" — a question about us. This one measures the
+     * transcript's own last-modified time, which answers "when did I last care
+     * about this", the question people actually ask when deciding what to throw
+     * away. They are different: a session archived two months ago that you
+     * reopened this morning is old by the first measure and current by this one.
+     *
+     * `null` means the source's own age is not considered.
+     */
+    sourceIdleDays: number | null;
+    /**
+     * Don't bother reclaiming sources smaller than this.
+     *
+     * Disk problems are not evenly distributed. A real machine here held 78 GB
+     * across 303 sessions, of which forty were over a gigabyte and 359 were under
+     * ten megabytes — so almost all the pain sat in a handful of files, and
+     * churning through hundreds of tiny ones buys nothing but risk and noise.
+     *
+     * `null` means every size is a candidate.
+     */
+    minSourceBytes: number | null;
+};
+export declare const DEFAULT_RETENTION: RetentionSettings;
+export declare const POLICIES: readonly RetentionPolicy[];
+export type Candidate = {
+    id: string;
+    agent: string;
+    path: string;
+    bytes: number;
+    createdAt: string;
+    eligible: boolean;
+    /** Every reason this source is still protected. Empty exactly when eligible. */
+    blockers: string[];
+    reason: string;
+    /** The one fact the table leads with: a verified cloud copy, or nothing. */
+    remote: {
+        provider: string;
+        verifiedAt: string;
+    } | null;
+};
+export type RetentionOptions = {
+    olderThanDays?: number;
+    now?: number;
+    activity?: ActivityOptions;
+    settings?: Partial<RetentionSettings>;
+};
+export declare function retentionSettings(config: VaultConfig, overrides?: Partial<RetentionSettings>): RetentionSettings;
+export declare function readApprovals(dataDir: string): Promise<string[]>;
+/** Manual-approval policy: an operator names the archives whose sources may be reclaimed. */
+export declare function approveReclamation(dataDir: string, archiveIds: string[]): Promise<string[]>;
+/**
+ * Decides, per archive, whether its local source may be reclaimed.
+ *
+ * Every gate is evaluated and all failures are reported, so an operator sees the
+ * complete reason a file is protected rather than the first one that matched.
+ */
+export declare function evaluateRetention(dataDir: string, options?: RetentionOptions): Promise<{
+    mode: "preview";
+    policy: RetentionPolicy;
+    olderThanDays: number;
+    graceDays: number;
+    sourceIdleDays: number | null;
+    minSourceBytes: number | null;
+    deleteAfterDays: number | null;
+    reclaimableBytes: number;
+    candidates: Candidate[];
+}>;
+export type ReclaimOutcome = {
+    id: string;
+    path: string;
+    bytes: number;
+    movedTo: string;
+    strategy: TrashResult["strategy"];
+};
+/**
+ * Reclaims eligible sources. Dry-run is the default: without `confirm`, nothing on
+ * disk changes. Reclaimed files go to the OS trash, never to `unlink`.
+ */
+export declare function applyRetention(dataDir: string, options?: RetentionOptions & {
+    confirm?: boolean;
+    home?: string;
+    strategy?: TrashResult["strategy"];
+}): Promise<{
+    mode: "dry-run";
+    policy: RetentionPolicy;
+    wouldReclaim: number;
+    wouldFreeBytes: number;
+    candidates: Candidate[];
+    reclaimed?: undefined;
+    failed?: undefined;
+    freedBytes?: undefined;
+    protected?: undefined;
+} | {
+    mode: "apply";
+    policy: RetentionPolicy;
+    reclaimed: ReclaimOutcome[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    freedBytes: number;
+    protected: number;
+    wouldReclaim?: undefined;
+    wouldFreeBytes?: undefined;
+    candidates?: undefined;
+}>;
+/**
+ * Reclaims ONE source, because a person pointed at it.
+ *
+ * The automatic pass (`applyRetention`) obeys every rule: policy, age, grace,
+ * idle, size floor, manual approval. Those rules exist so the machine acting
+ * on its own is conservative. A person clicking one row after checking its
+ * cloud copy IS the approval — so this path keeps only the gates that protect
+ * against actual data loss, and says which one refused when it refuses:
+ *
+ *  - the archive must have a verified remote copy (and a delta head's whole
+ *    chain must be verified — one unverified base and the cloud cannot
+ *    reproduce the file this is about to trash);
+ *  - the source must be byte-for-byte the file that was archived — a session
+ *    that grew since has content in no archive at all;
+ *  - nothing may have the file open right now.
+ *
+ * Policy, age and grace are deliberately not consulted. Trash, never unlink,
+ * same as everywhere.
+ */
+export declare function reclaimOne(dataDir: string, archiveId: string, options?: {
+    confirm?: boolean;
+    home?: string;
+    strategy?: TrashResult["strategy"];
+    now?: number;
+    activity?: ActivityOptions;
+}): Promise<ReclaimOutcome>;
+/**
+ * `reclaimOne` over a selection. Each row passes or is kept with its reason —
+ * one refusal never blocks the rest, and the reasons come back in the same
+ * sentences the single path speaks.
+ */
+export declare function reclaimBatch(dataDir: string, ids: readonly string[], options?: {
+    confirm?: boolean;
+    home?: string;
+    strategy?: TrashResult["strategy"];
+    now?: number;
+    activity?: ActivityOptions;
+}): Promise<{
+    reclaimed: ReclaimOutcome[];
+    kept: {
+        id: string;
+        reason: string;
+    }[];
+    freedBytes: number;
+}>;
+export declare function setRetentionPolicy(dataDir: string, settings: Partial<RetentionSettings>): Promise<VaultConfig>;
+export type RedundantArchive = {
+    id: string;
+    agent: string;
+    path: string;
+    /** Bytes this snapshot occupies in storage — what removing it would give back. */
+    storedBytes: number;
+    createdAt: string;
+    /** The newer archive that already contains every byte this one holds. */
+    supersededBy: string;
+    objectPath: string;
+};
+/**
+ * Snapshots whose every byte is already inside a newer archive of the same file.
+ *
+ * Agent transcripts are append-only, so a session archived while it was still
+ * growing leaves a trail: a 1 GB snapshot, then a 2 GB one, then the finished
+ * 3.8 GB. Each is complete and standalone — that is what makes them safe — but
+ * it also makes the earlier ones pure duplication, because the newest archive
+ * already reproduces every byte they hold. `supersedes` recorded this from the
+ * beginning and nothing ever read it, so the trail was kept forever and, on
+ * metered storage, paid for forever.
+ *
+ * Nothing is deleted here. Deleting an archive is the one action that cannot be
+ * undone from somewhere else, and the product's promise is that it reports what
+ * could go and never acts alone. Two conditions are required before a snapshot
+ * is even *offered*: the superseding archive's object must still exist, and,
+ * where remote storage is configured, it must be verified there. A redundant
+ * copy is only redundant while the copy that replaced it is real.
+ */
+export declare function redundantArchives(dataDir: string): Promise<{
+    redundant: RedundantArchive[];
+    reclaimableBytes: number;
+    kept: number;
+}>;
+/**
+ * Removes snapshots that `redundantArchives` has already proved duplicate.
+ *
+ * A dry run unless confirmed, like every other destructive path here. The list
+ * is recomputed rather than accepted from a caller, so a stale page cannot ask
+ * for the deletion of something that has since become the last copy.
+ */
+export declare function pruneRedundantArchives(dataDir: string, options?: {
+    confirm?: boolean;
+}): Promise<{
+    mode: "preview";
+    removed: never[];
+    wouldRemove: RedundantArchive[];
+    freedBytes: number;
+    failed?: undefined;
+} | {
+    mode: "apply";
+    removed: RedundantArchive[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    freedBytes: number;
+    wouldRemove?: undefined;
+}>;
+export type ExpiredArchive = {
+    id: string;
+    agent: string;
+    path: string;
+    bytes: number;
+    createdAt: string;
+    ageDays: number;
+    objectPath: string;
+};
+/**
+ * Archives whose retention period has run out.
+ *
+ * This only ever *reports*. Deleting an archive is the one action in Sealkeep
+ * that cannot be undone by restoring from somewhere else — the archive is the
+ * last copy once the source has been reclaimed — so the decision to act on this
+ * list stays with an explicit command, and `deleteAfterDays: null` (never) is
+ * the default.
+ */
+export declare function expiredArchives(dataDir: string, options?: RetentionOptions): Promise<{
+    settings: RetentionSettings;
+    expired: ExpiredArchive[];
+    keptForever: number;
+}>;