@nowcrew/daemon 0.6.51 → 0.6.52

package/dist/storage-target-confirmation.js

@@ -0,0 +1,129 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { atomicPrivateWrite } from "./atomic-private-write.js";
+import { readStorageMigrationReceipt } from "./storage-migration-controller.js";
+const FingerprintSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
+const IdentitySchema = z.object({
+    type: z.literal("daemon:storage-migration-confirmed"),
+    migrationId: z.string().uuid(),
+    environment: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,31}$/u),
+    workspaceId: z.string().uuid(),
+    profile: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,47}$/u),
+    manifestDigest: z.string().regex(/^[0-9a-f]{64}$/u),
+    targetStorageFingerprint: FingerprintSchema,
+}).strict();
+const AcknowledgementSchema = IdentitySchema.omit({ type: true }).extend({
+    version: z.literal(1),
+    confirmedAt: z.string().datetime({ offset: true }),
+}).strict();
+const delay = (milliseconds) => new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, milliseconds);
+});
+export function storageMigrationAcknowledgementPath(backupsRoot, migrationId) {
+    if (!isAbsolute(backupsRoot))
+        throw new Error("storage migration backups root must be absolute");
+    return join(backupsRoot, z.string().uuid().parse(migrationId), "hello-confirmed.json");
+}
+export async function waitForStorageMigrationAcknowledgement(input) {
+    const expected = IdentitySchema.omit({ type: true }).parse({
+        migrationId: input.migrationId,
+        environment: input.environment,
+        workspaceId: input.workspaceId,
+        profile: input.profile,
+        manifestDigest: input.manifestDigest,
+        targetStorageFingerprint: input.targetStorageFingerprint,
+    });
+    const timeoutMs = z.number().int().min(10).max(600_000).parse(input.timeoutMs ?? 120_000);
+    const pollIntervalMs = z.number().int().min(1).max(5_000).parse(input.pollIntervalMs ?? 250);
+    const path = storageMigrationAcknowledgementPath(input.backupsRoot, expected.migrationId);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        try {
+            const acknowledgement = AcknowledgementSchema.parse(JSON.parse(await readFile(path, "utf8")));
+            const { version: _version, confirmedAt: _confirmedAt, ...identity } = acknowledgement;
+            if (JSON.stringify(identity) !== JSON.stringify(expected)) {
+                throw new Error("storage migration acknowledgement identity mismatch");
+            }
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        await delay(pollIntervalMs);
+    }
+    throw new Error("storage migration hello confirmation timeout");
+}
+export function createStorageTargetConfirmationHandler(input) {
+    const profile = z.string().regex(/^[a-z0-9][a-z0-9_-]{0,47}$/u).parse(input.profile);
+    const completionTimeoutMs = z.number().int().min(10).max(600_000).parse(input.completionTimeoutMs ?? 120_000);
+    const pollIntervalMs = z.number().int().min(1).max(5_000).parse(input.pollIntervalMs ?? 250);
+    if (input.identity.storageMigrationId === undefined) {
+        throw new Error("storage target confirmation requires a migration identity");
+    }
+    let active = null;
+    const handle = async (raw, send) => {
+        const rawType = typeof raw === "object" && raw !== null && "type" in raw ? raw.type : undefined;
+        if (rawType !== "daemon:storage-migration-confirmed")
+            return false;
+        const confirmation = IdentitySchema.parse(raw);
+        if (confirmation.migrationId !== input.identity.storageMigrationId
+            || confirmation.environment !== input.identity.storageEnvironment
+            || confirmation.workspaceId !== input.identity.storageWorkspaceId
+            || confirmation.profile !== profile
+            || confirmation.targetStorageFingerprint !== input.identity.storageIdFingerprint) {
+            throw new Error("storage migration confirmation identity mismatch");
+        }
+        const key = JSON.stringify(confirmation);
+        if (active !== null) {
+            if (active.key !== key)
+                throw new Error("storage migration confirmation changed while processing");
+            return active.promise;
+        }
+        const processConfirmation = async () => {
+            const receipt = await readStorageMigrationReceipt(input.backupsRoot, confirmation.migrationId);
+            if (receipt === null || receipt.status !== "service_switched"
+                || receipt.environment !== confirmation.environment
+                || receipt.workspaceId !== confirmation.workspaceId
+                || receipt.profile !== confirmation.profile
+                || receipt.manifestDigest !== confirmation.manifestDigest) {
+                throw new Error("storage migration confirmation receipt identity mismatch");
+            }
+            const { type: _type, ...confirmationIdentity } = confirmation;
+            await atomicPrivateWrite(storageMigrationAcknowledgementPath(input.backupsRoot, confirmation.migrationId), `${JSON.stringify(AcknowledgementSchema.parse({
+                version: 1,
+                ...confirmationIdentity,
+                confirmedAt: new Date().toISOString(),
+            }), null, 2)}\n`);
+            const deadline = Date.now() + completionTimeoutMs;
+            while (Date.now() <= deadline) {
+                const current = await readStorageMigrationReceipt(input.backupsRoot, confirmation.migrationId);
+                if (current?.status === "completed") {
+                    send({
+                        type: "daemon:storage-migration-status",
+                        migrationId: confirmation.migrationId,
+                        status: "completed",
+                        environment: confirmation.environment,
+                        workspaceId: confirmation.workspaceId,
+                        profile: confirmation.profile,
+                    });
+                    return true;
+                }
+                if (current !== null && ["failed", "rolled_back", "rollback_failed"].includes(current.status)) {
+                    throw new Error(`storage migration ended before completion: ${current.status}`);
+                }
+                await delay(pollIntervalMs);
+            }
+            throw new Error("storage migration worker completion timeout");
+        };
+        const promise = processConfirmation();
+        active = { key, promise };
+        void promise.catch(() => {
+            if (active?.key === key)
+                active = null;
+        });
+        return promise;
+    };
+    return Object.freeze({ handle });
+}

