sealkeep 0.5.0

package/dist/src/control-plane-cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createControlPlaneServer } from "./control-plane/server.js";
+import { defaultDataDir } from "./vault.js";
+import { freePort } from "./net.js";
+/**
+ * Runs the control plane.
+ *
+ * Authentication is on by default. `VAULTLINE_CONTROL_PLANE_DEV=1` turns it off for
+ * local interface work and the banner says so loudly, because an unauthenticated
+ * instance reachable from a network would let anyone enumerate account metadata.
+ */
+const development = process.env.VAULTLINE_CONTROL_PLANE_DEV === "1";
+const storePath = process.env.VAULTLINE_CONTROL_PLANE_STORE ?? join(defaultDataDir(), "control-plane", "state.json");
+const tls = process.env.VAULTLINE_TLS_CERT && process.env.VAULTLINE_TLS_KEY
+    ? { cert: readFileSync(process.env.VAULTLINE_TLS_CERT), key: readFileSync(process.env.VAULTLINE_TLS_KEY) }
+    : undefined;
+const server = createControlPlaneServer({
+    storePath: development ? undefined : storePath,
+    requireAuth: !development,
+    tls,
+    onLog: (line) => console.log(JSON.stringify(line))
+});
+async function listen() {
+    const port = await freePort(Number(process.env.PORT ?? "8787"));
+    const host = process.env.HOST ?? "127.0.0.1";
+    server.once("error", (error) => { console.error(`Unable to start control-plane on port ${port}: ${error.message}`); process.exitCode = 1; });
+    server.listen(port, host, () => {
+        console.log(`Sealkeep control plane on ${tls ? "https" : "http"}://${host}:${port}`);
+        if (development)
+            console.log("MODE: development — device authentication is DISABLED and state is in memory. Do not expose this.");
+        else
+            console.log(`Durable state: ${storePath}${tls ? "" : "\nWARNING: no TLS configured. Set VAULTLINE_TLS_CERT and VAULTLINE_TLS_KEY before accepting non-loopback traffic."}`);
+    });
+}
+void listen();

package/dist/src/control-plane-server.d.ts

@@ -0,0 +1,10 @@
+import { createControlPlaneServer as createServer, type ControlPlaneOptions } from "./control-plane/server.js";
+/**
+ * Development interface: the same control plane with device signatures disabled and
+ * state kept in memory. It exists so local surfaces can be built against the real
+ * contract. Never deploy it — a deployment must use `createControlPlaneServer`
+ * from `src/control-plane/server.ts` with authentication left on.
+ */
+export declare function createDevelopmentControlPlane(options?: Omit<ControlPlaneOptions, "requireAuth">): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+export { createServer as createControlPlaneServer };
+export type { ControlPlaneOptions };

package/dist/src/control-plane-server.js

@@ -0,0 +1,11 @@
+import { createControlPlaneServer as createServer } from "./control-plane/server.js";
+/**
+ * Development interface: the same control plane with device signatures disabled and
+ * state kept in memory. It exists so local surfaces can be built against the real
+ * contract. Never deploy it — a deployment must use `createControlPlaneServer`
+ * from `src/control-plane/server.ts` with authentication left on.
+ */
+export function createDevelopmentControlPlane(options = {}) {
+    return createServer({ ...options, requireAuth: false });
+}
+export { createServer as createControlPlaneServer };

package/dist/src/control-plane.d.ts

