sealkeep 0.5.0

package/dist/src/local-api.js

@@ -0,0 +1,1757 @@
+import { createServer } from "node:http";
+import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { hostname } from "node:os";
+import { extname, join, resolve, sep } from "node:path";
+import { z } from "zod";
+import { detectAgents, detectSetupAgents, findTranscripts, installAgentHooks, SETUP_AGENT_IDS } from "./adapters.js";
+import { errorPayload, fail, isVaultlineError } from "./errors.js";
+import { ArchiveQueue } from "./queue.js";
+import { drainQueue } from "./worker.js";
+import { runDoctor } from "./doctor.js";
+import { liveness, readHeartbeat } from "./heartbeat.js";
+import { findWebRoot, localApiTokenPath } from "./paths.js";
+import { applyRetention, evaluateRetention, setRetentionPolicy } from "./retention.js";
+import { createActiveLease, createUploadClient } from "./providers/index.js";
+import { presign } from "./providers/sigv4.js";
+import { target as s3Target } from "./providers/s3.js";
+import { signGcsUrl } from "./providers/gcs.js";
+import { hasPasswordLock, unwrapPhrase, wrapPhrase } from "./password-lock.js";
+import { loadProviderCredentials, recallRecoveryPhrase, rememberRecoveryPhrase, storeProviderCredentials } from "./secrets.js";
+import { daemonInvocation, installService, serviceStatus, serviceUnitEnvironment } from "./service.js";
+import { defaultStrategy } from "./trash.js";
+import { isV2 } from "./types.js";
+import * as cloud from "./cloud.js";
+import { configureRemoteStorage, initialize, listArchives, previewRetention, readConfig, vaultStatus, writeRecord } from "./vault.js";
+import { sha256 } from "./crypto.js";
+const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+/**
+ * `vault.line` and `vault.localhost` join the list because the address bar is
+ * part of the product: `127.0.0.1:54142` reads as a malfunction. Neither name
+ * weakens the Host check below, which exists to stop a page on the open web
+ * reaching this service by pointing a hostname it controls at 127.0.0.1. These
+ * two resolve to loopback or nowhere — `vault.line` only exists if this user
+ * put it in their own hosts file — so accepting them adds no name an attacker
+ * can claim. The bearer token remains the thing that actually grants access.
+ */
+const ALLOWED_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1", "vault.line", "vault.localhost"]);
+const MAX_BODY_BYTES = 1_000_000;
+const enqueueSchema = z.object({
+    sourcePath: z.string().min(1).max(4096),
+    agent: z.string().min(1).max(64),
+    event: z.string().min(1).max(64).default("manual"),
+    sessionId: z.string().min(1).max(200).optional()
+}).strict();
+const retentionSchema = z.object({ olderThanDays: z.number().min(0).max(3650).default(30) }).strict();
+const applySchema = z.object({ confirm: z.boolean().default(false) }).strict();
+/**
+ * The retention rules, settable from the window rather than from a terminal.
+ *
+ * Deciding what may be deleted is the single most consequential choice this
+ * product asks anyone to make, and until now it could only be expressed by
+ * typing flags — so the page that showed a person their reclaimable space also
+ * had to tell them to go and run a command to act on it.
+ *
+ * `nullable` on the last two is load-bearing: null means "do not consider this
+ * rule", which is a different instruction from zero. Zero idle days would mean
+ * "reclaim everything however recently it was touched", so conflating them
+ * would turn an off switch into its opposite.
+ */
+const retentionPolicySchema = z.object({
+    policy: z.enum(["local-only", "sync-only", "archive-and-reclaim", "manual-approval"]).optional(),
+    olderThanDays: z.number().min(0).max(3650).optional(),
+    graceDays: z.number().min(0).max(3650).optional(),
+    sourceIdleDays: z.number().min(0).max(3650).nullable().optional(),
+    minSourceBytes: z.number().min(0).nullable().optional(),
+    /**
+     * Missing from this schema until now, which made the field on the retention
+     * page a control that did nothing and said "Saved". `.strict()` meant a body
+     * carrying it would have been rejected outright — so the page never sent it,
+     * and a person who typed 90 and pressed save was told their instruction had
+     * been recorded when it had not. A false success on a rule about *deleting
+     * archives* is the worst kind this product can ship.
+     */
+    deleteAfterDays: z.number().min(0).max(3650).nullable().optional()
+}).strict();
+/**
+ * The pairing code from the account panel, with the email it belongs to.
+ *
+ * Both, because that is what the panel's own instructions hand over: it shows
+ * `sealkeep cloud login --email … --code …`, and the exchange needs the pair.
+ *
+ * Deliberately not a password and not a recovery phrase: this links a machine
+ * to an account someone already has, which grants quota, managed storage and
+ * settings — never the ability to open an archive. That is what keeps the "no
+ * endpoint accepts a phrase" rule intact while still letting a returning user
+ * finish in the window instead of a terminal.
+ */
+const enrollSchema = z.object({
+    email: z.string().trim().min(3).max(320),
+    code: z.string().trim().min(1).max(200)
+}).strict();
+/**
+ * `confirmLastCopy` is the only field, and it exists because deleting a stored
+ * copy is usually reversible — the archive is still on this disk — until the
+ * day it is not. When the local bytes are already gone, the stored copy is the
+ * archive, and removing it must take a second, knowing request rather than the
+ * same one that deletes any other row.
+ */
+const deleteCopySchema = z.object({ confirmLastCopy: z.boolean().default(false) }).strict();
+/**
+ * Null clears the cap. The floor is 1 GB because zero would read as "keep
+ * nothing", which is a bulk delete wearing a setting's clothes — emptying
+ * storage is what the copies table above is for, one witnessed row at a time.
+ */
+const rollingCapSchema = z.object({ capGb: z.number().min(1).max(100_000).nullable() }).strict();
+/**
+ * The sessions a person picked, by absolute path.
+ *
+ * Capped because this is the one endpoint that starts real work: a thousand
+ * gigabyte transcripts selected by a stuck key should be refused, not attempted.
+ */
+/** Twenty-four words, once, to be kept — never to be read back. */
+const rememberSchema = z.object({ phrase: z.string().trim().min(1).max(2000) }).strict();
+const archiveSelectionSchema = z.object({
+    // Enqueue-only since the background drain took over sealing, so a large
+    // selection is cheap: "select all 700" arrives as one request. The old cap of
+    // 200 made the page split requests while the button offered no such limit.
+    paths: z.array(z.string().min(1).max(4096)).min(1).max(5000)
+}).strict();
+/** Mirrors adapters.ts's AgentId union. Zod needs a literal tuple to validate against, not a type. */
+const KNOWN_AGENTS = ["codex", "claude"];
+const TRASH_STRATEGIES = ["auto", "macos-trash", "xdg-trash", "windows-recycle-bin", "vaultline-trash"];
+// Every field is optional: PUT sends only what changed, and the handler merges
+// it onto the settings already on disk — the same partial-override shape
+// retention.ts uses for its own settings. `.strict()` is what makes the
+// read-only remote mirror actually unwritable rather than merely undocumented:
+// a body that names `sync`, `plan`, or `quota` is rejected as invalid_argument
+// before it reaches any handler logic.
+const localSettingsSchema = z.object({
+    deviceLabel: z.string().trim().min(1).max(80).optional(),
+    watchedAgents: z.array(z.enum(KNOWN_AGENTS)).max(KNOWN_AGENTS.length).optional(),
+    watchedPaths: z.array(z.string().min(1).max(4096)).max(200).optional(),
+    exclusions: z.array(z.string().min(1).max(4096)).max(500).optional(),
+    reclaimEnabled: z.boolean().optional(),
+    trashStrategy: z.enum(TRASH_STRATEGIES).optional(),
+    schedule: z.object({ intervalMinutes: z.number().min(1).max(1440) }).strict().optional(),
+    bandwidth: z.object({ uploadLimitMbps: z.number().min(0).max(100_000).nullable() }).strict().optional(),
+    // 200 MB is the hard floor: below that, operating systems fail in ways no
+    // archive tool should be the cause of. null returns to automatic.
+    diskReserveMb: z.number().min(200).max(102_400).nullable().optional(),
+    // Only meaningful when it flips reclaim from off to on; see the PUT handler.
+    confirm: z.boolean().default(false)
+}).strict();
+/**
+ * First-run setup (PRODUCT_ARCHITECTURE.md §7).
+ *
+ * Every one of these bodies is `.strict()` for the same reason the settings
+ * schema is: a field nobody declared is a field nobody reviewed, and this is
+ * the one surface where a browser hands the product real secrets.
+ */
+const setupVaultSchema = z.object({
+    confirm: z.boolean().default(false),
+    /**
+     * Keep the phrase in this machine's keystore so the background service can
+     * seal sessions without a human pasting it at every boot. On by default
+     * because a first run that ends with a service which cannot encrypt is not a
+     * finished setup; secrets.ts states the trade-off this accepts.
+     */
+    remember: z.boolean().default(true),
+    /**
+     * Free tier's unlock: seals the same phrase, on this machine, under a
+     * password the person chose (password-lock.ts). It never replaces the phrase
+     * and never travels — the response returns the phrase exactly as before, and
+     * the wizard still owes the person the write-it-down moment.
+     */
+    password: z.string().min(8).max(1024).optional(),
+    /**
+     * Made here, once, because it cannot be changed later without re-writing
+     * every archive: "plain" stores archives as readable gzip for people who
+     * chose portability over secrecy. Defaulted so a page that never mentions
+     * the choice still creates the vault everyone expects — an encrypted one.
+     */
+    storageMode: z.enum(["sealed", "plain"]).default("sealed")
+}).strict();
+/**
+ * A password to exchange for the phrase, and nothing else. Length is not
+ * policed here: whether it opens the lock is the only judgement an unlock
+ * attempt gets, so a short guess hears "wrong password", not a length rule.
+ */
+const setupUnlockSchema = z.object({ password: z.string().min(1).max(1024) }).strict();
+const setupHooksSchema = z.object({
+    agents: z.array(z.enum(SETUP_AGENT_IDS)).min(1).max(SETUP_AGENT_IDS.length),
+    confirm: z.boolean().default(false)
+}).strict();
+/**
+ * Storage credentials, and the only place they are ever accepted.
+ *
+ * They are validated here and handed straight to `storeProviderCredentials`,
+ * which puts them in the OS keystore. Nothing in this file reads them back,
+ * and the setup record deliberately holds only the fact that they exist.
+ */
+const awsCredentialsSchema = z.object({
+    accessKeyId: z.string().trim().min(1).max(256),
+    secretAccessKey: z.string().min(1).max(4096),
+    sessionToken: z.string().min(1).max(8192).optional()
+}).strict();
+const serviceAccountSchema = z.object({
+    clientEmail: z.string().trim().min(3).max(320),
+    privateKey: z.string().min(1).max(16_384)
+}).strict();
+/** Managed storage is provisioned by enrolment, not typed into a form, so it is not offered here. */
+const SETUP_PROVIDERS = ["s3", "r2", "b2", "gcs", "gdrive"];
+const setupStorageSchema = z.object({
+    provider: z.enum(SETUP_PROVIDERS),
+    bucket: z.string().trim().min(1).max(255),
+    prefix: z.string().trim().min(1).max(512).default("vaultline"),
+    region: z.string().trim().min(1).max(64).optional(),
+    /** Required for R2 and any other S3-compatible host; see providers/s3.ts. */
+    endpoint: z.string().trim().min(1).max(2048).optional(),
+    credentials: z.union([awsCredentialsSchema, serviceAccountSchema]),
+    confirm: z.boolean().default(false)
+}).strict();
+const deleteArchiveSchema = z.object({
+    confirm: z.boolean().default(false),
+    /** Required when the source file no longer exists: the archive IS the session then, and deleting it is forever. */
+    confirmForever: z.boolean().default(false)
+}).strict();
+const setupServiceSchema = z.object({
+    confirm: z.boolean().default(false),
+    /** Let the service reclaim local files once a remote copy is verified. Off by default, as everywhere else. */
+    reclaim: z.boolean().default(false)
+}).strict();
+const webRoot = findWebRoot();
+const CONTENT_TYPES = { ".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".svg": "image/svg+xml" };
+/**
+ * Serves the companion dashboard from the same origin as the API, so the page can
+ * authenticate with the local token without any cross-origin exception.
+ */
+/**
+ * Which page `/` means, which depends on whether there is a vault yet.
+ *
+ * It used to always mean the dashboard. On a machine with no vault the
+ * dashboard has exactly one thing it can say — "no vault here, run this
+ * terminal command" — so the first thing a new user saw was an error and an
+ * instruction to leave the window they had just been sent to. The wizard was
+ * sitting at /setup.html the whole time, reachable only by someone who already
+ * knew it existed.
+ */
+async function landingPage(dataDir) {
+    try {
+        await readConfig(dataDir);
+        return "/index.html";
+    }
+    catch {
+        return "/setup.html";
+    }
+}
+async function serveStatic(pathname, response) {
+    const relative = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
+    const file = resolve(webRoot, relative);
+    if (file !== webRoot && !file.startsWith(`${webRoot}${sep}`)) {
+        response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Forbidden");
+        return;
+    }
+    try {
+        const body = await readFile(file);
+        response.writeHead(200, { "content-type": CONTENT_TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+        response.end(body);
+    }
+    catch {
+        response.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found");
+    }
+}
+/**
+ * Proves a storage target works, before anyone trusts it with an archive.
+ *
+ * Credentials are the step of setup most likely to be wrong, and every way of
+ * being wrong used to surface at the same moment: hours later, in a background
+ * upload, as a failure nobody was watching. The bucket name has a typo, the key
+ * lacks PutObject, the region is the console's display name rather than its id,
+ * the B2 key is a native one rather than S3-compatible. All of that is knowable
+ * in a second while the person is still looking at the form.
+ *
+ * It writes a small object, reads it back, and compares the bytes, because
+ * anything less proves less: a successful PUT says nothing about whether GET is
+ * permitted, and this product's whole promise is that the bytes come back.
+ *
+ * Nothing is stored. The credential is used to build a client, held for the
+ * round trip, and dropped — the caller has not committed to this target yet,
+ * and a test that saved a broken configuration would be worse than no test.
+ */
+export async function testStorageTarget(input) {
+    const { credentials, endpoint, provider, bucket, prefix, region } = input;
+    if ((provider === "gcs") !== ("clientEmail" in credentials)) {
+        return { ok: false, detail: provider === "gcs"
+                ? "GCS needs a service-account credential (clientEmail and privateKey), not an access key"
+                : `${provider} needs an access-key credential (accessKeyId and secretAccessKey), not a service account` };
+    }
+    if (provider === "r2" && !endpoint)
+        return { ok: false, detail: "R2 needs its endpoint: https://<account-id>.r2.cloudflarestorage.com" };
+    if (endpoint) {
+        try {
+            assertHttpUrl(endpoint);
+        }
+        catch {
+            return { ok: false, detail: `${endpoint} is not a usable https URL` };
+        }
+    }
+    // One fixed key, overwritten on each test, so repeated attempts leave exactly
+    // one small object behind rather than a scattering of them.
+    // Filled from the lease once it exists, so the key reported is the key written.
+    let probeKey = `${prefix.replace(/^\/+|\/+$/g, "")}/.vaultline-write-test`;
+    const payload = Buffer.from(`sealkeep write test ${randomBytes(16).toString("hex")}\n`);
+    const digest = sha256(payload);
+    try {
+        // VAULTLINE_ENABLE_SIGNER gates *uploading archives* through a provider
+        // client, and it is off unless the installed service turns it on. That gate
+        // is right for archives and wrong for this: refusing to check a bucket
+        // because archives are not enabled yet would mean the only way to find out
+        // whether credentials work is to finish setup and wait for a background
+        // upload to fail. So the probe runs with it on, for this call only, writing
+        // fifty bytes the person explicitly asked to have written, to a bucket they
+        // just named, with a credential they just typed. Nothing else in this
+        // process gains the flag and the archive path is untouched.
+        const probeEnv = { ...process.env, VAULTLINE_ENABLE_SIGNER: "1" };
+        const target = { provider, bucket, prefix, ...(region ? { region } : {}) };
+        const client = createUploadClient(target, credentials, endpoint ? endpointOverrides(endpoint) : {}, probeEnv);
+        const lease = createActiveLease(target, {
+            archiveId: ".vaultline-write-test", ciphertextSha256: digest, bytes: payload.length
+        }, probeEnv);
+        // The lease decides the real key, including its suffix. Reporting anything
+        // else would send someone looking in their bucket for a name that is not there.
+        probeKey = lease.objectKey;
+        await client.upload(lease, payload);
+        // Reading the object back is the proof that matters, since the promise is
+        // that the bytes come back — but only the S3-family clients can do it, so
+        // GCS gets the strongest check it supports and the message says which was
+        // run rather than implying they are the same.
+        const readable = client;
+        if (typeof readable.download === "function") {
+            const read = await readable.download(lease);
+            if (!read.equals(payload)) {
+                return { ok: false, detail: "The bytes read back did not match what was written, so this target cannot be trusted with an archive.", probeKey };
+            }
+            return { ok: true, detail: `Wrote ${payload.length} bytes to ${bucket}/${probeKey} and read them back unchanged.`, probeKey };
+        }
+        const seen = await client.head(lease);
+        if (!seen.exists)
+            return { ok: false, detail: "The object was accepted but is not there afterwards.", probeKey };
+        if (seen.bytes !== payload.length)
+            return { ok: false, detail: `Wrote ${payload.length} bytes but the object is ${seen.bytes}.`, probeKey };
+        return { ok: true, detail: `Wrote ${payload.length} bytes to ${bucket}/${probeKey} and confirmed it is there. This provider does not support reading it back from here, so writing is what was proved.`, probeKey };
+    }
+    catch (error) {
+        // The provider's own words. "Access denied" naming the operation is worth
+        // more to whoever has to fix the policy than anything this could invent.
+        const message = error instanceof Error ? error.message : "the storage provider refused the request";
+        return { ok: false, detail: message, probeKey };
+    }
+}
+/** Agents whose sessions this build can actually seal. Others are detected but not offered. */
+const ARCHIVABLE = ["codex", "claude"];
+/**
+ * Every session on this machine, with the two facts a person needs to choose:
+ * how big it is, and when they last touched it.
+ *
+ * This exists because archiving everything automatically is the wrong default
+ * for the situation people are actually in — a nearly full disk, a handful of
+ * enormous transcripts, and no appetite for a background process deciding which
+ * ones to work through. Choosing is cheap when you can see sizes and dates;
+ * guessing is not.
+ *
+ * Already-archived sessions are marked rather than hidden, because "this one is
+ * done" is as useful as "this one is not", and hiding them would make the list
+ * shrink as you work and lose your place.
+ */
+export async function listSessions(dataDir, queue) {
+    const archives = await listArchives(dataDir).catch(() => []);
+    // Paths with a live job: queued or currently sealing. The page uses this to
+    // mark the row and refuse re-selection — without it, a person mid-batch saw
+    // 500 rows still reading "not archived" and could tick them all again.
+    const live = queue ? (await queue.list().catch(() => [])).filter((job) => job.status === "ready" || job.status === "leased") : [];
+    const inFlight = new Set(live.map((job) => job.sourcePath));
+    // A ready job whose last attempt was refused is waiting, not working — the
+    // refusal message (today: the disk guard's) rides to the page so the row can
+    // say "waiting for room" instead of pretending to seal.
+    const heldWhy = new Map(live.filter((job) => job.status === "ready" && job.lastError).map((job) => [job.sourcePath, typeof job.lastError === "string" ? job.lastError : job.lastError.message ?? "waiting to retry"]));
+    const sealingPct = new Map(live.filter((job) => job.status === "leased" && job.progress && job.progress.of > 0)
+        .map((job) => [job.sourcePath, Math.min(99, Math.floor((job.progress.bytes / job.progress.of) * 100))]));
+    // Keyed on path *and* length: a transcript that has grown since it was
+    // archived is not covered, and saying otherwise would invite someone to
+    // reclaim bytes no archive holds.
+    const covered = new Set(archives.map((record) => `${record.source.path}:${record.source.bytes}`));
+    // Sealed is not stored: an archive on this disk protects against deletion,
+    // a verified remote copy protects against losing the disk. The page filters
+    // on that difference, so it is computed here, from the same records.
+    const offMachine = new Set(archives
+        .filter((record) => record.version === 2 && record.remote?.verifiedAt)
+        .map((record) => `${record.source.path}:${record.source.bytes}`));
+    const sessions = [];
+    for (const agent of ARCHIVABLE) {
+        const found = await findTranscripts(agent, process.env.HOME ?? ".", 5_000).catch(() => []);
+        for (const item of found) {
+            const key = `${item.path}:${item.bytes}`;
+            sessions.push({
+                ...item,
+                // `?? null` because the candidate fields are optional pre-resolution;
+                // a row promises an answer, even when the answer is "nothing said".
+                project: item.project ?? null,
+                projectPath: item.projectPath ?? null,
+                archived: covered.has(key),
+                stored: offMachine.has(key),
+                queued: inFlight.has(item.path),
+                held: heldWhy.get(item.path) ?? null,
+                sealingPct: sealingPct.get(item.path) ?? null
+            });
+        }
+    }
+    // Biggest first: the reason anyone opened this page is disk, and on a real
+    // machine forty files hold the space that three hundred others do not.
+    sessions.sort((a, b) => b.bytes - a.bytes);
+    return {
+        sessions,
+        totalBytes: sessions.reduce((total, item) => total + item.bytes, 0),
+        unarchivedBytes: sessions.filter((item) => !item.archived).reduce((total, item) => total + item.bytes, 0)
+    };
+}
+/**
+ * Archives exactly the sessions that were chosen, and nothing else.
+ *
+ * The recovery phrase is read from this machine's keystore, never from the
+ * request: the rule that no endpoint accepts a phrase is what keeps a browser
+ * page from being able to hand one over, and it is not weakened by using one
+ * the person already chose to store here. With nothing stored, this refuses and
+ * says which command stores it, rather than failing halfway through a list.
+ */
+/**
+ * One background drain at a time, owned by this process.
+ *
+ * The manual path used to seal inside the HTTP request — fine for three files,
+ * ruinous for five hundred: the browser owned an hours-long loop, a refresh
+ * killed everything after the current batch, and nothing resumed. Now a request
+ * only queues; this loop seals until the queue is dry, whoever asked. It is
+ * also kicked once at server start, so jobs stranded by a restart or a closed
+ * page finish on their own.
+ */
+let drainRunning = false;
+export async function ensureDraining(dataDir, queue) {
+    if (drainRunning)
+        return;
+    drainRunning = true;
+    try {
+        const config = await readConfig(dataDir);
+        const phrase = await recallRecoveryPhrase(dataDir, config.vaultId);
+        if (!phrase)
+            return; // jobs stay queued; storing the phrase in Settings resumes them
+        await drainQueue(dataDir, phrase, { queue, max: 100_000, requireSpace: true });
+    }
+    catch {
+        // Jobs stay queued. The next archive request, or the next server start,
+        // kicks the drain again — failure here loses nothing.
+    }
+    finally {
+        drainRunning = false;
+    }
+}
+export async function archiveSelected(dataDir, paths, queue) {
+    const config = await readConfig(dataDir);
+    const phrase = await recallRecoveryPhrase(dataDir, config.vaultId);
+    if (!phrase) {
+        // Rendered verbatim on the Sessions page, which shows plain text: no
+        // backticks, no terminal command, and it points at a place that page can
+        // actually reach — Settings › Unlocking on the dashboard — not a tab that
+        // does not exist here. It also says plainly that nothing was lost.
+        fail("recovery_phrase_missing", "Nothing was archived, and nothing was lost — your sessions are untouched. This machine has not stored your recovery phrase yet, so it cannot seal on its own. Open the dashboard, go to Settings › Unlocking, and choose “Remember it on this machine”, then try again.");
+    }
+    const known = new Map((await listSessions(dataDir)).sessions.map((row) => [row.path, row]));
+    const results = [];
+    for (const path of paths) {
+        const row = known.get(path);
+        // Only paths this machine actually reported. A request naming something
+        // else is either stale or someone probing, and neither should reach the
+        // archiver with an arbitrary path.
+        if (!row) {
+            results.push({ path, ok: false, error: "not a session this machine reported" });
+            continue;
+        }
+        try {
+            await queue.enqueue({ sourcePath: row.path, agent: row.agent, event: "manual" });
+            results.push({ path, ok: true, bytes: row.bytes });
+        }
+        catch (error) {
+            results.push({ path, ok: false, error: error instanceof Error ? error.message : "could not queue" });
+        }
+    }
+    // Queued, not sealed: the response returns immediately and the drain runs in
+    // the background, so closing or refreshing the page changes nothing. The
+    // page reads live progress from GET /v1/sessions, whose rows carry `queued`.
+    void ensureDraining(dataDir, queue);
+    return {
+        requested: paths.length,
+        queued: results.filter((item) => item.ok).length,
+        bytes: results.filter((item) => item.ok).reduce((total, item) => total + (item.bytes ?? 0), 0),
+        background: true,
+        results
+    };
+}
+export { localApiTokenPath };
+/** Mints the loopback token once and keeps it owner-readable. It is never logged or returned by an endpoint. */
+export async function localApiToken(dataDir) {
+    const path = localApiTokenPath(dataDir);
+    try {
+        const existing = (await readFile(path, "utf8")).trim();
+        if (existing) {
+            await chmod(path, 0o600);
+            return existing;
+        }
+    }
+    catch { /* mint below */ }
+    const token = randomBytes(32).toString("base64url");
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    await writeFile(path, `${token}\n`, { mode: 0o600 });
+    return token;
+}
+const STATUS_BY_CODE = {
+    unauthorized: 401, forbidden: 403,
+    vault_not_initialized: 404, archive_not_found: 404, queue_job_not_found: 404,
+    signer_not_configured: 501, internal: 500
+};
+function json(response, status, value, headers = {}) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff", ...headers });
+    response.end(JSON.stringify(value));
+}
+function tokenMatches(presented, token) {
+    const a = Buffer.from(presented);
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * How a request proved itself: the bearer header (the CLI, and a page whose
+ * tab still holds the token) or the HttpOnly cookie (a browser coming back).
+ *
+ * The cookie exists so a person does not re-enter the token every time a tab
+ * closes. It is set server-side on the first bearer-authorized request and
+ * marked HttpOnly, so no script in the page can ever read it — which makes it
+ * strictly harder to steal than the sessionStorage copy the pages hold today.
+ * SameSite=Strict means a hostile website cannot ride it, the loopback and
+ * Host checks above already refuse everything non-local, and no CORS headers
+ * are ever sent, so a cross-origin page cannot read a response either.
+ */
+function authorizedVia(request, token) {
+    const header = request.headers.authorization;
+    if (typeof header === "string" && header.startsWith("Bearer ")) {
+        const presented = header.slice("Bearer ".length).trim();
+        // An empty bearer is a page that has no token in hand, not a wrong one —
+        // fall through and let the cookie answer for it.
+        if (presented.length > 0)
+            return tokenMatches(presented, token) ? "bearer" : null;
+    }
+    const cookies = request.headers.cookie;
+    if (typeof cookies === "string") {
+        for (const part of cookies.split(";")) {
+            const eq = part.indexOf("=");
+            if (eq === -1)
+                continue;
+            if (part.slice(0, eq).trim() !== "vaultline_token")
+                continue;
+            if (tokenMatches(part.slice(eq + 1).trim(), token))
+                return "cookie";
+        }
+    }
+    return null;
+}
+/** Rejects cross-origin hostnames so a browsing page cannot reach the API by DNS rebinding. */
+function hostAllowed(request) {
+    const host = (request.headers.host ?? "").toLowerCase();
+    return ALLOWED_HOSTS.has(host.replace(/:\d+$/, ""));
+}
+async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            fail("invalid_argument", "Request body is too large");
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return fail("invalid_argument", "Request body must be valid JSON");
+    }
+}
+function parseBody(schema, value) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        fail("invalid_argument", result.error.issues.map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`).join("; "));
+    return result.data;
+}
+/** Safe by construction: reclaim is off and nothing is excluded until a person turns them on. */
+function defaultLocalSettings() {
+    return {
+        version: 1,
+        deviceLabel: hostname(),
+        watchedAgents: [...KNOWN_AGENTS],
+        watchedPaths: [],
+        exclusions: [],
+        reclaimEnabled: false,
+        trashStrategy: "auto",
+        schedule: { intervalMinutes: 5 },
+        bandwidth: { uploadLimitMbps: null },
+        diskReserveMb: null
+    };
+}
+const localSettingsPath = (dataDir) => join(dataDir, "local-settings.json");
+/**
+ * Missing or unrecognised fields fall back to the default rather than failing
+ * to load, so a settings file written by an older build still reads after a
+ * new field is added. Unlike the vault config, these are preferences with
+ * nothing cryptographic riding on them, so there is no version to gate on.
+ */
+async function readLocalSettings(dataDir) {
+    const fallback = defaultLocalSettings();
+    try {
+        const saved = JSON.parse(await readFile(localSettingsPath(dataDir), "utf8"));
+        return {
+            ...fallback, ...saved,
+            schedule: { ...fallback.schedule, ...saved?.schedule },
+            bandwidth: { ...fallback.bandwidth, ...saved?.bandwidth }
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Written beside, never inside, the vault config: per-machine preferences are never synced. */
+async function writeLocalSettings(dataDir, settings) {
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const target = localSettingsPath(dataDir);
+    const temp = `${target}.${randomBytes(9).toString("hex")}.tmp`;
+    await writeFile(temp, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, target);
+}
+/**
+ * Plan, quota and email come from the account, live when the control plane
+ * answers and from the last remembered answer when it does not — the same one
+ * cache sync-rules.ts keeps, now holding everything the account said. Fetching
+ * live-only meant a machine that went offline forgot its owner was a paying
+ * customer: the plan badge vanished and plan-gated surfaces fell back to the
+ * free look. `source` says which of the two the reader is looking at.
+ */
+async function cloudPlanAndQuota(dataDir) {
+    const { resolveAccount } = await import("./sync-rules.js");
+    const { account, source } = await resolveAccount(dataDir);
+    return { plan: account.plan, quota: account.quota, email: account.email, source };
+}
+/** The account panel lives at the cloud API's origin with `/api` swapped for `#account`. */
+async function panelUrl() {
+    const { DEFAULT_CLOUD_URL } = await import("./cloud.js");
+    const origin = (process.env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "").replace(/\/api$/, "");
+    return `${origin}/#account`;
+}
+/**
+ * Everything the settings screen shows about the account, and none of it
+ * writable from here. `editable: false` travels with the data itself as a
+ * second guard alongside the PUT schema simply having no field for any of it —
+ * a reader of the response alone can tell these values are not a form.
+ */
+async function remoteSettingsMirror(dataDir) {
+    // One request to the control plane, not two: resolveAccount fetches and
+    // caches the whole answer (rules, plan, quota, email), and the rules are then
+    // read back from that same cache. Before this, the rules and the plan were
+    // fetched by two separate, identical account calls per settings read.
+    const [cloud, url] = await Promise.all([cloudPlanAndQuota(dataDir), panelUrl()]);
+    const { cachedSyncRules, DEFAULT_SYNC_RULES } = await import("./sync-rules.js");
+    const rules = (await cachedSyncRules(dataDir)) ?? DEFAULT_SYNC_RULES;
+    const source = cloud.source === "none" ? "default" : cloud.source;
+    return {
+        sync: { mode: rules.mode, keepLast: rules.keepLast, minAgeDays: rules.minAgeDays, source },
+        plan: cloud.plan,
+        quota: cloud.quota,
+        panelUrl: url,
+        editable: false
+    };
+}
+/**
+ * Which storage answers for "what is stored remotely".
+ *
+ * A configured bucket wins, because the vault's records point into it and the
+ * account knows nothing about it. With no bucket, being signed in is the fact
+ * that makes a vault managed — the same test autopilot applies before telling
+ * anyone to configure storage they are already paying us to run.
+ */
+async function storedCopiesMode(dataDir) {
+    const config = await readConfig(dataDir);
+    if (config.remoteStorage && config.remoteStorage.provider !== "vaultline")
+        return "own";
+    const { cloudToken } = await import("./cloud.js");
+    try {
+        await cloudToken(dataDir);
+        return "managed";
+    }
+    catch {
+        return "none";
+    }
+}
+/**
+ * Whether each archive's bytes still exist on this disk, by asking the disk.
+ *
+ * The `offloaded` marker says the file was removed, but the question here
+ * authorises deleting the only other copy, so the answer comes from a stat
+ * rather than from bookkeeping that could have missed a crash or a hand-tidied
+ * folder. A record whose object file cannot be proven present counts as absent.
+ */
+async function localArchivePresence(dataDir) {
+    const presence = new Map();
+    for (const record of await listArchives(dataDir).catch(() => [])) {
+        presence.set(record.id, await stat(record.objectPath).then((entry) => entry.isFile()).catch(() => false));
+    }
+    return presence;
+}
+/**
+ * Deletes one object from the customer's own bucket, signed here with the same
+ * signers the upload clients use — the upload client itself has no delete, and
+ * the archive path should not grow one for the sake of this route. The signer
+ * feature flag is deliberately not consulted: it gates background uploads,
+ * and this is a person removing one named object they are looking at.
+ */
+async function deleteOwnObject(dataDir, storage, remote) {
+    const config = await readConfig(dataDir);
+    if (remote.layout?.kind === "chunks" && storage.provider !== "gdrive") {
+        // A chunk-folder remote deletes as a folder: every deterministic chunk
+        // name plus the envelope sidecar, through the same client that wrote them.
+        const { deleteChunkFolder } = await import("./chunk-store.js");
+        const { uploadClientFromStore } = await import("./providers/index.js");
+        const client = (await uploadClientFromStore(dataDir, config.vaultId, { provider: storage.provider, bucket: storage.bucket, prefix: "unused", region: storage.region }));
+        await deleteChunkFolder(client, remote);
+        return;
+    }
+    const credentials = await loadProviderCredentials(dataDir, config.vaultId);
+    const { storageEndpoint } = await readSetupRecord(dataDir);
+    const overrides = storageEndpoint ? endpointOverrides(storageEndpoint) : {};
+    if (storage.provider === "gdrive") {
+        // Drive has no presignable delete: the OAuth client is the credential, so
+        // the provider client does the deleting itself, locating the file by the
+        // vaultlineKey property exactly the way head/download do.
+        const { GdriveUploadClient } = await import("./providers/gdrive.js");
+        if (!("kind" in credentials) || credentials.kind !== "gdrive")
+            fail("invalid_argument", "Google Drive needs its OAuth credential. Run: sealkeep storage connect gdrive");
+        const client = new GdriveUploadClient({ folderName: storage.bucket, appData: false }, credentials);
+        await client.deleteByKey(remote.objectKey);
+        return;
+    }
+    let url;
+    if (storage.provider === "gcs") {
+        if (!("clientEmail" in credentials))
+            fail("invalid_argument", "GCS needs a service-account credential, not an access key");
+        url = signGcsUrl({
+            method: "DELETE", bucket: storage.bucket, object: remote.objectKey, serviceAccount: credentials,
+            host: overrides.host, port: overrides.port, protocol: overrides.protocol
+        }).url;
+    }
+    else {
+        if (!("accessKeyId" in credentials))
+            fail("invalid_argument", `${storage.provider} needs an access-key credential, not a service account`);
+        const { host, path } = s3Target({
+            provider: storage.provider, region: storage.region ?? "auto", bucket: storage.bucket,
+            host: overrides.host, port: overrides.port, protocol: overrides.protocol, pathStyle: overrides.pathStyle
+        }, remote.objectKey);
+        url = presign({ method: "DELETE", host, port: overrides.port, protocol: overrides.protocol, path, region: storage.region ?? "auto", credentials }).url;
+    }
+    const response = await fetch(url, { method: "DELETE" });
+    // 404 passes: the goal is an absent object, and it is absent.
+    if (!response.ok && response.status !== 404) {
+        fail("internal", `Storage refused the delete: ${response.status} ${response.statusText}. The stored copy may still be there, and nothing was changed here.`);
+    }
+}
+/**
+ * The cache file sync-rules.ts owns. Named here as well because the rolling cap
+ * rides in that file beside the rules it belongs with; the name agreement is
+ * pinned by test/cloud-copies.test.ts, which greps both files.
+ */
+const syncRulesCachePath = (dataDir) => join(dataDir, "sync-rules.json");
+async function readRollingCap(dataDir) {
+    try {
+        const saved = JSON.parse(await readFile(syncRulesCachePath(dataDir), "utf8"));
+        const cap = Number(saved?.rolling_cap_gb);
+        return Number.isFinite(cap) && cap > 0 ? cap : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Merges the cap into the cache without disturbing the rules the account wrote there. */
+async function writeRollingCap(dataDir, capGb) {
+    let saved = {};
+    try {
+        saved = JSON.parse(await readFile(syncRulesCachePath(dataDir), "utf8"));
+    }
+    catch { /* first write */ }
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    await writeFile(syncRulesCachePath(dataDir), JSON.stringify({ ...saved, rolling_cap_gb: capGb }, null, 2), { mode: 0o600 });
+}
+/**
+ * A coarse ETA, not a promise. Grace period and activity are evaluated per
+ * candidate in retention.ts and already explained in full by GET /v1/retention;
+ * duplicating that branching here would drift the moment its rules changed.
+ * This answers only "open now", "not scheduled", or "not before <date>" from
+ * the age gate alone, and points at the real evaluation for the rest.
+ */
+function nextReclaimWindow(evaluation, now) {
+    if (evaluation.policy === "local-only" || evaluation.policy === "sync-only")
+        return { state: "not-scheduled" };
+    if (evaluation.reclaimableBytes > 0)
+        return { state: "open" };
+    const waiting = evaluation.candidates.filter((candidate) => !candidate.eligible);
+    if (waiting.length === 0)
+        return { state: "not-scheduled" };
+    const earliestMs = Math.min(...waiting.map((candidate) => Date.parse(candidate.createdAt) + evaluation.olderThanDays * 86_400_000));
+    return { state: "waiting", notBefore: new Date(Math.max(earliestMs, now)).toISOString(), pending: waiting.length };
+}
+const setupRecordPath = (dataDir) => join(dataDir, "setup.json");
+function defaultSetupRecord() {
+    return { version: 1, phraseIssuedAt: null, phraseRemembered: false, storageEndpoint: null, credentials: null, hooks: [] };
+}
+/** A storage endpoint the wizard collected, checked before it is stored or signed against. */
+function assertHttpUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return fail("invalid_argument", `Not a valid storage endpoint URL: ${value}`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        fail("invalid_argument", "A storage endpoint must be an http or https URL");
+    return parsed;
+}
+/** The host overrides a provider client takes. Path-style, because a named host always is one. */
+function endpointOverrides(endpoint) {
+    const parsed = assertHttpUrl(endpoint);
+    return { host: parsed.hostname, port: parsed.port ? Number(parsed.port) : undefined, protocol: parsed.protocol.replace(":", ""), pathStyle: true };
+}
+/** A missing or unreadable record means "nothing done yet", never a broken setup page. */
+async function readSetupRecord(dataDir) {
+    const fallback = defaultSetupRecord();
+    try {
+        const saved = JSON.parse(await readFile(setupRecordPath(dataDir), "utf8"));
+        return { ...fallback, ...saved, hooks: Array.isArray(saved?.hooks) ? saved.hooks : [] };
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeSetupRecord(dataDir, record) {
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const target = setupRecordPath(dataDir);
+    const temp = `${target}.${randomBytes(9).toString("hex")}.tmp`;
+    await writeFile(temp, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, target);
+}
+/**
+ * The unit this machine would run, built once for both installing and reading it
+ * back. The unit's path does not depend on its arguments, so a status read with
+ * different flags still finds the file an install wrote.
+ */
+function serviceOptionsFor(dataDir, environment, unit = {}) {
+    const invocation = daemonInvocation(dataDir, { reclaim: unit.reclaim });
+    return {
+        dataDir, executable: invocation.executable, args: invocation.args,
+        home: environment.home, platform: environment.platform, exec: environment.exec,
+        ...(unit.environment ? { environment: unit.environment } : {})
+    };
+}
+/**
+ * Everything the wizard needs to know about where it got to, assembled from the
+ * modules that already own each fact rather than from a progress flag.
+ *
+ * A vault that exists is the proof the vault step ran; a unit file on disk is
+ * the proof the service step ran. The only things read from the setup record
+ * are the two facts nothing else on the machine can answer: when the phrase was
+ * issued, and that a credential was stored.
+ */
+async function setupState(dataDir, environment) {
+    const [record, config, agents, beat] = await Promise.all([
+        readSetupRecord(dataDir),
+        readConfig(dataDir).catch(() => null),
+        detectSetupAgents(environment.home),
+        readHeartbeat(dataDir)
+    ]);
+    const service = await serviceStatus(serviceOptionsFor(dataDir, environment));
+    const installedHooks = agents.filter((agent) => agent.hooksInstalled).map((agent) => agent.agent);
+    // Kept apart because they are different offers to make: `ready` can be hooked
+    // by the next call, `manual` can only be handed a fragment to merge.
+    const readyHooks = agents.filter((agent) => agent.status === "ready").map((agent) => agent.agent);
+    const manualHooks = agents.filter((agent) => agent.status === "manual-merge-required").map((agent) => agent.agent);
+    const remote = config?.remoteStorage ?? null;
+    // Hooks and storage are skippable by design — §7 is explicit that stopping
+    // after the phrase must leave a working local-only vault — so `nextStep` is
+    // the next thing worth doing, not a gate the page has to pass.
+    const nextStep = !config ? "vault"
+        : installedHooks.length === 0 && readyHooks.length + manualHooks.length > 0 ? "hooks"
+            : !remote ? "storage"
+                : !service.present ? "service"
+                    : "done";
+    return {
+        vault: { created: config !== null, vaultId: config?.vaultId ?? null, dataDir, phraseIssuedAt: record.phraseIssuedAt, phraseRemembered: record.phraseRemembered },
+        hooks: { installed: installedHooks, ready: readyHooks, manual: manualHooks, detected: agents.filter((agent) => agent.detected).map((agent) => agent.agent) },
+        storage: {
+            configured: remote !== null,
+            provider: remote?.provider ?? null,
+            bucket: remote?.bucket ?? null,
+            prefix: remote?.prefix ?? null,
+            region: remote?.region ?? null,
+            endpoint: record.storageEndpoint,
+            // Presence only. There is no endpoint anywhere in this file that can turn
+            // this `true` back into the credential it describes.
+            credentialsStored: record.credentials !== null,
+            credentialsBackend: record.credentials?.backend ?? null,
+            credentialsStoredAt: record.credentials?.storedAt ?? null
+        },
+        service: { installed: service.present, kind: service.kind, path: service.path || null, liveness: liveness(beat) },
+        nextStep,
+        complete: config !== null && service.present
+    };
+}
+/**
+ * The loopback API shared by the CLI, dashboard, and MCP surfaces. It is the only
+ * place local surfaces read state from, so business logic is never duplicated.
+ *
+ * It deliberately cannot decrypt: no endpoint accepts a recovery phrase, and
+ * archive listings omit wrapped key material.
+ */
+export function createLocalApiServer(dataDir, token, options = {}) {
+    const queue = options.queue ?? new ArchiveQueue(dataDir);
+    // Jobs stranded by a restart or a closed page finish on their own: if the
+    // queue holds work and the keystore holds the phrase, sealing resumes now.
+    void ensureDraining(dataDir, queue);
+    const setupEnvironment = options.setup ?? {};
+    /**
+     * A promotion the control plane wants shown, fetched through this server
+     * because the dashboard speaks only to 127.0.0.1 — and cached, because an
+     * offer that changes weekly does not need fetching per page load. The
+     * content is Paul's to edit in the backend; an empty answer, a failed
+     * fetch, or a paying plan all mean "no banner", silently.
+     */
+    let offerCache = null;
+    async function currentOffer(plan) {
+        if (plan)
+            return null; // paying plans are not advertised to
+        if (offerCache && Date.now() - offerCache.at < 10 * 60_000)
+            return offerCache.value;
+        try {
+            const base = (process.env.VAULTLINE_CLOUD_URL ?? cloud.DEFAULT_CLOUD_URL).replace(/\/$/, "");
+            const response = await fetch(`${base}/v1/public/offer`, { signal: AbortSignal.timeout(4000) });
+            const body = response.ok ? await response.json() : null;
+            offerCache = { at: Date.now(), value: body?.offer ?? null };
+        }
+        catch {
+            offerCache = { at: Date.now(), value: null };
+        }
+        return offerCache.value;
+    }
+    let uploadRun = null;
+    let uploadAbort = null;
+    const uploadRunPath = join(dataDir, "upload-run.json");
+    const saveRun = () => {
+        // Fire-and-forget on purpose: run state is a progress report, not a ledger.
+        // What MUST survive a restart is the person's decision — cancelled stays
+        // cancelled — and the final shape of the last run, so a page opened after
+        // a restart shows what happened instead of amnesia.
+        if (uploadRun)
+            void writeFile(uploadRunPath, JSON.stringify(uploadRun), { mode: 0o600 }).catch(() => undefined);
+    };
+    // A run interrupted by a restart resumes itself; a run the person stopped
+    // stays stopped. This is read once at boot.
+    void (async () => {
+        try {
+            const prior = JSON.parse(await readFile(uploadRunPath, "utf8"));
+            if (prior.finishedAt || prior.cancelled) {
+                uploadRun = prior;
+                return;
+            }
+            // Active when the process died: resume by recomputing what is still
+            // pending — everything already verified skips naturally. The tallies
+            // start fresh; pretending continuity across a death would double-count.
+            const uploadConfig = await readConfig(dataDir);
+            const pendingRecords = (await listArchives(dataDir)).filter((item) => isV2(item) && !item.remote?.verifiedAt);
+            const pending = pendingRecords.map((item) => ({ id: item.id, bytes: isV2(item) ? item.cipher.storedBytes : 0 }));
+            if (pending.length === 0) {
+                uploadRun = { ...prior, finishedAt: new Date().toISOString() };
+                saveRun();
+                return;
+            }
+            uploadRun = {
+                startedAt: new Date().toISOString(), finishedAt: null, cancelled: false,
+                totalCount: pending.length, totalBytes: pending.reduce((sum, item) => sum + item.bytes, 0),
+                doneBytes: 0, freedBytes: 0, done: [], failed: [], current: null
+            };
+            saveRun();
+            const { storageEndpoint } = await readSetupRecord(dataDir);
+            void runUploads(pending, Boolean(uploadConfig.remoteStorage), uploadConfig.remoteStorage && storageEndpoint ? endpointOverrides(storageEndpoint) : undefined);
+        }
+        catch { /* no prior run, or unreadable — nothing to resume */ }
+    })();
+    async function runUploads(pending, viaOwnBucket, overrides) {
+        const run = uploadRun;
+        uploadAbort = new AbortController();
+        for (const item of pending) {
+            if (run.cancelled)
+                break;
+            run.current = { archiveId: item.id, bytes: item.bytes };
+            saveRun();
+            try {
+                if (viaOwnBucket) {
+                    const { uploadArchive } = await import("./upload.js");
+                    await uploadArchive(dataDir, item.id, overrides ? { overrides } : {});
+                }
+                else {
+                    await cloud.pushArchive(dataDir, item.id, undefined, { signal: uploadAbort.signal });
+                }
+                run.done.push({ archiveId: item.id, bytes: item.bytes });
+                run.doneBytes += item.bytes;
+                // The copy is verified remote as of seconds ago, which makes the local
+                // sealed blob a duplicate — Paul's model: the vault's home is the
+                // cloud; locally we keep originals and metadata, not a second copy of
+                // every gigabyte. Freed as the run goes, so a full disk breathes with
+                // each verify instead of after the whole run.
+                try {
+                    const { offloadArchives } = await import("./offload.js");
+                    const offload = await offloadArchives(dataDir, { confirm: true, only: new Set([item.id]), freshlyVerified: new Set([item.id]) });
+                    if (offload.mode === "apply")
+                        run.freedBytes += offload.freedBytes;
+                }
+                catch { /* offload is a bonus on this pass; the sweep gets another chance */ }
+            }
+            catch (error) {
+                run.failed.push({ archiveId: item.id, error: error instanceof Error ? error.message : "upload failed" });
+                // One archive's clear failure is a report; forty-eight identical ones
+                // are noise. When the account or the credentials are the problem,
+                // every remaining push fails the same way — stop and say so once.
+                if (isVaultlineError(error) && (error.code === "unauthorized" || error.code === "storage_not_configured" || error.code === "signer_not_configured"))
+                    break;
+            }
+            finally {
+                run.current = null;
+                saveRun();
+            }
+        }
+        run.finishedAt = new Date().toISOString();
+        uploadAbort = null;
+        saveRun();
+    }
+    return createServer(async (request, response) => {
+        try {
+            if (!LOOPBACK.has(request.socket.remoteAddress ?? ""))
+                return json(response, 403, { error: { code: "forbidden", message: "The local API accepts loopback connections only" } });
+            if (!hostAllowed(request))
+                return json(response, 403, { error: { code: "forbidden", message: "Unexpected Host header for a loopback service" } });
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            const method = request.method ?? "GET";
+            if (method === "GET" && url.pathname === "/health")
+                return json(response, 200, { ok: true, mode: "local-api", version: 1 });
+            // The dashboard shell is static and holds no vault data, so it loads before
+            // authentication; it then presents the token on every /v1 call below.
+            if (method === "GET" && !url.pathname.startsWith("/v1/")) {
+                return serveStatic(url.pathname === "/" ? await landingPage(dataDir) : url.pathname, response);
+            }
+            const via = authorizedVia(request, token);
+            if (!via)
+                return json(response, 401, { error: { code: "unauthorized", message: "A local API bearer token is required" } }, { "www-authenticate": "Bearer" });
+            // A browser that proved itself with the bearer once gets the HttpOnly
+            // cookie, so closing the tab does not mean typing the token again. The
+            // CLI receives it too and simply ignores it.
+            if (via === "bearer" && !(request.headers.cookie ?? "").includes("vaultline_token=")) {
+                response.setHeader("set-cookie", `vaultline_token=${token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=2592000`);
+            }
+            if (url.pathname === "/v1/recover" || url.pathname === "/v1/archives/decrypt") {
+                return json(response, 403, { error: { code: "forbidden", message: "Decryption is a local action. Use `sealkeep recover`; the local API never accepts a recovery phrase." } });
+            }
+            // The two secrets first-run setup handles, refused by name on every method
+            // that is not the one call allowed to produce them. Falling through to the
+            // 404 below would say the same thing far less clearly, and this is the
+            // rule PRODUCT_ARCHITECTURE.md §7 is least willing to see eroded.
+            if (method !== "POST" && (url.pathname === "/v1/setup/vault" || url.pathname === "/v1/setup/storage" || url.pathname === "/v1/setup/remember")) {
+                return json(response, 403, { error: { code: "forbidden", message: "The recovery phrase is returned once, by the call that generates it, and storage credentials are write-only. Neither can be read back." } });
+            }
+            if (method === "GET" && url.pathname === "/v1/status") {
+                // Everything here is read straight from the modules that already own it.
+                // Plan/quota/email are live when the control plane answers and the last
+                // remembered answer when it does not; `planSource` says which one this
+                // is, so the page can label a remembered value instead of hiding it.
+                const [vstatus, queueStats, beat, evaluation, cloud] = await Promise.all([
+                    vaultStatus(dataDir), queue.stats(), readHeartbeat(dataDir), evaluateRetention(dataDir), cloudPlanAndQuota(dataDir)
+                ]);
+                return json(response, 200, {
+                    ...vstatus, queue: queueStats,
+                    lastSyncAt: beat?.lastTickAt ?? null,
+                    plan: cloud.plan,
+                    quota: cloud.quota,
+                    accountEmail: cloud.email,
+                    planSource: cloud.source,
+                    // The upload run this server owns, if any — how the page shows
+                    // progress, offers cancel, and survives a refresh mid-run.
+                    upload: uploadRun,
+                    // Where the account is managed. A paying customer gets a door to
+                    // their cloud panel; the URL is derived from the same base the
+                    // API calls, so the two can never point at different places.
+                    panelUrl: cloud.plan ? await panelUrl() : null,
+                    nextReclaimWindow: nextReclaimWindow(evaluation, Date.now())
+                });
+            }
+            if (method === "GET" && url.pathname === "/v1/agents")
+                return json(response, 200, await detectAgents());
+            if (method === "GET" && url.pathname === "/v1/sessions") {
+                // Held jobs (disk guard) retry only when the drain is kicked, and the
+                // page polls this endpoint while anything is queued — so the poll IS
+                // the kick. Single-flighted and a stat call when nothing changed;
+                // the moment space frees, the waiting rows start sealing on their own.
+                void ensureDraining(dataDir, queue);
+                return json(response, 200, await listSessions(dataDir, queue));
+            }
+            if (method === "POST" && url.pathname === "/v1/sessions/archive") {
+                const { paths } = parseBody(archiveSelectionSchema, await readJsonBody(request));
+                return json(response, 200, await archiveSelected(dataDir, paths, queue));
+            }
+            // The bulk forms first, so the per-row routes never shadow them.
+            if (method === "POST" && url.pathname === "/v1/archives/check-copies") {
+                const body = (await readJsonBody(request));
+                const ids = Array.isArray(body?.ids) ? body.ids.filter((id) => typeof id === "string").slice(0, 500) : [];
+                if (ids.length === 0)
+                    fail("invalid_argument", "Pass ids: the archives whose copies to check.");
+                const { checkRemoteCopyMany } = await import("./offload.js");
+                const results = await checkRemoteCopyMany(dataDir, ids);
+                return json(response, 200, { results: results.map((item, index) => ({ id: ids[index], ...item })) });
+            }
+            if (method === "POST" && url.pathname === "/v1/archives/reclaim-batch") {
+                const body = (await readJsonBody(request));
+                const ids = Array.isArray(body?.ids) ? body.ids.filter((id) => typeof id === "string").slice(0, 500) : [];
+                if (ids.length === 0)
+                    fail("invalid_argument", "Pass ids: the sources to move to the trash.");
+                const { reclaimBatch } = await import("./retention.js");
+                return json(response, 200, await reclaimBatch(dataDir, ids, { confirm: body?.confirm === true }));
+            }
+            // Ask the storage, right now, whether the copy is really there — the
+            // question a person asks before trusting it enough to trash the source.
+            if (method === "POST" && /^\/v1\/archives\/[^/]+\/check-copy$/.test(url.pathname)) {
+                const archiveId = decodeURIComponent(url.pathname.split("/")[3]);
+                const { checkRemoteCopy } = await import("./offload.js");
+                return json(response, 200, await checkRemoteCopy(dataDir, archiveId));
+            }
+            // Reclaim ONE source because a person pointed at it. Hard gates only —
+            // verified copy (whole chain), unchanged source, file not in use; the
+            // click is the policy. See reclaimOne for the reasoning.
+            if (method === "POST" && /^\/v1\/archives\/[^/]+\/reclaim$/.test(url.pathname)) {
+                const archiveId = decodeURIComponent(url.pathname.split("/")[3]);
+                const body = (await readJsonBody(request));
+                const { reclaimOne } = await import("./retention.js");
+                const outcome = await reclaimOne(dataDir, archiveId, { confirm: body?.confirm === true });
+                return json(response, 200, { reclaimed: outcome });
+            }
+            if (method === "DELETE" && url.pathname.startsWith("/v1/archives/")) {
+                // Deleting an archive removes every copy Sealkeep holds of it — the
+                // local blob, the record, and the stored copy if one exists. Two
+                // truths decide how hard that is to do. If the original session file
+                // is still on disk, the person loses only the archive and can make
+                // another with one click. If the original is gone, this archive IS
+                // the session, and the server refuses until that is said back to it.
+                const archiveId = decodeURIComponent(url.pathname.slice("/v1/archives/".length));
+                const hasBody = typeof request.headers["content-length"] === "string" && request.headers["content-length"] !== "0";
+                const { confirm, confirmForever } = parseBody(deleteArchiveSchema, hasBody ? await readJsonBody(request) : {});
+                if (!confirm)
+                    fail("invalid_argument", "Deleting an archive removes Sealkeep's copies of this session. Resend with confirm: true.");
+                const config = await readConfig(dataDir);
+                const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+                if (!record)
+                    fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+                const sourceStillThere = await stat(record.source.path).then((entry) => entry.isFile()).catch(() => false);
+                if (!sourceStillThere && !confirmForever) {
+                    fail("invalid_argument", "The original session file is gone, so this archive is the only form this session exists in anywhere Sealkeep can see. Deleting it is forever. Nothing has been deleted — resend with confirmForever: true to do it with that knowledge.", { forever: true });
+                }
+                // The stored copy first: failing to delete remotely must not leave a
+                // record-less object nobody can find again. Reuses the same proven
+                // paths as the stored-copies page.
+                const fullRemote = isV2(record) ? record.remote : undefined;
+                const offloadedTo = isV2(record) ? record.offloaded : undefined;
+                const remoteProvider = fullRemote?.provider ?? offloadedTo?.provider;
+                if (remoteProvider === "vaultline") {
+                    if (fullRemote?.layout?.kind === "chunks") {
+                        // A managed chunk family deletes as a family: every chunk
+                        // reference plus the sidecar, through the same account verbs
+                        // that wrote them.
+                        const { deleteChunkFolder } = await import("./chunk-store.js");
+                        const { managedChunkClient } = await import("./managed-chunks.js");
+                        await deleteChunkFolder(managedChunkClient(dataDir), fullRemote);
+                    }
+                    else {
+                        const { deleteCloudArchive } = await import("./cloud.js");
+                        await deleteCloudArchive(dataDir, archiveId);
+                    }
+                }
+                else if (remoteProvider && fullRemote && config.remoteStorage && config.remoteStorage.provider !== "vaultline") {
+                    await deleteOwnObject(dataDir, { provider: config.remoteStorage.provider, bucket: config.remoteStorage.bucket, region: config.remoteStorage.region }, fullRemote);
+                }
+                const remote = remoteProvider !== undefined;
+                const { rm: removeFile } = await import("node:fs/promises");
+                await removeFile(record.objectPath, { force: true }).catch(() => undefined);
+                await removeFile(join(config.storage.root, `${archiveId}.json`), { force: true });
+                const { recordAudit } = await import("./audit.js");
+                await recordAudit(dataDir, "archive.delete", "allowed", { archiveId, hadRemote: remote, forever: !sourceStillThere }).catch(() => undefined);
+                return json(response, 200, { deleted: true, archiveId, removedRemote: remote, forever: !sourceStillThere });
+            }
+            if (method === "GET" && url.pathname === "/v1/archives") {
+                // Project identity, same derivation the Memory pool uses, so the two
+                // tables speak the same metadata. Claude paths carry theirs; a Codex
+                // rollout's cwd is read from the source file when it still exists —
+                // a reclaimed source honestly reads as no project rather than a guess.
+                const { claudeProjectFromPath, codexProjectFromRollout } = await import("./adapters.js");
+                const identify = async (record) => {
+                    try {
+                        if (record.source.agent === "claude")
+                            return claudeProjectFromPath(record.source.path);
+                        if (record.source.agent === "codex")
+                            return await codexProjectFromRollout(record.source.path, record.createdAt);
+                    }
+                    catch { /* an unreadable source is a null project, not an error */ }
+                    return { project: null, projectPath: null };
+                };
+                const { deltaOf } = await import("./vault.js");
+                const archives = await Promise.all((await listArchives(dataDir)).map(async (record) => ({
+                    id: record.id, createdAt: record.createdAt, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes,
+                    ciphertextSha256: record.cipher.ciphertextSha256, format: record.version,
+                    ...(await identify(record)),
+                    // Chain shape, so the vault can fold a session's snapshots into one
+                    // row: a delta names its base, and `supersedes` names the archive a
+                    // newer full snapshot re-covered.
+                    delta: deltaOf(record),
+                    supersedes: record.version === 2 && record.supersedes ? record.supersedes.archiveId : null,
+                    remote: record.version === 2 && record.remote ? { objectKey: record.remote.objectKey, verifiedAt: record.remote.verifiedAt } : null,
+                    // Whether the LOCAL blob was given back to the disk — with `remote`,
+                    // the page derives the three honest locations: here, cloud, or both.
+                    offloaded: record.version === 2 && record.offloaded ? true : false,
+                    reclaimed: record.version === 2 && record.reclaimed ? record.reclaimed.at : null
+                })));
+                return json(response, 200, archives);
+            }
+            if (method === "GET" && url.pathname === "/v1/queue")
+                return json(response, 200, await queue.list());
+            if (method === "GET" && url.pathname === "/v1/doctor")
+                return json(response, 200, await runDoctor(dataDir));
+            if (method === "GET" && url.pathname === "/v1/daemon") {
+                const beat = await readHeartbeat(dataDir);
+                return json(response, 200, { ...liveness(beat), watching: beat?.watching ?? [], last: beat?.last ?? null, startedAt: beat?.startedAt ?? null });
+            }
+            if (method === "GET" && url.pathname === "/v1/recipients")
+                return json(response, 200, (await readConfig(dataDir)).recipients ?? []);
+            if (method === "GET" && url.pathname === "/v1/retention")
+                return json(response, 200, await evaluateRetention(dataDir));
+            if (method === "POST" && url.pathname === "/v1/retention/apply") {
+                // `confirm` must be explicit: the API will not reclaim anything by default.
+                const { confirm } = parseBody(applySchema, await readJsonBody(request));
+                return json(response, 200, await applyRetention(dataDir, { confirm }));
+            }
+            if (method === "POST" && url.pathname === "/v1/upload") {
+                // Uploading needs no recovery phrase: the ciphertext already exists on
+                // disk. The call starts a background run and returns at once — the page
+                // watches it through /v1/status, can stop it, and can be refreshed
+                // without losing it. Pressing the button during a run just re-attaches.
+                if (uploadRun && !uploadRun.finishedAt)
+                    return json(response, 200, { started: false, alreadyRunning: true, upload: uploadRun });
+                // Two transports, chosen by how this vault stores remotely: a vault
+                // with its own bucket signs uploads itself; a managed vault pushes
+                // through the account. This endpoint used to know only the first, so
+                // on a managed vault every pending archive failed at once.
+                const uploadConfig = await readConfig(dataDir);
+                const pendingRecords = (await listArchives(dataDir)).filter((item) => isV2(item) && !item.remote?.verifiedAt);
+                const pending = pendingRecords.map((item) => ({ id: item.id, bytes: isV2(item) ? item.cipher.storedBytes : 0 }));
+                uploadRun = {
+                    startedAt: new Date().toISOString(), finishedAt: null, cancelled: false,
+                    totalCount: pending.length, totalBytes: pending.reduce((sum, item) => sum + item.bytes, 0),
+                    doneBytes: 0, freedBytes: 0, done: [], failed: [], current: null
+                };
+                if (pending.length === 0) {
+                    uploadRun.finishedAt = uploadRun.startedAt;
+                    saveRun();
+                    return json(response, 200, { started: true, upload: uploadRun });
+                }
+                saveRun();
+                const { storageEndpoint } = await readSetupRecord(dataDir);
+                void runUploads(pending, Boolean(uploadConfig.remoteStorage), uploadConfig.remoteStorage && storageEndpoint ? endpointOverrides(storageEndpoint) : undefined);
+                return json(response, 200, { started: true, upload: uploadRun });
+            }
+            if (method === "POST" && url.pathname === "/v1/upload/cancel") {
+                if (!uploadRun || uploadRun.finishedAt)
+                    return json(response, 200, { idle: true });
+                const hasCancelBody = typeof request.headers["content-length"] === "string" && request.headers["content-length"] !== "0";
+                const cancelBody = hasCancelBody ? await readJsonBody(request) : {};
+                uploadRun.cancelled = true;
+                saveRun();
+                if (cancelBody.hard) {
+                    // The transfer in flight is torn down mid-byte. A half-sent object
+                    // is unverified by construction — durable is only ever written after
+                    // proof — so nothing half-arrived can ever be trusted or reclaimed
+                    // against. The archive simply stays pending.
+                    uploadAbort?.abort();
+                    return json(response, 200, { cancelling: true, hard: true, note: "The transfer in flight was stopped mid-byte. Nothing half-sent counts as stored; that archive stays pending." });
+                }
+                return json(response, 200, { cancelling: true, note: "The archive being sent right now finishes and verifies; nothing after it starts." });
+            }
+            if (method === "POST" && url.pathname === "/v1/upload/rollback") {
+                // The other half of stopping: a person who changed their mind about
+                // this run can take back what it already uploaded. Each copy goes
+                // through the same delete used everywhere else — which refuses when
+                // the stored copy is the last one anywhere (an offloaded local means
+                // exactly that), per item, honestly.
+                if (!uploadRun)
+                    return json(response, 200, { idle: true, deleted: [], refused: [] });
+                // A run that is stopped-but-not-closed counts as decided: the person
+                // cancelled it; making them wait for a finishedAt stamp to take back
+                // uploads would be process trivia standing in front of their call.
+                if (!uploadRun.finishedAt && !uploadRun.cancelled)
+                    fail("invalid_argument", "The run is still going. Stop it first, then decide about what it uploaded.");
+                const rollbackDeleted = [];
+                const rollbackRefused = [];
+                for (const sent of uploadRun.done) {
+                    try {
+                        const record = (await listArchives(dataDir)).find((item) => item.id === sent.archiveId);
+                        const localCopy = record ? await stat(record.objectPath).then((entry) => entry.isFile()).catch(() => false) : false;
+                        if (!localCopy) {
+                            rollbackRefused.push({ archiveId: sent.archiveId, reason: "the stored copy is the only copy anywhere now — deleting it would lose the archive" });
+                            continue;
+                        }
+                        const { deleteCloudArchive } = await import("./cloud.js");
+                        await deleteCloudArchive(dataDir, sent.archiveId);
+                        if (record && record.version === 2 && record.remote) {
+                            const { remote: _gone, ...kept } = record;
+                            await writeRecord((await readConfig(dataDir)).storage.root, kept);
+                        }
+                        rollbackDeleted.push(sent.archiveId);
+                    }
+                    catch (error) {
+                        rollbackRefused.push({ archiveId: sent.archiveId, reason: error instanceof Error ? error.message : "delete failed" });
+                    }
+                }
+                const { recordAudit } = await import("./audit.js");
+                await recordAudit(dataDir, "archive.prune", "allowed", { rollback: true, deleted: rollbackDeleted.length, refused: rollbackRefused.length }).catch(() => undefined);
+                return json(response, 200, { deleted: rollbackDeleted, refused: rollbackRefused });
+            }
+            if (method === "GET" && url.pathname === "/v1/offer") {
+                const { plan } = await cloudPlanAndQuota(dataDir);
+                return json(response, 200, { offer: await currentOffer(plan) });
+            }
+            if (method === "DELETE" && url.pathname.startsWith("/v1/queue/")) {
+                // Taking a waiting job back out is an ordinary change of mind, not a
+                // destructive act: the session file is untouched, nothing has been
+                // written, and queueing it again is one click. The queue itself
+                // refuses the two cases where removal would mean something else.
+                const jobIdToRemove = decodeURIComponent(url.pathname.slice("/v1/queue/".length));
+                return json(response, 200, { removed: await queue.remove(jobIdToRemove) });
+            }
+            if (method === "POST" && url.pathname === "/v1/queue") {
+                const input = parseBody(enqueueSchema, await readJsonBody(request));
+                const { job, deduped } = await queue.enqueue(input);
+                return json(response, deduped ? 200 : 201, { job, deduped });
+            }
+            if (method === "PUT" && url.pathname === "/v1/retention/policy") {
+                // Returns the fresh evaluation, not just the saved settings: changing a
+                // rule is only meaningful through what it now protects or releases, and
+                // making the page ask twice would show it a moment out of date.
+                const settings = parseBody(retentionPolicySchema, await readJsonBody(request));
+                await setRetentionPolicy(dataDir, settings);
+                return json(response, 200, await evaluateRetention(dataDir));
+            }
+            if (method === "POST" && url.pathname === "/v1/retention/preview") {
+                const { olderThanDays } = parseBody(retentionSchema, await readJsonBody(request));
+                return json(response, 200, await previewRetention(dataDir, olderThanDays));
+            }
+            if (method === "GET" && url.pathname === "/v1/settings") {
+                const settings = await readLocalSettings(dataDir);
+                return json(response, 200, {
+                    local: settings,
+                    resolvedTrashStrategy: settings.trashStrategy === "auto" ? defaultStrategy() : settings.trashStrategy,
+                    remote: await remoteSettingsMirror(dataDir)
+                });
+            }
+            if (method === "PUT" && url.pathname === "/v1/settings") {
+                const { confirm, ...patch } = parseBody(localSettingsSchema, await readJsonBody(request));
+                const current = await readLocalSettings(dataDir);
+                // Turning reclaim on lets the daemon start moving files to the trash on
+                // its own the next time it runs, so it earns the same explicit confirm
+                // the reclaim endpoint itself already requires before it acts.
+                if (patch.reclaimEnabled === true && !current.reclaimEnabled && !confirm) {
+                    fail("invalid_argument", "Turning on reclaim changes what this machine does automatically; resend with confirm: true");
+                }
+                const next = {
+                    ...current, ...patch,
+                    schedule: { ...current.schedule, ...patch.schedule },
+                    bandwidth: { ...current.bandwidth, ...patch.bandwidth }
+                };
+                await writeLocalSettings(dataDir, next);
+                return json(response, 200, {
+                    local: next,
+                    resolvedTrashStrategy: next.trashStrategy === "auto" ? defaultStrategy() : next.trashStrategy,
+                    remote: await remoteSettingsMirror(dataDir)
+                });
+            }
+            // ---- Stored copies: see and clean what is held off this machine --------
+            if (method === "GET" && url.pathname === "/v1/cloud/copies") {
+                const mode = await storedCopiesMode(dataDir);
+                const presence = await localArchivePresence(dataDir);
+                let copies = [];
+                if (mode === "managed") {
+                    const { listCloudArchives } = await import("./cloud.js");
+                    // Chunk families fold into one row per archive: the page reasons
+                    // about archives, and the family's bytes are its chunk sum.
+                    const { collapseCloudRows } = await import("./managed-chunks.js");
+                    copies = collapseCloudRows(await listCloudArchives(dataDir)).map((row) => ({
+                        ref: row.vault_ref,
+                        bytes: Number(row.bytes) || 0,
+                        addedAt: row.durable_at ?? row.created_at ?? null,
+                        state: row.state,
+                        // A ref this machine has no bytes for — archived elsewhere, or
+                        // already offloaded — is a last copy from where this page stands.
+                        lastCopy: presence.get(row.vault_ref) !== true
+                    }));
+                }
+                else if (mode === "own") {
+                    // remote.verifiedAt is the stored set: it is only ever written after
+                    // storage proved it holds the bytes, on either upload path.
+                    copies = (await listArchives(dataDir).catch(() => [])).flatMap((record) => record.version === 2 && record.remote?.verifiedAt
+                        ? [{ ref: record.id, bytes: record.remote.bytes, addedAt: record.remote.verifiedAt, state: "durable", lastCopy: presence.get(record.id) !== true }]
+                        : []);
+                }
+                return json(response, 200, { copies, mode, rollingCapGb: await readRollingCap(dataDir) });
+            }
+            const copyMatch = /^\/v1\/cloud\/copies\/([^/]+)$/.exec(url.pathname);
+            if (method === "DELETE" && copyMatch) {
+                // A body is optional on DELETE — the page sends one, a curl need not.
+                const hasBody = typeof request.headers["content-length"] === "string" && request.headers["content-length"] !== "0";
+                const { confirmLastCopy } = parseBody(deleteCopySchema, hasBody ? await readJsonBody(request) : {});
+                const ref = decodeURIComponent(copyMatch[1]);
+                const mode = await storedCopiesMode(dataDir);
+                if (mode === "none")
+                    fail("archive_not_found", "No storage is connected to this vault, so there is no stored copy to delete. Nothing has changed.");
+                const config = await readConfig(dataDir);
+                const record = (await listArchives(dataDir)).find((item) => item.id === ref);
+                const localCopy = record ? await stat(record.objectPath).then((entry) => entry.isFile()).catch(() => false) : false;
+                if (!localCopy && !confirmLastCopy) {
+                    // `lastCopy: true` rides in the payload so the page can recognise
+                    // this refusal structurally instead of matching prose that may change.
+                    fail("invalid_argument", "This stored copy is the last one anywhere: this machine no longer holds the archive's bytes, so deleting it would lose the archive for good. Nothing has been deleted. Restore the archive first if you want a copy back, or resend with confirmLastCopy: true to delete it with that knowledge.", { lastCopy: true });
+                }
+                if (mode === "managed") {
+                    const { deleteCloudArchive, listCloudArchives } = await import("./cloud.js");
+                    if (record && record.version === 2 && record.remote?.layout?.kind === "chunks") {
+                        const { deleteChunkFolder } = await import("./chunk-store.js");
+                        const { managedChunkClient } = await import("./managed-chunks.js");
+                        await deleteChunkFolder(managedChunkClient(dataDir), record.remote);
+                    }
+                    else {
+                        // No local record to derive the family from (the collapsed-row
+                        // case): the account's own listing names the members, and a ref
+                        // with no members deletes as the single object it is.
+                        const rows = await listCloudArchives(dataDir);
+                        const members = rows.map((row) => row.vault_ref).filter((member) => member === ref || member.startsWith(`${ref}.`));
+                        for (const member of members.length > 0 ? members : [ref])
+                            await deleteCloudArchive(dataDir, member);
+                    }
+                }
+                else {
+                    const storage = config.remoteStorage;
+                    if (!storage)
+                        fail("storage_not_configured", "This vault has no bucket of its own to delete from.");
+                    const provider = storage.provider;
+                    if (provider === "vaultline")
+                        fail("storage_not_configured", "This vault has no bucket of its own to delete from.");
+                    if (!record || record.version !== 2 || !record.remote) {
+                        fail("archive_not_found", `No stored copy is recorded for ${ref}, so there is nothing to delete. Nothing has changed.`);
+                    }
+                    await deleteOwnObject(dataDir, { provider, bucket: storage.bucket, region: storage.region }, record.remote);
+                }
+                // Clear the remote marker on both paths, not just bring-your-own:
+                // retention reads remote.verifiedAt as permission to reclaim the local
+                // source, and a verified remote that was just deleted is permission to
+                // lose data. The record stays; only its claim to an off-machine copy goes.
+                if (record && record.version === 2 && record.remote) {
+                    const { remote: _deleted, ...kept } = record;
+                    await writeRecord(config.storage.root, kept);
+                }
+                const { recordAudit } = await import("./audit.js");
+                await recordAudit(dataDir, "archive.prune", "allowed", { archiveId: ref, remote: true, mode, lastCopy: !localCopy }).catch(() => undefined);
+                return json(response, 200, { deleted: true, ref, mode, lastCopy: !localCopy });
+            }
+            if (method === "PUT" && url.pathname === "/v1/cloud/rolling") {
+                // A thin proxy for a rule the account owns. The control plane has a
+                // dedicated PUT /v1/cloud/rolling (backed by account_pref and enforced
+                // hourly by trim-to-rolling-cap, oldest first, audited) — the cap goes
+                // straight there, and is only cached here once the account accepted it.
+                // Caching an unsent cap would be a settings page saying "Saved" about a
+                // rule nothing will ever enforce.
+                const { capGb } = parseBody(rollingCapSchema, await readJsonBody(request));
+                const { cloudToken, DEFAULT_CLOUD_URL } = await import("./cloud.js");
+                const token = await cloudToken(dataDir);
+                const base = (process.env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+                const pushed = await fetch(`${base}/v1/cloud/rolling`, {
+                    method: "PUT",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+                    body: JSON.stringify({ capGb })
+                }).catch(() => null);
+                if (!pushed || !pushed.ok) {
+                    fail("internal", `Your account could not take the setting${pushed ? ` (${pushed.status})` : ""}, so the cap was not saved. Your stored copies are untouched; try again in a moment.`);
+                }
+                await writeRollingCap(dataDir, capGb);
+                return json(response, 200, { capGb, savedToAccount: true });
+            }
+            // ---- First-run setup (PRODUCT_ARCHITECTURE.md §7) ----------------------
+            // Nothing below reads a secret back. The phrase leaves this process once,
+            // in the response to the call that generated it; credentials leave the
+            // process only into the OS keystore and are never read here at all.
+            if (method === "GET" && url.pathname === "/v1/setup/state")
+                return json(response, 200, await setupState(dataDir, setupEnvironment));
+            // Deliberately a different list from GET /v1/agents: that one answers
+            // "what can Sealkeep archive" and so names only the agents with a
+            // session adapter, while this one answers "what is on this machine and
+            // could be hooked", which is a wider and more honest question for a page
+            // asking somebody to choose.
+            if (method === "GET" && url.pathname === "/v1/setup/agents")
+                return json(response, 200, await detectSetupAgents(setupEnvironment.home));
+            if (method === "POST" && url.pathname === "/v1/setup/remember") {
+                // The one other place a phrase may cross the loopback boundary, and for
+                // the same reason the wizard's vault call may: to put it in this
+                // machine's keystore so the machine can seal unattended. It is checked
+                // against the vault first — storing a wrong phrase would make every
+                // later archive fail in a way that blamed the phrase — and it is never
+                // echoed back, logged, or kept in this process past the call.
+                const { phrase } = parseBody(rememberSchema, await readJsonBody(request));
+                const config = await readConfig(dataDir);
+                const { canonicalPhrase } = await import("./mnemonic.js");
+                const { phraseCheck, equalHex } = await import("./crypto.js");
+                if (!equalHex(config.recovery.phraseCheck, phraseCheck(canonicalPhrase(phrase)))) {
+                    fail("recovery_phrase_mismatch", "That is not this vault's recovery phrase. Nothing was stored.");
+                }
+                const remembered = await rememberRecoveryPhrase(dataDir, config.vaultId, canonicalPhrase(phrase));
+                await writeSetupRecord(dataDir, { ...(await readSetupRecord(dataDir)), phraseRemembered: remembered !== null });
+                return json(response, 200, { remembered: remembered !== null, backend: remembered?.backend ?? null });
+            }
+            if (method === "GET" && url.pathname === "/v1/setup/unlock-check") {
+                // What the page needs before it can offer a password form — does a lock
+                // exist, and is unlocking even necessary — stated without touching
+                // either secret. `phraseRemembered` asks the keystore, not setup.json,
+                // because the page is about to act on the answer.
+                const config = await readConfig(dataDir).catch(() => null);
+                const phraseRemembered = config !== null && (await recallRecoveryPhrase(dataDir, config.vaultId).catch(() => null)) !== null;
+                return json(response, 200, { passwordLock: await hasPasswordLock(dataDir), phraseRemembered });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/unlock") {
+                // The password is traded for the phrase entirely inside this process:
+                // on success the phrase goes into the machine keystore so background
+                // sealing works again, and the response says only that it did. The
+                // phrase itself never crosses HTTP here — the one call that may return
+                // it remains the one that generated it.
+                const { password } = parseBody(setupUnlockSchema, await readJsonBody(request));
+                if (!(await hasPasswordLock(dataDir))) {
+                    fail("invalid_argument", "This vault has no password on this machine, so a password cannot unlock it. Nothing has changed. Unlock with your recovery phrase instead.");
+                }
+                const phrase = await unwrapPhrase(dataDir, password);
+                if (phrase === null)
+                    fail("forbidden", "That password does not open this vault. Nothing has changed.");
+                const config = await readConfig(dataDir);
+                let remembered = false;
+                try {
+                    remembered = (await rememberRecoveryPhrase(dataDir, config.vaultId, phrase)) !== null;
+                }
+                catch {
+                    remembered = false;
+                }
+                if (remembered) {
+                    await writeSetupRecord(dataDir, { ...(await readSetupRecord(dataDir)), phraseRemembered: true });
+                    // The keystore holds the phrase again, so work stranded while the
+                    // vault was locked can finish without waiting for the next archive.
+                    void ensureDraining(dataDir, queue);
+                }
+                return json(response, 200, { unlocked: true, remembered });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/vault") {
+                const { confirm, remember, password, storageMode } = parseBody(setupVaultSchema, await readJsonBody(request));
+                if (!confirm) {
+                    fail("invalid_argument", "Creating the vault generates a recovery phrase that is shown exactly once and can never be fetched again. Show that warning, then resend with confirm: true.");
+                }
+                // `initialize` refuses an existing vault, so this cannot become the
+                // endpoint that quietly replaces a working one with a new phrase.
+                const { config, phrase } = await initialize(dataDir, undefined, { storageMode });
+                const notes = [];
+                let remembered = null;
+                if (remember) {
+                    try {
+                        remembered = await rememberRecoveryPhrase(dataDir, config.vaultId, phrase);
+                    }
+                    catch (error) {
+                        notes.push(`This machine's keystore refused the phrase (${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}). The background service will need VAULTLINE_RECOVERY_PHRASE in its environment.`);
+                    }
+                }
+                else {
+                    notes.push("The phrase was not stored on this machine, so the background service cannot seal sessions until VAULTLINE_RECOVERY_PHRASE is in its environment.");
+                }
+                if (password) {
+                    // Failure may not cost the person this response: the vault already
+                    // exists and the phrase above is being shown exactly once, so a lock
+                    // that cannot be written becomes a note, never an error.
+                    try {
+                        await wrapPhrase(dataDir, phrase, password);
+                    }
+                    catch {
+                        notes.push("Your password could not be saved on this machine. Nothing else changed: the recovery phrase shown here still opens this vault, and you can choose a password again later.");
+                    }
+                }
+                // The time and the fact, never the phrase. This is the whole of what
+                // setup writes down about it.
+                await writeSetupRecord(dataDir, { ...(await readSetupRecord(dataDir)), phraseIssuedAt: new Date().toISOString(), phraseRemembered: remembered !== null });
+                return json(response, 201, {
+                    vaultId: config.vaultId,
+                    dataDir,
+                    recoveryPhrase: phrase,
+                    wordCount: phrase.split(/\s+/).filter(Boolean).length,
+                    shownOnce: true,
+                    remembered,
+                    notes,
+                    warning: "This is the only time Sealkeep will show this phrase. Write it down now: no endpoint can return it again, and without it these archives cannot be opened."
+                });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/hooks") {
+                const { agents, confirm } = parseBody(setupHooksSchema, await readJsonBody(request));
+                // Hook installation edits a file that belongs to another program, so it
+                // gets the same explicit confirm /v1/retention/apply requires before it
+                // touches anything of the user's.
+                if (!confirm)
+                    fail("invalid_argument", "Installing hooks edits another program's configuration. Resend with confirm: true.");
+                const results = await installAgentHooks(agents, { dataDir, home: setupEnvironment.home });
+                const record = await readSetupRecord(dataDir);
+                const installedAt = new Date().toISOString();
+                await writeSetupRecord(dataDir, {
+                    ...record,
+                    hooks: [
+                        ...record.hooks.filter((hook) => !agents.includes(hook.agent)),
+                        ...results.filter((result) => result.installed).map((result) => ({ agent: result.agent, installedAt, hookFile: result.hookFile }))
+                    ]
+                });
+                /**
+                 * Choosing an agent means both halves: Sealkeep captures its sessions
+                 * (the hook) and the agent can ask about them afterwards (the MCP
+                 * server). Splitting those into two decisions produced a product where
+                 * the recall half shipped, was installed by nothing, and was findable
+                 * only by reading the source.
+                 *
+                 * The MCP server is registered locally and stays local, because
+                 * everything it needs is: the content index, the archives and the key
+                 * that opens them. Nothing about answering "what did I do last time"
+                 * requires a server, so nothing about it goes to one.
+                 *
+                 * It never fails the hook install. Capture is the part that cannot be
+                 * caught up on — a session not recorded today is gone — while recall
+                 * can be registered any time afterwards with `sealkeep mcp install`.
+                 */
+                const { installMcpServer } = await import("./mcp-install.js");
+                const mcp = await installMcpServer(dataDir, { home: setupEnvironment.home })
+                    .catch((error) => ({ agents: [], error: error instanceof Error ? error.message : "could not register the MCP server" }));
+                // The re-detection is the proof, not the claim: it re-reads the agents'
+                // own files rather than echoing what the installer believed it did.
+                return json(response, 200, { results, mcp, agents: await detectSetupAgents(setupEnvironment.home) });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/enroll") {
+                // Linking this machine to an account someone already has, using the
+                // pairing code the panel actually issues — the button there reads "Show
+                // a pairing code", and it is spent against /cli/exchange together with
+                // the account's email.
+                //
+                // This deliberately does not use `enroll()`. That path wants a
+                // different code, from a "Devices > Add device" screen that does not
+                // exist in the panel, so pointing anyone at it would be sending them to
+                // look for something that was never built.
+                //
+                // A code and an email, never a password and never a recovery phrase, so
+                // the rule that no endpoint accepts a phrase is untouched: what this
+                // grants is quota, storage and settings, not the ability to open an
+                // archive.
+                const { email, code } = parseBody(enrollSchema, await readJsonBody(request));
+                const { loginWithCode } = await import("./cloud.js");
+                const account = await loginWithCode(dataDir, { email, token: code });
+                return json(response, 200, { account: { plan: account.plan, email: account.email, quotaBytes: account.quota_bytes, usedBytes: account.used_bytes } });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/storage/test") {
+                return json(response, 200, await testStorageTarget(parseBody(setupStorageSchema, await readJsonBody(request))));
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/storage") {
+                const { credentials, confirm, endpoint, ...target } = parseBody(setupStorageSchema, await readJsonBody(request));
+                // No vault means no vault id to file the credential under, and
+                // `readConfig` already fails with the instruction that says so.
+                const config = await readConfig(dataDir);
+                const record = await readSetupRecord(dataDir);
+                if ((config.remoteStorage || record.credentials) && !confirm) {
+                    fail("invalid_argument", "This machine already has storage configured; replacing it changes where archives go and which credential signs for them. Resend with confirm: true.");
+                }
+                // The same pairing the upload client enforces (providers/index.ts),
+                // checked here so a service-account key pasted into an S3 form is
+                // refused while the person is still looking at the form.
+                if ((target.provider === "gcs") !== ("clientEmail" in credentials)) {
+                    fail("invalid_argument", target.provider === "gcs"
+                        ? "GCS needs a service-account credential (clientEmail and privateKey), not an access key"
+                        : `${target.provider} needs an access-key credential (accessKeyId and secretAccessKey), not a service account`);
+                }
+                // R2 signs against a per-account host that cannot be derived from the
+                // bucket — providers/s3.ts refuses without it — so refusing here beats
+                // storing a configuration that could never upload.
+                if (target.provider === "r2" && !endpoint)
+                    fail("invalid_argument", "R2 needs its endpoint: https://<account-id>.r2.cloudflarestorage.com");
+                if (endpoint)
+                    assertHttpUrl(endpoint);
+                await configureRemoteStorage(dataDir, { provider: target.provider, bucket: target.bucket, prefix: target.prefix, ...(target.region ? { region: target.region } : {}) });
+                // Uploads look the credential up by the vault id (see `uploadArchive`),
+                // so filing it under anything else files it where nothing looks.
+                const stored = await storeProviderCredentials(dataDir, config.vaultId, credentials);
+                await writeSetupRecord(dataDir, {
+                    ...record,
+                    storageEndpoint: endpoint ?? null,
+                    credentials: { storedAt: new Date().toISOString(), backend: stored.backend, storageConfigId: config.vaultId }
+                });
+                // The credential is gone from this process now. What comes back is the
+                // same storage view GET /v1/setup/state serves: configuration, and the
+                // fact that a credential exists.
+                return json(response, 200, { storage: (await setupState(dataDir, setupEnvironment)).storage });
+            }
+            if (method === "POST" && url.pathname === "/v1/setup/service") {
+                const { confirm, reclaim } = parseBody(setupServiceSchema, await readJsonBody(request));
+                if (!confirm)
+                    fail("invalid_argument", "Installing the background service makes this machine run Sealkeep at every login. Resend with confirm: true.");
+                const config = await readConfig(dataDir);
+                const record = await readSetupRecord(dataDir);
+                // Idempotent on purpose: `launchctl load` on an already-loaded unit
+                // fails, so a second call would report an install failure for a service
+                // that is running perfectly well.
+                const existing = await serviceStatus(serviceOptionsFor(dataDir, setupEnvironment));
+                if (existing.present) {
+                    return json(response, 200, { service: { kind: existing.kind, installed: true, alreadyInstalled: true, path: existing.path, ranCommands: [], note: null }, phraseAvailable: record.phraseRemembered });
+                }
+                const outcome = await installService(serviceOptionsFor(dataDir, setupEnvironment, {
+                    reclaim,
+                    // A service manager starts the daemon with a bare environment. Without
+                    // this the upload pass is off, and because reclaiming requires a
+                    // verified remote copy it would never free a byte either — see the
+                    // note on `environment` in service.ts. serviceUnitEnvironment adds
+                    // the secret-backend choice, without which the daemon cannot unlock.
+                    environment: serviceUnitEnvironment(config.remoteStorage ? { VAULTLINE_ENABLE_SIGNER: "1" } : {})
+                }));
+                return json(response, outcome.installed ? 201 : 200, {
+                    service: { kind: outcome.kind, installed: outcome.installed, alreadyInstalled: false, path: outcome.path, ranCommands: outcome.ranCommands, note: outcome.note ?? null },
+                    phraseAvailable: record.phraseRemembered
+                });
+            }
+            return json(response, 404, { error: { code: "invalid_argument", message: `No such endpoint: ${method} ${url.pathname}` } });
+        }
+        catch (error) {
+            const payload = errorPayload(error);
+            return json(response, isVaultlineError(error) ? STATUS_BY_CODE[error.code] ?? 400 : 500, payload);
+        }
+    });
+}