sealkeep 0.9.0 → 0.11.0

package/dist/src/durable-ticket-lock.js

@@ -0,0 +1,232 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, readdir, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+const CLAIM_NAME = /^(\d{20})\.json$/;
+const MAX_TICKET = BigInt("99999999999999999999");
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function codedError(message, code) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function ensureDirectory(path) {
+    const created = await mkdir(path, { recursive: true, mode: 0o700 });
+    if (created) {
+        await syncDirectory(dirname(resolve(created)));
+        await syncDirectory(path);
+    }
+}
+async function publishJsonExclusive(path, value) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await link(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function replaceJsonDurably(path, value) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+function parseClaim(raw, expectedTicket) {
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1
+            || typeof value.ticket !== "string"
+            || !/^\d{20}$/.test(value.ticket)
+            || (expectedTicket !== undefined && value.ticket !== expectedTicket)
+            || typeof value.token !== "string"
+            || typeof value.pid !== "number"
+            || !Number.isSafeInteger(value.pid)
+            || value.pid <= 0
+            || typeof value.resource !== "string"
+            || typeof value.createdAt !== "string"
+            || (value.state !== "waiting" && value.state !== "released"))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+}
+async function wait(ms, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolveWait, reject) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            signal?.removeEventListener("abort", abort);
+            resolveWait();
+        }
+        function abort() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(signal?.reason ?? codedError("Lock acquisition aborted", "ABORT_ERR"));
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+async function allocateClaim(queuePath, resource) {
+    for (;;) {
+        const names = await readdir(queuePath);
+        let maximum = 0n;
+        for (const name of names) {
+            const match = CLAIM_NAME.exec(name);
+            if (match)
+                maximum = maximum > BigInt(match[1]) ? maximum : BigInt(match[1]);
+        }
+        const next = maximum + 1n;
+        if (next > MAX_TICKET)
+            throw codedError(`Lock ticket space exhausted for ${resource}`, "DURABLE_LOCK_EXHAUSTED");
+        const ticket = next.toString().padStart(20, "0");
+        const path = join(queuePath, `${ticket}.json`);
+        const wire = {
+            version: 1,
+            ticket,
+            token: randomUUID(),
+            pid: process.pid,
+            resource,
+            createdAt: new Date().toISOString(),
+            state: "waiting",
+        };
+        try {
+            await publishJsonExclusive(path, wire);
+            return { path, wire };
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+        }
+    }
+}
+/**
+ * Cross-process FIFO lock without stale-owner unlink.
+ *
+ * Every contender atomically allocates a monotonically increasing immutable
+ * ticket. Released and dead-owner tickets stay as tiny tombstones, so no later
+ * process can recreate an older pathname or race a compare-then-unlink stale
+ * takeover. A dead process is skipped by later tickets; a malformed earlier
+ * ticket fails closed until an operator repairs it.
+ */
+export async function acquireDurableTicketLock(requestedQueuePath, resource, options = {}) {
+    const queuePath = resolve(requestedQueuePath);
+    const timeoutMs = Math.max(1, options.timeoutMs ?? 5_000);
+    const pollMs = Math.max(1, options.pollMs ?? 25);
+    const alive = options.isProcessAlive ?? processIsAlive;
+    const started = Date.now();
+    await ensureDirectory(queuePath);
+    const claim = await allocateClaim(queuePath, resource);
+    let released = false;
+    const release = async () => {
+        if (released)
+            return;
+        const current = parseClaim(await readFile(claim.path, "utf8").catch(() => ""), claim.wire.ticket);
+        if (!current || current.token !== claim.wire.token || current.resource !== resource) {
+            throw codedError(`Durable lock claim changed unexpectedly: ${claim.path}`, "DURABLE_LOCK_CONFLICT");
+        }
+        if (current.state !== "released") {
+            await replaceJsonDurably(claim.path, {
+                ...current,
+                state: "released",
+                releasedAt: new Date().toISOString(),
+            });
+        }
+        released = true;
+    };
+    try {
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const own = parseClaim(await readFile(claim.path, "utf8").catch(() => ""), claim.wire.ticket);
+            if (!own || own.token !== claim.wire.token || own.resource !== resource || own.state !== "waiting") {
+                throw codedError(`Durable lock claim ownership was lost: ${claim.path}`, "DURABLE_LOCK_CONFLICT");
+            }
+            const names = (await readdir(queuePath)).filter((name) => CLAIM_NAME.test(name)).sort();
+            let blocked = false;
+            for (const name of names) {
+                const ticket = name.slice(0, 20);
+                if (ticket >= claim.wire.ticket)
+                    break;
+                const prior = parseClaim(await readFile(join(queuePath, name), "utf8").catch(() => ""), ticket);
+                // A malformed ticket might be a durability fault in a live owner. It
+                // cannot be skipped safely, so acquisition times out without mutation.
+                if (!prior || (prior.state === "waiting" && await alive(prior.pid))) {
+                    blocked = true;
+                    break;
+                }
+            }
+            if (!blocked)
+                break;
+            if (Date.now() - started >= timeoutMs) {
+                throw codedError(`Timed out waiting for durable lock: ${resource}`, "DURABLE_LOCK_TIMEOUT");
+            }
+            await wait(Math.min(pollMs, Math.max(1, timeoutMs - (Date.now() - started))), options.signal);
+        }
+        return {
+            queuePath,
+            claimPath: claim.path,
+            ticket: claim.wire.ticket,
+            token: claim.wire.token,
+            assertOwned: async () => {
+                if (released)
+                    throw codedError(`Durable lock was already released: ${resource}`, "DURABLE_LOCK_CONFLICT");
+                const current = parseClaim(await readFile(claim.path, "utf8").catch(() => ""), claim.wire.ticket);
+                if (!current || current.token !== claim.wire.token || current.resource !== resource || current.state !== "waiting") {
+                    throw codedError(`Durable lock ownership was lost: ${resource}`, "DURABLE_LOCK_CONFLICT");
+                }
+            },
+            release,
+        };
+    }
+    catch (error) {
+        await release().catch(() => undefined);
+        throw error;
+    }
+}