@@ -0,0 +1,78 @@
+export type ProviderKind = "vaultline" | "s3" | "r2" | "b2" | "gcs" | "gdrive";
+export type ProviderConfig = {
+    provider: ProviderKind;
+    bucket: string;
+    region?: string;
+    prefix: string;
+};
+export type LeaseStatus = "pending-signer" | "active";
+export type UploadLease = {
+    archiveId: string;
+    provider: ProviderKind;
+    objectKey: string;
+    expiresAt: string;
+    /** `CREDENTIALS` delegates by scoped credential instead of by signed URL: the machine signs its own streaming requests. No signer produces it yet — see docs/managed-streaming-contract.md. */
+    method: "PUT" | "MULTIPART" | "RESUMABLE" | "CREDENTIALS";
+    uploadUrl: string;
+    requiredHeaders: Record<string, string>;
+    /**
+     * Present only when `method` is `CREDENTIALS`: a short-lived S3-compatible
+     * key scoped to this account's prefix, which the client feeds to its own
+     * `S3UploadClient` for multipart streaming with resume. Types only for now —
+     * the contract the control plane must implement is documented in
+     * docs/managed-streaming-contract.md.
+     */
+    vendedCredentials?: {
+        endpoint: string;
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+        expiresAt: string;
+    };
+    /** `pending-signer` until credential-backed signing exists. It is never `active` in this build. */
+    status: LeaseStatus;
+    uploadable: boolean;
+};
+export type LeaseInput = {
+    archiveId?: string;
+    ciphertextSha256: string;
+    bytes: number;
+    now?: number;
+    ttlMs?: number;
+};
+export declare const DEFAULT_LEASE_TTL_MS: number;
+export interface StorageLeaseProvider {
+    validate(config: ProviderConfig): void;
+    createUploadLease(config: ProviderConfig, input: LeaseInput): UploadLease;
+}
+export declare const providers: Record<ProviderKind, StorageLeaseProvider>;
+export declare function leaseExpired(lease: UploadLease, now?: number): boolean;
+/**
+ * The single gate every upload path must pass. Expiry is checked first so a
+ * replayed lease is refused as expired rather than as an unsigned lease.
+ */
+export declare function assertLeaseUsable(lease: UploadLease, now?: number): void;
+/** Feature flag for provider work in progress. Off by default and read per call so tests and operators can flip it. */
+export declare function signerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The contract a real S3/R2/GCS client will implement. Credentials belong to the
+ * signer service, never to this process, so no implementation ships in this build.
+ */
+export interface ProviderUploadClient {
+    readonly kind: ProviderKind;
+    upload(lease: UploadLease, ciphertext: Buffer): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
+    head(lease: UploadLease): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+}
+/** Registration is refused unless the operator explicitly enabled signer work. */
+export declare function registerUploadClient(client: ProviderUploadClient, env?: NodeJS.ProcessEnv): void;
+export declare function uploadClientFor(kind: ProviderKind, env?: NodeJS.ProcessEnv): ProviderUploadClient;
+/** Test and operator hook so a flag flip cannot leak state between runs. */
+export declare function clearUploadClients(): void;

