@nowcrew/daemon 0.5.12 → 0.5.13

package/dist/execution-journal.js

@@ -0,0 +1,678 @@
+import { execFile } from "node:child_process";
+import { open, mkdir, readFile, readdir, rename, rm, unlink, } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { z } from "zod";
+import { ExecutionCompletedSchema, EffectivePermissionSchema, } from "./execution-protocol.js";
+import { JournalLockedError, createJournalLease, } from "./execution-journal-lock.js";
+export { JournalLockedError, JournalLockCorruptionError } from "./execution-journal-lock.js";
+const ExecutionIdSchema = z.string().uuid();
+const TimestampSchema = z.string().datetime({ offset: true });
+const RuntimeSchema = z.enum(["claude", "codex", "kimi"]);
+const RawJournalEntrySchema = z.object({
+    executionId: ExecutionIdSchema,
+    specHash: z.string().min(1),
+    state: z.enum(["accepted", "running", "completed", "interrupted"]),
+    pid: z.number().int().positive().nullable(),
+    completion: ExecutionCompletedSchema.nullable(),
+    completionAcknowledged: z.boolean(),
+    updatedAt: TimestampSchema,
+    requestedRuntime: RuntimeSchema,
+    requestedModel: z.string().nullable(),
+    resumed: z.boolean(),
+    acceptedAt: TimestampSchema,
+    processStartedAt: TimestampSchema.nullable(),
+    processIdentity: z.string().min(1).refine((value) => value.trim().length > 0).nullable(),
+    // Optional for journals written before execution permission persistence was introduced.
+    effectivePermission: EffectivePermissionSchema.nullable().optional(),
+}).strict();
+export const JournalEntrySchema = RawJournalEntrySchema.superRefine((entry, ctx) => {
+    const issue = (message, path) => {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message, path: [path] });
+    };
+    if (entry.state === "accepted") {
+        if (entry.pid !== null)
+            issue("accepted entry cannot have a pid", "pid");
+        if (entry.processStartedAt !== null) {
+            issue("accepted entry cannot have processStartedAt", "processStartedAt");
+        }
+        if (entry.processIdentity !== null)
+            issue("accepted entry cannot have processIdentity", "processIdentity");
+        if (entry.completion !== null)
+            issue("accepted entry cannot have a completion", "completion");
+    }
+    if (entry.state === "running") {
+        if (entry.pid === null)
+            issue("running entry requires a pid", "pid");
+        if (entry.processStartedAt === null) {
+            issue("running entry requires processStartedAt", "processStartedAt");
+        }
+        if (entry.processIdentity === null)
+            issue("running entry requires processIdentity", "processIdentity");
+        if (entry.completion !== null)
+            issue("running entry cannot have a completion", "completion");
+    }
+    if (entry.state === "completed" || entry.state === "interrupted") {
+        if (entry.pid !== null)
+            issue("terminal entry cannot have a pid", "pid");
+        if (entry.completion === null)
+            issue("terminal entry requires a completion", "completion");
+        if (entry.completion !== null && entry.completion.executionId !== entry.executionId) {
+            issue("terminal completion executionId must match the entry", "completion");
+        }
+    }
+    if (entry.state === "interrupted" && entry.completion !== null) {
+        if (entry.completion.outcome !== "failed" || entry.completion.errorCode !== "interrupted") {
+            issue("interrupted entry requires an interrupted failed completion", "completion");
+        }
+    }
+    if ((entry.state === "accepted" || entry.state === "running") && entry.completionAcknowledged) {
+        issue("active entry cannot acknowledge completion", "completionAcknowledged");
+    }
+});
+const runningProcessIdentityBrand = Symbol("runningProcessIdentity");
+export class JournalConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JournalConflictError";
+    }
+}
+export class JournalTransitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JournalTransitionError";
+    }
+}
+export class JournalCorruptionError extends Error {
+    constructor(path, cause) {
+        super(`Invalid execution journal record: ${path}`, { cause });
+        this.name = "JournalCorruptionError";
+    }
+}
+export class JournalRecoveryError extends Error {
+    constructor(message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "JournalRecoveryError";
+    }
+}
+export async function captureRunningProcessIdentity(pid, processStartedAt, controller = defaultProcessController) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        throw new TypeError("pid must be a positive safe integer");
+    }
+    TimestampSchema.parse(processStartedAt);
+    let processIdentity;
+    try {
+        processIdentity = await controller.inspectIdentity(pid);
+    }
+    catch (error) {
+        throw new JournalRecoveryError(`Failed to inspect process ${pid} after spawn`, error);
+    }
+    if (processIdentity === null || processIdentity.trim().length === 0) {
+        throw new JournalRecoveryError(`Process ${pid} has no verifiable identity after spawn`);
+    }
+    return {
+        pid,
+        processStartedAt,
+        processIdentity,
+        [runningProcessIdentityBrand]: true,
+    };
+}
+const DEFAULT_RETENTION_DAYS = 7;
+const DEFAULT_MAX_ENTRIES = 10_000;
+const DEFAULT_TERMINATION_GRACE_MS = 30_000;
+const DEFAULT_KILL_VERIFICATION_DELAY_MS = 100;
+const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
+const directoryQueues = new Map();
+function runSerialized(directory, operation) {
+    const previous = directoryQueues.get(directory) ?? Promise.resolve();
+    const result = previous.then(operation, operation);
+    directoryQueues.set(directory, result.then(() => undefined, () => undefined));
+    return result;
+}
+function runCommand(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(command, [...args], { encoding: "utf8", ...options }, (error, stdout) => {
+            if (error !== null)
+                reject(error);
+            else
+                resolve({ stdout });
+        });
+    });
+}
+function errorCode(error) {
+    return error instanceof Error && "code" in error && (typeof error.code === "string"
+        || typeof error.code === "number")
+        ? error.code
+        : undefined;
+}
+function linuxIdentity(raw) {
+    const commandEnd = raw.lastIndexOf(")");
+    if (commandEnd < 0)
+        throw new Error("Malformed /proc stat: missing command terminator");
+    const fields = raw.slice(commandEnd + 1).trim().split(/\s+/);
+    const startTimeTicks = fields[19];
+    if (startTimeTicks === undefined || !/^\d+$/.test(startTimeTicks)) {
+        throw new Error("Malformed /proc stat: missing starttime");
+    }
+    return startTimeTicks;
+}
+function linuxBootId(raw) {
+    const bootId = raw.trim().toLowerCase();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(bootId)) {
+        throw new Error("Malformed Linux boot identity");
+    }
+    return bootId;
+}
+export function createProcessController(dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const readTextFile = dependencies.readTextFile ?? ((path) => readFile(path, "utf8"));
+    const execute = dependencies.runCommand ?? runCommand;
+    const commandTimeoutMs = dependencies.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    const supervisorTree = dependencies.supervisorTree ?? false;
+    if (!Number.isFinite(commandTimeoutMs) || commandTimeoutMs <= 0) {
+        throw new RangeError("commandTimeoutMs must be a positive finite number");
+    }
+    const executeWithTimeout = async (command, args, options = {}) => {
+        const abortController = new AbortController();
+        const commandPromise = execute(command, args, { ...options, signal: abortController.signal });
+        commandPromise.catch(() => undefined);
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                abortController.abort();
+                reject(new Error(`Process identity command timed out after ${commandTimeoutMs}ms`));
+            }, commandTimeoutMs);
+        });
+        try {
+            return await Promise.race([commandPromise, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+    const inspectIdentity = async (pid) => {
+        if (platform === "linux") {
+            let startTimeTicks;
+            try {
+                startTimeTicks = linuxIdentity(await readTextFile(`/proc/${pid}/stat`));
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    return null;
+                throw error;
+            }
+            const bootId = linuxBootId(await readTextFile("/proc/sys/kernel/random/boot_id"));
+            return `linux:${bootId}:${startTimeTicks}`;
+        }
+        if (platform === "win32") {
+            const script = `$p=Get-Process -Id ${pid} -ErrorAction SilentlyContinue; `
+                + "if ($null -eq $p) { Write-Output '__ABSENT__'; exit 0 }; "
+                + "Write-Output ('windows:' + $p.StartTime.ToUniversalTime().ToFileTimeUtc())";
+            const { stdout } = await executeWithTimeout("powershell.exe", [
+                "-NoProfile", "-NonInteractive", "-Command", script,
+            ]);
+            const token = stdout.trim();
+            if (token === "__ABSENT__")
+                return null;
+            if (!/^windows:\d+$/.test(token))
+                throw new Error("Malformed PowerShell process identity");
+            return token;
+        }
+        try {
+            const { stdout } = await executeWithTimeout("ps", ["-p", String(pid), "-o", "lstart="], { env: { ...process.env, LC_ALL: "C", LANG: "C" } });
+            const token = stdout.trim().replace(/\s+/g, " ");
+            if (token.length === 0)
+                throw new Error("Malformed ps process identity");
+            return `unix:${token}`;
+        }
+        catch (error) {
+            if (errorCode(error) === 1)
+                return null;
+            throw error;
+        }
+    };
+    return {
+        inspectIdentity,
+        signal: dependencies.signal ?? (async (pid, signal) => {
+            if (!supervisorTree) {
+                process.kill(pid, signal);
+                return;
+            }
+            if (platform === "win32") {
+                await executeWithTimeout("taskkill.exe", [
+                    "/PID", String(pid), "/T", ...(signal === "SIGKILL" ? ["/F"] : []),
+                ]);
+                return;
+            }
+            process.kill(-pid, signal);
+        }),
+        wait: dependencies.wait ?? (async (milliseconds) => {
+            await new Promise((resolve) => setTimeout(resolve, milliseconds));
+        }),
+    };
+}
+export const defaultProcessController = createProcessController();
+export const defaultSupervisorProcessController = createProcessController({
+    supervisorTree: true,
+});
+function assertNonnegativeFinite(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${name} must be a nonnegative finite number`);
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function sameValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function validateExecutionId(executionId) {
+    if (!ExecutionIdSchema.safeParse(executionId).success) {
+        throw new TypeError("Invalid executionId: expected UUID");
+    }
+}
+export function createExecutionJournal(agentsRoot, options = {}) {
+    const directory = join(agentsRoot, ".crew", "executions");
+    const now = options.now ?? (() => new Date());
+    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const terminationGraceMs = options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS;
+    const killVerificationDelayMs = options.killVerificationDelayMs
+        ?? DEFAULT_KILL_VERIFICATION_DELAY_MS;
+    const processController = options.processController ?? defaultSupervisorProcessController;
+    const lockProcessController = options.lockProcessController ?? defaultProcessController;
+    const platform = options.platform ?? process.platform;
+    assertNonnegativeFinite(retentionDays, "retentionDays");
+    assertNonnegativeFinite(maxEntries, "maxEntries");
+    assertNonnegativeFinite(terminationGraceMs, "terminationGraceMs");
+    assertNonnegativeFinite(killVerificationDelayMs, "killVerificationDelayMs");
+    if (!Number.isInteger(maxEntries))
+        throw new RangeError("maxEntries must be an integer");
+    let initialized = false;
+    const recordPath = (executionId) => join(directory, `${executionId}.json`);
+    const parseRecord = (path, raw) => {
+        try {
+            const entry = JournalEntrySchema.parse(JSON.parse(raw));
+            const filename = basename(path, ".json");
+            if (entry.executionId !== filename) {
+                throw new Error("executionId does not match the journal filename");
+            }
+            return entry;
+        }
+        catch (error) {
+            throw new JournalCorruptionError(path, error);
+        }
+    };
+    const readRecord = async (executionId) => {
+        const path = recordPath(executionId);
+        try {
+            return parseRecord(path, await readFile(path, "utf8"));
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return null;
+            throw error;
+        }
+    };
+    const readAll = async () => {
+        const names = (await readdir(directory))
+            .filter((name) => name.endsWith(".json"))
+            .sort();
+        const entries = [];
+        for (const name of names) {
+            const path = join(directory, name);
+            entries.push(parseRecord(path, await readFile(path, "utf8")));
+        }
+        return entries;
+    };
+    const defaultSyncDirectory = async (path) => {
+        if (platform === "win32")
+            return;
+        const handle = await open(path, "r");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    const fsyncDirectory = options.syncDirectory ?? defaultSyncDirectory;
+    const fsyncFinalFile = async (path) => {
+        const handle = await open(path, "r+");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    const lease = createJournalLease({
+        directory,
+        currentPid: process.pid,
+        captureCurrentIdentity: async () => {
+            try {
+                const identity = await lockProcessController.inspectIdentity(process.pid);
+                if (identity === null)
+                    throw new Error("current process identity is absent");
+                return identity;
+            }
+            catch (error) {
+                throw new JournalRecoveryError("Failed to capture journal lock owner identity", error);
+            }
+        },
+        inspectIdentity: async (pid) => {
+            try {
+                return await lockProcessController.inspectIdentity(pid);
+            }
+            catch (error) {
+                throw new JournalRecoveryError("Failed to inspect journal lock owner", error);
+            }
+        },
+        syncDirectory: fsyncDirectory,
+        ...(options.lockFileSystem === undefined ? {} : { fileSystem: options.lockFileSystem }),
+        ...(options.lockHooks === undefined ? {} : { hooks: options.lockHooks }),
+        ...(options.lockNow === undefined ? {} : { now: options.lockNow }),
+        ...(options.lockOrphanGraceMs === undefined
+            ? {}
+            : { orphanGraceMs: options.lockOrphanGraceMs }),
+    });
+    const confirmDurable = async (entry) => {
+        const diskEntry = await readRecord(entry.executionId);
+        if (diskEntry === null || !sameValue(diskEntry, entry)) {
+            throw new JournalCorruptionError(recordPath(entry.executionId), new Error("Durable journal record does not match expected entry"));
+        }
+        await fsyncFinalFile(recordPath(entry.executionId));
+        await fsyncDirectory(directory);
+        return diskEntry;
+    };
+    const writeRecord = async (entry) => {
+        const validated = JournalEntrySchema.parse(entry);
+        const temporaryPath = join(directory, `${entry.executionId}.tmp`);
+        let handle = null;
+        try {
+            handle = await open(temporaryPath, "w", 0o600);
+            await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = null;
+            const finalPath = recordPath(entry.executionId);
+            await rename(temporaryPath, finalPath);
+            await confirmDurable(validated);
+        }
+        catch (error) {
+            if (handle !== null)
+                await handle.close().catch(() => undefined);
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    };
+    const pruneInternal = async () => {
+        const entries = await readAll();
+        const acknowledged = entries
+            .filter((entry) => (entry.state === "completed" || entry.state === "interrupted")
+            && entry.completionAcknowledged)
+            .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt)
+            || left.executionId.localeCompare(right.executionId));
+        const cutoff = now().valueOf() - retentionDays * 24 * 60 * 60 * 1_000;
+        const expired = acknowledged.filter((entry) => Date.parse(entry.updatedAt) < cutoff);
+        const retained = acknowledged.filter((entry) => Date.parse(entry.updatedAt) >= cutoff);
+        const overLimit = retained.slice(0, Math.max(0, retained.length - maxEntries));
+        const toDelete = new Set([...expired, ...overLimit].map((entry) => entry.executionId));
+        for (const executionId of toDelete) {
+            await unlink(recordPath(executionId));
+        }
+        if (toDelete.size > 0)
+            await fsyncDirectory(directory);
+    };
+    const initialize = async () => {
+        if (initialized)
+            return;
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await lease.acquire();
+        const names = await readdir(directory);
+        for (const name of names.filter((candidate) => candidate.endsWith(".tmp"))) {
+            await rm(join(directory, name), { force: true });
+        }
+        await pruneInternal();
+        initialized = true;
+    };
+    const serialized = (operation) => runSerialized(directory, async () => {
+        lease.assertUsable();
+        await initialize();
+        return operation();
+    });
+    const requireRecord = async (executionId) => {
+        const entry = await readRecord(executionId);
+        if (entry === null)
+            throw new JournalTransitionError(`Unknown execution: ${executionId}`);
+        return entry;
+    };
+    const interruptedCompletion = (entry) => {
+        const startedAt = entry.state === "running" && entry.processStartedAt !== null
+            ? entry.processStartedAt
+            : entry.acceptedAt;
+        return ExecutionCompletedSchema.parse({
+            type: "execution:completed",
+            protocolVersion: 1,
+            executionId: entry.executionId,
+            outcome: "failed",
+            errorCode: "interrupted",
+            runtime: entry.requestedRuntime,
+            ...(entry.requestedModel === null ? {} : { model: entry.requestedModel }),
+            resumed: entry.resumed,
+            startedAt,
+            finishedAt: now().toISOString(),
+        });
+    };
+    const writeInterrupted = async (entry) => {
+        await writeRecord({
+            ...entry,
+            state: "interrupted",
+            pid: null,
+            completion: interruptedCompletion(entry),
+            completionAcknowledged: false,
+            updatedAt: now().toISOString(),
+        });
+    };
+    const inspectForRecovery = async (pid) => {
+        try {
+            return await processController.inspectIdentity(pid);
+        }
+        catch (error) {
+            throw new JournalRecoveryError(`Failed to inspect running process ${pid}`, error);
+        }
+    };
+    const waitForRecovery = async (milliseconds, phase) => {
+        try {
+            await processController.wait(milliseconds);
+        }
+        catch (error) {
+            throw new JournalRecoveryError(`Failed while waiting ${phase}`, error);
+        }
+    };
+    const proveRunningProcessStopped = async (entry) => {
+        if (entry.pid === null || entry.processIdentity === null) {
+            throw new JournalRecoveryError(`Execution ${entry.executionId} lacks process identity`);
+        }
+        const { pid, processIdentity } = entry;
+        const initialIdentity = await inspectForRecovery(pid);
+        if (initialIdentity === null || initialIdentity !== processIdentity)
+            return;
+        try {
+            await processController.signal(pid, "SIGTERM");
+        }
+        catch (error) {
+            if (errorCode(error) === "ESRCH")
+                return;
+            throw new JournalRecoveryError(`Failed to terminate process ${pid}`, error);
+        }
+        await waitForRecovery(terminationGraceMs, "for process termination");
+        const afterTerm = await inspectForRecovery(pid);
+        if (afterTerm === null || afterTerm !== processIdentity)
+            return;
+        try {
+            await processController.signal(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (errorCode(error) === "ESRCH")
+                return;
+            throw new JournalRecoveryError(`Failed to kill process ${pid}`, error);
+        }
+        await waitForRecovery(killVerificationDelayMs, "to verify process kill");
+        const afterKill = await inspectForRecovery(pid);
+        if (afterKill === null || afterKill !== processIdentity)
+            return;
+        throw new JournalRecoveryError(`Process ${pid} still matches after SIGKILL`);
+    };
+    return {
+        accept: async (executionId, specHash, recoveryFacts) => {
+            validateExecutionId(executionId);
+            if (specHash.length === 0)
+                throw new TypeError("specHash must not be empty");
+            return serialized(async () => {
+                const existing = await readRecord(executionId);
+                if (existing !== null) {
+                    if (existing.specHash !== specHash) {
+                        throw new JournalConflictError(`Execution ${executionId} already has a different specHash`);
+                    }
+                    return { kind: "existing", ...await confirmDurable(existing) };
+                }
+                const timestamp = now().toISOString();
+                const entry = JournalEntrySchema.parse({
+                    executionId,
+                    specHash,
+                    state: "accepted",
+                    pid: null,
+                    completion: null,
+                    completionAcknowledged: false,
+                    updatedAt: timestamp,
+                    requestedRuntime: recoveryFacts.runtime,
+                    requestedModel: recoveryFacts.model ?? null,
+                    resumed: recoveryFacts.resumed ?? false,
+                    acceptedAt: timestamp,
+                    processStartedAt: null,
+                    processIdentity: null,
+                    effectivePermission: recoveryFacts.effectivePermission ?? null,
+                });
+                await writeRecord(entry);
+                return { kind: "created", ...entry };
+            });
+        },
+        startGuarded: async (executionId, processStartedAt, startDormant) => {
+            validateExecutionId(executionId);
+            TimestampSchema.parse(processStartedAt);
+            return serialized(async () => {
+                const entry = await requireRecord(executionId);
+                if (entry.state !== "accepted") {
+                    return { kind: "existing", entry: await confirmDurable(entry) };
+                }
+                const dormant = await startDormant();
+                const abortWith = async (error) => {
+                    try {
+                        await dormant.abort();
+                    }
+                    catch (abortError) {
+                        throw new AggregateError([error, abortError], "Dormant runtime abort failed");
+                    }
+                    throw error;
+                };
+                try {
+                    if (dormant.parentExitGuard !== "pipe-eof") {
+                        throw new TypeError("Dormant runtime must use a pipe-eof parent exit guard");
+                    }
+                    const identity = await captureRunningProcessIdentity(dormant.pid, processStartedAt, processController);
+                    const updated = JournalEntrySchema.parse({
+                        ...entry,
+                        state: "running",
+                        pid: identity.pid,
+                        processStartedAt: identity.processStartedAt,
+                        processIdentity: identity.processIdentity,
+                        updatedAt: now().toISOString(),
+                    });
+                    await writeRecord(updated);
+                    try {
+                        await dormant.release();
+                    }
+                    catch (error) {
+                        return abortWith(error);
+                    }
+                    return { kind: "started", entry: updated, handle: dormant };
+                }
+                catch (error) {
+                    return abortWith(error);
+                }
+            });
+        },
+        complete: async (executionId, completionInput) => {
+            validateExecutionId(executionId);
+            const completion = ExecutionCompletedSchema.parse(completionInput);
+            if (completion.executionId !== executionId) {
+                throw new JournalConflictError("Completion executionId does not match the journal record");
+            }
+            return serialized(async () => {
+                const entry = await requireRecord(executionId);
+                if (entry.state === "completed" || entry.state === "interrupted") {
+                    if (sameValue(entry.completion, completion))
+                        return confirmDurable(entry);
+                    throw new JournalConflictError(`Execution ${executionId} already has a different completion`);
+                }
+                const updated = JournalEntrySchema.parse({
+                    ...entry,
+                    state: "completed",
+                    pid: null,
+                    completion,
+                    completionAcknowledged: false,
+                    updatedAt: now().toISOString(),
+                });
+                await writeRecord(updated);
+                return updated;
+            });
+        },
+        acknowledgeCompletion: async (executionId) => {
+            validateExecutionId(executionId);
+            return serialized(async () => {
+                const entry = await requireRecord(executionId);
+                if (entry.state !== "completed" && entry.state !== "interrupted") {
+                    throw new JournalTransitionError(`Cannot acknowledge ${entry.state} execution`);
+                }
+                if (entry.completionAcknowledged)
+                    return confirmDurable(entry);
+                const updated = JournalEntrySchema.parse({
+                    ...entry,
+                    completionAcknowledged: true,
+                    updatedAt: now().toISOString(),
+                });
+                await writeRecord(updated);
+                await pruneInternal();
+                return updated;
+            });
+        },
+        get: async (executionId) => {
+            validateExecutionId(executionId);
+            return serialized(() => readRecord(executionId));
+        },
+        replay: async () => serialized(async () => (await readAll())
+            .filter((entry) => entry.state === "accepted"
+            || entry.state === "running"
+            || !entry.completionAcknowledged)
+            .sort((left, right) => left.executionId.localeCompare(right.executionId))),
+        reconcileAfterRestart: async () => serialized(async () => {
+            const active = (await readAll()).filter((entry) => entry.state === "accepted" || entry.state === "running");
+            const results = await Promise.allSettled(active.map(async (entry) => {
+                if (entry.state === "running")
+                    await proveRunningProcessStopped(entry);
+                await writeInterrupted(entry);
+            }));
+            const failures = results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (failures.length > 0) {
+                throw new AggregateError(failures, "One or more executions could not be reconciled");
+            }
+        }),
+        prune: async () => serialized(pruneInternal),
+        close: async () => {
+            await runSerialized(directory, lease.close);
+        },
+    };
+}