stageflow 0.31.0 → 0.33.0

package/dist/email/attachments.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { EmailAccount } from "./accounts.js";
+import { type EmailArtifactContext, type SendEmailInput, type PreparedEmailAttachment, type DownloadEmailAttachmentResult } from "./port.js";
+export declare const attachmentReferencesSchema: z.ZodArray<z.ZodObject<{
+    artifact: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const attachmentLimitsSchema: z.ZodObject<{
+    count: z.ZodDefault<z.ZodNumber>;
+    perFileBytes: z.ZodDefault<z.ZodNumber>;
+    totalBytes: z.ZodDefault<z.ZodNumber>;
+    downloadBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare function safeAttachmentFilename(filename: string | undefined): string;
+export declare function prepareAttachments(account: EmailAccount, references: SendEmailInput["attachments"], context?: EmailArtifactContext): Promise<PreparedEmailAttachment[]>;
+export declare function attachmentIdentity(attachments: PreparedEmailAttachment[]): {
+    filename: string;
+    size: number;
+    sha256: string;
+}[];
+export declare function saveSelectedAttachment(account: EmailAccount, source: Buffer, attachmentId: string, context: EmailArtifactContext, validateAccount: () => void): Promise<DownloadEmailAttachmentResult>;

package/dist/email/attachments.js

@@ -0,0 +1,146 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+import { simpleParser } from "mailparser";
+import { z } from "zod";
+import { isInsideDir, resolveArtifactTarget } from "../runstore/workspaceLayout.js";
+import { EmailError } from "./port.js";
+export const attachmentReferencesSchema = z.array(z.object({ artifact: z.string().min(1).max(2048), filename: z.string().max(200).optional() }).strict()).max(100);
+export const attachmentLimitsSchema = z.object({
+    count: z.number().int().min(1).max(100).default(10),
+    perFileBytes: z.number().int().min(1).max(16 * 1024 * 1024).default(2 * 1024 * 1024),
+    totalBytes: z.number().int().min(1).max(32 * 1024 * 1024).default(5 * 1024 * 1024),
+    downloadBytes: z.number().int().min(1).max(32 * 1024 * 1024).default(8 * 1024 * 1024),
+}).strict();
+export function safeAttachmentFilename(filename) {
+    const name = (filename ?? "attachment").split(/[/\\]/).at(-1).replace(/[\x00-\x1f\x7f]/g, "_").replace(/[^\p{L}\p{N} ._()-]/gu, "_").slice(0, 200).trim();
+    return !name || name === "." || name === ".." ? "attachment" : name;
+}
+/** Reject symlinks in every descendant, including artifact directories. */
+async function containedPath(context, relative, createDirectories = false) {
+    if (typeof relative !== "string" || relative.includes("\\") || path.isAbsolute(relative) || relative.split("/").some(segment => !segment || segment === "." || segment === ".." || segment === ".pi-agent" || segment === "auth.json" || segment === "pi-session.jsonl"))
+        throw new EmailError("EMAIL_UNAUTHORIZED");
+    const root = await realpath(context.workspaceDir);
+    const segments = relative.split("/");
+    let current = root;
+    for (let index = 0; index < segments.length; index++) {
+        current = path.join(current, segments[index]);
+        const last = index === segments.length - 1;
+        if (createDirectories && !last)
+            await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST")
+                throw error; });
+        if (createDirectories && last)
+            break;
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink() || (!last && !stat.isDirectory()) || (last && (!stat.isFile() || stat.nlink !== 1)))
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+        const resolved = await realpath(current);
+        if (!isInsideDir(resolved, root))
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+    }
+    return current;
+}
+export async function prepareAttachments(account, references, context) {
+    if (!references?.length)
+        return [];
+    if (!context)
+        throw new EmailError("EMAIL_UNAUTHORIZED");
+    if (references.length > account.attachmentLimits.count)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    let total = 0;
+    const attachments = [];
+    for (const reference of references) {
+        // Only run artifact files are eligible; arbitrary run files are not.
+        if (!/^stages\/[^/]+\/(?:attempts\/[1-9]\d*\/)?artifacts\/.+/.test(reference.artifact))
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+        let handle;
+        try {
+            const target = await containedPath(context, reference.artifact);
+            handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1)
+                throw new EmailError("EMAIL_UNAUTHORIZED");
+            await containedPath(context, reference.artifact);
+            const checked = await lstat(target);
+            if (checked.dev !== stat.dev || checked.ino !== stat.ino || !checked.isFile() || checked.nlink !== 1)
+                throw new EmailError("EMAIL_UNAUTHORIZED");
+            const limit = Math.min(account.attachmentLimits.perFileBytes, account.attachmentLimits.totalBytes - total);
+            if (stat.size > limit)
+                throw new EmailError("EMAIL_RESOURCE_LIMIT");
+            // Read from this descriptor once. Hash and SMTP use these same bounded bytes.
+            const content = Buffer.alloc(limit + 1);
+            let size = 0;
+            while (size <= limit) {
+                const read = await handle.read(content, size, Math.min(65536, content.length - size), null);
+                if (!read.bytesRead)
+                    break;
+                size += read.bytesRead;
+            }
+            if (size > limit)
+                throw new EmailError("EMAIL_RESOURCE_LIMIT");
+            total += size;
+            attachments.push({ filename: safeAttachmentFilename(reference.filename ?? path.basename(reference.artifact)), content: Buffer.from(content.subarray(0, size)) });
+        }
+        catch (error) {
+            if (error instanceof EmailError)
+                throw error;
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    return attachments;
+}
+export function attachmentIdentity(attachments) {
+    return attachments.map(value => ({ filename: value.filename, size: value.content.length, sha256: createHash("sha256").update(value.content).digest("hex") }));
+}
+export async function saveSelectedAttachment(account, source, attachmentId, context, validateAccount) {
+    if (source.length > account.attachmentLimits.downloadBytes)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    if (typeof attachmentId !== "string" || !/^(0|[1-9]\d{0,2})$/.test(attachmentId))
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    let parsed;
+    try {
+        parsed = await simpleParser(source, { skipHtmlToText: true, skipTextToHtml: true, skipImageLinks: true, maxHtmlLengthToParse: 128 * 1024 });
+    }
+    catch {
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+    if (parsed.attachments.length > account.attachmentLimits.count)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    const selected = parsed.attachments[Number(attachmentId)];
+    if (!selected)
+        throw new EmailError("EMAIL_MESSAGE_NOT_FOUND");
+    if (selected.size > account.attachmentLimits.perFileBytes || selected.content.length > account.attachmentLimits.perFileBytes || selected.content.length > account.attachmentLimits.totalBytes)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    const filename = safeAttachmentFilename(selected.filename);
+    const artifact = resolveArtifactTarget(context.workspaceDir, context.stageId, context.attempt, `email-${randomUUID()}.bin`).runRelativePath;
+    let target;
+    let created = false;
+    try {
+        validateAccount();
+        target = await containedPath(context, artifact, true);
+        validateAccount();
+        const handle = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        created = true;
+        try {
+            await handle.writeFile(selected.content);
+        }
+        finally {
+            await handle.close();
+        }
+        // Recheck directory containment after the write; never return an escaped result.
+        await containedPath(context, artifact);
+        validateAccount();
+        return { id: attachmentId, filename, contentType: selected.contentType.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200), size: selected.content.length, artifact };
+    }
+    catch (error) {
+        if (created && target)
+            await unlink(target).catch(() => { });
+        if (error instanceof EmailError)
+            throw error;
+        throw new EmailError("EMAIL_UNAUTHORIZED");
+    }
+}

package/dist/email/events.d.ts

@@ -0,0 +1,95 @@
+import { EmailAccounts, type EmailAccount } from "./accounts.js";
+import { type EmailErrorCode, type EmailMessageSummary, type EmailReceivedEvent } from "./port.js";
+/** Adapter-owned identity shared by live delivery and explicit historical retrieval. */
+export declare function receivedEventId(scope: string, accountId: string, folder: string, generation: string, uid: number): string;
+/** Internal provider seam. Each bounded metadata read isolates normalization faults by UID. */
+export type ReceiveOutcome = {
+    uid: number;
+} & ({
+    message: EmailMessageSummary;
+    fault?: never;
+} | {
+    fault: "EMAIL_INVALID_INPUT" | "EMAIL_RESOURCE_LIMIT";
+    message?: never;
+});
+export interface ReceiveMailbox {
+    snapshot(): Promise<{
+        generation: string;
+        high: number;
+    }>;
+    read(lower: number, upper: number): Promise<ReceiveOutcome[]>;
+    next(lower: number, upper: number): Promise<number | undefined>;
+    watch?(): void;
+    close(): void;
+}
+type Progress = {
+    generation: string;
+    uid: number;
+};
+type SafeError = {
+    code: EmailErrorCode;
+    retryable: boolean;
+};
+export type ReceivedRecord = {
+    event: EmailReceivedEvent;
+    state: "pending" | "accepted" | "faulted";
+    acceptedAt?: string;
+    error?: SafeError;
+};
+export type MessageFault = {
+    accountId: string;
+    folder: string;
+    generation: string;
+    uid: number;
+    code: EmailErrorCode;
+    detectedAt: string;
+};
+export type WatcherHealth = {
+    accountId: string;
+    folder: string;
+    state: "starting" | "watching" | "recovering" | "failed";
+    error?: SafeError;
+    storageError?: SafeError;
+    retryAt?: string;
+    lastAccepted?: Progress;
+    reset?: {
+        previousGeneration: string;
+        generation: string;
+        baseline: number;
+        detectedAt: string;
+    };
+    faults?: MessageFault[];
+};
+/** Internal fault-injection seam. Production uses real timers and atomic file writes. */
+type RecoveryDependencies = {
+    random?: () => number;
+    beforePersist?: () => void;
+    afterPersist?: () => void;
+};
+/** Single host writer. A pending event blocks folder progress until its consumer accepts it. */
+export declare class EmailEvents {
+    private readonly accounts;
+    private readonly open;
+    private readonly dependencies;
+    private readonly file;
+    private saved;
+    private durable;
+    private readonly watchers;
+    private emit?;
+    private unsubscribe?;
+    private changes;
+    constructor(accounts: EmailAccounts, open: (account: EmailAccount, folder: string, signal: () => void) => Promise<ReceiveMailbox>, dependencies?: RecoveryDependencies);
+    list(): ReceivedRecord[];
+    health(): WatcherHealth[];
+    start(emit: (event: EmailReceivedEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    private cancel;
+    private replace;
+    private signal;
+    private fail;
+    private reconcile;
+    private folderRecords;
+    private deliver;
+    private persist;
+}
+export {};

package/dist/email/events.js

@@ -0,0 +1,292 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { decodeRef } from "./messages.js";
+import { EmailError } from "./port.js";
+/** Adapter-owned identity shared by live delivery and explicit historical retrieval. */
+export function receivedEventId(scope, accountId, folder, generation, uid) {
+    return createHash("sha256").update(JSON.stringify([scope, accountId, folder, generation, uid])).digest("hex");
+}
+/** Single host writer. A pending event blocks folder progress until its consumer accepts it. */
+export class EmailEvents {
+    accounts;
+    open;
+    dependencies;
+    file;
+    saved;
+    durable;
+    watchers = new Map();
+    emit;
+    unsubscribe;
+    changes = Promise.resolve();
+    constructor(accounts, open, dependencies = {}) {
+        this.accounts = accounts;
+        this.open = open;
+        this.dependencies = dependencies;
+        this.file = path.join(accounts.scope, ".stageflow", "email-events.json");
+        this.saved = existsSync(this.file) ? JSON.parse(readFileSync(this.file, "utf8")) : { version: 1, progress: {}, records: [] };
+        if (this.saved.version !== 1 || !this.saved.progress || !Array.isArray(this.saved.records))
+            throw new EmailError("EMAIL_INVALID_INPUT");
+        this.durable = structuredClone(this.saved);
+    }
+    list() { return structuredClone(this.saved.records); }
+    health() {
+        return [...this.watchers.entries()].map(([key, watcher]) => structuredClone({
+            ...watcher.health,
+            ...(this.saved.lastAccepted?.[key] ? { lastAccepted: this.saved.lastAccepted[key] } : {}),
+            ...(this.saved.resets?.[key] ? { reset: this.saved.resets[key] } : {}),
+            ...(this.saved.messageFaults?.some(value => value.accountId === watcher.account.accountId && value.folder === watcher.folder)
+                ? { faults: this.saved.messageFaults.filter(value => value.accountId === watcher.account.accountId && value.folder === watcher.folder) } : {}),
+        }));
+    }
+    async start(emit) {
+        if (this.emit) {
+            await this.changes;
+            return;
+        }
+        this.emit = emit;
+        this.unsubscribe = this.accounts.onChange(accountId => {
+            for (const watcher of this.watchers.values())
+                if (watcher.account.accountId === accountId)
+                    this.cancel(watcher);
+            this.changes = this.changes.then(() => this.replace(accountId));
+        });
+        this.changes = Promise.all(this.accounts.list().map(account => this.replace(account.accountId))).then(() => { });
+        await this.changes;
+    }
+    async stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        const stopping = [...this.watchers.values()];
+        for (const watcher of stopping)
+            this.cancel(watcher);
+        this.emit = undefined;
+        await this.changes;
+        await Promise.all(stopping.map(value => value.work));
+        this.watchers.clear();
+    }
+    cancel(watcher) {
+        watcher.cancelled = true;
+        clearTimeout(watcher.timer);
+        clearTimeout(watcher.retry);
+        watcher.connection?.close();
+    }
+    async replace(accountId) {
+        const old = [...this.watchers.entries()].filter(([, watcher]) => watcher.account.accountId === accountId);
+        for (const [, watcher] of old)
+            this.cancel(watcher);
+        await Promise.all(old.map(([, watcher]) => watcher.work));
+        for (const [key] of old)
+            this.watchers.delete(key);
+        const account = this.accounts.list().find(value => value.accountId === accountId && value.enabled);
+        if (!account || !this.emit)
+            return;
+        await Promise.all([...new Set(account.folders)].map(async (folder) => {
+            const key = JSON.stringify([accountId, folder]);
+            const watcher = { account, folder, cancelled: false, dirty: false, scheduled: false, attempts: 0, work: Promise.resolve(), health: { accountId, folder, state: "starting" } };
+            this.watchers.set(key, watcher);
+            this.signal(key, watcher);
+            await watcher.work;
+        }));
+    }
+    signal(key, watcher) {
+        if (watcher.cancelled || watcher.retry || watcher.health.state === "failed")
+            return;
+        watcher.dirty = true;
+        if (watcher.scheduled)
+            return;
+        watcher.scheduled = true;
+        watcher.work = watcher.work.then(async () => {
+            try {
+                while (watcher.dirty && !watcher.cancelled && !watcher.retry && watcher.health.state !== "failed") {
+                    watcher.dirty = false;
+                    try {
+                        watcher.connection ??= await this.open(watcher.account, watcher.folder, () => this.signal(key, watcher));
+                        if (watcher.cancelled || !this.emit) {
+                            watcher.connection.close();
+                            break;
+                        }
+                        await this.reconcile(key, watcher);
+                        if (watcher.cancelled)
+                            break;
+                        watcher.connection.watch?.();
+                        watcher.attempts = 0;
+                        watcher.health = { accountId: watcher.account.accountId, folder: watcher.folder, state: "watching" };
+                        if (this.saved.faults?.[key]) {
+                            delete this.saved.faults[key];
+                            this.persist();
+                        }
+                        clearTimeout(watcher.timer);
+                        watcher.timer = setTimeout(() => this.signal(key, watcher), watcher.account.pollingIntervalMs);
+                        watcher.timer.unref();
+                    }
+                    catch (error) {
+                        this.fail(key, watcher, error);
+                    }
+                }
+            }
+            finally {
+                watcher.scheduled = false;
+            }
+        });
+    }
+    fail(key, watcher, error) {
+        if (watcher.cancelled)
+            return;
+        const fault = error instanceof EmailError ? error : new EmailError("EMAIL_CONNECTION_FAILED", true);
+        const retryable = fault.retryable && !["EMAIL_AUTH_FAILED", "EMAIL_TOKEN_EXPIRED"].includes(fault.code);
+        watcher.health = { accountId: watcher.account.accountId, folder: watcher.folder, state: retryable ? "recovering" : "failed", error: { code: fault.code, retryable } };
+        clearTimeout(watcher.timer);
+        if (retryable) {
+            const ceiling = Math.min(watcher.account.reconnectMaxDelayMs, 1000 * 2 ** Math.min(watcher.attempts++, 22));
+            const random = Math.max(0, Math.min(1, (this.dependencies.random ?? Math.random)()));
+            const delay = Math.floor(ceiling * (0.5 + random * 0.5));
+            watcher.health.retryAt = new Date(Date.now() + delay).toISOString();
+            watcher.retry = setTimeout(() => { watcher.retry = undefined; this.signal(key, watcher); }, delay);
+            watcher.retry.unref();
+        }
+        // Set the recovery state before close: synchronous close signals cannot queue a retry.
+        watcher.connection?.close();
+        watcher.connection = undefined;
+        this.saved.faults ??= {};
+        this.saved.faults[key] = structuredClone(watcher.health);
+        try {
+            this.persist();
+        }
+        catch {
+            watcher.health.storageError = { code: "EMAIL_STORAGE_FAILED", retryable: true };
+        }
+    }
+    async reconcile(key, watcher) {
+        const connection = watcher.connection;
+        const snapshot = await connection.snapshot();
+        if (!/^\d{1,20}$/.test(snapshot.generation) || !Number.isSafeInteger(snapshot.high) || snapshot.high < 0 || snapshot.high > 4294967295)
+            throw new EmailError("EMAIL_RESOURCE_LIMIT");
+        if (watcher.cancelled)
+            return;
+        const progress = this.saved.progress[key];
+        if (!progress || progress.generation !== snapshot.generation) {
+            if (progress) {
+                this.saved.resets ??= {};
+                this.saved.resets[key] = { previousGeneration: progress.generation, generation: snapshot.generation, baseline: snapshot.high, detectedAt: new Date().toISOString() };
+                for (const record of this.folderRecords(watcher)) {
+                    if (record.state !== "pending")
+                        continue;
+                    record.state = "faulted";
+                    record.error = { code: "EMAIL_STALE_REFERENCE", retryable: false };
+                    record.acceptedAt = new Date().toISOString();
+                }
+            }
+            this.saved.progress[key] = { generation: snapshot.generation, uid: snapshot.high };
+            this.persist();
+            return;
+        }
+        const pending = this.folderRecords(watcher).filter(value => value.state === "pending")
+            .sort((a, b) => decodeRef(watcher.account, a.event.message.ref).uid - decodeRef(watcher.account, b.event.message.ref).uid);
+        for (const record of pending) {
+            if (watcher.cancelled || !this.emit)
+                return;
+            const reference = decodeRef(watcher.account, record.event.message.ref);
+            if (reference.generation !== progress.generation) {
+                record.state = "faulted";
+                record.error = { code: "EMAIL_STALE_REFERENCE", retryable: false };
+                record.acceptedAt = new Date().toISOString();
+                this.persist();
+                continue;
+            }
+            await this.deliver(key, watcher, record, reference.uid);
+            progress.uid = Math.max(progress.uid, reference.uid);
+            this.persist();
+        }
+        while (progress.uid < snapshot.high) {
+            if (watcher.cancelled)
+                return;
+            const first = await connection.next(progress.uid + 1, snapshot.high);
+            if (watcher.cancelled)
+                return;
+            if (first === undefined) {
+                progress.uid = snapshot.high;
+                this.persist();
+                break;
+            }
+            if (!Number.isSafeInteger(first) || first <= progress.uid || first > snapshot.high)
+                throw new EmailError("EMAIL_RESOURCE_LIMIT");
+            const upper = Math.min(snapshot.high, first + 99);
+            const messages = await connection.read(first, upper);
+            if (messages.length > 100 || new Set(messages.map(value => value.uid)).size !== messages.length || messages.some(value => !Number.isSafeInteger(value.uid) || value.uid < first || value.uid > upper))
+                throw new EmailError("EMAIL_RESOURCE_LIMIT");
+            messages.sort((a, b) => a.uid - b.uid);
+            for (const outcome of messages) {
+                if (watcher.cancelled || !this.emit)
+                    return;
+                const { uid } = outcome;
+                if (outcome.fault) {
+                    this.saved.messageFaults ??= [];
+                    if (!this.saved.messageFaults.some(value => value.accountId === watcher.account.accountId && value.folder === watcher.folder && value.generation === snapshot.generation && value.uid === uid)) {
+                        this.saved.messageFaults.push({ accountId: watcher.account.accountId, folder: watcher.folder, generation: snapshot.generation, uid, code: outcome.fault, detectedAt: new Date().toISOString() });
+                        this.persist();
+                    }
+                }
+                else {
+                    const eventId = receivedEventId(this.accounts.scope, watcher.account.accountId, watcher.folder, snapshot.generation, uid);
+                    let record = this.saved.records.find(value => value.event.eventId === eventId);
+                    if (!record) {
+                        if (this.saved.records.filter(value => value.state === "pending").length >= 10000)
+                            throw new EmailError("EMAIL_RESOURCE_LIMIT");
+                        const message = outcome.message;
+                        record = { state: "pending", event: { type: "email.received", version: 1, eventId, accountId: watcher.account.accountId, message, receivedAt: message.receivedAt, detectedAt: new Date().toISOString() } };
+                        this.saved.records.push(record);
+                        this.persist();
+                    }
+                    if (record.state === "pending")
+                        await this.deliver(key, watcher, record, uid);
+                }
+                progress.uid = uid;
+                this.persist();
+            }
+            if (watcher.cancelled)
+                return;
+            progress.uid = upper;
+            this.persist();
+        }
+    }
+    folderRecords(watcher) {
+        return this.saved.records.filter(value => value.event.accountId === watcher.account.accountId && value.event.message.ref.mailbox === watcher.folder);
+    }
+    async deliver(key, watcher, record, uid) {
+        this.persist();
+        try {
+            await this.emit(structuredClone(record.event));
+        }
+        catch {
+            throw new EmailError("EMAIL_EVENT_ACCEPTANCE_FAILED", true);
+        }
+        record.state = "accepted";
+        record.acceptedAt = new Date().toISOString();
+        this.saved.lastAccepted ??= {};
+        this.saved.lastAccepted[key] = { generation: decodeRef(watcher.account, record.event.message.ref).generation, uid };
+        // Persist acceptance before checkpoint advancement. A restart uses the stable event ID.
+        this.saved.records = [...this.saved.records.filter(value => value !== record), record];
+        this.persist();
+    }
+    persist() {
+        const cutoff = Date.now() - 30 * 86400000;
+        const completed = this.saved.records.filter(value => value.state !== "pending" && Date.parse(value.acceptedAt) >= cutoff)
+            .sort((a, b) => Date.parse(a.acceptedAt) - Date.parse(b.acceptedAt)).slice(-1000);
+        this.saved.records = [...this.saved.records.filter(value => value.state === "pending"), ...completed];
+        this.saved.messageFaults = this.saved.messageFaults?.filter(value => Date.parse(value.detectedAt) >= cutoff).slice(-1000);
+        try {
+            this.dependencies.beforePersist?.();
+            mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+            const temporary = `${this.file}.${randomUUID()}.tmp`;
+            writeFileSync(temporary, JSON.stringify(this.saved), { mode: 0o600 });
+            renameSync(temporary, this.file);
+        }
+        catch {
+            this.saved = structuredClone(this.durable);
+            throw new EmailError("EMAIL_STORAGE_FAILED", true);
+        }
+        this.durable = structuredClone(this.saved);
+        this.dependencies.afterPersist?.();
+    }
+}

package/dist/email/host.d.ts

@@ -0,0 +1,15 @@
+import { EmailAccounts } from "./accounts.js";
+import { LocalEmailAdapter } from "./adapter.js";
+import { type EmailMailbox, type EmailArtifactContext } from "./port.js";
+import type { StageConfig } from "../types/stage.js";
+export declare function emailHostFor(cwd: string): {
+    accounts: EmailAccounts;
+    mailbox: LocalEmailAdapter;
+};
+export declare function releaseEmailHost(cwd: string): Promise<void>;
+export type StageEmail = Pick<EmailMailbox, "send" | "reply" | "search" | "getMessage" | "downloadAttachment">;
+export declare function validateStageEmailAccounts(accounts: EmailAccounts, stage: StageConfig): void;
+export declare function stageEmail(mailbox: EmailMailbox, stage: StageConfig, runId: string, context?: Omit<EmailArtifactContext, "stageId">): StageEmail;
+export declare function emailWorkerEnvironment(env: NodeJS.ProcessEnv, accounts: EmailAccounts): NodeJS.ProcessEnv;
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export declare function workerStageEmail(): StageEmail;