package/dist/src/control-plane.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+import { fail } from "./errors.js";
+export const DEFAULT_LEASE_TTL_MS = 15 * 60_000;
+class PlannedProvider {
+    provider;
+    method;
+    constructor(provider, method) {
+        this.provider = provider;
+        this.method = method;
+    }
+    validate(config) { if (!config.bucket || !config.prefix)
+        fail("invalid_argument", "bucket and prefix are required"); }
+    createUploadLease(config, input) {
+        this.validate(config);
+        const archiveId = input.archiveId ?? randomUUID();
+        const issuedAt = input.now ?? Date.now();
+        // Deliberately non-functional until real credential-backed signers are configured.
+        return {
+            archiveId, provider: this.provider,
+            objectKey: `${config.prefix.replace(/\/$/, "")}/${archiveId}.vlarchive`,
+            expiresAt: new Date(issuedAt + (input.ttlMs ?? DEFAULT_LEASE_TTL_MS)).toISOString(),
+            method: this.method,
+            uploadUrl: `vaultline+pending://${this.provider}/${config.bucket}/${archiveId}`,
+            requiredHeaders: { "content-type": "application/vnd.vaultline.ciphertext", "x-vaultline-ciphertext-sha256": input.ciphertextSha256, "content-length": String(input.bytes) },
+            status: "pending-signer", uploadable: false
+        };
+    }
+}
+export const providers = {
+    vaultline: new PlannedProvider("vaultline", "MULTIPART"), s3: new PlannedProvider("s3", "MULTIPART"), r2: new PlannedProvider("r2", "MULTIPART"), b2: new PlannedProvider("b2", "MULTIPART"), gcs: new PlannedProvider("gcs", "RESUMABLE"), gdrive: new PlannedProvider("gdrive", "RESUMABLE")
+};
+export function leaseExpired(lease, now = Date.now()) {
+    return !(Date.parse(lease.expiresAt) > now);
+}
+/**
+ * The single gate every upload path must pass. Expiry is checked first so a
+ * replayed lease is refused as expired rather than as an unsigned lease.
+ */
+export function assertLeaseUsable(lease, now = Date.now()) {
+    if (leaseExpired(lease, now))
+        fail("lease_expired", `Upload lease for ${lease.archiveId} expired at ${lease.expiresAt}`, { archiveId: lease.archiveId, expiresAt: lease.expiresAt });
+    if (!lease.uploadable || lease.status !== "active")
+        fail("signer_not_configured", "This lease cannot upload: no credential-backed signer is configured", { provider: lease.provider, archiveId: lease.archiveId });
+}
+/** Feature flag for provider work in progress. Off by default and read per call so tests and operators can flip it. */
+export function signerEnabled(env = process.env) {
+    return env.VAULTLINE_ENABLE_SIGNER === "1";
+}
+const uploadClients = new Map();
+/** Registration is refused unless the operator explicitly enabled signer work. */
+export function registerUploadClient(client, env = process.env) {
+    if (!signerEnabled(env))
+        fail("signer_not_configured", "Set VAULTLINE_ENABLE_SIGNER=1 to register a provider upload client", { provider: client.kind });
+    uploadClients.set(client.kind, client);
+}
+export function uploadClientFor(kind, env = process.env) {
+    const client = signerEnabled(env) ? uploadClients.get(kind) : undefined;
+    return client ?? fail("signer_not_configured", `No upload client is available for ${kind}. Sealkeep cannot upload until a reviewed signer with isolated credentials exists.`, { provider: kind, signerEnabled: signerEnabled(env) });
+}
+/** Test and operator hook so a flag flip cannot leak state between runs. */
+export function clearUploadClients() { uploadClients.clear(); }

package/dist/src/crypto.d.ts

@@ -0,0 +1,56 @@
+export declare function sha256(input: Buffer): string;
+/**
+ * @deprecated Defect #49: v1's stored phrase check was one unsalted SHA-256 of
+ * the phrase -- 0.74us to evaluate, versus 67.8ms for the envelope's scrypt.
+ * Five guesses recovered a user-chosen phrase straight from config.json.
+ * Kept so `upgradeLegacyPhraseCheck` can still recognise and re-derive from an
+ * old vault's stored value; nothing should compare a live phrase against this
+ * directly any more -- use `phraseCheck` or `matchesPhraseCheck`.
+ */
+export declare function legacyPhraseCheck(phrase: string): string;
+/**
+ * Confirms a typed phrase before any archive is touched. Defect #49: replaces
+ * a single cheap SHA-256 with the same scrypt cost `recoveryKey` charges the
+ * envelope, chained on top of `legacyPhraseCheck` rather than the raw phrase.
+ * Chaining on the digest (not the phrase) is what lets `upgradeLegacyPhraseCheck`
+ * promote an old vault's stored value using nothing but that value -- no
+ * phrase required, see there.
+ */
+export declare function phraseCheck(phrase: string): string;
+/** True for a config still holding a bare v1 digest (32 bytes); false once `phraseCheck` has tagged it (33). */
+export declare function isLegacyPhraseCheck(stored: string): boolean;
+/**
+ * Promotes a v1 vault's stored digest to the v2 (cost-matched) format in
+ * place. Takes the OLD digest, not the phrase -- see `phraseCheck` -- which is
+ * what lets `readConfig` call this unconditionally on every legacy config it
+ * reads: no vault is stranded waiting on its owner to run a migration command,
+ * or even to unlock it first.
+ */
+export declare function upgradeLegacyPhraseCheck(stored: string): string;
+/** Verifies a typed phrase against a stored check, whichever format it is in. */
+export declare function matchesPhraseCheck(stored: string, phrase: string): boolean;
+export declare function equalHex(left: string, right: string): boolean;
+/** @deprecated Format v1. Retained so existing archives stay readable and migratable. */
+export declare function encryptLegacyArchive(plaintext: Buffer, phrase: string): {
+    ciphertext: Buffer<ArrayBuffer>;
+    nonce: string;
+    authTag: string;
+    wrappedKey: {
+        algorithm: "scrypt-aes-256-gcm";
+        salt: string;
+        nonce: string;
+        authTag: string;
+        ciphertext: string;
+    };
+};
+/** @deprecated Format v1 reader. New archives use `vaultline-crypto`. */
+export declare function decryptLegacyArchive(ciphertext: Buffer, envelope: {
+    nonce: string;
+    authTag: string;
+    wrappedKey: {
+        salt: string;
+        nonce: string;
+        authTag: string;
+        ciphertext: string;
+    };
+}, phrase: string): Buffer;

