sealkeep 0.8.1 → 0.11.0

package/dist/src/heartbeat.js

@@ -1,8 +1,39 @@
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { isV2 } from "./types.js";
+import { archiveCopies, hasCompleteVerifiedCopyChain } from "./archive-copies.js";
+import { readConfig, resolveDeltaChain } from "./vault.js";
+import { backgroundUploadBytesPerSecond, readLocalSettings } from "./machine-settings.js";
 export const heartbeatPath = (dataDir) => join(dataDir, "daemon-state.json");
+const STALE_TEMPORARY_MS = 60_000;
+const sweptRoots = new Set();
+/**
+ * Every JSON file in the vault root is replaced through `<name>.<uuid>.tmp`
+ * and rename. A daemon stopped between the two — a service reload, a reboot —
+ * leaves the temporary behind, and nothing ever looked for it again: a vault
+ * carried one per restart, forever. The first heartbeat of a process removes
+ * the ones no live writer can still own; a minute is far longer than any of
+ * these writes takes, and the sweep is scoped to that naming so it can never
+ * touch a real file.
+ */
+async function sweepStaleTemporaries(dataDir) {
+    if (sweptRoots.has(dataDir))
+        return;
+    sweptRoots.add(dataDir);
+    const names = await readdir(dataDir).catch(() => []);
+    const now = Date.now();
+    for (const name of names) {
+        if (!/\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/.test(name))
+            continue;
+        const path = join(dataDir, name);
+        const modifiedAt = await stat(path).then((value) => value.mtimeMs).catch(() => Number.NaN);
+        if (Number.isFinite(modifiedAt) && now - modifiedAt > STALE_TEMPORARY_MS)
+            await rm(path, { force: true }).catch(() => undefined);
+    }
+}
 export async function writeHeartbeat(dataDir, beat) {
+    await sweepStaleTemporaries(dataDir);
     const path = heartbeatPath(dataDir);
     const temp = `${path}.${randomUUID()}.tmp`;
     await writeFile(temp, JSON.stringify(beat, null, 2) + "\n", { mode: 0o600 });
@@ -49,63 +80,418 @@ export function liveness(beat, now = Date.now(), alive = processAlive) {
     }
     return {
         state: "running",
-        detail: beat.paused ? "Running but paused; no work is being done." : `Running. Last checked ${describeGap(secondsSinceTick)}.`,
+        detail: beat.paused
+            ? "Running. New work is paused; an operation already in progress may finish safely."
+            : `Running. Last checked ${describeGap(secondsSinceTick)}.${beat.teamAccess?.state === "attention" ? " Team access needs attention; retrying automatically." : ""}`,
         lastTickAt: beat.lastTickAt, secondsSinceTick, paused: beat.paused, totals: beat.totals
     };
 }