package/dist/storage-worker-command.js

@@ -0,0 +1,27 @@
+import { posix, win32 } from "node:path";
+import { executeStorageMigrationWorker, recoverStorageMigrationWorker, } from "./storage-worker-executor.js";
+import { completeStorageMigrationWorkerServiceForHandoff } from "./storage-worker-handoff.js";
+import { startStorageWorkerHeartbeat, writeStorageWorkerFailureStatus, } from "./storage-worker-status.js";
+export async function runStorageWorkerCommand(args, execute = executeStorageMigrationWorker, writeFailure = writeStorageWorkerFailureStatus, startHeartbeat = startStorageWorkerHeartbeat, completeService = completeStorageMigrationWorkerServiceForHandoff, recover = recoverStorageMigrationWorker) {
+    const command = args[0];
+    if (command !== "storage-migration-worker" && command !== "storage-migration-recover")
+        return null;
+    const path = args[1] === "--job" ? args[2] : undefined;
+    if (args.length !== 3 || path === undefined || path.length === 0
+        || /[\0\r\n]/u.test(path) || (!posix.isAbsolute(path) && !win32.isAbsolute(path))) {
+        throw new Error("Invalid storage migration worker command");
+    }
+    const stopHeartbeat = await startHeartbeat(path);
+    try {
+        await (command === "storage-migration-recover" ? recover(path) : execute(path));
+    }
+    catch (error) {
+        await writeFailure(path, error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await stopHeartbeat().catch(() => undefined);
+        await completeService(path);
+    }
+    return 0;
+}

package/dist/storage-worker-executor.js

@@ -0,0 +1,380 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { buildServiceSpec, captureExactService, serviceAction, systemCommandRunner, } from "./computer-service.js";
+import { listProfiles, loadProfile, removeProfile, saveProfile, } from "./computer-profile.js";
+import { assertManagedServiceIdentity, installManagedService, uninstallManagedService, uninstallUnregisteredManagedService, } from "./managed-service-lifecycle.js";
+import { readManagedServiceRegistry, normalizeManagedServiceRecord, serviceDescriptorSha256, } from "./managed-service-registry.js";
+import { readInstallations, writeInstallations, } from "./storage-config.js";
+import { runStorageDoctor } from "./storage-doctor.js";
+import { readStorageMigrationReceipt, recoverStorageMigration, runStorageMigration, StorageMigrationFailure, } from "./storage-migration-controller.js";
+import { readStorageWorkerHandoff } from "./storage-worker-handoff.js";
+import { readStorageWorkerOperation } from "./storage-worker-operation.js";
+import { storageIdFingerprint } from "./storage-identity.js";
+import { waitForStorageMigrationAcknowledgement } from "./storage-target-confirmation.js";
+const defaultServiceDependencies = () => ({
+    assertManagedServiceIdentity,
+    serviceAction,
+    uninstallManagedService,
+    uninstallUnregisteredManagedService,
+    installManagedService,
+    captureExactService,
+    readManagedServices: readManagedServiceRegistry,
+    listProfiles,
+    loadProfile,
+    saveProfile,
+    removeProfile,
+    readInstallations,
+    writeInstallations,
+});
+function serviceSpec(operation, record, profileHome) {
+    return buildServiceSpec({
+        platform: operation.service.platform,
+        profile: operation.profile,
+        userHome: realpathSync.native(operation.service.userHome),
+        uid: operation.service.uid,
+        nodePath: record.nodePath,
+        entryPath: record.entryPath,
+        profileHome,
+    });
+}
+function assertRecordMatchesSpec(record, spec) {
+    const normalizedDescriptorPath = spec.descriptorPath === null
+        ? null
+        : normalizeManagedServiceRecord({ ...record, descriptorPath: spec.descriptorPath }).descriptorPath;
+    const mismatches = [
+        spec.descriptor === null ? "descriptor" : null,
+        spec.descriptorPath === null ? "descriptorPath" : null,
+        record.platform !== spec.platform ? "platform" : null,
+        record.serviceId !== spec.id ? "serviceId" : null,
+        record.profile !== spec.profile ? "profile" : null,
+        record.descriptorPath !== normalizedDescriptorPath ? "descriptorPath" : null,
+        spec.descriptor !== null && record.descriptorSha256 !== serviceDescriptorSha256(spec.descriptor)
+            ? "descriptorSha256"
+            : null,
+    ].filter((value) => value !== null);
+    if (mismatches.length > 0) {
+        throw new Error(`Managed service record does not match operation service '${record.serviceId}': ${mismatches.join(", ")}`);
+    }
+}
+function sameRecord(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function sameInstallation(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function sameProfile(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function canonicalServerUrl(value) {
+    return value.replace(/\/+$/u, "");
+}
+export function createStorageWorkerServiceLifecycle(operation, injected = {}) {
+    const dependencies = { ...defaultServiceDependencies(), ...injected };
+    const registry = { userHome: operation.service.userHome };
+    const sourceRecord = operation.service.sourceRecord;
+    const targetRecord = operation.service.targetRecord;
+    const sourceSpec = serviceSpec(operation, sourceRecord, operation.migration.sourceRoots["daemon-home"]);
+    const targetSpec = serviceSpec(operation, targetRecord, operation.installation.configRoot);
+    assertRecordMatchesSpec(sourceRecord, sourceSpec);
+    assertRecordMatchesSpec(targetRecord, targetSpec);
+    let sourceProfile = null;
+    let savedTargetProfile = null;
+    let baselineInstallations = null;
+    let targetProfileCreated = false;
+    let targetInstallationWritten = false;
+    const assertSourceIdentity = () => dependencies.assertManagedServiceIdentity({
+        spec: sourceSpec,
+        record: sourceRecord,
+        registry,
+    });
+    const readTargetInstallations = () => dependencies.readInstallations({
+        configRoot: operation.installation.configRoot,
+    });
+    const assertTargetMetadataUnchanged = async () => {
+        const profiles = await dependencies.listProfiles(operation.installation.configRoot);
+        if (profiles.includes(operation.profile))
+            throw new Error(`Target profile '${operation.profile}' already exists`);
+        const current = await readTargetInstallations();
+        if (baselineInstallations !== null && JSON.stringify(current) !== JSON.stringify(baselineInstallations)) {
+            throw new Error("Target installation registry changed after worker preflight");
+        }
+        if (current.some((record) => record.profile === operation.profile
+            || record.installationId === operation.installation.target.installationId)) {
+            throw new Error("Target installation identity already exists");
+        }
+        return current;
+    };
+    const preflight = async () => {
+        await assertSourceIdentity();
+        const source = await dependencies.captureExactService(sourceSpec, systemCommandRunner);
+        if (!source.installed || !source.exact || source.running !== operation.service.sourceWasRunning) {
+            throw new Error("Source service state does not match worker operation");
+        }
+        const target = await dependencies.captureExactService(targetSpec, systemCommandRunner);
+        if (target.installed)
+            throw new Error(`Target service '${targetSpec.id}' already exists`);
+        sourceProfile = await dependencies.loadProfile(operation.profile, sourceRecord.daemonHome);
+        if (sourceProfile.name !== operation.profile
+            || canonicalServerUrl(sourceProfile.serverUrl) !== canonicalServerUrl(operation.installation.target.serverUrl)) {
+            throw new Error("Source profile does not match target installation identity");
+        }
+        baselineInstallations = await assertTargetMetadataUnchanged();
+    };
+    const stopSourceService = async () => {
+        await dependencies.serviceAction(sourceSpec, "stop", systemCommandRunner);
+        const stopped = await dependencies.captureExactService(sourceSpec, systemCommandRunner);
+        if (!stopped.installed || !stopped.exact || stopped.running) {
+            throw new Error(`Source service '${sourceSpec.id}' did not stop exactly`);
+        }
+    };
+    const installTargetService = async () => {
+        if (sourceProfile === null || baselineInstallations === null)
+            throw new Error("Worker service preflight is required");
+        const installations = await assertTargetMetadataUnchanged();
+        await assertSourceIdentity();
+        await dependencies.uninstallManagedService({
+            spec: sourceSpec,
+            record: sourceRecord,
+            runner: systemCommandRunner,
+            registry,
+        });
+        const { version: _version, ...profile } = sourceProfile;
+        savedTargetProfile = await dependencies.saveProfile({
+            ...profile,
+            agentsRoot: targetRecord.agentsRoot,
+        }, operation.installation.configRoot);
+        targetProfileCreated = true;
+        await dependencies.writeInstallations([...installations, operation.installation.target].sort((left, right) => left.profile.localeCompare(right.profile)), { configRoot: operation.installation.configRoot });
+        targetInstallationWritten = true;
+        await dependencies.installManagedService({
+            spec: targetSpec,
+            record: targetRecord,
+            runner: systemCommandRunner,
+            registry,
+        });
+        const target = await dependencies.captureExactService(targetSpec, systemCommandRunner);
+        if (!target.installed || !target.exact || target.running) {
+            throw new Error(`Target service '${targetSpec.id}' was not installed exactly in stopped state`);
+        }
+    };
+    const startTargetService = async () => {
+        await dependencies.serviceAction(targetSpec, "start", systemCommandRunner);
+        const target = await dependencies.captureExactService(targetSpec, systemCommandRunner);
+        if (!target.installed || !target.exact || !target.running) {
+            throw new Error(`Target service '${targetSpec.id}' did not start exactly`);
+        }
+    };
+    const removeTargetService = async () => {
+        const records = await dependencies.readManagedServices(registry);
+        const registered = records.find((record) => record.serviceId === targetRecord.serviceId
+            || (record.profile === targetRecord.profile && record.daemonHome === targetRecord.daemonHome));
+        if (registered !== undefined && !sameRecord(registered, targetRecord)) {
+            throw new Error(`Target service '${targetSpec.id}' identity changed before rollback`);
+        }
+        if (registered !== undefined) {
+            await dependencies.uninstallManagedService({
+                spec: targetSpec,
+                record: targetRecord,
+                runner: systemCommandRunner,
+                registry,
+            });
+        }
+        else {
+            const target = await dependencies.captureExactService(targetSpec, systemCommandRunner);
+            if (target.installed && !target.exact)
+                throw new Error(`Target service '${targetSpec.id}' changed before rollback`);
+            if (target.installed) {
+                await dependencies.uninstallUnregisteredManagedService({
+                    spec: targetSpec,
+                    daemonHome: targetRecord.daemonHome,
+                    npmPrefix: targetRecord.npmPrefix,
+                    runner: systemCommandRunner,
+                    registry,
+                });
+            }
+        }
+        const installations = await readTargetInstallations();
+        const targetInstallation = installations.find((record) => record.profile === operation.profile
+            || record.installationId === operation.installation.target.installationId);
+        if (targetInstallation !== undefined) {
+            if (!sameInstallation(targetInstallation, operation.installation.target)) {
+                throw new Error("Target installation identity changed before rollback");
+            }
+            await dependencies.writeInstallations(installations.filter((record) => !sameInstallation(record, operation.installation.target)), { configRoot: operation.installation.configRoot });
+            targetInstallationWritten = false;
+        }
+        const profiles = await dependencies.listProfiles(operation.installation.configRoot);
+        if (profiles.includes(operation.profile)) {
+            const current = await dependencies.loadProfile(operation.profile, operation.installation.configRoot);
+            const original = sourceProfile
+                ?? await dependencies.loadProfile(operation.profile, sourceRecord.daemonHome);
+            const { version: _version, ...profile } = original;
+            const expected = savedTargetProfile ?? { version: 1, ...profile, agentsRoot: targetRecord.agentsRoot };
+            if (!sameProfile(current, expected)) {
+                throw new Error("Target profile identity changed before rollback");
+            }
+            await dependencies.removeProfile(operation.profile, operation.installation.configRoot);
+            targetProfileCreated = false;
+        }
+    };
+    const restoreSourceService = async () => {
+        const current = await dependencies.captureExactService(sourceSpec, systemCommandRunner);
+        if (current.installed && !current.exact) {
+            throw new Error(`Source service '${sourceSpec.id}' changed before rollback`);
+        }
+        if (!current.installed) {
+            await dependencies.installManagedService({
+                spec: sourceSpec,
+                record: sourceRecord,
+                runner: systemCommandRunner,
+                registry,
+            });
+        }
+        const afterInstall = current.installed
+            ? current
+            : await dependencies.captureExactService(sourceSpec, systemCommandRunner);
+        if (operation.service.sourceWasRunning && !afterInstall.running) {
+            await dependencies.serviceAction(sourceSpec, "start", systemCommandRunner);
+        }
+        else if (!operation.service.sourceWasRunning && afterInstall.running) {
+            await dependencies.serviceAction(sourceSpec, "stop", systemCommandRunner);
+        }
+        const restored = await dependencies.captureExactService(sourceSpec, systemCommandRunner);
+        if (!restored.installed || !restored.exact || restored.running !== operation.service.sourceWasRunning) {
+            throw new Error(`Source service '${sourceSpec.id}' was not restored exactly`);
+        }
+    };
+    return Object.freeze({
+        preflight,
+        assertServiceIdentity: assertSourceIdentity,
+        isBusy: () => false,
+        quiesceExecutions: async () => undefined,
+        waitForIdle: async () => undefined,
+        flushLocalState: async () => undefined,
+        stopSourceService,
+        installTargetService,
+        startTargetService,
+        removeTargetService,
+        restoreSourceService,
+        confirmHello: (receipt) => waitForStorageMigrationAcknowledgement({
+            backupsRoot: operation.migration.backupsRoot,
+            migrationId: operation.migrationId,
+            environment: operation.environment,
+            workspaceId: operation.workspaceId,
+            profile: operation.profile,
+            manifestDigest: receipt.manifestDigest,
+            targetStorageFingerprint: storageIdFingerprint(operation.installation.target.storageId),
+        }),
+    });
+}
+function validateFreshDoctor(operation, doctor) {
+    if (!doctor.applyAllowed
+        || doctor.manifestDigest !== operation.expectedManifestDigest
+        || doctor.manifest.migrationId !== operation.migrationId
+        || doctor.environment !== operation.environment
+        || doctor.workspaceId !== operation.workspaceId
+        || doctor.profile !== operation.profile
+        || doctor.manifest.targetWorkspaceRoot !== operation.migration.targetWorkspaceRoot) {
+        throw new StorageMigrationFailure("worker_doctor_mismatch", "fresh worker doctor digest or identity does not match the approved operation");
+    }
+}
+function workerDoctorInput(operation, generatedAt = operation.doctorInput.generatedAt) {
+    const { freeSpaceMultiplier, ...input } = operation.doctorInput;
+    return {
+        ...input,
+        generatedAt,
+        ...(freeSpaceMultiplier === undefined ? {} : { freeSpaceMultiplier }),
+    };
+}
+function workerSourceRoots(operation) {
+    return Object.fromEntries(Object.entries(operation.migration.sourceRoots)
+        .filter((entry) => entry[1] !== undefined));
+}
+export async function executeStorageMigrationWorker(handoffPath, injected = {}) {
+    const dependencies = {
+        runDoctor: (input) => runStorageDoctor(input),
+        runMigration: runStorageMigration,
+        recoverMigration: recoverStorageMigration,
+        readReceipt: readStorageMigrationReceipt,
+        createServiceLifecycle: (operation) => createStorageWorkerServiceLifecycle(operation),
+        now: () => new Date(),
+        ...injected,
+    };
+    const handoff = await readStorageWorkerHandoff(handoffPath);
+    const operation = await readStorageWorkerOperation(handoff.operationPath, handoff.operationSha256);
+    if (handoff.migrationId !== operation.migrationId || handoff.profile !== operation.profile) {
+        throw new StorageMigrationFailure("worker_handoff_mismatch", "worker handoff does not match operation identity");
+    }
+    const lifecycle = dependencies.createServiceLifecycle(operation);
+    const existing = await dependencies.readReceipt(operation.migration.backupsRoot, operation.migrationId);
+    if (existing !== null) {
+        if (existing.environment !== operation.environment || existing.workspaceId !== operation.workspaceId
+            || existing.profile !== operation.profile) {
+            throw new StorageMigrationFailure("worker_receipt_mismatch", "worker receipt does not match operation identity");
+        }
+        if (existing.status === "completed" || existing.status === "rolled_back")
+            return existing;
+        return dependencies.recoverMigration({
+            backupsRoot: operation.migration.backupsRoot,
+            migrationId: operation.migrationId,
+        }, { ...lifecycle, now: dependencies.now });
+    }
+    await lifecycle.preflight();
+    const doctor = await dependencies.runDoctor(workerDoctorInput(operation));
+    validateFreshDoctor(operation, doctor);
+    return dependencies.runMigration({
+        doctor,
+        sourceRoots: workerSourceRoots(operation),
+        stagingWorkspaceRoot: operation.migration.stagingWorkspaceRoot,
+        targetWorkspaceRoot: operation.migration.targetWorkspaceRoot,
+        backupsRoot: operation.migration.backupsRoot,
+        backupArtifacts: operation.migration.backupArtifacts,
+        acceptedWarnings: operation.migration.acceptedWarnings,
+    }, {
+        ...lifecycle,
+        now: dependencies.now,
+        refreshDoctor: async () => {
+            const refreshed = await dependencies.runDoctor(workerDoctorInput(operation, dependencies.now().toISOString()));
+            if (refreshed.manifest.migrationId !== operation.migrationId
+                || refreshed.environment !== operation.environment
+                || refreshed.workspaceId !== operation.workspaceId
+                || refreshed.profile !== operation.profile) {
+                throw new StorageMigrationFailure("final_doctor_failed", "final worker doctor identity changed");
+            }
+            return refreshed;
+        },
+    });
+}
+export async function recoverStorageMigrationWorker(handoffPath, injected = {}) {
+    const dependencies = {
+        runDoctor: (input) => runStorageDoctor(input),
+        runMigration: runStorageMigration,
+        recoverMigration: recoverStorageMigration,
+        readReceipt: readStorageMigrationReceipt,
+        createServiceLifecycle: (operation) => createStorageWorkerServiceLifecycle(operation),
+        now: () => new Date(),
+        ...injected,
+    };
+    const handoff = await readStorageWorkerHandoff(handoffPath);
+    const operation = await readStorageWorkerOperation(handoff.operationPath, handoff.operationSha256);
+    if (handoff.migrationId !== operation.migrationId || handoff.profile !== operation.profile) {
+        throw new StorageMigrationFailure("worker_handoff_mismatch", "worker handoff does not match operation identity");
+    }
+    const receipt = await dependencies.readReceipt(operation.migration.backupsRoot, operation.migrationId);
+    if (receipt === null) {
+        throw new StorageMigrationFailure("migration_receipt_missing", "explicit rollback requires an existing migration receipt");
+    }
+    if (receipt.environment !== operation.environment || receipt.workspaceId !== operation.workspaceId
+        || receipt.profile !== operation.profile) {
+        throw new StorageMigrationFailure("worker_receipt_mismatch", "worker receipt does not match operation identity");
+    }
+    if (receipt.status === "completed" || receipt.status === "rolled_back")
+        return receipt;
+    return dependencies.recoverMigration({
+        backupsRoot: operation.migration.backupsRoot,
+        migrationId: operation.migrationId,
+    }, { ...dependencies.createServiceLifecycle(operation), now: dependencies.now });
+}
+export function storageWorkerOperationDigest(operation) {
+    return createHash("sha256").update(`${JSON.stringify(operation, null, 2)}\n`).digest("hex");
+}

package/dist/storage-worker-handoff.js

@@ -0,0 +1,116 @@
+import { execFile } from "node:child_process";
+import { readFile, rm } from "node:fs/promises";
+import { join, posix, resolve, win32 } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { atomicPrivateWrite } from "./atomic-private-write.js";
+import { readStorageWorkerOperation } from "./storage-worker-operation.js";
+const AbsolutePathSchema = z.string().min(1).max(32768)
+    .refine((value) => !/[\0\r\n]/u.test(value), "path must be a single line")
+    .refine((value) => posix.isAbsolute(value) || win32.isAbsolute(value), "path must be absolute");
+const HandoffSchema = z.object({
+    version: z.literal(1),
+    migrationId: z.string().uuid(),
+    profile: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,47}$/u),
+    operationPath: AbsolutePathSchema,
+    operationSha256: z.string().regex(/^[0-9a-f]{64}$/u),
+}).strict();
+export async function writeStorageWorkerHandoff(raw, input) {
+    let handoff;
+    try {
+        handoff = HandoffSchema.parse(raw);
+        AbsolutePathSchema.parse(input.stateRoot);
+    }
+    catch (error) {
+        throw new Error("Invalid storage worker handoff", { cause: error });
+    }
+    const path = join(input.stateRoot, "migrations", handoff.migrationId, "handoff.json");
+    await atomicPrivateWrite(path, `${JSON.stringify(handoff, null, 2)}\n`);
+    return path;
+}
+export async function readStorageWorkerHandoff(path) {
+    try {
+        AbsolutePathSchema.parse(path);
+        return HandoffSchema.parse(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch (error) {
+        throw new Error("Invalid storage worker handoff", { cause: error });
+    }
+}
+const execFileAsync = promisify(execFile);
+const systemSupervisorRun = async (command, args) => {
+    try {
+        const result = await execFileAsync(command, [...args], {
+            encoding: "utf8",
+            timeout: 15_000,
+            maxBuffer: 64 * 1024,
+        });
+        return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (error) {
+        const failure = error;
+        return {
+            exitCode: typeof failure.code === "number" ? failure.code : 127,
+            stdout: failure.stdout ?? "",
+            stderr: failure.stderr ?? failure.message,
+        };
+    }
+};
+function workerUnitName(migrationId) {
+    return `nowwork-storage-migration-${migrationId}.service`;
+}
+function workerUnitPath(userHome, migrationId) {
+    return resolve(userHome, ".config", "systemd", "user", workerUnitName(migrationId));
+}
+function systemdArg(value) {
+    if (/[\0\r\n]/u.test(value))
+        throw new Error("storage worker service argument must be a single line");
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+async function checkedSupervisor(run, command, args) {
+    const result = await run(command, args);
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `exit ${result.exitCode}`);
+}
+export async function launchStorageMigrationWorker(input, runSupervisor = systemSupervisorRun) {
+    AbsolutePathSchema.parse(input.entryPath);
+    AbsolutePathSchema.parse(input.handoffPath);
+    AbsolutePathSchema.parse(input.userHome);
+    const migrationId = z.string().uuid().parse(input.migrationId).toLowerCase();
+    if (input.platform !== "linux")
+        throw new Error("Persistent storage migration workers require Linux systemd");
+    const worker = [process.execPath, input.entryPath, "storage-migration-worker", "--job", input.handoffPath];
+    const unit = workerUnitName(migrationId);
+    const path = workerUnitPath(input.userHome, migrationId);
+    const descriptor = `[Unit]\nDescription=NowWork storage migration ${migrationId}\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=exec\nExecStart=${worker.map(systemdArg).join(" ")}\nRestart=on-abnormal\nRestartSec=5\n\n[Install]\nWantedBy=default.target\n`;
+    await atomicPrivateWrite(path, descriptor);
+    try {
+        await checkedSupervisor(runSupervisor, "systemctl", ["--user", "daemon-reload"]);
+        await checkedSupervisor(runSupervisor, "systemctl", ["--user", "enable", "--now", unit]);
+    }
+    catch (error) {
+        await runSupervisor("systemctl", ["--user", "disable", "--now", unit]).catch(() => undefined);
+        await rm(path, { force: true });
+        await runSupervisor("systemctl", ["--user", "daemon-reload"]).catch(() => undefined);
+        throw new Error("Storage migration persistent service launch failed", { cause: error });
+    }
+}
+export async function completeStorageMigrationWorkerService(input, runSupervisor = systemSupervisorRun) {
+    const migrationId = z.string().uuid().parse(input.migrationId).toLowerCase();
+    if (input.platform !== "linux")
+        return;
+    AbsolutePathSchema.parse(input.userHome);
+    const unit = workerUnitName(migrationId);
+    await checkedSupervisor(runSupervisor, "systemctl", ["--user", "disable", unit]);
+    await rm(workerUnitPath(input.userHome, migrationId), { force: true });
+    await checkedSupervisor(runSupervisor, "systemctl", ["--user", "daemon-reload"]);
+}
+export async function completeStorageMigrationWorkerServiceForHandoff(path) {
+    const handoff = await readStorageWorkerHandoff(path);
+    const operation = await readStorageWorkerOperation(handoff.operationPath, handoff.operationSha256);
+    await completeStorageMigrationWorkerService({
+        migrationId: operation.migrationId,
+        platform: operation.service.platform,
+        userHome: operation.service.userHome,
+    });
+}