@cydm/happy-elves 0.1.0-beta.7 → 0.1.0-beta.71

package/apps/daemon/dist/lifecycle/restart.js

@@ -0,0 +1,650 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { daemonProcessStatusForIdentity, isDaemonProcessAlive, parseDaemonPidIdentity, readDaemonProcessStartedAtMs, } from "../../../../packages/shared/dist/node/daemon-process.js";
+import { configDir, daemonLifecycleJournalPath, daemonScriptPath, pidPath } from "../paths.js";
+import { lifecycleError } from "./errors.js";
+const lifecycleDaemonPathEnv = "HAPPY_ELVES_LIFECYCLE_DAEMON_PATH";
+const maxBundledHelperBytes = 16 * 1024 * 1024;
+const helperCleanupMarkerVersion = 1;
+export function detachedLifecycleHelperSpawnSpec(requestId, helperNonce, options = {}) {
+    assertLifecycleIdentifier(requestId, "request id");
+    if (!/^[a-f0-9]{48}$/u.test(helperNonce)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_ID_INVALID", "Daemon lifecycle helper nonce is invalid");
+    }
+    const helperPath = options.helperPath ?? detachedHelperPath();
+    const nodeExecPath = options.nodeExecPath ?? process.execPath;
+    if (!path.isAbsolute(helperPath) || !path.isAbsolute(nodeExecPath)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_EXEC_INVALID", "Detached lifecycle helper paths must be absolute");
+    }
+    return {
+        command: nodeExecPath,
+        args: [helperPath, "--request-id", requestId, "--helper-nonce", helperNonce],
+        options: fixedDetachedOptions(options.cwd ?? configDir, {
+            ...(options.env ?? process.env),
+            [lifecycleDaemonPathEnv]: daemonScriptPath,
+        }),
+    };
+}
+export async function spawnDetachedLifecycleHelper(requestId, helperNonce, options = {}) {
+    const spec = detachedLifecycleHelperSpawnSpec(requestId, helperNonce, options);
+    return await (options.spawnDetached ?? spawnDetachedProcess)(spec);
+}
+export function detachedDaemonRestartSpawnSpec(cwd, instanceNonce, options = {}) {
+    if (!path.isAbsolute(cwd))
+        throw lifecycleError("DAEMON_RESTART_CWD_INVALID", "Daemon restart cwd must be absolute");
+    if (!/^[a-f0-9]{32,128}$/u.test(instanceNonce)) {
+        throw lifecycleError("DAEMON_INSTANCE_NONCE_INVALID", "Daemon restart instance nonce is invalid");
+    }
+    const daemonPath = options.daemonPath ?? lifecycleDaemonPathFromEnvironment() ?? daemonScriptPath;
+    const nodeExecPath = options.nodeExecPath ?? process.execPath;
+    if (!path.isAbsolute(daemonPath) || !path.isAbsolute(nodeExecPath)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_EXEC_INVALID", "Daemon restart paths must be absolute");
+    }
+    return {
+        command: nodeExecPath,
+        args: [daemonPath, "start", "--instance-nonce", instanceNonce],
+        options: fixedDetachedOptions(cwd, options.env ?? process.env),
+    };
+}
+/**
+ * Publish a self-contained helper under Happy Elves home before the parent
+ * exits. An npm upgrade may replace the installation directory while this
+ * process is running, so the detached helper must never execute from there.
+ */
+export async function stageDetachedLifecycleHelper(helperNonce, options = {}) {
+    if (!/^[a-f0-9]{48}$/u.test(helperNonce)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_ID_INVALID", "Daemon lifecycle helper nonce is invalid");
+    }
+    const journalPath = options.journalPath ?? daemonLifecycleJournalPath;
+    const directory = path.join(path.dirname(path.resolve(journalPath)), "daemon-lifecycle-helpers-v1");
+    await ensurePrivateHelperDirectory(directory);
+    const sourcePath = options.sourcePath ?? detachedHelperBundlePath();
+    const source = await readRegularHelper(sourcePath);
+    if (!source) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper bundle is missing");
+    }
+    const targetPath = path.join(directory, `${helperNonce}.mjs`);
+    const existing = await readRegularHelper(targetPath, true);
+    if (existing) {
+        if (helperDigest(existing) !== helperDigest(source)) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_CONFLICT", "Staged lifecycle helper does not match the installed helper bundle");
+        }
+        await fs.chmod(targetPath, 0o600);
+        // A previous attempt may have published the target and then failed its
+        // directory sync. Re-establish rename durability before treating the
+        // existing helper as safely staged.
+        await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+        return targetPath;
+    }
+    const temporaryPath = path.join(directory, `.${helperNonce}-${randomBytes(18).toString("hex")}.tmp`);
+    let handle;
+    try {
+        handle = await fs.open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(source);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(temporaryPath, targetPath);
+        await fs.chmod(targetPath, 0o600);
+        await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return targetPath;
+}
+/**
+ * Retire only the immutable helper selected by an exact operation nonce.
+ * Cleanup is bounded because Windows antivirus/process handles can briefly
+ * delay unlink after the bundled module has finished loading. Unknown file
+ * types are preserved and fail closed instead of being removed recursively.
+ */
+export async function retireStagedLifecycleHelper(helperNonce, options = {}) {
+    await queueStagedLifecycleHelperCleanup(helperNonce, options);
+    const outcome = await retireStagedLifecycleHelperFile(helperNonce, options);
+    if (outcome !== "pending") {
+        await removeStagedLifecycleHelperCleanupMarker(helperNonce, options);
+    }
+    return outcome;
+}
+/**
+ * Publish the exact helper nonce before a terminal journal can be replaced.
+ * A marker is immutable and one-per-nonce, so concurrent operations cannot
+ * lose an older pending cleanup through read-modify-write races.
+ */
+export async function queueStagedLifecycleHelperCleanup(helperNonce, options = {}) {
+    assertHelperNonce(helperNonce);
+    const directory = helperCleanupDirectory(options.journalPath);
+    await ensurePrivateHelperDirectory(directory);
+    const markerPath = helperCleanupMarkerPath(helperNonce, options.journalPath);
+    const expected = helperCleanupMarker(helperNonce);
+    const raw = `${JSON.stringify(expected)}\n`;
+    const stagingDirectory = path.dirname(directory);
+    const temporaryPath = path.join(stagingDirectory, `.daemon-lifecycle-helper-cleanup-${helperNonce}-${randomBytes(18).toString("hex")}.tmp`);
+    let handle;
+    try {
+        // The canonical marker must never be visible partially written. A crash
+        // before the hard-link can leave only a sibling temp file, which is
+        // outside the manifest directory and cannot poison future drains.
+        handle = await fs.open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(raw, "utf8");
+        await handle.chmod(0o600);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            let linked = false;
+            try {
+                await fs.link(temporaryPath, markerPath);
+                linked = true;
+                await options.afterMarkerLinked?.();
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                await options.afterMarkerLinkConflict?.();
+            }
+            // On EEXIST, validate before fsync so corrupt or foreign content never
+            // becomes authority merely because it occupies the canonical path.
+            if (!linked) {
+                const beforeSync = await cleanupPublicationState(helperNonce, markerPath, options.journalPath);
+                if (beforeSync === "helper-absent")
+                    return;
+                if (beforeSync === "retry")
+                    continue;
+            }
+            await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+            // A legal drain can unlink the marker while this publisher is between
+            // link/read and fsync. It removes the exact helper first, so absence is
+            // safe only when that helper is also proven absent; otherwise retry the
+            // create-only publication with the same fully-synced temp inode.
+            const afterSync = await cleanupPublicationState(helperNonce, markerPath, options.journalPath);
+            if (afterSync === "published" || afterSync === "helper-absent")
+                return;
+        }
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker could not be published stably");
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Drain cleanup records independently of the current lifecycle journal. This
+ * lets a later Daemon retire a Windows-blocked helper even after a new
+ * operation has replaced the terminal journal that originally owned it.
+ */
+export async function drainStagedLifecycleHelperCleanup(options = {}) {
+    const directory = helperCleanupDirectory(options.journalPath);
+    const stat = await fs.lstat(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!stat)
+        return { removed: 0, pending: 0 };
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup directory is unsafe");
+    }
+    const names = await fs.readdir(directory);
+    names.sort();
+    let removed = 0;
+    let pending = 0;
+    for (const name of names) {
+        const match = /^([a-f0-9]{48})\.json$/u.exec(name);
+        if (!match) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup directory contains an unknown entry");
+        }
+        const helperNonce = match[1];
+        if (!helperNonce) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker name is invalid");
+        }
+        const marker = await readStagedLifecycleHelperCleanupMarker(path.join(directory, name)).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (!marker)
+            continue;
+        if (marker.helperNonce !== helperNonce) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker name does not match its content");
+        }
+        const outcome = await retireStagedLifecycleHelperFile(helperNonce, options);
+        if (outcome === "pending") {
+            pending += 1;
+            continue;
+        }
+        await removeStagedLifecycleHelperCleanupMarker(helperNonce, options);
+        removed += 1;
+    }
+    return { removed, pending };
+}
+async function retireStagedLifecycleHelperFile(helperNonce, options) {
+    assertHelperNonce(helperNonce);
+    const journalPath = options.journalPath ?? daemonLifecycleJournalPath;
+    const directory = path.join(path.dirname(path.resolve(journalPath)), "daemon-lifecycle-helpers-v1");
+    const targetPath = path.join(directory, `${helperNonce}.mjs`);
+    const retryDelaysMs = options.retryDelaysMs ?? [0, 50, 200, 500];
+    if (retryDelaysMs.length === 0) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup requires at least one attempt");
+    }
+    const sleep = options.sleep ?? ((durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs)));
+    const unlink = options.unlink ?? ((value) => fs.unlink(value));
+    for (let attempt = 0; attempt < retryDelaysMs.length; attempt += 1) {
+        const delayMs = retryDelaysMs[attempt] ?? 0;
+        if (delayMs > 0)
+            await sleep(delayMs);
+        const directoryStat = await fs.lstat(directory).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (!directoryStat)
+            return "absent";
+        if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper directory is unsafe");
+        }
+        const helperStat = await fs.lstat(targetPath).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (!helperStat) {
+            await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+            return "absent";
+        }
+        if (!helperStat.isFile() || helperStat.isSymbolicLink() || helperStat.size <= 0 || helperStat.size > maxBundledHelperBytes) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Staged lifecycle helper is not a safe regular file");
+        }
+        try {
+            await unlink(targetPath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+                return "absent";
+            }
+            if (!["EBUSY", "EPERM", "EACCES"].includes(code ?? ""))
+                throw error;
+            if (attempt === retryDelaysMs.length - 1)
+                return "pending";
+            continue;
+        }
+        // Once unlink succeeds, durability errors are not equivalent to a locked
+        // file. Propagate them so the per-nonce marker remains available for
+        // crash recovery instead of observing ENOENT on a misleading retry.
+        await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+        return "removed";
+    }
+    return "pending";
+}
+export async function spawnDetachedDaemonRestart(cwd, options = {}) {
+    const instanceNonce = options.instanceNonce ?? randomBytes(24).toString("hex");
+    const spec = detachedDaemonRestartSpawnSpec(cwd, instanceNonce, options);
+    const pid = await (options.spawnDetached ?? spawnDetachedProcess)(spec);
+    return { pid, instanceNonce };
+}
+export async function waitForDetachedDaemonRestart(expected, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const pollMs = options.pollMs ?? 100;
+    const sleep = options.sleep ?? ((durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs)));
+    const readPid = options.readPid ?? readPidFile;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const raw = await readPid();
+        if (raw !== undefined) {
+            const identity = parseDaemonPidIdentity(raw);
+            if (identity.record?.pid === expected.pid &&
+                identity.record.instanceNonce === expected.instanceNonce) {
+                const status = daemonProcessStatusForIdentity(identity, [options.expectedScriptPath ?? daemonScriptPath]);
+                if (status.running)
+                    return;
+            }
+        }
+        await sleep(pollMs);
+    }
+    throw lifecycleError("DAEMON_RESTART_SETTLEMENT_FAILED", "Detached daemon restart did not publish a verified owner before the deadline");
+}
+export async function findVerifiedDaemonRestart(instanceGeneration, options = {}) {
+    if (!/^[a-f0-9]{32,128}$/u.test(instanceGeneration)) {
+        throw lifecycleError("DAEMON_INSTANCE_NONCE_INVALID", "Daemon restart instance generation is invalid");
+    }
+    const raw = await (options.readPid ?? readPidFile)();
+    if (raw === undefined)
+        return undefined;
+    const identity = parseDaemonPidIdentity(raw);
+    const status = daemonProcessStatusForIdentity(identity, [options.expectedScriptPath ?? daemonScriptPath]);
+    if (status.alive && !status.running) {
+        throw lifecycleError("DAEMON_PID_UNVERIFIED", "A live process owns the daemon pid file but cannot be verified");
+    }
+    if (!status.running || !identity.record || identity.record.instanceNonce !== instanceGeneration)
+        return undefined;
+    return {
+        pid: identity.record.pid,
+        instanceNonce: identity.record.instanceNonce,
+        startedAt: identity.record.startedAt,
+    };
+}
+/**
+ * Stop only the replacement process whose pid and instance generation are
+ * still proven by the daemon pid identity. This is intentionally stricter
+ * than a generic process kill: PID reuse or a changed owner aborts the
+ * operation without signalling the observed process.
+ */
+export async function terminateVerifiedDaemonRestart(expected, options = {}) {
+    const findRestart = options.findRestart ?? findVerifiedDaemonRestart;
+    const signal = options.signal ?? ((pid, value) => process.kill(pid, value));
+    const sleep = options.sleep ?? ((durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs)));
+    const pollMs = options.pollMs ?? 100;
+    const current = await findRestart(expected.instanceNonce);
+    if (!current) {
+        if (!isDaemonProcessAlive(expected.pid))
+            return;
+        throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon is alive but its exact owner proof is missing");
+    }
+    if (current.pid !== expected.pid || current.instanceNonce !== expected.instanceNonce) {
+        throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon owner changed before rollback");
+    }
+    const expectedStartedAt = expected.startedAt ?? current.startedAt;
+    if (expectedStartedAt === undefined || current.startedAt === undefined || Math.abs(current.startedAt - expectedStartedAt) > 10_000) {
+        throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon process start identity could not be verified for rollback");
+    }
+    const exactExpected = { ...expected, startedAt: expectedStartedAt };
+    try {
+        signal(expected.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    if (await waitUntilRestartIsGone(exactExpected, options.timeoutMs ?? 5_000, pollMs, sleep))
+        return;
+    const beforeKill = await findRestart(expected.instanceNonce);
+    if (!beforeKill) {
+        if (!isDaemonProcessAlive(expected.pid))
+            return;
+        throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon is alive but its owner proof disappeared before forced termination");
+    }
+    if (beforeKill.pid !== expected.pid ||
+        beforeKill.instanceNonce !== expected.instanceNonce ||
+        beforeKill.startedAt === undefined ||
+        Math.abs(beforeKill.startedAt - expectedStartedAt) > 10_000) {
+        throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon owner changed before forced rollback termination");
+    }
+    try {
+        signal(expected.pid, "SIGKILL");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    if (await waitUntilRestartIsGone(exactExpected, options.killTimeoutMs ?? 2_000, pollMs, sleep))
+        return;
+    throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The exact upgraded daemon process could not be terminated for rollback");
+}
+async function waitUntilRestartIsGone(expected, timeoutMs, pollMs, sleep) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isDaemonProcessAlive(expected.pid))
+            return true;
+        const observedStartedAt = readDaemonProcessStartedAtMs(expected.pid);
+        if (observedStartedAt === undefined || Math.abs(observedStartedAt - expected.startedAt) > 10_000) {
+            throw lifecycleError("DAEMON_UPGRADE_ROLLBACK_FAILED", "The upgraded daemon process identity became unverified while rollback termination was settling");
+        }
+        await sleep(pollMs);
+    }
+    return false;
+}
+async function spawnDetachedProcess(spec) {
+    return await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(spec.command, spec.args, spec.options);
+        }
+        catch (error) {
+            reject(lifecycleError("DAEMON_LIFECYCLE_HELPER_SPAWN_FAILED", allowedSpawnMessage(error)));
+            return;
+        }
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            reject(lifecycleError("DAEMON_LIFECYCLE_HELPER_SPAWN_FAILED", "Detached lifecycle process did not spawn before the deadline"));
+        }, 5_000);
+        timer.unref?.();
+        child.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(lifecycleError("DAEMON_LIFECYCLE_HELPER_SPAWN_FAILED", allowedSpawnMessage(error)));
+        });
+        child.once("spawn", () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const pid = child.pid;
+            if (!pid) {
+                reject(lifecycleError("DAEMON_LIFECYCLE_HELPER_SPAWN_FAILED", "Detached lifecycle process did not return a pid"));
+                return;
+            }
+            child.unref();
+            resolve(pid);
+        });
+    });
+}
+function detachedHelperPath() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./detached-helper-cli.ts" : "./detached-helper-cli.js", import.meta.url));
+}
+function detachedHelperBundlePath() {
+    return fileURLToPath(new URL("./detached-helper-bundle.mjs", import.meta.url));
+}
+function lifecycleDaemonPathFromEnvironment() {
+    const value = process.env[lifecycleDaemonPathEnv];
+    return value && path.isAbsolute(value) ? value : undefined;
+}
+async function ensurePrivateHelperDirectory(directory) {
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper directory is not a private directory");
+    }
+    await fs.chmod(directory, 0o700);
+}
+async function readRegularHelper(filePath, allowMissing = false) {
+    const stat = await fs.lstat(filePath).catch((error) => {
+        if (allowMissing && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!stat)
+        return undefined;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > maxBundledHelperBytes) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper bundle is not a safe regular file");
+    }
+    return await fs.readFile(filePath);
+}
+function helperDigest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function helperCleanupDirectory(journalPath = daemonLifecycleJournalPath) {
+    return path.join(path.dirname(path.resolve(journalPath)), "daemon-lifecycle-helper-cleanup-v1");
+}
+function helperCleanupMarkerPath(helperNonce, journalPath) {
+    return path.join(helperCleanupDirectory(journalPath), `${helperNonce}.json`);
+}
+function helperCleanupMarker(helperNonce) {
+    return {
+        version: helperCleanupMarkerVersion,
+        helperNonce,
+        checksum: createHash("sha256")
+            .update("daemon-lifecycle-helper-cleanup-v1\n")
+            .update(helperNonce)
+            .digest("hex"),
+    };
+}
+async function readStagedLifecycleHelperCleanupMarker(markerPath) {
+    const stat = await fs.lstat(markerPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 4 * 1024) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker is not a safe regular file");
+    }
+    const raw = await fs.readFile(markerPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker has an invalid root");
+    }
+    const value = parsed;
+    const keys = Object.keys(value).sort();
+    if (keys.length !== 3 ||
+        keys[0] !== "checksum" ||
+        keys[1] !== "helperNonce" ||
+        keys[2] !== "version" ||
+        value.version !== helperCleanupMarkerVersion ||
+        typeof value.helperNonce !== "string" ||
+        !/^[a-f0-9]{48}$/u.test(value.helperNonce) ||
+        typeof value.checksum !== "string") {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker has an invalid shape");
+    }
+    const expected = helperCleanupMarker(value.helperNonce);
+    if (value.checksum !== expected.checksum) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker checksum does not match");
+    }
+    return expected;
+}
+async function cleanupPublicationState(helperNonce, markerPath, journalPath) {
+    const marker = await readStagedLifecycleHelperCleanupMarker(markerPath).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (marker) {
+        if (marker.helperNonce !== helperNonce) {
+            throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker ownership changed");
+        }
+        return "published";
+    }
+    return await stagedLifecycleHelperExists(helperNonce, journalPath) ? "retry" : "helper-absent";
+}
+async function stagedLifecycleHelperExists(helperNonce, journalPath = daemonLifecycleJournalPath) {
+    const directory = path.join(path.dirname(path.resolve(journalPath)), "daemon-lifecycle-helpers-v1");
+    const directoryStat = await fs.lstat(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!directoryStat)
+        return false;
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper directory is unsafe");
+    }
+    const targetPath = path.join(directory, `${helperNonce}.mjs`);
+    const helperStat = await fs.lstat(targetPath).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!helperStat)
+        return false;
+    if (!helperStat.isFile() || helperStat.isSymbolicLink() || helperStat.size <= 0 || helperStat.size > maxBundledHelperBytes) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Staged lifecycle helper is not a safe regular file");
+    }
+    return true;
+}
+async function removeStagedLifecycleHelperCleanupMarker(helperNonce, options) {
+    const directory = helperCleanupDirectory(options.journalPath);
+    const markerPath = helperCleanupMarkerPath(helperNonce, options.journalPath);
+    const marker = await readStagedLifecycleHelperCleanupMarker(markerPath).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!marker)
+        return;
+    if (marker.helperNonce !== helperNonce) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_PATH_INVALID", "Lifecycle helper cleanup marker ownership changed");
+    }
+    await fs.unlink(markerPath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+    await syncLifecycleDirectory(directory, options.syncDirectory, options.platform);
+}
+async function syncLifecycleDirectory(directory, sync, platform = process.platform) {
+    let directoryHandle;
+    try {
+        if (sync) {
+            await sync(directory);
+            return;
+        }
+        directoryHandle = await fs.open(directory, "r");
+        await directoryHandle.sync();
+    }
+    catch (error) {
+        const code = error.code ?? "";
+        if (platform !== "win32" || !["EINVAL", "ENOTSUP", "EISDIR", "EPERM"].includes(code))
+            throw error;
+    }
+    finally {
+        await directoryHandle?.close();
+    }
+}
+function fixedDetachedOptions(cwd, sourceEnv) {
+    const env = { ...sourceEnv };
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === "node_options")
+            delete env[key];
+    }
+    return {
+        cwd,
+        env,
+        detached: true,
+        shell: false,
+        stdio: "ignore",
+        windowsHide: true,
+        windowsVerbatimArguments: false,
+    };
+}
+function assertLifecycleIdentifier(value, label) {
+    if (!/^[A-Za-z0-9._:-]{1,200}$/u.test(value)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_REQUEST_INVALID", `Daemon lifecycle ${label} is invalid`);
+    }
+}
+function assertHelperNonce(helperNonce) {
+    if (!/^[a-f0-9]{48}$/u.test(helperNonce)) {
+        throw lifecycleError("DAEMON_LIFECYCLE_HELPER_ID_INVALID", "Daemon lifecycle helper nonce is invalid");
+    }
+}
+async function readPidFile() {
+    try {
+        return await fs.readFile(pidPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function allowedSpawnMessage(error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    return code && new Set(["ENOENT", "EACCES", "EPERM"]).has(code)
+        ? `Could not spawn the fixed lifecycle executable (${code})`
+        : "Could not spawn the fixed lifecycle executable";
+}

package/apps/daemon/dist/lifecycle/runtime.d.ts

@@ -0,0 +1,36 @@
+import { runDetachedLifecycleOperation } from "./helper.js";
+import { transitionDaemonLifecycleJournal, type DaemonLifecycleJournalOptions } from "./journal.js";
+export type ActiveDaemonLifecycleRuntime = {
+    daemonId: string;
+    instanceGeneration: string;
+    requestShutdown(): void;
+};
+type LifecycleStartOptions = DaemonLifecycleJournalOptions & {
+    processId?: number;
+    processStartedAt?: number;
+    helperNonce?: string;
+    recover?: typeof runDetachedLifecycleOperation;
+    afterHelperCleanupQueued?: () => Promise<void>;
+};
+export declare function configureDaemonLifecycleRuntime(runtime: ActiveDaemonLifecycleRuntime): void;
+export declare function clearDaemonLifecycleRuntime(instanceGeneration: string): void;
+export declare function daemonLifecycleRuntime(): ActiveDaemonLifecycleRuntime;
+/**
+ * During upgrade/restart, the lifetime lock is intentionally absent after the
+ * old daemon exits. The journal is the only authority that can let a new
+ * daemon cross that window. If the helper died, this start process atomically
+ * becomes the recovery helper, resumes the recorded phase, and exits instead
+ * of racing the replacement daemon it launches.
+ */
+export declare function assertDaemonLifecycleStartAllowed(instanceGeneration: string, options?: LifecycleStartOptions): Promise<"start" | "recovered">;
+export declare function settleAuthorizedLifecycleRestartAfterRelayAuthentication(input: {
+    daemonId: string;
+    instanceGeneration: string;
+    pid?: number;
+}, options?: DaemonLifecycleJournalOptions & {
+    now?: () => Date;
+    processStartedAt?: number;
+    afterReplacementPublication?: (journal: Awaited<ReturnType<typeof transitionDaemonLifecycleJournal>>) => Promise<void>;
+    verifyRunningVersion?: (expectedVersion: string, packageRoot: string) => Promise<void>;
+}): Promise<void>;
+export {};