@ours.network/fleet 0.11.1 → 0.13.0

package/dist/loops/manager.d.ts

@@ -0,0 +1,48 @@
+import type { ResolvedRoleLoop } from './config.js';
+import { type ScheduledLoopsFile } from './state.js';
+import { RoleTurnArbiter } from '../session/arbiter.js';
+export interface LoopManagerDeps {
+    now(): number;
+    setTimer(callback: () => void, ms: number): unknown;
+    clearTimer(timer: unknown): void;
+    log(line: string): void;
+}
+export interface LoopActionResult {
+    state: 'started' | 'skipped_busy' | 'disabled' | 'unavailable';
+    runId?: string;
+}
+export interface ScheduledLoopManagerHandle {
+    start(): void;
+    stop(): Promise<void>;
+    status(): ScheduledLoopsFile;
+    runNow(name: string): Promise<LoopActionResult>;
+    disable(name: string): LoopActionResult;
+    enable(name: string): LoopActionResult;
+    reconcile(definitions: ResolvedRoleLoop[]): void;
+}
+export declare class ScheduledLoopManager implements ScheduledLoopManagerHandle {
+    private readonly role;
+    private readonly arbiter;
+    private readonly deps;
+    private readonly definitions;
+    private readonly store;
+    private timer?;
+    private stopping;
+    constructor(role: string, definitions: ResolvedRoleLoop[], stateDir: string, arbiter: RoleTurnArbiter, deps: LoopManagerDeps);
+    start(): void;
+    stop(): Promise<void>;
+    status(): ScheduledLoopsFile;
+    runNow(name: string): Promise<LoopActionResult>;
+    disable(name: string): LoopActionResult;
+    enable(name: string): LoopActionResult;
+    reconcile(definitions: ResolvedRoleLoop[]): void;
+    /** Public fake-clock seam; timer callbacks call the same transition. */
+    poll(): Promise<void>;
+    private attempt;
+    private finish;
+    private advance;
+    private skipMissed;
+    private skipRestartMisses;
+    private schedule;
+    private envelope;
+}

package/dist/loops/manager.js