package/dist/src/enroll.d.ts

@@ -1,7 +1,7 @@
 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. */
+    /** The short-lived code shown in the account panel under Machines > Show a pairing code. */
     code: string;
     /** How this machine will show up in the device list. */
     label: string;

package/dist/src/enroll.js

@@ -1,7 +1,7 @@
 import { fail } from "./errors.js";
 import { chooseBackend } from "./secrets.js";
 import { readConfig } from "./vault.js";
-import { DEFAULT_CLOUD_URL, tokenRefFor } from "./cloud.js";
+import { commitCloudAuthCredentials, 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";
 /**
@@ -58,7 +58,7 @@ 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.");
+        fail("invalid_argument", "An enrollment code is required. Find it in the account panel under Machines > Show a pairing code.");
     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,
@@ -97,11 +97,17 @@ export async function enroll(dataDir, options) {
         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);
+    // Publish the token and its cache generation as one fail-closed transition.
+    // The pairing code is single-use, so a full disk must be detected before the
+    // credential changes; otherwise the machine could retain the new account
+    // under the previous account's cache scope.
+    await commitCloudAuthCredentials(dataDir, backend, [{ ref, value: enrolled.token }]);
+    // Claim a machine identity too. Without it this machine can seal and upload
+    // but cannot delete anything another machine sealed, because the control
+    // plane has no way to tell it apart from every other laptop on the account.
+    // Best-effort: enrolment succeeding matters more than being nameable.
+    const { registerMachine } = await import("./cloud.js");
+    await registerMachine(dataDir, enrolled.token);
     let settingsCached = true;
     let cacheWarning;
     let sync;

package/dist/src/env.d.ts

@@ -6,8 +6,17 @@
  * break because we renamed a brand — but everything the product prints, writes,
  * and documents now says SEALKEEP_. When both are set the new name wins, so a
  * machine can be migrated one variable at a time.
+ *
+ * This fallback was deleted once, on the reasoning that one machine had no
+ * VAULTLINE_ variables set. That reasoning was wrong twice over: it generalised
+ * from a single machine, and it missed that `mcp install` WROTE the old names
+ * into agent config files that are still on disk. An agent spawned from one of
+ * those configs would have silently ignored its own configured vault and used
+ * the default instead — two vaults, no error, which is the exact failure this
+ * product has an acceptance test for.
  */
-/** Reads `SEALKEEP_<name>`, falling back to the Vaultline-era name. */
+export declare const PREFIX = "SEALKEEP_";
+/** Reads `SEALKEEP_<name>`, falling back to the Vaultline-era spelling. */
 export declare function envVar(name: string, env?: NodeJS.ProcessEnv): string | undefined;
 /** True when either spelling is set to something truthy. */
 export declare function envFlag(name: string, env?: NodeJS.ProcessEnv): boolean;

package/dist/src/env.js

@@ -6,16 +6,24 @@
  * break because we renamed a brand — but everything the product prints, writes,
  * and documents now says SEALKEEP_. When both are set the new name wins, so a
  * machine can be migrated one variable at a time.
+ *
+ * This fallback was deleted once, on the reasoning that one machine had no
+ * VAULTLINE_ variables set. That reasoning was wrong twice over: it generalised
+ * from a single machine, and it missed that `mcp install` WROTE the old names
+ * into agent config files that are still on disk. An agent spawned from one of
+ * those configs would have silently ignored its own configured vault and used
+ * the default instead — two vaults, no error, which is the exact failure this
+ * product has an acceptance test for.
  */
+export const PREFIX = "SEALKEEP_";
 const LEGACY_PREFIX = "VAULTLINE_";
-const PREFIX = "SEALKEEP_";
-/** Reads `SEALKEEP_<name>`, falling back to the Vaultline-era name. */
+/** Reads `SEALKEEP_<name>`, falling back to the Vaultline-era spelling. */
 export function envVar(name, env = process.env) {
     const current = env[PREFIX + name];
     if (current !== undefined && current !== "")
         return current;
     const legacy = env[LEGACY_PREFIX + name];
-    return legacy === "" ? undefined : legacy;
+    return legacy === undefined || legacy === "" ? undefined : legacy;
 }
 /** True when either spelling is set to something truthy. */
 export function envFlag(name, env = process.env) {

package/dist/src/errors.d.ts

@@ -3,24 +3,24 @@
  * between releases; these codes are a contract for the CLI, local API, and MCP.
  * Details are operational only: never place plaintext, phrases, or keys here.
  */
-export type VaultlineErrorCode = "invalid_argument" | "vault_not_initialized" | "vault_already_initialized" | "config_unsupported_version" | "recovery_phrase_missing" | "recovery_phrase_mismatch" | "archive_not_found" | "source_unreadable" | "destination_exists" | "destination_unwritable" | "insufficient_disk_space" | "path_not_permitted" | "native_restore_unavailable" | "ciphertext_integrity_failed" | "plaintext_integrity_failed" | "hook_payload_invalid" | "queue_job_not_found" | "queue_lease_invalid" | "queue_lease_expired" | "queue_job_exhausted" | "storage_not_configured" | "provider_unsupported" | "signer_not_configured" | "lease_expired" | "unauthorized" | "forbidden" | "internal";
-export declare class VaultlineError extends Error {
-    readonly code: VaultlineErrorCode;
+export type SealkeepErrorCode = "invalid_argument" | "vault_not_initialized" | "vault_already_initialized" | "config_unsupported_version" | "recovery_phrase_missing" | "recovery_phrase_mismatch" | "recipient_key_mismatch" | "payment_required" | "archive_not_found" | "source_unreadable" | "destination_exists" | "destination_unwritable" | "insufficient_disk_space" | "scratch_space_busy" | "path_not_permitted" | "native_restore_unavailable" | "ciphertext_integrity_failed" | "plaintext_integrity_failed" | "hook_payload_invalid" | "queue_job_not_found" | "queue_lease_invalid" | "queue_lease_expired" | "queue_job_exhausted" | "daemon_already_running" | "storage_not_configured" | "storage_read_timeout" | "operation_timeout" | "cloud_account_unavailable" | "provider_unsupported" | "signer_not_configured" | "lease_expired" | "upload_incomplete" | "team_state_changed" | "team_membership_revoked" | "rate_limited" | "unauthorized" | "forbidden" | "internal";
+export declare class SealkeepError extends Error {
+    readonly code: SealkeepErrorCode;
     readonly details: Record<string, unknown>;
-    constructor(code: VaultlineErrorCode, message: string, details?: Record<string, unknown>);
+    constructor(code: SealkeepErrorCode, message: string, details?: Record<string, unknown>);
     toJSON(): {
         error: {
-            code: VaultlineErrorCode;
+            code: SealkeepErrorCode;
             message: string;
         };
     };
 }
-export declare function fail(code: VaultlineErrorCode, message: string, details?: Record<string, unknown>): never;
-export declare function isVaultlineError(value: unknown): value is VaultlineError;
+export declare function fail(code: SealkeepErrorCode, message: string, details?: Record<string, unknown>): never;
+export declare function isSealkeepError(value: unknown): value is SealkeepError;
 /** Safe wire/log shape. Unknown failures are never echoed with a stack. */
 export declare function errorPayload(error: unknown): {
     error: {
-        code: VaultlineErrorCode;
+        code: SealkeepErrorCode;
         message: string;
     };
 };

package/dist/src/errors.js

@@ -1,23 +1,23 @@
-export class VaultlineError extends Error {
+export class SealkeepError extends Error {
     code;
     details;
     constructor(code, message, details = {}) {
         super(message);
-        this.name = "VaultlineError";
+        this.name = "SealkeepError";
         this.code = code;
         this.details = details;
     }
     toJSON() { return { error: { code: this.code, message: this.message, ...this.details } }; }
 }
 export function fail(code, message, details) {
-    throw new VaultlineError(code, message, details);
+    throw new SealkeepError(code, message, details);
 }
-export function isVaultlineError(value) {
-    return value instanceof VaultlineError;
+export function isSealkeepError(value) {
+    return value instanceof SealkeepError;
 }
 /** Safe wire/log shape. Unknown failures are never echoed with a stack. */
 export function errorPayload(error) {
-    if (isVaultlineError(error))
+    if (isSealkeepError(error))
         return error.toJSON();
     return { error: { code: "internal", message: error instanceof Error ? error.message : "Unexpected error" } };
 }

package/dist/src/flush.d.ts

@@ -0,0 +1,12 @@
+import { type FileHandle } from "node:fs/promises";
+/** Flags that reject a symlink where a regular file is expected. */
+export declare const FLUSH_NO_FOLLOW: number;
+export type FlushHandle = {
+    handle: FileHandle;
+    writable: boolean;
+};
+/**
+ * A handle suitable for `handle.sync()`. `extraFlags` carries the caller's own
+ * guards (typically `FLUSH_NO_FOLLOW`); pass 0 for none.
+ */
+export declare function openForFlush(path: string, extraFlags?: number): Promise<FlushHandle>;

package/dist/src/flush.js

@@ -0,0 +1,37 @@
+/**
+ * Opening a file in order to flush it.
+ *
+ * `fsync` on POSIX works through any descriptor, so durability code here used
+ * to open read-only — often with `O_NOFOLLOW`, because the thing being made
+ * durable must be the exact file that was just written and never a symlink
+ * planted in its place. Windows implements the same call as
+ * FlushFileBuffers, which requires write access: every one of those flushes
+ * failed there with EPERM, and with them every archive record write, every
+ * reclaim transaction and the Codex resume pointer.
+ *
+ * So: ask for write access, keep the caller's guard flags, and fall back to a
+ * read-only handle when the file genuinely cannot be opened for writing (a
+ * restored archive made read-only, a read-only mount). On POSIX the fallback
+ * still flushes; on Windows nothing more can be done for such a file, and a
+ * caller that must not silently lose durability checks the returned mode.
+ */
+import { constants as fsConstants } from "node:fs";
+import { open } from "node:fs/promises";
+const NO_FOLLOW = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+/** Flags that reject a symlink where a regular file is expected. */
+export const FLUSH_NO_FOLLOW = NO_FOLLOW;
+/**
+ * A handle suitable for `handle.sync()`. `extraFlags` carries the caller's own
+ * guards (typically `FLUSH_NO_FOLLOW`); pass 0 for none.
+ */
+export async function openForFlush(path, extraFlags = 0) {
+    try {
+        return { handle: await open(path, fsConstants.O_RDWR | extraFlags), writable: true };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "EACCES" && code !== "EPERM" && code !== "EROFS" && code !== "EISDIR")
+            throw error;
+        return { handle: await open(path, fsConstants.O_RDONLY | extraFlags), writable: false };
+    }
+}

package/dist/src/heartbeat.d.ts

@@ -1,5 +1,5 @@
 import type { UploadOptions, UploadOutcome } from "./upload.js";
-import type { offloadArchives } from "./offload.js";
+import type { FetchClient, offloadArchives } from "./offload.js";
 /**
  * The background service's sign of life.
  *
@@ -18,17 +18,69 @@ export type Heartbeat = {
     intervalMs: number;
     totals: {
         archived: number;
+        indexed?: number;
         uploaded: number;
         reclaimed: number;
         failed: number;
     };
     last: {
         archived: number;
+        indexed?: number;
         uploaded: number;
         reclaimed: number;
         failed: number;
         notes: string[];
     };
+    /** What this running build can do; absent on heartbeats written by older versions. */
+    capabilities?: {
+        uploads: boolean;
+        reclaim: boolean;
+    };
+    /** Derived search catch-up state; optional for heartbeats written by older versions. */
+    indexing?: {
+        state: "idle" | "building" | "retry-wait";
+        /** Current build attempt, or consecutive failed attempts while waiting. */
+        attempts: number;
+        startedAt?: string;
+        nextAttemptAt?: string;
+        /** Stable error name/code only — never an exception message or secret. */
+        lastError?: string;
+    };
+    /** Cloud access requests are independent of archive preservation. */
+    teamAccess?: {
+        state: "idle" | "working" | "attention";
+        failures: number;
+        lastAttemptAt?: string;
+        lastSuccessAt?: string;
+        /** Stable error code only; never an exception message, path, or token. */
+        lastError?: string;
+    };
+    /**
+     * The automatic recall lane (hook-context passes). Hooks fail open by
+     * design, so this is the one place a person can see that recall is dying
+     * instead of merely absent.
+     */
+    context?: {
+        state: "idle" | "working" | "attention";
+        /** Consecutive failed passes; reset by the next success. */
+        failures: number;
+        lastAttemptAt?: string;
+        lastSuccessAt?: string;
+        /** Stable reason only: stalled, absolute, or an error code; never request contents. */
+        lastError?: string;
+    };
+    /** Existing private history becoming usable by a newly connected team. */
+    backfill?: {
+        state: "idle" | "working" | "attention";
+        total: number;
+        indexed: number;
+        registered: number;
+        pending: number;
+        failed: number;
+        blocked: number;
+        /** Stable error name/code only; archive content and paths never appear. */
+        lastError?: string;
+    };
     paused: boolean;
     watching: string[];
 };
@@ -63,27 +115,49 @@ export type UploadOffloadOutcome = {
     offloaded: string[];
     /** Local bytes given back by offloading verified copies as the pass went. */
     freedBytes: number;
+    /** Missed managed team grants recovered after the upload loop. */
+    teamRegistered: number;
 };
+type ArchiveCacheSweepOutcome = {
+    offloaded: string[];
+    freedBytes: number;
+};
+/**
+ * Gives the daemon a bounded, retry-cooled cleanup lane for encrypted local
+ * duplicates. This runs even when the upload backlog is empty, so a service
+ * upgrade or an earlier provider outage cannot strand old `.skarchive` files.
+ */
+export declare function sweepExpiredArchiveCache(dataDir: string, options: {
+    cacheDays: number | null;
+    offload?: typeof offloadArchives;
+    maxArchives?: number;
+    now?: number;
+    freshlyVerified?: ReadonlySet<string>;
+    signal?: AbortSignal;
+    client?: FetchClient;
+    maxBytesPerSecond?: number;
+}): Promise<ArchiveCacheSweepOutcome>;
 /**
  * The daemon's upload pass, finished properly: upload, verify, then offload.
  *
  * `uploadPending` alone leaves a sealed local copy of every archive it just
- * proved the bucket holds — on the machines this product is for, that is the
- * disk staying exactly as full as before. The dashboard's push already does
- * the whole job (see `runUploads` in local-api.ts): the moment an archive's
- * verify lands, its local blob is a duplicate, and offloading it right then
- * lets a full disk breathe with each verify instead of never.
+ * proved the bucket holds — on the machines this product is for, that cache
+ * must not grow forever. The visible per-machine cache setting decides when a
+ * verified duplicate leaves; a value of zero completes that cleanup in this
+ * same pass.
  *
  * Offload failure is tolerated per archive: the upload is still verified and
- * recorded, and the next offload sweep gets another chance. `freshlyVerified`
- * is what keeps this cheap — the verify happened milliseconds ago, so the
- * usual fetch-and-hash re-proof would double the egress of every push.
+ * recorded, and a bounded, backed-off sweep gets another chance. A fresh
+ * verify still receives one final streamed whole-chain proof at the actual
+ * local purge boundary when the cache setting is zero.
  *
- * Integration note: src/daemon.ts's tick still calls bare `uploadPending`;
- * switching it to this function is the remaining wiring (daemon.ts is outside
- * this change's file list).
+ * The daemon calls this combined pass so routing, remote verification, retry
+ * fairness, and reclaim all share one ordering boundary.
  */
 export declare function uploadAndOffloadPending(dataDir: string, options?: UploadOptions & {
     offload?: typeof offloadArchives;
+    maxArchives?: number;
+    maxOffloads?: number;
 }): Promise<UploadOffloadOutcome>;
 export declare function describeGap(seconds: number): string;
+export {};