package/dist/src/crypto.js

@@ -0,0 +1,132 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, createHash, timingSafeEqual } from "node:crypto";
+const KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+/** Cost parameters shared by every phrase-derived key in this file: ~68ms and ~32MB per guess. */
+const SCRYPT_PARAMS = { N: 1 << 15, r: 8, p: 1, maxmem: 128 * 1024 * 1024 };
+export function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function recoveryKey(phrase, salt) {
+    return scryptSync(phrase.normalize("NFKD"), salt, KEY_BYTES, SCRYPT_PARAMS);
+}
+/**
+ * @deprecated Defect #49: v1's stored phrase check was one unsalted SHA-256 of
+ * the phrase -- 0.74us to evaluate, versus 67.8ms for the envelope's scrypt.
+ * Five guesses recovered a user-chosen phrase straight from config.json.
+ * Kept so `upgradeLegacyPhraseCheck` can still recognise and re-derive from an
+ * old vault's stored value; nothing should compare a live phrase against this
+ * directly any more -- use `phraseCheck` or `matchesPhraseCheck`.
+ */
+export function legacyPhraseCheck(phrase) {
+    return sha256(Buffer.from(`vaultline-recovery-check:v1:${phrase.normalize("NFKD")}`));
+}
+// Fixed rather than random. `vault.ts`'s archiveFile (out of scope for defect
+// #49 -- it is changing concurrently) compares a typed phrase against
+// `phraseCheck(phrase)` with no config object in hand, so there is nowhere to
+// plumb a per-vault salt through. A shared pepper cannot stop one attacker
+// amortising a table across every vault, but scrypt's memory cost still prices
+// building that table the same as attacking every vault individually would --
+// which is the actual gap this closes: config.json being *cheaper* to attack
+// than the envelope sitting right next to it, not being unsalted.
+const PHRASE_CHECK_PEPPER = Buffer.from("vaultline-recovery-check:v2:pepper");
+// Tags a stored value as v2 so `isLegacyPhraseCheck` can tell it apart from a
+// bare v1 digest without needing a version field of its own (see
+// `upgradeLegacyPhraseCheck`, which has no version field to read either).
+const PHRASE_CHECK_TAG = "02";
+/**
+ * In-process memo, keyed by the v1 digest rather than the phrase, so the map
+ * never holds the secret itself.
+ *
+ * The scrypt cost is the whole point of this check against an attacker holding
+ * config.json — but archiveFile verifies on *every* archive, and paying it per
+ * file doubled the cost of archiving: measured 70.5ms to 134.9ms per archive,
+ * which is 26 seconds against 49 across the 365 sessions on this machine, and
+ * a cost the daemon would pay forever. An attacker is not inside this process,
+ * so caching here costs them nothing; a legitimate caller archiving a thousand
+ * files pays scrypt once. Bounded in practice by how many distinct phrases one
+ * process handles, which is one.
+ */
+const strengthened = new Map();
+function strengthen(legacyDigestHex) {
+    const cached = strengthened.get(legacyDigestHex);
+    if (cached !== undefined)
+        return cached;
+    const derived = scryptSync(Buffer.from(legacyDigestHex, "hex"), PHRASE_CHECK_PEPPER, KEY_BYTES, SCRYPT_PARAMS);
+    const tagged = PHRASE_CHECK_TAG + derived.toString("hex");
+    strengthened.set(legacyDigestHex, tagged);
+    return tagged;
+}
+/**
+ * Confirms a typed phrase before any archive is touched. Defect #49: replaces
+ * a single cheap SHA-256 with the same scrypt cost `recoveryKey` charges the
+ * envelope, chained on top of `legacyPhraseCheck` rather than the raw phrase.
+ * Chaining on the digest (not the phrase) is what lets `upgradeLegacyPhraseCheck`
+ * promote an old vault's stored value using nothing but that value -- no
+ * phrase required, see there.
+ */
+export function phraseCheck(phrase) {
+    return strengthen(legacyPhraseCheck(phrase));
+}
+/** True for a config still holding a bare v1 digest (32 bytes); false once `phraseCheck` has tagged it (33). */
+export function isLegacyPhraseCheck(stored) {
+    return Buffer.from(stored, "hex").length === KEY_BYTES;
+}
+/**
+ * Promotes a v1 vault's stored digest to the v2 (cost-matched) format in
+ * place. Takes the OLD digest, not the phrase -- see `phraseCheck` -- which is
+ * what lets `readConfig` call this unconditionally on every legacy config it
+ * reads: no vault is stranded waiting on its owner to run a migration command,
+ * or even to unlock it first.
+ */
+export function upgradeLegacyPhraseCheck(stored) {
+    return strengthen(stored);
+}
+/** Verifies a typed phrase against a stored check, whichever format it is in. */
+export function matchesPhraseCheck(stored, phrase) {
+    return isLegacyPhraseCheck(stored) ? equalHex(stored, legacyPhraseCheck(phrase)) : equalHex(stored, phraseCheck(phrase));
+}
+export function equalHex(left, right) {
+    const a = Buffer.from(left, "hex");
+    const b = Buffer.from(right, "hex");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** @deprecated Format v1. Retained so existing archives stay readable and migratable. */
+export function encryptLegacyArchive(plaintext, phrase) {
+    const archiveKey = randomBytes(KEY_BYTES);
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", archiveKey, nonce, { authTagLength: TAG_BYTES });
+    cipher.setAAD(Buffer.from("vaultline-archive:v1"));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const salt = randomBytes(16);
+    const wrapNonce = randomBytes(NONCE_BYTES);
+    const wrappingKey = recoveryKey(phrase, salt);
+    const wrapper = createCipheriv("aes-256-gcm", wrappingKey, wrapNonce, { authTagLength: TAG_BYTES });
+    wrapper.setAAD(Buffer.from("vaultline-wrapped-key:v1"));
+    const wrapped = Buffer.concat([wrapper.update(archiveKey), wrapper.final()]);
+    return {
+        ciphertext,
+        nonce: nonce.toString("base64url"),
+        authTag: authTag.toString("base64url"),
+        wrappedKey: {
+            algorithm: "scrypt-aes-256-gcm",
+            salt: salt.toString("base64url"),
+            nonce: wrapNonce.toString("base64url"),
+            authTag: wrapper.getAuthTag().toString("base64url"),
+            ciphertext: wrapped.toString("base64url")
+        }
+    };
+}
+/** @deprecated Format v1 reader. New archives use `vaultline-crypto`. */
+export function decryptLegacyArchive(ciphertext, envelope, phrase) {
+    const wrappingKey = recoveryKey(phrase, Buffer.from(envelope.wrappedKey.salt, "base64url"));
+    const unwrap = createDecipheriv("aes-256-gcm", wrappingKey, Buffer.from(envelope.wrappedKey.nonce, "base64url"), { authTagLength: TAG_BYTES });
+    unwrap.setAAD(Buffer.from("vaultline-wrapped-key:v1"));
+    unwrap.setAuthTag(Buffer.from(envelope.wrappedKey.authTag, "base64url"));
+    const archiveKey = Buffer.concat([unwrap.update(Buffer.from(envelope.wrappedKey.ciphertext, "base64url")), unwrap.final()]);
+    const decipher = createDecipheriv("aes-256-gcm", archiveKey, Buffer.from(envelope.nonce, "base64url"), { authTagLength: TAG_BYTES });
+    decipher.setAAD(Buffer.from("vaultline-archive:v1"));
+    decipher.setAuthTag(Buffer.from(envelope.authTag, "base64url"));
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}

package/dist/src/daemon.d.ts

@@ -0,0 +1,52 @@
+import { ArchiveQueue } from "./queue.js";
+import { type NotifyOptions } from "./notify.js";
+export type DaemonOptions = {
+    phrase: string;
+    intervalMs?: number;
+    home?: string;
+    watch?: boolean;
+    upload?: boolean;
+    reclaim?: boolean;
+    queue?: ArchiveQueue;
+    /** Pause archiving when the disk has less free space than this. Reclamation still runs. */
+    diskPressureFreeBytes?: number;
+    /** Passed to the per-job check; see DrainOptions.reserveBytes. */
+    reserveBytes?: number;
+    /** How often to re-walk the transcript roots as a safety net. */
+    rescanEveryMs?: number;
+    onTick?: (result: TickResult) => void;
+    /** Desktop notifications. Omit to follow the environment; false to stay silent. */
+    notifications?: boolean;
+    notify?: NotifyOptions;
+    now?: () => number;
+};
+export type TickResult = {
+    at: string;
+    paused: boolean;
+    archived: number;
+    failed: number;
+    uploaded: number;
+    uploadErrors: number;
+    reclaimed: number;
+    freeBytes?: number;
+    notes: string[];
+};
+export type Daemon = {
+    tick(): Promise<TickResult>;
+    pause(): void;
+    resume(): void;
+    status(): Promise<{
+        paused: boolean;
+        queue: Awaited<ReturnType<ArchiveQueue["stats"]>>;
+        watching: string[];
+    }>;
+    close(): Promise<void>;
+};
+/**
+ * The long-running local agent: watch, archive, upload, then reclaim.
+ *
+ * Each stage is independent and failure-isolated, so a provider outage cannot stop
+ * archiving and a retention misconfiguration cannot stop uploads. `tick()` is
+ * exposed directly so behaviour can be tested without waiting on timers.
+ */
+export declare function startDaemon(dataDir: string, options: DaemonOptions): Promise<Daemon>;

package/dist/src/daemon.js

@@ -0,0 +1,142 @@
+import { freeBytes, resolveReserveBytes } from "./disk.js";
+import { ArchiveQueue } from "./queue.js";
+import { applyRetention, retentionSettings } from "./retention.js";
+import { readConfig } from "./vault.js";
+import { drainQueue } from "./worker.js";
+import { uploadAndOffloadPending } from "./heartbeat.js";
+import { signerEnabled } from "./control-plane.js";
+import { startTranscriptWatcher } from "./watcher.js";
+import { isVaultlineError } from "./errors.js";
+import { writeHeartbeat } from "./heartbeat.js";
+import { notify, NotificationGate, summarize } from "./notify.js";
+// One definition, shared with the worker's per-job check in src/disk.ts. Two
+// copies of "how much room is there" is how the two came to disagree about
+// whether there was any.
+/**
+ * The long-running local agent: watch, archive, upload, then reclaim.
+ *
+ * Each stage is independent and failure-isolated, so a provider outage cannot stop
+ * archiving and a retention misconfiguration cannot stop uploads. `tick()` is
+ * exposed directly so behaviour can be tested without waiting on timers.
+ */
+export async function startDaemon(dataDir, options) {
+    const queue = options.queue ?? new ArchiveQueue(dataDir);
+    const intervalMs = options.intervalMs ?? 30_000;
+    const now = options.now ?? Date.now;
+    const startedAt = new Date(now()).toISOString();
+    const totals = { archived: 0, uploaded: 0, reclaimed: 0, failed: 0 };
+    const gate = new NotificationGate();
+    const rescanEveryMs = options.rescanEveryMs ?? 60_000;
+    let lastScanAt = 0;
+    let paused = false;
+    let watcher;
+    if (options.watch !== false) {
+        watcher = await startTranscriptWatcher(dataDir, { home: options.home, queue });
+        await watcher.scan();
+        lastScanAt = now();
+    }
+    async function tick() {
+        const notes = [];
+        const free = await freeBytes(dataDir);
+        const result = { at: new Date(now()).toISOString(), paused, archived: 0, failed: 0, uploaded: 0, uploadErrors: 0, reclaimed: 0, freeBytes: free, notes };
+        let freedBytes = 0;
+        if (paused) {
+            notes.push("daemon is paused; no work was done");
+            await beat(result);
+            options.onTick?.(result);
+            return result;
+        }
+        // File-system watchers drop events: FSEvents coalesces, inotify runs out of
+        // watches, and a watcher can die with its directory. Re-walking the roots on a
+        // slow cadence means a missed event costs latency, never a lost session. The
+        // walk is cheap because content-addressed ids make re-queuing a no-op.
+        if (watcher && now() - lastScanAt >= rescanEveryMs) {
+            const found = await watcher.scan().catch(() => 0);
+            lastScanAt = now();
+            if (found)
+                notes.push(`rescanned transcript roots (${found} seen)`);
+        }
+        // This used to read `options.diskPressureFreeBytes` with no default, and
+        // nothing anywhere set it — so the guard was dead code and the installed
+        // service ran with no floor at all, on machines chosen for being short of
+        // space. It now defaults, and `drainQueue` additionally refuses any single
+        // job it has no room to finish, because one floor cannot know that the next
+        // transcript is 4 GB.
+        // One knob where there could be two: an operator who set a reserve meant it
+        // for both checks, and a tick-level floor that ignored it would refuse
+        // everything while the per-job check was happy to proceed.
+        const floor = options.diskPressureFreeBytes ?? options.reserveBytes ?? await resolveReserveBytes(dataDir);
+        if (free !== undefined && free < floor) {
+            notes.push(`disk is low (${(free / 1024 ** 3).toFixed(1)} GB free, holding ${(floor / 1024 ** 3).toFixed(1)} GB back); reclaiming instead of archiving`);
+        }
+        else {
+            const processed = await drainQueue(dataDir, options.phrase, { queue, reserveBytes: options.reserveBytes });
+            result.archived = processed.filter((job) => job.status === "done").length;
+            result.failed = processed.filter((job) => job.status !== "done" && job.lastError?.code !== "insufficient_disk_space").length;
+            const waiting = processed.filter((job) => job.lastError?.code === "insufficient_disk_space").length;
+            if (waiting)
+                notes.push(`${waiting} session${waiting === 1 ? "" : "s"} left queued: not enough free space to seal ${waiting === 1 ? "it" : "them"} safely`);
+        }
+        if (options.upload !== false && signerEnabled()) {
+            try {
+                // Upload, verify, then offload: a verified push whose blob stays on
+                // this disk has not freed anything, and this daemon exists to free it.
+                const uploads = await uploadAndOffloadPending(dataDir);
+                result.uploaded = uploads.uploaded.length;
+                result.uploadErrors = uploads.failed.length;
+                if (uploads.freedBytes > 0)
+                    notes.push(`freed ${(uploads.freedBytes / 1073741824).toFixed(1)} GB of sealed copies this disk no longer needs`);
+            }
+            catch (error) {
+                result.uploadErrors += 1;
+                notes.push(`upload pass failed: ${isVaultlineError(error) ? error.code : "unexpected error"}`);
+            }
+        }
+        else if (options.upload !== false) {
+            notes.push("uploads are disabled: no signer is enabled");
+        }
+        if (options.reclaim) {
+            const config = await readConfig(dataDir);
+            const settings = retentionSettings(config);
+            if (settings.policy === "archive-and-reclaim" || settings.policy === "manual-approval") {
+                const applied = await applyRetention(dataDir, { confirm: true, home: options.home });
+                result.reclaimed = applied.mode === "apply" ? applied.reclaimed.length : 0;
+                freedBytes = applied.mode === "apply" ? applied.freedBytes : 0;
+            }
+            else {
+                notes.push(`retention policy ${settings.policy} never reclaims`);
+            }
+        }
+        totals.archived += result.archived;
+        totals.uploaded += result.uploaded;
+        totals.reclaimed += result.reclaimed;
+        totals.failed += result.failed;
+        await beat(result);
+        // One notification at most per round, and only for something worth interrupting for.
+        const summary = summarize({ archived: result.archived, uploaded: result.uploaded, reclaimed: result.reclaimed, failed: result.failed, freedBytes });
+        if (summary && gate.allow(now(), result.failed > 0 || result.reclaimed > 0)) {
+            await notify(summary, { ...options.notify, enabled: options.notifications ?? options.notify?.enabled });
+        }
+        options.onTick?.(result);
+        return result;
+    }
+    /** Records the sign of life every other surface reads. */
+    async function beat(result) {
+        const state = {
+            version: 1, pid: process.pid, startedAt, lastTickAt: result.at, intervalMs,
+            totals: { ...totals },
+            last: { archived: result.archived, uploaded: result.uploaded, reclaimed: result.reclaimed, failed: result.failed, notes: result.notes },
+            paused, watching: watcher?.roots ?? []
+        };
+        await writeHeartbeat(dataDir, state).catch(() => undefined);
+    }
+    const timer = setInterval(() => { void tick().catch(() => undefined); }, intervalMs);
+    timer.unref?.();
+    return {
+        tick,
+        pause: () => { paused = true; },
+        resume: () => { paused = false; },
+        status: async () => ({ paused, queue: await queue.stats(), watching: watcher?.roots ?? [] }),
+        close: async () => { clearInterval(timer); await watcher?.close(); }
+    };
+}

package/dist/src/dashboard-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/dashboard-cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// `npm run dashboard` is a thin alias for the local API, which serves the dashboard
+// from the same origin. Keeping one server means one authentication path and no
+// second copy of the business logic.
+import { defaultDataDir } from "./vault.js";
+import { createLocalApiServer, localApiToken, localApiTokenPath } from "./local-api.js";
+import { freePort } from "./net.js";
+const dataDir = process.env.VAULTLINE_DATA_DIR ?? defaultDataDir();
+async function listen() {
+    const token = await localApiToken(dataDir);
+    const server = createLocalApiServer(dataDir, token);
+    const port = await freePort(Number(process.env.PORT ?? "4173"));
+    server.once("error", (error) => { console.error(`Unable to start dashboard on port ${port}: ${error.message}`); process.exitCode = 1; });
+    server.listen(port, "127.0.0.1", () => {
+        // The token travels in the URL fragment, which the browser never sends to a server.
+        console.log(`Sealkeep dashboard: http://127.0.0.1:${port}/#token=${token}`);
+        console.log(`Token file (do not share): ${localApiTokenPath(dataDir)}`);
+    });
+}
+void listen();