@nowcrew/daemon 0.6.68 → 0.6.69

package/dist/storage-worker-executor.js

@@ -0,0 +1,430 @@
+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 { materializeStorageManifest, publishStagedStorage, reconcileStorageManifest, verifyStagedStorage, } from "./storage-copy.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,
+        ...(operation.service.serviceEnvironment === undefined
+            ? {}
+            : { environment: operation.service.serviceEnvironment }),
+    });
+}
+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, manifestStoreRoot, ...input } = operation.doctorInput;
+    return {
+        ...input,
+        generatedAt,
+        ...(manifestStoreRoot === undefined ? {} : { manifestStoreRoot }),
+        ...(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);
+    const assertHeartbeatHealthy = dependencies.assertHeartbeatHealthy ?? (() => undefined);
+    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 });
+    }
+    assertHeartbeatHealthy();
+    await lifecycle.preflight();
+    assertHeartbeatHealthy();
+    const doctor = await dependencies.runDoctor(workerDoctorInput(operation));
+    assertHeartbeatHealthy();
+    validateFreshDoctor(operation, doctor);
+    const guardedMaterialize = async (input, hooks = {}) => materializeStorageManifest(input, {
+        ...hooks,
+        afterSourceLstat: async (path) => {
+            await hooks.afterSourceLstat?.(path);
+            assertHeartbeatHealthy();
+        },
+        afterTargetParentOpen: async (path) => {
+            await hooks.afterTargetParentOpen?.(path);
+            assertHeartbeatHealthy();
+        },
+    });
+    const guardedVerify = async (input, hooks = {}) => verifyStagedStorage(input, {
+        ...hooks,
+        afterTargetLstat: async (path) => {
+            await hooks.afterTargetLstat?.(path);
+            assertHeartbeatHealthy();
+        },
+    });
+    const guardedReconcile = async (input) => {
+        assertHeartbeatHealthy();
+        const result = await reconcileStorageManifest(input);
+        assertHeartbeatHealthy();
+        return result;
+    };
+    const guardedPublish = async (input, deps = {}) => {
+        assertHeartbeatHealthy();
+        await publishStagedStorage(input, deps);
+        assertHeartbeatHealthy();
+    };
+    const receipt = await 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,
+        onStatus: () => assertHeartbeatHealthy(),
+        assertHealthy: assertHeartbeatHealthy,
+    }, {
+        ...lifecycle,
+        now: dependencies.now,
+        materialize: guardedMaterialize,
+        reconcile: guardedReconcile,
+        verify: guardedVerify,
+        publish: guardedPublish,
+        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;
+        },
+    });
+    assertHeartbeatHealthy();
+    return receipt;
+}
+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);
+    const assertHeartbeatHealthy = dependencies.assertHeartbeatHealthy ?? (() => undefined);
+    assertHeartbeatHealthy();
+    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;
+    const recovered = await dependencies.recoverMigration({
+        backupsRoot: operation.migration.backupsRoot,
+        migrationId: operation.migrationId,
+    }, { ...dependencies.createServiceLifecycle(operation), now: dependencies.now });
+    assertHeartbeatHealthy();
+    return recovered;
+}
+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,151 @@
+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 workerLaunchdLabel(migrationId) {
+    return `com.nowcrew.storage-migration.${migrationId}`;
+}
+function workerLaunchdPath(userHome, migrationId) {
+    return resolve(userHome, "Library", "LaunchAgents", `${workerLaunchdLabel(migrationId)}.plist`);
+}
+function xml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+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();
+    const worker = [process.execPath, input.entryPath, "storage-migration-worker", "--job", input.handoffPath];
+    if (input.platform === "darwin") {
+        if (input.uid === undefined || !Number.isSafeInteger(input.uid) || input.uid < 0) {
+            throw new Error("Persistent storage migration launchd worker requires a numeric uid");
+        }
+        const label = workerLaunchdLabel(migrationId);
+        const path = workerLaunchdPath(input.userHome, migrationId);
+        const args = worker.map((arg) => `      <string>${xml(arg)}</string>`).join("\n");
+        const descriptor = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key><string>${xml(label)}</string>\n  <key>ProgramArguments</key>\n  <array>\n${args}\n  </array>\n  <key>RunAtLoad</key><true/>\n  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key><false/>\n  </dict>\n  <key>ProcessType</key><string>Background</string>\n</dict>\n</plist>\n`;
+        await atomicPrivateWrite(path, descriptor);
+        try {
+            await checkedSupervisor(runSupervisor, "launchctl", ["bootstrap", `gui/${input.uid}`, path]);
+        }
+        catch (error) {
+            await runSupervisor("launchctl", ["bootout", `gui/${input.uid}/${label}`]).catch(() => undefined);
+            await rm(path, { force: true });
+            throw new Error("Storage migration persistent service launch failed", { cause: error });
+        }
+        return;
+    }
+    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();
+    AbsolutePathSchema.parse(input.userHome);
+    if (input.platform === "darwin") {
+        if (input.uid === undefined || !Number.isSafeInteger(input.uid) || input.uid < 0) {
+            throw new Error("Persistent storage migration launchd worker requires a numeric uid");
+        }
+        const label = workerLaunchdLabel(migrationId);
+        await rm(workerLaunchdPath(input.userHome, migrationId), { force: true });
+        await runSupervisor("launchctl", ["bootout", `gui/${input.uid}/${label}`]);
+        return;
+    }
+    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,
+        ...(operation.service.uid === undefined ? {} : { uid: operation.service.uid }),
+    });
+}