sealkeep 0.9.0 → 0.11.0

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

@@ -35,8 +35,8 @@ const enrollSchema = z.object({
     label: z.string().min(1).max(120),
     publicKey: z.string().min(40).max(100)
 }).strict();
-function json(response, status, value) {
-    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+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));
 }
 async function readBody(request) {
@@ -84,11 +84,24 @@ export function createControlPlaneServer(options = {}) {
         let status = 500;
         let deviceId;
         try {
-            const limitKey = request.headers["x-vaultline-device"] ?? request.socket.remoteAddress ?? "anonymous";
-            if (!limiter.take(limitKey, now())) {
+            // The remote address is not caller-controlled. Using the presented
+            // device header here let an unauthenticated caller rotate fake ids and
+            // mint an unlimited number of fresh buckets before signature checking.
+            const limitKey = request.socket.remoteAddress ?? "anonymous";
+            const limited = limiter.consume(limitKey, now());
+            if (!limited.allowed) {
                 status = 429;
                 store.audit({ action: `${method} ${url.pathname}`, outcome: "denied", detail: { reason: "rate_limited" } });
-                return json(response, 429, { error: { code: "rate_limited", message: "Too many requests" } });
+                const retryAfterSeconds = Math.max(1, Math.ceil(limited.retryAfterMs / 1_000));
+                return json(response, 429, { error: {
+                        code: "rate_limited", message: "Too many requests",
+                        retryAfterMs: limited.retryAfterMs, retryAt: new Date(now() + limited.retryAfterMs).toISOString(),
+                    } }, {
+                    "retry-after": String(retryAfterSeconds),
+                    "ratelimit-limit": String(limiter.capacity),
+                    "ratelimit-remaining": String(limited.remaining),
+                    "ratelimit-reset": String(Math.ceil(limited.resetAt / 1_000)),
+                });
             }
             if (method === "GET" && url.pathname === "/health") {
                 status = 200;
@@ -179,7 +192,7 @@ export function createControlPlaneServer(options = {}) {
                     return json(response, 402, { error: { code: "quota_exceeded", message: "This account has no remaining quota" } });
                 }
                 // The object key is allocated here. A client cannot choose where its bytes land.
-                const objectKey = `${config.prefix.replace(/^\/+|\/+$/g, "")}/${input.archiveId}.vlarchive`;
+                const objectKey = `${config.prefix.replace(/^\/+|\/+$/g, "")}/${input.archiveId}.skarchive`;
                 const issuedAt = now();
                 const lease = store.addLease({
                     id: randomUUID(), accountId: device.accountId, deviceId: device.id, archiveId: input.archiveId, storageConfigId: config.id,

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

@@ -53,7 +53,23 @@ export declare function leaseExpired(lease: UploadLease, now?: number): boolean;
  * replayed lease is refused as expired rather than as an unsigned lease.
  */
 export declare function assertLeaseUsable(lease: UploadLease, now?: number): void;
-/** Feature flag for provider work in progress. Off by default and read per call so tests and operators can flip it. */
+export type DaemonSignerGrant = {
+    release(): void;
+};
+/**
+ * Grants provider-signing capability to one running daemon instance.
+ *
+ * The grant is process-local and lifetime-scoped: it does not modify the
+ * environment or make a separate CLI process upload-capable. Reference
+ * counting matters for embedded/test processes which legitimately host more
+ * than one daemon for different vaults.
+ */
+export declare function acquireDaemonSignerGrant(): DaemonSignerGrant;
+/**
+ * Explicit operator enablement, or a capability held by a live daemon.
+ * Supplying an environment is a hermetic check: callers which deliberately
+ * pass `{}` must not inherit capability from another daemon in this process.
+ */
 export declare function signerEnabled(env?: NodeJS.ProcessEnv): boolean;
 /**
  * The contract a real S3/R2/GCS client will implement. Credentials belong to the

package/dist/src/control-plane.js

@@ -18,7 +18,7 @@ class PlannedProvider {
         // Deliberately non-functional until real credential-backed signers are configured.
         return {
             archiveId, provider: this.provider,
-            objectKey: `${config.prefix.replace(/\/$/, "")}/${archiveId}.vlarchive`,
+            objectKey: `${config.prefix.replace(/\/$/, "")}/${archiveId}.skarchive`,
             expiresAt: new Date(issuedAt + (input.ttlMs ?? DEFAULT_LEASE_TTL_MS)).toISOString(),
             method: this.method,
             uploadUrl: `vaultline+pending://${this.provider}/${config.bucket}/${archiveId}`,
@@ -43,18 +43,44 @@ export function assertLeaseUsable(lease, now = Date.now()) {
     if (!lease.uploadable || lease.status !== "active")
         fail("signer_not_configured", "This lease cannot upload: no credential-backed signer is configured", { provider: lease.provider, archiveId: lease.archiveId });
 }
-/** Feature flag for provider work in progress. Off by default and read per call so tests and operators can flip it. */
-export function signerEnabled(env = process.env) {
-    return envVar("ENABLE_SIGNER", env) === "1";
+let daemonSignerGrants = 0;
+/**
+ * Grants provider-signing capability to one running daemon instance.
+ *
+ * The grant is process-local and lifetime-scoped: it does not modify the
+ * environment or make a separate CLI process upload-capable. Reference
+ * counting matters for embedded/test processes which legitimately host more
+ * than one daemon for different vaults.
+ */
+export function acquireDaemonSignerGrant() {
+    daemonSignerGrants += 1;
+    let held = true;
+    return {
+        release() {
+            if (!held)
+                return;
+            held = false;
+            daemonSignerGrants = Math.max(0, daemonSignerGrants - 1);
+        },
+    };
+}
+/**
+ * Explicit operator enablement, or a capability held by a live daemon.
+ * Supplying an environment is a hermetic check: callers which deliberately
+ * pass `{}` must not inherit capability from another daemon in this process.
+ */
+export function signerEnabled(env) {
+    return envVar("ENABLE_SIGNER", env ?? process.env) === "1"
+        || (env === undefined && daemonSignerGrants > 0);
 }
 const uploadClients = new Map();
 /** Registration is refused unless the operator explicitly enabled signer work. */
-export function registerUploadClient(client, env = process.env) {
+export function registerUploadClient(client, env) {
     if (!signerEnabled(env))
         fail("signer_not_configured", "Set SEALKEEP_ENABLE_SIGNER=1 to register a provider upload client", { provider: client.kind });
     uploadClients.set(client.kind, client);
 }
-export function uploadClientFor(kind, env = process.env) {
+export function uploadClientFor(kind, env) {
     const client = signerEnabled(env) ? uploadClients.get(kind) : undefined;
     return client ?? fail("signer_not_configured", `No upload client is available for ${kind}. Sealkeep cannot upload until a reviewed signer with isolated credentials exists.`, { provider: kind, signerEnabled: signerEnabled(env) });
 }

package/dist/src/crypto.d.ts

@@ -43,7 +43,7 @@ export declare function encryptLegacyArchive(plaintext: Buffer, phrase: string):
         ciphertext: string;
     };
 };
-/** @deprecated Format v1 reader. New archives use `vaultline-crypto`. */
+/** @deprecated Format v1 reader. New archives use `sealkeep-crypto`. */
 export declare function decryptLegacyArchive(ciphertext: Buffer, envelope: {
     nonce: string;
     authTag: string;

package/dist/src/crypto.js

@@ -96,14 +96,14 @@ export function encryptLegacyArchive(plaintext, phrase) {
     const archiveKey = randomBytes(KEY_BYTES);
     const nonce = randomBytes(NONCE_BYTES);
     const cipher = createCipheriv("aes-256-gcm", archiveKey, nonce, { authTagLength: TAG_BYTES });
-    cipher.setAAD(Buffer.from("vaultline-archive:v1"));
+    cipher.setAAD(Buffer.from("sealkeep-archive:v1"));
     const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const authTag = cipher.getAuthTag();
     const salt = randomBytes(16);
     const wrapNonce = randomBytes(NONCE_BYTES);
     const wrappingKey = recoveryKey(phrase, salt);
     const wrapper = createCipheriv("aes-256-gcm", wrappingKey, wrapNonce, { authTagLength: TAG_BYTES });
-    wrapper.setAAD(Buffer.from("vaultline-wrapped-key:v1"));
+    wrapper.setAAD(Buffer.from("sealkeep-wrapped-key:v1"));
     const wrapped = Buffer.concat([wrapper.update(archiveKey), wrapper.final()]);
     return {
         ciphertext,
@@ -118,15 +118,15 @@ export function encryptLegacyArchive(plaintext, phrase) {
         }
     };
 }
-/** @deprecated Format v1 reader. New archives use `vaultline-crypto`. */
+/** @deprecated Format v1 reader. New archives use `sealkeep-crypto`. */
 export function decryptLegacyArchive(ciphertext, envelope, phrase) {
     const wrappingKey = recoveryKey(phrase, Buffer.from(envelope.wrappedKey.salt, "base64url"));
     const unwrap = createDecipheriv("aes-256-gcm", wrappingKey, Buffer.from(envelope.wrappedKey.nonce, "base64url"), { authTagLength: TAG_BYTES });
-    unwrap.setAAD(Buffer.from("vaultline-wrapped-key:v1"));
+    unwrap.setAAD(Buffer.from("sealkeep-wrapped-key:v1"));
     unwrap.setAuthTag(Buffer.from(envelope.wrappedKey.authTag, "base64url"));
     const archiveKey = Buffer.concat([unwrap.update(Buffer.from(envelope.wrappedKey.ciphertext, "base64url")), unwrap.final()]);
     const decipher = createDecipheriv("aes-256-gcm", archiveKey, Buffer.from(envelope.nonce, "base64url"), { authTagLength: TAG_BYTES });
-    decipher.setAAD(Buffer.from("vaultline-archive:v1"));
+    decipher.setAAD(Buffer.from("sealkeep-archive:v1"));
     decipher.setAuthTag(Buffer.from(envelope.authTag, "base64url"));
     return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
 }

package/dist/src/daemon-lease.d.ts

@@ -0,0 +1,70 @@
+export type DaemonProcessIdentityLookupResult = {
+    state: "identified";
+    identity: string;
+} | {
+    state: "dead";
+} | {
+    state: "unknown";
+};
+export type DaemonProcessIdentityLookup = (pid: number) => Promise<DaemonProcessIdentityLookupResult>;
+export type DaemonWorkerLease = {
+    instanceId: string;
+    pid: number;
+    processIdentity: string;
+    path: string;
+    /** Proves this exact process generation still owns the published lease. */
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+};
+/**
+ * A process-generation election, separate from the UI listener election.
+ *
+ * The listener may be replaced or borrowed during a package-manager/service
+ * reload. Queue, index, upload, retention and team reconciliation are a single
+ * stateful unit and must stay owned by the old daemon until all of its lanes
+ * have quiesced. Keeping this election in the vault makes manager crashes and
+ * PID reuse safe too; no particular service manager is trusted as the lock.
+ */
+export declare const daemonWorkerLeaseDir: (dataDir: string) => string;
+/**
+ * The installed service may itself still carry an older background scheduling
+ * class while it reconciles its launchd definition. On macOS, execute the
+ * tiny `ps` probe at the default task policy so that migration can make
+ * progress under load. This is an argv-only wrapper: no shell or interpolation.
+ */
+export declare function daemonPsIdentityCommand(pid: number, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+};
+export declare const daemonProcessIdentity: DaemonProcessIdentityLookup;
+/** Legacy ps generations did not record locale/timezone. A changed rendering
+ * cannot prove PID reuse across an upgrade; a still-live legacy owner remains
+ * uncertain until it exits instead of being mistaken for a stale process. */
+export declare function classifyDaemonProcessGeneration(owner: DaemonProcessIdentityLookupResult, expectedIdentity: string): "current" | "stale" | "unknown";
+/** Publish before a worker receives work or SIGSTOP. The immutable candidate
+ * outlives its daemon, so a replacement cannot overlap an orphan's last writes.
+ * It is not released on parent shutdown until the exact child is proved gone. */
+export declare function registerDaemonIndexWorker(dataDir: string, pid: number, processIdentity: string, options?: {
+    identityLookup?: DaemonProcessIdentityLookup;
+}): Promise<{
+    scratchGeneration: string;
+    retireAfterExit(): Promise<void>;
+}>;
+/** Context also writes durable per-session state; a replacement daemon must
+ * wait for its exact old generation, even while the orphan watchdog cancels it. */
+export declare function registerDaemonContextWorker(dataDir: string, pid: number, processIdentity: string): Promise<{
+    retireAfterExit(): Promise<void>;
+}>;
+/**
+ * Elects the sole complete daemon worker for this vault.
+ *
+ * `null` means another identified generation owns the vault, or an existing
+ * record could not safely be classified. Uncertainty fails closed: preserving
+ * availability never justifies two retention/index writers.
+ */
+export declare function acquireDaemonWorkerLease(dataDir: string, options?: {
+    identityLookup?: DaemonProcessIdentityLookup;
+    electionWindowMs?: number;
+    /** Test seam; production uses a one-second fail-closed ceiling. */
+    identityLookupTimeoutMs?: number;
+}): Promise<DaemonWorkerLease | null>;

package/dist/src/daemon-lease.js

@@ -0,0 +1,420 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { cleanupInterruptedIndexScratch } from "./index-scratch-cleanup.js";
+const execFileAsync = promisify(execFile);
+const ELECTION_WINDOW_MS = 80;
+// Process generation is part of the safety boundary, but it must not become an
+// availability boundary. On a heavily loaded Mac, `ps` can inherit the
+// daemon's scheduling class and otherwise wait indefinitely before emitting
+// its one line. A timeout is uncertainty, never proof that a lease is stale.
+// A bound on the identity probe, not a budget for it. POSIX answers from
+// procfs or a `ps` call in milliseconds; Windows has no such file and must
+// start PowerShell, which on a cold, loaded machine takes seconds — at 750 ms
+// every probe there timed out, and a timed-out probe reads as "this process
+// cannot be verified", which refuses queue locks, scratch reservations and
+// workers outright (about 150 failures on a Windows CI runner).
+const PROCESS_IDENTITY_COMMAND_TIMEOUT_MS = process.platform === "win32" ? 10_000 : 750;
+const PROCESS_IDENTITY_LOOKUP_TIMEOUT_MS = 1_000;
+const processIdentityCommandOptions = {
+    windowsHide: true,
+    timeout: PROCESS_IDENTITY_COMMAND_TIMEOUT_MS,
+    killSignal: "SIGKILL",
+    maxBuffer: 4 * 1024,
+    // ps lstart is otherwise localized and timezone-dependent: two observers
+    // could call the same live generation stale, or fail to arm its watchdog.
+    env: identityCommandEnvironment(),
+};
+/**
+ * The environment the identity command runs with.
+ *
+ * The allowlist exists for POSIX, where `ps lstart` prints a localized,
+ * timezone-dependent date: two observers reading different locales could call
+ * the same live generation stale. Windows reads an integer tick count, which
+ * no locale can change, and powershell.exe will not start under a pruned
+ * environment — measured on a CI runner, it hung until the probe's timeout
+ * (10 s) with a short list and answered in 0.6 s with the inherited one, and
+ * a probe that cannot answer refuses queue locks, scratch reservations and
+ * workers. So Windows inherits the environment and pins only the locale.
+ */
+function identityCommandEnvironment() {
+    const deterministic = { LC_ALL: "C", LANG: "C", TZ: "UTC" };
+    if (process.platform === "win32")
+        return { ...process.env, ...deterministic };
+    return {
+        PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR,
+        TEMP: process.env.TEMP, TMP: process.env.TMP, TMPDIR: process.env.TMPDIR,
+        ...deterministic,
+    };
+}
+let currentDaemonProcessIdentity;
+/**
+ * A process-generation election, separate from the UI listener election.
+ *
+ * The listener may be replaced or borrowed during a package-manager/service
+ * reload. Queue, index, upload, retention and team reconciliation are a single
+ * stateful unit and must stay owned by the old daemon until all of its lanes
+ * have quiesced. Keeping this election in the vault makes manager crashes and
+ * PID reuse safe too; no particular service manager is trusted as the lock.
+ */
+export const daemonWorkerLeaseDir = (dataDir) => join(dataDir, "daemon-worker-leases");
+const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+function processLiveness(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return "dead";
+    try {
+        process.kill(pid, 0);
+        return "alive";
+    }
+    catch (error) {
+        return error.code === "ESRCH" ? "dead" : "unknown";
+    }
+}
+/**
+ * The installed service may itself still carry an older background scheduling
+ * class while it reconciles its launchd definition. On macOS, execute the
+ * tiny `ps` probe at the default task policy so that migration can make
+ * progress under load. This is an argv-only wrapper: no shell or interpolation.
+ */
+export function daemonPsIdentityCommand(pid, platform = process.platform) {
+    const args = ["-p", String(pid), "-o", "lstart="];
+    return platform === "darwin"
+        ? { file: "/usr/sbin/taskpolicy", args: ["-a", "/bin/ps", ...args] }
+        : { file: "ps", args };
+}
+/** A PID plus this kernel-backed generation is not reusable by a later process. */
+async function uncachedDaemonProcessIdentity(pid) {
+    const before = processLiveness(pid);
+    if (before === "dead")
+        return { state: "dead" };
+    if (before === "unknown")
+        return { state: "unknown" };
+    try {
+        if (process.platform === "linux") {
+            const [raw, bootId] = await Promise.all([
+                readFile(`/proc/${pid}/stat`, "utf8"),
+                readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+            ]);
+            const fieldsAfterName = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/);
+            const startTicks = fieldsAfterName[19]; // proc(5) field 22; this slice begins at field 3.
+            if (startTicks && /^\d+$/.test(startTicks) && bootId.trim()) {
+                return { state: "identified", identity: `linux:${bootId.trim()}:${startTicks}` };
+            }
+        }
+        else if (process.platform === "win32") {
+            const command = `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`;
+            const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], processIdentityCommandOptions);
+            const started = stdout.trim();
+            if (/^\d+$/.test(started))
+                return { state: "identified", identity: `windows:${started}` };
+        }
+        else {
+            const command = daemonPsIdentityCommand(pid);
+            const { stdout } = await execFileAsync(command.file, command.args, processIdentityCommandOptions);
+            const started = stdout.trim();
+            if (started)
+                return { state: "identified", identity: `ps-utc:${started}` };
+        }
+    }
+    catch { }
+    return processLiveness(pid) === "dead" ? { state: "dead" } : { state: "unknown" };
+}
+export const daemonProcessIdentity = async (pid) => {
+    if (pid !== process.pid)
+        return uncachedDaemonProcessIdentity(pid);
+    if (!currentDaemonProcessIdentity) {
+        const lookup = uncachedDaemonProcessIdentity(pid);
+        currentDaemonProcessIdentity = lookup;
+        void lookup.then((result) => {
+            // This process's exact kernel generation cannot change while it remains
+            // alive, so an identified result is safe to retain. A transient failure
+            // must not poison every future election in this long-lived process.
+            if (result.state !== "identified" && currentDaemonProcessIdentity === lookup) {
+                currentDaemonProcessIdentity = undefined;
+            }
+        }, () => {
+            if (currentDaemonProcessIdentity === lookup)
+                currentDaemonProcessIdentity = undefined;
+        });
+    }
+    return currentDaemonProcessIdentity;
+};
+/**
+ * Bounds both production and injected generation lookups. Only an explicit
+ * `dead` result permits reclaiming another candidate; timeout, exceptions and
+ * malformed adapter results all remain unknown and therefore fail closed.
+ */
+async function boundedProcessIdentity(lookup, pid, timeoutMs) {
+    let timeout;
+    const deadline = new Promise((resolve) => {
+        timeout = setTimeout(() => resolve({ state: "unknown" }), timeoutMs);
+    });
+    try {
+        const result = await Promise.race([
+            Promise.resolve().then(() => lookup(pid)),
+            deadline,
+        ]);
+        if (result.state === "dead" || result.state === "unknown")
+            return result;
+        if (result.state === "identified" && typeof result.identity === "string"
+            && result.identity.length > 0 && result.identity.length <= 512)
+            return result;
+        return { state: "unknown" };
+    }
+    catch {
+        return processLiveness(pid) === "dead" ? { state: "dead" } : { state: "unknown" };
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function parseCandidate(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || typeof value.instanceId !== "string"
+            || !/^[A-Za-z0-9_-]{16,128}$/.test(value.instanceId)
+            || !Number.isInteger(value.pid) || (value.pid ?? 0) <= 0
+            || typeof value.processIdentity !== "string" || value.processIdentity.length < 1 || value.processIdentity.length > 512
+            || (value.role !== undefined && value.role !== "index-child" && value.role !== "context-child")
+            || (value.role !== undefined && (typeof value.scratchGeneration !== "string"
+                || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value.scratchGeneration)))
+            || !Number.isFinite(value.createdAtMs))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function readCandidate(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const value = parseCandidate(raw);
+        return value ? { state: "present", raw, value } : { state: "invalid" };
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? { state: "missing" } : { state: "invalid" };
+    }
+}
+/** Legacy ps generations did not record locale/timezone. A changed rendering
+ * cannot prove PID reuse across an upgrade; a still-live legacy owner remains
+ * uncertain until it exits instead of being mistaken for a stale process. */
+export function classifyDaemonProcessGeneration(owner, expectedIdentity) {
+    if (owner.state === "dead")
+        return "stale";
+    if (owner.state === "unknown")
+        return "unknown";
+    if (expectedIdentity.startsWith("ps:") && owner.identity.startsWith("ps-utc:"))
+        return "unknown";
+    return owner.identity === expectedIdentity ? "current" : "stale";
+}
+async function candidateState(candidate, lookup) {
+    const owner = await lookup(candidate.pid);
+    return classifyDaemonProcessGeneration(owner, candidate.processIdentity);
+}
+/**
+ * Moves an immutable candidate out of the election instead of unlinking the
+ * pathname observed earlier. The inode/content recheck prevents a stale
+ * observer from deleting a successor if storage is concurrently repaired.
+ */
+async function quarantineExact(path, observed, reason) {
+    const [current, details] = await Promise.all([
+        readFile(path, "utf8").catch(() => null),
+        stat(path).catch(() => null),
+    ]);
+    if (current !== observed.raw || !details?.isFile())
+        return;
+    const fingerprint = createHash("sha256")
+        .update(`${observed.value.instanceId}\n${details.dev}:${details.ino}:${details.birthtimeMs}\n${observed.raw}`)
+        .digest("hex")
+        .slice(0, 20);
+    const quarantine = `${path}.${reason}-${fingerprint}-${randomUUID()}`;
+    try {
+        await rename(path, quarantine);
+        await rm(quarantine, { force: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function publishCandidate(directory, candidate) {
+    const path = join(directory, `${candidate.instanceId}.json`);
+    const staging = join(directory, `.${candidate.instanceId}.${randomUUID()}.pending`);
+    const handle = await open(staging, "wx", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(candidate) + "\n", "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(staging, path);
+        let directoryHandle;
+        try {
+            directoryHandle = await open(directory, "r");
+            await directoryHandle.sync();
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        finally {
+            await directoryHandle?.close();
+        }
+        return path;
+    }
+    catch (error) {
+        await rm(staging, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Publish before a worker receives work or SIGSTOP. The immutable candidate
+ * outlives its daemon, so a replacement cannot overlap an orphan's last writes.
+ * It is not released on parent shutdown until the exact child is proved gone. */
+export async function registerDaemonIndexWorker(dataDir, pid, processIdentity, options = {}) {
+    return registerDaemonBackgroundWorker(dataDir, pid, processIdentity, "index-child", options);
+}
+/** Context also writes durable per-session state; a replacement daemon must
+ * wait for its exact old generation, even while the orphan watchdog cancels it. */
+export async function registerDaemonContextWorker(dataDir, pid, processIdentity) {
+    return registerDaemonBackgroundWorker(dataDir, pid, processIdentity, "context-child");
+}
+async function registerDaemonBackgroundWorker(dataDir, pid, processIdentity, role, options = {}) {
+    if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid
+        || !processIdentity || processIdentity.length > 512)
+        throw new Error("Invalid index worker process generation");
+    const lookup = (target) => boundedProcessIdentity(options.identityLookup ?? daemonProcessIdentity, target, PROCESS_IDENTITY_LOOKUP_TIMEOUT_MS);
+    const current = await lookup(pid);
+    if (current.state !== "identified" || current.identity !== processIdentity) {
+        throw new Error("Index worker process generation could not be verified before publication");
+    }
+    const directory = daemonWorkerLeaseDir(dataDir);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const candidate = {
+        version: 1, role, scratchGeneration: randomUUID(), instanceId: randomBytes(24).toString("base64url"),
+        pid, processIdentity, createdAtMs: Date.now(),
+    };
+    const path = await publishCandidate(directory, candidate);
+    const observed = { raw: JSON.stringify(candidate) + "\n", value: candidate };
+    return {
+        scratchGeneration: candidate.scratchGeneration,
+        async retireAfterExit() {
+            if (await candidateState(candidate, lookup) !== "stale") {
+                throw new Error("A live or unverified index worker still owns its startup barrier");
+            }
+            if (role === "index-child")
+                await cleanupInterruptedIndexScratch(dataDir, candidate.scratchGeneration);
+            await quarantineExact(path, observed, "released");
+        },
+    };
+}
+/**
+ * Elects the sole complete daemon worker for this vault.
+ *
+ * `null` means another identified generation owns the vault, or an existing
+ * record could not safely be classified. Uncertainty fails closed: preserving
+ * availability never justifies two retention/index writers.
+ */
+export async function acquireDaemonWorkerLease(dataDir, options = {}) {
+    const lookup = options.identityLookup ?? daemonProcessIdentity;
+    const lookupTimeoutMs = Math.max(1, options.identityLookupTimeoutMs ?? PROCESS_IDENTITY_LOOKUP_TIMEOUT_MS);
+    // One election can observe several immutable candidates for the same process
+    // (including its freshly published candidate). Resolve that generation once
+    // so one delayed `ps` cannot be multiplied by the number of lease files.
+    const generations = new Map();
+    const lookupOnce = (pid) => {
+        let pending = generations.get(pid);
+        if (!pending) {
+            pending = boundedProcessIdentity(lookup, pid, lookupTimeoutMs);
+            generations.set(pid, pending);
+        }
+        return pending;
+    };
+    const self = await lookupOnce(process.pid);
+    if (self.state !== "identified") {
+        throw new Error("Sealkeep could not verify this process generation, so it refused to start a vault worker");
+    }
+    const directory = daemonWorkerLeaseDir(dataDir);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const candidate = {
+        version: 1,
+        instanceId: randomBytes(24).toString("base64url"),
+        pid: process.pid,
+        processIdentity: self.identity,
+        createdAtMs: Date.now(),
+    };
+    const path = await publishCandidate(directory, candidate);
+    const observedSelf = { raw: JSON.stringify(candidate) + "\n", value: candidate };
+    const release = () => quarantineExact(path, observedSelf, "released");
+    const assertOwned = async () => {
+        const observed = await readCandidate(path);
+        if (observed.state !== "present" || observed.raw !== observedSelf.raw
+            || observed.value.instanceId !== candidate.instanceId
+            || observed.value.pid !== candidate.pid
+            || observed.value.processIdentity !== candidate.processIdentity) {
+            throw new Error("Sealkeep no longer owns the daemon worker lease for this vault");
+        }
+    };
+    await pause(Math.max(0, options.electionWindowMs ?? ELECTION_WINDOW_MS));
+    const entries = await readdir(directory).catch(() => []);
+    const active = [];
+    let uncertain = false;
+    let liveIndexChild = false;
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const candidatePath = join(directory, name);
+        const observed = await readCandidate(candidatePath);
+        // A losing contender can remove its uniquely named immutable candidate
+        // after our readdir snapshot. Its absence is normal contention, not
+        // evidence of a corrupt possibly-live owner.
+        if (observed.state === "missing")
+            continue;
+        // Published candidates are written+fsynced before atomic rename. An
+        // invalid JSON record therefore means corruption, not an in-flight write.
+        if (observed.state === "invalid") {
+            uncertain = true;
+            continue;
+        }
+        const state = await candidateState(observed.value, lookupOnce);
+        if (state === "stale") {
+            if (observed.value.role === "index-child") {
+                try {
+                    await cleanupInterruptedIndexScratch(dataDir, observed.value.scratchGeneration);
+                }
+                catch {
+                    uncertain = true;
+                    continue;
+                }
+            }
+            await quarantineExact(candidatePath, observed, "stale").catch(() => { uncertain = true; });
+            continue;
+        }
+        if (state === "unknown") {
+            uncertain = true;
+            continue;
+        }
+        if (observed.value.role === "index-child" || observed.value.role === "context-child")
+            liveIndexChild = true;
+        else
+            active.push(observed.value);
+    }
+    active.sort((left, right) => left.createdAtMs - right.createdAtMs || left.instanceId.localeCompare(right.instanceId));
+    if (uncertain || liveIndexChild || active[0]?.instanceId !== candidate.instanceId) {
+        await release().catch(() => undefined);
+        return null;
+    }
+    return {
+        instanceId: candidate.instanceId,
+        pid: candidate.pid,
+        processIdentity: candidate.processIdentity,
+        path,
+        assertOwned,
+        release,
+    };
+}