+const uploadRetryPath = (dataDir) => join(dataDir, "upload-retries.json");
+const archiveCacheRetryPath = (dataDir) => join(dataDir, "archive-cache-retries.json");
+async function readUploadRetries(dataDir) {
+    try {
+        const parsed = JSON.parse(await readFile(uploadRetryPath(dataDir), "utf8"));
+        return parsed.version === 1 && parsed.archives && typeof parsed.archives === "object"
+            ? { version: 1, archives: parsed.archives }
+            : { version: 1, archives: {} };
+    }
+    catch {
+        return { version: 1, archives: {} };
+    }
+}
+async function writeUploadRetries(dataDir, ledger) {
+    const path = uploadRetryPath(dataDir);
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(ledger, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+async function readArchiveCacheRetries(dataDir) {
+    try {
+        const parsed = JSON.parse(await readFile(archiveCacheRetryPath(dataDir), "utf8"));
+        return parsed.version === 1 && parsed.archives && typeof parsed.archives === "object"
+            ? { version: 1, archives: parsed.archives }
+            : { version: 1, archives: {} };
+    }
+    catch {
+        return { version: 1, archives: {} };
+    }
+}
+async function writeArchiveCacheRetries(dataDir, ledger) {
+    const path = archiveCacheRetryPath(dataDir);
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(ledger, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+function nextUploadAttempt(attempts, now) {
+    // Five seconds makes one-off network failures cheap; exponential cooling
+    // stops a permanent first page of failures from consuming every bounded pass.
+    const delay = Math.min(60 * 60_000, 5_000 * 2 ** Math.min(Math.max(0, attempts - 1), 10));
+    return new Date(now + delay).toISOString();
+}
+/**
+ * Gives the daemon a bounded, retry-cooled cleanup lane for encrypted local
+ * duplicates. This runs even when the upload backlog is empty, so a service
+ * upgrade or an earlier provider outage cannot strand old `.skarchive` files.
+ */
+export async function sweepExpiredArchiveCache(dataDir, options) {
+    const offloadModule = await import("./offload.js");
+    // Transaction recovery is independent of whether this machine currently
+    // retains new encrypted archives forever. A crash after unlinking the
+    // source must converge on the next daemon pass even if the cache policy was
+    // changed meanwhile. Injected test offload functions remain self-contained.
+    const recovered = options.offload
+        ? { completed: [], freedBytes: 0 }
+        : await offloadModule.reconcileOffloadTransactions(dataDir, {
+            client: options.client,
+            maxBytesPerSecond: options.maxBytesPerSecond,
+            signal: options.signal,
+        });
+    const recoveredIds = recovered.completed.map((candidate) => candidate.id);
+    if (options.cacheDays === null)
+        return { offloaded: recoveredIds, freedBytes: recovered.freedBytes };
+    const now = options.now ?? Date.now();
+    const limit = Math.max(0, Math.trunc(options.maxArchives ?? 8));
+    if (limit === 0)
+        return { offloaded: recoveredIds, freedBytes: recovered.freedBytes };
+    const { offloadable, offloadArchives: realOffload } = offloadModule;
+    const offload = options.offload ?? realOffload;
+    const preview = await offloadable(dataDir, { olderThanDays: options.cacheDays, now });
+    const candidateIds = new Set(preview.candidates.map((candidate) => candidate.id));
+    const retries = await readArchiveCacheRetries(dataDir);
+    let retriesChanged = false;
+    for (const archiveId of Object.keys(retries.archives)) {
+        if (!candidateIds.has(archiveId)) {
+            delete retries.archives[archiveId];
+            retriesChanged = true;
+        }
+    }
+    // listArchives is newest-first; reversing gives the oldest expired cache
+    // entries first, which makes bounded passes recover space fairly.
+    const selected = [...preview.candidates].reverse().filter((candidate) => {
+        const retry = retries.archives[candidate.id];
+        return !retry || Date.parse(retry.nextAttemptAt) <= now;
+    }).slice(0, limit);
+    if (selected.length === 0) {
+        if (retriesChanged)
+            await writeArchiveCacheRetries(dataDir, retries).catch(() => undefined);
+        return { offloaded: recoveredIds, freedBytes: recovered.freedBytes };
+    }
+    const selectedIds = new Set(selected.map((candidate) => candidate.id));
+    const markRetry = (archiveId, error) => {
+        const attempts = (retries.archives[archiveId]?.attempts ?? 0) + 1;
+        retries.archives[archiveId] = {
+            attempts,
+            nextAttemptAt: nextUploadAttempt(attempts, now),
+            lastError: error.replace(/\s+/g, " ").slice(0, 500),
+        };
+        retriesChanged = true;
+    };
+    try {
+        options.signal?.throwIfAborted();
+        const outcome = await offload(dataDir, {
+            confirm: true,
+            olderThanDays: options.cacheDays,
+            now,
+            only: selectedIds,
+            freshlyVerified: options.freshlyVerified,
+            signal: options.signal,
+            client: options.client,
+            maxBytesPerSecond: options.maxBytesPerSecond,
+        });
+        if (outcome.mode !== "apply")
+            throw new Error("archive cache cleanup did not enter apply mode");
+        const completed = new Set(outcome.offloaded.map((candidate) => candidate.id));
+        const failures = new Map([
+            ...outcome.failed.map((failure) => [failure.id, failure.error]),
+            ...outcome.blocked.map((failure) => [failure.id, failure.reason]),
+        ]);
+        for (const archiveId of selectedIds) {
+            if (completed.has(archiveId)) {
+                if (retries.archives[archiveId]) {
+                    delete retries.archives[archiveId];
+                    retriesChanged = true;
+                }
+            }
+            else {
+                markRetry(archiveId, failures.get(archiveId) ?? "verified archive cache cleanup did not complete");
+            }
+        }
+        if (retriesChanged)
+            await writeArchiveCacheRetries(dataDir, retries).catch(() => undefined);
+        return { offloaded: [...new Set([...recoveredIds, ...completed])], freedBytes: recovered.freedBytes + outcome.freedBytes };
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? error;
+        const message = error instanceof Error ? error.message : "archive cache cleanup failed";
+        for (const archiveId of selectedIds)
+            markRetry(archiveId, message);
+        await writeArchiveCacheRetries(dataDir, retries).catch(() => undefined);
+        return { offloaded: recoveredIds, freedBytes: recovered.freedBytes };
+    }
+}
+function uploadChains(records) {
+    const byChain = new Map();
+    for (const record of records) {
+        if (!isV2(record))
+            continue;
+        let chain;
+        try {
+            chain = resolveDeltaChain(records, record);
+        }
+        catch {
+            continue;
+        }
+        if (chain.length < 2)
+            continue;
+        const rootId = chain[0].id;
+        if (!byChain.has(rootId))
+            byChain.set(rootId, { rootId, records: chain });
+    }
+    const chains = [...byChain.values()];
+    const result = new Map();
+    for (const chain of chains)
+        for (const record of chain.records)
+            result.set(record.id, chain);
+    return { byId: result, chains };
+}
+async function chooseCommonTarget(dataDir, chain, config, options = {}) {
+    const { chooseTarget, remoteCopyMatchesTarget, resolveTargets, targetUsage } = await import("./storage-targets.js");
+    const targets = await resolveTargets(dataDir);
+    for (const target of targets) {
+        let additional = 0;
+        let eligible = true;
+        for (const item of chain.records) {
+            if (!isV2(item)) {
+                eligible = false;
+                break;
+            }
+            const teamBound = Boolean(item.source.projectScope || (item.source.project && config.teamSpaces?.[item.source.project]));
+            let alreadyThere = false;
+            for (const copy of archiveCopies(item)) {
+                if (copy.verifiedAt && await remoteCopyMatchesTarget(dataDir, target, copy)) {
+                    alreadyThere = true;
+                    break;
+                }
+            }
+            if (alreadyThere)
+                continue;
+            // Injected clients are the provider-test seam and already prove local
+            // connectivity. Keep every routing/cap/team check, but do not require a
+            // machine credential that the seam intentionally replaces.
+            if (options.clientProvided) {
+                if (target.enabled === false || (teamBound && target.provider !== "vaultline")) {
+                    eligible = false;
+                    break;
+                }
+                if (target.maxGb !== undefined) {
+                    const usage = (await targetUsage(dataDir, targets)).get(target.id) ?? 0;
+                    if (usage + additional + item.cipher.storedBytes > target.maxGb * 1024 ** 3) {
+                        eligible = false;
+                        break;
+                    }
+                }
+            }
+            else
+                try {
+                    // Include earlier missing links in the projected size so maxGb is
+                    // checked for the whole chain, not once per link against stale usage.
+                    await chooseTarget(dataDir, {
+                        project: item.source.project ?? null,
+                        projectKey: item.source.projectKey ?? null,
+                        bytes: item.cipher.storedBytes + additional,
+                        requireManaged: teamBound,
+                        targetId: target.id,
+                    });
+                }
+                catch {
+                    eligible = false;
+                    break;
+                }
+            additional += item.cipher.storedBytes;
+        }
+        if (eligible)
+            return target.id;
+    }
+    return null;
+}
 /**
  * The daemon's upload pass, finished properly: upload, verify, then offload.
  *
  * `uploadPending` alone leaves a sealed local copy of every archive it just
- * proved the bucket holds — on the machines this product is for, that is the
- * disk staying exactly as full as before. The dashboard's push already does
- * the whole job (see `runUploads` in local-api.ts): the moment an archive's
- * verify lands, its local blob is a duplicate, and offloading it right then
- * lets a full disk breathe with each verify instead of never.
+ * proved the bucket holds — on the machines this product is for, that cache
+ * must not grow forever. The visible per-machine cache setting decides when a
+ * verified duplicate leaves; a value of zero completes that cleanup in this
+ * same pass.
  *
  * Offload failure is tolerated per archive: the upload is still verified and
- * recorded, and the next offload sweep gets another chance. `freshlyVerified`
- * is what keeps this cheap — the verify happened milliseconds ago, so the
- * usual fetch-and-hash re-proof would double the egress of every push.
+ * recorded, and a bounded, backed-off sweep gets another chance. A fresh
+ * verify still receives one final streamed whole-chain proof at the actual
+ * local purge boundary when the cache setting is zero.
  *
- * Integration note: src/daemon.ts's tick still calls bare `uploadPending`;
- * switching it to this function is the remaining wiring (daemon.ts is outside
- * this change's file list).
+ * The daemon calls this combined pass so routing, remote verification, retry
+ * fairness, and reclaim all share one ordering boundary.
  */
 export async function uploadAndOffloadPending(dataDir, options = {}) {
     // Imported lazily, like the paths local-api takes: this module is read by
     // every surface that asks "is the service alive", none of which should pay
     // for the provider stack.
-    const [{ uploadArchive }, { listArchives }, { isV2 }] = await Promise.all([
-        import("./upload.js"), import("./vault.js"), import("./types.js")
+    const [{ uploadArchive }, { listArchives }, { hasVerifiedCopy: hasVerifiedCopyDynamic }] = await Promise.all([
+        import("./upload.js"), import("./vault.js"), import("./archive-copies.js")
     ]);
-    const { offload: injectedOffload, ...uploadOptions } = options;
+    const { offload: injectedOffload, maxArchives, maxOffloads, ...uploadOptions } = options;
     const offload = injectedOffload ?? (await import("./offload.js")).offloadArchives;
-    const records = await listArchives(dataDir);
+    const localSettings = await readLocalSettings(dataDir);
+    // This function is the daemon's automatic upload boundary. A null field in
+    // older settings meant "reserved/not implemented", not informed consent to
+    // saturate the link, so it resolves to the safe automatic rate here.
+    uploadOptions.maxBytesPerSecond ??= backgroundUploadBytesPerSecond(localSettings);
+    // listArchives is newest-first for the UI. Work oldest-first here so a large
+    // new session (or a failure on it) cannot keep earlier memory local forever.
+    const records = (await listArchives(dataDir))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+    const config = await readConfig(dataDir);
+    const chainIndex = uploadChains(records);
+    const incompleteChainById = new Map();
+    for (const chain of chainIndex.chains) {
+        if (chain.records.every(isV2) && hasCompleteVerifiedCopyChain(chain.records))
+            continue;
+        for (const item of chain.records)
+            incompleteChainById.set(item.id, chain);
+    }
+    const retries = await readUploadRetries(dataDir);
+    const pendingIds = new Set(records.filter((record) => !isV2(record) || incompleteChainById.has(record.id) || !hasVerifiedCopyDynamic(record)).map((record) => record.id));
+    let retriesChanged = false;
+    for (const archiveId of Object.keys(retries.archives)) {
+        if (!pendingIds.has(archiveId)) {
+            delete retries.archives[archiveId];
+            retriesChanged = true;
+        }
+    }
     const uploaded = [];
     const failed = [];
     const offloaded = [];
     let freedBytes = 0;
+    let attempted = 0;
+    const commonTargets = new Map();
+    const blockedChains = new Set();
+    const limit = maxArchives === undefined ? Number.POSITIVE_INFINITY : Math.max(0, Math.trunc(maxArchives));
     for (const record of records) {
-        if (isV2(record) && record.remote?.verifiedAt)
+        uploadOptions.signal?.throwIfAborted();
+        const chain = incompleteChainById.get(record.id);
+        if (isV2(record) && hasVerifiedCopyDynamic(record) && !chain)
             continue;
-        try {
-            uploaded.push(await uploadArchive(dataDir, record.id, uploadOptions));
-        }
-        catch (error) {
-            failed.push({ archiveId: record.id, error: error instanceof Error ? error.message : "upload failed" });
+        if (chain && blockedChains.has(chain.rootId))
             continue;
+        const now = Date.now();
+        const retry = retries.archives[record.id];
+        if (retry && Date.parse(retry.nextAttemptAt) > now)
+            continue;
+        if (attempted >= limit)
+            break;
+        let targetId;
+        if (chain) {
+            if (!commonTargets.has(chain.rootId)) {
+                commonTargets.set(chain.rootId, await chooseCommonTarget(dataDir, chain, config, { clientProvided: Boolean(uploadOptions.client) }));
+            }
+            const chosen = commonTargets.get(chain.rootId);
+            if (!chosen) {
+                blockedChains.add(chain.rootId);
+                const message = "No one eligible storage destination can hold the complete archive chain yet; the chain remains local until a common destination is available.";
+                failed.push({ archiveId: record.id, error: message });
+                const attempts = (retry?.attempts ?? 0) + 1;
+                retries.archives[record.id] = { attempts, nextAttemptAt: nextUploadAttempt(attempts, now), lastError: message };
+                retriesChanged = true;
+                continue;
+            }
+            targetId = chosen;
+            // A verified copy at the frozen destination needs no transfer. It still
+            // belongs to the chain's work set, so leave it available for the common
+            // destination proof but do not upload it again.
+            let alreadyThere = false;
+            const { resolveTargets, remoteCopyMatchesTarget } = await import("./storage-targets.js");
+            const target = (await resolveTargets(dataDir)).find((candidate) => candidate.id === targetId);
+            if (target)
+                for (const copy of isV2(record) ? archiveCopies(record) : []) {
+                    if (copy.verifiedAt && await remoteCopyMatchesTarget(dataDir, target, copy)) {
+                        alreadyThere = true;
+                        break;
+                    }
+                }
+            if (alreadyThere)
+                continue;
         }
+        attempted += 1;
         try {
-            const outcome = await offload(dataDir, { confirm: true, only: new Set([record.id]), freshlyVerified: new Set([record.id]) });
-            if (outcome.mode === "apply") {
-                freedBytes += outcome.freedBytes;
-                offloaded.push(...outcome.offloaded.map((item) => item.id));
+            // An injected provider client is a test seam, not a machine credential
+            // for the named target. Keep the frozen target for eligibility above,
+            // while letting the seam use its explicit transport without requiring a
+            // persisted credential binding. Production calls always carry targetId.
+            const outcome = await uploadArchive(dataDir, record.id, {
+                ...uploadOptions,
+                ...(targetId && !uploadOptions.client ? { targetId } : {}),
+            });
+            if (!outcome.verified)
+                throw new Error("storage did not verify this upload as durable");
+            uploaded.push(outcome);
+            if (retry) {
+                delete retries.archives[record.id];
+                retriesChanged = true;
             }
         }
-        catch { /* offload is a bonus on this pass; the sweep gets another chance */ }
+        catch (error) {
+            if (uploadOptions.signal?.aborted)
+                throw uploadOptions.signal.reason ?? error;
+            const message = error instanceof Error ? error.message : "upload failed";
+            failed.push({ archiveId: record.id, error: message });
+            const attempts = (retry?.attempts ?? 0) + 1;
+            retries.archives[record.id] = {
+                attempts,
+                nextAttemptAt: nextUploadAttempt(attempts, now),
+                lastError: message.replace(/\s+/g, " ").slice(0, 500),
+            };
+            retriesChanged = true;
+            continue;
+        }
+    }
+    if (retriesChanged)
+        await writeUploadRetries(dataDir, retries).catch(() => undefined);
+    // The per-machine cache policy is visible in Settings. It is deliberately
+    // separate from source retention: this removes only encrypted `.skarchive`
+    // duplicates that a readable off-machine destination has already verified.
+    const cacheSweep = await sweepExpiredArchiveCache(dataDir, {
+        cacheDays: localSettings.localArchiveCacheDays,
+        offload,
+        maxArchives: maxOffloads ?? Math.min(8, limit),
+        freshlyVerified: new Set(uploaded.map((item) => item.archiveId)),
+        signal: uploadOptions.signal,
+        client: uploadOptions.client,
+        maxBytesPerSecond: uploadOptions.maxBytesPerSecond,
+    });
+    offloaded.push(...cacheSweep.offloaded);
+    freedBytes += cacheSweep.freedBytes;
+    // A team grant is separate from account durability. Retry it every daemon
+    // pass so an upload completed while offline, a crash after verification, or
+    // a newly enabled project all converge without a Sealkeep command.
+    let reconciled;
+    try {
+        reconciled = await (await import("./upload.js")).reconcileManagedTeamArchives(dataDir, {
+            signal: uploadOptions.signal,
+        });
     }
-    return { uploaded, failed, skipped: records.length - uploaded.length - failed.length, offloaded, freedBytes };
+    catch (error) {
+        if (uploadOptions.signal?.aborted)
+            throw uploadOptions.signal.reason ?? error;
+        reconciled = { registered: 0, failed: 0 };
+    }
+    return {
+        uploaded,
+        failed,
+        skipped: records.length - uploaded.length - failed.length,
+        offloaded,
+        freedBytes,
+        teamRegistered: reconciled.registered,
+    };
 }
 export function describeGap(seconds) {
     if (seconds < 5)

package/dist/src/index-background-watchdog.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index-background-watchdog.js

@@ -0,0 +1,94 @@
+import { daemonProcessIdentity } from "./daemon-lease.js";
+let ownership;
+let disconnected = false;
+let disarmed = false;
+let cleanupStarted = false;
+let arming;
+async function signalOwned(signal) {
+    if (!ownership || disarmed)
+        return false;
+    const current = await daemonProcessIdentity(ownership.pid);
+    if (disarmed || current.state !== "identified" || current.identity !== ownership.identity)
+        return false;
+    try {
+        return process.kill(ownership.pid, signal);
+    }
+    catch {
+        return false;
+    }
+}
+async function orphanCleanup() {
+    if (cleanupStarted || disarmed)
+        return;
+    cleanupStarted = true;
+    // Disconnect can arrive while the initial generation check is in flight.
+    if (arming)
+        await arming;
+    let terminatedAt;
+    while (ownership && !disarmed) {
+        const current = await daemonProcessIdentity(ownership.pid);
+        if (current.state === "dead" || (current.state === "identified" && current.identity !== ownership.identity))
+            break;
+        if (current.state === "identified") {
+            // Retry CONT as well: a transient failed probe must not leave TERM
+            // queued forever on a stopped process. Every signal checks generation.
+            if (process.platform !== "win32")
+                await signalOwned("SIGCONT");
+            if (terminatedAt === undefined) {
+                if (await signalOwned("SIGTERM"))
+                    terminatedAt = Date.now();
+            }
+            else if (Date.now() - terminatedAt >= ownership.graceMs) {
+                await signalOwned("SIGKILL");
+            }
+        }
+        // Unknown is not permission to signal, nor proof of cleanup. Keep this
+        // never-paused, secret-free watchdog alive until identity recovers or the
+        // exact generation is positively gone. Each OS lookup is itself bounded.
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    process.exit(0);
+}
+process.on("message", (wire) => {
+    if (!wire || typeof wire !== "object" || !("type" in wire))
+        return;
+    const message = wire;
+    if (message.type === "disarm") {
+        // Only the owner sends this, after observing the actual worker exit.
+        disarmed = true;
+        process.exit(0);
+    }
+    if (message.type !== "arm" || arming || ownership)
+        return;
+    if (!Number.isInteger(message.pid) || message.pid <= 0
+        || message.pid === process.pid || message.pid === process.ppid
+        || typeof message.identity !== "string" || !message.identity
+        || typeof message.graceMs !== "number" || !Number.isFinite(message.graceMs)) {
+        process.exit(1);
+    }
+    ownership = {
+        pid: message.pid,
+        identity: message.identity,
+        graceMs: Math.max(1, Math.min(2_000, message.graceMs)),
+    };
+    arming = (async () => {
+        const current = await daemonProcessIdentity(ownership.pid);
+        return current.state === "identified" && current.identity === ownership.identity;
+    })();
+    void arming.then((verified) => {
+        if (disconnected || disarmed)
+            return;
+        if (!verified) {
+            process.exit(1);
+            return;
+        }
+        process.send?.({ type: "armed" }, (error) => {
+            if (error)
+                void orphanCleanup();
+        });
+    });
+});
+process.once("disconnect", () => {
+    disconnected = true;
+    void orphanCleanup();
+});

package/dist/src/index-background-work.d.ts

@@ -0,0 +1,21 @@
+import { buildContentIndex, type PublishLocalContentIndexCheckpointOptions } from "./search.js";
+import { type LegacyIndexPublicationOutcome } from "./index-upgrade-publication.js";
+export type BackgroundIndexWorkOptions = NonNullable<Parameters<typeof buildContentIndex>[2]> & {
+    /** Cooperative work hook for the pre-build streaming upgrade inspection. */
+    upgradeYield?: PublishLocalContentIndexCheckpointOptions["onYield"];
+    /** Ciphertext byte progress for the pre-build managed publication. */
+    upgradeProgress?: PublishLocalContentIndexCheckpointOptions["onProgress"];
+};
+/** The daemon only needs incremental progress; checkpoint details remain on disk. */
+export type BackgroundIndexWorkResult = {
+    indexedNow: number;
+    skipped: number;
+};
+type BackgroundIndexWorkDependencies = {
+    publishUpgrade(dataDir: string, phrase: string, options: PublishLocalContentIndexCheckpointOptions): Promise<LegacyIndexPublicationOutcome>;
+    needsWork(dataDir: string): Promise<boolean>;
+    build: typeof buildContentIndex;
+};
+/** The one operation executed by the daemon-owned historical-index child. */
+export declare function runBackgroundIndexWork(dataDir: string, phrase: string, options: BackgroundIndexWorkOptions, dependencies?: Partial<BackgroundIndexWorkDependencies>): Promise<BackgroundIndexWorkResult>;
+export {};

package/dist/src/index-background-work.js

@@ -0,0 +1,25 @@
+import { buildContentIndex, contentIndexNeedsPolicyUpgrade, } from "./search.js";
+import { publishLegacyLocalIndexCheckpointIfNeeded, } from "./index-upgrade-publication.js";
+const defaults = {
+    publishUpgrade: publishLegacyLocalIndexCheckpointIfNeeded,
+    needsWork: contentIndexNeedsPolicyUpgrade,
+    build: buildContentIndex,
+};
+/** The one operation executed by the daemon-owned historical-index child. */
+export async function runBackgroundIndexWork(dataDir, phrase, options, dependencies = {}) {
+    const deps = { ...defaults, ...dependencies };
+    const upgrade = await deps.publishUpgrade(dataDir, phrase, {
+        signal: options.signal,
+        remoteIdleMs: options.scheduling?.remoteIdleMs,
+        maxBytesPerSecond: options.scheduling?.backgroundTransferBytesPerSecond,
+        onYield: options.upgradeYield,
+        onProgress: options.upgradeProgress,
+    });
+    if (upgrade.status === "published" && !await deps.needsWork(dataDir)) {
+        return {
+            indexedNow: 0,
+            skipped: 0,
+        };
+    }
+    return deps.build(dataDir, phrase, options);
+}