@@ -0,0 +1,237 @@
+import { randomUUID } from 'node:crypto';
+import { ScheduledLoopStateStore, deterministicJitter, increment, } from './state.js';
+export class ScheduledLoopManager {
+    role;
+    arbiter;
+    deps;
+    definitions = new Map();
+    store;
+    timer;
+    stopping = false;
+    constructor(role, definitions, stateDir, arbiter, deps) {
+        this.role = role;
+        this.arbiter = arbiter;
+        this.deps = deps;
+        for (const definition of definitions)
+            this.definitions.set(definition.name, definition);
+        this.store = new ScheduledLoopStateStore(stateDir, role, definitions, deps.now(), deps.log);
+    }
+    start() {
+        if (!this.store.fresh)
+            this.skipRestartMisses();
+        this.schedule();
+    }
+    async stop() {
+        this.stopping = true;
+        this.arbiter.stopScheduledAdmission();
+        if (this.timer !== undefined)
+            this.deps.clearTimer(this.timer);
+        this.timer = undefined;
+        this.store.state.clock.lastWallMs = this.deps.now();
+        this.store.persist();
+    }
+    status() { return structuredClone(this.store.state); }
+    async runNow(name) {
+        const definition = this.definitions.get(name);
+        const state = this.store.state.loops[name];
+        if (!definition || !state || this.stopping)
+            return { state: 'unavailable' };
+        if (!definition.enabled || state.operatorDisabled)
+            return { state: 'disabled' };
+        return this.attempt(definition, state, this.deps.now());
+    }
+    disable(name) {
+        const state = this.store.state.loops[name];
+        if (!state)
+            return { state: 'unavailable' };
+        state.operatorDisabled = true;
+        state.lastOutcome = 'operator_disabled';
+        this.store.persist();
+        this.schedule();
+        return { state: 'disabled' };
+    }
+    enable(name) {
+        const definition = this.definitions.get(name);
+        const state = this.store.state.loops[name];
+        if (!definition || !state)
+            return { state: 'unavailable' };
+        if (!definition.enabled)
+            return { state: 'disabled' };
+        state.operatorDisabled = false;
+        state.lastOutcome = 'operator_enabled';
+        this.store.persist();
+        this.schedule();
+        return { state: 'started' };
+    }
+    reconcile(definitions) {
+        if (this.stopping)
+            return;
+        this.definitions.clear();
+        for (const definition of definitions)
+            this.definitions.set(definition.name, definition);
+        this.store.reconcile(definitions, this.deps.now());
+        this.schedule();
+    }
+    /** Public fake-clock seam; timer callbacks call the same transition. */
+    async poll() {
+        if (this.stopping)
+            return;
+        const now = this.deps.now();
+        if (now < this.store.state.clock.lastWallMs - 5 * 60_000) {
+            this.store.state.health = 'degraded';
+            this.store.state.anomaly = 'clock_regression';
+            this.store.state.clock.lastWallMs = now;
+            this.store.persist();
+            this.deps.log(`[${this.role}] scheduled loops paused after backward clock jump`);
+            this.schedule();
+            return;
+        }
+        const due = [...this.definitions.values()].filter(definition => {
+            const state = this.store.state.loops[definition.name];
+            return definition.enabled && !state.operatorDisabled && Date.parse(state.nextDueAt) <= now;
+        }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const definition of due) {
+            const state = this.store.state.loops[definition.name];
+            if (now >= Date.parse(state.nextDueAt) + definition.intervalMs) {
+                this.skipMissed(definition, state, now);
+                continue;
+            }
+            const scheduledAt = Date.parse(state.nextScheduledAt);
+            this.advance(definition, state);
+            this.store.persist();
+            await this.attempt(definition, state, scheduledAt);
+        }
+        this.store.state.clock.lastWallMs = now;
+        this.store.persist();
+        this.schedule();
+    }
+    async attempt(definition, state, scheduledAt) {
+        const runId = `sl_${randomUUID()}`;
+        const origin = { kind: 'scheduled-loop', loop: definition.name, runId };
+        const prompt = this.envelope(definition, runId, scheduledAt);
+        let claimed = false;
+        const result = await this.arbiter.tryScheduled(prompt, origin, () => {
+            claimed = true;
+            state.activeRunId = runId;
+            state.lastRunId = runId;
+            state.lastStartedAt = new Date(this.deps.now()).toISOString();
+            state.lastOutcome = 'running';
+            state.lastError = null;
+            state.counts.started = increment(state.counts.started);
+            this.store.persist();
+        });
+        if (result.state === 'skipped_busy') {
+            state.counts.skipped = increment(state.counts.skipped);
+            state.counts.skippedBusy = increment(state.counts.skippedBusy);
+            state.lastOutcome = 'skipped_busy';
+            state.lastFinishedAt = new Date(this.deps.now()).toISOString();
+            this.store.persist();
+            this.deps.log(`[${this.role}] loop ${definition.name} skipped_busy at ${new Date(scheduledAt).toISOString()}`);
+            return { state: 'skipped_busy' };
+        }
+        if (result.state === 'unavailable') {
+            state.activeRunId = null;
+            state.counts.failed = increment(state.counts.failed);
+            state.lastOutcome = claimed ? 'queue_failed' : 'unavailable';
+            state.lastFinishedAt = new Date(this.deps.now()).toISOString();
+            state.lastError = { kind: claimed ? 'queue_failed' : 'unavailable', at: state.lastFinishedAt };
+            this.store.persist();
+            this.deps.log(`[${this.role}] loop ${definition.name} ${state.lastOutcome} run=${runId.slice(0, 11)}`);
+            return { state: 'unavailable', runId };
+        }
+        this.deps.log(`[${this.role}] loop ${definition.name} started run=${runId.slice(0, 11)} scheduled=${new Date(scheduledAt).toISOString()}`);
+        void result.queued.completion.then(turn => this.finish(definition, state, runId, turn));
+        return { state: 'started', runId };
+    }
+    finish(definition, state, runId, result) {
+        if (state.activeRunId !== runId)
+            return;
+        state.activeRunId = null;
+        state.lastFinishedAt = new Date(this.deps.now()).toISOString();
+        state.lastCancellationSource = result.cancellationSource ?? null;
+        if (result.outcome === 'completed') {
+            state.counts.completed = increment(state.counts.completed);
+            state.lastOutcome = 'completed';
+        }
+        else if (result.outcome === 'cancelled') {
+            state.counts.cancelled = increment(state.counts.cancelled);
+            state.lastOutcome = `cancelled${result.cancellationSource ? `(${result.cancellationSource})` : ''}`;
+        }
+        else {
+            state.counts.failed = increment(state.counts.failed);
+            state.lastOutcome = result.outcome;
+            state.lastError = { kind: result.outcome, at: state.lastFinishedAt };
+        }
+        this.store.persist();
+        const duration = Date.parse(state.lastFinishedAt) - Date.parse(state.lastStartedAt);
+        this.deps.log(`[${this.role}] loop ${definition.name} finished run=${runId.slice(0, 11)} outcome=${state.lastOutcome} duration=${duration}ms`);
+    }
+    advance(definition, state) {
+        const current = Date.parse(state.nextScheduledAt);
+        state.lastScheduledAt = new Date(current).toISOString();
+        const next = current + definition.intervalMs;
+        state.nextScheduledAt = new Date(next).toISOString();
+        state.nextDueAt = new Date(next + deterministicJitter(this.role, definition.name, next, definition.jitterMs)).toISOString();
+    }
+    skipMissed(definition, state, now) {
+        let missed = 0;
+        while (Date.parse(state.nextDueAt) <= now) {
+            this.advance(definition, state);
+            missed++;
+        }
+        state.counts.skipped = increment(state.counts.skipped, missed);
+        state.counts.skippedMissed = increment(state.counts.skippedMissed, missed);
+        state.lastOutcome = 'skipped_missed';
+        state.lastFinishedAt = new Date(now).toISOString();
+        this.store.persist();
+        this.deps.log(`[${this.role}] loop ${definition.name} skipped_missed count=${missed}`);
+    }
+    skipRestartMisses() {
+        const now = this.deps.now();
+        for (const definition of this.definitions.values()) {
+            const state = this.store.state.loops[definition.name];
+            if (definition.enabled && !state.operatorDisabled && Date.parse(state.nextDueAt) <= now)
+                this.skipMissed(definition, state, now);
+        }
+    }
+    schedule() {
+        if (this.timer !== undefined)
+            this.deps.clearTimer(this.timer);
+        this.timer = undefined;
+        if (this.stopping)
+            return;
+        const due = [...this.definitions.values()].filter(definition => {
+            const state = this.store.state.loops[definition.name];
+            return definition.enabled && !state.operatorDisabled;
+        }).map(definition => Date.parse(this.store.state.loops[definition.name].nextDueAt));
+        if (!due.length)
+            return;
+        const delay = Math.max(0, Math.min(...due) - this.deps.now());
+        this.timer = this.deps.setTimer(() => {
+            void this.poll().catch(error => {
+                this.store.state.health = 'failed';
+                this.store.state.anomaly = 'manager_task_failed';
+                try {
+                    this.store.persist();
+                }
+                catch { }
+                this.deps.log(`[${this.role}] scheduled loop manager failed: ${error?.name ?? 'Error'}`);
+            });
+        }, Math.min(delay, 60_000));
+    }
+    envelope(definition, runId, scheduledAt) {
+        return [
+            '[fleet-loop]',
+            `loop: ${definition.name}`,
+            `run: ${runId}`,
+            `scheduled_at: ${new Date(scheduledAt).toISOString()}`,
+            'origin: local-trusted-config',
+            '',
+            'This is a scheduled internal maintenance turn, not an owner message and not ordinary ours mail.',
+            'Perform one bounded pass. Do not wait for the next tick. Do not report to an owner unless your',
+            'configured policy and an existing authenticated proactive-report route authorize a material report.',
+            '',
+            definition.prompt,
+        ].join('\n');
+    }
+}

package/dist/loops/state.d.ts

@@ -0,0 +1,54 @@
+import type { ResolvedRoleLoop } from './config.js';
+export interface LoopCounts {
+    started: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    skipped: number;
+    skippedBusy: number;
+    skippedMissed: number;
+}
+export interface LoopRuntimeState {
+    definitionHash: string;
+    promptHash: string;
+    enabled: boolean;
+    operatorDisabled: boolean;
+    nextScheduledAt: string;
+    nextDueAt: string;
+    lastScheduledAt: string | null;
+    lastStartedAt: string | null;
+    lastFinishedAt: string | null;
+    lastOutcome: string | null;
+    lastCancellationSource: string | null;
+    lastRunId: string | null;
+    activeRunId: string | null;
+    counts: LoopCounts;
+    lastError: {
+        kind: string;
+        at: string;
+    } | null;
+}
+export interface ScheduledLoopsFile {
+    version: 1;
+    role: string;
+    generation: string;
+    clock: {
+        lastWallMs: number;
+    };
+    health: 'healthy' | 'degraded' | 'failed';
+    anomaly: string | null;
+    loops: Record<string, LoopRuntimeState>;
+}
+export declare const increment: (value: number, amount?: number) => number;
+export declare function deterministicJitter(role: string, loop: string, nominalMs: number, maximumMs: number): number;
+export declare function scheduledLoopsPath(stateDir: string): string;
+export declare function readScheduledLoops(stateDir: string): ScheduledLoopsFile | undefined;
+export declare class ScheduledLoopStateStore {
+    private readonly log;
+    readonly path: string;
+    readonly fresh: boolean;
+    state: ScheduledLoopsFile;
+    constructor(stateDir: string, role: string, definitions: ResolvedRoleLoop[], now: number, log: (line: string) => void);
+    reconcile(definitions: ResolvedRoleLoop[], now: number, recoverActive?: boolean): void;
+    persist(): void;
+}

package/dist/loops/state.js

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, readFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+const zeroCounts = () => ({
+    started: 0, completed: 0, failed: 0, cancelled: 0,
+    skipped: 0, skippedBusy: 0, skippedMissed: 0,
+});
+export const increment = (value, amount = 1) => Math.min(Number.MAX_SAFE_INTEGER, value + Math.max(0, amount));
+export function deterministicJitter(role, loop, nominalMs, maximumMs) {
+    if (maximumMs <= 0)
+        return 0;
+    const digest = createHash('sha256').update(`${role}\0${loop}\0${nominalMs}`).digest();
+    const value = digest.readUIntBE(0, 6);
+    return value % (maximumMs + 1);
+}
+export function scheduledLoopsPath(stateDir) {
+    return join(stateDir, '.scheduled-loops.json');
+}
+export function readScheduledLoops(stateDir) {
+    try {
+        const path = scheduledLoopsPath(stateDir);
+        if (!safeStateFile(path))
+            return undefined;
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        return validFile(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class ScheduledLoopStateStore {
+    log;
+    path;
+    fresh;
+    state;
+    constructor(stateDir, role, definitions, now, log) {
+        this.log = log;
+        this.path = scheduledLoopsPath(stateDir);
+        let restored;
+        let corrupt = false;
+        if (existsSync(this.path)) {
+            try {
+                if (!safeStateFile(this.path))
+                    throw new Error('insecure scheduled-loop state');
+                const parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+                if (!validFile(parsed) || parsed.role !== role)
+                    throw new Error('invalid scheduled-loop state');
+                restored = parsed;
+                chmodSync(this.path, 0o600);
+            }
+            catch {
+                corrupt = true;
+                try {
+                    renameSync(this.path, `${this.path}.corrupt-${now}`);
+                }
+                catch { }
+            }
+        }
+        this.fresh = !restored;
+        this.state = restored ?? {
+            version: 1, role, generation: '', clock: { lastWallMs: now },
+            health: corrupt ? 'degraded' : 'healthy', anomaly: corrupt ? 'corrupt_state_recovered' : null,
+            loops: {},
+        };
+        this.reconcile(definitions, now, Boolean(restored));
+        if (corrupt)
+            this.log(`[${role}] scheduled loops recovered corrupt state; delayed cadence reinitialized`);
+    }
+    reconcile(definitions, now, recoverActive = false) {
+        const next = {};
+        for (const definition of definitions) {
+            const old = this.state.loops[definition.name];
+            if (old?.definitionHash === definition.definitionHash) {
+                next[definition.name] = {
+                    ...old, promptHash: definition.promptHash, enabled: definition.enabled,
+                };
+            }
+            else {
+                const nominal = now + definition.initialDelayMs;
+                next[definition.name] = {
+                    ...(old ?? {}),
+                    definitionHash: definition.definitionHash, promptHash: definition.promptHash,
+                    enabled: definition.enabled,
+                    nextScheduledAt: new Date(nominal).toISOString(),
+                    nextDueAt: new Date(nominal + deterministicJitter(definition.role, definition.name, nominal, definition.jitterMs)).toISOString(),
+                    lastScheduledAt: old?.lastScheduledAt ?? null,
+                    lastStartedAt: old?.lastStartedAt ?? null,
+                    lastFinishedAt: old?.lastFinishedAt ?? null,
+                    lastOutcome: old?.lastOutcome ?? null,
+                    lastCancellationSource: old?.lastCancellationSource ?? null,
+                    lastRunId: old?.lastRunId ?? null,
+                    activeRunId: old?.activeRunId ?? null,
+                    counts: old?.counts ?? zeroCounts(), lastError: old?.lastError ?? null,
+                    operatorDisabled: old?.operatorDisabled ?? false,
+                };
+            }
+            if (recoverActive && next[definition.name].activeRunId) {
+                const item = next[definition.name];
+                item.counts.failed = increment(item.counts.failed);
+                item.lastOutcome = 'abandoned_restart';
+                item.lastFinishedAt = new Date(now).toISOString();
+                item.lastError = { kind: 'abandoned_restart', at: new Date(now).toISOString() };
+                item.activeRunId = null;
+                this.state.health = 'degraded';
+                this.state.anomaly = 'abandoned_restart';
+            }
+        }
+        this.state.loops = next;
+        this.state.generation = createHash('sha256').update(JSON.stringify(definitions.map(item => ({
+            name: item.name, definitionHash: item.definitionHash, promptHash: item.promptHash,
+        })))).digest('hex');
+        this.state.clock.lastWallMs = now;
+        this.persist();
+    }
+    persist() {
+        replaceFileAtomically(this.path, JSON.stringify(this.state, null, 2) + '\n', 0o600);
+        chmodSync(this.path, 0o600);
+    }
+}
+function validFile(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const file = value;
+    if (file.version !== 1 || typeof file.role !== 'string' || !file.clock
+        || !Number.isSafeInteger(file.clock.lastWallMs) || !file.loops || typeof file.loops !== 'object')
+        return false;
+    return (file.health === 'healthy' || file.health === 'degraded' || file.health === 'failed')
+        && (file.anomaly === null || typeof file.anomaly === 'string')
+        && Object.values(file.loops).every(item => item && typeof item === 'object'
+            && typeof item.definitionHash === 'string' && typeof item.promptHash === 'string'
+            && typeof item.nextScheduledAt === 'string' && typeof item.nextDueAt === 'string'
+            && Number.isFinite(Date.parse(item.nextScheduledAt)) && Number.isFinite(Date.parse(item.nextDueAt))
+            && typeof item.enabled === 'boolean' && typeof item.operatorDisabled === 'boolean'
+            && item.counts && Object.values(item.counts).every(count => Number.isSafeInteger(count) && count >= 0)
+            && (item.activeRunId === null || typeof item.activeRunId === 'string'));
+}
+function safeStateFile(path) {
+    try {
+        const stat = lstatSync(path);
+        const uid = process.getuid?.();
+        return stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o777) === 0o600
+            && (uid === undefined || stat.uid === uid);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/monitor.js

@@ -115,6 +115,30 @@ export function filterEvents(events, wakeSources) {
     const set = new Set(wakeSources);
     return events.filter(e => e.event !== undefined && set.has(e.event));
 }
+/**
+ * A reconnect or the short coalescing poll may overlap the preceding daemon
+ * page. Collapse only events with a stable notification ID; ID-less events are
+ * retained because two otherwise-identical introductions may be distinct.
+ * The key deliberately contains only fields already allowed in the body-free
+ * notification contract.
+ */
+function notificationKey(event) {
+    const id = event.event === 'file_received' ? event.file_id : event.msg_id;
+    if (id === undefined)
+        return undefined;
+    return `${event.event ?? ''}\u0000${event.from ?? ''}\u0000${String(id)}`;
+}
+function appendUniqueEvents(target, additions) {
+    const seen = new Set(target.map(notificationKey).filter((key) => key !== undefined));
+    for (const event of additions) {
+        const key = notificationKey(event);
+        if (key !== undefined && seen.has(key))
+            continue;
+        target.push(event);
+        if (key !== undefined)
+            seen.add(key);
+    }
+}
 const uniq = (xs) => [...new Set(xs)];
 const plural = (n, one, many = one + 's') => (n === 1 ? one : many);
 /**
@@ -401,7 +425,7 @@ export class Monitor {
             }
             this.advance(body.cursor, false);
             const batch = filterEvents(body.events ?? [], this.cfg.wake_sources);
-            pending.push(...batch);
+            appendUniqueEvents(pending, batch);
             if (pending.length === 0) {
                 this.persistCursor();
                 continue;
@@ -445,7 +469,7 @@ export class Monitor {
         try {
             const more = await this.doFetch(String(this.cursor ?? 0), COALESCE_HOLD_MS);
             this.advance(more.cursor, false);
-            batch.push(...filterEvents(more.events ?? [], this.cfg.wake_sources));
+            appendUniqueEvents(batch, filterEvents(more.events ?? [], this.cfg.wake_sources));
         }
         catch { /* no stragglers / abort — deliver what we have */ }
     }

package/dist/owner-channel/attachments.d.ts

@@ -0,0 +1,74 @@
+import type { OwnerAttachmentConfig } from '../config.js';
+export interface AttachmentReplyRef {
+    wire_id: string;
+    sentence?: number;
+}
+export interface IncomingAttachment {
+    fileId: number;
+    wireId: string;
+    senderId: string;
+    senderName: string;
+    filename: string;
+    mime: string;
+    size: number;
+    status: string;
+    date: string;
+    kind: 'file' | 'voice_message';
+    replyTo: AttachmentReplyRef | null;
+}
+export interface VoiceTranscription {
+    configured: boolean;
+    attempted: boolean;
+    status: 'succeeded' | 'failed' | 'unavailable';
+    provider: string | null;
+    text: string | null;
+    errorCategory: string | null;
+    audioPath: string;
+    fileWireId: string;
+}
+export interface RetrievedAttachment extends IncomingAttachment {
+    path: string;
+    sha256: string;
+    transcription?: VoiceTranscription;
+}
+export interface AdmittedAttachment {
+    wireId: string;
+    filename: string;
+    path: string;
+    declaredMime: string;
+    detectedMime: string;
+    size: number;
+    sha256: string;
+    kind: 'file' | 'voice_message';
+    transcription?: Omit<VoiceTranscription, 'audioPath'>;
+}
+export declare function parseIncomingAttachments(raw: unknown): IncomingAttachment[];
+export declare function parseRetrievedAttachments(raw: unknown, expected: IncomingAttachment[], recovered?: boolean): RetrievedAttachment[];
+export declare function validateAttachmentSelection(files: IncomingAttachment[], config: OwnerAttachmentConfig): string | undefined;
+export declare function prepareAttachmentDirectory(root: string, requestId: string): Promise<string>;
+export declare function admitAttachments(files: RetrievedAttachment[], dir: string, config: OwnerAttachmentConfig): Promise<AdmittedAttachment[]>;
+export declare function recoveredAttachment(file: IncomingAttachment, path: string): Promise<RetrievedAttachment>;
+export declare function removeRequestDirectory(path: string): Promise<void>;
+export declare function cleanupAttachmentRoot(root: string, now: number, retentionMs: number, limit?: number): Promise<number>;
+export interface PendingAttachmentRequest {
+    id: string;
+    contact: string;
+    originWireId: string;
+    fileWireIds: string[];
+    createdAt: number;
+}
+export declare class AttachmentRecoveryState {
+    private readonly path;
+    private pending;
+    private corrupt;
+    constructor(path: string);
+    integrity(): boolean;
+    list(): PendingAttachmentRequest[];
+    add(item: PendingAttachmentRequest): void;
+    remove(id: string): void;
+    cleanup(now: number, retentionMs: number): number;
+    private assertHealthy;
+    private persist;
+}
+export declare function safeField(value: unknown, max: number): string;
+export declare function sanitizeFilename(value: string): string;